richinfo-cr 代码审核

通过本机 richinfo-cr CLI 完成代码审核。认证、变更收集、CodeGraph 上下文、提交、等待与结果渲染全部由 CLI 负责；禁止直接调用服务端 API，禁止自行用 git diff / CodeGraph 复刻这些步骤。命令输出按结构化 JSON 处理，不得在输出中暴露任何凭据值。

触发时机

在以下任一场景下主动介入：

• 用户完成一段代码编写或修改后，希望确认质量；
• 用户在 commit、push 或发起 PR(MR) 之前；
• 用户明确要求「审核」「审查」「review」「检查代码」；
• 用户执行主动命令 /review。

工作流

第 0 步：版本对齐（不最新则强制升级）

审核的起手动作就是版本对齐：先取本机版本、再取线上最新版本；只要不是最新，就强制升级到最新，升级后复审确认，再进第 1 步。

richinfo-cr version --format json      # 本机版本（cliVersion）
npm view @richinfo-cr/cli version      # 线上最新版本

判定与动作：

强制升级的五条硬要求：

1. 比对与安装必须走同一个 registry。 本机 npm 可能指向镜像源，两处用不同源会得出「永远不是最新」的假结论并反复升级。先 npm config get registry 确认；需要显式指定时，两条命令统一加 --registry https://registry.npmjs.org。
2. 升级后必须复审一次 richinfo-cr version --format json。仍不一致、或安装失败 → 如实报告错误并停止本次审核，不要用旧版本静默继续。
3. npm install -g 改的是整机 CLI，会同时影响这台机器上所有宿主（WorkBuddy / Claude Code / Codex / Cursor）以及正在跑的审核会话——这是"强制"的固有代价，不要再回头征求同意。
4. 幂等：版本已一致就不要重复安装；同一会话内已对齐过，后续审核不必每轮再装一次。
5. command not found ≠ 未安装 —— 先排除 PATH 问题。 npm 全局 bin（$(npm prefix -g)/bin，本机实测为 ~/.npm-global/bin）常常不在 Agent 沙箱 / 非登录 shell 的 PATH 里，而已装好的软链其实就躺在那里。查明前不要重装（重装修不好解析，只会白装一遍并在每轮审核里重复）：

ls -l "$(npm prefix -g)/bin/richinfo-cr"

• 存在 ⇒ 是 PATH 问题，不要安装。改用绝对路径调用，并提示用户把 $(npm prefix -g)/bin 加进 PATH：

"$(npm prefix -g)/bin/richinfo-cr" version --format json

• 确实不存在 ⇒ 才走上面的安装动作。

> 版本对齐只针对 richinfo-cr CLI 本身。其他外部工具仍不要在审核流程内引导安装：skillhub 与审核无关、不要引入；CodeGraph 由 CLI 按需托管（init 自动拉取并 pin 版本，判定见「索引状态真伪判定」一节）。

第 1 步：前置检查（懒初始化）

首次使用或不确定环境是否就绪时，先运行健康检查：

richinfo-cr doctor --format json

doctor 返回 checks[]，每项为 {name, ok, message}，覆盖 login、git、codegraph、config、network 五项。按结果逐项处理：

• login 失败 → 运行 richinfo-cr login --format json 启动设备授权，引导用户完成登录（会打开浏览器）；
• git 或 config 失败 → 运行 richinfo-cr init --format json（自动注册当前仓库、准备 CodeGraph 索引）；
• codegraph 失败 → 运行 richinfo-cr init --format json。该项现为「二进制版本 + 本地索引状态」两段式：健康时给出已索引文件/符号数，并提示待同步文件或 daemon 状态；失败可能是二进制缺失、索引未构建、reindexRecommended（需一次性全量重建：引擎升级，或索引从未建成过）或 WAL 异常增长（>1 GiB，索引可能损坏），以上都由 init 读 status 自动分流修复（分流规则见「索引状态真伪判定」一节）。

触发全量重建前必须先核算索引规模，不要拿仓库体积当代理指标。 索引只吃「可建图的源码文本」——.git 对象、二进制、图片、构建产物、以及被 exclude 挡掉的目录全都不进索引，两者可以差一个数量级（pc_client 实测：仓库 9.6 GB，其中 .git 4.7 GB，排除 ext/ 后实际索引仅 204 MB）。核算三步（估算法与实测标定详见 references/codegraph-probe.md）：

