study-tool
d8808e64d9
现象：发版流程里「手动提交 + 手动打 tag」与 bump-my-version 的 commit = true / tag = true 冲突，真用工具会撞同名 tag；另外没有写清「何时提交、何时必须先提交」，导致为 1 行 uv.lock 单开了提交（4784ac0）。 根因：发版步骤是按手动流程写的，后来才配了自动提交 + 打 tag 的工具，两边没有对齐；提交时机 只散落在发版一节里。 边界： - 新增「收尾（Commit）」：任务完成后自动提交，一个任务一个 commit；附带产物（如 uv.lock） 跟着产生它的任务走；重大变更（改依赖 / 表结构 / 规则文档 / 发版）开始前工作区必须干净； 发版本只在用户确认后触发 - 「发版本流程」改为：整理 CHANGELOG 并普通提交 → uv lock 自检 → 工作区干净后 uv tool run bump-my-version bump patch 一次完成改三处版本 + 提交 + 打 tag；不再手动 commit / tag - docs/agent_workflow.md 记入三条：发版配置要 dry-run、发版只留一条线、附带产物不单开提交 - 不改代码、不改版本号、不打 tag 运行了什么：git status 自查（只提交这 2 个文档文件）；提交时 pre-commit 跑 ruff / web typecheck / commitizen 没跑什么：没跑 bump-my-version 真实发版；没跑测试、没构建（本次无代码改动）
133 lines
7.4 KiB
Markdown
133 lines
7.4 KiB
Markdown
# Agent 工作流 · 经验账本
|
||
|
||
> 规则在 `AGENTS.md`；这里只放「还没被证实」或「刚被证实一次」的经验。
|
||
> 写入前先全文搜重：有同义条目就改旧的，不新增重复条目。
|
||
> Agent 可以写本文件，但**不能自己改 `AGENTS.md`**——只能提议 + 附证据。
|
||
|
||
## 怎么用
|
||
|
||
1. 遇到问题，先搜本文件有没有同一条。
|
||
2. 没有 → 在「观察中」加一条，`Seen：1×`。
|
||
3. 又遇到 → 同一条 `Seen +1`，把新证据追加进去（不要另开一条）。
|
||
4. `Seen ≥3` 且用户同意 → 升级进 `AGENTS.md`，本文件那条标 `已升级`；判断为「不该加」的 → 移到「已否决」并写清原因。
|
||
|
||
## 条目格式
|
||
|
||
```markdown
|
||
### <一句话规则，写成能执行的动作>
|
||
|
||
- 为什么：<不这么做的具体代价>
|
||
- 证据：
|
||
- `<版本 / 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 代码块以钩子结果为准，别手改对抗）
|
||
|
||
### 发版配置写完要真跑一次 dry-run
|
||
|
||
- 为什么：没验证过的发版配置会在发版当天才暴露问题，那时最没有余量排查。
|
||
- 证据：
|
||
- `ecadae5` 之前的 `pyproject.toml`：`bump-my-version` 默认 `regex = false`，且仓库文件是 CRLF，原 `search` 真跑报 `Did not find '(?m)^version = "0.0.8"$' in file: 'pyproject.toml'`，这条发版命令从未成功过。
|
||
- Seen：1×
|
||
- 状态：观察中（改发版配置后跑 `bump-my-version bump patch --dry-run --allow-dirty -vv`，确认三处都会被改）
|
||
|
||
## 已升级 → 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.md` 93 行，其中「日志规范」+「代码结构 / 平台插件」约 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.8` CHANGELOG：文档里的旧目录名 `pugins/` 是另一次同类漂移，靠一次性全量替换才修掉。
|
||
- Seen：2×
|
||
- 状态：已升级 → AGENTS.md「文档规范」（`docs/todo.md` 已删除；其中 2 条仍未修的代码问题已迁入 `docs/progress/todo.md`）
|
||
|
||
### 发版流程只留一条线，别让手动步骤和工具自动步骤并存
|
||
|
||
- 为什么：工具已经自动提交 + 打 tag，文档还写「提交完成后手动打 tag」，照做就会撞同名 tag 失败。
|
||
- 证据：
|
||
- `ecadae5`：`pyproject.toml` 里 `commit = true` / `tag = true`，而当时 `AGENTS.md` 发版流程仍有「提交完成后，给当前提交打 tag」一条。
|
||
- Seen：1×
|
||
- 状态：已升级 → AGENTS.md「发版本流程」（改为 bump-my-version 一次完成改版本 + 提交 + 打 tag）
|
||
|
||
### 附带产物跟着任务走，不单开提交
|
||
|
||
- 为什么：为 1 行 `uv.lock` 单开提交会让历史里充满噪音，也让「一个任务一个 commit」失去意义。
|
||
- 证据：
|
||
- `4784ac0`：`chore: uv.lock 的 study-tool 版本同步到 0.0.8`，仅 1 行改动，是 v0.0.8 发版的遗留；用户指出「完成一个任务才需要提交」。
|
||
- Seen：1×
|
||
- 状态：已升级 → AGENTS.md「收尾（Commit）」
|
||
|
||
## 已否决（不要再提议）
|
||
|
||
| 规则 | 原因 |
|
||
| --- | --- |
|
||
| 每个任务都强制建 git worktree | 单人顺序开发时是纯摩擦：新 worktree 没有 `.env` / `.venv` / `node_modules`，每次要重装；已在 AGENTS.md 限定为「并行开发时」。 |
|
||
| 六条验收硬拦发布（全量测试 / 多平台 vet / 真用） | 与「用户自己构建验证」冲突，本项目没有对应的测试体系。 |
|
||
| 每个失败都在同一 commit 开 issue | 用 `docs/progress/todo.md` 等价实现，个人项目不引入 issue 流程。 |
|
||
| 只合并 reviewed head（`--match-head-commit`） | 没有外部 PR 流程，不适用。 |
|
||
|
||
## 维护
|
||
|
||
- 「观察中」+「已升级」合计超过 15 条就该清理：合并同义条目、删掉已否决的、把过期的观察降级或删掉。
|
||
- 每条都必须能落到「证据」；写不出证据的，先别写进来。
|
||
- 不写会议纪要、不写「注意质量」这类无法执行的表述。
|