前言¶

在 DSH（DeepSeek Harness）里跑 OpenAI 兼容路由时，模型实际落在哪条检查点、网关有没有悄悄换上游，往往只能事后翻日志或抓包。官方响应里的 system_fingerprint 能对应检查点，但 UI 里通常不会直接展示；走第三方网关时，指纹字段还可能根本不存在。

下面介绍社区插件 dsh-system-fingerprint（维护者 Mizumic，分类：模型推理）。它在会话头部显示当前模型检查点或网关请求级溯源，主动探测 system_fingerprint 并映射成可读名称，同时拦截响应元数据做存证与端点登记；原始响应字节默认不落盘。插件以独立 bundle 分发，不写本机绝对路径进仓库，供应商映射可配置。

目录页：https://www.skillhub.cn/plugins/Mizumic/dsh-system-fingerprint
源码：https://github.com/Mizumic/dsh-system-fingerprint（MIT，当前包版本 0.3.0）

这是什么¶

dsh-system-fingerprint 是 DSH Web 插件：宿主半边注册 API 与响应拦截，浏览器半边在会话头部注入「检查点 / 网关溯源」徽标。

两条信息通路可以概括为：

会话模型路由（provider/model）
    ├─（主路）主动探测：POST <同层端点根>/chat/completions → response.system_fingerprint
    │        └─ 内置 MD5 映射表 → 检查点名
    └─（证据/兜底）fetch 拦截：模型响应解码前 clone，解析元数据（默认不落原始字节）
             └─ 解析 system_fingerprint / model / x-ds-trace-id；记录真实对话 URL / host
             └─ 上游不返回指纹时，解析响应头里的网关溯源头
             └─ 仅 captureRaw: true 时把原始字节写到 $DSH_HOME/storages/system-fingerprint/raw/

插件是被动层：单独安装即可工作；可选的外部行为监测工具只读本插件产物，不装也不影响徽标与存证。

环境要求¶

核心功能¶

徽标与交互¶

• 已知指纹：显示映射后的检查点名，例如内置表中的 flash 1017。
• 映射表未收录：显示原始 32 位 system_fingerprint（md5），不猜测、不冒充。
• 网关路由（上游不返回指纹）：徽标直接显示上游端点名；悬浮卡给出后端池、上游路由、请求 id，并标明「这不是模型指纹」。取不到端点名时回退为「网关溯源」；尚未抓到真实响应时显示「不适用」。
• 悬停：自定义卡片展示模型、检查点、指纹、明文、来源、探测端点、同层可信度、trace id、稳定性、存证开关状态等；长字段自动换行。
• 点击：绕过缓存强制重新探测；可见时约每 10 分钟轮询一次（探测为真实计费请求）。
• 可选行为告警：配置 externalAlertFile 读取外部只读告警 JSON；warn/critical 时徽标追加警示标记，文件缺失或损坏时静默降级。

同层探测可信度不是 high 时，圆点转警示色并在卡片中说明原因。

隐私默认¶

分发语义以隐私优先（README 自 2026-10 起）：

请求体只解析 model 字段，不保存 prompt。默认配置下 raw/ 目录应为 0 个文件（由测试断言锁定）。

对外契约（v1）¶

插件代码不引用外部监测项目，只写自己的存储目录；meta.json / raw/ 为内部产物。

内置检查点映射（默认值）¶

完整明文与 md5 见仓库 README；换供应商时可替换 checkpointTable 配置。

安装与启用¶

插件是 DSH bundle（package.json 的 dsh.bundle.patch 指向 cordis.patch.yml），并注入浏览器模块 lib/client.js。机器相关路径由符号映射定义，详见仓库 docs/SYMBOLS.md 与 docs/AGENT-INSTALL.md（含离线验证、安装、回滚步骤）。

取得发行包或本地目录后，在 DSH 中安装 bundle，例如：

# 在 DSH 里用插件管理器安装（绝对路径或 npm 包名均可）
# plugin_manager install_bundle('/绝对路径/dsh-system-fingerprint')

或在 profile 的 dsh.profile.bundles 中以 link: 引用本目录（开发时）。

装好后：

1. 重新启用 bundle 后宿主半边立即生效，浏览器半边需刷新页面。
2. 会话头部右上角出现徽标；无凭据时显示「缺少凭据」。
3. 卸载：从 profile 的 bundles 去掉本包并刷新页面。

README 说明：勿在发行配置中写 file:// 绝对路径；开发期可通过 patch 里递增 ?v=N 热加载宿主单文件模块。

配置要点¶

在 profile 的 cordis.patch.yml 覆盖本插件行的 config（包内 cordis.patch.yml 为模板）。常用项：

非 provider 配置的路由：若响应里实际带 system_fingerprint，徽标仍优先采用；既不返回指纹又没配网关溯源头时显示「不适用」，不会借用其他路由的检查点。

典型用法¶

1. 配置 DEEPSEEK_API_KEY（或 apiKeyEnv 指向的变量），安装 bundle 并刷新 Web 页面。
2. 在目标会话中发起至少一次真实模型对话，让拦截层记录同源端点；观察头部徽标是否为检查点名或 md5。
3. 悬停查看探测端点、同层可信度与最近对话响应时间差；需要强制刷新时点击徽标。
4. 若走不带 system_fingerprint 的网关，确认 gatewayHosts / gatewayHeaders 与供应商响应头一致，徽标应显示端点名或「网关溯源」。
5. 需要脚本或监测工具消费状态时，请求：

GET /api/system-fingerprint/state?sessionId=…&provider=…&model=…&refresh=1

模型解析优先级：query > 会话 modelSelection > 已拦截的 llm/stream > 默认模型 > 配置。

存证或审计若必须保留原始响应体，在配置中显式设置 captureRaw: true，并注意 maxRawBytes（默认 524288）与 maxRawFiles（默认 120）的存储上限。

适用场景与注意¶

适合谁：需要在 DSH 会话界面一眼确认检查点或网关路由的开发者；需要端点登记表与元数据存证、又不想默认落盘全量回复正文的团队；可与只读消费 endpoints.json / config.json 的监测工具配合，但插件本身不依赖这些工具。

开销：主动探测会向配置的端点发送真实 chat/completions 请求（计费）；页面可见时每 10 分钟轮询一次。

安全与信任：插件以当前 DSH 进程权限运行，会拦截经 connection.fetch 的模型流量并写入 $DSH_HOME/storages/system-fingerprint/。安装前请阅读源码与 MIT 许可证，确认 capture / captureRaw 与网关 host 列表符合本机合规要求；凭据不应出现在 config.json 导出中。

生态说明：DSH 社区插件目录（SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；本仓库 README 标明为可分发型独立仓库，不修改 DSH 宿主源码。

验证状态：仓库 CI 与 README 记载离线/宿主测试共 218 项通过（以仓库当前 badge 为准）。

结尾¶

dsh-system-fingerprint 把 system_fingerprint 探测、可配置网关溯源和响应元数据存证收敛到会话头部一条徽标里，默认不把模型回复原始字节落盘。若你已在 DSH 0.2.0-rc.2 及以上环境使用 OpenAI 兼容路由，可按 docs/AGENT-INSTALL.md 安装 bundle 并在 profile 中按需覆盖 config。

• 目录页：https://www.skillhub.cn/plugins/Mizumic/dsh-system-fingerprint
• GitHub：https://github.com/Mizumic/dsh-system-fingerprint