前言¶
在 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。
