From 48e72ab1e7d24769a0f39ecc513930fba8706e0a Mon Sep 17 00:00:00 2001 From: study-tool Date: Sun, 1 Nov 2026 21:22:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=8F=91=E7=89=88=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E6=8B=86=E6=88=90=E9=80=9A=E7=94=A8=E4=B8=8E=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E4=B8=A4=E5=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象：AGENTS.md「发版本流程」里写死了本项目的文件名和命令（metadata.yaml、uv tool run bump-my-version、uv.lock），换项目没法直接复用；手写那一行还出现了 `runm` 和 `etadata.yaml` 两处笔误。 根因：通用规则和项目实现细节混在同一节，规则文件承担了本该属于架构文档的内容。 边界： - AGENTS.md「发版本流程」改成通用表述：确认后触发、CHANGELOG 整理、锁文件自检、发版工具一次 完成改版本 + 提交 + 打 tag、tag 查重、发版不构建；不再出现具体文件名和命令 - docs/architecture.md 新增「发版」一节，放本项目的三处版本文件、bump-my-version 命令、 CRLF + regex 的配置坑、改配置后先 dry-run - docs/agent_workflow.md「项目契约和 Agent 行为规则分开」补上这次的证据，Seen 升到 2× - 不改代码、不改版本号、不打 tag 运行了什么：git status 自查（只提交这 3 个文档文件）；提交时 pre-commit 跑 ruff / web typecheck / commitizen 没跑什么：没跑 bump-my-version 真实发版；没跑测试、没构建（本次无代码改动） --- AGENTS.md | 10 ++++++---- docs/agent_workflow.md | 3 ++- docs/architecture.md | 12 ++++++++++++ 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c92c83b..419df6a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,12 +76,14 @@ ## 发版本流程 +本节是通用流程；本项目的版本文件、发版命令和配置细节见 `docs/architecture.md`「发版」。 + - 发版本只在用户明确确认后触发；触发前工作区必须干净（见「收尾」）。 - 先把 `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/` 一起提交（在发版前的普通提交里完成）。 +- 发版前先做依赖锁文件自检：锁文件若有变化，说明某个任务漏提交了它——补进那次任务，不为它单开提交。 +- 版本号只在发版时提升，普通提交不动版本号；用项目配置好的发版工具一次完成「改版本号 + 提交 + 打 tag」，**不要再手动 commit 或打 tag**。 +- 打 tag 前确认没有同名 tag，不覆盖已有 tag；发完确认 tag 存在、HEAD 正确。 +- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；产物（如前端构建）在发版前的普通提交里完成。 ## 项目契约 diff --git a/docs/agent_workflow.md b/docs/agent_workflow.md index cd82be0..a3d1291 100644 --- a/docs/agent_workflow.md +++ b/docs/agent_workflow.md @@ -88,7 +88,8 @@ - 为什么：行为规则和项目契约混在一个文件里，改契约时没人会想到 review 规则文件，两边都不好维护。 - 证据： - `v0.0.8 (aa48145)`：`AGENTS.md` 93 行，其中「日志规范」+「代码结构 / 平台插件」约 4KB 是项目契约，而 `docs/architecture.md` 已在维护同一套分层与插件契约。 -- Seen：1× + - `d8808e6`：`AGENTS.md`「发版本流程」里写死了本项目的文件名和命令（`metadata.yaml`、`uv tool run bump-my-version …`），用户指出这些该放进 `docs/architecture.md`，`AGENTS.md` 只留通用流程；手写命令还出现过 `runm` / `etadata.yaml` 这类笔误。 +- Seen：2× - 状态：已升级 → AGENTS.md「项目契约」（两节已并入 `docs/architecture.md`，AGENTS.md 降到 79 行） ### 一个文件只留一份权威账本 diff --git a/docs/architecture.md b/docs/architecture.md index fe14cb1..8c404af 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -255,3 +255,15 @@ NOTIFY = notify.register(DaidaiPush()) # 插件 main.py 末尾注册 - key 约定：账号相关用账号 id（页面卡片「课程日志」直接显示）；全局 / 系统事件用 `"system"`（右上角「系统日志」弹窗显示）。 - 时间戳、级别、格式都由 `runtime.log` 统一拼（`时间 [级别] 内容`），模块里不要自己加时间前缀。 - 前端读日志统一用 `/api/log?key=&since=`（实时）+ `/api/log/history?key=&tail=`（历史兜底），不要另起一套日志接口。 + +## 发版 + +通用流程见 `AGENTS.md`「发版本流程」；本项目的具体做法： + +- 版本号三处：`metadata.yaml`、`pyproject.toml`、`uv.lock`（其中 `study-tool` 那一段），由 `pyproject.toml` 的 `[tool.bumpversion]` 统一改，不要手改。 +- 发版前先 `uv lock` 自检；它若改动了 `uv.lock`，说明某个任务漏提交了锁文件，补进那次任务。 +- 命令：`uv tool run bump-my-version bump patch`。工作区需干净；它一次完成改三处版本、提交 `chore(release): vX.Y.Z`、打 tag `vX.Y.Z`，不要再手动 commit 或 `git tag`。 +- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；同名 tag 已存在时工具会失败，不会覆盖。 +- 前端有改动时，`pnpm build` 并提交 `static/` 要在发版前的普通提交里完成，发版步骤本身不构建。 +- 改了 `[tool.bumpversion]` 配置后，先跑 `uv tool run bump-my-version bump patch --dry-run --allow-dirty -vv`，确认三个文件都会被改。 +- 仓库文件是 CRLF，且 bump-my-version 默认按字面量搜索：用正则的条目必须写 `regex = true`，并且不要用 `$` 锚定行尾（`uv.lock` 那条用 `\r?\n` 兼容换行）。