1. 读仓库根 codegraph.json 的 exclude（init 会把内置规则合并进来），确认第三方源码目录（ext/、vendor/、third_party/ 这类）在排除面内。内置规则不覆盖 ext/，这类目录必须由仓库自己声明——init 时可一次写入：richinfo-cr init --exclude '**/ext/**' --format json；
2. 按目录汇总可建图字节：git ls-tree -r -l HEAD | awk '{p=$5; s=$4; if (p ~ /\.(hpp|h|cpp|c|ipp|cc|cxx|m|mm|js|ts|tsx|xml|yaml|yml)$/) {split(p,a,"/"); d=(a[2]==""?"(root)":a[1]); b[d]+=s}} END {for (k in b) printf "%10.1f MiB %s\n", b[k]/1048576, k}' | sort -rn；
3. 按 db ≈ 可建图源码字节 × 3（峰值瞬时再 × 2.5）估算，再与 df -h 的可用空间比对。

排除到位时，大仓重建通常是百余 MB、分钟级（pc_client 实测 2,256 文件 / 204 MB / 54 秒）；只有把 vendored 依赖也建图才会到 GB 级、小时级。先算出数字再决定要不要用户拍板，不要把笼统的"数小时 / 数 GB"抛给用户；核算发现确实超预算时，优先扩大 exclude 面，而不是直接放弃索引。
- network 失败 → 先用 curl 探一次服务地址确认服务是否真的不可达：若服务有响应（如 /api/v1/version 返回 JSON），说明是认证探测失败而非网络问题，继续尝试审核；确实不可达才报告用户，不要反复重试；
- 全部 ok=true → 直接进入第 2 步。

doctor 是纯只读检测，幂等；完成后无需再次运行即可直接审核。索引状态检查只在 git 仓库内、且配置检查通过后执行，非仓库目录下不会因此变红。

第 2 步：执行审核

richinfo-cr review --format json

该命令默认等待终态结果。缩小审核范围可用 --base <branch>、--commit <sha>，或传仓库相对路径。

变更范围包含未跟踪的新文件（本机实测：工作区 1 个已跟踪改动 + 1 个 ?? 新文件 → summary.filesChanged=2，两条 finding 全部落在那个未跟踪文件上）。所以提交前先看一眼 git status，别把临时脚本、本地调试产物、构建中间件一并送审；只想审已提交内容就用 --commit <sha>。另外 --format json 下全程无进度输出（含前台），静默到出结果为止——小改动约 1~2 分钟，属正常，不要据此判定卡死。

退出码含义：

大仓 / 慢网关下不要在前台死等。 本机实测：review 在前台可能长时间无任何输出，而工具侧的等待上限会把它 SIGTERM 掉（退出码 137）——但审核已在服务端继续跑，不会因此丢失。判断与跟进方式：

1. 改用 --no-wait 提交，拿到 reviewId 后轮询：

richinfo-cr review --commit <sha> --no-wait --format json   # → {"reviewId":"CLI-12-…","status":"QUEUED"}
richinfo-cr status <reviewId> --format json                  # 轮询到 COMPLETED / FAILED / PARTIAL_FAILED
richinfo-cr result <reviewId> --format json

2. 若已在前台被中断，不要重新提交，先 richinfo-cr list --format json 看是否已生成 reviewId，有就直接 status / result 跟进。
3. status 在 REVIEWING 55% 停留较久是正常的（该阶段是多个专家 Agent 并行审查），不要据此判定卡死。

第 3 步：展示审核结果

读取返回的 ReviewResult，结构化展示：

• summary：变更/审核文件数、发现项总数、阻断数、最高严重度、覆盖率、耗时；
• findings[]：逐项列出 severity、path:line、title、message、suggestion；
• incomplete 或 contextPartial 为 true 时，如实提示结果可能不完整。

第 4 步：本地 Agent 分析缺陷是否成立

