dsh-ua-headers

dsh-TUI · 一个为 dsh-TUI 生态打造的插件

一个遵循 dsh-ecosystem-spec（dsh-std Community v0.15 / TUI Admission v0.15）的 DSH 插件：自定义所选模型调用时的 User-Agent，并加入自定义请求头。

功能

• 自定义 UA：匹配到的模型请求会替换 User-Agent；留空则保留 DSH 默认 UA。
• 加入请求头：以 JSON 对象配置任意 HTTP 请求头（如 X-Trace-Id、Authorization-Override 等），会合并进模型请求。
• 按模型匹配：支持 * 全部模型、精确模型 ID、deepseek-* 前缀匹配、*pro 后缀匹配。
• 声明式设置项：通过 tui.dsh/v1alpha1 SettingsSection 贡献 host-rendered 设置页，跨 TUI / Web 一致呈现。
• 标准配置存储：配置经 storage.dsh/v1alpha1 LocalStorage 协议持久化，带命名空间隔离与权限模型（storage.local.read / storage.local.write）。

生态结构

文件	说明
dsh-plugin.json	标准 manifest（唯一发现入口）：声明 facet、协议 requirement、权限、设置项贡献，以及 fetch patch 的 overrides 声明
lib/index.js	Host facet 入口（@dsh-std/sdk defineFacet）：配置读写走 LocalStorage，globalThis.fetch patch 收敛为单 owner 并在 deactivate 时恢复
package.json	依赖 @dsh-std/sdk、@dsh-std/storage

关于 fetch patch

改写模型请求 UA / 请求头在生态中尚无标准「请求中间件」协议，故该行为在 dsh-plugin.json 的 overrides 中以 kind: "patch" 显式声明，供 adapter 的 provenance / admission 审计。这是当前生态下最诚实、功能不缩水的折中方案；一旦出现标准协议，将迁移到标准机制。

安装

从 GitHub 安装（源码）

dsh plugin --profile web add github:fplj-fplj/dsh-ua-headers

从 npm 安装（推荐 / 可被 DSH Market 收录）

dsh plugin --profile web add dsh-ua-headers

安装后重启 DSH 服务。插件通过 dsh-plugin.json 被发现与激活，无需手动修改任何宿主配置文件。

DSH Market

本插件已发布到 npm，并提交到 DSH 1024Store / deepseek1024.com。在 DSH 设置 → 插件市场中搜索 dsh-ua-headers 即可找到。

使用

1. 打开 DSH 设置。
2. 进入「UA 与请求头」设置页。
3. 打开“启用自定义 UA 与请求头”。
4. 填写 User-Agent；留空则不改写 DSH 默认 UA。
5. 填写模型匹配规则（逗号分隔）：* 表示全部，或如 deepseek-v4-pro, deepseek-v4-flash、deepseek-*、*pro。
6. 填写请求头 JSON，例如：

{
  "X-Trace-Id": "my-trace-id",
  "X-Request-Source": "dsh"
}

7. 保存。下一次匹配的模型调用即生效。

开发 / 校验

环境要求：Node.js 20+。

npm install

对 manifest 做生态准入校验（使用 dsh-ecosystem-spec 的 conformance suite，与市场准入共用同一套 admission 算法）：

npm run validate:manifest -- --manifest ./dsh-plugin.json

说明

• 插件在 Host 进程 patch globalThis.fetch，拦截 OpenAI 兼容的 /chat/completions（及 /responses）POST 请求，读取请求体中的 model 字段并与配置匹配；deactivate 时恢复原始 fetch。
• 只有匹配到的模型请求会改写 UA / 合并请求头，其他 HTTP 请求不受影响。
• 自定义请求头会覆盖同名请求头；未出现过的请求头会新增。
• 请求头名称必须是合法 HTTP token，值不能包含换行或 NUL。
• 配置通过 LocalStorage 协议读写；协议或权限不可用时降级为默认配置并告警。