前言¶
DeepSeek Harness（DSH）开发智能体时，配置层面的变更（如注册新工具、修改系统提示词、调整采样参数）很容易导致调用行为发生漂移。开发者通常需要在本地调试或 CI 环境中验证请求参数是否与预期一致。
dsh-modelprint 专注于解决“当前请求的配置指纹是否与上一次已知良好的配置一致”这一问题。它不依赖网络请求或模型加载，仅通过读取本地文件进行对比。
这是什么¶
这是一个 DSH 插件，用于对每次请求的配置进行指纹识别，并通过 modelprint_check 工具对比当前 live card 与 pinned card，检测配置漂移。
插件由 jwilson411 维护，基于 MIT 许可证开源。其核心价值在于提供一种轻量级的配置一致性检查手段，帮助开发者确认 Harness 在组装请求时，是否使用了预期的 provider、model id、sampling、tool schemas 以及 system-prompt prefix。
核心功能¶
1. 请求指纹识别¶
插件会对 DSH 发出的请求进行标准化，生成一个“card”，包含以下字段：
* provider：提供者名称。
* model：实际发送的模型 ID。
* temperature：采样温度。
* top_p：采样核值。
* tools_hash：工具列表的 SHA-256 哈希值。
* system_prompt_prefix_hash：系统提示词前缀的 SHA-256 哈希值。
2. 配置对比与漂移检测¶
通过 modelprint_check 工具，将生成的 live card 与本地的 pinned card 进行比对。如果存在差异，工具会返回所有不一致的字段名称。
3. 零依赖与轻量化¶
- 不涉及网络请求。
- 不加载模型。
- 无需密钥。
- 仅依赖读取 pin 文件进行 I/O 操作。
4. 灵活的配置路径¶
支持通过 cordis.patch.yml 配置 pinPath，也可以通过环境变量 DSH_MODELPRINT_PIN 或默认路径 modelprint.pin.json 指定 pin 文件位置。
安装与启用¶
使用官方 CLI 命令安装该插件：
dsh plugin --profile web add github:jwilson411/dsh-modelprint
安装后，插件会自动将其 dsh.bundle.patch 声明附加到 profile manifest 中，并加载 cordis.patch.yml 配置层。
典型用法¶
1. 配置 Pin 路径¶
在 cordis.patch.yml 中配置 pin 文件的路径。优先级为：配置文件中的 config.pinPath > 环境变量 DSH_MODELPRINT_PIN > 默认的 modelprint.pin.json。
- id: modelprint
config:
pinPath: ./modelprint.pin.json
2. 生成 Pin 文件¶
第一次使用时，可以调用 modelprint_check 并指定一个不存在的 pin 路径，从返回的 PIN_MISSING 结果中复制 live 字段内容，生成 pin 文件。
{
"provider": "deepseek",
"model": "deepseek-chat",
"temperature": 0.2,
"top_p": null,
"tools_hash": "841e5f22...",
"system_prompt_prefix_hash": "d2c86f05..."
}
3. 调用检测工具¶
在代码或 CLI 中调用 modelprint_check 工具。如果不指定 pin 参数，则使用配置的路径；若指定 request_json，则仅对当前请求进行指纹比对，不会覆盖 pin 文件。
适用场景与注意¶
适用场景¶
- 在 CI/CD 流程中验证 Harness 配置是否发生变化。
- 在本地开发中确认工具注册顺序或系统提示词是否意外修改。
- 需要快速排查请求参数异常的调试环节。
注意事项¶
- 非认证产品：此插件不是水印检测、权重交换检测或模型认证工具。它只能证明发起请求的一侧配置未变，无法证明模型本身未被替换。
- 故意误报：插件在检测到工具列表或系统提示词发生有意更改时，会产生误报。这是设计特性，旨在区分“有意的配置变更”和“意外的配置漂移”。
- 环境要求：需要 Node.js 版本 >= 22.14.0。
- 依赖关系：插件依赖于
@deepseek-ai/dsh-tools版本^0.1.1-rc.2。
总结¶
dsh-modelprint 提供了一种基于配置指纹的漂移检测机制。通过将请求参数固化到 pin 文件中并定期比对，开发者可以更清晰地掌握 Harness 的行为轨迹。
