# DSH 模型监控（独立本地插件）

[English](README.md)

此包独立存放、构建和安装，不修改 deepseek-harness 的源码、workspace、锁文件或内置插件列表；Web 版和桌面端都可用。它不是 DeepSeek 官方插件，与 DeepSeek 没有隶属或背书关系；沿用原包名 `@deepseek-ai/dsh-model-audit` 只是为了迁移已有配置——本包没有发布到 npm，该包名仅在本机使用，请不要把它发布到 DeepSeek 的 npm scope 下。许可证为 [MIT](LICENSE)。

## 安装和使用

需要已安装的 DSH Web 版。此插件版本为 `0.1.7-rc.2`，对应验证的 DSH 版本也是 `0.1.7-rc.2`，Node 要求与 DSH 一致。

1. 将整个插件目录放在官方仓库之外，或使用分享包 `.tgz`。
2. 在 DSH 的「插件 → 添加插件」中填写插件的绝对路径；也可运行：

   ```sh
   dsh plugin --profile web add /absolute/path/to/dsh-model-audit --offline --ignore-scripts
   ```

3. 插件出现在「已安装」列表。桌面端由应用独占管理 profile，命令行会拒绝 `--profile desktop`，请在桌面应用的插件页里添加插件的绝对路径。用外部目录首次安装时，先重启 DSH 一次，让宿主建立外部包的依赖解析；之后可直接通过开关启停。启用「模型监控」，点开详情中的「打开监控」。
4. 分别选择 DeepSeek、GPT 发送「只回复 OK」，页面应新增请求，显示实际请求模型和上游声明模型。不能读到模型字段或未经过支持的传输时，显示待确认/未观测，不推断为一致。
5. 「打开监控」按界面区分：网页版在新标签页打开监控页；桌面端直接在应用窗口内显示，因为桌面壳会拒绝 `dsh-app:` 协议上的所有弹窗。桌面端视图读取同一个鉴权页面并渲染在同源框架里，用页头「关闭」或 Esc 退出。宿主侧代码改动仍需重启桌面应用一次，已导入的模块会在该进程内保持缓存。

使用源码版 DSH 时，在官方仓库里把 `dsh` 换成 `node --import tsx/esm apps/cli/src/bin.ts` 即可，不需要改任何官方文件。

安装包已包含前后端产物和 SSE 解析器，无需额外启动 Python、代理或采集器。关闭监控页面后仍采集；关闭插件后停止采集并清空内存记录。默认最多保留 500 条，可导出 JSON。

从仓库内旧版本迁移时，用同一命令添加外部目录，原启用状态保留。DSH 不支持在同一进程里重定向已经加载的包；路径变更后需重启 DSH 一次。重启会清空监控内存记录，需保留时先导出。

从 `0.1.7-rc.1` 升级时，安装新版目录或 `deepseek-ai-dsh-model-audit-0.1.7-rc.2.tgz`，然后重新加载 DSH，让宿主重新读取插件版本和依赖。新版通过 DSH 原生兼容性校验，不需要添加版本豁免；`0.1.7-rc.1` 不再通过校验，因为 DSH `0.1.7-rc.2` 拆分了 Messages 适配器配置，插件的测试夹具现在为 API Key 路由加载 `@deepseek-ai/dsh-llm-deepseek-api-key`。仍使用旧版 DSH 的用户应保留对应的旧插件包。

卸载可以使用原生插件页，也可运行：

```sh
dsh plugin --profile web remove @deepseek-ai/dsh-model-audit
```

## 与官方同步

插件源代码、构建配置、测试和产物都在本目录，安装信息只写入 DSH 用户目录的 profile。更新官方仓库无需合并模型监控补丁，也不会删除本目录。

运行时使用宿主提供的 Cordis、LLM 和网页服务。DSH 的插件接口仍在演进；官方更改接口时需要单独适配本插件，不能保证未来每个版本无需更新。

## 采集范围

- DeepSeek Messages、GPT Responses 和 Chat Completions，支持 HTTP JSON/SSE；同一个真实 HTTP 请求对比其请求模型与返回模型。
- Responses 优先读取终态 `response.model`；流中模型名冲突、缺字段或传输未被观测时保留未知。
- 主对话、自动标题和上下文压缩分别标记，避免把后台模型误认为用户选择的主模型。
- 仅保存模型名、响应 ID、Token、耗时和用途等元数据；不保存输入正文、回复正文、API Key、请求头或原始错误。
- 页面沿用 DSH 登录、来源校验与同源路由，支持 HTTP 和反向代理子路径。

仅观测经过 `llm/stream` 且使用全局 `fetch` 的调用。WebSocket、SDK 私有传输、提前缓存的 fetch 和回放不在采集范围。请求正文需是可解析的 JSON 字符串；不会消费 `Request`/流式正文。模型名称来自上游声明，不能证明真实模型权重或算力。

## 独立开发和验证

普通使用者无需运行这些命令。维护者可以从 npm 准备开发依赖，或复用已安装依赖、已构建的原版 DSH：

```sh
node scripts/link-dev.mjs /absolute/path/to/deepseek-harness
npm run build
npm test
DSH_SOURCE=/absolute/path/to/deepseek-harness npm run test:web
npm pack --ignore-scripts
```

`link-dev.mjs` 只在本插件的 `node_modules` 建立开发链接，绝不写入官方仓库。构建配置独立，不导入官方构建脚本。网页集成测试通过 `DSH_SOURCE` 使用原版 DSH 测试夹具，验证「已安装」分类、启停、打开页面和反向代理子路径；此环境变量不是运行插件所需。

构建时仅将 `eventsource-parser` 内联，许可见 [THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt)。宿主框架以 peer dependency 使用同一个运行时实例，避免复制服务或持有第二套模型状态。

## 仓库结构

- `src/`：宿主半（`index.ts`、`monitor.ts`、`parser.ts`、`dashboard.ts`、`locales.ts`）与浏览器半（`src/client/`）。
- `lib/`：随仓库提交的构建产物（`lib/index.js`、`lib/client.js` 及类型声明），DSH 实际加载的就是它；`npm run build` 重新生成。
- `tests/`：监控单元测试、跑真实 DeepSeek/GPT 适配器的 Loader 组合测试、浏览器集成测试，期望输出在 `tests/expected/`。
- `scripts/link-dev.mjs`：把本插件的开发依赖链接到已构建的官方 checkout，不修改官方仓库。
- `dist/`：本机 `npm pack` 产物，不纳入版本管理。

宿主版本是精确匹配的：本版本针对 DSH `0.1.7-rc.2`，DSH 遇到不兼容的插件会直接拒绝加载而不是冒险崩溃，因此更新的 DSH 预发布版可能需要同步更新插件。许可为 MIT；产物中唯一的第三方代码是 `eventsource-parser`，所有框架依赖在运行时都使用宿主自带的 DSH 包。