前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，常見做法是固定一個 provider 和 model。任務變長、工具輪次增多後，成本和延遲會隨每次調用累積；若要在「便宜檔」和「強檔」之間切換，又需要自己在業務層維護用量、升級策略和取消後的計費對齊。jev-harness-router 是面向 Harness 的 TypeScript 插件，在 Cordis 側接管受管 LLM 路由，在 economy / strong 兩檔邏輯下登記多家 Chat Completions 服務，並配合預算預留、SSE 與取消對賬。項目尚未發佈到 npm，需按倉庫內安裝指南用本地 bundle 或已編譯 tgz 集成；依賴鎖定 Harness 0.1.7-rc.2 與 Cordis 4.0.4（截至 2026-09-28 覈驗的已發佈 Harness 版本，含預發佈）。
這是什麼¶
- 名稱：jev-harness-router（GitHub：
mattlennon/jev-harness-router，版本 v0.2.1） - 維護者：mattlennon
- 分類：模型推理（社區目錄 SkillHub 條目）
- 許可證：MIT
- 定位：Budget-aware Jev routing plugin for DeepSeek Harness——支持多廠家推理、SSE，以及取消與斷流後的 reconciliation；範圍覆蓋文本、函數工具調用、廠家推理回放與 SSE 流式輸出。
社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；安裝與運行均在當前 DSH 進程權限下進行，啓用前應自行審閱源碼與許可證。
核心功能¶
下列能力均來自項目 README 中的「已實現」說明，未列出的能力（如圖像/音視頻、管理 UI、自動廠家故障遷移等）當前不提供。
與新版 Harness 的適配¶
- 使用
RequestMessage、獨立 tool 消息、完整工具投影、受管LlmAdapter，以及持久化會話 surface 替換。
P0：請求前檢與逐次計量¶
- 完整請求預檢、上下文哈希。
- 逐次記錄 usage、緩存、推理、費用、首 token 延遲，以及目標與階段更新。
P1：路由決策與上下文管理¶
- 質量門檻與預計費用排序、前綴緩存觀察。
- 切換收益與駐留門檻、升級預算、工具結果壓縮、可追溯檢查點。
P2：多廠家推理與流式¶
- DeepSeek / Kimi / GLM 專用推理配置及回放。
- 真正增量 SSE、取消與斷流結算、人工回執對賬。
路由模式與預算¶
- 路由模式：
off/shadow/auto，以及固定模型；最多一次自動升級。 - SQLite 原子預留、重啓恢復；未知費用持續佔用預算，避免超支。
驗證範圍說明¶
- 官方核心運行時 + 本地 HTTP/SSE 驗證；demo 與 eval 使用模擬數據，不產生真實密鑰請求。
doctor只檢查配置與環境變量；smoke與 agent 示例會產生真實請求，且 smoke 固定模型、跳過 Jev，不能替代多輪工具、取消計費與真實任務評測。
環境與依賴¶
- Node.js：24+（
package.json中engines.node爲>=24.0.0）。 - Harness / Cordis：與
SOURCE_LOCK.json及 peerDependencies 一致——@deepseek-ai/dsh-*0.1.7-rc.2，@deepseek-ai/cordis4.0.4。安裝@deepseek-ai/dsh時建議複覈 latest/next 是否指向該 Harness 版本。
安裝與啓用¶
項目未發佈 npm 包。完整步驟見倉庫 docs/INSTALL.md（本機啓動、模型/密鑰、bundle 安裝、更新與卸載）。面向完整 DSH 應用的推薦方式是 dsh.bundle 配置層（package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml）；同框架依賴以 peerDependencies 與宿主共享，開發測試另用 devDependencies。
配置真實服務前，先在項目目錄構建並生成本地配置模板：
npm run build
node dist/src/cli.js init --reasoning --config config/router.local.json
Copy-Item .env.example .env
不需要廠家推理能力時，可省略 init 的 --reasoning。模板保留實際模型 ID、能力、價格、驗證記錄和密鑰變量名，路由默認均未啓用；按 docs/PROVIDERS.md 填寫。Kimi 的 preserved / always / k3 模式須與實際模型一致。新模板默認 SSE；舊配置未寫 transport 時仍走 JSON。
校驗與單路由冒煙（會產生真實 API 請求，需已配置 .env）：
node --env-file=.env dist/src/cli.js doctor --config config/router.local.json
node --env-file=.env dist/src/cli.js smoke --config config/router.local.json --route deepseek-strong
node --env-file=.env examples/agent.mjs --config config/router.local.json --route kimi-strong --prompt "解釋函數職責"
建議先對各路由做 smoke，再啓用 shadow；填寫校準報告、語言覆蓋與兼容白名單後再啓用 auto。預計費用與質量門檻需自行校準，不宜直接當作生產降本承諾。
集成宿主¶
使用與插件一致版本的 Harness 服務，先掛載 llm 和 tools，再通過插件入口註冊。Agent 的 provider / model 應使用配置中的一組受管路由名稱。
import * as RouterPlugin from './dist/src/harness/plugin.js';
import { resolve } from 'node:path';
await ctx.plugin(RouterPlugin, {
routerConfigFile: resolve('config/router.local.json'),
databaseFile: resolve('data/router.sqlite'),
}).await();
完整宿主示例見倉庫 examples/agent.mjs。
典型用法：任務生命週期與路由干預¶
通過 ctx.jevRouter.engine 可在業務側顯式管理任務、階段、證據與固定路由：
const router = ctx.jevRouter.engine;
router.beginTask(agent.id, userGoal, { taskId: businessTaskId, language: 'zh-CN' });
router.updateTask(agent.id, { phase: 'verification', facts: ['驗證器已確認的事實'] });
router.recordEvidence(agent.id, {
eventId: checkEventId, repairAttemptId, goalId: validationGoalId,
category: 'task_validation', outcome: 'fail', evidenceRef: testReportPath,
});
router.fixRoute(agent.id, 'kimi-strong'); // null 解除固定；仍受歷史兼容和預算約束
router.finish(agent.id, 'success'); // 由獨立驗收器確認，不能相信模型自報成功
未調用 beginTask 時，插件會在首次接受的用戶輸入上創建會話任務；後續輸入加入有限事實並觸發重評，同一任務保留費用與升級計數。新業務任務應先結束舊任務再 beginTask。跨模型不會直接移植原始推理狀態；必要時使用宿主確認、保留證據的檢查點。
本地無密鑰驗證可運行（README「本地運行」一節）：
npm ci
npm test
npm run demo
npm run eval
npm run doctor
demo 經本地 SSE 與官方 AgentLoop、工具運行時演示 economy → economy → strong 及逐次賬目；eval 爲四組模擬對照，成本與質量數字均爲測試數據。
配置與文檔索引¶
| 資源 | 用途 |
|---|---|
config/router.example.json / config/router.reasoning.example.json |
未啓用的多廠家路由模板 |
| docs/OPTIMIZATION.md | P0/P1/P2、token 與成本、檢查點、取消對賬 |
| docs/MIGRATION-0.2.md | 新版 Harness API 與舊賬本 |
| docs/IMPLEMENTATION.md | 路由、併發、計費邊界 |
| docs/VERIFICATION.md | 測試報告與未驗證項 |
打包與自檢：npm pack 生成已編譯 tgz；npm run check:repo、npm run check:package 檢查倉庫與安裝包內容。
適用場景與注意¶
適合：已在 DSH 0.1.7-rc.2 棧上開發智能體，需要在 DeepSeek、Kimi、智譜 GLM 等 Chat Completions 之間做兩檔（economy / strong）路由，並關心預算預留、升級次數上限、SSE 流式與取消/斷流後賬目一致性的團隊。
注意：
- 插件以當前 Harness 進程權限訪問網絡、讀寫 SQLite 與配置文件；密鑰通過環境變量注入，安裝前請檢查
.env.example與 SECURITY.md。 - 不提供輔助付費摘要預算、廠家賬單自動拉取；真實廠家聯調仍依賴正確配置與自行驗證。
- 路由從
shadow到auto前應完成 smoke、校準與白名單，避免未驗證路由進入自動決策。
結尾¶
jev-harness-router 把多廠家 Chat Completions、Jev 檔位路由、預算與計量、SSE 及取消對賬收攏到 Harness 插件層，適合作爲 DSH「一切皆插件」生態裏「模型推理」類擴展使用。詳情與安裝以 GitHub 倉庫爲準；社區索引見 SkillHub 目錄頁與 https://github.com/mattlennon/jev-harness-router。
