notes-web Agent 协作协议（示例，项目覆盖层）

本项目基于 ack v0.18.0。通用规范由 /ack 从 Skill 自身的 references/ 读取，本文件只填项目差异。覆盖层文件放在 docs/ack/project.md，不占用 AGENTS.md。 ACK 不会自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。 docs/ack/ 只保存 project.md、tasks.yaml、knowledge.yaml 与 delivery.yaml。

项目概览

项目：notes-web
技术栈：TypeScript + React (Vite) + Go
运行命令：npm run dev（前端）、go run ./server（后端）
Base URL：http://localhost:5173
任务板：docs/ack/tasks.yaml
项目知识：docs/ack/knowledge.yaml
交付契约：docs/ack/delivery.yaml
覆盖层文件：docs/ack/project.md

稳定规范（引用，不重复）

开始一个需求（启动手册）：references/kickoff.md
角色 / 权限 / 状态机 / 完成定义：references/roles-and-permissions.md
模型档位与升级规则：references/model-routing.md
闭环流程（含手动模式、worktree 对齐）：references/closed-loop.md
优化方法（验收信号、三轮策略）：references/optimization-method.md
派发 prompt 模板：references/prompt-templates.md
Orca 编排命令：references/orca-adapter.md
验证后交付：references/delivery.md

Worker 路由

结构化配置位于 docs/ack/tasks.yaml 的 project.orchestration，启动记录位于顶层 workerReceipts。本项目默认使用：

角色	profile ID	档位
Developer	`codex-dev-standard`	standard
Test	`codex-test-standard`	standard
Developer 升级	`codex-dev-strong`	strong

项目如改用 Cursor 或 Grok，应修改结构化 profile、allowlist 和 defaults，再运行任务板校验。本文件不保存或拼接 worker shell 命令。

路径权限

路径	Coordinator	Test	Developer	说明
`docs/spec/**`	R/W	Read-only	Read-only	产品规格（PM 拥有）
`tests/browser/**`	Read-only	R/W	Read-only	浏览器回归用例（Test 拥有）
`.qa-records/**`	Read-only	R/W	Read-only	复测记录（gitignore）
`web/`、`server/`	Read-only	Read-only	R/W	应用源码
`*/_test.go`、`web/*/.test.tsx`	Read-only	Read-only	R/W	单元测试
`config/.example.`	Read-only	Read-only	R/W	可提交配置模板
`.env`、`config/local.*`	Read-only	Read-only	Read-only	本地私有配置
`tasks.yaml`	R/W	Read-only	Read-only	只有 Coordinator 写
`knowledge.yaml`	R/W	Read-only	Read-only	只有 Coordinator 写；Developer/Test 通过回报提名或验证
`delivery.yaml`	仅显式维护时 R/W	Read-only	Read-only	项目交付能力，不是执行授权

命令

Developer 白盒验证：

npm run build
go test ./...
npm run dev   # 本地起前端

Test 黑盒复测：

curl -s http://localhost:5173/api/health
curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
# 浏览器回归：tests/browser/cases/*.md

项目已审查的知识检查入口保存在 knowledge.yaml.verificationRegistry，格式为检查 ID 对应仓库内相对 path 和结构化 args。知识正文不保存或自动执行自由 shell 命令。执行时只把检查 ID 交给 Skill 的 scripts/run_verification.py，不直接拼接 path/args。项目状态校验由 /ack 使用 Skill 自带的 scripts/validate_tasks.py、 scripts/validate_knowledge.py 和 scripts/validate_delivery.py 执行。交付机器入口以 delivery.yaml 为准，本覆盖层不维护第二套发布或部署命令。

硬规则（其余见 references/）

三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 references/model-routing.md）。
自动 worker 只通过 ACK 的 scripts/launch_worker.py 启动；不直接执行自由 orca --command。v0.10 的自动 profile 只允许 read-only 或 workspace-write，不允许 full-access、bypass、YOLO/force 或关闭 sandbox。
每次自动派发都先审阅 plan，再用 --expected-launch-fingerprint 启动 fresh worker；持久化 receipt 只作审计。仅同轮空闲、身份匹配并可信清理历史消息后复用；整轮结束回收 verified 任务终端，blocked/failed/leftover 终端保留且不设 TTL。
worker_done 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 verified。
只有 Coordinator 写 tasks.yaml 和 knowledge.yaml；Test 与 Developer 只读。
Coordinator 只派发按 scope 命中并显式写入 knowledgeRefs 的 active 知识； candidate 不派发，知识库不全量注入。
Developer 回报 knowledgeApplied 与 knowledgeCandidates，Test 回报 knowledgeChecks；关键约束应继续下沉到测试、lint、CI 或正式规范。
交付只在任务 verified 后运行；默认 profile 停在 validation_ready 或 review_ready。stable 发布与 production 部署保留显式 approval，配置变更只影响下一次 run。
每个任务最多派发 3 轮，仍不过标记 leftover 并继续。
不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。

5.4 KiB Raw Blame History Unescape Escape