99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# Roles And Permissions
|
||
|
||
本文件定义多 Agent 协作的责任边界。目标是让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
|
||
|
||
## 角色模型
|
||
|
||
| 角色 | 主要职责 | 验证方式 | 不应做的事 |
|
||
|------|----------|----------|------------|
|
||
| Product/Test Coordinator | 需求拆解、任务记录、黑盒测试、复测验收、调度开发 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、凭 worker_done 直接标记完成 |
|
||
| Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
|
||
| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
|
||
|
||
## 路径权限模板
|
||
|
||
目标项目应在 `AGENTS.md` 中填入实际路径。
|
||
|
||
| 路径 | Product/Test | Developer | 说明 |
|
||
|------|:------------:|:---------:|------|
|
||
| `<spec_paths>` | R/W | Read-only | PRD、API spec、设计文档 |
|
||
| `<integration_test_paths>` | R/W | Read-only | 浏览器用例、API smoke、回归清单 |
|
||
| `<test_records_path>` | R/W | Read-only | 复测记录，通常可 gitignore |
|
||
| `<source_paths>` | Read-only | R/W | 应用源码 |
|
||
| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
|
||
| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
|
||
| `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
|
||
| `tasks.yaml` | R/W | Limited R/W | 任务事实源；Developer 可写实现状态和证据，Product/Test 写 verified |
|
||
|
||
## Product/Test Coordinator 工作流
|
||
|
||
1. 读取用户目标、项目规格、任务板。
|
||
2. 用黑盒方式复现问题或验证需求。
|
||
3. 在 `tasks.yaml` 写入任务：
|
||
- 复现步骤
|
||
- 预期结果
|
||
- 实际结果
|
||
- 证据
|
||
- 验收命令或验收页面
|
||
4. 创建 Orca 编排任务并派发 Developer Worker。
|
||
5. 等待 `worker_done` / `escalation` / `decision_gate`。
|
||
6. 重新构建和复测。
|
||
7. 通过则标记 `verified`；失败则追加证据并继续派发，最多三轮。
|
||
8. 三轮失败则标记为遗留项，继续下一个任务。
|
||
|
||
## Developer Worker 工作流
|
||
|
||
1. 读取 `AGENTS.md`、`tasks.yaml` 和相关规格。
|
||
2. 只修改 Developer 可写路径。
|
||
3. 做最小正确修改，避免顺手重构。
|
||
4. 为非平凡逻辑补充或更新单元测试。
|
||
5. 运行项目要求的验证命令。
|
||
6. 完成后发送一次 `worker_done`，包含：
|
||
- 修改文件
|
||
- 验证命令和结果
|
||
- 剩余风险
|
||
7. 不标记 `verified`，也不提交或推送，除非用户明确要求。
|
||
|
||
## 状态机
|
||
|
||
推荐 `tasks.yaml` 使用以下状态：
|
||
|
||
```text
|
||
open
|
||
-> dispatched
|
||
-> fixed_by_dev
|
||
-> retesting
|
||
-> verified
|
||
```
|
||
|
||
失败分支：
|
||
|
||
```text
|
||
dispatched -> blocked
|
||
fixed_by_dev -> failed_retest -> dispatched
|
||
failed_retest x3 -> leftover
|
||
```
|
||
|
||
状态定义：
|
||
|
||
| 状态 | 写入者 | 含义 |
|
||
|------|--------|------|
|
||
| `open` | Product/Test | 已发现，等待处理 |
|
||
| `dispatched` | Product/Test | 已派发给开发 Agent |
|
||
| `blocked` | Product/Test 或 Developer | 需要用户决策或外部条件 |
|
||
| `fixed_by_dev` | Developer | 开发声称已修复并提供验证 |
|
||
| `retesting` | Product/Test | 正在复测 |
|
||
| `failed_retest` | Product/Test | 复测失败，可继续派发 |
|
||
| `verified` | Product/Test | 复测通过 |
|
||
| `leftover` | Product/Test | 三轮仍未通过，留给人工或专项处理 |
|
||
|
||
## 完成定义
|
||
|
||
一个任务只有同时满足以下条件，才能标记 `verified`：
|
||
|
||
- Developer 已提供修改文件和验证证据。
|
||
- Product/Test 在正确 worktree 和正确服务实例上复测。
|
||
- 相关单元测试、构建、集成或浏览器检查通过。
|
||
- `tasks.yaml` 中记录了复测证据。
|
||
- 用户可见行为符合验收标准。
|