From d8808e64d9bc5c4b1c43547b4b34787ab77e7cc7 Mon Sep 17 00:00:00 2001 From: study-tool Date: Sun, 1 Nov 2026 21:17:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=E5=A2=9E=E5=8A=A0=E6=94=B6?= =?UTF-8?q?=E5=B0=BE=E6=8F=90=E4=BA=A4=E8=A7=84=E5=88=99=EF=BC=8C=E5=8F=91?= =?UTF-8?q?=E7=89=88=E6=B5=81=E7=A8=8B=E6=94=B9=E4=B8=BA=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E9=A9=B1=E5=8A=A8=E4=B8=80=E6=9D=A1=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象：发版流程里「手动提交 + 手动打 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 真实发版；没跑测试、没构建（本次无代码改动） --- AGENTS.md | 21 ++++++++++++++------- docs/agent_workflow.md | 24 ++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9aad55..c92c83b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,14 @@ - 命令失败、文件读不到、解析失败 → 结论是「未知」，不是「空」或「没问题」。 - 没跑的验证写 `Not tried: <原因>`。 +### 收尾（Commit） + +- **任务完成后自动提交**：一个任务一个 commit（一个 commit 一个目标），不为附带产物（如 `uv.lock`）单开提交，它们跟着产生它的那次任务走。 +- **重大变更开始前，工作区必须干净**：重大变更指改依赖、改表结构、改 `AGENTS.md` / `docs/architecture.md` 这类规则文档、发版本；有残留改动先提交或撤销，再动手。 +- **发版本是独立动作**：只在用户明确确认「发版」后才触发，见「发版本流程」。 +- 提交范围：只提交本次任务的文件（`git add <具体路径>`）。提交前 `git status` 必须只剩本次任务的文件；出现别人的或无关的改动 → 停下问，不顺手提交。 +- 提交信息：标题 `<区域>: <用户可见的变化>`；body 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。 + ## 多 Agent 协作 - 看板表头统一为 `| 路径 | 任务 | Agent | 状态 |`，历史行 `Agent` 列留空。 @@ -68,13 +76,12 @@ ## 发版本流程 -- 发版本时，先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录，并保留空的 `Unreleased` 标题。 -- **只在发版提交时提升版本号**：`metadata.yaml`、`pyproject.toml`、`uv.lock` 三处 `version` 一起改（bumpversion 已配置这三处）；普通提交不动版本号。 -- 发版提交前跑一次 `uv lock`，确认 `uv.lock` 里的依赖与 `study-tool` 版本跟 `pyproject.toml` 一致；有变化就一起提交。 -- 提交范围：只提交本次任务的文件（`git add <具体路径>`）。提交前 `git status` 必须只剩本次任务的文件；出现别人的或无关的改动 → 停下问，不顺手提交。 -- 提交完成后，给当前提交打最新版本号对应的 tag（如 `v0.0.8`）。打之前 `git tag -l` 查重、`git rev-parse HEAD` 确认，不覆盖已有 tag。 -- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需 `pnpm build` 并把 `static/` 一起提交。 -- 完成一个能独立回滚的改动就提交一次（一个 commit 一个目标）。提交信息：标题 `<区域>: <用户可见的变化>`；body 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。 +- 发版本只在用户明确确认后触发；触发前工作区必须干净（见「收尾」）。 +- 先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录，保留空的 `Unreleased` 标题，并作为一个普通提交先提交。 +- 发版前跑一次 `uv lock` 自检：它若改动了 `uv.lock`，说明某个任务漏提交了锁文件——补进那次任务，不为它单开提交。 +- 工作区干净后执行 `uv tool run bump-my-version bump patch`：它一次完成「改 `metadata.yaml` / `pyproject.toml` / `uv.lock` 三处 `version` + 自动提交 + 自动打 tag」，**不要再手动 commit 或 `git tag`**。普通提交不动版本号。 +- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；打 tag 前工具会失败于同名 tag，不覆盖已有 tag。 +- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需 `pnpm build` 并把 `static/` 一起提交（在发版前的普通提交里完成）。 ## 项目契约 diff --git a/docs/agent_workflow.md b/docs/agent_workflow.md index 21a521b..cd82be0 100644 --- a/docs/agent_workflow.md +++ b/docs/agent_workflow.md @@ -41,6 +41,14 @@ - 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 ### 修改已存在文件：一次清单、一次同意 @@ -92,6 +100,22 @@ - 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）」 + ## 已否决（不要再提议） | 规则 | 原因 |