请求头注入 chenyifawan-cell/dsh-litellm-extra-headers

dsh-litellm-extra-headers

给 DeepSeek Harness 用的宿主插件：把 extra_headers: { "": "<value>" } 塞进 OpenAI 兼容请求的 body，只对「配置里列出的 provider 路由」+「配置里列出的上游 host」生效。

用途：绕过 LiteLLM 之类的反向代理丢弃客户端 HTTP 头的问题——某些上游（例如 OpenCode / 网关自建的会话亲和）要求每个请求带 x-opencode-session，而代理只在 body.extra_headers 里认这个字段。

为什么只能这么做（已核实，改动前先读）

1. 客户端 HTTP 头在 LiteLLM 这一跳被丢弃。 实测把 x-opencode-session 加在请求头上，上游仍然 500；改放 body.extra_headers 后 200。
2. DSH 的 llm-pi-ai 适配器只白名单转发 temperature / maxTokens / sessionId / signal / headers / … 这些字段（见其 profileOptions()），pi-ai 唯一能塞任意 body 字段的入口 options.samplingParams 在 DSH 里没有暴露，所以纯配置解决不了。
3. 现成的 dsh-opencode-session 插件是「加 HTTP 头」的，在这条链路上注定无效；而且它的默认 providers 是 pi-ai 目录里的 ['opencode', 'opencode-go']，不含自定义路由键（如 gwds、go）。
4. pi-ai 的 openai-completions 走官方 openai SDK（v6.40.0），SDK 通过 this.fetch = options.fetch ?? globalThis.fetch 调用 globalThis.fetch。因此运行时替换 globalThis.fetch 是当前唯一可用的宿主侧注入点。

结论：不要在别处再加 header，那条路已经验证过是死的；要新字段就往 body 里合。

安装

已发布在 npm：dsh-litellm-extra-headers@0.1.0

npm（推荐）
dsh plugin --profile web add dsh-litellm-extra-headers

从本地目录（开发时推荐，link 安装，改动即时生效）
dsh plugin --profile web add ./dsh-litellm-extra-headers
从打包产物
dsh plugin --profile web add ./dsh-litellm-extra-headers-0.1.0.tgz
从 git 主机（本包是纯 JS，无需 pnpm 放行构建脚本）
dsh plugin --profile web add github:chenyifawan-cell/dsh-litellm-extra-headers

包内 cordis.patch.yml 会插入一行插件；dsh plugin add 识别到 dsh.bundle 后自动把本包加进该 profile 的 bundles 列表。装完确认一层存在：

dsh --profile web --dump-config | Select-String litellm-extra-headers

不想装包也可以手工把这一行写进 profile 的 cordis.patch.yml（行指向本包名或 index.js 路径）。包内自带的这一行 providers / hosts 默认留空（空列表 = 插件保持惰性），把你的路由键和上游地址填进去才生效：

- insert:
- id: litellm-extra-headers
name: dsh-litellm-extra-headers
config:
providers: [gwds, go] # 你的路由键
hosts: ["litellm.internal:4000"] # 只有这些上游才注入
header: x-opencode-session
mode: session-id
value: null
debug: false
debugFile: null

配置字段

| 字段 | 类型 | 默认 | 说明 |
| providers | string[] | [] | llm/stream 的 options.provider 路由键白名单。必须显式列出，匹配大小写不敏感。 |
| hosts | string[] | [] | 允许注入的上游 host[:port] 白名单；带 scheme / path 的写法会被归一化（http://litellm.internal:4000/v1 → litellm.internal:4000）。必须显式列出。 |
| header | string | x-opencode-session | 放进 extra_headers 的字段名。 |
| mode | session-id \| uuid \| fixed | session-id | 取值来源：DSH 会话 id（跨轮次、跨重启稳定）／每会话一个进程内随机 uuid／配置里的字面量。 |
| value | string | — | mode: fixed 时的字面量；fixed 却没给值会在加载时报错。 |
| debug | boolean | false | 每次注入决策打一条 ctx.logger.info。 |
| debugFile | string | — | 每次注入决策追加一行 JSON（含 provider / model / session / host / path / event / reason），进程控制台看不到时用它排错。 |

providers 或 hosts 为空时插件保持惰性并打一条 warning：一个可以共享出去的包，不应该对别人没被告知过的网关偷偷加字段。

