opencode-go 无法发送逐对话会话头（x-opencode-session）：compat 门控 withhold 导致配置层无解，缓存命中率受损

[aobakaolengmian]

English TL;DR — OpenCode Go requires a per-conversation session ID header (x-opencode-session; the gateway also accepts x-session-id / session_id). dsh already forwards the conversation id (session.id) down to pi-ai, but pi-ai maps session affinity only to OpenRouter/OpenAI header names, and dsh's COMPLETIONS_COMPAT_GATE marks sendSessionAffinityHeaders / sessionAffinityFormat as "withhold" (also absent from the compatProfile schema) — so it cannot be enabled by configuration. Users are forced to hard-code a static x-opencode-session in headers, which defeats the intended per-conversation routing / prompt-cache affinity. A local patch flipping those two gate entries to "offer" plus compat: { sendSessionAffinityHeaders: true, sessionAffinityFormat: openrouter } was verified to emit a distinct x-session-id per conversation (all requests 200, ~50% cache hit on turn 2). Suggested fix: offer those compat fields, or declare affinity in the opencode-go catalog, or add an "opencode" affinity format emitting x-opencode-session.

---

发帖位置：https://github.com/deepseek-ai/deepseek-harness/discussions（该仓库 issues 已关闭，仅 Discussions 可用）

现象

使用 OpenCode Go（https://opencode.ai/zen/go）作为供应商时，任何请求都返回：

HTTP 400
{"type":"MissingSessionID","message":"Error from provider (Console Go): Request is missing x-opencode-session and cannot be routed efficiently. Please see https://opencode.ai/docs/go/#where-can-i-use-it"}

OpenCode Go 官方文档明确要求（原文）：

Send a stable session ID in x-opencode-session for each conversation so we can optimize routing and prompt caching.

即该头是逐对话的稳定标识，用于路由亲和与提示词缓存优化。

环境

• dsh 0.1.5-rc.1（npm 全局安装），macOS 26.6 arm64
• @earendil-works/pi-ai 0.85.1
• 供应商配置（~/.dsh/settings.yaml）：

llm-pi-ai:
  providers:
    opencode-go:
      apiKeyEnv: OPENCODE_GO_API_KEY

根因分析

会话 ID 的管道其实是通的，断在最后一层映射 + 配置门控：

层	状况
dsh-agent-loop	✅ 已传递真实会话 ID：sessionId: this.session.id（dsh-agent-loop/lib/index.js:1215）
dsh-llm-pi-ai	✅ 继续透传给 pi-ai：...options.sessionId === void 0 ? {} : { sessionId: String(options.sessionId) }（lib/index.js:1871）
pi-ai	❌ 会话亲和只映射到 OpenRouter / OpenAI 两种头型： sessionAffinityFormat: "openrouter" → x-session-id sessionAffinityFormat: "openai" → session_id + x-client-request-id + x-session-affinity 没有映射到 x-opencode-session
dsh-llm-pi-ai 配置层	❌ COMPLETIONS_COMPAT_GATE 把 sendSessionAffinityHeaders / sessionAffinityFormat 标记为 "withhold"（lib/index.js:403,405），且 compatProfile schema 中不含这两个字段 → 用户无法通过配置启用，字段即便写入也会被 schema 剥离

结果：用户只能退化为「全局静态头」workaround（配置文件 headers 只能写死字符串），所有对话共用同一个路由/缓存桶，恰好与官方"逐对话"的意图相反，缓存命中率受损。

实测：网关接受的头名（用真实 key 逐个验证）

请求头	结果
（无）	✗ 400 MissingSessionID
x-opencode-session	✓ 200
x-session-id	✓ 200
session_id	✓ 200
x-session-affinity	✗ 400
x-client-request-id	✗ 400

即 pi-ai 现有的 openrouter 格式（x-session-id）就能被 OpenCode Go 接受——只差把门控放开、让配置能声明它。

已验证的本地补丁方案（供参考）

改动 @deepseek-ai/dsh-llm-pi-ai/lib/index.js 两处：

1. compatProfile 增加两个字段：

   sendSessionAffinityHeaders: z.boolean(),
   sessionAffinityFormat: z.union([z.const("openai"), z.const("openai-nosession"), z.const("openrouter")])

2. COMPLETIONS_COMPAT_GATE：sendSessionAffinityHeaders 与 sessionAffinityFormat 由 "withhold" 改为 "offer"

随后在供应商配置中声明：

llm-pi-ai:
  providers:
    opencode-go:
      apiKeyEnv: OPENCODE_GO_API_KEY
      compat:
        sendSessionAffinityHeaders: true
        sessionAffinityFormat: openrouter   # → x-session-id: <对话ID>

抓包验证结果：每个对话携带各自不同的动态会话 ID（对话请求与标题生成请求均带上），所有请求 200，第二轮缓存命中约 50%：

[REQ] /chat/completions (对话)      {"x-session-id":"session-dd8d30a3-..."}
[REQ] /chat/completions (标题生成)  {"x-session-id":"session-dd8d30a3-..."}
[REQ] /chat/completions (对话)      {"x-session-id":"session-3d961362-..."}   ← 另一会话，ID 不同

建议的修复方向（任一即可）

1. 开放门控：把 sendSessionAffinityHeaders / sessionAffinityFormat 从 withhold 改为 offer，并加入 compatProfile schema，让用户可为 OpenCode 类路由启用会话亲和。
2. 目录层直接声明：在 pi-ai 的 opencode-go 目录数据里为 openai-completions 类模型加上
   "sendSessionAffinityHeaders": true, "sessionAffinityFormat": "openrouter"，
   开箱即可获得逐对话会话头（openai-responses 类是否适用需单独确认）。
3. 更贴合语义：pi-ai 增加 sessionAffinityFormat: "opencode" → 发送 x-opencode-session，并在 opencode-go 目录中启用。

注意事项

• anthropic-messages 协议路径发送的是 x-session-affinity（见 pi-ai/dist/api/anthropic-messages.js），该头被 OpenCode Go 拒绝。因此若采用路由级 compat，需确认 OpenCode 路由下 anthropic 类模型会被正确跳过（route 级字段对不支持该字段的协议应 skip），否则会引入 400。
• 与之配套的 pi-ai 侧问题已另提：earendil-works/pi（见下）。

[aobakaolengmian]

补充：pi-ai 侧的对应 issue 已提交（含 SessionAffinityFormat 缺 opencode 映射的代码定位与实测矩阵）→ earendil-works/pi#9437

另附本机上已验证可行的临时方案：把 compatProfile schema 加上这两个字段、并把 COMPLETIONS_COMPAT_GATE 中两项由 withhold 改为 offer，随后在 provider 上声明 compat: { sendSessionAffinityHeaders: true, sessionAffinityFormat: openrouter }，即可发出逐对话的 x-session-id（抓包确认对话与标题生成请求均携带、各会话 ID 不同、全部 200，第二轮缓存命中约 50%）。