cross-review - SKILL.md Agent Skill

name: cross-review description: "在开发完成后自动交叉评审代码变更。审查者运行在隔离的 LLM 会话中，不继承开发上下文，发现偏差和盲点。Advisory 模式：结论仅供参考，不自动阻断。"

何时触发

在 develop 阶段完成、代码已写入磁盘后触发。不要在规划阶段或未产生代码变更时触发。

前置条件：

工作区存在未评审的代码变更（已提交的 review range、已暂存的本轮变更，或可确认只包含本轮任务的未暂存变更）。
crossreview CLI 已安装，且支持 pack --diff/--staged/--unstaged、render-prompt --pack、ingest --raw-analysis/--pack/--format human。
默认 host-integrated 路径可用：宿主能在 fresh / isolated review context 中执行 render-prompt 产出的完整 prompt。

注释：Sopify Phase 4a 的默认路径不要求 CrossReview 自己配置模型、provider 或 API key；LLM 调用由当前宿主完成。只有使用 standalone fallback 的 crossreview verify 时，才需要 CROSSREVIEW_MODEL / CROSSREVIEW_PROVIDER / API key 或等价 crossreview.yaml。

默认流程（Host-integrated）

Step 0 — 选择 diff source 并隔离 review range

CrossReview 0.1.0a2+ 支持三种确定性差异来源：

--staged：优先用于本轮未提交变更的 pre-commit review，执行 git diff --cached，不要求创建 review commit。
--diff REF：用于已提交或需要可复现 review range 的场景，执行 git diff REF HEAD。
--unstaged：只在工作区未暂存变更可以确认全是本轮任务时使用，执行 git diff。

0A — 选择推荐路径：

[IF 本轮变更尚未提交，且可以安全区分本轮目标文件] 只 stage 本轮 develop 产生的文件（基于任务清单中的目标文件），不使用 git add -A。设置 DIFF_SOURCE="--staged"。

[ELSE IF 本轮变更已提交，或用户要求审查提交范围] [IF 任务涉及多次提交] REF = HEAD~~{提交数} [ELSE] REF = HEAD~~1

展示 REF 对应的 commit，让用户确认起点正确：

git log -1 --oneline <REF>

[ACTION: INFORM_USER] "Review 起点为：{REF 对应的 commit 摘要}。本轮 develop 的所有变更应在此之后。" 若用户认为起点不对，让用户指定正确的 commit SHA 作为 REF。设置 DIFF_SOURCE="--diff <REF>"。

[ELSE IF 工作区存在未暂存变更，且可以确认全部属于本轮任务] 设置 DIFF_SOURCE="--unstaged"。

[ELSE] 跳过 advisory review，记录原因 diff_source_not_isolated，继续主流程。

重要：不要自动 git add -A && git commit。这会把工作区所有变更（包括无关草稿、未跟踪文件）一起提交，违反安全边界。

Step 1 — 生成 ReviewPack

CR_TMP="$(mktemp -d)"
printf '%s\n' "$CR_TMP"
crossreview pack $DIFF_SOURCE \
  --intent "任务意图摘要" \
  > "$CR_TMP/pack.json"

若 exit code 非零，记录 pack_failed 并结束本次 advisory review，继续主流程。

参数说明：

--intent "任务意图摘要" — 帮助审查者理解变更目标（推荐始终提供）。
--task ./task.md — 任务描述文件；仅在文件真实存在时添加。
--context ./plan.md — 额外上下文文件（可重复）；仅在文件真实存在时添加。
--focus <area> — 聚焦区域（可重复）。

注释：pack 只做确定性打包，不调用 LLM，不需要 API key。注释：如果后续命令不是在同一个 shell session 中执行，必须记录 mktemp 打印的实际目录，并把后续命令里的 $CR_TMP 显式替换为该目录；不要假设 shell 变量会跨 tool call 保留。

Step 2 — 渲染 canonical reviewer prompt

crossreview render-prompt --pack "$CR_TMP/pack.json" > "$CR_TMP/prompt.md"

若 exit code 非零，记录 render_prompt_failed 并结束本次 advisory review，继续主流程。

注释：render-prompt 只把 ReviewPack 渲染成标准审查 prompt，不调用 LLM，不需要 API key。

Step 3 — 宿主执行隔离审查

在 fresh / isolated host review context 中执行 "$CR_TMP/prompt.md" 的完整内容，并将原始审查输出保存为：

