dsh-opencode-session-id：零配置 OpenCode 會話 ID 注入

在基於 DeepSeek Harness (DSH) 的智能體開發中，對接 OpenCode 類模型（如 opencode / opencode-go）時，需要在出站 HTTP 請求中攜帶會話標識（如 x-opencode-session），以便網關識別會話上下文。手動注入不僅繁瑣，還容易在多實例部署時引入不一致。DSH 的插件化生態提供了標準化擴展點，下面介紹一個專門解決這一問題的插件。

dsh-opencode-session-id 是一個 DeepSeek Harness 插件，由 gausszhou 維護。它的核心價值是在使用 OpenCode 模型時，自動將會話 ID 注入到出站 HTTP 請求的 Wire 層，實現零配置運行。

核心功能¶

• 自動注入會話頭：在出站 HTTP 請求中添加 x-opencode-session、x-session-affinity、x-client-request-id 等頭部。
• 零配置：安裝後默認啓用，無需額外配置。
• Wire 層攔截：通過包裝 fetch 在網絡傳輸層注入頭部，不改變請求體、URL 和方法。
• 確定性哈希：將會話 ID 中的 UUID 部分哈希爲 8 位字母數字的 nanoid，提高安全性並降低頭部長度。
• 協議覆蓋：主要覆蓋基於 fetch 的協議（如 openai-completions、openai-responses、anthropic-messages）。

安裝與啓用¶

1. 安裝插件：
   使用官方包名安裝到 web 配置文件：

    dsh plugin --profile web add "@gausszhou/dsh-opencode-session-id"

2. 重載服務：
   安裝後需重啓 dsh-web 進程以使插件生效：

    systemctl --user restart dsh-web

典型用法¶

• 查看日誌：啓用調試模式以查看原始 ID 到 Wire Token 的映射關係：

    journalctl --user -u dsh-web -f | grep opencode-session-id

• 配置 verbose：在配置文件中開啓詳細日誌：

    - id: opencode-session-id
      config:
        verbose: true

適用場景與注意¶

• 適用場景：使用 DSH 運行 OpenCode 模型，且需要與 OpenCode Gateway 保持會話一致性的場景。
• 注意：
  • 該插件僅支持基於 fetch 的協議，不覆蓋 transport: websocket。
  • Wire Token 是對 UUID 部分進行的單向 SHA-256 哈希，無法逆向還原原始會話 ID。
  • 修改 nanoid 相關配置（如 nanoidLength、nanoidAlphabet）會破壞與舊記錄的關聯，需謹慎調整。

經過上述步驟，DSH 在調用 OpenCode 模型時將自動攜帶正確的會話頭。該插件通過 Wire 層攔截，在不干擾業務邏輯的前提下完成了會話追蹤。更多細節可參考插件目錄或GitHub 倉庫。