Files

T

weichen 048bbe4a5e 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.

2026-09-21 08:08:14 +00:00

7.6 KiB

Raw Blame History

Agent worktree 工作规范

生效日期：2026-09-21。用户已确认“提交吧，之后按这套执行”。 规范来源：AGENTS §6；完整方案。

本文件用于创建任务、集成、部署、清理时执行。工作方式立即采纳；自动注册表、队列、服务守卫、OS 权限隔离尚未实现，当前使用下面的显式校验与人工协调。代码文件隔离不等于数据库或运行环境隔离。

1. 创建任务

读取启动链，检查主目录和各任务的 git status、分支、git worktree list --porcelain 与 CURRENT/任务文。识别其他 Agent 的活跃任务，冲突范围不进入写阶段。
确认主工作区真实路径：通过 Git worktree 列表和 common-dir 核对，不根据当前脚本父目录推算。已有 .kilo 或目录/分支不匹配 worktree 仅盘点，不自动搬动或清理。
确定任务 ID、允许写路径、mutex 和验证计划；同一写范围只有一个 owner。CURRENT 在各分支内仅作快照，协调者还需交叉核对活跃任务；未实现原子注册表前不宣称已有自动原子认领。
使用显式本地 dev SHA。远端状态注明已 fetch 或仅本地跟踪快照；不因创建任务在主目录 checkout/pull，也不从 feature 派生无关任务。

在已核实的主仓路径执行以下语义；示例 task-id 须替换为本任务唯一标识：

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 槽位并保留前后基线。完整注册表、自动队列另行实施。

锁应由覆盖整个操作的父进程持有，不是一个命令拿锁后退出再执行下一条：

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. 集成候选与部署

锁定 dev 基线 D 和任务 head T；任务工作树干净且准入证据有效。
从 D 建 .worktrees/ 下的 feature/integrate-*，把 T 以 --no-ff 合成候选 M。业务冲突退回 owner 修复；集成者不在主目录改代码解冲突。
在 M 验证相应门禁。dev 仍为 D、任务仍为 T 才可在干净 dev 工作区 merge --ff-only M；变化则重建候选。dev 历史保留该 no-ff 节点，不再重做另一份未测试合并。
纯工程规范/文档标 deployment=not_required。运行内容变化则从已合入版本构建/应用确定制品，核验实际镜像、schema、/health、/ready 和相关业务链路。
当前 candidate-images-build.sh --commit 未保证构建树等于参数，修复前调用者必须确保干净树、HEAD 与参数完全一致，记录证据；不能仅凭标签声明准确版本。
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. 安全清理

清理在待删除目录外执行，依次核查：

worktree 实际路径、分支与任务登记一致；无越界/保护项；无 merge/rebase 中间状态。
git merge-base --is-ancestor <task-head> dev 成功；冻结后未新增未合入提交。
所需部署与验收通过或 not_required；报告、截图和唯一日志已归档。
检查 tracked、untracked 及 ignored 文件；只允许丢弃确认可再生的缓存，不因 git status --short 为空就认定没有证据文件。
Agent/测试进程已退出、无进程 cwd/其他任务依赖该目录。
普通 git worktree remove <path>；分支用 git branch -d <branch>。若非 dev 当前检出导致 -d 拒绝，即使祖先检查通过也保留到 dev 可用时清理，不换成 -D。

失败只标 cleanup_pending，保留数据。禁止强制删除、按年龄批量删除或把 worktree 清理扩展为 data/数据库/容器卷清理。Push 仅在用户明确要求时执行，并与本地提交/合入分开报告。

6. 执行状态

已采纳：强制任务 worktree、明确 dev 基线、主目录保护、串行集成/部署、按范围验证、条件清理。
可立即执行：本规范的原生 Git、人工范围认领、本机 flock、精确候选检查。
尚待工程实现：自动登记与排队、脚本强制 guard、安全 helper、部署身份闭环、PI 镜像交付、故障自动恢复和 OS 沙箱。见自动化实施任务。

7.6 KiB Raw Blame History Unescape Escape