docs(review): add risk-based read-only agent gates
Harness governance / validate (push) Has been cancelled
Harness governance / validate (push) Has been cancelled
This commit is contained in:
@@ -65,6 +65,60 @@ write_paths: # 允许修改的仓库相对路径
|
||||
- 进入评审后 Issue 使用唯一 `status/review`;PR 合并且默认分支任务文件为 `DONE` 后,Issue 才能关闭并标记 `status/done`。
|
||||
- 领取、结构化 claim 评论、过期锁回收和分支清理的完整规则见 [`../gitea-collaboration.md`](../gitea-collaboration.md)。
|
||||
|
||||
## 单任务多角色评审(风险分级)
|
||||
|
||||
多角色评审仍然只处理一个任务,不增加第二个任务所有者。dispatcher / 主 Agent 负责选择评审级别和裁决结果;只有一个 writer 持有 `claimed_by`、工作分支和仓库写权限。
|
||||
|
||||
### 评审级别
|
||||
|
||||
| `review_mode` | 适用任务 | 必需角色 |
|
||||
| --- | --- | --- |
|
||||
| `none` | 文案、链接、非敏感简单配置、无行为变化且自动校验充分 | writer |
|
||||
| `test` | 普通功能、缺陷修复、行为或测试变化 | writer + 只读测试评审 |
|
||||
| `dual` | 登录、权限、Token、隐私、资金、删除 / 迁移、公共 API / Schema、核心架构、部署、外部平台集成 | writer + 只读测试评审 + 只读安全/架构评审 |
|
||||
|
||||
项目可以提高某类任务的默认级别,但不得把高风险任务降为 `none`。评审安排写在任务文件 `## 协作约束`;启用 Gitea 时同时写入 Issue。
|
||||
|
||||
### 角色权限
|
||||
|
||||
| 角色 | 可以做 | 不可以做 |
|
||||
| --- | --- | --- |
|
||||
| writer | 修改允许路径、写测试、运行验证、提交和推送工作分支、回填执行记录 | 忽略必需评审、把自己的自测冒充独立评审 |
|
||||
| 测试评审 | 读取任务、代码、候选 diff 和验证证据;提出测试矩阵、边界场景和缺失覆盖 | 修改文件、提交 Git、更新 Gitea、在共享工作区执行会产生文件或外部状态的命令 |
|
||||
| 安全/架构评审 | 检查权限、秘密、数据风险、模块边界、公共接口、依赖和回滚 | 修改文件、提交 Git、更新 Gitea、替 writer 顺手修复 |
|
||||
| dispatcher / 主 Agent | 分配角色、汇总结论、决定 `ACCEPT` / `REVISE` / `BLOCK` | 在仍有未解决阻断或高风险发现时放行 |
|
||||
|
||||
评审角色不是任务领取者:不创建 claim、不创建工作分支、不成为 `claimed_by`。需要实际运行可能写缓存、数据库或外部系统的测试时,由 writer 执行,或使用一次性 worktree、容器 / 临时环境;“只读评审”不能只靠提示词约束。
|
||||
|
||||
### 执行顺序
|
||||
|
||||
1. dispatcher 根据任务风险确定 `review_mode`,并把角色写入 `## 协作约束`。
|
||||
2. `test` / `dual` 模式下,评审角色可在实现前只读任务规格,分别给出测试重点和风险清单;不得提前修改实现。
|
||||
3. writer 完成实现和自测,先把验证证据写入任务文件,再产生候选提交;dispatcher / PR 记录该提交为 `candidate_sha`。不要把当前提交 SHA 写回同一个提交中的任务文件,避免自引用。
|
||||
4. 必需评审角色独立读取任务规格、`context_ref`、候选提交 SHA / diff 和验证证据;不能只读 writer 的总结。
|
||||
5. 每个评审输出结构化结论。dispatcher 汇总后决定:
|
||||
- `ACCEPT`:该角色未发现阻断项;
|
||||
- `REVISE`:存在必须由 writer 修复的问题;
|
||||
- `BLOCK`:需求、架构、安全前提或验证环境存在根本阻塞。
|
||||
6. writer 修复后产生新 SHA;此前针对旧 SHA 的结论不能直接复用,至少重新评审受影响内容。
|
||||
7. 启用 PR 时,最终必需评审的 `reviewed_sha` 必须等于待合并 PR head。未启用 PR 时,`reviewed_sha` 至少覆盖最后一个代码 / 配置变更提交;其后的提交只能更新当前任务文件中的评审证据,dispatcher 必须用 `git diff <reviewed_sha>..HEAD` 确认没有实现变化。
|
||||
8. 连续两轮仍为 `BLOCK`,或平台无法提供任务要求的独立评审角色时,把任务标为 `BLOCKED` 并请求维护者 / 用户裁决;不得由 writer 冒充评审或静默降低 `review_mode`。
|
||||
|
||||
评审结果使用稳定格式:
|
||||
|
||||
```text
|
||||
REVIEW
|
||||
role: test | risk
|
||||
reviewed_sha: 【40 位提交 SHA】
|
||||
verdict: ACCEPT | REVISE | BLOCK
|
||||
findings:
|
||||
- severity: critical | high | medium | low
|
||||
evidence: 【文件、测试或行为证据】
|
||||
required_action: 【必须修复或说明的动作】
|
||||
```
|
||||
|
||||
评审 Agent 只返回报告;writer 在 `## 执行记录` 写自测、修复动作和评审链接,dispatcher 在 PR / Issue 记录精确的 `reviewed_sha` 与 verdict。若要把评审摘要复制进任务文件,必须先提交该变更,再让必需评审检查新的 PR head;评审 Agent 本身不直接写远端状态。
|
||||
|
||||
## 用户指令暗语(可选约定)
|
||||
|
||||
> 用户的工作流通常固定为:提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。
|
||||
|
||||
@@ -32,7 +32,12 @@ write_paths:
|
||||
|
||||
## 协作约束
|
||||
|
||||
(启用 Gitea 时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支;任何新增写路径先检查与其他活跃任务是否重叠。)
|
||||
- review_mode: 【none | test | dual】
|
||||
- writer: 【唯一写入 agent-id;未领取时为 null】
|
||||
- test_reviewer: 【只读测试评审 agent-id;不适用时为 null】
|
||||
- risk_reviewer: 【只读安全/架构评审 agent-id;不适用时为 null】
|
||||
|
||||
(启用 Gitea 时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支。只有 writer 可以修改和提交仓库;评审角色只读。任何新增写路径先检查与其他活跃任务是否重叠。候选 SHA 由 PR / 评审报告记录,避免任务文件自引用;分支产生任何新提交后重新评审。)
|
||||
|
||||
## 执行记录
|
||||
|
||||
|
||||
Reference in New Issue
Block a user