From 6e28c5724562511ddf1c412a41ea8e4d67c42e02 Mon Sep 17 00:00:00 2001 From: weichen Date: Mon, 21 Sep 2026 07:59:40 +0000 Subject: [PATCH 1/2] docs(workflow): plan isolated agent development and serialized integration --- ...26-09-21-agent-workflow-governance-plan.md | 48 +++ .doc/ops/CURRENT.md | 2 + ...26-09-21-agent-workflow-governance-plan.md | 43 +++ ...9-21-agent-workflow-governance-research.md | 61 ++++ ...26-09-21-agent-workflow-governance-plan.md | 274 ++++++++++++++++++ .doc/status/FEATURE-MATRIX.md | 1 + 6 files changed, 429 insertions(+) create mode 100644 .doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md create mode 100644 .doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md create mode 100644 .doc/ops/research/2026-09-21-agent-workflow-governance-research.md create mode 100644 .doc/remediation/2026-09-21-agent-workflow-governance-plan.md diff --git a/.doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md b/.doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md new file mode 100644 index 00000000..9905cdd2 --- /dev/null +++ b/.doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md @@ -0,0 +1,48 @@ +--- +title: "Agent 工作规范与 worktree 并行治理方案" +status: done +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-plan +--- + +# Agent 工作规范与 worktree 并行治理方案 + +## 目标 + +基于当前仓库规范、脚本和现场，评估主目录保护、强制 worktree、串行集成与清理机制，交付可审核方案。 + +## 范围 + +- 只读检查 Git、脚本、Compose、测试入口和协作记录。 +- 形成调研、治理方案及交接文档；仅在本任务 worktree 写文档。 + +## 非目标 + +- 不修改业务代码、Agent 规则或运维脚本；不切换主目录分支、不干预其他任务、不重建服务、不清理既有 worktree、不 push。 + +## 步骤 + +1. [x] 阅读启动链并盘点现场。 +2. [x] 显式从本地 dev@15b8a4a8 创建独立 worktree。 +3. [x] 完成机制核验、方案和边界审查。 +4. [x] 写交接并核查文档差异。 + +## 验收标准 + +- [x] 有现状证据、方案比较、操作流程、并行边界、恢复与验收标准。 +- [x] 区分已存在机制与拟实现机制；不将方案宣称为已落地。 + +## 证据 / 备注 + +初始主目录为 fix/intent-workflow-scoping-2026-09-21，有其他任务未提交变更。为保护现场，未执行 checkout dev / pull；从显式本地 dev 创建 worktree。origin/dev...dev 为 0/309，仅为本地远端跟踪引用快照，本轮未 fetch。认领仅登记本 worktree 的 CURRENT，尚无跨 worktree 实时协调入口；本任务只读代码且使用独立文档路径。 + +## 交付 + +- [调研](../../ops/research/2026-09-21-agent-workflow-governance-research.md) +- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) +- [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md) +- 仅文档核验，未执行产品测试；治理能力在 FEATURE-MATRIX 保持 planned。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index ef0dc44c..6882b230 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -13,6 +13,7 @@ | owner | task | branch | worktree | mutex | status | |-------|------|--------|----------|-------|--------| +| 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 | | Cursor | 2026-09-21-trace-panel-to-chat | feature/trace-panel-to-chat-2026-09-21 | - | trace-impact+web | done | @@ -195,6 +196,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-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 new file mode 100644 index 00000000..19622af9 --- /dev/null +++ b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md @@ -0,0 +1,43 @@ +--- +title: "Agent worktree 并行治理方案待审核" +created: 2026-09-21 +from: Codex +to: user-and-next-agent +status: open +--- + +# 交接：Agent worktree 并行治理方案待审核 + +## 已完成 + +- 当前规范、worktree/服务/制品脚本、Compose、CI 和实际运行挂载的只读核查。 +- [调研](../research/2026-09-21-agent-workflow-governance-research.md) 与 [完整方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)，含现状差距、五阶段实施、恢复与十四项验收。 +- 本分支 CURRENT 登记已结束；FEATURE-MATRIX 新能力保持 planned；研究任务归档。 + +## 下一步 + +用户审核方案后，从最新 dev 按 W0–W4 逐步实施；尚未授权执行治理改造、旧 worktree 清理或服务更新。本次 worktree 留作审核，不能自动清理。 + +## 认领 / 槽位 + +| 项 | 值 | +|---|---| +| 研究 mutex | 已在本 worktree CURRENT 标记 done | +| 共享集成槽位 | 未占用，未修改主目录 CURRENT | +| branch | feature/agent-workflow-governance-plan | +| worktree | .worktrees/feature-agent-workflow-governance-plan | +| 起点 | 本地 dev@15b8a4a8 | +| 合入 / push | 均未执行；方案只在本地任务分支 | + +## 验证及边界 + +- 仅文档差异、链接和状态检查；未运行 Go/前端测试、迁移或真实 PI 操作，不作产品验收声明。 +- 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。 +- 当前没有机器协调入口，分支 CURRENT 不等于全局实时认领。本任务只读代码，写入独立文档文件。 +- 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。 +- 后续合入 CURRENT 要保留当时其他任务和槽位状态；本次不合入是因为仅请求研究方案且主目录正有进行中任务，不是已经完成的代码交付。 + +## 相关链接 + +- [研究任务](../../archive/ops/2026-09-21-agent-workflow-governance-plan.md) +- [CURRENT](../CURRENT.md) diff --git a/.doc/ops/research/2026-09-21-agent-workflow-governance-research.md b/.doc/ops/research/2026-09-21-agent-workflow-governance-research.md new file mode 100644 index 00000000..fefa14ee --- /dev/null +++ b/.doc/ops/research/2026-09-21-agent-workflow-governance-research.md @@ -0,0 +1,61 @@ +--- +title: "Agent worktree 与并行协作机制核查" +created: 2026-09-21 +status: done +confidence: high +--- + +# Agent worktree 与并行协作机制核查 + +## 结论 + +用户提出的主目录保护、全部开发使用 worktree、从 dev 开任务分支、验证后合入并更新服务、安全清理的方向成立。当前仓库具备规范雏形，但机器执行尚未形成闭环；仅修改 AGENTS 文案无法保证并行可靠性。建议采用任务 worktree + 机器协调状态 + 串行集成队列，分阶段增加执行隔离。 + +本次核查为只读研究及文档编写，未执行产品测试、迁移或服务重建。下列发现是代码与现场证据，风险推断不等于已发生事故。 + +## 采样边界 + +- 2026-09-21 初始主目录：`fix/intent-workflow-scoping-2026-09-21@5c6b4f77`；`internal/server/stage_access_helpers.go` 已修改，`internal/projectinstance/workflow_scope.go` 未跟踪，均属其他任务。 +- 本地 dev：`15b8a4a8`；研究 worktree 显式以此创建。上述治理脚本与主目录版本 diff 为空。 +- `git rev-list --left-right --count origin/dev...dev` 为 `0 309`。未 fetch，仅说明当时本地跟踪引用状态，不能宣称实时远端落后 309。 +- `git worktree list --porcelain` 初始列出主目录及 4 个 linked worktree：其中 3 个在 `.worktrees/`，1 个在 `.kilo/worktrees/` 且 detached；新增本次研究 worktree 后为 5 个 linked worktree。 +- 本机 Git 2.53.0；`core.hooksPath` 未配置，`.git/hooks` 未检出非 sample 文件。 +- CURRENT 中仍保留较早的“extra worktree 仅余……”叙述，不能用作当前 worktree 清单。 + +## 发现与依据 + +| 编号 | 当前证据 | 影响 / 推断 | +|---|---|---| +| F01 | `AGENTS.md` §6.2 允许单 Agent 在主目录创建 feature 分支；CURRENT 多条 worktree=`-` | 用户提出的是对现行规范的实质收紧，必须统一修改入口与执行规则 | +| F02 | `scripts/agent-worktree.sh:50` 未给 start-point；Git worktree add 默认以 HEAD 为起点 | 从主目录任务分支创建新任务可能夹带其他任务提交，不能保证“来自 dev” | +| F03 | 同脚本 5–7 行从脚本目录推导 ROOT | 在 linked worktree 调用自身脚本会推导嵌套 `.worktrees`，不能定位唯一主仓 | +| F04 | 同脚本 34–35 行仅把 `/` 替换为 `-` | `feature/a-b` 与 `feature/a/b` 映射冲突；缺少任务 ID、严格命名及路径校验 | +| F05 | 同脚本 67–69 行默认 `remove --force`，可选 `branch -D` 且吞错 | 删除前未验证是否合入 dev、是否有未保存文件、是否仍有 Agent 使用；可能损失工作 | +| F06 | `scripts/env-service.sh:18–20,76–151` 从自身位置定位 Compose；无 worktree、分支、租约校验 | 文档禁止 worktree 动共享服务，但脚本未强制；`logs` 也会经过配置/目录初始化，非纯只读 | +| F07 | `docker-compose.dev.yml:8,13,38,74,147,174–184` 固定 project/container/network/volume 名 | 不同目录运行同份 Compose 不能获得独立环境；单改 project name 仍不足以隔离显式名称和宿主端口 | +| F08 | `docker-compose.dev.yml:53–58` 挂载主目录 PI 源码和数据；docker inspect 确认挂载实际存在 | 主目录变更可影响以后加载/重启时的 Runner 行为；`:ro` 只约束容器写入，不冻结宿主文件内容 | +| F09 | `.doc/ops/CURRENT.md` 是普通版本化 Markdown，无原子认领；各 worktree 内容不同 | 两个 Agent 可同时看到 idle；分支内认领不会实时传到另一 worktree；不能用作真正互斥锁 | +| F10 | `AGENTS.md` §6.3 要求长 E2E 可先 smoke 释放槽位 | 如 E2E 仍使用可变共享 dev，后续部署会使证据混合；必须保留环境租约或转入隔离环境 | +| F11 | `scripts/herdr-agent-start.sh:97–109`、dispatch 66–77 行校验仓库文件和 feature/fix 分支，未检验 linked worktree 身份 | 主目录 feature 分支同样可通过；同一逻辑实例名及同 cwd 路由需要适配并行任务身份 | +| F12 | `.dockerignore:1–20` 未排除 `.worktrees` / `.kilo`；`deploy/app/Dockerfile:19` 为 `COPY . .` | 多 worktree 可能进入构建上下文和构建阶段，增加大小和无关缓存失效；未测传输量，不断言全部最终进入运行镜像 | +| F13 | `scripts/candidate-images-build.sh:29,48,53` 用指定 COMMIT 标记，但 docker build 使用当前目录 | 任意 `--commit` 并不保证构建该提交；未来集成凭证必须绑定真实干净树，不能直接相信标签 | +| F14 | `internal/server/handlers.go:28–40,89–155` 提供 ready/schema，Version 固定为 v1.0 | `/ready` 可以检查就绪，但不能单独证明当前运行精确提交；需镜像标识、挂载和配置摘要关联 | +| F15 | `.github/workflows/ci.yml` 已有 Go/迁移/PG/前端/架构门禁；nightly 与 promotion receipt 也已存在 | 应复用已存在的检查与凭证，补本地准入和集成关联，不另起一套相互矛盾标准 | + +## 运行态核查 + +- dev app/events/PI/PG 均显示 healthy；本轮只查询状态，没有变更容器。 +- `GET :8080/ready`：`status=ok`、`env=dev`、`agent_backend=pi-agent`、schema=60，database/schema/task_store ready。 +- app 挂载主目录 `data/dev`、`.regulations`；PI 挂载主目录 `data/dev/workspaces`、`agent_sessions` 和四组源码路径。 +- app/events 镜像 ID 不同；本轮未调查构建历史，不能仅据此认定异常。这说明未来需要逐组件记录运行身份。 +- 未读取 `.env` 内容、用户会话正文或生产数据；未验证远端分支保护与 CI 当前执行结果。 + +## 官方机制核验 + +1. [Git worktree](https://git-scm.com/docs/git-worktree)：linked worktree 有独立 HEAD/index，但共享仓库资源；创建必须显式选择起点。`worktree lock` 用于防移动、删除和修剪，不是开发互斥锁。 +2. [Git hooks](https://git-scm.com/docs/githooks)：hooks 作用于 Git 生命周期，不能拦截编辑器普通写文件。客户端 hook 是防误操作层，不能当作 OS 权限隔离。 +3. [Docker Compose project name](https://docs.docker.com/compose/how-tos/project-name/)：project name 有多级优先级；结合本仓显式容器/卷/网络/端口配置，判断不能只换目录或加 `-p` 就宣称完全隔离。 + +## 建议 + +详见 [治理方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)。最先修正创建起点与强制删除，再落机器协调/服务守卫，最后试点候选集成和可靠部署。旧 worktree 按所有者和证据逐个处理，禁止一键清空。 diff --git a/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md new file mode 100644 index 00000000..4b93c7e1 --- /dev/null +++ b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md @@ -0,0 +1,274 @@ +--- +title: "Agent 工作规范与 worktree 并行开发治理方案" +status: planned +created: 2026-09-21 +updated: 2026-09-21 +owner: Codex +--- + +# Agent 工作规范与 worktree 并行开发治理方案 + +## 1. 建议与目标 + +采用“主目录作为 dev 集成与运行入口，所有任务在 `.worktrees/` 内开发，自动检查后进入串行集成队列”的方案。单 Agent 也遵守。一个任务对应一个分支和一个 worktree，可包含多个原子提交；不是每改一个文件就新建分支。 + +你的目标应保留，但补上五项前提： + +1. 主目录的**受版本控制文件**禁止日常直接编辑；集成更新、运行数据、受控配置和 Git 元数据需明确例外。 +2. worktree 只提供代码工作区隔离；数据库、端口、容器、共享状态须单独治理。 +3. “测过”必须对应确切提交和环境；排队后 dev 前进，旧测试不能直接代替新组合的验证。 +4. “合入”“部署成功”“业务验收通过”“已清理”“已推送”是不同事实，分别记录。 +5. 普通文档不改变运行内容，无需每次重建 dev；部署范围应按实际差异判定。 + +本次是待审核方案，未修改生效规则或脚本，未授权迁移既有任务、服务重建、批量清理及 test/main 晋升。 + +现状依据：[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md)。目标是降低误改和并行竞争，不重建个人工程中控台，不为每项任务默认起全套环境。 + +## 2. 方案比较 + +| 方案 | 优点 | 局限 | 选择 | +|---|---|---|---| +| 只改 AGENTS，要求自觉使用 worktree | 最少改动 | 当前脚本仍能从错误分支开工、强删、竞争服务 | 不足以满足可靠性 | +| 主目录固定 dev + 强制任务 worktree + 本机协调器 + 单集成队列 | 延续现有目录、三环境、脚本体系；适合当前单机多 Agent | 需少量脚本及状态治理；同 UID 仍可绕过规则 | **首选，分阶段落地** | +| bare 仓库 + 全部 linked worktree + 独立部署目录 | 仓库与运行目录边界更整齐 | 需迁移 IDE、挂载、配置和运维；仍不能解决共享环境竞争 | 当前不迁移；未来运行目录脱离时再评估 | +| 每任务独立 clone + 全套容器/DB | 隔离更强，可并行运行 E2E | 磁盘、内存、端口、凭证和数据治理成本高 | 高风险任务按需使用，不作默认 | +| 远端 PR/merge queue + CI 部署 | 适合跨机器协作和权限强约束 | 需要远端权限、runner、制品和部署能力建设 | 后续阶段；不把本地状态文件当分布式锁 | + +## 3. 目录与权限边界 + +```text +Agent-System/ 主工作区；迁移后固定检出 dev + AGENTS.md / PROJECT.md 集成更新，禁止日常手工改写 + internal/ web/ scripts/ ... 同上 + .env / configs/.env.* 受控运维配置；不复制给每个任务 + data/ .regulations/ 服务运行数据，非开发素材 + .git/agent-control/ 拟新增本机协调状态，不提交 Git + .worktrees/ + / 任务分支工作区 + / 临时集成候选；也属于受控 worktree +``` + +统一目录名 `.worktrees`，不同时引入 `.worktree`。目录用任务 ID，分支用 `feature/` / `fix/`，通过登记映射关联，不用有歧义的字符串替换推算路径。 + +| 对象 | 开发 Agent | 集成执行者 | 运维/服务进程 | +|---|---|---|---| +| 主目录跟踪文件 | 只读 | 只允许受控 Git 快进更新；冲突回任务区解决 | 只读 | +| 自己的任务 worktree | 范围内读写 | 读、建候选；不得混入其他任务未提交文件 | 无默认权限 | +| 其他任务 worktree | 授权范围内只读 | 审查与协调 | 无 | +| 主目录 `.env`、环境覆盖文件 | 默认不读写、不复制；使用注入的任务所需配置 | 部署时受控读取 | 独立运维任务授权后可改 | +| `data/dev` 等业务数据 | 通过受控 API 和测试身份验收，禁止直接编辑 | 维护窗口内受控操作 | 服务正常读写 | +| 共享 `.git` 与协调状态 | 通过统一入口使用 | 通过统一入口使用 | 不对业务容器暴露 | + +“主目录只读”不是 `chmod -R a-w`：后者会连带 `.git`、`.worktrees` 和数据，破坏正常运行。第一阶段采用规则+守卫防误操作；强约束阶段使用独立用户/沙箱，只给任务目录写权限，由受限管理入口代办共享 Git 和部署操作。不可宣称同 UID、可任意执行 shell 且可写共同 Git 目录时绝对不能改主仓。 + +受控例外必须登记 task、owner、目标路径、原因、时效、验证和恢复办法。运维配置修改不等于开发例外；业务修复包括紧急修复仍走任务 worktree，可加急队列。若需破坏性数据操作或扩大授权，另行确认。 + +## 4. 角色与任务契约 + +角色按职责划分，不绑定特定模型： + +- **协调者**：明确授权范围、拆任务、依赖和写范围、安排验收与资源预算。 +- **实现者**：在唯一任务 worktree 内编码、测试和记录，提交冻结版本。 +- **审查者**：审查冻结 SHA；只读评审，可并行；任何修复回实现者并使旧准入失效。 +- **集成执行者**：唯一持有 dev 集成及部署租约，验证候选、合入、部署、恢复和收据。 + +同一 Agent 可分时兼任；涉及鉴权、迁移、秘密配置或发布关键点，安排独立审查。增加 Agent 数量不能取代职责边界。Herdr 是可选的执行终端，核心入口也供普通 CLI/IDE 使用；不依赖 Herdr 是否在线。 + +任务最少记录：`task_id`、授权范围、owner/运行实例、branch、worktree、base_dev_sha、依赖、允许写路径、mutex 集合、验证计划、风险、提交 SHA、准入/部署/清理结果、证据路径。初始模型仅建议 2–3 个并行写任务；根据内存、CPU、排队耗时调整，集成始终 1 个。 + +任务状态继续使用现有 `planned/in_progress/blocked/done/cancelled`；另用 operation phase 表达 `developing/validating/queued/candidate_testing/merging/deploying/accepting/cleanup_pending/closed/failed`。不要把 phase 塞进旧文档 status。 + +## 5. 机器协调状态与并行边界 + +### 5.1 CURRENT 不再承担实时互斥 + +当前每个 worktree 的 CURRENT 都是不同 Git 快照，不能原子认领。拟在 `git rev-parse --path-format=absolute --git-common-dir` 对应目录下建立 `agent-control/`： + +- `tasks/.json`：单任务当前状态；包含 generation、owner、base/head SHA、paths、mutex、更新时间、证据。 +- `queue/`：待集成请求；以 task+head SHA 去重，FIFO 为默认，可审计加急。 +- `locks/`：注册表短事务锁、dev 集成锁、共享环境验收锁。 +- `operations/`：每次集成的阶段记录和恢复信息；记录原 dev、候选、运行镜像身份。 +- `runtime/dev.json`：当前实际部署版本及验收状态；不能由文档 done 推导。 + +单机本地文件系统使用 `flock` 与原子 rename；注册任务、路径占用与 mutex 检查在同一短事务内完成。资源集合一次性校验并原子取得，禁止先占一个 mutex 再等另一个造成死锁。集成父进程持有 fd 锁贯穿 Git 更新和部署；子进程生命周期纳入管理。 + +心跳过期只标记 suspect，不能据此强抢：先检查 owner 进程、子进程、Git 操作、容器活动，再进入恢复。崩溃可释放 OS 锁，但未完成 operation 仍阻止新集成，直到恢复者核实。`git worktree lock` 不是此处的互斥实现。 + +此注册表只做本机实时协调，不包含秘密、不作为历史证据唯一存储。稳定任务文与收据落在 `.doc`；CURRENT 由集成执行者在任务/文档分支生成或合并摘要，带 snapshot 时间。Agent 启动先查机器状态再读 CURRENT。主目录无需为每个任务直接修改 Markdown。跨主机时升级中央服务或远端队列，不共享本机 flock 文件伪装分布式协调。 + +### 5.2 开发冲突与资源冲突分别处理 + +- 不同模块、不同写路径可以并行；同文件原则上单写者，扩大范围需重新登记。 +- 模块 mutex 是默认边界；稳定接口下的大模块可拆细，如 `web:chat`、`web:admin`，仍对共享路由/DTO/全局状态文件单独排他。 +- 迁移号由协调器短事务预留，候选阶段再次扫描重复和顺序；已在共享环境应用的迁移禁止改名重写。两个任务各自取“最大号+1”不是安全分配。 +- `go.mod/go.sum`、前端 lockfile、数据库迁移、顶层路由等公共热点集中认领；不为“提高并行”默认允许多人改同一热点。 +- CURRENT、FEATURE-MATRIX 的各任务变更意图写到本任务文，集成时串行汇总；不要每个分支都重写整张表。 +- PG 测试使用独立测试数据库/角色，必要时独立实例，独立端口及工作目录；不把业务 dev/test/main 库当测试沙盒。 +- 编码和本地测试不占 dev 部署锁；共享 dev 的写入验收单独申请环境租约并使用专属测试项目，禁止污染真实用户会话。 +- 依赖任务先合入 dev，再从新 dev 开下游分支；等待时做只读研究。默认不从 feature 派生另一功能分支，也不整支拉入未完成旁支。 +- 编译/浏览器/真实 PI 按资源预算调度；Go/npm 下载缓存可复用，每个 worktree 的 node_modules、dist、测试输出独立，不能共享可变目录。 + +## 6. 开发、集成、部署闭环 + +```mermaid +flowchart LR + A[任务授权与范围登记] --> B[从明确 dev SHA 创建 worktree] + B --> C[并行开发与本地测试] + C --> D[冻结提交与审查] + D --> E[进入集成队列] + E --> F[构造并验证合并候选] + F --> G{dev 基线仍匹配} + G -- 否 --> F + G -- 是 --> H[受控推进 dev] + H --> I{影响运行内容} + I -- 是 --> J[构建或应用确定制品] + J --> K[就绪与相关业务验收] + I -- 否 --> L[记录无需部署] + K --> M[证据归档与安全清理] + L --> M +``` + +### 6.1 开工：从明确 dev 创建，不切换共享主目录 + +1. 校验任务 ID、分支名、路径、授权范围、mutex 和已有任务。仅接受预期仓库身份；拒绝 symlink 越界、嵌套 worktree、路径冲突和分支占用。 +2. 主目录定位以 Git common-dir + 已登记主工作区为依据，不从当前脚本的父目录猜。核查 `git worktree list --porcelain`，拒绝用户目录同名但不同仓库的假路径。 +3. dev 同步由协调者串行进行；开发 Agent 不执行共享目录 `checkout dev && pull`。远端可访问时 fetch 后判定领先/落后/分叉；可快进时按同步协议处理；分叉或有现场改动则停止自动同步并保留现场。离线可按明示策略使用本地 dev SHA，记录来源新鲜度。 +4. 创建使用已解析 `base_dev_sha`，核心语义为 `git worktree add -b `；确保 branch 的初始提交就是该 dev 快照。 +5. 登记 branch/path/base SHA 后再发写任务；创建中断可按 task_id 幂等恢复。主目录即使有旧任务残留也不能偷偷 stash/reset；迁移期间本地只读研究可显式使用 dev 创建隔离文档任务。 +6. 不复制主目录 `.env`、`data`、浏览器登录态；依赖安装和测试配置留在自己的 worktree。 + +### 6.2 开发与准入 + +实现者提交原子变更；每个任务可有多次 commit。准入前固定 `head_sha`，检查实际变更是否超出 paths/mutex，运行相应门禁并审查。测试结果必须记录 commit、命令、退出码、工具/配置版本、时间和真实/stub/skip 分类。head 改变立即使旧准入失效。 + +| 变更范围 | 基本准入 | 额外检查 | +|---|---|---| +| 普通 `.doc` 文档 | diff/链接/状态一致性 | 不需要 Go/PI/容器重建 | +| Go / API | `go vet ./...`、`go test -short ./...`、现有架构检查 | 涉及 PG/鉴权用真实独立 PG 对应测试 | +| web | `npm ci`、`npm test`、`npm run build` | 受影响交互以真实浏览器验收 | +| 迁移/数据契约 | migration gate + 空库/已有库升级验证 | 并发编号、兼容旧应用、备份恢复证据 | +| Agent/工作流/文档生成 | 对应单测、PG/接口检查 | 产品 PI Runner 与浏览器真实链路；stub 不作为最终验收 | +| 治理脚本/规则 | 临时测试仓库中的错误起点、并发锁、清理拒绝、故障恢复等 | 用受控两任务试点证明闭环；无业务改动不为形式强跑产品 PI | + +规则/CI/Dockerfile/模板/提示词不按文件扩展名草率归入“普通文档”。尤其 `templates/**/*.md`、`configs/**/*.md` 可能属于运行制品。 + +### 6.3 合并候选：测试什么，最终就合入什么 + +建议引入临时 `feature/integrate-`，在 `.worktrees/` 从锁定 dev SHA `D` 创建，再 `merge --no-ff` 冻结任务提交 `T` 得到候选 `M`。冲突由任务所有者在任务 worktree 解决，并重新提交/测试/排队；集成执行者不临场改业务逻辑。 + +在候选 `M` 上执行组合门禁。成功后获取/校验 dev 集成锁，确认主目录为干净 dev、dev 仍为 `D`，任务仍冻结为 `T`，然后将 dev **仅快进到已验证的 `M`**。这样 dev 的历史仍保留 no-ff 合并节点，同时避免验证一个合并结果、再生成另一个未验证结果。 + +这需要明确修订现行“只能在主目录执行 merge --no-ff”的字面约定：no-ff 合并节点在候选区生成，主目录只接收验证后的节点。不要用直接 update-ref 绕过主目录工作树同步。 + +候选测试可在集成锁外进行，减少排队，但推进 dev 前必须 compare-and-check 原基线；dev 已变化则重建候选并重跑受影响验证。第一版仅一个集成执行者，不引入复杂投机合并队列。 + +### 6.4 dev 更新与验收 + +1. 取得部署/环境租约；共享 dev 存在尚未结束的真实任务或验收时排队，不默认杀任务。必要维护窗口先按已授权方式暂停新任务并等待结束。 +2. 记录旧运行 app/events/PI 镜像身份、目标 M、配置安全摘要和 schema；构建必须读取干净 M，不接受任意 `--commit` 给另一份目录内容贴标签。 +3. 第一版复用 `env-service.sh dev rebuild`，补 preflight、超时、失败状态、精确源身份及结果检查；`restart` 不能代替新代码构建。候选镜像脚本必须先修“标签 SHA 与构建树不一致”的风险，才可用于无重建应用同一制品。 +4. 核验 app `/health` 和 `/ready`、events 就绪、PI 连通性、实际镜像/挂载与目标匹配、预期 schema；然后执行变化相关真实业务和浏览器检查。当前固定 v1.0 不能证明提交版本，拟加 build metadata/镜像 revision label 并写部署收据。 +5. 建议将 dev PI 源码 bind mount 退出默认部署配置，运行源码随镜像；调试挂载只作显式临时 profile，有 owner、租约、过期时间和恢复动作。切换前应确认现存热补丁已归入源码与镜像。 +6. 将 `dev_merged_sha` 与 `runtime_deployed_sha` 分开。普通文档合入可记录 `deployment=not_required`；后续分类比较必须覆盖“当前实际运行版本→新 dev”的累计差异，不能只看最后一次 commit 漏掉先前未部署代码。 +7. 共享 dev 的长 E2E **持有环境租约直到结束**；仅当验收已转到独立固定环境且证据绑定身份后，才能释放共享环境继续部署。 +8. 发布收据记录 candidate/head/merge/runtime SHA、组件 image IDs/digests、schema、测试结果和恢复信息。秘密配置仅记录字段状态或受保护版本号，不记录值。 + +原始操作收据先写本机协调区，完成后导出 `.doc/test-reports/`。部署后的报告以普通文档分支从最新 dev 产生并串行合入，跳过重建；避免为了给报告写入新 SHA 而形成无止境的“提交→重建→再提交报告”。稳定的执行 operation_id 关联最初制品。 + +## 7. 失败恢复 + +| 故障 | 必须行为 | 禁止行为 | +|---|---|---| +| 创建中断/同 ID 重试 | 查 registry、branch、Git worktree 元数据，恢复同一任务或明确冲突 | 新建第二个写者覆盖原任务 | +| 合并冲突/候选门禁失败 | 保留候选证据，退回原任务修复 | 在主目录直接改业务代码、伪造 PASS | +| dev 已前进 | 旧候选过期，重新组合与验证 | 强推/重置 dev 到旧基线 | +| dev 已合入、构建失败 | 记录 merged-but-not-deployed；阻断后续集成，保留旧运行环境，修复后继续 | 宣称 done 或删除任务 worktree | +| 部署成功但 ready/业务失败 | 标 failed；按预先检查的兼容性恢复旧镜像或修复前滚；恢复后再开放队列 | 仅看容器 Up 就放行 | +| 迁移已应用 | 优先兼容性前滚；回退应用需证明新 schema 兼容 | 自动 Down、删库、restore 覆盖真实新增数据 | +| Agent/集成进程崩溃 | 查 operation 阶段、实际 dev/runtime 和子进程；恢复者记录接管 | 超时直接抢锁并再部署 | +| Docker/网络超时 | 区分未知结果与明确未执行；先查容器状态再决定重试 | 因超时重复应用有副作用动作 | +| 清理失败 | 标 cleanup_pending，可重试，不影响已通过的部署事实 | 用 --force 掩盖路径/权限/dirty 错误 | + +需要回退已合入代码时，从最新 dev 创建 `fix/*`，形成显式 revert/修复提交并走同一队列；不硬重置 dev。DB 不兼容时先恢复服务能力或保留故障窗口，不能自动假定“换旧镜像”安全。 + +## 8. 完成与安全清理 + +开发实现完成可进入 validating/queued；只有合入、所需部署/验收、文档证据满足后才算任务 done。清理结果作为独立状态，便于磁盘维护。 + +自动清理需全部满足： + +- 注册路径与 `git worktree list --porcelain` 的实际分支一致，路径严格位于主目录 `.worktrees` 且无 symlink 越界。 +- 冻结 task head 已通过 `git merge-base --is-ancestor dev`，未出现排队后的新提交。 +- 所需部署/验收通过或明确 not_required，报告和 handoff 已持久化，旧运行恢复信息可追溯。 +- tracked/untracked 文件均检查；ignored 文件也盘点，只有预先约定的可再生缓存可删除。唯一日志、截图、报告、未提交草稿先迁入证据区。 +- Agent 和相关写进程已退出；不再是有效 cwd，无依赖任务正在使用目录；清理器从管理目录运行。 +- 无未完成 merge/rebase、无未解决锁、无“不整支合并/不删除”的历史保护标记。 + +使用普通 `git worktree remove`；分支删除在明确祖先检查后用非强制 `git branch -d`，拒绝时报告并保留，绝不回退到 `-D`。`prune` 仅清理已失效的 Git 元数据，不等于删除工作成果；禁止 `rm -rf .worktrees/*`。 + +push 与本地完成分开：用户未要求时不自动 push；已要求时必须成功并验证对应远端引用后才关闭同步项。没有 push 的合入仍需明确报告本地状态。清理只移除已安全保存的任务目录，不清理 `data`、共享卷或其他 Agent 目录。 + +旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。本次研究 worktree 也因方案尚待审核而保留。 + +## 9. 规则与工具落点（拟实现） + +以下是后续能力要求，不是现在已经可调用的新命令。 + +| 落点 | 变更要求 | +|---|---| +| `AGENTS.md` §2/3/6/8，`PROJECT.md`，`.cursor/rules/git-workflow-and-environments.mdc` | 去掉单 Agent 主目录开发例外；明示候选合并、主目录受控更新、运维例外、执行权限边界 | +| 各客户端薄入口与 roster | 保留一个规范来源；按 task_id 建实例名；校验任务与 linked worktree 身份；重投不扩授权 | +| `scripts/agent-worktree.sh` | 显式 dev SHA；唯一主仓定位；路径和分支校验；安全 remove；可恢复创建；list/doctor | +| 拟新增任务/集成管理入口及公共 guard | 原子认领、队列、短事务锁、operation 日志、候选测试、dev/部署串行、状态恢复；尽量共享一份校验逻辑 | +| `scripts/env-service.sh` | dev 写操作必须主目录/dev/有效集成租约；test/main/shared 按各自运维或晋升授权与锁校验，不能借 dev 任务操作 all；只读操作无隐式初始化；独立隔离验证环境走专用入口 | +| `scripts/candidate-images-build.sh` 等制品入口 | 构建树与 SHA 严格关联、干净树校验、标签/收据对应制品；不能只检查传入 SHA 存在 | +| `.dockerignore` | 排除 `.worktrees/`、已知 IDE worktree/cache、协调状态和测试输出；验证模板/配置必须仍被打包 | +| `docker-compose.dev.yml` / Dockerfile | 默认撤出运行源码 bind mount、显式稳定运行数据路径、增加构建身份；保留受控调试 profile | +| Git hooks / CI | 阻止主目录/主干直接开发提交和错误任务路径；测试/迁移/架构门禁；hooks 可绕过，远端保护另行配置 | +| `.doc/ops/templates/*` / CURRENT / FEATURE-MATRIX | task_id、base/head/runtime 身份、权限范围、阶段收据；CURRENT 成为快照，模块状态据实际验收更新 | + +脚本入口可提供 `create/doctor/claim/validate/submit/status/integrate/cleanup` 语义；具体组合成几个文件由实现决定。不要把核心约束散落于每种模型提示词。 + +## 10. 分阶段落地 + +| 阶段 | 负责人职责 | 交付 | 进入下一阶段的条件 | +|---|---|---|---| +| W0 现场迁移准备 | 协调者 + 现有任务所有者 | 清点主目录改动、所有 worktree、运行挂载、旧保护项；确定切换窗口 | 原任务保存并由 owner 交接；主目录可安全回 dev；无强 stash/reset | +| W1 基础防护 | 实现者 + 审查者 | 创建/安全清理修正、主目录规则、身份 doctor、构建忽略 | 临时仓库负例通过；旧目录仅盘点；新增写任务全部走 worktree | +| W2 实时协调 | 实现者 + 集成者 | 注册表、原子 mutex/路径认领、队列、服务 guard、生命周期与恢复 | 同时申请同资源仅一个成功；非持有者服务写操作被拒；崩溃可恢复 | +| W3 合并部署闭环 | 集成者 + 验收者 | 固定候选验证、dev 推进、制品身份、ready/业务验收、PI 镜像交付 | 两个并行任务串行交付，运行身份一致，失败恢复证据齐全 | +| W4 收口与持续维护 | 协调者 | 证据归档、安全自动清理、统一薄入口、文档投影 | 清理拒绝危险状态；遗留任务有明确 owner/保留原因 | +| W5 按需增强 | 平台维护者 | OS 权限隔离、临时预览环境、跨机远端队列 | 由实际瓶颈与绕过风险触发，不预先铺开全套平台 | + +W1/W2 是最小可用安全闭环，W3/W4 达到用户完整目标。不要在 W1 仅改文案后宣称治理已完成。实施任务分别从当时 dev 创建，互斥范围以具体文件/资源登记；治理脚本共用处串行。 + +## 11. 验收清单 + +以下为未来实施验收，均未在本次研究中执行： + +1. 主目录处在另一任务分支时，create 仍严格从指定 dev 创建；从任意子目录调用不会生成嵌套 worktree。 +2. 两个不同写范围任务可同时运行；同 mutex/热点路径同时申请只有一个成功，另一个有清楚排队原因。 +3. 未登记、路径越界、分支不符、主目录直写/提交被相应入口拒绝；另验证并诚实记录 OS 隔离启用前的绕过边界。 +4. feature/fix worktree 运行共享服务 start/stop/restart/rebuild/down 全部被 guard 拒绝；status/logs 不生成 env/data。 +5. 源码/文档/制品中不出现任务复制的秘密，构建上下文不含其他 worktree；模板 Markdown 正常进入镜像。 +6. 任务 A/B 从同一个 dev 起步；A 合入后 B 旧候选必须失效或重新组合验证，不可复用旧 PASS 直接推进。 +7. 合并冲突在任务区解决；主目录保持干净 dev，未夹带其他未提交修改。 +8. 指定错误 `--commit` 构建被拒绝；候选 SHA、运行组件 image ID、schema、验收收据可互相核对。 +9. 模拟构建失败、部署失败、ready 失败、迁移不兼容、进程崩溃和超时；均可按 operation 恢复，不冒充 done。 +10. 共享 dev 长 E2E 期间第二个部署排队；验收使用独立测试数据且不污染真实用户项目。 +11. 未合并、dirty、存在唯一 ignored 证据、分支/目录不符、Agent 存活、保护任务全部拒绝清理；完成任务可普通 remove。 +12. 普通文档合入记录 not_required，不重建；模板/提示词/运行配置变化正确触发运行验证。 +13. push 未授权时不发生；授权同步时验证目标远端引用，不以本地 origin 缓存冒充实时结果。 +14. 用两个隔离任务完成“认领→实现→审查→排队→候选→合入→部署→真实验收→证据→清理”的现场演练。 + +成功指标：新任务在主目录直接开发次数为 0；共享服务并发变更为 0；每次交付有可追溯收据；不产生强制删除；结束任务无无主 worktree。再收集候选重跑率、集成等待时间、构建时间和残留目录数，决定是否值得增加独立预览环境。 + +## 12. 审核建议与待实施边界 + +建议批准 W0–W4 作为整体方向，先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。 + +最值得审核的是两个策略：是否接受主目录只接收已测试合并节点的快进更新，以及是否将 dev PI 源码热挂载改为镜像交付。两者均推荐；实施前需接续现有主目录任务并核查热补丁，不能直接迁移现场。 + +尚未验证：远端分支保护、实际远端最新 dev、主机可承载的最佳并行数、每个客户端的沙箱边界。它们不阻碍本地方案成立，但不得据此承诺绝对禁止所有绕过或无限并行。 + +本方案自检已覆盖：worktree 隔离边界、机器锁与文档快照、精确候选测试、运行绑定、长 E2E 租约、数据库恢复、证据提交循环、安全清理及现存任务迁移。实施后仍需用 §11 的实际证据验收。 diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index 4ccb981f..5f9cb682 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -49,6 +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` | | 意图识别 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` | From 048bbe4a5e2fd6ae0093664a2041a7533ea39fdf Mon Sep 17 00:00:00 2001 From: weichen Date: Mon, 21 Sep 2026 08:08:14 +0000 Subject: [PATCH 2/2] docs(workflow): require isolated worktrees for all new agent changes Adopt the approved workflow with explicit dev baselines, serialized candidate integration, scoped validation and safe cleanup. Keep automation work tracked separately from the active policy. --- .../rules/git-workflow-and-environments.mdc | 3 +- .doc/README.md | 1 + .doc/ops/2026-09-13-herdr-agent-roster.md | 4 +- .../ops/2026-09-21-agent-worktree-workflow.md | 85 +++++++++++++++ .doc/ops/CURRENT.md | 6 +- ...26-09-21-agent-workflow-governance-plan.md | 14 +-- ...21-agent-workflow-governance-automation.md | 28 +++++ ...9-21-agent-workflow-governance-adoption.md | 36 +++++++ .doc/ops/templates/session-close-checklist.md | 6 +- .doc/ops/templates/short-term-task.md | 7 +- ...26-09-21-agent-workflow-governance-plan.md | 12 ++- .doc/status/FEATURE-MATRIX.md | 2 +- AGENTS.md | 101 ++++++------------ PROJECT.md | 6 +- 14 files changed, 220 insertions(+), 91 deletions(-) create mode 100644 .doc/ops/2026-09-21-agent-worktree-workflow.md create mode 100644 .doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md create mode 100644 .doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md 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）