laily
12e00bd594
Keep pouch naming and .pouch/ack project state, and bring in ACK regression mode, deployer test-environment binding, and manage-release updates from main.
112 lines
5.7 KiB
Markdown
112 lines
5.7 KiB
Markdown
# notes-web Agent 协作协议（示例，项目覆盖层）
|
||
|
||
> 本项目基于 ack v0.19.0。
|
||
> 通用规范由 `/ack` 从 Skill 自身的 `references/` 读取，本文件只填项目差异。
|
||
> 覆盖层文件放在 `.pouch/ack/project.md`，不占用 `AGENTS.md`。
|
||
> ACK 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||
> `.pouch/ack/` 只保存 `project.md`、`tasks.yaml`、`knowledge.yaml`、`delivery.yaml`
|
||
> 与 `regression.yaml`。
|
||
|
||
## 项目概览
|
||
|
||
- 项目：`notes-web`
|
||
- 技术栈：`TypeScript + React (Vite) + Go`
|
||
- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
|
||
- Base URL：`http://localhost:5173`
|
||
- 任务板：`.pouch/ack/tasks.yaml`
|
||
- 项目知识：`.pouch/ack/knowledge.yaml`
|
||
- 交付契约：`.pouch/ack/delivery.yaml`
|
||
- 回归目录：`.pouch/ack/regression.yaml`
|
||
- 覆盖层文件：`.pouch/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`
|
||
- 回归目录与运行：`references/regression.md`
|
||
|
||
## Worker 路由
|
||
|
||
结构化配置位于 `.pouch/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 通过回报提名或验证 |
|
||
| `regression.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Test 通过 regressionCandidates 提名 |
|
||
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |
|
||
|
||
## 命令
|
||
|
||
Developer 白盒验证：
|
||
|
||
```bash
|
||
npm run build
|
||
go test ./...
|
||
npm run dev # 本地起前端
|
||
```
|
||
|
||
Test 黑盒复测：
|
||
|
||
```bash
|
||
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` 和
|
||
`scripts/validate_regression.py` 执行。
|
||
测试环境由 ACK 内部调用 deployer；发版机器入口以 `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 明确包含。
|