279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
# 本地 CCRA 评审机制说明
|
||
|
||
version: 0.4
|
||
|
||
last_updated: 2026-06-19
|
||
|
||
status: stable explanatory asset
|
||
|
||
## 1. 文档定位
|
||
|
||
本文档说明 `the-mindscape-of-bro-tsong` 项目如何使用 Local CCRA 做本地第一轮评审。
|
||
|
||
它只解释项目侧机制，不定义 `ccra-local-reviewer` Agent 本体。
|
||
|
||
Agent Spec、Runtime Spec、调用协议、会话保持机制、评审 rubric 和配套能力归属判定属于 `ccpe-system`。
|
||
|
||
## 2. 为什么需要 Local CCRA
|
||
|
||
当前项目已经有 Web CCRA / GPT 评审流程，但人工搬运成本较高。
|
||
|
||
Local CCRA 的目标是把以下工作本地化：
|
||
|
||
- 审核资料的第一轮审查；
|
||
- 轮次目标是否被偷换的检查；
|
||
- 工程通过与产品判断之间的差距识别；
|
||
- selector 规则变更后的非目标行为变化识别；
|
||
- 模型生命周期是否被过早升级的守门；
|
||
- 下一轮应修、应延后、应进入 calibration 或 regression 的建议。
|
||
|
||
Local CCRA 是正式本地初审，但不替代 Owner 或 Web CCRA 的关键节点判断。
|
||
|
||
## 3. 第一版范围
|
||
|
||
第一版只服务：
|
||
|
||
```text
|
||
C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong
|
||
```
|
||
|
||
不建立独立 reviewer 项目。
|
||
|
||
原因是当前没有跨项目评审需求。正交性来自真实子会话 / Agent Runtime 隔离，而不是来自另建目录或另建项目。
|
||
|
||
## 4. 项目侧目录
|
||
|
||
Local CCRA 运行记录放在：
|
||
|
||
```text
|
||
local_ccra_reviews/
|
||
```
|
||
|
||
路径规则：
|
||
|
||
```text
|
||
local_ccra_reviews/<public-round>/<local-pass>/
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
local_ccra_reviews/round-05_selector-calibration-policy/01/
|
||
local_ccra_reviews/round-05_selector-calibration-policy/02/
|
||
local_ccra_reviews/round-04/pilot-01/
|
||
local_ccra_reviews/round-03.2a_depth-limiting-qpi-override-patch/01/
|
||
```
|
||
|
||
`<public-round>` 跟随 Owner / Web CCRA 共同确定的公共轮次，例如 `round-05`、`round-04.1`、`round-03.2a`。
|
||
|
||
`<local-pass>` 是 Local CCRA 内部评审次数，例如 `01/`、`02/`。
|
||
|
||
## 5. 每次评审的文件
|
||
|
||
每个本地评审目录应包含：
|
||
|
||
```text
|
||
run-notes.md
|
||
review-metadata.json
|
||
gate-manifest.yaml
|
||
lifecycle-guard-config.yaml
|
||
agent-invocation-packet.md
|
||
prompt-to-send.md
|
||
turn-prompts/
|
||
review-context.md
|
||
review-file-manifest.json
|
||
helper-outputs/
|
||
04_LOCAL_CCRA_REVIEW_REPORT.md
|
||
next-review-requirements.md
|
||
returned-output.md
|
||
05_WEB_LOCAL_CCRA_COMPARISON.md
|
||
findings-confirmation.md
|
||
owner-decision.md
|
||
```
|
||
|
||
关键含义：
|
||
|
||
- `run-notes.md`：记录本轮运行、helper 命令、跳过项、dispatch 和 resume 信息。
|
||
- `review-metadata.json`：记录本轮目标、范围、非目标和开放问题。
|
||
- `agent-invocation-packet.md`：交给 CCPE Agent Runtime 的文件优先调用包。
|
||
- `prompt-to-send.md`：通过 Codex 子线程等 carrier 调用时使用的提示词。
|
||
- `turn-prompts/`：保存 `review_turn`、`planning_turn`、必要时的 `comparison_turn` 提示。
|
||
- `review-context.md` / `review-file-manifest.json`：由 `review-context-builder` 生成的文件优先上下文索引。
|
||
- `04_LOCAL_CCRA_REVIEW_REPORT.md`：`ccra-local-reviewer` 唯一判断输出。
|
||
- `next-review-requirements.md`：同一子会话第二回合产出的下一轮评审要求与提交资料规划。
|
||
- `returned-output.md`：子会话返回内容或报告路径记录。
|
||
- `05_WEB_LOCAL_CCRA_COMPARISON.md`：可选的主会话比较笔记，用于把 Local CCRA 输出与 Web CCRA / GPT 反馈对照后调优。
|
||
- `findings-confirmation.md`：主会话用中文摘录 Local CCRA findings 的核心确认事项，供 Owner 快速决策。
|
||
- `owner-decision.md`：Owner 对 findings 的接受、拒绝、延后或升级判断。
|
||
|
||
## 6. 运行流程
|
||
|
||
推荐流程：
|
||
|
||
```text
|
||
Owner 决定需要本地评审
|
||
-> Codex 创建 local_ccra_reviews/<round>/<pass>/
|
||
-> Codex 运行 review-context-builder 和适用 helper Skill
|
||
-> Codex 生成 Runtime invocation packet 和 prompt-to-send
|
||
-> Codex 调起 CCPE Agent Runtime 子会话并记录 child_session_id
|
||
-> review_turn: ccra-local-reviewer 只读评审资料并写本地评审报告
|
||
-> planning_turn: 同一 child_session_id 继续，写下一轮评审要求与提交资料规划
|
||
-> Codex 主会话写 findings-confirmation.md，提取中文核心确认事项
|
||
-> Owner 写 decision
|
||
-> Codex 根据 accepted findings 修复
|
||
-> 必要时进入下一次本地评审
|
||
-> 通过后生成正式 Web CCRA bundle
|
||
```
|
||
|
||
`ccra-local-reviewer` 只输出评审意见，不做任何项目文件调整。
|
||
|
||
当前推荐的正式使用模式是两回合：
|
||
|
||
1. `review_turn`：评审本轮资料，识别问题、机制、证据缺口、补丁范围和是否需要本地修复。
|
||
2. `planning_turn`：复用同一个 `child_session_id`，基于第一回合报告和 Owner decision，规划下一轮评审要求和应提交资料。
|
||
|
||
`planning_turn` 不应重新完整评审当前 bundle，除非 Owner 明确要求或新增证据已经进入评审目录。
|
||
|
||
运行时长与工具使用原则：
|
||
|
||
- Local CCRA 是深度文件优先评审，不是快速聊天摘要。
|
||
- 成熟运行的目标耗时可按 Web CCRA 的常见 5-10 分钟理解，具体取决于客户端和 API / runtime 配置。
|
||
- 子会话可以按需使用本地工具解压、检索、读取 manifest、运行 helper Skill，并在 Owner 或运行包允许时执行回归 / 验证命令。
|
||
- 主会话不应仅因为子会话阅读文件或运行工具持续数分钟就中断评审。
|
||
- 每次运行应在 `run-notes.md` 记录可观察耗时，便于后续区分正常深度评审和 runtime 异常。
|
||
|
||
## 7. 正式使用条件
|
||
|
||
基于 Round 04 `pilot-02` 的三方对比和 CCPE Patch 2 更新，Local CCRA v0.1.2 可以作为本项目正式本地初审使用，但带条件：
|
||
|
||
- 必须真实调起子会话，不允许主会话角色扮演。
|
||
- 必须记录并复用 `child_session_id`。
|
||
- 必须使用 `knowledge_assets/` 作为强制知识库路径。
|
||
- 默认采用 `review_turn` + `planning_turn` 两回合模式。
|
||
- helper 输出只能作为证据线索，必须标注置信度、噪声和适用范围。
|
||
- 当评审对象包含补丁或 post-patch 证据时，必须要求 before / after 行为对比。
|
||
- Local CCRA 不能替代 Owner decision、Web CCRA final review 或模型生命周期升级判断。
|
||
|
||
v0.1.2 已把 Patch 2 硬化项纳入 CCPE runtime 合同。每次运行应明确记录：
|
||
|
||
```text
|
||
bundle_audit_profile: ccra_mindscape_review_bundle | generic | not_applicable
|
||
gate_execution_mode: dry_run | run | owner_waived | not_applicable
|
||
routing_diff_policy: required | skipped_no_after_evidence | manual_equivalent_required | not_applicable
|
||
lifecycle_scan_scope: current_review_bundle | changed_files | knowledge_assets | model_library_state | whole_repo
|
||
```
|
||
|
||
这些字段通常写入 `review-metadata.json` 和 `agent-invocation-packet.md`，并在 `returned-output.md` 中摘要返回。
|
||
|
||
字段含义：
|
||
|
||
- `bundle_audit_profile`：优先使用 `ccra_mindscape_review_bundle`；若 helper 只能使用 generic profile，必须标注 profile mismatch，不能自动判定 bundle 失败。
|
||
- `gate_execution_mode`：`dry_run` 只能证明 gate 声明可读，不能支持 pass claim；真正验收需要 `run` 或 Owner 记录 `owner_waived`。
|
||
- `routing_diff_policy`：如果评审对象包含 patch 或 before / after 证据，必须有 routing diff 或手工等价表；初始无后验评审可记录为 `skipped_no_after_evidence`。
|
||
- `lifecycle_scan_scope`：whole repo 是广域审计模式，不应默认成为当前评审 blocker；发现项必须做 current-scope triage。
|
||
|
||
CCPE Patch 2 没有改变机制诊断、补丁范围判断、同子会话延续、强制知识库或权限边界，因此不需要第三次历史试运行。可以在下一次 Owner / Web CCRA 已确定目标的真实本地初审中验证 v0.1.2。
|
||
|
||
## 8. 与 Web CCRA Bundle 的关系
|
||
|
||
正式 Web CCRA / GPT 上传包仍放在：
|
||
|
||
```text
|
||
ccra_review_bundle/round-NN_YYYY-MM-DD_topic/
|
||
```
|
||
|
||
不要使用简写路径，例如：
|
||
|
||
```text
|
||
ccra_review_bundle/05/
|
||
```
|
||
|
||
正式 Web CCRA 包默认不包含：
|
||
|
||
```text
|
||
04_LOCAL_CCRA_REVIEW_REPORT.md
|
||
```
|
||
|
||
只有 Owner 明确要求 Web CCRA 复核本地评审意见时，才把本地评审报告纳入正式上传包。
|
||
|
||
## 9. 与 CCPE 和 skills-vault 的分工
|
||
|
||
`ccpe-system` 负责：
|
||
|
||
- `ccra-local-reviewer` Agent Spec；
|
||
- CCPE Agent Runtime 接口；
|
||
- 子会话创建与继续协议；
|
||
- 评审 rubric；
|
||
- 生命周期守门规则；
|
||
- 文件优先评审协议；
|
||
- 配套能力是否应转交 `skills-vault` 的判定。
|
||
|
||
`skills-vault` 只负责：
|
||
|
||
- 已经被抽象为可复用、确定性、跨项目自动化的工具；
|
||
- 例如 `bundle-zip` 这种与具体 CCRA 角色无关的通用文件处理能力。
|
||
|
||
Local CCRA 的 companion automation 不直接提交给 `skills-vault`。应先由 CCPE 判定它是 Agent 专属、Runtime 配套、项目本地 helper，还是可抽公共 Skill。
|
||
|
||
## 10. 自动化边界
|
||
|
||
Local CCRA 机制只定义本地初审的 reviewer/runtime 使用方式，不把 `ccra-local-reviewer` 变成执行者。
|
||
|
||
项目侧可以另行定义 Round Conductor 协议来减少人工搬运和重复操作。当前协议见：
|
||
|
||
```text
|
||
docs/ROUND_AUTOMATION_PROTOCOL.md
|
||
```
|
||
|
||
Round Conductor v0.1 范围：
|
||
|
||
```text
|
||
Owner/Web 确定 Round N 规划
|
||
-> Codex 创建 round charter 和 Local CCRA pass
|
||
-> Codex 准备上下文、helper 输出、调用包和提示词
|
||
-> Codex 调起真实 Local CCRA 子会话
|
||
-> Local CCRA 输出 review_turn / planning_turn
|
||
-> Codex 写 findings-confirmation.md，摘录中文核心确认事项
|
||
-> Owner 写 owner-decision.md
|
||
```
|
||
|
||
Round Conductor v0.2 范围：
|
||
|
||
```text
|
||
Owner 接受 findings
|
||
-> Codex 只处理 accept_for_codex_fix 项
|
||
-> Codex 运行验证和 before/after 行为检查
|
||
-> 必要时进入下一次本地评审 pass
|
||
-> 满足停止条件后准备正式 Web CCRA bundle
|
||
```
|
||
|
||
这仍然不是无人值守自动修复。必须保留：
|
||
|
||
- Round 目标和非目标的 Owner / Web CCRA 确认；
|
||
- findings 的 Owner decision gate；
|
||
- 生命周期升级、模型范围扩大、第三模型扩展、Web bundle 是否包含 Local CCRA report 的人工判断；
|
||
- Web CCRA 对关键产品节点的正式评审。
|
||
|
||
## 11. 非目标
|
||
|
||
Local CCRA 不做：
|
||
|
||
- Owner 最终决策；
|
||
- Web CCRA 关键节点复审替代；
|
||
- 模型生命周期升级；
|
||
- selector 规则修改；
|
||
- model card 修改；
|
||
- regression case 修改；
|
||
- review bundle 创建；
|
||
- Round Conductor 的 Owner decision 或修复授权；
|
||
- 第三模型扩展；
|
||
- LLM selector、RAG、数据库、前端、后端或平台化功能。
|
||
|
||
## 12. 结论
|
||
|
||
Local CCRA 是本项目的本地第一轮审查机制。
|
||
|
||
它的价值不是复制 Web GPT，而是把 CCRA 的审查原则本地文件化、运行时隔离化、报告归档化。
|
||
|
||
项目侧负责保存 review runs；CCPE 负责定义 reviewer 和 runtime；skills-vault 只承接被抽象后的通用自动化。
|