# AGENTS

这个文件是本仓库的人机协作硬约束入口。

如果你要在这个仓库里做分析、改代码、补文档或排查问题，默认先读下面 4 份文档：

1. [项目约束总表](./docs/constraints/README.md)
2. [项目编码约束](./docs/constraints/coding-rules.md)
3. [项目架构](./docs/overview/architecture.md)
4. [项目业务总览](./docs/business/README.md)

## 新增硬约束

如果本轮采用任务看板 / `worktree` 协作，项目只约束结果，不约束协作工具的内部实现：

- 协作流程必须保持单一任务真值，不能并存第二套长期运行时状态
- 文件变更任务必须使用独立 `worktree` 或等效隔离执行位
- 主工作区或目标文件一旦存在冲突，必须显式暴露，不能静默覆盖
- 协作工具的状态文件路径、命令名、锁机制和生命周期由工具自行实现，项目不感知这些细节

只要改动涉及业务逻辑、共享契约、映射、筛选、状态推进或跨层编排，这次改动就必须完成逻辑准确性校验。

- 默认命令：`npm run verify:logic`
- 默认要求：覆盖所有适用的契约校验、核心逻辑校验和关键链路校验
- 默认立场：没有完成逻辑准确性校验的代码设计，不算完成

## 先记住这 10 条

1. 这个项目是“本地优先的桌面研究工作台”，不是普通 Web 后台。
2. 页面层不越级，只通过 `src/renderer/src/api/client.ts` 消费能力。
3. 页面层不能直接碰 SQLite，也不能直接访问第三方数据源。
4. bridge 层只做协议适配和命名转换，不承载业务逻辑。
5. 长任务统一由 Rust 后台执行，前端只负责发起、展示状态和消费结果。
6. SQLite 是本地状态中心；关键业务结果优先落库，再展示。
7. 内部运维能力默认不对普通用户开放，开发者模式和普通模式要保持统一权限口径。
8. 如果启用任务看板协作，项目只关心唯一真值、独立 `worktree` 和冲突显式暴露，不关心协作工具的内部状态实现。
9. 涉及业务逻辑、共享契约、映射、筛选、状态推进或跨层编排的改动，必须完成逻辑准确性校验。
10. 禁止运行时兜底兼容；强制单一契约；默认 fail fast。

## 改代码时的默认边界

- 改页面时，不要在 `views/*` 或 `components/*` 里直接写 `invoke()`。
- 做跨表、跨流程、跨数据源编排时，优先放到 Rust 服务层，而不是 bridge 或页面层。
- 遇到字段漂移、历史字段、命名不一致时，优先修 producer、contract、service boundary，不要在 consumer 侧双读兼容。
- 新增 SQLite 表时，必须使用固定分类前缀命名；原始 provider 表用 `api_`，业务事实与工作流表用 `biz_`，系统 / 任务 / 制品表沿用正式分类前缀，禁止再新增无分类前缀表名。
- 不要用空字符串、`-`、默认值掩盖结构性错误。
- 涉及业务逻辑、共享契约、映射、筛选、状态推进或跨层编排的改动，提交前必须完成逻辑准确性校验。
- 提交前默认运行 `npm run check:constraints`，不要绕过仓库里的结构化约束检查。
- 提交前默认运行 `npm run verify:logic`，不要用“只是重构”跳过逻辑验证。

## 脏工作区与 Worktree 约束

- 开工前默认先执行一次 `git status --short`，确认当前工作区是否已有未提交改动。
- 如果采用临时 `worktree` 协作，优先把实际改动放进独立 `worktree` 执行。
- 如果当前工作区已有未提交改动，且本次任务目标文件当前是干净的，优先切临时 `worktree` 隔离开发，不要把新任务直接叠到现有脏工作区。
- 临时 `worktree` 必须从当前 `HEAD` 新建临时分支进入，例如 `git worktree add -b codex/<topic> ../<repo>-<topic> HEAD`。
- 在临时 `worktree` 完成改动、验证和文档留存后，再把变更回灌主工作区；回灌失败时直接暴露冲突并停止，不允许静默覆盖。
- 回灌完成后，必须删除临时 `worktree`；如果创建了临时分支，也一起删除，不保留悬挂工作树。
- 如果本次任务目标文件在主工作区里已经有未提交改动，不要继续叠加修改，也不要假装能自动合并；先显式说明冲突事实，再决定是否继续。
- 禁止为了切 `worktree` 自动执行 `git stash`、`git reset --hard`、`git checkout --` 这类会改写用户现场的命令。

## 机器可读约束

- 机器可读约束单一来源：`config/constraints.json`
- 逻辑验证统一入口：`npm run verify:logic`
- 逻辑验证机器规则入口：`config/constraints.json > verification`
- 本地检查脚本：`scripts/check_constraints.mjs`
- 文档结构检查脚本：`scripts/check_docs_structure.mjs`
- CI 会执行同一条逻辑校验命令：`npm run verify:logic`
- `npm run check:constraints` 现在同时检查结构化约束和文档目录 / frontmatter 规则
- SQLite 建表命名也受 `config/constraints.json` 约束；新增表必须命中固定分类前缀，legacy 表名只能作为已登记迁移债务临时存在。
- 当前页面层没有登记中的直达 Tauri / desktop bridge 例外；如需新增，必须先把原因和退出条件写进 `config/constraints.json`
- 当前 `composables/*`、`stores/*` 和 `App.vue` 也禁止直接碰 desktop bridge 或 `@tauri-apps/*`，统一通过 `src/renderer/src/api/client.ts` 收口

## 改文档时的默认边界

- `docs/` 只允许“根目录 + 一级分类目录”的结构，不再继续向下嵌套正式文档目录。
- 每篇正式文档头部都必须自带 frontmatter，至少写清 `title`、`doc_type`、`domain`、`keywords`、`summary`、`when_to_read`、`read_next`。
- 每篇正式文档在标题下都要有简短导语，先说明“这篇文档讲什么、什么时候用、读完再看什么”。
- 长期稳定业务上下文、任务口径和业务沉淀写到 `docs/business/`
- 系统结构、分层和运行时边界写到 `docs/overview/`
- 项目级硬约束和编码规则写到 `docs/constraints/`
- 功能专项设计、实现现状和专项迁移方案写到 `docs/features/`
- 运行说明、功能测试、排障和手工验收写到 `docs/operations/`
- 初始化包、导入导出说明写到 `docs/bootstrap/`
- 模板只写到 `docs/templates/`

## 任务路由建议

- 想快速理解全局边界：先看 [项目约束总表](./docs/constraints/README.md)
- 想确认最硬的编码规则：先看 [项目编码约束](./docs/constraints/coding-rules.md)
- 想理解运行时结构和模块职责：先看 [项目架构](./docs/overview/architecture.md)
- 想理解业务闭环和研究流程：先看 [项目业务总览](./docs/business/README.md)
