80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# notes-web Agent 协作协议（示例，项目覆盖层）
|
||
|
||
> 本项目基于 ack v0.8.0。
|
||
> 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。
|
||
> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
|
||
> 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。
|
||
|
||
## 项目概览
|
||
|
||
- 项目：`notes-web`
|
||
- 技术栈：`TypeScript + React (Vite) + Go`
|
||
- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
|
||
- Base URL：`http://localhost:5173`
|
||
- 任务板：`docs/ack/tasks.yaml`
|
||
- 覆盖层文件：`docs/ack/project.md`
|
||
|
||
## 稳定规范（引用，不重复）
|
||
|
||
- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md`
|
||
- 角色 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
|
||
- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
|
||
- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
|
||
- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
|
||
- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
|
||
- Orca 编排命令：`docs/ack/kit/core/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 写 |
|
||
|
||
## 命令
|
||
|
||
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
|
||
```
|
||
|
||
任务板校验：
|
||
|
||
```bash
|
||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||
```
|
||
|
||
## 硬规则（其余见 kit/core/）
|
||
|
||
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
|
||
- 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 kit/core/model-routing.md）。
|
||
- `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
|
||
- 只有 Coordinator 写 `tasks.yaml`；Test 与 Developer 只读。
|
||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
|
||
- 不提交或推送，除非用户明确要求。
|