前言¶
在 DSH（DeepSeek Harness）裏調用模型時，請求往往還要經過自建網關或統一代理：需要帶會話標識、租戶頭、鏈路追蹤 ID 等。這類頭通常只能改 DSH 源碼，或在網關側寫死邏輯，改動面大、也難按 provider 或模型區分。
dsh-request-injector 是社區維護的 DSH 插件，用一份配置在請求發出前注入自定義 HTTP 頭，並按 provider、model、host 做匹配；頭值裏的 ${變量} 只在真正發請求時求值。下面介紹它的定位、能力、安裝與配置方式。
這是什麼¶
- 插件名稱：dsh-request-injector（目錄頁：SkillHub 插件條目）
- 維護者：PluieM
- 分類：模型推理（社區目錄歸類）
- 一句話：按 provider / model / host 匹配，向下遊模型請求注入自定義 HTTP 請求頭；請求頭的值支持
${variable}佔位符，在請求真正發出時才求值。
插件以當前 DSH 進程的權限運行，安裝前應自行查閱 GitHub 倉庫 源碼與 MIT 許可證。社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
匹配與注入¶
- 三個匹配維度：
provider精確匹配；model精確或尾部*前綴匹配（如deepseek-v4*）；host按真實目標主機匹配（不計大小寫）。留空表示該維度不限。 - 佔位符：例如
x-opencode-session: ${sessionId}、x-trace-id: ${uuid}；不做遞歸展開，$$輸出字面量$。 - 變量缺失時：可選
skip（跳過該頭）、empty（替換爲空串）、error（讓本次請求失敗）。 - 保留頭保護：
authorization、host、content-length、x-dsh-*等由 HTTP 棧或宿主管理的頭拒絕寫入。
雙後端與生效範圍¶
插件在鏈路上有兩處落點，默認 backend: auto 同時啓用：
| 後端 | 覆蓋的場景 | 盲區 |
|---|---|---|
A · 官方擴展點 llm-pi-ai/request-headers |
pi-ai 適配器的全部傳輸方式（含 websocket） | 拿不到真實目標 URL；非 pi-ai 適配器與模型列表探測不走這裏 |
B · 包裝 globalThis.fetch |
所有走 fetch 的路徑，可按 host 精確匹配 | websocket 握手不經 fetch |
同一條規則被兩個後端各寫一次時，值相同則冪等，無需額外去重。無 LLM 上下文時（例如模型列表探測），只有顯式寫了 host 的規則纔會命中——避免把本會話級頭誤注入到進程內任意 fetch。
配置與 UI¶
- 配置頁入口：設置 → 「請求頭注入」，或 插件管理器 → 請求頭注入行詳情；兩處讀寫同一 namespace。
- 配置整節爲 volatile：在插件頁保存後立即生效，無需重啓插件或重載 DSH；也可手寫 profile 的
cordis.patch.yml，Host 側會審計並告警明顯錯誤。 - 可視化表單支持規則增刪排序、逐頭校驗、可用變量速查表；保存採用整表提交併帶版本衝突檢測。
- 安裝後默認
rules爲空，不注入任何頭，不影響現有行爲。
安裝與啓用¶
在 DSH 環境中執行：
dsh plugin install dsh-request-injector
或在插件管理器「添加插件」中填寫 dsh-request-injector。包內已包含可直接加載的 lib/index.js（Host）與 lib/client.js（Web 客戶端），無需構建步驟。
資料中 package.json 標明版本 0.1.3，聲明與 DSH 0.2.2-rc.1 兼容；Node 引擎要求 >=22.19.0。
快速上手¶
配置可在界面中完成，不必先改文件。
- 打開插件管理器，找到「請求頭注入」，進入配置頁。
- 在「基本」區：啓用插件、後端（默認「自動（兩個後端都註冊）」）、變量缺失時的處理方式、調試日誌。
- 在「規則」區點「新增規則」：
- 匹配條件：provider、model、host，留空表示不限。
- 請求頭：逐條填名稱與值，值中可寫${sessionId}等佔位符。
- 順序：數字小的先應用；同名頭後寫的覆蓋先寫的。 - 點「保存」。保存即生效，下一條請求即可帶頭。
典型 YAML 示例（給網關帶會話頭）：
enabled: true
backend: auto # auto | headers | fetch
onMissingVariable: skip # skip | empty | error
debug: false
rules:
- enabled: true
comment: 給網關帶會話頭
match:
provider: newapi-responses
model: '' # 空 = 不限
host: '' # 空 = 不限
headers:
x-opencode-session: ${sessionId}
適用場景與注意¶
適合誰：需要在不改 DSH 核心、不改網關硬編碼的前提下，按 provider / 模型 / 目標 host 附加 HTTP 頭的智能體或網關集成場景——例如自建網關會話頭、按模型區分租戶標識、鏈路追蹤頭。
務必注意：
- websocket：僅後端 A 對 WS 有效；保持默認
backend: auto即可。 - 配置明文：保存在 profile 的
cordis.patch.yml；不要把長期密鑰寫進配置，優先用短期會話 ID 類變量。 - 能力邊界：
model需手填，無下拉；只處理請求頭，不修改請求體。 - 運行權限：插件與 DSH 同進程，安裝前請覈對源碼與許可證。
結尾¶
dsh-request-injector 把「按條件注入下游模型請求頭 + 運行時佔位符」收成可熱更新的插件配置，併兼顧 pi-ai 擴展點與 fetch 兩條路徑。需要查閱說明與源碼時，可參考 SkillHub 目錄頁 與 GitHub：PluieM/dsh-request-injector。
