推理服务诊断 xiciyang/inference-diagnose

@xiciyang/inference-diagnose

用证据诊断推理服务，不靠猜——证据不足时，就直说「未确认」。

生成采集脚本 → 离线解析脱敏报告 → 给出按优先级排序的根因和修复方案 → 修复失败，就只补采缺失的探针，再和上一轮做 diff。
全程离线、去标识化、审计哈希链；framework × runtime × hardware 组合缺规则时，直接 fail-closed。

- 日志不出本机：采集在用户机器上跑，解析和诊断都在内存里完成，不走云端往返。
- 证据驱动：每条结论都带严重度、置信度和证伪条件；「未确认」也是有效结论。
- 三种模式：服务故障（A）、相对客户基线的劣化（B）、一致性 / 非确定性（C）。
- 五个工具，全部 risk: read——不写盘、不需要沙箱、不需要确认令牌。

安装

git clone https://github.com/xiciyang/inference-diagnose.git
cd inference-diagnose && bash scripts/build.sh
dsh plugin --profile <name> add .

尚未发布到 npm；按上面的源码路径装完，重启生效。

要求 Node ≥ 20，已在本机 DSH 0.2.0-rc.2 上验证。

从源码构建：

bash scripts/build.sh # 27 个文件 → lib/
node tests/run.mjs # 30 spec，无 GPU / 无容器 / 无网络

用法

在会话里直接调用五个工具（裸名，无 inference_ 前缀）：

| 工具 | 作用 |
| generate_collect_script | 生成内嵌脱敏的采集脚本（在用户自己的机器上执行，本插件不代执行） |
| parse_collect_report | 解析已脱敏报告 → 结构化证据（全程内存，明文不落盘） |
| diagnose_service | A 范式：服务异常（崩溃/启动失败/挂起/被外部杀/资源耗尽/输出异常） |
| diagnose_regression | B 范式：相对客户基线的性能/精度劣化（无基线则退化为定性诊断） |
| diagnose_consistency | C 范式：一致性/非确定性 |

典型链路：generate_collect_script → 用户在目标机执行 → parse_collect_report → diagnose_service；修复失败后，用返回的 nextSteps 只补采缺失探针，再调一次 diagnose_service（带 priorRound）看 diff。

配置

| 变量 | 作用 | 默认 |
| INFERENCE_DIAGNOSE_ROOT | 审计链与运行状态根 | ~/.ai-infra |
| DSH_HOME | 会话存储根 | ~/.dsh |
| INFERENCE_WORKSPACE | 跑「与兄弟插件工具名不重名」检查时的源码目录 | 未设置则跳过该检查 |
| SPEC_ROOT | 设计文档仓（门禁 2–4） | 未设置则跳过 |

三维词表是 L1 数据：assets/config/dims.json + assets/dimensions/<kind>/<id>.yaml。
新增一个维度取值 = 加一个 YAML + 在 dims.json 登记 + 配规则文件；缺规则文件会让该组合 fail-closed（ERR_ROOTCAUSE_RULES_NOT_LOADED），不会静默降级。

framework：mindie（Ascend）· vllm；runtime：docker； hardware：ascend-arm · gb10 · nvidia · cpu。

治理面

- 风险分级：五个工具全部 risk: read / sandbox: none / confirmation: not-required。
声明面在 manifest.yaml（给人/审计看）与 src/governance/risk.js（给代码看），由 tests/unit/governance.spec.mjs 断言逐工具相等，并与实际注册工具名双向一致。
- 审计哈希链：每次调用追加到 $INFERENCE_DIAGNOSE_ROOT/logs/audit/inference-diagnose/<YYYY-MM-DD>.jsonl； hash = sha256(canonicalJson(record 去掉 hash))，prevHash 首尾相接，只追加（O_APPEND + 0600）。
记录只存参数摘要与参数名，绝不存参数值。
- 复算：node scripts/verify-audit.mjs [--root R] [--day D] [--tail N]，链损坏 exit 1。

兼容与门禁

- DSH bundle：已声明 dsh.bundle.patch + engines.dsh；entry id 为 inference-diagnose，npm 名为 @xiciyang/inference-diagnose。
- node tests/run.mjs：30 个 spec 全部通过（本机实测），只收集 tests/unit/ 与 tests/integration/。
- bash scripts/verify-all.sh：spec 套件 +（可选）状态机穷举与兄弟仓契约；缺少外部仓时显式 SKIP，不伪造通过。
- 真机端到端脚本在 tests/realmachine/，不进 CI（见其 README）。

许可

BSD-3-Clause。见 LICENSE。