dsh-provider-headers
English | 中文
给 DeepSeek Harness（dsh）的模型设置页加上"自定义请求头"编辑器：在每一个 pi-ai 提供方的卡片里直接增删请求头，并把 ${sessionId} 按会话展开。
不修改任何 dsh 源码，也不修改打包好的应用。 全部通过 dsh 的插件机制完成：UI 走模型设置页官方预留的扩展槽，配置写进 Harness 自带的字段，卸载后完全还原。
它解决什么问题
dsh 本身就支持按提供方配置请求头——llm-pi-ai.providers.<路由>.headers。它会被：
- 合并进该路由的模型请求（
packages/llm/llm-pi-ai/src/adapter.ts） - 合并进该路由的「获取可用模型」请求（
packages/llm/llm-pi-ai/src/discovery.ts）
但这个字段只在 settings.yaml 里手写，模型设置页没有入口（packages/client/ui-settings-models/README.md 明确写了这一点，页面上的提示也让你"直接编辑 settings.yaml"）。
本插件补上这个入口，并额外解决一件原生配置做不到的事：值随会话变化。
安装
需要 Node.js ^22.19.0 || >=24.0.0 和 pnpm。
# 已发布到 npm 后
dsh plugin --profile desktop add dsh-provider-headers
# 从本地目录安装
dsh plugin --profile desktop add /path/to/dsh-provider-headers
# 或者先打包再装
npm pack
dsh plugin --profile desktop add ./dsh-provider-headers-0.1.0.tgz
把 desktop 换成你实际使用的 profile 名（dsh 默认 profile 是 web）。装完重启该 profile，插件的浏览器半才会被页面加载。
本包声明了 dsh.bundle.patch，因此它作为 bundle 插件进入 profile 的 dsh.profile.bundles 层栈——不需要手工写挂载行，设置页也能直接启用 / 禁用 / 卸载它。
卸载：
dsh plugin --profile desktop remove dsh-provider-headers
已写进 settings.yaml 的请求头不会被主动删除。
进入插件市场
npm 上的包本身不会自动出现在市场的设置页里。市场索引由第三方仓库 DSH-Plugins-Marketplace 维护，按 GitHub 的 dsh-plugin topic 全量抓取（约 3100 条）：
- 把本仓库推到 GitHub。
- 打上
dsh-plugintopic；再加deepseek-harness-plugin、request-headers提升搜索命中。 - 在
package.json补repository/homepage/bugs——安装器的"已安装判定"会做包名与 repository 的双向匹配。
索引抓取有延迟，仓库建好不会立刻出现。安装器在 npm 已发布时优先走 npm。
使用
- 打开 设置 → 模型。
- 展开任意一个 pi-ai 提供方（DeepSeek 官方、内置第三方、自定义提供方都算）。
- 卡片里会出现 「自定义请求头（N）」，展开后按
名称/值逐行填写。 - 点 保存。写入位置就是 Harness 原生的那个字段。
以 OpenCode Go 为例
OpenCode 从 09/05 起要求所有推理请求带 x-opencode-session，且需要一个每会话稳定的 ID。在 opencode-go 卡片里加一行：
| 名称 | 值 |
|---|---|
x-opencode-session |
${sessionId} |
保存后，每个会话的请求都会带上属于它自己的 ID。落在 settings.yaml 里是这样：
llm-pi-ai:
providers:
opencode-go:
apiKeyEnv: OPENCODE_GO_API_KEY
headers:
x-opencode-session: ${sessionId}
也可以完全不写占位符，填一个固定值——那部分由 Harness 原生逻辑处理，插件不参与。
${sessionId} 是怎么生效的
Harness 无法自己展开它：一个提供方 profile 按路由解析一次，同一路由下所有会话共用同一个值。
所以插件的宿主半做了两件事：
- 监听
llm/stream瀑布，把一次流式调用放进一个携带该调用会话 ID 的AsyncLocalStorage作用域。 - 在插件生命周期内包装
globalThis.fetch；只有落在上述作用域内的请求才会被附加展开后的请求头。
作用域之外的任何请求原样透传给原来的 fetch，其他插件后装的 wrapper 也不会被本插件卸载时覆盖掉。
只有值里含占位符的请求头走这条路径；固定值的请求头仍然走 Harness 原生逻辑。
配置
- id: model-headers
config:
dynamic: true # 默认 true；设为 false 则完全不安装 fetch 包装与监听器
hosts: [] # 默认空 = 作用域内所有主机；填写则按主机后缀收窄
已知限制
- 只覆盖 pi-ai 路由。
llm-deepseek的Config里根本没有headers字段（请求头是硬编码的），所以 DeepSeek 官方路由的卡片不会出现这个编辑器，需要先改 Harness 本体。 user-agent不能覆盖。 它是 Harness 的归属标识，原生路径与插件路径都会跳过它。${sessionId}只覆盖流式模型请求。 「获取可用模型」是一次由 UI 触发的一次性请求，不经过llm/stream，因此那里仍然发送字面量。固定值不受影响。- 编辑器渲染在卡片里、「编辑」表单之外，因为模型设置页只开放了这一个槽位。
- 请求头的值以普通文本存在
settings.yaml，不会被脱敏。不要把密钥写进请求头，用 Harness 的凭据字段（apiKeyEnv）。
开发与验证
npm test # 两组检查，零依赖，不碰 dsh 运行时
npm run test:load # 真 Cordis 加载检查（需 @deepseek-ai/cordis）
test/verify.mjs—— 宿主半：假 ctx + 记录型fetch，验证展开确实到达线上请求、并发会话互不串号、保留名不被附加、作用域外的请求不受影响、卸载能还原fetch。ctx 是严格代理，读没声明的属性就抛错，与 Cordis 一致。test/verify-client.mjs—— 浏览器半：把client.js当作页面模块队列里的产物加载，用极小的 React 桩驱动组件，验证注册的槽位与 key、以及写出的 path op 恰好落在providers.<路由>.headers上并按 revision 加锁。ctx 同样是严格代理，且允许列表从插件导出的inject推导。test/load.mjs—— 用真的 Cordis 加载宿主半并断言 fiber 到达 ACTIVE。它同时会加载一个故意写坏的孪生插件并要求它 FAILED，否则这个检查全绿也没有意义。
两个已经踩过的坑，以及现在的检查为什么能挡住
一、配置从哪来。 0.1.0 用 ctx.config 读配置，而 Cordis 把配置作为 apply 的第二个参数传入。读未声明的属性会让 apply 抛错，进而整棵插件树加载失败（DSH 是 fail-loud 设计）。只有 test/load.mjs（真 Cordis）挡得住这类错误。
二、点号 inject 不等于服务本身。 0.1.1 声明的是 inject: ['slots', 'remote.settings', 'locale']，却访问 ctx.remote.settings。声明 remote.settings 只表示"等那个命名空间挂载"，不表示允许读 ctx.remote——这是两件事，必须两个都声明。结果插件加载正常，但每次读设置都抛 cannot get property "remote" without inject，编辑器渲染成一条错误。
第二个坑没被拦住，是因为当时的测试手写了允许列表，而我把 remote 也写了进去。现在允许列表从插件自己导出的 inject 推导（只取不含点号的根名，加上核实过存在于 Cordis Context 上的核心方法），手写清单再也无法掩盖"声明"与"访问"的错配。
许可证
MIT
