@xiciyang/inference-diagnose

Diagnose an inference service from evidence, not guesswork — and say "unconfirmed" when the evidence is not there.

Generate a collection script → parse the sanitized report offline → produce a ranked root cause with a fix → if the fix fails, re-collect only the missing probes and diff against the previous round. Offline, de-identified, hash-chained audit, and fail-closed when a rule for the framework × runtime × hardware combination is missing.

• No cloud round-trip for your logs: collection runs on the user's machine; parsing and diagnosis happen in memory.
• Evidence-driven: every conclusion carries severity, confidence and a falsifier; "not confirmed" is a valid verdict.
• Three modes: service failure (A), regression against a customer baseline (B), consistency / non-determinism (C).
• Five tools, all risk: read — no writes, no sandbox requirement, no confirmation token.

安装

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。