study-tool
106818cfc2
现象：AGENTS.md 里 5 处规则互相打架——逐次询问 vs 认领/提交/升版本；不构建 vs 前端必须 build；全部提交 vs 禁 add -A；每次提交 bump 版本号，而实际 24 次提交版本仍是 0.0.8。 docs/agent_board.md 没有 Agent 列，认领规则无法落地；docs/agent_workflow.md 是 0 字节； docs/todo.md 与 docs/progress/todo.md 双账本漂移，旧文件还写 platforms/gdgxk.py。 根因：规则按「想防的事」逐条追加，没有回头消解冲突；项目契约和 Agent 行为混在同一个入口文件里。 边界： - AGENTS.md 只留行为规则；日志 / 目录 / 插件契约指向 docs/architecture.md（两节内容已并入，未丢失） - 版本号改为只在发版提交时 bump，普通提交不动 - 看板改四列表头，状态带时间戳「进行中 (MM-DD HH:mm)」，超 24h 可接管 - 删除 docs/todo.md；其中 2 条仍未修的代码问题已迁入 docs/progress/todo.md，待办按 待做 / 已知偏差 / 未验证 重排 - 不改代码、不改版本号、不打 tag 运行了什么：git status 自查（只提交这 6 个文档文件，uv.lock 是原有改动未提交）；提交时 pre-commit 跑 ruff / web typecheck / commitizen 没跑什么：没跑测试、没构建、没跑 pnpm build（本次无代码改动）
5.9 KiB
5.9 KiB
Agent 工作流 · 经验账本
规则在
AGENTS.md；这里只放「还没被证实」或「刚被证实一次」的经验。 写入前先全文搜重：有同义条目就改旧的，不新增重复条目。 Agent 可以写本文件，但不能自己改AGENTS.md——只能提议 + 附证据。
怎么用
- 遇到问题，先搜本文件有没有同一条。
- 没有 → 在「观察中」加一条，
Seen：1×。 - 又遇到 → 同一条
Seen +1，把新证据追加进去（不要另开一条）。 Seen ≥3且用户同意 → 升级进AGENTS.md，本文件那条标已升级；判断为「不该加」的 → 移到「已否决」并写清原因。
条目格式
### <一句话规则，写成能执行的动作>
- 为什么：<不这么做的具体代价>
- 证据：
- `<版本 / commit sha>` <现象，带文件:行 或报错原文>
- Seen：N×
- 状态：观察中 | 已升级 → AGENTS.md「<章节>」 | 已否决（原因）
观察中（Seen 1–2）
文档里不写具体的版本号 / 行号示例，它们会过期
- 为什么：示例一旦过期，Agent 会照着过期的值做事，且没人会主动去改示例。
- 证据：
v0.0.8 (aa48145)：旧AGENTS.md写「打 tag，例如v0.0.5」，而当时最新 tag 已是v0.0.8。
- Seen：1×
- 状态：观察中（新版本改成了
v0.0.8，同样会过期；下次改成<最新 tag>或直接删示例）
ruff-format 会重排文档里的 python 代码块
- 为什么：以为只改
.py，结果提交时它把文档里 ```python 代码块的格式也改了，pre-commit 直接拦下这次提交；不知道这点会反复「改了又变」。 - 证据：
06d3206提交时：docs/architecture.md的Channel示例被ruff-format加了空行，pre-commit 报files were modified by this hook并中止提交。
- Seen：1×
- 状态：观察中（文档里的 python 代码块以钩子结果为准，别手改对抗）
已升级 → AGENTS.md
修改已存在文件：一次清单、一次同意
- 为什么：逐文件询问会让「认领 → 改代码 → 升版本 → 提交」每一步都卡住，长任务直接跑不动；但完全不问又会动到用户的文件。
- 证据：
v0.0.8 (aa48145)：旧规则「任何文件编辑…必须先询问」与同文件的「认领看板」「提交代码」「升版本号」三条互相冲突，且没写清「一次同意管几次」。
- Seen：1×
- 状态：已升级 → AGENTS.md「动文件之前（Plan-first）」
不构建 ≠ 不验证
- 为什么：把「不跑构建」写成「不用检查」，会让 Agent 把没验证的结论当成已验证的结论报上来。
- 证据：
v0.0.8 (aa48145)：同文件一边写「不需要检查语法、不需要执行构建」，一边写「改完前端必须cd web && pnpm build」；.pre-commit-config.yaml又会在提交时跑ruff-check/ruff-format/web typecheck。
- Seen：1×
- 状态：已升级 → AGENTS.md「验证口径」
版本号只在发版提交时提升
- 为什么：每次提交都 bump 时，bump 同时改
metadata.yaml+pyproject.toml，并行分支必然冲突；而且这条从来没被执行过。 - 证据：
v0.0.8 (aa48145)：旧规则「每次提交必须提升版本号」，实际 24 次提交、版本仍是 0.0.8，tag 只有v0.0.1/v0.0.8。
- Seen：1×
- 状态：已升级 → AGENTS.md「发版本流程」
看板按 Agent 认领，完成后改状态、保留行
- 为什么：规则说「按 Agent 认领」，表里却没有 Agent 列，认领动作无从落地；删行又会把完成记录一起删掉。
- 证据：
v0.0.8 (aa48145)：docs/agent_board.md表头只有「路径 / 任务 / 状态」，12 行状态全是「已完成,待实测」，没有 Agent 列。
- Seen：1×
- 状态：已升级 → AGENTS.md「多 Agent 协作」
项目契约和 Agent 行为规则分开
- 为什么：行为规则和项目契约混在一个文件里，改契约时没人会想到 review 规则文件，两边都不好维护。
- 证据：
v0.0.8 (aa48145)：AGENTS.md93 行，其中「日志规范」+「代码结构 / 平台插件」约 4KB 是项目契约，而docs/architecture.md已在维护同一套分层与插件契约。
- Seen：1×
- 状态：已升级 → AGENTS.md「项目契约」（两节已并入
docs/architecture.md，AGENTS.md 降到 79 行）
一个文件只留一份权威账本
- 为什么：两份待办并存时，Agent 会读旧的、写新的，两边慢慢分叉。
- 证据：
v0.0.8 (aa48145)：docs/todo.md仍写../src/study_tool/platforms/gdgxk.py，而平台早已迁到src/study_tool/plugins/gdgxk/。v0.0.8CHANGELOG：文档里的旧目录名pugins/是另一次同类漂移，靠一次性全量替换才修掉。
- Seen：2×
- 状态：已升级 → AGENTS.md「文档规范」（
docs/todo.md已删除；其中 2 条仍未修的代码问题已迁入docs/progress/todo.md）
已否决（不要再提议）
| 规则 | 原因 |
|---|---|
| 每个任务都强制建 git worktree | 单人顺序开发时是纯摩擦：新 worktree 没有 .env / .venv / node_modules，每次要重装；已在 AGENTS.md 限定为「并行开发时」。 |
| 六条验收硬拦发布（全量测试 / 多平台 vet / 真用） | 与「用户自己构建验证」冲突，本项目没有对应的测试体系。 |
| 每个失败都在同一 commit 开 issue | 用 docs/progress/todo.md 等价实现，个人项目不引入 issue 流程。 |
只合并 reviewed head（--match-head-commit） |
没有外部 PR 流程，不适用。 |
维护
- 「观察中」+「已升级」合计超过 15 条就该清理：合并同义条目、删掉已否决的、把过期的观察降级或删掉。
- 每条都必须能落到「证据」；写不出证据的，先别写进来。
- 不写会议纪要、不写「注意质量」这类无法执行的表述。