前言¶
在 DeepSeek Harness（DSH）裏走 OpenCode Go 調用 DeepSeek 系列模型時，上游靠 x-opencode-session 把同一會話釘在後端上，靠重複提示詞前綴做 prompt cache。上下文摺疊（billion-context）、系統提示詞改寫、歷史壓縮都會改寫前綴，緩存隨之丟失；摺疊後的重建請求往往是冷的，但緊跟着的那條請求又可能立刻變熱。若在請求已經發出之後才換路由，往往會多打一條無意義的冷啓動。下面介紹 TLEWA 維護的 DSH 宿主插件 dsh-opencode-go-router（Cordis 內部 id 爲 opencode-router）：在請求發出之前預測緩存命中率，並在「判冷且最近很慢」時替換路由 id，同時用兩級熱路由池讓前綴相近的新會話接手已有緩存的 id。
這是什麼¶
dsh-opencode-go-router 是發佈在 npm 上的 DSH 插件包（當前資料中的版本爲 0.6.2，許可證 MIT）。它只修改 OpenCode Go 相關請求的 x-opencode-session 請求頭，不是模型適配器。billion-context 可選：有摺疊賬本時可做摺疊診斷；沒有會話狀態文件時，實測緩存、TTFT/吞吐統計、池替換與輪換歷史仍由插件自身採樣維護。
維護者與倉庫：TLEWA/dsh-opencode-go-router。社區目錄頁：skillhub.cn 插件頁。
爲什麼需要預測式輪換¶
OpenCode Go 用會話頭綁定後端與緩存。前綴一變，該後端上的緩存就對不上新前綴。billion-context 摺疊重建時，重建請求本身冷，但重建會把新前綴寫進該後端緩存，下一條往往又熱。
本插件的切換時機是：在一條本來就會冷的請求發出之前。鉤子在 llm/stream、請求頭組裝之前運行，預測 <= cacheHitThresholdPct（默認 25%）且最近樣本很慢時換新的 ses_... 路由 id，使新 id 作用在同一條被判冷的請求上，避免「多打一條額外冷請求」。
系統提示詞改寫或消息歷史被壓縮時，預測命中率恆爲 0%，但僅「判冷」不夠，還須最近請求的平均 TTFT 或吞吐達到慢請求門檻（默認 TTFT ≥ 12000 ms 或吞吐 ≤ 60 tok/s）。連續切換後仍慢於基礎目標時，插件會按步進放寬下一次判定（stepTtftGraceMs、stepThroughputGraceTps），而不是重複等價切換。
只處理已配置 provider（默認 opencode-go）且模型 id 以 deepseek 開頭（大小寫不敏感）的請求；其他模型忽略。
核心能力¶
實測緩存與性能樣本¶
插件包裝合格請求的 llm/stream，讀取最後一個 usage 塊。單次命中率定義爲 cacheReadTokens / (inputTokens + cacheReadTokens)，並記錄 TTFT、吞吐、提示詞 token 數等；每個 DSH 會話保留最近 sampleSize（默認 5）條有效樣本參與判定。
摺疊賬本（可選診斷）¶
若存在 billion-context 會話狀態文件（路徑形如 sessions/openai/<host>_<sha256(conversationId).slice(0,24)>.json），可跟蹤 metadata.cacheLedger.folds。conversationId 在 DSH 中通常來自優先級更高的 x-bili-plugin-conversation；輪換 x-opencode-session 不改變該文件名。最新摺疊主要作爲「剛發生過重建式大冷請求」的證據，不單獨直接觸發輪換。插件不修改 billion-context 以外的文件。
預測與輪換條件¶
合格請求發出前，按 README 描述的順序預測下一條命中率（含系統提示詞變化、歷史變短、空閒 cacheTtlMs、上次命中、大前綴 prefill 等規則）。第一個合格請求沒有樣本，不會因預測而輪換。
僅在預測爲冷、minRotationGapMs 已過、最近普通請求模型合格、且（默認）攢滿 requireFullSamples 時輪換。dryRun: true 時只記錄不改請求頭。
熱路由 id 池¶
會話空閒入池後，前綴摘要（分塊 SHA-256，不存原文）相近的新會話可借入一級或二級池中的老 ses_... id，減少冷啓動。一級池要求前綴塊命中率至少 poolMatchPct（默認 60%）；二級借入還須滿足相對會話基線的 poolSpeedGainRatio（默認 1.1）等條件。poolEnabled: false 可關閉池邏輯，行爲更接近 0.6 之前「僅輪換時才創建路由」的模式。
Web 狀態頁¶
安裝後可在 DSH Web 端口訪問狀態路徑（README 示例：http://127.0.0.1:<DSH Web 端口>/opencode-router/status）查看實時統計與池對比信息。
環境要求¶
- DSH 版本 ≥ 0.2.1-rc.5 且 < 0.3.0（與
package.json中engines.dsh一致）。 - Node.js 20 或更新。
- 使用帶
llm-pi-ai適配器的 DSH，並配置 OpenCode Go provider（默認名opencode-go），且至少有一個模型 id 以deepseek開頭的 DeepSeek 系列模型。
安裝與啓用¶
從 npm 安裝（命令須與倉庫 README 一致）：
dsh plugin add dsh-opencode-go-router --profile <profile>
也可在 DSH 插件管理器的「添加插件」中填寫包名 dsh-opencode-go-router。包內聲明瞭 dsh.bundle.patch，正常安裝會自動創建 opencode-router 行；不要在 profile 裏爲它再手動加一條獨立 Cordis 行，也不要在 cordis.patch.yml 裏重複 insert 同一插件。
安裝後若 bundle 已在宿主運行期聲明，需在插件管理器中重新加載或重啓 DSH。與 dsh-opencode-ip-guard 等配套注入器聯用時，路由存在時本插件會替換基線 x-opencode-session；overrideExistingHeader 控制是否覆蓋已有頭。
典型配置¶
在 profile 的 cordis.patch.yml 中按行 id 覆蓋默認值，例如調高或調低緩存命中輪換門檻：
- id: opencode-router
config:
cacheHitThresholdPct: 25
常用項（完整表格見 GitHub README）包括：
| 鍵 | 默認值 | 作用摘要 |
|---|---|---|
enabled |
true |
總開關 |
predictiveRotation |
true |
關閉則不做預測式切換 |
cacheHitThresholdPct |
25 |
預測命中率低於等於此值纔可能輪換 |
ttftThresholdMs |
12000 |
慢請求 TTFT 基礎門檻 |
throughputThresholdTps |
60 |
慢請求吞吐基礎門檻 |
poolEnabled |
（見 README） | 是否啓用熱路由池 |
修改實現後，觸碰一次插件配置或開關 profile bundle 通常即可重新加載；版本號長期不變時可重啓 DSH。
適用場景與注意¶
適合誰： 已在 DSH 中通過 OpenCode Go 穩定使用 DeepSeek 系列模型，且關心 prompt cache 丟失後 TTFT/吞吐變差、希望自動換路由或跨會話複用熱 session id 的開發者。
權限與安全： 插件以當前 DSH 進程權限運行，會在本地寫入 statePath（默認 $DSH_HOME/storages/opencode-router/state.json）並改寫出站請求頭。安裝前建議閱讀 倉庫源碼 與 MIT 許可證，確認 profile 與 provider 配置符合預期。
邊界： 不壓縮上下文、不改系統提示詞或會話日誌；失敗判定始終按基礎 TTFT/吞吐目標，不按已放寬後的目標。聲明瞭 purpose 的輔助請求不改變「最近一次普通會話模型」的輪換判定狀態。
結尾¶
dsh-opencode-go-router 把 OpenCode Go 的路由頭管理與緩存命中率預測綁在 DSH 請求鏈路上：在緩存註定丟失且實測變慢時，於請求發出前替換 x-opencode-session，並用兩級池讓相似前綴會話繼承仍熱的後端綁定。DeepSeek Harness 生態奉行「一切皆插件」；SkillHub 目錄 與 GitHub 倉庫 爲獨立社區信息與源碼歸屬處，與 DeepSeek / 幻方無官方應用商店從屬關係。
