前言¶

DeepSeek Harness（DSH）在調用模型時，會把會話信息放在 GenerateOptions.sessionId 裏，但 harness 本身沒有統一的「請求級 header」擴展點：GenerateOptions 不含 headers 字段，各 adapter 各自構造線上 HTTP header。若你的模型網關、中間代理或審計層需要按 session header 做路由、緩存或關聯日誌，僅靠 harness 默認行爲往往發不出這個頭。

社區插件 dsh-session-header（維護者 EmotionTowel）通過 harness 官方攔截點，在每一次 LLM 相關 fetch 上注入可配置的 session header，並在需要時覆蓋工具執行期內、指向指定網關前綴的請求。下面介紹它的定位、安裝與典型配置。

這是什麼¶

dsh-session-header 是 DSH 的 Cordis 插件（當前包版本 0.2.2，MIT 許可）。它在不改變 adapter 源碼的前提下，給 harness 發出的 LLM 請求（以及按配置白名單匹配的工具期 fetch）加上 HTTP header，默認名爲 x-session-id，值爲該次調用對應的 harness session id。

與直連 DeepSeek 官方 API 不同：官方 llm-deepseek adapter 已自帶 x-deepseek-harness-session-id；本插件面向 provider 中立場景，且默認不覆蓋調用方已設置的同名 header。

爲什麼需要它¶

harness 缺少全局 header 縫，各傳輸層若最終走 globalThis.fetch，本插件用兩處機制補齊：

1. llm/stream waterfall：標記 LLM 調用，並攜帶 options.sessionId；
2. globalThis.fetch 補丁：在 LLM 調用流內部的 fetch 上注入 header，覆蓋 llm-deepseek、llm-pi-ai 等基於 fetch 的 adapter。

上下文通過 AsyncLocalStorage 傳播：只有某次 LLM 調用流內部的 fetch 會被修改；web RPC、遙測、無關工具流量原樣通過。別人已設置的 header 按 HTTP 語義（大小寫不敏感）不會被覆蓋；插件卸載時還原原始 fetch。

取值語義（資料原文）：

• 未配置 value：取當前調用的 GenerateOptions.sessionId，並去掉 harness 的 session- 品牌前綴，發送純 UUID；主會話各輪、壓縮/起標題輔助調用、in-process 子 agent 各自上報自己的 session id；
• 配置了 value：所有匹配注入規則的調用使用固定字符串（原樣發送，不剝前綴）；
• 兩者皆無時，不發該 header。

核心功能¶

• 可配置 header 名（默認 x-session-id）。
• 可選固定 value，或動態使用當前 harness session id。
• toolEndpoints：工具執行期（tools/execute 瀑布內）僅對 URL 前綴匹配的 fetch 注入 header；默認空數組時保持「僅 LLM 流內注入」行爲。
• overwriteHeaders：允許覆蓋已有值的 header 名列表，用於替換某些 provider 硬編碼的佔位 session 頭。
• 不觸碰 attributionHeaders()；併發會話經 AsyncLocalStorage 解析，不依賴共享可變狀態。

安裝與啓用¶

需要已安裝 dsh CLI，且 Node ≥ 22。本包爲純 JavaScript，無構建腳本。

作爲 bundle 安裝（推薦）¶

在指定 profile 下執行：

dsh plugin --profile <name> add github:EmotionTowel/dsh-session-header

驗證配置層並啓動：

dsh --profile <name> --dump-config   # 應能看到 "# == dsh-session-header" 層
dsh --profile <name>

本地 checkout 用 overlay 加載¶

開發或本地路徑時，可在 overlay 中用絕對路徑引用 index.js（示例來自 README）：

# my-overlay.yml —— 此處插件行需要絕對模塊路徑
- insert:
    - id: session-header
      name: /absolute/path/to/dsh-session-header/index.js
      config:
        header: x-session-id
        # value: my-fixed-session-id

dsh --patch ./my-overlay.yml

配置項¶

在 profile 的 cordis.patch.yml 中調整 session-header 插件的 config 即可。

典型用法：適配 OpenCode Go 網關¶

OpenCode Go 文檔要求請求攜帶穩定的 session header（x-opencode-session），缺失時網關會返回 400（MissingSessionID）。README 給出三步配置，無需再查網關文檔細節。

1. 會話請求（LLM）¶

# ~/.dsh/profiles/<name>/cordis.patch.yml
- id: session-header
  config:
    header: x-opencode-session
    toolEndpoints:
      - https://opencode.ai/zen/go/v1

2. web-search（工具執行期的網關 fetch）¶

Go 的 web-search 走 Anthropic Messages 端點，fetch 發生在工具執行期，需 toolEndpoints 納入範圍；必要時用 overwriteHeaders 替換硬編碼佔位值：

- id: session-header
  config:
    header: x-opencode-session
    toolEndpoints:
      - https://opencode.ai/zen/go/v1
    overwriteHeaders:
      - x-opencode-session

toolEndpoints 只匹配 URL 前綴，web_fetch 抓任意網頁、GitHub、MCP 等第三方目標不受影響。

3. headless profile¶

每個 profile 的插件相互獨立；使用 Go 網關跑 headless 時需單獨安裝並配置：

dsh plugin --profile headless add github:EmotionTowel/dsh-session-header

# ~/.dsh/profiles/headless/cordis.patch.yml
- id: session-header
  config:
    header: x-opencode-session
    toolEndpoints:
      - https://opencode.ai/zen/go/v1

驗證示例（exit=0 且模型正常回答即爲通過）：

dsh --profile headless "運行 pwsh 命令 Get-Random -Maximum 1000000，只回復該數字"

驗證注入是否生效¶

將某 provider 的 baseURL 指向會記錄或回顯請求 header 的端點，開啓會話後應看到類似：

x-session-id: ba104306-a748-4052-a6e3-ab60be2e4c1f

同一會話內請求攜帶同一 id；spawn 出的子 agent 請求攜帶 child session id。

適用場景與注意¶

適合：自建或第三方模型網關按 session header 路由、緩存、審計；需要與 OpenCode Go 等強制 session 頭的服務對齊；希望在不動 adapter 的前提下統一注入會話標識。

不需要本插件：直連 DeepSeek 官方 API（api.deepseek.com）時，llm-deepseek 已帶 x-deepseek-harness-session-id，無需本節 OpenCode 類配置。

安全與權限：DSH 插件在當前 dsh 進程權限下運行，會 patch 全局 fetch 等行爲。安裝前應閱讀 倉庫源碼 與 MIT 許可證，確認符合你的合規要求。社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係，屬於 DSH「一切皆插件」生態中的第三方擴展。

結尾¶

dsh-session-header 用 llm/stream 與 fetch 補丁組合，補上 harness 缺少的請求級 session header 能力，並支持工具期白名單與有限覆蓋，便於對接按 session 約束的網關。更多信息見 GitHub 倉庫 與 SkillHub 目錄頁。