diff --git a/AGENTS.md b/AGENTS.md index 337d115..f019e85 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,8 @@ - 正式代码统一放入 `app/` 包;迁移完成后复用 `app/cdp.py`,遵守架构第七节的选择器、就绪判断、上传/拖拽方式,不另起一套 CDP 交互。 - 只做当前任务范围内的事;T-504 已接入的多账号并行、dry-run、运行日志属于当前范围,其他 V2 / V3 功能只记录不实现。 - CDP 选择器 / 流程 / 配置 schema 变化,必须同步更新 `docs/04-architecture.md` 与相关任务。 -- 改完后更新任务状态、追加 `progress.md`、覆盖 `docs/current-state.md`。 +- **新任务一任务一文件写进 `docs/tasks/T-<编号>.md`,不再手改 `docs/06-tasks.md`**(已冻结为 T-000~T-549 历史归档);命名/frontmatter/领取规则见 `docs/tasks/README.md`。为避免多 agent 并发抢改同一文件、ID 撞号。 +- 改完后更新对应任务文件状态、追加 `progress.md`、覆盖 `docs/current-state.md`。 ## 安全红线 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index a4bfa3d..196315b 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -1,6 +1,8 @@ # 任务看板(Tasks) > 把目标拆成小步、可独立交付的任务,让 AI 一步一步开发,避免一次生成整个项目。 +> +> **⚠️ 本文件已冻结为历史归档(T-000~T-549)。新任务不再加到这里**——为避免多 agent 并发抢改同一文件、ID 撞号,**新任务一律一任务一文件放 [`tasks/`](tasks/)**(`docs/tasks/T-<编号>.md`),约定见 [`tasks/README.md`](tasks/README.md)。只有订正历史任务状态时才改本文件。 ## 使用规则 diff --git a/docs/README.md b/docs/README.md index f85b196..7aee07f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,7 +17,8 @@ - [技术栈](03-tech-stack.md):语言、运行平台、CDP 方案、GUI 选型和运行命令。 - [架构设计](04-architecture.md):模块职责、账号与配置目录数据模型、CDP 已验证事实和开发顺序。 - [编码规则](05-coding-rules.md):写代码前必须遵守的硬约束。 -- [任务看板](06-tasks.md):按依赖拆分的小任务,agent 每轮只做一个。 +- [任务文件](tasks/README.md):**新任务入口**——一任务一文件 `docs/tasks/T-<编号>.md`,避免多 agent 并发抢改同一文件、ID 撞号。 +- [任务看板(历史归档)](06-tasks.md):T-000~T-549 历史任务,已冻结,不再新增。 - [模块 / CLI 合约](api.md):本地模块接口、Chrome 启动参数、账号配置 schema。 - [界面与流程结构](routes.md):GUI 窗口、操作流程、按钮职责(无前端路由,用 GUI 流程替代)。 - [当前实现状态](current-state.md):当前代码现实、可运行命令、下一步可做任务。 diff --git a/docs/tasks/README.md b/docs/tasks/README.md new file mode 100644 index 0000000..7534de5 --- /dev/null +++ b/docs/tasks/README.md @@ -0,0 +1,55 @@ +# 任务文件(一任务一文件) + +> 目的:多个 agent 并发时,避免所有人抢改同一个 `../06-tasks.md`——单大文件 + 多写者会导致「读到旧版本」的编辑冲突和 ID 撞号(本项目已实际发生)。 +> 约定:**新任务一律一个文件放这里 `docs/tasks/T-<编号>.md`;不再往 `../06-tasks.md` 加新任务**(它已冻结为历史归档,保留 T-000~T-549)。 + +## 为什么这样 + +一任务一文件后:改哪个任务只动哪个文件,agent 之间互不抢占;ID 撞号在**新建文件时当场暴露**(文件已存在就换号),不像往大表塞行、撞了也不知道。 + +## 文件命名与 ID(方案 1:连续编号) + +- 文件名:`docs/tasks/T-<编号>.md`,如 `docs/tasks/T-550.md`;同族细分用后缀 `T-550a.md`。 +- 分配下一个 ID:取「`../06-tasks.md` 归档 + `docs/tasks/` 现有文件」里最大的 `T-###`,`+1`。 +- **建文件即防撞**:若 `T-550.md` 已存在(别的 agent 先建了),直接改用下一个号(`T-551`),**不要覆盖别人的文件**。 +- 模板 `_template.md` 以下划线开头,不是真实任务、不参与编号扫描。 + +## 每个任务文件的结构(frontmatter + 正文) + +```markdown +--- +id: T-550 +title: 一句话任务名 +phase: 7 # 所属阶段,沿用 06-tasks.md 的 Phase 编号 +deps: [T-546, T-538] # 依赖的任务 ID(跨归档/新结构都用完整 ID 引用) +status: TODO # TODO | DOING | DONE | BLOCKED +created: 2026-07-08 +--- + +## 问题 / 背景 +... + +## 方案 +... + +## 验收要点 +... + +## 边界(不改什么) +... +``` + +## 状态与领取流程(同 `../06-tasks.md`「使用规则」) + +- 状态:`TODO` · `DOING`(同一时间最多 1 个)· `DONE` · `BLOCKED`。 +- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务,取编号最靠前的;做完自测、改 `status: DONE`、追加 `../../progress.md`、覆盖 `../current-state.md`。 +- **只改自己那个任务文件**;不要编辑别人正在做的任务文件。 + +## 看板视图 + +- 现阶段:`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。 +- (可选,后续)加一个脚本把所有任务文件汇总成一张看板表,agent 不手改看板。 + +## 历史归档 + +- `docs/06-tasks.md` = T-000~T-549 的历史归档,**冻结、不再新增**;只有历史任务需要订正状态时才动它,新任务不进去。 diff --git a/docs/tasks/_template.md b/docs/tasks/_template.md new file mode 100644 index 0000000..afb60bd --- /dev/null +++ b/docs/tasks/_template.md @@ -0,0 +1,24 @@ +--- +id: T-XXX +title: 一句话任务名 +phase: 7 +deps: [] +status: TODO +created: 2026-07-08 +--- + +## 问题 / 背景 + +(现象、根因、为什么要做) + +## 方案 + +(怎么改,落到"改哪个文件、改成什么") + +## 验收要点 + +(可验证的完成标准;涉及测试写清跑哪个) + +## 边界(不改什么) + +(明确不碰的模块/流程:DB schema、CDP/Shopee、Excel 等)