前言¶
把 DeepSeek Harness（DSH）部署在企業內網時，有一個常見障礙：出口網關會校驗請求的 user-agent，不含指定品牌字樣的請求直接被拒。而 DSH 的 LLM 適配器會強制寫入自己的 attribution user-agent，這不是在配置文件裏改一個字段就能繞過的。
dsh-llm-headers 解決的就是這個問題：它是一個 DSH 插件，在 HTTP 層爲發往 LLM provider 的請求注入你配置的請求頭。下面介紹它的原理、安裝方式和典型用法。
這是什麼¶
dsh-llm-headers 爲 DeepSeek Harness 的自定義 LLM API 請求注入 HTTP Headers，典型用途是改寫 user-agent。代碼以 MIT 協議發佈，當前版本 0.1.0，託管在 GitHub 倉庫 QiE2035/dsh-llm-headers。
它的關鍵性質是提供商無關：DSH 的 LLM 適配器（dsh-llm-deepseek、dsh-llm-pi-ai）都通過全局 fetch 發出模型請求，所以插件只包裝一次 fetch，一次配置就能同時作用於所有 LLM provider。
核心功能¶
工作原理：插件在加載時包裝 globalThis.fetch，僅對 URL 匹配 urlPatterns 的請求把配置的 headers 逐項 set() 上去（覆蓋同名頭，包括適配器強制 attribution 的 user-agent），其餘請求原樣透傳。
三個配置入口，即時生效：
- Web UI：插件把 Config schema 註冊爲
llm-headers用戶配置命名空間，Settings 頁面自動渲染編輯表單，保存後即時生效（applies: live，無需重啓）； cordis.yml：作爲 base 層配置；settings.yaml：備用通道，保存即熱重載。
UI 保存的值優先級高於 cordis.yml 中的 config。
默認安全：
- 默認惰性（
headers爲空）時不改寫任何請求； urlPatterns中的空字符串會被忽略，不會誤匹配全部 URL；- 請求 URL 無法分類（如跨 realm 的
Request實例）時原樣透傳； - 卸載時僅在自己仍是當前 fetch 包裝者的情況下恢復原值，不破壞後續包裝者。
併發保護：Web 卡片保存攜帶最後一次讀取的 revision（樂觀併發），配置在別處被修改時以衝突提示拒絕並自動刷新；提供「恢復默認」按鈕，清空用戶層後回到 cordis.yml config 與 schema 默認值。
安裝與啓用¶
發佈形態是 bundle，安裝命令如下，會把 llm-headers 追加到指定 profile 的 bundle 層：
dsh plugin --profile <name> add /path/to/llm-headers
安裝後默認配置下插件處於惰性狀態（headers 爲空），不會改寫任何請求，需要顯式配置纔會生效。
開發調試時可以按路徑加載本地源碼，在任一 cordis.yml（或 patch overlay）里加入：
- insert:
- id: llm-headers
name: /absolute/path/to/llm-headers/src/index.ts
典型用法¶
通過 cordis.yml 配置¶
下面的配置把 user-agent 改寫爲 opencode/1.0，且只對 URL 含 /chat/completions 的請求生效：
- id: llm-headers
name: dsh-llm-headers
config:
headers:
user-agent: opencode/1.0
urlPatterns:
- /chat/completions
兩個字段的含義：
| 字段 | 類型 | 默認 | 說明 |
|---|---|---|---|
headers |
Record<string, string> |
{} |
注入的請求頭；同名覆蓋，空表示不注入 |
urlPatterns |
string[] |
['/chat/completions'] |
URL 子串匹配規則，命中任一項即注入 |
通過 Web UI 配置¶
安裝到含 Web 界面的 profile 後：
- 打開 Web UI → Settings（設置）頁面；
- 「插件」→「插件配置」中找到 LLM 請求頭 卡片；
- 填寫
headers與urlPatterns後保存，寫入 user-settings 文檔並即時生效。
通過 settings.yaml 配置¶
不用 Web UI 時，也可以在 settings.yaml 裏寫：
llm-headers:
headers:
user-agent: opencode/1.0
urlPatterns:
- /chat/completions
保存即熱重載，無需重啓。
端到端驗證¶
倉庫自帶 e2e/echo-server.mjs，它會記錄收到的請求頭並返回模擬流式響應，用來確認配置的頭真的到達了 provider：
node e2e/echo-server.mjs
pnpx @deepseek-ai/dsh --profile headless --patch <overlay.yml> "Reply ok"
先啓動 echo 服務器，再跑一個 headless 任務；服務器終端應打印出該請求攜帶的 user-agent（即 overlay 裏配置的值）。倉庫還把這個流程腳本化爲 pnpm test:e2e，自動備份並還原 settings.yaml，運行需要 DEEPSEEK_API_KEY。
適用場景與注意¶
適合的場景：
- 部署環境有網關校驗
user-agent，需要替換爲部署者品牌（白標替換）； - 需要給所有 LLM 請求統一附加某個自定義頭；
- 希望通過 Web UI 在運行時調整請求頭，不改配置文件、不重啓。
使用前注意：
user-agent覆蓋僅在headers中顯式配置該頭時生效，未配置時 attribution 原樣保留；- 多個插件同時包裝
fetch會互相覆蓋，避免與其他做同類事情的插件疊加； - 運行環境要求 Node
^22.19.0 || >=24.0.0； ./client入口（lib/client.js）是供宿主 Web 模塊加載器消費的內部接口，不面向第三方，也不發佈類型聲明。
另外提醒：插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。本插件代碼 MIT 協議、源碼公開，可以自行審閱後再啓用。
小結¶
dsh-llm-headers 做的事情很集中：在 HTTP 層爲 DSH 的 LLM 請求注入自定義頭，默認惰性、即時生效、卸載乾淨，是 DSH「一切皆插件」思路下解決網關與部署定製問題的一個小而具體的工具。
倉庫地址：https://github.com/QiE2035/dsh-llm-headers
社區目錄頁：https://www.skillhub.cn/plugins/QiE2035/dsh-llm-headers （社區維護的獨立站點，與 DeepSeek、幻方無官方從屬關係）
