dsh-model-session-headers
给 DeepSeek Harness (DSH) 用的插件：按模型（而不是按 provider 路由）给发往网关的请求附加会话 ID 头，内置两种生态的写法：
| 生态 | 请求头 | 谁在读 |
|---|---|---|
| Claude Code | x-claude-code-session-id |
Claude Code 兼容网关 / 中转（按会话聚合流量、计费、粘性路由） |
| OpenCode Go | x-opencode-session |
OpenCode / OpenCode Go（缺头会 400 MissingSessionID，同值请求粘在同一后端以保 prompt cache） |
| 通用 | x-session-id |
LiteLLM / one-api 等自建中转 |
同一个 provider 路由下的两个模型可以走两套头：claude-* 发 Claude Code 头，deepseek-* 发 OpenCode 头，互不干扰。
为什么需要它
DSH 没有"单请求头"的扩展点：GenerateOptions 里没有 headers 字段，每个适配器在 stream() 内部自己拼 wire headers。本插件组合两个官方拦截点补上这一层：
llm/streamwaterfall —— 拿到这次调用的options.provider/options.model/options.sessionId；- 打补丁的
globalThis.fetch—— 真正把头写进出站请求。
AsyncLocalStorage 把补丁的作用域限定在这一次流式调用内，所以 Web RPC、遥测、工具请求等无关 fetch 完全不受影响。
和"provider 级请求头"类插件的区别：那类插件只能对整个路由生效，无法区分同一路由下的不同模型；本插件按模型 id 匹配，粒度更细。
安装
# 本地目录（开发时用，link 安装，改完重启 DSH 即生效）
dsh plugin --profile web add /abs/path/to/dsh-model-session-headers
# 或从 git
dsh plugin --profile web add github:jiangwennn/dsh-model-session-headers
装完重启 profile（bundle 层在启动时读取）。确认层已生效：
dsh --profile web --dump-config | grep model-session-headers
设置界面
web profile 里，打开「设置 → 插件 → Installed plugins → dsh-model-session-headers」，可以直接编辑规则：添加/删除、填模型 glob、选 flavor、启用开关。保存后无需重启，下一次模型调用即生效。
保存写入的是 profile 的 cordis.patch.yml（行 id model-session-headers），与手写 YAML 完全等价，两种方式可以混用。
实现上有两个坑，都已在代码里处理：
rules必须声明.volatile()，否则SettingsForms.write()以not volatile拒绝写入；但 volatile 字段会被 DSH 换成 observable 传给插件，直接.filter()会抛错，所以读取统一走unwrapRules()。- 插槽渲染器以普通函数调用的方式执行组件，函数组件里的 React hooks 不生效（组件静默不渲染），所以卡片写成 class 组件。
对话右上角的发送状态
每个对话的头部（固定在「后台任务」按钮左侧，后台任务出现或消失时不会被挤动）会显示一个状态标记：圆点 + 最近一次请求的头名称。
| 圆点 | 含义 |
|---|---|
| 绿 | 已发送：DSH 已带上这个头发出请求 |
| 黄 | 跳过：请求里已有同名头且 overwrite 关闭，保留了原值 |
| 灰 | 未命中规则，或还没有请求记录 |
点开后列出会话 id 和这个对话最近 10 次请求：时间、provider / 模型、状态、实际发出的头和值（跳过时显示已存在的值）。
- 默认开启。在设置卡片里取消「在对话右上角显示发送状态」即可关闭，保存后无需重启；关闭期间不再记录。等价 YAML：
showStatus: false。 - 记录只在内存中，每个对话最多 10 条、最多保留 100 个对话，DSH 重启后清空。
- 没有会话 id 的内部辅助请求无法归属到某个对话，不会出现在列表里。
- 只能证明 DSH 这一跳已发出。中间网关（如 magpie）是否把头转发给上游，这里看不到——那需要看网关自己的日志。
实现：host 端注册只读接口 GET /model-session-headers/api/status?session=，经 connection.requestRejection 做浏览器信任校验；前端每 3 秒（页面不可见时暂停）按页面自身的 base 解析相对路径请求它——desktop 页面是 dsh-app://app/，直接请求 host 的 127.0.0.1 源会因跨域被浏览器拦截。
配置
写在 profile 的 cordis.patch.yml（或本包自带的同名文件，安装后按 id 覆盖整个 config，需写全量）：
- insert:
- id: model-session-headers
name: dsh-model-session-headers
config:
mode: session-id # session-id | uuid | fixed
keepPrefix: false
overwrite: false
debug: false
rules:
# Claude Code 兼容：所有 claude 系模型
- models: ["claude-*", "anthropic/claude-*"]
flavor: claude-code
# OpenCode Go：只对走 opencode-go 路由的 deepseek 模型
- models: ["deepseek-v4*"]
providers: [opencode-go]
flavor: opencode-go
# 完全自定义：一个模型挂多套头
- models: ["my-gateway-model"]
headers:
x-session-id: "{sessionId}"
x-opencode-session: "{sessionId}"
x-tenant: acme
x-routing-key: "{provider}/{model}"
默认规则
未配置 rules 时内置两条规则（本包自带的 cordis.patch.yml 也写的是这两条）：
| 模型 | flavor | 示例 |
|---|---|---|
opencode/*、*/opencode/* |
opencode-go |
opencode/deepseek-v4.1-flash、aihub/opencode/deepseek-v4.1-flash |
claude-* |
claude-code |
claude-sonnet-4-6、anthropic/claude-sonnet-4-6 |
显式写 rules: [] 表示停用全部注入；profile 里已有的 rules 会整体覆盖默认规则。
规则匹配
- 规则自上而下求值，首条命中生效；未命中任何规则的调用原样透传。
models支持*/?通配，大小写不敏感。完整 id 和最后一段（/之后）都会参与匹配，所以claude-*能命中anthropic/claude-sonnet-4-6。models留空 = 不限模型；providers留空 = 不限路由；两者都空 = 该规则匹配全部调用（相当于全局）。enabled: false可临时停用某条规则。
头信息
flavor 提供预设，headers 在其之上追加或覆盖（同名后者胜）：
| flavor | 默认头 |
|---|---|
claude-code |
x-claude-code-session-id: {sessionId} |
opencode-go |
x-opencode-session: {sessionId} |
generic |
x-session-id: {sessionId} |
模板变量：{sessionId}、{model}、{provider}。模板里没有变量时就是固定值。
取值语义
mode |
头的值 |
|---|---|
session-id（默认） |
本次调用的 DSH 会话 id；默认去掉 session- 前缀，只发裸 UUID（keepPrefix: true 可保留） |
uuid |
会话 id 的 SHA-256 派生的 UUIDv5 形态，跨进程稳定、对上游不可读 |
fixed |
配置里的 value，所有调用相同（value 为空则该规则不注入） |
会话 id 缺失的调用（部分内部辅助请求）不注入任何头，不会把空值发出去。
覆盖行为
默认不覆盖已存在的同名头（HTTP 语义上大小写不敏感），这样适配器自己设置的值优先。某些官方 provider 会写死占位符（如 x-opencode-session: dsh-web-search），此时把 overwrite 打开（全局或单条规则），或让规则里的 headers 覆盖预设。
调试
debug: true # 控制台打印每次注入
debugFile: /tmp/session-headers.jsonl # 每次注入追加一行 JSON
JSONL 每行：{"ts","provider","model","session","headers"}。
工作原理
llm/stream(options, next)
├─ selectRule(): provider + model 匹配 → 命中规则
├─ buildHeaders(): flavor/headers 模板 → [[header, value], ...]
└─ 每次 iterator.next() 都在 als.run(scope) 内执行
└─ 适配器内部 fetch()
└─ 补丁后的 fetch: 读 als store → 合并 headers → 发请求
ctx.on('llm/stream')与ctx.effect()都是可逆注册，卸载插件时自动移除监听并还原fetch（若期间被别的插件再次替换则不强行还原，只告警）。- 合并 headers 覆盖两种 fetch 写法：
Request对象自带的 headers，以及init.headers覆盖。
限制
- 只覆盖
llm/stream内的对话/流式请求。GET /models这类模型发现请求是独立流程，不会带头；如果网关连列表接口都拒绝，需要另做适配。 - 依赖 DSH 出站 LLM 请求走 Node 全局
fetch。未来若 DSH 换网络栈，注入会失效（症状是原来的缺头报错回归）。 - 不伪造 TLS 指纹、
user-agent、anthropic-beta等其他头；需要时用规则的headers显式添加。 - 不把内部会话 id 泄露给第三方：只有命中规则的出站请求会被改写，其他 fetch 原样通过。
开发
npm install
npm test # node:test，含本地 echo server 的端到端断言
无构建步骤，index.js 即产物。
已验证
- DSH
0.2.1-rc.2（Node 24）：dsh plugin --profile web add安装成功，--dump-config中可见# == dsh-model-session-headers层，web profile 启动时apply被真实调用。 - 16 个本地测试通过，含
llm/stream→ 补丁 fetch → echo server 的端到端断言（Claude Code / OpenCode Go / 未匹配模型 / 不覆盖 / 覆盖 / Request 对象 / 卸载还原）。 - 未对真实 Claude Code 或 OpenCode Go 网关发过请求。头名按官方文档核对：Claude Code 网关的
x-claude-code-session-id、OpenCode 的x-opencode-session。
License
MIT
