cross-review - SKILL.md Agent Skill

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

何时触发

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

前置条件：

工作区存在未评审的代码变更（已提交的 review range git diff <REF>..HEAD 非空，或存在需要用户确认提交的本轮未提交变更）。
crossreview CLI 已安装（pip install crossreview 或 pip install -e .）。
默认 host-integrated 路径可用：宿主能在 fresh / isolated review context 中执行 render-prompt 产出的完整 prompt。

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

默认流程（Host-integrated）

Step 0 — 确定 diff 基准并确保变更进入 review range

CrossReview 的 --diff REF 执行的是 git diff REF HEAD，只捕获已提交的变更，不包含未暂存或未提交的工作区修改。

0A — 确定 diff 基准（REF）：

[IF 任务涉及多次提交] REF = HEAD~~{提交数} [ELSE] REF = HEAD~~1

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

git log -1 --oneline <REF>

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

0B — 处理未提交变更：

[IF git status --short 非空（工作区存在未提交的 develop 变更）] [ACTION: INFORM_USER] 说明 CrossReview v0 只能审查已提交的 diff，当前变更尚未进入 review range。 [ACTION: ASK_USER] "本轮 develop 产出尚未提交。CrossReview 需要已提交的 diff 才能工作。 (A) 创建 review commit 并继续评审 (B) 跳过本次 advisory review"

用户选 A：
1. 记录当前基准：BASE_SHA=$(git rev-parse <REF>)，作为 review range 的稳定起点。
2. 只 stage 本轮 develop 产生的文件（基于任务清单中的目标文件），不使用 git add -A。
3. 若无法安全区分本轮文件与工作区其他变更，跳过 advisory review 并记录原因 crossreview_requires_committed_diff。
4. 使用任务摘要作为 commit message（如 "develop: 实现用户认证模块"），不使用固定泛化消息。
5. 提交后设置 REF = BASE_SHA。后续 crossreview pack --diff <REF> 会稳定审查 BASE_SHA..HEAD，包含本轮所有已提交变更和刚创建的 review commit。
用户选 B：跳过 advisory review，记录原因 user_skipped_uncommitted，继续主流程。

[ELSE IF git status --short 为空（工作区干净）] 检查已提交的 review range：git diff <REF>..HEAD。 [IF review range 非空] 变更已在 HEAD 中，继续 Step 1。 [ELSE] 无代码变更，跳过评审。

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

Step 1 — 生成 ReviewPack

CR_TMP="$(mktemp -d)"
printf '%s\n' "$CR_TMP"
crossreview pack --diff <REF> \
  --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。

已验证 host adapter：

Qoder：读取 references/host-adapters/qoder-agent.md（Agent 工具隔离路径，2026-06-21 验证）
其他宿主：暂无已验证 adapter。若宿主提供 fresh session 能力，按上述硬性约束实现并记录。

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 <REF> --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）