diff --git a/.cursor/rules/git-workflow-and-environments.mdc b/.cursor/rules/git-workflow-and-environments.mdc index 59d6d4d0..580874ed 100644 --- a/.cursor/rules/git-workflow-and-environments.mdc +++ b/.cursor/rules/git-workflow-and-environments.mdc @@ -12,7 +12,8 @@ alwaysApply: true 1. **开发分支 (`dev`)**: - **合入基线**，不是日常 commit 目标。 - **禁止**在 `dev` 上直接开发提交（含 docs/chore）。 - - 一律从最新 `dev` 检出 `feature/` 或 `fix/`，在 feature 分支上渐进式提交；自测后占集成槽位，`--no-ff` 合回 `dev`，并删除临时子分支（见 [AGENTS.md](../../AGENTS.md) §6.2）。 + - 全部新增改动（含单 Agent、文档）从明确的 `dev` SHA 创建 `.worktrees/` 内的 `feature/*` / `fix/*` 任务；主目录只作集成与运行入口。 + - 创建、候选验证、串行合入、部署和安全清理统一遵守 [AGENTS.md](../../AGENTS.md) §6 与 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md)；不以旧脚本的强制删除替代清理门禁。 2. **测试分支 (`test`)**: - 当 `dev` 积累了一定的功能阶段后，合并至 `test` 分支，创建阶段候选节点 Tag（如 `rc-vX.Y.Z-beta.1`）。 diff --git a/.doc/README.md b/.doc/README.md index 99ed93ef..88f29a22 100644 --- a/.doc/README.md +++ b/.doc/README.md @@ -33,6 +33,7 @@ | 我要… | 读这里 | |--------|--------| +| 创建任务、集成、部署、清理 | [worktree 工作规范](ops/2026-09-21-agent-worktree-workflow.md) | | 当前在做什么 | [ops/CURRENT.md](ops/CURRENT.md) | | 模块完成度 | [status/FEATURE-MATRIX.md](status/FEATURE-MATRIX.md) | | 发布 blocker | [remediation/gap-matrix.md](remediation/gap-matrix.md) | diff --git a/.doc/ops/2026-09-13-herdr-agent-roster.md b/.doc/ops/2026-09-13-herdr-agent-roster.md index da311783..14a523f0 100644 --- a/.doc/ops/2026-09-13-herdr-agent-roster.md +++ b/.doc/ops/2026-09-13-herdr-agent-roster.md @@ -4,7 +4,7 @@ **owner**: `orchestrator_codex` **status**: active -本文只管理工程协作终端，不管理产品运行时智能体。通用分支、worktree、mutex、集成槽、密钥和破坏性操作规则仍以仓库根 [AGENTS.md](../../AGENTS.md) 为准。 +本文只管理工程协作终端，不管理产品运行时智能体。通用分支、worktree、mutex、集成槽、密钥和破坏性操作规则仍以仓库根 [AGENTS.md](../../AGENTS.md) 为准。任务启动、合入和清理同时遵守 [worktree 工作规范](./2026-09-21-agent-worktree-workflow.md)；客户端脚本尚未强制校验的条件由调用者先检查。 ## 1. 身份边界 @@ -69,7 +69,7 @@ Claude 只在 `critical-review` 中作为前排备援；其他 lane 放在最后 | Kimi | `--auto` | Never Ask 模式 | | Cline | `--tui --auto-approve true` | 所有工具自动批准 | -即使客户端不弹确认框，Agent 也不得自行执行：删库/清空数据、强推、删除主干或 worktree、停止 Herdr server、覆盖其他 Agent 未合并改动、泄露密钥、未获用户授权的外部写入。需要新权限时写 handoff/blocker，不把确认框转交给用户逐条点击。 +即使客户端不弹确认框，Agent 也不得自行执行：删库/清空数据、强推、删除主干或未通过清理门禁的 worktree、停止 Herdr server、覆盖其他 Agent 未合并改动、泄露密钥、未获用户授权的外部写入。需要新权限时写 handoff/blocker，不把确认框转交给用户逐条点击。 ## 6. 操作入口 diff --git a/.doc/ops/2026-09-21-agent-worktree-workflow.md b/.doc/ops/2026-09-21-agent-worktree-workflow.md new file mode 100644 index 00000000..d324e745 --- /dev/null +++ b/.doc/ops/2026-09-21-agent-worktree-workflow.md @@ -0,0 +1,85 @@ +# Agent worktree 工作规范 + +**生效日期**：2026-09-21。用户已确认“提交吧，之后按这套执行”。 +**规范来源**：[AGENTS](../../AGENTS.md) §6；[完整方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)。 + +本文件用于创建任务、集成、部署、清理时执行。工作方式立即采纳；自动注册表、队列、服务守卫、OS 权限隔离尚未实现，当前使用下面的显式校验与人工协调。代码文件隔离不等于数据库或运行环境隔离。 + +## 1. 创建任务 + +1. 读取启动链，检查主目录和各任务的 `git status`、分支、`git worktree list --porcelain` 与 CURRENT/任务文。识别其他 Agent 的活跃任务，冲突范围不进入写阶段。 +2. 确认主工作区真实路径：通过 Git worktree 列表和 common-dir 核对，不根据当前脚本父目录推算。已有 `.kilo` 或目录/分支不匹配 worktree 仅盘点，不自动搬动或清理。 +3. 确定任务 ID、允许写路径、mutex 和验证计划；同一写范围只有一个 owner。CURRENT 在各分支内仅作快照，协调者还需交叉核对活跃任务；未实现原子注册表前不宣称已有自动原子认领。 +4. 使用显式本地 dev SHA。远端状态注明已 fetch 或仅本地跟踪快照；不因创建任务在主目录 checkout/pull，也不从 feature 派生无关任务。 + +在已核实的主仓路径执行以下语义；示例 task-id 须替换为本任务唯一标识： + +```bash +repo_main=/home/weichen/projects/Agent-System +base_dev_sha=$(git -C "$repo_main" rev-parse --verify 'dev^{commit}') +git -C "$repo_main" worktree add -b feature/task-id "$repo_main/.worktrees/task-id" "$base_dev_sha" +``` + +先检查目标路径不存在、无 symlink 越界、分支未被使用；保留 `base_dev_sha` 到任务文。主目录需移动 Git 引用时取得下述锁。不要使用尚未修复的 `agent-worktree.sh create/remove`：前者未明确 dev 起点，后者包含强制删除。 + +## 2. 开发、测试与准入 + +- 所有新增代码、配置、规范和文档修改都在任务 worktree 完成；同一任务允许多个提交。 +- `.env`、业务数据、真实用户会话、其他任务的构建产物不复制到新工作区。测试使用专属数据库、目录、端口和测试身份。 +- 每次准入冻结完整 head SHA；记录命令、结果和证据。提交变化或 dev 组合变化后检查受影响的准入是否需重跑。 +- Go、web、迁移、产品 PI 的门禁见完整方案 §6.2。治理规则/纯工程文档检查链接、规则冲突、差异和状态；不启动真实 PI 或重建业务服务。 +- 普通文档与运行模板、提示词分开：`templates/**/*.md`、`configs/**/*.md` 可能改变运行行为。 + +## 3. 串行锁和集成槽位 + +共享 dev 的 Git 更新、部署、写入验收都使用共同 Git 目录下同一个 `agent-control/dev-integration.lock`。锁是本机合作约束；旧客户端可绕过，因此仍核查主目录现场、活跃任务、CURRENT 槽位并保留前后基线。完整注册表、自动队列另行实施。 + +锁应由覆盖整个操作的父进程持有，不是一个命令拿锁后退出再执行下一条： + +```bash +common_dir=$(git rev-parse --path-format=absolute --git-common-dir) +mkdir -p "$common_dir/agent-control" +exec 9>"$common_dir/agent-control/dev-integration.lock" +flock -n 9 || exit 1 +# 在本进程及受控子进程中执行基线核对、候选准入、dev 更新与所需部署/验收。 +# 同时记录 owner、task、phase、原 dev、候选 SHA 和恢复状态。 +# 操作完毕或形成失败交接后退出本进程，关闭 fd 9。 +``` + +CURRENT holder/phase 由集成任务分支记录并在合入时成为快照，不能为占槽去改动另一个活跃任务的脏工作区。实时 owner/phase 可写在 common-dir 的 `agent-control/active-operation.json`，但该文件不是锁。结束保留结果再释放；发现前次非终态记录，先核查恢复，不能只因锁空闲就重复执行。 + +共享 dev 的长 E2E 持锁至结束；独立固定环境才允许释放 dev。资源不足则排队，不默认起多套共享 Compose 或终止产品任务。 + +## 4. 集成候选与部署 + +1. 锁定 dev 基线 D 和任务 head T；任务工作树干净且准入证据有效。 +2. 从 D 建 `.worktrees/` 下的 `feature/integrate-*`，把 T 以 `--no-ff` 合成候选 M。业务冲突退回 owner 修复；集成者不在主目录改代码解冲突。 +3. 在 M 验证相应门禁。dev 仍为 D、任务仍为 T 才可在干净 dev 工作区 `merge --ff-only M`；变化则重建候选。dev 历史保留该 no-ff 节点，不再重做另一份未测试合并。 +4. 纯工程规范/文档标 `deployment=not_required`。运行内容变化则从已合入版本构建/应用确定制品，核验实际镜像、schema、`/health`、`/ready` 和相关业务链路。 +5. 当前 `candidate-images-build.sh --commit` 未保证构建树等于参数，修复前调用者必须确保干净树、HEAD 与参数完全一致，记录证据；不能仅凭标签声明准确版本。 +6. `restart` 仅重启现有容器。worktree 不调用共享 `env-service.sh` 写命令；共享服务只由主目录下获授权的持锁集成者操作。失败记录 merged/deployed/accepted 的实际状态，兼容性不明时不自动恢复数据库。 + +### 主目录旧任务尚未结束时 + +保护旧任务现场，不能为了落实新规范先强切 dev。仅**纯工程规范/文档**允许过渡例外：dev 未在其他 worktree 检出时，持锁将 dev 检出到 `.worktrees/agent-governance-dev-integration`，只接收已验证文档候选，不运行服务、不合入未验收业务代码。登记临时目录、原因和接管人，当前根目录继续保持原任务分支。 + +旧任务 owner 保存/提交成果、确认主目录干净后：先确认临时 dev 工作区干净且没有 Agent/进程使用，普通 remove 该临时 worktree，释放 dev 检出占用，再由主目录切回 dev。不能用 `--ignore-other-worktrees` 或强删抢占。此前新任务直接从 dev ref 创建自己的 worktree，读取 dev 中已采纳的规范；旧任务收口时也按新流程集成。 + +## 5. 安全清理 + +清理在待删除目录外执行，依次核查： + +1. worktree 实际路径、分支与任务登记一致；无越界/保护项；无 merge/rebase 中间状态。 +2. `git merge-base --is-ancestor dev` 成功；冻结后未新增未合入提交。 +3. 所需部署与验收通过或 not_required；报告、截图和唯一日志已归档。 +4. 检查 tracked、untracked **及 ignored 文件**；只允许丢弃确认可再生的缓存，不因 `git status --short` 为空就认定没有证据文件。 +5. Agent/测试进程已退出、无进程 cwd/其他任务依赖该目录。 +6. 普通 `git worktree remove `；分支用 `git branch -d `。若非 dev 当前检出导致 -d 拒绝，即使祖先检查通过也保留到 dev 可用时清理，不换成 -D。 + +失败只标 cleanup_pending，保留数据。禁止强制删除、按年龄批量删除或把 worktree 清理扩展为 data/数据库/容器卷清理。Push 仅在用户明确要求时执行，并与本地提交/合入分开报告。 + +## 6. 执行状态 + +- 已采纳：强制任务 worktree、明确 dev 基线、主目录保护、串行集成/部署、按范围验证、条件清理。 +- 可立即执行：本规范的原生 Git、人工范围认领、本机 flock、精确候选检查。 +- 尚待工程实现：自动登记与排队、脚本强制 guard、安全 helper、部署身份闭环、PI 镜像交付、故障自动恢复和 OS 沙箱。见 [自动化实施任务](./long-term/2026-09-21-agent-workflow-governance-automation.md)。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 6882b230..9f7e73ea 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -13,6 +13,8 @@ | owner | task | branch | worktree | mutex | status | |-------|------|--------|----------|-------|--------| +| Cursor | 2026-09-21-intent-workflow-scoping | fix/intent-workflow-scoping-2026-09-21 | -（迁移前旧任务，保留现场） | intent+web+docgov | in_progress | +| Codex | 2026-09-21-agent-workflow-governance-adoption | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance | in_progress | | Codex | 2026-09-21-agent-workflow-governance-plan | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance-plan | done | | Cursor | 2026-09-21-workflow-doc-key-unification | fix/workflow-doc-key-unification-2026-09-21 | .worktrees/fix-workflow-doc-key-unification-2026-09-21 | docgov+web | done | | Cursor | 2026-09-21-dev-deep-test-four-issues | fix/dev-deep-test-four-issues-2026-09-21 | - | web+intent+taskrun | done | @@ -178,7 +180,7 @@ | holder | phase | since | scope | queue | |--------|-------|-------|-------|-------| -| - | idle | 2026-09-21 | 文档键统一已合入并重建 dev；`/health` schema_version=60；项目 6579 为 7 条 bd_* | - | +| Codex | merging | 2026-09-21 | Agent worktree 规范采纳；仅文档候选集成，主目录旧任务现场保留；deployment=not_required | - | **phase**: `idle` | `merging` | `smoke` | `e2e` @@ -196,7 +198,7 @@ | 类型 | 路径 | |------|------| -| 2026-09-21 Agent worktree 治理（仅方案） | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md) · [调研](./research/2026-09-21-agent-workflow-governance-research.md) · [交接](./handoffs/2026-09-21-agent-workflow-governance-plan.md)；未实施、未合入 dev | +| 2026-09-21 Agent worktree 工作规范 | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md) · [调研](./research/2026-09-21-agent-workflow-governance-research.md) · [交接](./handoffs/2026-09-21-agent-workflow-governance-plan.md)；规范已采纳，自动化另列 planned | | 2026-09-20 rdev 种子 | [short-term](./short-term/2026-09-20-rdev-seed-hotfix.md) · [报告](../test-reports/2026-09-20-rdev-seed-hotfix-test-report.md) | | 2026-09-20 模块解耦 | [审计](../audit/2026-09-20-module-coupling-audit.md) · [规范](../system-design/2026-09-20-module-development-standards.md) · [批次 A–G](../remediation/2026-09-20-module-decoupling-batch-plan.md) · [short-term](./short-term/2026-09-20-module-decoupling-spec-audit.md) | | 文档总地图 | [../README.md](../README.md) | diff --git a/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md index 19622af9..7d645b57 100644 --- a/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md +++ b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md @@ -1,12 +1,12 @@ --- -title: "Agent worktree 并行治理方案待审核" +title: "Agent worktree 并行治理规范采纳与迁移交接" created: 2026-09-21 from: Codex to: user-and-next-agent status: open --- -# 交接：Agent worktree 并行治理方案待审核 +# 交接：Agent worktree 并行治理规范采纳与迁移交接 ## 已完成 @@ -16,26 +16,26 @@ status: open ## 下一步 -用户审核方案后，从最新 dev 按 W0–W4 逐步实施；尚未授权执行治理改造、旧 worktree 清理或服务更新。本次 worktree 留作审核，不能自动清理。 +用户已确认采纳并提交。生效规则见 [worktree 工作规范](../2026-09-21-agent-worktree-workflow.md)；自动化仍按 [W0–W4 实施任务](../long-term/2026-09-21-agent-workflow-governance-automation.md) 追踪，不能当作已经实现。此次仅集成规范文档，不迁移旧任务或重建服务。 ## 认领 / 槽位 | 项 | 值 | |---|---| | 研究 mutex | 已在本 worktree CURRENT 标记 done | -| 共享集成槽位 | 未占用，未修改主目录 CURRENT | +| 共享集成槽位 | 本任务分支 CURRENT 登记文档集成；实际操作持 common-dir 下 dev-integration.lock，主目录 CURRENT 保留 | | branch | feature/agent-workflow-governance-plan | | worktree | .worktrees/feature-agent-workflow-governance-plan | | 起点 | 本地 dev@15b8a4a8 | -| 合入 / push | 均未执行；方案只在本地任务分支 | +| 合入 / push | 本次按已验证候选合入本地 dev；未 push，最终结果见规范采纳验收报告 | ## 验证及边界 - 仅文档差异、链接和状态检查；未运行 Go/前端测试、迁移或真实 PI 操作，不作产品验收声明。 - 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。 -- 当前没有机器协调入口，分支 CURRENT 不等于全局实时认领。本任务只读代码，写入独立文档文件。 +- 当前没有自动任务协调器，分支 CURRENT 不等于全局实时认领。此次只有人工明确范围和本机 flock，不宣称自动队列或全局硬隔离已实现。 - 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。 -- 后续合入 CURRENT 要保留当时其他任务和槽位状态；本次不合入是因为仅请求研究方案且主目录正有进行中任务，不是已经完成的代码交付。 +- 主目录仍是旧任务分支；dev 暂由 `.worktrees/agent-governance-dev-integration` 检出以安全集成文档。旧任务 owner 保存成果、确认主目录干净后，先安全移除临时 dev worktree，再在主目录切回 dev；不得强抢 dev 检出。 ## 相关链接 diff --git a/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md b/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md new file mode 100644 index 00000000..35412922 --- /dev/null +++ b/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md @@ -0,0 +1,28 @@ +--- +title: "Agent worktree 治理自动化 W0–W4" +status: planned +created: 2026-09-21 +updated: 2026-09-21 +owner: next-implementation-owner +mutex: agent-workflow-governance +--- + +# Agent worktree 治理自动化 W0–W4 + +工作方式已由用户采纳，本任务跟踪尚未实现的工程能力。规则生效不等于脚本或权限隔离已完成。 + +## 按依赖实施 + +1. W0：接续主目录旧任务，核查运行挂载与热补丁，安全回到 dev。 +2. W1：修 worktree 创建起点、主仓定位、安全 remove、路径/分支校验和构建忽略。 +3. W2：原子认领、资源 mutex、集成队列、env-service guard、operation 恢复。 +4. W3：候选测试对应实际 dev/运行制品，PI 源码镜像交付、就绪/业务验收和恢复。 +5. W4：证据归档、条件自动清理、客户端薄入口与状态投影。 + +每个实施任务从当时 dev 在 `.worktrees/` 开工；按 [完整方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) §11 验收。W5 OS/跨机能力按实际需要另立任务。 + +## 关闭条件 + +- 两个独立任务完成并行开发、串行交付、运行验收和安全清理。 +- 错误起点、并发抢占、危险清理、部署失败/超时/崩溃均有拒绝或恢复证据。 +- 自动化机制确实落地后再将对应 FEATURE-MATRIX 能力升 done。 diff --git a/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md b/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md new file mode 100644 index 00000000..2428761f --- /dev/null +++ b/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md @@ -0,0 +1,36 @@ +--- +title: "采纳 Agent worktree 工作规范" +status: in_progress +created: 2026-09-21 +updated: 2026-09-21 +owner: Codex +branch: feature/agent-workflow-governance-plan +worktree: .worktrees/feature-agent-workflow-governance-plan +mutex: agent-workflow-governance +--- + +# 采纳 Agent worktree 工作规范 + +## 授权与范围 + +用户于 2026-09-21 确认“提交吧，之后按这套执行”。延续原治理任务，在原 dev 派生的独立 worktree 内将方案采纳为生效规则，提交并合入本地 dev。仅修改规范、模板和治理记录。 + +本次不将 W1–W4 的自动化开发宣称已完成；它们保留在实施任务中。主目录仍有其他任务未提交改动，使用临时集成 worktree 合入纯文档，不迁移原任务、不改变业务运行态、不 push。 + +## 步骤 + +1. [x] 核对主目录现场、原方案提交与集成槽位。 +2. [ ] 同步 AGENTS、PROJECT、Cursor 规则、操作规范与模板。 +3. [ ] 文档检查、提交、独立 worktree 合入 dev。 +4. [ ] 更新验收/交接及清理状态。 + +## 验收 + +- [ ] 单 Agent 主目录开发例外已移除，生效规则可从启动链发现。 +- [ ] 创建明确来自 dev；测试提交、共享服务串行、部署及安全清理条件可执行。 +- [ ] 自动化能力保持 planned；主目录其他任务未提交改动不被纳入提交。 +- [ ] 本地 dev 含本次规范提交；未 push，未重建服务。 + +## 相关链接 + +- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) diff --git a/.doc/ops/templates/session-close-checklist.md b/.doc/ops/templates/session-close-checklist.md index ae2cb032..4ecfd608 100644 --- a/.doc/ops/templates/session-close-checklist.md +++ b/.doc/ops/templates/session-close-checklist.md @@ -5,14 +5,14 @@ ## 认领与集成 - [ ] CURRENT「并行认领」行 status 已更新（done 或移除） -- [ ] 若曾占集成槽位：smoke 已完成，holder=idle，queue 已通知 +- [ ] 若曾占集成槽位：所需 smoke/E2E 已完成（或失败恢复交接），锁已释放、holder=idle；文档可记 deployment=not_required - [ ] mutex 无遗留 in_progress（除明确 handoff 交接项） ## 代码与分支 - [ ] 确认未在 `dev` / `test` / `main` 上直接 commit（工作均在 `feature/*` 或 `fix/*`） -- [ ] 已占集成槽位并 `merge --no-ff` 合回 `dev`（或 handoff 说明未 merge 原因） -- [ ] feature/fix 分支已删除或 worktree 已 remove（若已合入） +- [ ] 已持锁/占槽验证合并候选并合回 `dev`（或 handoff 说明未 merge 原因） +- [ ] 已按 [清理门禁](../2026-09-21-agent-worktree-workflow.md) 核对祖先、部署/验收、文件与进程；普通 remove/-d 已完成，或记录保留原因（不强删） - [ ] 无未 push 的关键提交（若用户要求同步远端） ## 文档 diff --git a/.doc/ops/templates/short-term-task.md b/.doc/ops/templates/short-term-task.md index a1d7dbff..930e8cfe 100644 --- a/.doc/ops/templates/short-term-task.md +++ b/.doc/ops/templates/short-term-task.md @@ -5,7 +5,12 @@ created: YYYY-MM-DD updated: YYYY-MM-DD owner: agent branch: feature/ # 必填：feature/* 或 fix/*；禁止 dev / test / main -worktree: "-" +worktree: .worktrees/ +base_dev_sha: <创建时的完整 dev SHA> +write_scope: [<允许修改的路径>] +head_sha: <准入时冻结的提交> +deployment: pending # pending | passed | failed | not_required +cleanup: pending # pending | done | retained-with-reason mutex: --- diff --git a/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md index 4b93c7e1..3b81c15f 100644 --- a/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md +++ b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md @@ -8,6 +8,8 @@ owner: Codex # Agent 工作规范与 worktree 并行开发治理方案 +> **2026-09-21 已采纳**：用户确认“提交吧，之后按这套执行”。生效工作规范见 [执行入口](../ops/2026-09-21-agent-worktree-workflow.md)。本文 status=planned 追踪尚未实现的自动化 W0–W4，不代表仍待审核；采纳与自动化验收分开记录。 + ## 1. 建议与目标 采用“主目录作为 dev 集成与运行入口，所有任务在 `.worktrees/` 内开发，自动检查后进入串行集成队列”的方案。单 Agent 也遵守。一个任务对应一个分支和一个 worktree，可包含多个原子提交；不是每改一个文件就新建分支。 @@ -20,7 +22,7 @@ owner: Codex 4. “合入”“部署成功”“业务验收通过”“已清理”“已推送”是不同事实，分别记录。 5. 普通文档不改变运行内容，无需每次重建 dev；部署范围应按实际差异判定。 -本次是待审核方案，未修改生效规则或脚本，未授权迁移既有任务、服务重建、批量清理及 test/main 晋升。 +原研究阶段只形成方案；现已采纳工作规范。此次规范提交不包含自动化脚本开发、既有任务迁移、服务重建、批量清理或 test/main 晋升。 现状依据：[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md)。目标是降低误改和并行竞争，不重建个人工程中控台，不为每项任务默认起全套环境。 @@ -208,7 +210,7 @@ flowchart LR push 与本地完成分开：用户未要求时不自动 push；已要求时必须成功并验证对应远端引用后才关闭同步项。没有 push 的合入仍需明确报告本地状态。清理只移除已安全保存的任务目录，不清理 `data`、共享卷或其他 Agent 目录。 -旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。本次研究 worktree 也因方案尚待审核而保留。 +旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。原研究 worktree 现可在规范合入且清理门禁满足后移除；临时 dev 集成 worktree 如需保留，必须交接主目录恢复条件。 ## 9. 规则与工具落点（拟实现） @@ -263,11 +265,11 @@ W1/W2 是最小可用安全闭环，W3/W4 达到用户完整目标。不要在 W 成功指标：新任务在主目录直接开发次数为 0；共享服务并发变更为 0；每次交付有可追溯收据；不产生强制删除；结束任务无无主 worktree。再收集候选重跑率、集成等待时间、构建时间和残留目录数，决定是否值得增加独立预览环境。 -## 12. 审核建议与待实施边界 +## 12. 已采纳方向与待实施边界 -建议批准 W0–W4 作为整体方向，先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。 +已采纳 W0–W4 方向；实施次序为先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。 -最值得审核的是两个策略：是否接受主目录只接收已测试合并节点的快进更新，以及是否将 dev PI 源码热挂载改为镜像交付。两者均推荐；实施前需接续现有主目录任务并核查热补丁，不能直接迁移现场。 +已采纳主目录接收已测试合并节点的流程，以及 dev PI 源码改为镜像交付的方向。后者尚未实施，切换前需接续现有主目录任务并核查热补丁，不能直接迁移现场。 尚未验证：远端分支保护、实际远端最新 dev、主机可承载的最佳并行数、每个客户端的沙箱边界。它们不阻碍本地方案成立，但不得据此承诺绝对禁止所有绕过或无限并行。 diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index 5f9cb682..e2c7a8e4 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -49,7 +49,7 @@ | 模块 | 声明范围 | 状态 | 发布关系 | 证据 | 剩余工作 / 关闭条件 | mutex | |------|----------|------|----------|------|---------------------|-------| -| Agent worktree 并行治理 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | planned | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md) | 仅完成研究与方案；规则、脚本、机器锁和试点均未实施，不能宣称已强制隔离 | `agent-workflow-governance` | +| Agent worktree 治理自动化 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | planned | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md) | [工作规范](../ops/2026-09-21-agent-worktree-workflow.md) 已采纳；人工显式校验立即执行。自动注册表、队列、脚本守卫、部署闭环和权限隔离仍待[实施](../ops/long-term/2026-09-21-agent-workflow-governance-automation.md)，不能宣称自动强制已完成 | `agent-workflow-governance` | | 意图识别 L1 | 18 类 Intent、三分支消解、写/只读分流、双标签 `DOC_BUSY`、intent 纯依赖边界 | done | non_blocker | [intent-recognition](../system-design/intent-recognition/)；[审计](../audit/2026-09-13-conversation-intent-runtime-state.md)；[报告](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/live.json)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U3](../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) | **边界 before**：含 U9–U12 叙事混入 → **after**：U9–U12 迁至「多意图扩面」行。关闭：纯依赖边界回归即重开 | `intent` | | 多意图持久计划（U1–U8 基线） | app/intentflow 生命周期、HITL、默认 `legacy`、U1–U8 代码与安全基线 | partial | non_blocker（默认 legacy） | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U8](../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md)；[Wave2 真 PI](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | legacy 有限只读多意图仍默认启用；新持久计划生产组合根仍使用 Fake query owner，confirm 后缺可靠调度，typed 参数/目标版本不足。原 U1–U8 测试证据保留，但不足以证明升 `auto_read/confirm` 可用。关闭条件见[整改方案](../remediation/2026-09-20-capability-enablement-impact-plan.md) Foundation 1 与 Track I | `intent-plan` | | 多意图扩面（U9–U12） | U9 LLM 分段实验；U10 mutate；U11 docgov；U12 workflow/run-control | partial | deferred_enhancement | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[脚手架](../test-reports/2026-09-16-pu8-u9-u12-flags-test-report.md)；[U9](../test-reports/2026-09-17-w4-u9-segment-test-report.md)；[U10](../test-reports/2026-09-17-w4-u10-mutate-test-report.md)；[U11](../test-reports/2026-09-17-w4-u11-docgov-test-report.md)；[U12](../test-reports/2026-09-17-w4-u12-run-control-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | U9 proposer 已实现和注入但未进入生产聊天分段调用；提议请求已带 reasoning profile。U10–U12 当前为 dry-run/validated-only adapter。历史直接调用/PI 测试继续有效，不代表 live 接线。逐域实现和验收，禁止以 `full` 一次放量 | `intent-plan` | diff --git a/AGENTS.md b/AGENTS.md index 0fdaafa6..e75af5c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,9 @@ 3. **[`.doc/README.md`](./.doc/README.md)**（文档 taxonomy） 4. **[`.doc/ops/CURRENT.md`](./.doc/ops/CURRENT.md)**（焦点、并行认领、集成槽位） 5. **[`.doc/status/FEATURE-MATRIX.md`](./.doc/status/FEATURE-MATRIX.md)**（模块完成度） -6. 相关 **short-term** / **handoff** / **audit** / **remediation** -7. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md) +6. 创建任务、合入、部署、清理前：读 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)（含自动化未落地时的操作方法） +7. 相关 **short-term** / **handoff** / **audit** / **remediation** +8. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md) **未读完不得开始改代码**（紧急热修除外，事后必须在 24h 内补文档）。 @@ -90,79 +91,47 @@ ## 6. 多 Agent 协作 -### 6.1 并行认领（编码阶段） +### 6.1 任务与主目录边界 -任务开始前在 CURRENT「并行认领」表登记： +- 主目录作为 `dev` 集成与运行入口；**所有新增开发、配置、规范和文档改动，包括单 Agent 任务，均在 `.worktrees/` 的任务 worktree 内完成**。 +- 主目录跟踪文件只通过受控 Git 集成更新，不作日常编辑；`.git`、任务 worktree、服务运行数据和获授权的运维配置属于明确例外。禁止递归 chmod 整个主目录。 +- 一个任务一个 `feature/` / `fix/` 分支、一个 worktree，可包含多个原子提交。既有任务延续原任务分支；无关新任务重新从 dev 创建。 +- 已经在主目录运行的旧任务保留现场，由所有者完成或交接后迁移；其他 Agent 不得擅自 checkout、stash、reset、移动其未提交文件。 +- 任务必须登记 owner、branch、worktree、base_dev_sha、允许写路径、mutex、验证计划。CURRENT 保留认领快照；各 worktree 的 CURRENT 不构成原子锁。 +- 同一 mutex 或重叠写路径同时只允许一个写者；公共 lockfile、路由、迁移号单独认领。冲突时排队或写 handoff，不覆盖他人工作。 -| 字段 | 说明 | -|------|------| -| owner | 工具 + 标识 | -| task | short-term 文件名 | -| branch | `feature/*` 或 `fix/*` | -| worktree | 路径或 `-` | -| mutex | 模块名（见 FEATURE-MATRIX） | -| status | `in_progress` / `blocked` / `done` | +### 6.2 创建与开发 -**同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。 +1. 先核对仓库、主工作区、当前分支、工作树状态、已有 worktree 与任务认领。 +2. 由协调者管理 dev 同步；开发 Agent 不在共享主目录切分支或直接 pull。记录本地 dev 的确切 SHA 与远端同步状态，分叉时保留现场。 +3. 显式从该 `base_dev_sha` 创建 `.worktrees/`，不能省略起点，也不从另一 feature 分支开新任务。 +4. 在任务 worktree 完成开发、原子提交、相应测试和文档；不复制主目录 `.env`、业务 data 或其他任务的可变产物。 +5. 提交集成前冻结 head SHA；变更超出允许范围时先重新认领，提交变化后原测试/审查准入失效。 -### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支） +当前脚本尚有错误起点和强制删除缺口，**修复验收前不用 `agent-worktree.sh create/remove`**；按 [操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md) 使用带显式起点的 Git 命令和非强制清理。 -> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。 -> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。 +### 6.3 串行集成与环境验收 -**任务开始（先于改码）：** +- 编码和隔离测试可并行；dev 合入、共享服务变更和共享环境验收必须串行，记录 CURRENT 槽位和共同 Git 目录中的执行锁。完整机器队列未实现时按操作规范手工持锁，不以 Markdown 的 idle 作为唯一准入。 +- 推荐在 `.worktrees/` 内的临时 `feature/integrate-*` 上从 dev 基线生成 `--no-ff` 合并候选，验证该提交；锁内确认 dev 基线未变后，将干净 dev 工作区 `--ff-only` 推进至同一候选。dev 变化则重新组合并验证。 +- 业务冲突返回任务 worktree 解决；dev/test/main 禁止直接开发提交。迁移期间主目录被旧任务占用时，纯规范/文档可使用登记的临时 dev 集成 worktree，禁止由此操作共享服务；详见操作规范的收口条件。 +- Go 变更执行 PROJECT 的 Go/架构及相关 PG 检查；web 变更执行前端检查与受影响浏览器验证；涉及产品 PI 的业务交付执行真实链路验收。纯工程规范/文档只做对应一致性检查，不为形式重建服务。 +- 影响运行内容的改动合入后，持有环境槽位更新 dev，核查实际制品、`/health`、`/ready` 和相关业务行为。`restart` 不证明新代码部署；模板/提示词 Markdown 不能按普通文档跳过部署。 +- 使用共享 dev 的长 E2E 持有环境槽位直到结束；仅在切换到独立固定环境后才可提前释放。失败或未知结果先核对运行态、记录恢复，不能冒充 PASS 或盲目重复执行。 +- CURRENT 槽位字段仍为 `holder | phase | since | scope | queue`；生产/test 晋升独立授权，dev 任务不得顺手操作 `all`。 -1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端） -2. 从 `dev` 创建分支：`feature/`（新能力）或 `fix/`（缺陷）；slug 与 short-term 任务名对齐 -3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/`（worktree 内编码） -4. 单 Agent：可在主仓 `git checkout -b feature/`，**不得**留在 `dev` 上改码提交 +### 6.4 收口与清理 -**合回 dev（占集成槽位，见 §6.3）：** +- 分别报告已提交、已合入 dev、已部署、已验收、已清理、已推送；文档合入可注明 `deployment=not_required`。 +- 清理前核对：任务提交是 dev 的祖先、所需验收通过、证据持久化、无 tracked/untracked/唯一 ignored 遗留文件、无 Agent/进程或其他任务使用、路径与分支一致且不属保护项。 +- 使用普通 `git worktree remove` 和 `git branch -d`；拒绝时保留并记录 cleanup_pending，不升级到 `--force` / `-D`，不批量清空 `.worktrees`。 +- 未合入或待恢复任务保留 worktree 与 handoff；部署失败按兼容性恢复/前滚，不自动回滚数据库或硬重置 dev。 -```bash -git checkout dev -git merge --no-ff feature/ -m "merge: feature/" -# 冒烟通过后 -git branch -d feature/ # 或 agent-worktree.sh remove -``` +### 6.5 共享文档 -| 允许 | 禁止 | -|------|------| -| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit | -| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` | -| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 | -| 连主仓已起服务 `:8080` | 各 worktree 各起 docker | - -脚本：`./scripts/agent-worktree.sh create|list|remove` - -### 6.3 集成槽位（合入 dev + 容器验证） - -> **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。** - -Agent A 占槽 merge + 冒烟期间，Agent B **不得** merge dev 或动共享 docker；B 可继续 worktree 编码，并写入 queue 等待。 - -CURRENT「集成槽位」：`holder` | `phase`（idle/merging/smoke/e2e）| `since` | `scope` | `queue` - -**释放**：冒烟 PASS（或 FAIL+handoff）+ 文档同步 + holder=idle。长 E2E 优先 smoke 释放，E2E 结果后补报告。 - -**默认冒烟（holder 在主仓执行）**： - -```bash -go vet ./... -go test -short ./... -./scripts/env-service.sh dev rebuild -curl -sf http://127.0.0.1:8080/health -``` - -### 6.4 共享文档 - -`CURRENT.md` / `FEATURE-MATRIX.md` 由认领方或合并者更新；冲突时保留双方认领行再收敛。 - -### 6.5 协作纪律 - -- **单一焦点**：CURRENT 只列 1–3 个焦点 -- **不覆盖**：发现冲突先 handoff/blocker -- **交接优先**：口头转述不可代替 handoff 文件 +- CURRENT 只列 1–3 个焦点；机器状态与 Git 现场优先，CURRENT 是带日期的协作快照。 +- 实现者在任务文记录状态和 FEATURE-MATRIX 变更意图，由集成者串行汇总；保留其他任务、槽位与历史证据。 +- 规范生效与自动化实现分别记录；机器锁服务、队列、脚本守卫和权限沙箱未验收前不得宣称已自动强制。 ### 6.6 Herdr 角色、自动审批与备援 @@ -190,7 +159,7 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务） - 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci` - **原子提交**：一个逻辑变更一批；提交发生在 `feature/*` 或 `fix/*` 上，不在三大主干 -- **合回 dev**：占集成槽位后 `merge --no-ff`（见 §6.2、§6.3） +- **合回 dev**：占槽验证 `--no-ff` 合并候选，dev 接收已验证节点（见 §6.3）；只在任务分支直接开发提交 - **晋升**：`dev` → `test`（rc tag）→ `main`（release tag）；仅在规划的环境合并时动 `test`/`main` - **用户未要求**：不擅自 push - **用户已要求 push/同步远端**：必须自主完成 diff --git a/PROJECT.md b/PROJECT.md index 33594798..ebaab179 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -53,7 +53,7 @@ **红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。 -**分支红线**：三大主干（`dev`/`test`/`main`）禁止直接开发 commit；一律从 `dev` 开 `feature/*` 或 `fix/*`，合回 `dev` 须占集成槽位（见 [AGENTS.md](./AGENTS.md) §6）。 +**开发入口**：所有新增改动均从明确的 `dev` 提交创建 `feature/*` / `fix/*`，在 `.worktrees/` 内完成；主目录保留给集成与运行。任务创建、串行集成、部署和清理遵守 [AGENTS.md](./AGENTS.md) §6 及 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)。 --- @@ -115,7 +115,7 @@ cd web && npm test && npm run build ## 8. 测试与验收铁律 -- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M2.7-highspeed 全链路 +- 涉及产品 Agent/工作流的业务交付：开发可用 stub，**交付前验收**必须真实产品 PI Agent Runner + MiniMax-M2.7-highspeed 全链路。纯工程规范/文档变更执行对应一致性检查，不调用产品 PI - 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard - 禁止 stub 输出冒充最终验收数据 @@ -141,4 +141,4 @@ cd web && npm test && npm run build ## 11. 语言与提交 - 对用户：**简体中文** -- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，合回 `dev` 用 `--no-ff`（禁止在三大主干直接 commit） +- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，集成遵守 AGENTS §6.3 的已验证合并候选流程（禁止在三大主干直接开发 commit）