这一步的分析主体是本机 Agent，不是服务端。 服务端只返回 findings 的原始数据；某条缺陷是否真的成立、是否值得改，必须由你在本地结合真实代码、diff 范围、调用链与项目约定自行判断。不要盲信服务端给出的 severity，也不要无脑全修。

判断依据（字段含义详见 references/finding-schema.md）：

• severity：BLOCKER/CRITICAL 默认必须处理；MAJOR 需结合上下文；MINOR/INFO 一般不处理；
• validation.introduced：true 为本次变更新引入（应处理）；false/缺省为历史遗留，通常不在本次范围；
• validation.grounded：true 表示证据充分；false 可能是误报，须亲自读代码复核；
• suggestion：官方修复建议，仅作参考，不代替你的判断；
• 本地复核（必需）：打开 path:startLine 附近的真实代码，确认问题是否真实存在、是否由本次 diff 引入、项目约定是否另有要求。

据此输出三类清单：

1. 必须处理：BLOCKER/CRITICAL；或 MAJOR 且 introduced=true 且本地复核成立；
2. 建议处理：MAJOR；或高严重度但本地复核存疑；
3. 可忽略：MINOR/INFO；或 introduced=false 的历史遗留。

对每个「必须处理」和「建议处理」项，先写出你的结论（成立 / 不成立 + 一句话理由，引用具体代码事实）。这个理由在第 6 步 B 分支会上报给平台，必须是基于代码的判断，不能只是复述平台描述。

第 5 步：弹窗收集用户决策

对第 4 步产出的「必须处理」「建议处理」清单，逐项弹窗让用户决策，不要只在正文里问一句。

使用 AskUserQuestion 工具，每个 finding 一个问题，选项固定三项：

分批规则（AskUserQuestion 单次最多 4 个问题）：

• 待决策项 ≤ 3 个 → 一次性逐项询问；
• 待决策项 > 3 个 → 先弹一个总览问题「共 N 项待处理，如何决策？」，选项为 全部修复 / 逐项决策 / 全部暂不处理；用户选 逐项决策 后再按每批不超过 3 项分批询问。

问题文本用 path:startLine + title，每个选项的 description 写你第 4 步得出的判断理由，便于用户快速决策。

第 6 步：按决策执行

A 分支：修复

• 按 path:startLine 定位，采纳 suggestion 并结合项目约定修改；同一文件多个 finding 合并处理，避免重复编辑；
• 修完在正文列出改动点（文件 + 行 + 改了什么）；
• 询问用户是否重跑 richinfo-cr review --format json 复检；
• 复检通过后，若 CLI 支持，执行下面命令把采纳状态回写平台，供统计采纳率（GitLab 来源会同步回评）：

richinfo-cr finding adopt --review <reviewId> --finding <findingKey> --format json

B 分支：上报为误报（整合到平台 bad-case）

先做能力探测，确认 CLI 是否支持反馈命令：

richinfo-cr finding --help 2>/dev/null || echo "NO_FEEDBACK_CMD"

支持时，对每个上报项执行：

richinfo-cr finding false-positive --review <reviewId> --finding <findingKey> --format json \
  --category "<类别>" --reason "<本地 Agent 给出的不成立理由>"

• --category 由你依据本地复核结论判定（服务端会把中文归一化为枚举值）。最常用三类：幻觉（平台描述与代码事实不符）、规范不合理（规则不适用于当前上下文）、可忽略（问题成立但影响极小）；另有 低价值、已有保护措施、不符合项目规范、其他 可用；
• --reason 填你第 4 步写出的判断理由（必填），说明为什么不成立。平台会把该理由连同代码片段一起存入 bad-case 库；
• 依赖 findingKey：上报按 findingKey 定位 finding（形如 26898161811f），该字段由 richinfo-cr result 返回（CLI 默认按 schemaVersion=2 取结果，已包含）。若 findings 中不含 findingKey，说明服务端或 CLI 版本过旧，走下面的降级路径，不要臆造 ID；
• 提交即生效，无需审批（平台已于 2026-09-17 去审批）。上报成功后平台立即置 qa_status_code=ACTIVE，但向量化是异步的：先 PENDING_VECTOR，完成后转 READY。只有 READY 的条目才会被后续审核召回，所以刚上报时不要声称"已用于抑制同类误报"——须如实告知用户向量化仍在进行（通常数秒到数十秒）。
• 状态是两个正交字段，不要混为一谈：qa_status_code（ACTIVE/DISABLED，业务可用性，提交即 ACTIVE、管理员可下线）与 vector_state（PENDING_VECTOR/READY/FAILED，向量化进度）。长时间停在 PENDING_VECTOR 或转为 FAILED 时，平台有定时扫描自动重试，无需重新上报。