RAW_ANALYSIS="$CR_TMP/raw-analysis.md"
printf '%s\n' "$RAW_ANALYSIS"

注释：这里是保存路径约定；宿主隔离审查完成后，必须把 raw analysis 写入该文件，之后 Step 4 才能 ingest。

硬性约束：

不要把 develop 对话、作者推理链、未公开的自我解释放入 reviewer context。
不要在当前 develop 上下文中直接“自己审自己”，这不满足 CrossReview 的上下文隔离目标。
若宿主无法提供 fresh / isolated review context，记录原因 host_isolation_unavailable 并结束本次 host-integrated 审查（不得执行 Step 4）；若 standalone 前置条件满足可改走备用流程，否则继续主流程。不要伪装成已完成 CrossReview。

Step 4 — Ingest 原始审查输出并读取 verdict

crossreview ingest \
  --raw-analysis "$RAW_ANALYSIS" \
  --pack "$CR_TMP/pack.json" \
  --model host_unknown \
  --prompt-source product \
  --prompt-version v0.1 \
  --format human

若 exit code 非零，记录 ingest_failed 并结束本次 advisory review，继续主流程。

命令成功时（exit code 0），输出格式为：

CrossReview 0.1-alpha | artifact: <hash> | review_status: <status>

Intent: <intent>
Intent Coverage: covered/partial/unknown
Pack Completeness: 0.XX

Findings (N):
  [HIGH]  file.py:42 — 发现摘要
  [MED]   other.py — 另一个发现

Advisory Verdict: <verdict>
  Rationale: <理由>

关键字段：

review_status — complete / rejected / failed
Advisory Verdict — 见 Step 5 分支

Step 5 — 根据 verdict 分支处理

[IF review_status != "complete"] [ACTION: LOG_WARNING] 记录非正常状态（rejected / failed），继续主流程，不阻断。 [SKIP] 不进入以下 verdict 分支。

[IF Advisory Verdict == "pass_candidate"] [ACTION: CONTINUE] 告知用户：评审未发现问题，代码可以继续推进。

[IF Advisory Verdict == "concerns"] [ACTION: SHOW_FINDINGS] 向用户展示所有 findings（按严重度排列）。 [ACTION: ASK_USER] "评审发现以下问题：\n{findings}\n(A) 修改代码后重新评审 (B) 接受并继续 (C) 忽略"

用户选 A → 修改代码，回到 Step 0 重新执行
用户选 B 或 C → 继续主流程

[IF Advisory Verdict == "needs_human_triage"] [ACTION: SHOW_FINDINGS] 展示所有 findings。 [ACTION: REQUEST_HUMAN] "评审发现需要人工判断的复杂问题，请审阅后决定。" 等待用户明确指令后再继续。

[IF Advisory Verdict == "inconclusive"] [ACTION: LOG_WARNING] "评审结果不确定，可能由于上下文不足、隔离审查失败或模型限制。" 继续主流程，不阻断。

备用流程（Standalone Verify）

仅在 host-integrated 路径不可用，且 standalone reviewer 配置已经存在时使用：

crossreview verify $DIFF_SOURCE --intent "任务意图摘要" --format human

可选参数同 Step 1（--task、--context、--focus）。

Standalone 前置条件：

已设置 CROSSREVIEW_MODEL / CROSSREVIEW_PROVIDER / CROSSREVIEW_API_KEY_ENV，或等价 crossreview.yaml。
对应 API key 环境变量存在。

注释：standalone fallback 会由 CrossReview CLI 直接调用 LLM API；这不是 Phase 4a 的默认宿主集成路径。

重要约束

Exit code 0 = 结果已产出，不代表评审通过。必须读 Advisory Verdict 行判断。
Exit code 非零 = 命令执行失败，无评审结果。记录错误，继续主流程。
Advisory 模式：verdict 仅供参考，不自动阻断任何流程。
不要在无代码变更时运行（浪费 token）。
默认 host-integrated 路径为 pack -> render-prompt -> host isolated review -> ingest；verify --diff 只是 standalone fallback。
--format human 用于终端展示，--format json 用于程序解析。

交付检查

crossreview pack 成功生成 ReviewPack
crossreview render-prompt 成功生成 canonical reviewer prompt
宿主 fresh / isolated review context 已产出 raw analysis
crossreview ingest --format human 成功产出 ReviewResult
Advisory Verdict 已读取并展示给用户
concerns / needs_human_triage 时用户已被告知并做出决定
结果不阻断主流程（advisory only）