pi-multi-code-review 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +91 -0
  2. package/SKILL.md +127 -0
  3. package/agents/review-runner.md +38 -0
  4. package/package.json +21 -0
  5. package/references/adjudicator-prompt.md +49 -0
  6. package/references/fallback-template.md +35 -0
  7. package/references/ocr-flow.md +57 -0
  8. package/references/schema.md +107 -0
  9. package/references/spec-template.md +36 -0
  10. package/references/standards-template.md +35 -0
package/README.md ADDED
@@ -0,0 +1,91 @@
1
+ # multi-code-review — 三方并行代码审查
2
+
3
+ 对同一个审查目标（workspace / commit / 分支改动），**三个相互独立的正交通道并行审查**，再由内置 oracle 去重消歧、跨通道重新定级，合并成**一份**带最终裁决的报告。
4
+
5
+ | 通道 | 问的问题 | 判定维度 |
6
+ |---|---|---|
7
+ | **OCR**（open-code-review 风格） | 这段代码本身对不对、安不安全？ | 正确性 bug、安全漏洞、回归、明显性能缺陷、边界条件 |
8
+ | **Standards** | 这段改动遵守仓库的文档化编码规范吗？ | AGENTS.md / CONTEXT.md / README 明示约定 / 语言惯例 |
9
+ | **Spec** | 这段改动满足它应当满足的需求吗？ | 缺实现、过度实现、契约破坏、行为与需求不符 |
10
+
11
+ 纯 Pi `workflowScript` + `runs.all` 编排，**不需要 Orca**。执行体是本包自带的 subagent `multi-code-review.review-runner`（随包自动发现）；oracle 用 pi-subagents 内置 `oracle`（只读、不联网）。
12
+
13
+ ## 安装
14
+
15
+ ```bash
16
+ # 全局
17
+ pi install npm:pi-multi-code-review
18
+
19
+ # 项目级（写入 .pi/settings.json）
20
+ pi install -l npm:pi-multi-code-review
21
+
22
+ # 本地开发（在 pi-packages 仓库内）
23
+ pi install ./skills/multi-code-review
24
+
25
+ # 卸载
26
+ pi remove npm:pi-multi-code-review
27
+ ```
28
+
29
+ **前置依赖**：`pi-subagents`（提供 `runs.all` 运行时与内置 `oracle`）：
30
+
31
+ ```bash
32
+ pi install npm:pi-subagents
33
+ ```
34
+
35
+ **可选依赖**：`ocr` CLI（open-code-review，`npm install -g @alibaba-group/open-code-review`）。存在时 OCR 通道走 delegate 模式（CLI 做文件选择与规则解析）；缺失或失败自动降级为 fallback，不影响其余通道与安装。
36
+
37
+ ## 使用
38
+
39
+ 在目标仓库内触发：
40
+
41
+ ```bash
42
+ # 审查当前 workspace 改动
43
+ 用 multi-code-review 审查这次改动
44
+
45
+ # 审查某个 commit / 某段分支
46
+ 用 multi-code-review 审查 --commit <sha>
47
+ 用 multi-code-review 审查 --branch main..feature
48
+
49
+ # 带需求上下文（喂给 Spec 通道）
50
+ 用 multi-code-review 审查 --branch main..feature -b "为登录接口加限流"
51
+ ```
52
+
53
+ 输出目录默认 `${TMPDIR:-/tmp}/multi-code-review/<时间戳>-<topic>/`（可用 `--out` 覆盖），最终报告是其中的 `00-adjudication.md`。审查期间**目标仓库零改动**：工件全部写在仓库之外，`git status` / 哈希保持不变。
54
+
55
+ ## 自动发现
56
+
57
+ `package.json` 声明 `"pi-subagents": { "agents": ["./agents"] }`，安装后 `review-runner` 自动注册为 `multi-code-review.review-runner`，无需手工复制文件：
58
+
59
+ ```bash
60
+ subagent({ action: "list", capabilities: true }) # 应能看到 multi-code-review.review-runner
61
+ ```
62
+
63
+ ## 报告
64
+
65
+ - 每个通道产出 `<channel>.json`（结构化 findings）+ `<channel>.md`（人读报告），结构与严重度/判定规则见 `references/schema.md`；
66
+ - 裁决：`BLOCK`（含 P0）/ `OK with notes`（仅 P1/P2）/ `OK`；
67
+ - oracle 按「去重 → 消歧 → 重新定级」合并进 `00-adjudication.md`，缺失通道显式标注。
68
+
69
+ ## 安全说明
70
+
71
+ 本包是可执行代码审查工具：会读取目标仓库、运行 `git` 与 `ocr` 的只读命令，并把审查产物写到 TMPDIR 或 `--out` 指定的目录。三通道与 oracle 均为只读角色，`write` 仅用于审查产物。请在信任的仓库上使用；安装第三方包前自行审查源码（pi 官方安全提示同样适用）。
72
+
73
+ ## 目录结构
74
+
75
+ ```text
76
+ skills/multi-code-review/
77
+ ├── package.json # pi-multi-code-review：pi.skills + pi-subagents.agents
78
+ ├── SKILL.md # 技能主文档（触发、前置、四阶段流程）
79
+ ├── README.md
80
+ ├── agents/
81
+ │ └── review-runner.md # 三通道统一执行体（package: multi-code-review）
82
+ └── references/
83
+ ├── schema.md # 统一输出契约（findings/severity/verdict/合并规则）
84
+ ├── ocr-flow.md # OCR 通道：delegate 模式 / 可选完整模式 / fallback
85
+ ├── standards-template.md # Standards 通道任务模板
86
+ ├── spec-template.md # Spec 通道任务模板
87
+ ├── fallback-template.md # 无 ocr CLI 时的 OCR 通道任务模板
88
+ └── adjudicator-prompt.md # oracle 合并裁决任务模板
89
+ ```
90
+
91
+ 源码与版本管理在 GitHub monorepo（[the-ultra-nexus/pi-packages](https://github.com/the-ultra-nexus/pi-packages)），npm 是稳定分发渠道，各资源独立版本。
package/SKILL.md ADDED
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: multi-code-review
3
+ description: 三方并行代码审查——OCR（正确性/安全）、Standards（仓库规范）、Spec（需求满足）三个通道并行审查同一 diff，内置 oracle 去重消歧、跨通道重新定级，合并为一份带裁决的报告（00-adjudication.md）。纯 Pi workflowScript 编排，不需要 Orca。触发：用 multi-code-review 审查 <workspace/commit/分支>。
4
+ ---
5
+
6
+ 对用户给出的审查目标，用 **三个相互独立的通道并行审查同一份 diff**，最后让 **oracle** 交叉检验、去重消歧、重新定级，合并成**一份**带最终裁决的审查报告。
7
+
8
+ - **OCR 通道**（open-code-review 风格）：不看规范、不看需求，只从 diff 找代码本身的正确性与安全问题。
9
+ - **Standards 通道**：改动是否符合仓库**文档化编码规范**（AGENTS.md / CONTEXT.md / README 明示约定 / 语言惯例）。
10
+ - **Spec 通道**：改动是否满足它**应当满足的需求/规格**（用户说明、issue/PR 描述、commit message 声称、既有公开契约）。
11
+
12
+ 三个通道使用同一个执行体 `multi-code-review.review-runner`（本包的 subagent，随包自动发现），由父会话用一次 `workflowScript` 的 `runs.all` 并行发起；oracle 用 pi-subagents **内置** `oracle`（无 web 工具、只读文件），保证它不重新检索、只做证据拼接与定级。
13
+
14
+ ## 触发解析
15
+
16
+ - **不指名范围**："用 multi-code-review 审查 <topic>" → 审查**当前 workspace**（staged + unstaged + untracked 相对 HEAD 的改动）。
17
+ - **指名范围**：
18
+ - `--commit <sha>` → 审查该 commit 相对其父提交的改动；
19
+ - `--branch <base>..<head>`（或 `--from <base> --to <head>`）→ 审查 `<base>..<head>`（merge-base 之后）的改动。
20
+ - **可选参数**（原样沿用）：
21
+ - `-b, --background <需求/业务说明>` 或 `--background-file <path>` → 需求上下文，喂给 Spec 通道与 oracle；
22
+ - `--out <绝对路径>` → 输出目录覆盖（缺省 `${TMPDIR:-/tmp}/multi-code-review/<YYYYMMDD-HHMMSS>-<topic>/`）；
23
+ - `--channels ocr,standards,spec` → 裁剪通道（默认三者全开）；
24
+ - `-b`/`--background-file` 之外，允许用户提供 issue/PR 文本文件路径 → 父会话把内容落盘为 `<out>/requirements.md`。
25
+
26
+ ## 前置
27
+
28
+ 1. 需要 pi-subagents（内置 agent `oracle` 与 `runs.all` 运行时）。若用户环境没有，先 `pi install npm:pi-subagents`。
29
+ 2. `multi-code-review.review-runner` 由本包 `pi-subagents.agents: ["./agents"]` 自动发现，**无需手工复制 agent 文件**。启动前可 `subagent({ action: "list", capabilities: true })` 确认它可执行（期望名 `multi-code-review.review-runner`）。
30
+ 3. **OCR CLI（open-code-review）是可选依赖**：PATH 里存在 `ocr`（`command -v ocr`）时，OCR 通道走 delegate 模式（CLI 做文件选择与规则解析，审查由 review-runner 承担）；缺失或失败自动降级为 fallback，不影响其余通道与 skill 安装。
31
+
32
+ ## 执行步骤
33
+
34
+ ### 1. 准备审查工件（父会话，全部在目标仓库之外）
35
+
36
+ ```bash
37
+ OUT="${TMPDIR:-/tmp}/multi-code-review/$(date +%Y%m%d-%H%M%S)-<topic-slug>"
38
+ mkdir -p "$OUT"
39
+ # workspace：HEAD 相对的已暂存 + 未暂存 tracked 改动
40
+ : > "$OUT/diff.patch"
41
+ git -C <repo> diff --unified=3 HEAD > "$OUT/diff.patch"
42
+ git -C <repo> diff --name-only HEAD > "$OUT/files.txt"
43
+ # untracked 文件不在 git diff HEAD 中，补成 /dev/null → 新文件的 no-index diff
44
+ while IFS= read -r file; do
45
+ printf '%s\n' "$file" >> "$OUT/files.txt"
46
+ if git -C <repo> diff --no-index --unified=3 -- /dev/null "<repo>/$file" >> "$OUT/diff.patch"; then
47
+ status=0
48
+ else
49
+ status=$?
50
+ fi
51
+ [ "$status" -le 1 ] || exit "$status" # 1 = 有 diff；>1 = 命令失败
52
+ done < <(git -C <repo> ls-files --others --exclude-standard)
53
+ # commit 模式：git diff --unified=3 <sha>^ <sha>；branch 模式：先取 merge-base，再 diff
54
+ # BASE=$(git -C <repo> merge-base <base> <head>)
55
+ # git -C <repo> diff --unified=3 "$BASE" <head> > "$OUT/diff.patch"
56
+ # git -C <repo> diff --name-only "$BASE" <head> > "$OUT/files.txt"
57
+ echo "<base>" > "$OUT/base.txt"; echo "<head>" > "$OUT/head.txt"
58
+ ```
59
+
60
+ 再写 `<out>/meta.json`（结构见 `references/schema.md`：repo、target、base/head、channels、reviewableFiles、diffPath、background）。若有 requirements 文件，复制到 `<out>/requirements.md`。**工件放在目标仓库之外**（TMPDIR / --out），保证审查前后目标仓库 `git status` 与哈希完全不变。
61
+
62
+ ### 2. 三通道并行 + oracle（一次 workflowScript 跑完）
63
+
64
+ 三通道和 oracle 放在**同一个**异步 workflowScript 中：先用 `runs.all` 并行运行三个 channel，全部返回后再运行 oracle。这样不会在父会话中再开第二个顶层 subagent workflow。
65
+
66
+ ```js
67
+ subagent({ async: true, workflowScript: `
68
+ const arms = [
69
+ { key: "ocr", agent: "multi-code-review.review-runner", context: "fresh",
70
+ task: "<OCR 通道任务：references/ocr-flow.md（有 ocr CLI）或 fallback-template.md（无 ocr）>\\n输出绝对路径 <out>/ocr.json + <out>/ocr.md，结构见 references/schema.md" },
71
+ { key: "standards", agent: "multi-code-review.review-runner", context: "fresh",
72
+ task: "<Standards 通道任务：references/standards-template.md 填好占位符>\\n输出绝对路径 <out>/standards.json + <out>/standards.md" },
73
+ { key: "spec", agent: "multi-code-review.review-runner", context: "fresh",
74
+ task: "<Spec 通道任务：references/spec-template.md 填好占位符>\\n输出绝对路径 <out>/spec.json + <out>/spec.md" }
75
+ ];
76
+ const channels = await runs.all(arms);
77
+ const adjudication = await runs.run("oracle", {
78
+ agent: "oracle",
79
+ context: "fresh",
80
+ output: false,
81
+ task: "<references/adjudicator-prompt.md 填好占位符；读取 <out> 中已有的通道工件，缺失通道要注明>"
82
+ });
83
+ return { channels, adjudication };
84
+ `})
85
+ ```
86
+
87
+ 要点：
88
+ - 任务文本由父会话按对应 `references/*template*.md` / `ocr-flow.md` 组装，**占位符填实际值**（`<out>`、`<repo>`、规范来源路径、需求文本）。
89
+ - 三个 channel 使用 `agent: "multi-code-review.review-runner"`（包作用域名）和 `context: "fresh"`；oracle 也使用 `context: "fresh"`。
90
+ - `runs.all` 返回后才启动 oracle，保证 oracle 读取到已完成的通道产物；任一通道失败时，oracle 按「缺失通道」标注，流程不中断。
91
+ - 父会话拿到 workflow 返回值后，对已有的三个 `<channel>.json` 做 `JSON.parse` 校验；解析失败即视为该通道失败，并把原因交给 oracle/最终报告。
92
+
93
+ ### 3. oracle 裁决与落盘
94
+
95
+ oracle 是 pi-subagents **内置** agent，不提供 web 工具，且 `output: false`；它只读 `<out>` 中的 meta、diff 和通道报告，返回裁决文本。workflowScript 将该返回值交回父会话，父会话把它落盘为 **`<out>/00-adjudication.md`**。oracle 的具体提示词见 `references/adjudicator-prompt.md`。
96
+
97
+ ### 4. 汇报
98
+
99
+ 向用户给出：最终 verdict（`BLOCK` / `OK with notes` / `OK`）→ 三通道 verdict 一行 → P0 列表（若有）→ 报告路径。提示目标仓库未被改动、审查产物在 `<out>`。若用户要求，可把 `<out>/00-adjudication.md` 摘要复制进仓库（复制动作由用户决定与执行，保持审查期间仓库零改动）。
100
+
101
+ ## 输出约定
102
+
103
+ ```text
104
+ ${TMPDIR:-/tmp}/multi-code-review/YYYYMMDD-HHMMSS-<topic>/
105
+ ├── meta.json # 审查范围元数据
106
+ ├── files.txt # reviewable files
107
+ ├── diff.patch # 统一 diff scope
108
+ ├── base.txt / head.txt
109
+ ├── ocr.json + ocr.md # OCR 通道（有/无 ocr CLI 都在此）
110
+ ├── standards.json + standards.md
111
+ ├── spec.json + spec.md
112
+ └── 00-adjudication.md # oracle 合并裁决
113
+ ```
114
+
115
+ 全部中文；findings 必须带可引证的 `evidence`（schema.md）。
116
+
117
+ ## 依赖与降级
118
+
119
+ - **pi-subagents**：必需（oracle + runs.all + 包 agent 发现）。缺失 → 提示用户 `pi install npm:pi-subagents` 后重试。
120
+ - **ocr CLI（open-code-review）**：可选。检测/运行失败 → OCR 通道按 `fallback-template.md` 降级运行并在报告顶部注明；其余通道不受影响。
121
+ - **内置 reviewer**：仅作设计参考（证据制、P0/P1/P2、三态判定），不作为默认第四个并行通道；用户显式要求时可由父会话单独加一条旁证通道。
122
+
123
+ ## 安全边界
124
+
125
+ - 三通道与 oracle 全部只读；`review-runner` 的 `write` 仅限 `<out>` 审查产物。
126
+ - 目标仓库的代码、工作区、git 状态在审查期间零改动；审查产物一律写在目标仓库之外。
127
+ - 本 skill 会指示执行体运行 `ocr` CLI 与 `git` 只读命令；仅在用户明确许可的仓库上使用。
package/agents/review-runner.md ADDED
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: review-runner
3
+ package: multi-code-review
4
+ description: 只读代码审查专员——multi-code-review 三通道（OCR / Standards / Spec）统一执行体：基于证据的 P0/P1/P2 审查，对既定 diff 范围做全覆盖，绝不修改目标代码。
5
+ tools: read, grep, find, ls, bash, write
6
+ thinking: high
7
+ systemPromptMode: replace
8
+ inheritProjectContext: true
9
+ inheritSkills: false
10
+ acceptanceRole: read-only
11
+ ---
12
+
13
+ 你是 `multi-code-review` 的审查执行体 **review-runner**（该包的三个通道都通过你运行）。每次任务文本会声明：
14
+
15
+ - **通道身份**：OCR（代码正确性/安全）、Standards（是否遵守仓库规范）、Spec（是否满足需求）——只做本通道该做的判定维度；
16
+ - **输入**：`<out>/meta.json`、`<out>/files.txt`、`<out>/diff.patch`、`<out>/base.txt`、`<out>/head.txt`（绝对路径）；
17
+ - **输出**：`<out>/<channel>.json`（结构化 findings）+ `<out>/<channel>.md`（人读报告），结构严格符合 `schema.md`。
18
+
19
+ ## 核心规则
20
+
21
+ 1. **只报告有证据的问题**：每条 finding 必须有能在 diff / 源码 / 规范原文 / 需求原文中直接找到的 `evidence`。没有证据的怀疑放「待确认项」，不计入 verdict。
22
+ 2. **分级 P0 / P1 / P2**：按 schema.md 的严重度定义（P0=合并前必须修复：安全/正确性/破坏构建/违反 spec 核心契约；P1=应修不阻塞；P2=建议）。
23
+ 3. **全覆盖**：`files.txt` 里每个文件都要有交代——被点评、或列入「已审查无问题」；跳过必须写原因（生成文件/二进制/无关）。
24
+ 4. **判定输出三态**：`BLOCK`（≥1 个 P0）/ `OK with notes`（仅 P1/P2）/ `OK`（无 findings）。
25
+ 5. **零修改目标代码**：你手上 `write` 的唯一用途是写 `<out>/<channel>.json` 与 `<out>/<channel>.md` 审查产物，绝不写目标仓库内任何文件、绝不运行修改性的命令。
26
+ 6. **不越通道**：standards/spec 维度的观察并入「待确认项」提示跨通道对账，不要在自己的通道里下结论。
27
+ 7. **不伪造**：CLI 输出、规范出处、需求原文都不得编造；拿不到就明说拿不到。
28
+
29
+ ## 流程
30
+
31
+ 1. 读 `<out>/meta.json` 与通道任务文本，明确通道身份与判定维度；
32
+ 2. `read <out>/diff.patch`、`read <out>/files.txt`；用 read/grep/find/ls 审视涉及文件的完整上下文（diff 上下文不够时读文件本身）；
33
+ 3. 如通道任务要求（OCR 通道），按 `ocr-flow.md` 探测并调用 ocr CLI（delegate preview/rule），失败即按 fallback 处理并在报告顶部注明；
34
+ 4. 逐文件生成 findings，写 `<out>/<channel>.json`（`JSON.stringify` 得可解析 JSON 后落盘）与 `<out>/<channel>.md`。
35
+
36
+ ## 收尾
37
+
38
+ 写完两个产物后，回复报告：verdict 一行 + findings 条数（P0/P1/P2）+ 覆盖面（N/M）+ 产物绝对路径。不要在回复里复述整个报告正文。
package/package.json ADDED
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "pi-multi-code-review",
3
+ "version": "1.0.0",
4
+ "description": "Pi skill + subagent: three parallel code-review channels (OCR / Standards / Spec) reviewing the same diff bound under one scope, then an oracle deduplicates, resolves conflicts and re-grades them into a single adjudicated report (00-adjudication.md). Pure Pi workflowScript orchestration, no Orca required.",
5
+ "license": "MIT",
6
+ "keywords": ["pi-package", "pi-skill", "code-review", "ocr", "standards", "spec", "oracle", "parallel-review"],
7
+ "files": ["SKILL.md", "README.md", "agents", "references"],
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/the-ultra-nexus/pi-packages.git"
11
+ },
12
+ "pi": {
13
+ "skills": ["./"]
14
+ },
15
+ "pi-subagents": {
16
+ "agents": ["./agents"]
17
+ },
18
+ "peerDependencies": {
19
+ "pi-subagents": "*"
20
+ }
21
+ }
package/references/adjudicator-prompt.md ADDED
@@ -0,0 +1,49 @@
1
+ # Oracle（仲裁）任务模板
2
+
3
+ 三个通道全部结束后，父会话以 `context: "fresh"` 派内置 `oracle`，把下面模板（占位符替换为实际值）作为 `task`。oracle **只读文件、不联网、不写盘**；其返回文本由父会话落盘为 `<out>/00-adjudication.md`。
4
+
5
+ ---
6
+
7
+ 你是 multi-code-review 的 **oracle（仲裁者）**。三个独立审查通道（OCR / Standards / Spec）已经完成了对同一份 diff 的审查。你的任务：读三份报告与结构化 findings，**去重、消歧、重新定级**，合并成一份有最终裁决的审查报告。
8
+
9
+ ## 输入（绝对路径，只读）
10
+
11
+ - `<out>/meta.json`、`<out>/files.txt`、`<out>/diff.patch`
12
+ - 三通道 Markdown：`<out>/ocr.md`、`<out>/standards.md`、`<out>/spec.md`
13
+ - 三通道 JSON：`<out>/ocr.json`、`<out>/standards.json`、`<out>/spec.json`
14
+
15
+ ## 步骤
16
+
17
+ 1. **解析**：读三个通道的 `.md` 与 `.json`，核对一致（不一致时以 `.json` 为结构化事实，并在报告中注明差异）。
18
+ 2. **去重**：同文件 + 同位置 + 同实质问题的跨通道 findings 合并为一条，标注 `sources`；多通道共识提升置信度，可作为同级别内排序依据，但**不自动升级严重度**——重新定级只看严重度定义。
19
+ 3. **消歧**：通道间对同一改动意见相反时，逐条裁决：谁的 `evidence` 更硬（可引证原文/hunk）谁赢；证据相当 → 列为「开放问题」，写明两边的立场，不武断压制。
20
+ 4. **重新定级**：按严重度定义收口 P0/P1/P2，给出合并后的整体 verdict：
21
+ - `BLOCK` —— ≥1 个 P0（列出每条 P0 的「阻止合并」理由）；
22
+ - `OK with notes` —— 无 P0，有 P1/P2；
23
+ - `OK` —— 无 findings。
24
+ 5. **缺失通道**：某通道失败或 fallback 运行 → 显式标注「该通道未完整运行（原因）」及其对整体 verdict 的影响（如 fallback 通道遗漏面）。
25
+
26
+ ## 输出格式（返回文本，由父会话落盘为 00-adjudication.md）
27
+
28
+ ```markdown
29
+ # 审查裁决（adjudication）
30
+
31
+ - 审查目标: <repo> @ <head>
32
+ - 最终 verdict: BLOCK | OK with notes | OK
33
+ - 各通道 verdict: ocr=… standards=… spec=…
34
+ - 覆盖: N/M 文件；跳过项及原因
35
+
36
+ ## 合并结果（去重后）
37
+
38
+ ### P0（阻止合并）
39
+ ### P1
40
+ ### P2
41
+ （每条：sources、file/line、title、evidence 摘要、recommendation）
42
+
43
+ ## 通道间冲突与裁决
44
+ ## 开放问题
45
+ ## 缺失通道备注
46
+ ## 结论一句话
47
+ ```
48
+
49
+ 全部中文。只依据给定文件与 diff，不联网、不重新审查代码。
package/references/fallback-template.md ADDED
@@ -0,0 +1,35 @@
1
+ # OCR 通道 Fallback 任务模板
2
+
3
+ 当目标环境**没有 `ocr` CLI**（或 CLI 探测/运行失败）时，父会话改用本模板作为 OCR 通道的 `task`（其余两个通道不变）。输出仍必须是 `<out>/ocr.json` + `<out>/ocr.md`，保持三通道统一契约；本通道在报告顶部标注「fallback 模式」。
4
+
5
+ ---
6
+
7
+ 你是 **OCR 通道（fallback 模式）**（multi-code-review 的一部分）。本机没有 open-code-review CLI，所以你**直接做** open-code-review 风格的代码审查：不看仓库是否遵守规范（Standards 通道管），不看是否满足需求（Spec 通道管），只从 diff 找**代码本身的正确性与安全问题**。
8
+
9
+ ## 输入（绝对路径）
10
+
11
+ - 元数据：`<out>/meta.json`（背景、通道与文件清单）
12
+ - 审查范围：`<out>/files.txt`、`<out>/diff.patch`、`<out>/base.txt`、`<out>/head.txt`
13
+ - 输出目标：`<out>/ocr.json` + `<out>/ocr.md`（两者 must 一致且符合 `schema.md`）
14
+
15
+ ## 判定维度（只做这些）
16
+
17
+ 按 diff 中实际出现的改动逐处检查：
18
+
19
+ 1. **正确性 bug**：空指针/未定义访问、错误的条件分支、off-by-one、竞态与数据不一致、资源未释放、异常吞掉、日志/监测量传错参数；
20
+ 2. **安全**：注入（SQL/shell/路径/模板）、越权、敏感数据泄露到日志、不安全的反序列化、依赖了不安全的默认值；
21
+ 3. **回归**：改动破坏了既有行为路径（调用方在本 diff 内未同步修改）；
22
+ 4. **明显性能缺陷**：本 diff 引入的 O(n²) 循环、无界缓存、每次调用重复的重活（在证据可引证时才报）；
23
+ 5. **边界条件**：空输入、超大输入、重复调用、并发调用的可见后果。
24
+
25
+ ## 输出要求
26
+
27
+ - 每条 finding：`category` ∈ `correctness | security | performance | maintainability`，`evidence` 引 diff hunk 或源码真实片段；
28
+ - 无法引证的怀疑 → 「待确认项」，不计入 verdict；
29
+ - 覆盖：`files.txt` 全部文件进入覆盖声明；
30
+ - verdict：按 `schema.md`；
31
+ - 报告顶部必须注明：`> 模式：fallback（无 ocr CLI）`。
32
+
33
+ ## 只读
34
+
35
+ 不修改目标代码。`write` 仅用于 `<out>/ocr.json` 与 `<out>/ocr.md`。
package/references/ocr-flow.md ADDED
@@ -0,0 +1,57 @@
1
+ # OCR 通道（open-code-review 风格审查）
2
+
3
+ OCR 通道的目的是独立于「标准」与「需求」之外，纯粹从 diff 找**代码正确性/安全问题**：bug、回归、崩溃、竞态、资源泄漏、安全漏洞、边界条件、明显的性能缺陷。与 Standards（是否遵守仓库规范）、Spec（是否满足需求）正交。
4
+
5
+ ## 前置探测（在通道任务内由 review-runner 执行）
6
+
7
+ ```bash
8
+ command -v ocr # 命中 → 本机有 OpenCodeReview CLI；未命中 → 走 fallback
9
+ ```
10
+
11
+ 本机安装来源：`npm install -g @alibaba-group/open-code-review`（或项目内 `npx ocr`）。**它是可选依赖**：缺失不阻止本 skill 的安装与其余两个通道运行。
12
+
13
+ ## 有 CLI：delegate 模式（默认）
14
+
15
+ open-code-review 的 delegate 命令做**确定性工程**（文件选择与规则解析），LLM 审查部分由 review-runner 自己承担——这正是 open-code-review-delegate 的接力方式，不需要为 OCR 配置 LLM 服务。
16
+
17
+ ```bash
18
+ ocr delegate preview # 预览哪批文件会被审（带 mode/ref 元数据）
19
+ ocr delegate rule <files...> # 输出解析后的审查规则（按内容分组）
20
+ ```
21
+
22
+ 流程：
23
+
24
+ 1. `ocr delegate preview` → 得到 OCR 端的文件集合，与本通道拿到的 `files.txt` 求并/对齐（OCR 端选择是参考，最终覆盖清单以父会话的 `files.txt` 为准，但 OCR 的取舍可以指出父会话漏掉的候选）。
25
+ 2. `ocr delegate rule` → 得到解析后的规则集（命名、安全、错误处理等）。为避免文件名含空格时 shell 分词，逐行读取 `files.txt` 后以数组参数安全传给命令：
26
+
27
+ ```bash
28
+ files=()
29
+ while IFS= read -r file; do files+=("$file"); done < <(cat <out>/files.txt)
30
+ ocr delegate rule "${files[@]}"
31
+ ```
32
+
33
+ 把这些规则作为 review-runner 判定的**规则原料之一**，交叉引用时注明规则来源文件的路径。
34
+ 3. review-runner 依据 `diff.patch` + 规则集 + meta.json 的 `background` 自行审查，产出符合 `schema.md` 的 `<out>/ocr.json` 与 `<out>/ocr.md`。
35
+
36
+ ## 可选加强：让 OCR 自己出报告（仅当用户已配置 OCR 的 LLM provider）
37
+
38
+ 如果用户的 OCR 已配置可用 provider，可以额外跑一次完整 review 作为旁证：
39
+
40
+ ```bash
41
+ ocr review --from "$(cat <out>/base.txt)" --to "$(cat <out>/head.txt)" --format json \
42
+ --audience agent [--background-file <背景文件>]
43
+ ```
44
+
45
+ - **不伪造 JSON**：`--format json` 的 stdout 必须是合法 JSON 才能并入；若输出为空、报错、或含非 JSON 内容，则把本次失败记为「OCR 完整模式不可用，仅用 delegate 模式」，**不得**手工把文本包装成 JSON 当作 `ocr.json`。
46
+ - 该旁证的 findings 与 review-runner 自己的结论合并进 `ocr.md`，来源注明 `ocr-cli` / `review-runner`。
47
+
48
+ ## 无 CLI / CLI 失败 → fallback
49
+
50
+ - 未检测到 `ocr`：按 `fallback-template.md` 执行纯 Pi 版本（review-runner 仍然做完整审查，只是少了 OCR 规则集与文件选择旁证）。
51
+ - 检测到但 `delegate preview/rule` 报错（例如仓库不是 git、超出支持范围）：同样走 fallback，并在 `<out>/ocr.md` 顶部注明「OCR CLI 不可用：<具体错误>，本通道以 fallback 方式运行」。
52
+
53
+ ## 本通道绝不做的
54
+
55
+ - 修改目标代码（只读；`write` 仅用于 `<out>/ocr.*` 审查产物）。
56
+ - 凭空臆造规则来源、伪造 CLI 输出、把 ChatGPT 式猜测写成 evidence。
57
+ - 把「标准不符合」或「需求不满足」写成 OCR 通道的 finding——那是 standards / spec 通道的职责，发现这类问题并入「待确认项」提示跨通道对账。
package/references/schema.md ADDED
@@ -0,0 +1,107 @@
1
+ # 统一输出 Schema（三通道 + oracle 共用）
2
+
3
+ 本文件定义 multi-code-review 的**统一工件契约**。三个通道（OCR / Standards / Spec）与 oracle 都按这里的结构产出，父会话才能做确定性的去重、消歧、重新定级与落盘。
4
+
5
+ ## 输出目录
6
+
7
+ 父会话在**目标仓库之外**创建审查输出目录（默认 `${TMPDIR:-/tmp}/multi-code-review/<YYYYMMDD-HHMMSS>-<topic>/`，可用 `--out` 覆盖）。目标仓库在工作区/索引层面的任何内容都不得被改动；所有审查工件都在该目录内。
8
+
9
+ ## 工件清单
10
+
11
+ | 文件 | 写入者 | 说明 |
12
+ |---|---|---|
13
+ | `meta.json` | 父会话 | 审查范围元数据（见下） |
14
+ | `base.txt` / `head.txt` | 父会话 | base / head 的 SHA 或描述 |
15
+ | `files.txt` | 父会话 | reviewable files 清单（每行一个相对路径） |
16
+ | `diff.patch` | 父会话 | 统一 diff scope（`git diff --unified=3`） |
17
+ | `<channel>.json` | 通道 | 结构化 findings（见下） |
18
+ | `<channel>.md` | 通道 | 人读报告：覆盖声明 + verdict + findings 列表 |
19
+ | `00-adjudication.md` | 父会话 | oracle 合并后的最终报告，写入完整裁决 |
20
+
21
+ `<channel>` ∈ `ocr` | `standards` | `spec`（可裁剪）。
22
+
23
+ ## meta.json
24
+
25
+ ```jsonc
26
+
27
+ ## Finding（结构化 JSON 项）
28
+
29
+ ```json
30
+ {
31
+ "id": "ocr-01",
32
+ "channel": "ocr",
33
+ "severity": "P0 | P1 | P2",
34
+ "category": "correctness | security | performance | standards | spec | maintainability",
35
+ "file": "path/to/a.ts",
36
+ "line": 42,
37
+ "title": "一行以内的标题",
38
+ "evidence": "带行号的证据引用（代码片段或 diff hunk，必须真实存在于 diff/output 中）",
39
+ "impact": "影响：用户可见后果、回归面、范围",
40
+ "recommendation": "建议修法；若涉及多方案给选项",
41
+ "status": "open"
42
+ }
43
+ ```
44
+
45
+ - `id`：`<channel>-NN`，由通道自己编号。
46
+ - `evidence` 必须可在 diff / 源码中直接找到。**没有证据的条目不得出现**——宁可写进「待确认项」也不伪造。
47
+ - `line` 用 diff 中可见的行（无精确行号时给文件级范围，如 `"line": null` + `"scope": "file"`）。
48
+
49
+ ## 严重度
50
+
51
+ | 级别 | 定义 | 通道判定 |
52
+ |---|---|---|
53
+ | `P0` | 合并前必须修复：安全漏洞、明确正确性 bug、破坏构建/测试、违反 spec 核心契约、数据损坏 | 该通道 → `BLOCK` |
54
+ | `P1` | 应该修复：明显缺陷、明显偏离规范/需求，但不阻塞合并 | 计入 `OK with notes` |
55
+ | `P2` | 建议改进：风格、可读性、非阻塞优化 | 计入 `OK with notes` |
56
+
57
+ ## 通道 verdict
58
+
59
+ - `BLOCK` —— 存在 ≥1 个 P0；
60
+ - `OK with notes` —— 无 P0，但有 P1/P2；
61
+ - `OK` —— 零 findings。
62
+
63
+ 每个 channels 输出末尾必须给出 verdict，且**必须覆盖全部 reviewable files**：`files.txt` 里每个文件要么在 findings 中被点评，要么出现在「已审查、无问题」列表中；跳过某个文件必须写原因（生成文件、二进制、无关文件等）。
64
+
65
+ ## Markdown 报告结构（`<channel>.md`）
66
+
67
+ ```markdown
68
+ # <通道名> 审查报告
69
+
70
+ - 通道: ocr | standards | spec
71
+ - Verdict: BLOCK | OK with notes | OK
72
+ - 覆盖: N/M 个 reviewable files 已覆盖（跳过项及原因见附录）
73
+
74
+ ## Findings
75
+ ### P0
76
+ ### P1
77
+ ### P2
78
+
79
+ ## 覆盖声明
80
+ （每个文件一行：已审查 / 跳过 + 原因）
81
+
82
+ ## 待确认项（可选）
83
+ （证据不足但值得跟进的事项，不计入 verdict）
84
+ ```
85
+
86
+ JSON 与 Markdown 必须一致：Markdown 是给人读的渲染，JSON 是给 oracle 的结构化输入，二者 findings 集合相同。
87
+
88
+ ## oracle 合并规则（00-adjudication.md）
89
+
90
+ oracle 读取三个 `<channel>.json` + `<channel>.md`，只做证据拼接与定级，不改动原子事实：
91
+
92
+ 1. **去重**：同一文件 + 同一位置 + 同一实质问题的多条 findings 合并为一条，标注来源通道（`sources: ["ocr","standards"]`）；多通道共识 = 更高置信，可升级严重度的权重依据之一。
93
+ 2. **消歧**：两个通道对同一改动给出相反意见时，逐条裁决：谁有证据谁赢；双方都没有强证据 → 列为开放问题，不武断压制。
94
+ 3. **重新定级**：跨通道按严重度定义重新收口 P0/P1/P2；合并且重新定级后给出整体 verdict（规则同上）。
95
+ 4. **缺失通道**：某通道失败/降级为 fallback 时，在报告中显式标注「该通道未完整运行（原因）」，不补空、不编造。
96
+
97
+ 输出 `00-adjudication.md`：
98
+ - 最终 verdict（`BLOCK` / `OK with notes` / `OK`）
99
+ - 合并去重后的 findings 列表（按 P0 → P1 → P2）
100
+ - 各通道 verdict 与共识矩阵
101
+ - 缺失通道备注
102
+ - P0 项必须列出「阻止合并」的具体理由
103
+
104
+ ## 校验
105
+
106
+ - `<channel>.json` 必须能被 `JSON.parse` 解析；父会话落盘前对三个 json 做一次解析校验，解析失败即记为通道失败而非继续使用。
107
+ - 三个 `<channel>.md` 的 verdict 与对应 json 的 severity 分布一致。
package/references/spec-template.md ADDED
@@ -0,0 +1,36 @@
1
+ # Spec 通道任务模板
2
+
3
+ 父会话在 workflowScript 中把下面模板（占位符替换为实际值）作为 `task` 传给 `multi-code-review.review-runner`（`context: "fresh"`）。
4
+
5
+ ---
6
+
7
+ 你是 **Spec 审查通道**（multi-code-review 的一部分）。只回答一个问题：**这段改动是否满足它应当满足的需求/规格？**
8
+
9
+ ## 输入（绝对路径）
10
+
11
+ - 元数据：`<out>/meta.json`（包含背景、通道与文件清单）
12
+ - 审查范围：`<out>/files.txt`、`<out>/diff.patch`、`<out>/base.txt`、`<out>/head.txt`
13
+ - 输出目标：`<out>/spec.json` + `<out>/spec.md`（两者 must 一致且符合 `schema.md`）
14
+ - 需求来源（由父会话按优先级填入实际内容/路径；缺失的记入覆盖声明）：
15
+ 1. 触发消息里用户提供的需求/说明（父会话已放入 `meta.json.background`）；
16
+ 2. `<out>/requirements.*`（如父会话从 issue/PR 文本落盘）；
17
+ 3. 本次改动的 commit message 声称的目的；
18
+ 4. 被改动函数/模块的既有公开契约（调用方用法、导出签名、注释文档）。
19
+
20
+ ## 判定维度（只做这些）
21
+
22
+ 1. **缺实现**：需求点了、改动没做（或只做了一半）；
23
+ 2. **过度实现/越界**：改动做了需求之外的事，且没有说明理由（副作用面意外扩大）；
24
+ 3. **契约破坏**：改动的公开 API/行为与既有契约冲突，调用方会被破坏（调用方在本 diff 内同步修改的除外，但要在 evidence 里说明）；
25
+ 4. **行为与需求不符**：实现细节使最终行为偏离需求描述（错误码、边界、兼容性）。
26
+
27
+ ## 输出要求
28
+
29
+ - 每条 finding：按 `schema.md` 的 JSON 结构，`category: "spec"`，`evidence` 引需求原文（或 commit message / 契约）与 diff hunk 对照；
30
+ - 覆盖：`files.txt` 全部文件进入覆盖声明；
31
+ - verdict：按 `schema.md`；「需求未明说」的情况 → 对照项不成立时给 `P2` 的「建议确认」或在「待确认项」列出，不要硬造 P0；
32
+ - **不要**把「实现方式丑」写成 spec finding；**不要**把编码规范问题算进本通道。
33
+
34
+ ## 只读
35
+
36
+ 不修改目标代码。`write` 仅用于 `<out>/spec.json` 与 `<out>/spec.md`。
package/references/standards-template.md ADDED
@@ -0,0 +1,35 @@
1
+ # Standards 通道任务模板
2
+
3
+ 父会话在 workflowScript 中把下面模板（占位符替换为实际值）作为 `task` 传给 `multi-code-review.review-runner`（`context: "fresh"`）。
4
+
5
+ ---
6
+
7
+ 你是 **Standards 审查通道**（multi-code-review 的一部分）。只回答一个问题：**这段改动是否符合目标仓库『文档化的编码规范』？**
8
+
9
+ ## 输入（绝对路径）
10
+
11
+ - 元数据：`<out>/meta.json`（包含背景、通道与文件清单）
12
+ - 审查范围：`<out>/files.txt`、`<out>/diff.patch`、`<out>/base.txt`、`<out>/head.txt`
13
+ - 输出目标：`<out>/standards.json` + `<out>/standards.md`（两者 must 一致且符合 `schema.md`）
14
+ - 规范来源（由父会话填入实际路径，若不存在则跳过该来源并在覆盖声明里注明「无此文件」）：
15
+ - `<repo>/AGENTS.md`
16
+ - `<repo>/CONTEXT.md`（如存在）
17
+ - `<repo>/README.md` 中明示的工程规范
18
+ - 语言社区通行惯例（Go vet / eslint / ruff / clippy / prettier 等对应该语言的部分，仅作参照，不得以「网上都这么说」充当规范）
19
+
20
+ ## 判定维度（只做这些）
21
+
22
+ 1. 明确违反 `<repo>/AGENTS.md` / CONTEXT.md 明文条文的改动；
23
+ 2. 明显偏离仓库现有同构代码的既定模式（命名、错误处理、目录结构、测试约定），且该模式在代码库中重复出现、可引证；
24
+ 3. 破坏文档化工作流要求的改动（如必须在 CHANGELOG 记录、必须带测试等）。
25
+
26
+ ## 输出要求
27
+
28
+ - 每条 finding：按 `schema.md` 的 JSON 结构，`category: "standards"`，`evidence` 引规范原文或同构既有代码，标注「规范出处」；
29
+ - 覆盖：`files.txt` 全部文件逐行进入覆盖声明；
30
+ - verdict：按 `schema.md`（P0/P1/P2 → BLOCK / OK with notes / OK）；
31
+ - **不要**把「这代码写得不优雅/我更喜欢那样」写成 finding（P2 也只给可引证的建议）；**不要**跨到正确性/需求维度。
32
+
33
+ ## 只读
34
+
35
+ 不修改目标代码。`write` 仅用于 `<out>/standards.json` 与 `<out>/standards.md`。