不支持时（已输出 NO_FEEDBACK_CMD，或无 findingKey），不要报错中断流程，降级处理：把每个上报项整理成一段可直接粘贴的内容（reviewId + findingKey + path:startLine + category + 你写的 reason），提示用户到平台 Web 端 bad-case 页面上报，并说明 CLI 需升级到支持反馈命令的版本。

C 分支：暂不处理

• 在正文说明该项已由用户决定暂不处理，本次不再改动；
• 若 CLI 支持，可执行下面命令记录决策；不支持则跳过，不必强行上报：

richinfo-cr finding ignore --review <reviewId> --finding <findingKey> --format json

必须区分的语义：暂不处理 与 上报为误报 完全不同——前者代表认可问题但本次不改，后者代表认为审查结果根本不成立。绝不要把「暂不处理」也作为误报上报，否则会污染平台 bad-case 库，导致后续同类真实问题被错误抑制。

索引状态真伪判定

> 本节以 CLI v0.2.0 的实际行为为准（managedCodeGraph.Init + codegraph.IndexStatus.Complete()，引入于 f634500，自 0.2.0 起随包发布）。v0.1.9 及更早不读 status 分支，会把被中断的索引当「已初始化」跳过修复——在旧版 CLI 上排查时不要套用本节结论。

initialized: true 不等于索引可用——一个被强杀打断的索引同样满足 initialized。判断索引真伪的唯一权威口径是引擎自报的 codegraph status --json（不要只看 doctor：inspectLocalIndex 只检查「是否初始化 / 是否需重建 / WAL 是否 >1 GiB」三项，检不出下面这类半成品）。

# 在目标仓库内执行；CG 为 CLI 托管的那份二进制
CG=$(ls -d ~/Library/Caches/richinfo-cr/codegraph/versions/*/codegraph-*/bin/codegraph | tail -1)
cd <repo> && "$CG" status --json

判为半成品（典型组合：state=indexing + pendingRefs 数万 + 残留锁）时，直接跑 richinfo-cr init --format json 即可，不要手动删 .codegraph。v0.2.0 起 init 会先读一次 status 再决定动作（managedCodeGraph.Init）：

⚠️ 两个容易看错的地方：① builtWithVersion=null 时 reindexRecommended 必为 true，会走全量重建这条最贵的路径——doctor 的「引擎已升级 / 需全量重建」说的就是它，但成因是"没建完"而非"要升级"，执行前先按第 1 步核算规模（pc_client 排除 ext/ 后全量重建约 54 秒）；② rm -rf .codegraph 只在你确认要重来一遍时才做——它会把可续跑的检查点也丢掉，属于最贵的选择，不是首选。

常见故障处理（本机实测）

审核耗时参考（本机实测）：3 文件小改约 2 分钟；34 文件变更约 12~15 分钟；pc_client 这类 C/C++ 大仓 5 文件单次约 11~16 分钟（三专家并行）。命令超时建议给足（≥600s）；前台等待被工具 SIGTERM 掉（退出码 137）不会丢失审核，按第 2 步的 --no-wait 方式跟进即可。

命令速查

参考资料

• references/finding-schema.md：finding 字段语义、严重度映射与 3 种处理动作。
• references/codegraph-probe.md：核验 CodeGraph 版本能力（命令面、status --json 真实字段、迁移门闸、daemon 行为）的可复现步骤，以及索引体积/耗时的估算法与实测标定。以下三种情况先读它，不要凭印象下结论：① 判断「某能力属于哪个版本」或升级 CodeGraph pin；② 估算某仓库的索引代价（体积 / 耗时），或要回答"这个大仓值不值得建索引"；③ 索引异常（半成品、WAL 泄漏、需全量重建）时定因。