study-tool
ecadae581e
现象：v0.0.8 发版后 uv.lock 里 study-tool 的 version 仍停在 0.0.1，与 metadata.yaml / pyproject.toml 的 0.0.8 不一致，需要单独补一次提交。 根因：bumpversion 只配置了 metadata.yaml 和 pyproject.toml 两个文件。另外原有的两处正则 search 有两个坑：一是没开 regex = true（bump-my-version 默认按字面量搜索），二是仓库文件是 CRLF，`^...$` 锚点匹配不到行尾——真跑会直接报「Did not find」而不是改版本。 边界：只改发版配置和流程说明；不动业务代码、不改当前版本号、不打 tag。 运行了什么：`uv tool run bump-my-version bump patch --dry-run --allow-dirty -vv`，确认 metadata.yaml / pyproject.toml / uv.lock 三处都会被改、且 dry-run 没写盘（文件仍是 0.0.8） 没跑什么：没真跑 bump（会改版本号并自动提交、打 tag，留给你发版时执行）；没跑测试、没构建
81 lines
6.1 KiB
Markdown
81 lines
6.1 KiB
Markdown
# AGENTS.md
|
||
|
||
本文档用于约束本项目中的 AI / 自动化开发行为。
|
||
|
||
**优先级：用户当前消息 > 本文件 > 其他文档。** 与本文件冲突时以用户消息为准，并在收尾时问一句要不要同步改本文件。
|
||
|
||
## 基本原则
|
||
|
||
- 先读现有代码，再动手修改，优先沿用项目已有结构和写法。
|
||
- 写代码保持最少行数，能简单实现就不要引入复杂抽象。
|
||
- 标准格式、协议、解析、压缩、加密、日期等通用能力优先使用成熟稳定的库，不要手写底层实现，除非用户明确要求或项目已有实现必须沿用。
|
||
- 不要为了“兼容更多场景”写大量分支，只实现当前明确需要的功能。
|
||
- 项目尚未上线，不需要兼容旧数据；表结构或字段调整时直接按新设计修改，不写旧字段兼容、数据迁移兜底或删除旧表的清理逻辑，除非用户明确要求。
|
||
- 不要改无关文件，不要顺手重构；顺手发现的 bug 不修，记进 `docs/progress/todo.md` 并注明位置。
|
||
- 如果工作区已有用户改动，不要回滚，不要覆盖；只在必要范围内追加修改。
|
||
|
||
### 动文件之前（Plan-first）
|
||
|
||
- 修改**已存在文件**前，先给一次改动清单：路径 / 改什么 / 为什么 / 影响面；同意后本次任务内连续执行，不逐文件问。
|
||
- 新建文件、新建目录不用逐次问，但要列进清单。
|
||
- 删除、覆盖、格式化、`git reset --hard`、`git checkout .`、`git push -f`、删分支 / 删 worktree，必须单独列出、单独同意。
|
||
- 用户当条消息里点名的改动，视为已同意。
|
||
|
||
### 验证口径
|
||
|
||
- **产物生成必须做**：前端改动 → `cd web && pnpm build`，`static/` 一起提交，不直接改 `static/` 里的产物。
|
||
- **质量验证不做**：不跑测试、不跑全量 lint / typecheck，由用户执行。例外：用户明确要求、发版、或改到核心逻辑（认证 / 计费 / 写库 / 定时任务 / 并发 / 对外协议）。
|
||
- 提交时 pre-commit 会跑 `ruff-check` / `ruff-format` / `web typecheck`，失败就修；这不算“检查语法”。
|
||
- 结论必须带依据：命令、`文件:行`、报错原文；没核实就写「未核实」。
|
||
- 命令失败、文件读不到、解析失败 → 结论是「未知」，不是「空」或「没问题」。
|
||
- 没跑的验证写 `Not tried: <原因>`。
|
||
|
||
## 多 Agent 协作
|
||
|
||
- 看板表头统一为 `| 路径 | 任务 | Agent | 状态 |`，历史行 `Agent` 列留空。
|
||
- 开工前在 `docs/agent_board.md` 追加一行，状态写 `进行中 (MM-DD HH:mm)`（如 `进行中 (11-01 19:40)`）。同一路径已有别人的 `进行中` → 停下问，不硬改。
|
||
- 完成后只改自己那行：状态改 `已完成,待实测`，**保留行**（它是完成记录）。不动别人 Agent 的行。
|
||
- 超过 24 小时仍是 `进行中` 的行（按状态里的时间算）视为过期，可以接管，但要注明接管人。
|
||
- 只有一个 Agent 在顺序开发时，认领行可以省，但改前必须先看有没有人动过同一文件。
|
||
- **并行开发（≥2 个任务同时改代码）** 时，每个任务用独立 worktree：
|
||
|
||
```bash
|
||
git worktree add ../study-tool-<任务名> -b <任务名>
|
||
cp .env ../study-tool-<任务名>/
|
||
uv sync
|
||
pnpm --dir web install
|
||
```
|
||
|
||
合并回 master 后 `git worktree remove ../study-tool-<任务名>`。单人顺序开发不强制建 worktree。
|
||
- 禁止 `git add -A` / `git add .`：必须按具体文件名暂存，防止误提交其他 Agent 未完成的改动。
|
||
|
||
## 反复提醒沉淀
|
||
|
||
- 同一个坑出现 ≥2 次（或同一个注意事项被用户纠正 2 次以上）才写成规则；只出现 1 次的先记 `docs/agent_workflow.md` 的「观察中」。
|
||
- `docs/agent_workflow.md` 每条格式：规则 / 为什么 / 证据（提交 sha、报错原文、`文件:行`）/ Seen N×。
|
||
- Seen ≥3 且用户同意，才升级进本文件；写入前先全文搜重，有同义条目就改旧的，不新增重复条目。
|
||
- 补充时写成明确、可执行的规则，避免只写模糊描述。
|
||
- Agent 只提议并附证据，**不自己改本文件**。
|
||
|
||
## 文档规范
|
||
|
||
- README 保持简洁，只放项目介绍、核心功能、快速开始和文档入口。
|
||
- 后续待办写到 `docs/progress/todo.md`，分三段：待做 / 已知偏差 / 未验证。
|
||
- 已实现但还需要用户测试确认的事项写到 `OPTIMIZATION.md`。
|
||
- 每次任务完成前，根据实际变更检查并更新 `OPTIMIZATION.md` 与 `docs/progress/todo.md`；没有变化也要确认无需修改。
|
||
- 文档里的命令、路径、字段名必须与代码一致；引用代码写 `路径 + 符号名`，不写行号。
|
||
- 文档不要写过期日期；除非用户明确要求记录具体时间。
|
||
|
||
## 发版本流程
|
||
|
||
- 发版本时，先把 `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 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。
|
||
|
||
## 项目契约
|
||
|
||
- 日志约定、目录分层、平台插件契约统一维护在 `docs/architecture.md`，改动结构时同步更新；本文件不再重复这些内容。 |