设计要点

1. 双层匹配，缺一不可。
- llm/stream waterfall 里判断 options.provider ∈ providers 且存在 options.sessionId，才把 { value, provider, model, session } 放进 AsyncLocalStorage（这一步才有路由键）。
- fetch patch 里再判断目标 URL 的 host ∈ hosts 才改 body。
- 于是别人路由键跟你不同时，只会改白名单里的网关，不会给别人的网关塞未知字段。
2. 只改 /chat/completions 的 JSON body。 条件是 method === 'POST' + content-type 含 application/json + typeof init.body === 'string' + pathname 以 /chat/completions 结尾。解析失败一律原样放行；extra_headers 已存在时合并而不覆盖，已有同名字段时尊重调用方、不覆盖。
3. 零依赖 + 可还原。 只用 node:async_hooks / node:crypto / node:fs/promises；安装与卸载都是 ctx.effect()，dispose 时 globalThis.fetch 按引用还原（被别人又包了一层也不会误还原）。

验证

npm test # node --test：条目命中 / 非命中 / 已存在不覆盖 / 非 JSON 原样 / dispose 还原（19 项）
npm run test:e2e # 真机链路：本地 mock 上游 + 真实 dsh headless 跑一轮，对照组不带插件

按顺序，前一步不过不进下一步：

1. npm test 全绿。
2. npm run test:e2e：起一个会记录请求体的本地 OpenAI 兼容上游，用 dsh --profile headless --patch 把 provider 指向它并挂上本插件，跑一轮真实会话。断言：命中的请求 body 里多出 extra_headers、值在整轮里稳定（同一个会话 id）、对照组（去掉插件行）没有这个字段，并且 debugFile 有 event: "inject" 记录。
3. 换到能连到 LiteLLM 的那台机器上（第 2 步用的是本地 mock 上游，不需要网络）再跑一轮，用 debugFile 确认日志里出现注入记录，且上游不再报缺少会话头。这一步验证的是 LiteLLM 自己的「body.extra_headers → 上游请求头」合并行为，只有真实网关能证明。
对照实验：手动 curl 只带 HTTP 头、不带 extra_headers → 上游报错；body 里带 extra_headers → 通过。

发布备忘（首次发布踩过的坑）

1. 2FA 必须开：npm 只支持安全密钥（Windows Hello 指纹/PIN 或 YubiKey），没有 Google Authenticator 那种 TOTP。
2. npm publish 要在真终端里跑：npm 只在 stdin/stdout 都是 TTY 时才走「自动开浏览器 → 轮询授权 → 自动重试上传」那条路（lib/utils/auth.js 的 otplease）；管道化的非交互进程会直接抛 EOTP，而错误文本里的授权 URL 被 @npmcli/redact 打码，等于拿不到链接。
3. 新包名会先进审核：首次发布会先在 registry 上生成一个 0.0.0-stage 占位版本（"Temporary package placeholder for staged publishing"），真正的版本进入审核，CLI 只提示 Your package is being processed。几分钟后正式版本自动上线，latest 指向它，占位版留在历史里。期间 npm stage list 可能为空，不用慌。
4. 发布前记得 --registry=https://registry.npmjs.org：本机若把 registry 指向 npmmirror 这类只读镜像，默认 npm publish 会打错源。

已知边界

- input 是 Request 对象时（body 在 Request 里，同步读不出来）不改，原样放行；当前 pi-ai + openai SDK 走的是「URL 字符串 + init.body 字符串」，不触发这条。
- extra_headers 存在但不是普通对象（数组 / 字符串等）时原样放行，避免把别人的 body 改坏。
- 只注入，不做重试、不改 header、不改其它 body 字段。

English summary

Host plugin for DeepSeek Harness: while a model call routed to a configured provider streams, globalThis.fetch merges extra_headers[] = <value> into the JSON body of POST .../chat/completions requests sent to a configured upstream host. It exists because a LiteLLM relay drops client HTTP headers (verified: header-only 500, body extra_headers 200), DSH's pi-ai adapter whitelists request fields, and the existing dsh-opencode-session plugin only sets a header. Both providers and hosts must be listed explicitly, or the plugin stays inert. MIT.

License

MIT