From 90dc09d13d94c5dd6c91ed10f5738ff0644ee7d7 Mon Sep 17 00:00:00 2001 From: ila Date: Thu, 16 Jul 2026 20:42:32 +0800 Subject: [PATCH] Use single-agent workflow --- AGENTS.md | 13 +++++++------ docs/06-tasks.md | 4 ++-- docs/README.md | 2 +- docs/current-state.md | 4 ++-- docs/tasks/README.md | 33 ++++++++++++--------------------- 5 files changed, 24 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dc027eb..7d7035d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,13 +45,14 @@ - 密钥、许可证私钥、真实注册码、真实下载 URL 一律不入库;示例只用占位符。 - 提交信息使用英文祈使句,任务相关提交带上 `T-<编号>`。 -## 多 Agent 协作 +## Agent 执行模式 -- 任务依赖仍是硬门槛:T-301 → T-302 → T-303 这类依赖链不得把后置任务提前并发实现。 -- 同一个任务默认只有**一个写入 Agent**拥有任务文件 `write_paths`;其他 Agent 可并行进行只读测试设计、安全审查或代码审查,但不得修改文件、暂存或提交。 -- 主 Agent / coordinator 负责领取、分配角色、汇总只读意见、执行最终验证与创建该任务唯一提交;审查 Agent 只通过消息返回发现和建议。 -- 只有先把大任务拆成独立 `T-<编号><后缀>.md`、冻结共享接口并提交,且各子任务 `write_paths` 无目录前缀重叠时,才允许多个写入 Agent 并行编码。 -- 多 Agent 角色、写入所有权、只读边界和汇总结果必须记录到当前任务的 `## 协作约束` / `## 执行记录`,不能只存在于对话。 +- 后续任务默认且持续使用**单 Agent 串行执行**;当前 Agent 独立完成任务落文档、实现、审查、自测、状态更新和 Git 提交。 +- 不启动子 Agent,不把测试设计、安全审查或代码审查委派给其他 Agent;需要复核时由当前 Agent 分阶段自行检查。 +- 项目同一时间只保留一个活跃任务。T-301 → T-302 → T-303 这类依赖链严格按顺序完成和提交,不得提前并发实现后置任务。 +- `write_paths` 继续作为单任务修改边界,用于限制任务范围和提交内容,不再用于安排并行写入。 +- T-301 的多 Agent 执行记录保留为历史事实,不代表后续默认方式。 +- 只有用户以后再次明确要求多 Agent,才允许先修改并提交本节及相关任务文档,再启动子 Agent;对话中的临时建议不能覆盖本规则。 ## 验证 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 7220f05..f22117e 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -6,7 +6,7 @@ ## 使用规则 1. **开工先落文件**:从下方「建议拆分清单」把下一个任务按 [`tasks/README.md`](tasks/README.md) 落成 `docs/tasks/T-<编号>.md`(沿用建议编号),把验收要点展开成可执行、可观察的步骤,再开始实现。 -2. **每个 agent 一次只做一个任务**:领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md);`DONE` 需要可运行证据,多 agent 只并行写路径互不重叠的任务。 +2. **单 Agent 串行执行**:同一时间只做一个任务,领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md);前一任务 `DONE`、验证并提交后才开始下一任务。 3. **不跳步**:依赖未完成的任务不能开工。 4. **本文只在规划变化时修改**:调整阶段划分、里程碑、增删建议任务或 Backlog 条目时才动本文;单个任务开工或完成**不**修改本文。 5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。 @@ -43,7 +43,7 @@ ### Phase 3 · 下载与安装 -Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保持串行。每个任务内部默认采用“一个写入 Agent + 测试设计/安全审查只读 Agents”;只有先落成子任务、提交共享接口且写路径无重叠时才并行编码,完整规则见 [`tasks/README.md`](tasks/README.md) 与仓库 `AGENTS.md`。 +Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保持串行。T-302 起继续由单 Agent 完成规格、实现、测试、安全检查和提交,不启动子 Agent;完整规则见 [`tasks/README.md`](tasks/README.md) 与仓库 `AGENTS.md`。 | ID | 任务 | 依赖 | 验收要点 | | --- | --- | --- | --- | diff --git a/docs/README.md b/docs/README.md index 9c1f407..6541c56 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端, - [架构设计](04-architecture.md):分层结构、monorepo 目录、数据模型、安全流程和开发顺序。 - [编码规则](05-coding-rules.md):AI 写代码前必须遵守的硬约束(分层、工具链、安全纪律)。 - [任务路线图](06-tasks.md):Phase 0-6 阶段划分、里程碑和待办池;只读,不跟踪单任务状态。 -- [任务文件(默认)](tasks/README.md):一任务一文件 `docs/tasks/T-<编号>.md`,单/多 agent 通用,每个 agent 同时只做一个。 +- [任务文件(默认)](tasks/README.md):一任务一文件 `docs/tasks/T-<编号>.md`,当前按单 Agent 串行执行。 - [已有项目接入清单](adoption-checklist.md):把本模板补进已有代码库时的迁移步骤(本项目从零开始,备查)。 - [协议合约](api.md):Catalog 清单、标准软件包协议 v1、许可证、事件合约、CLI 参数。 - [页面与视图结构](routes.md):Gio 视图划分、组件归属、交互硬约束。 diff --git a/docs/current-state.md b/docs/current-state.md index 044c92b..140e59d 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -21,7 +21,7 @@ - 标准启动路径:`./init.sh` / `./init.ps1`(同步依赖、执行完整 Phase 0 闸门、打印双目标构建命令) - 标准验证路径:`bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1` - 版本管理:git 已初始化,main 分支,远端 origin 为 Gitea `opc/soft_quay`;harness 文档已提交 -- 当前 blocker:无;下一个任务是 T-302 安装流程整合,必须先正式落成并提交任务文件,再启动一个写入 Agent + 测试/安全只读 Agents +- 当前 blocker:无;下一个任务是 T-302 安装流程整合,必须先正式落成并提交任务文件,再由单 Agent 串行完成 ## 当前目录要点 @@ -42,7 +42,7 @@ - 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`。 - 正在进行:无。 -- 下一个可领取任务:先按路线图正式落成 `T-302 安装流程整合` 并提交,然后才能领取和启动多 Agent。 +- 下一个可领取任务:先按路线图正式落成 `T-302 安装流程整合` 并提交,然后由单 Agent 领取和执行。 ## 当前可运行内容 diff --git a/docs/tasks/README.md b/docs/tasks/README.md index 55f338b..57142bc 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -1,13 +1,13 @@ # 任务文件（一任务一文件 · 默认任务管理方式） -> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`，单 agent 与多 agent 并发通用。 +> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`。当前项目使用单 Agent 串行执行。 > 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md)；路线图只读，不跟踪单任务状态。 ## 为什么默认一任务一文件 - **单 agent**：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 `git log -p` 一个文件即可回放全程。 -- **多 agent 并发**：单个大看板 + 多写者 = **编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。 -- **零迁移**：项目从单 agent 长到多 agent，无需切换任何约定。 +- **低上下文成本**：一任务一文件让单 Agent 只读取当前任务规格和执行记录,减少跨文件同步与重复检索。 +- **保留扩展性**：如果未来由用户明确重新启用多 Agent,现有任务文件仍可作为写路径和依赖边界;重新启用前必须先更新并提交协作规则。 ## 文件命名与 ID @@ -46,28 +46,19 @@ write_paths: # 允许修改的仓库相对路径 ## 领取 / 完成流程 -- 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。 -- 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。 -- `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。 +- 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。项目同一时间只保留一个活跃任务。 +- 单 Agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。 +- `write_paths` 必须在动手前写清,用于约束本任务允许修改和提交的路径。 - 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。 - **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。 -- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。 +- **只改当前任务文件**；不要顺带修改其他任务的状态或执行记录。 -### 同一任务的多 Agent 模式 +### 当前单 Agent 模式 -当任务本身不能安全拆成互不依赖的写路径时,使用“单写入者 + 多只读审查者”: - -1. coordinator 先落成任务文件并提交,明确唯一写入 Agent、只读测试 Agent、只读安全/架构 Agent。 -2. 写入 Agent 独占任务 `write_paths`;只读 Agent 不调用文件编辑、`git add`、`git commit` 或会改变仓库状态的命令。 -3. 只读 Agent 返回可复现的测试矩阵、风险和审查意见;coordinator 决定是否采纳并由唯一写入者或 coordinator 修改。 -4. 所有意见合并后由 coordinator 跑任务完整闸门、更新执行记录并创建唯一任务提交。 - -若要让多个 Agent 并行写代码,必须先: - -- 拆成带后缀的独立任务文件(如 `T-301a.md` / `T-301b.md`)。 -- 先完成并提交共享接口/协议冻结任务。 -- 确保依赖均 DONE,且 `write_paths` 互不重叠、没有目录前缀包含关系。 -- 每个子任务独立状态、验证证据和 Git 提交;最后另设串行集成任务。 +1. 当前 Agent 负责从任务落文档到最终提交的完整生命周期,不启动或委派子 Agent。 +2. 测试设计、安全检查、代码审查和提交前复核由当前 Agent 分阶段执行,结果统一写入任务执行记录。 +3. 前一个任务达到 `DONE`、完整验证通过并提交后,才正式落成或领取下一个依赖任务。 +4. 若用户以后明确恢复多 Agent,必须先修改并提交 `AGENTS.md`、本文和当前任务的协作约束;在该文档提交之前不得启动子 Agent。 未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 `TODO` 改为 `DOING` 即可。启用 Gitea 时，必须先按 [`../gitea-collaboration.md`](../gitea-collaboration.md) 由 dispatcher 串行分配并创建 `claims/T-<编号>` 防御性标记；assignee、标签、读回和普通 create-branch API 都不能单独提供并发互斥。