6.4 KiB
6.4 KiB
title, created, status, confidence
| title | created | status | confidence |
|---|---|---|---|
| Agent worktree 与并行协作机制核查 | 2026-09-21 | done | 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 当前执行结果。
官方机制核验
- Git worktree：linked worktree 有独立 HEAD/index，但共享仓库资源；创建必须显式选择起点。
worktree lock用于防移动、删除和修剪，不是开发互斥锁。 - Git hooks：hooks 作用于 Git 生命周期，不能拦截编辑器普通写文件。客户端 hook 是防误操作层，不能当作 OS 权限隔离。
- Docker Compose project name：project name 有多级优先级；结合本仓显式容器/卷/网络/端口配置，判断不能只换目录或加
-p就宣称完全隔离。
建议
详见 治理方案。最先修正创建起点与强制删除，再落机器协调/服务守卫，最后试点候选集成和可靠部署。旧 worktree 按所有者和证据逐个处理，禁止一键清空。