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

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

模型档位

角色	默认档位	本项目实际
Coordinator (PM)	强模型	claude-sonnet-5-thinking-high
Test	中低模型	默认（中低）
Developer	中低模型	默认（中低），架构任务临时升级

路径权限

路径	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 通过回报提名或验证

命令

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 执行。

硬规则（其余见 references/）

三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 references/model-routing.md）。
worker_done 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 verified。
只有 Coordinator 写 tasks.yaml 和 knowledge.yaml；Test 与 Developer 只读。
Coordinator 只派发按 scope 命中并显式写入 knowledgeRefs 的 active 知识； candidate 不派发，知识库不全量注入。
Developer 回报 knowledgeApplied 与 knowledgeCandidates，Test 回报 knowledgeChecks；关键约束应继续下沉到测试、lint、CI 或正式规范。
每个任务最多派发 3 轮，仍不过标记 leftover 并继续。
不提交或推送，除非用户明确要求。

4.0 KiB Raw Blame History Unescape Escape