English · 简体中文

日常对话不该花旗舰模型的钱；真正重要的对话也不该交给便宜模型。

在每个顶层 Agent 的每一轮开始之前，一个轻量的 LLM 裁判（运行在你的 Fast 层模型链上）会把用户消息判定为 fast（日常）或 smart（重要）。被选中的层随后通过 harness 自身的 agent/request 管线驱动整轮——思考、工具调用、代码编辑。裁判只做判定，从不干活。

🦾 [deepseek-flash]     → fix the failing test
🧭 judging…
🧠 [deepseek-v4-pro]    ← "design the auth flow" → 立即升级
⚠️ deepseek-flash 429 → 冷却中，同层故障转移 — 1 分钟后重试
🦾 [deepseek-v4-flash]  ← Fast 链中的下一个健康模型

• 期望成本路由（EV） —— 当且仅当 pSmart ≥ θ 时走 Smart，其中 θ = 1/reworkPenalty：这条门槛与模型价格无关，所以唯一的旋钮就是"错误降级有多痛"。升级是即时的；降回来需要 downgradeMemory 次连续的决定性 fast 判定。裁判不可用或判定不确信时一律保持原位，绝不猜测。
• 缓存感知路由 —— 当 Fast 与 Smart 共享同一 provider 时，决策门槛会除以 sameFamilyPenalty（默认 1.5），并在 prompt 缓存仍热时抑制降级，避免切到便宜模型反而更贵。
• 运行时故障转移 —— 429 / 402 / 5xx / 配额 / 用量上限 / 模型下线 等失败会把模型置入指数退避冷却（1m → 4m → 16m → 1h04m → 4h16m，上限 6h；客户端侧限流从 16m 起步），并在同一层内重新解析到下一个健康模型——同一轮内重试，绝不跨层。
• 任务级编排 —— 复杂任务会让 Smart 层担任 CTO：规划、通过 harness 的 subagent 工具把实现委派给 Fast 层工程师子代理、逐个审查结果并迭代。硬上限由插件强制执行而非仅靠提示词：每次委派计一轮、连续工作代理失败计一次升级，一旦触顶 subagent 工具会被直接拒绝、系统提示词切换为"立即收尾"通知。
• 成本遥测 —— 按层统计 token，可选的 USD 计价表（/router status 会显示"本次会话若全程使用 Smart 模型将花费多少"）。吞吐速率不在此列：DSH 原生已在消息页脚与 trajectory 面板显示 tok/s，且按解码时间计算，口径更准。
• 动作可见 —— 切换档位或模型时会往对话里写一条 [shift-router] Fast → Smart · … 通知（harness 没有给插件预留状态栏座位），所以插件启用后不会"静默地什么都没发生"。把 ux.routerLogVerbose 打开，则每一轮判定都会有一条通知，而不只是切换时。
• 零配置启动 —— 未配置分层前完全无操作；配置完成后路由立即生效。配置可通过 GUI 设置面板 和 /router config 命令实时编辑（持久化，无需重启）。

本包是一个 DSH bundle：cordis.patch.yml 会把插件行插入任何声明了它的 profile。下面每条通道最后都是同一条 dsh plugin --profile <name> add …——它在 profile 目录里转发给 pnpm。

dsh plugin --profile web add dsh-shift-router

安装的是预构建产物：不会在你的机器上运行任何构建脚本，因此无需任何授权。

npm pack      # 或下载 release 里的 tarball
dsh plugin --profile web add ./dsh-shift-router-0.6.0.tgz

同样是预构建产物；无法访问 registry 时用这条。

dsh plugin --profile web add github:green-dalii/dsh-shift-router#v0.6.0

git 安装拉到的是源码而非构建产物，因此由包的 prepare 脚本构建 dist/。pnpm ≥ 10 默认拒绝 git 依赖的 prepare——若第一次 add 失败，把 pnpm 打印的确切包键复制进 profile 的 pnpm-workspace.yaml 后重新执行：

allowBuilds:
  dsh-shift-router: true

这等于允许该包的代码在安装时于你的机器上执行，且不在 agent 沙箱内。请锁定 tag 或 commit（…#v0.6.0、…#<sha>），避免后续 push 悄悄改变你实际运行的内容。

git clone https://github.com/green-dalii/dsh-shift-router.git
cd dsh-shift-router && npm install && npm run build
dsh plugin --profile web add /path/to/dsh-shift-router

dsh --profile web --dump-config | grep -A3 'id: shift-router'

插件无需任何配置即可加载（所有默认值都安全）；分层模型来自设置卡片（SPEC §12）或 profile 的 patch 行。后应用的层胜出，且 patch 会替换目标行的整个 config 值——覆盖本行的 patch 必须重述它需要的每一个键（SPEC §10）。

DeepSeek Harness 通过 @deepseek-ai/cordis-plugin-hmr 支持热重载，但有两点需要了解：

1. 官方 Web bundle 默认禁用了共享 HMR 行（packages/bundle/web-app/cordis.patch.yml 中是 - id: hmr, disabled: true，上游 TODO："在 Web 的重载生命周期测试通过后重新启用共享 HMR"）。在 profile patch 中重新启用它——这是文档化的覆盖机制：

   # ~/.dsh/profiles/<name>/cordis.patch.yml
   - id: hmr
     disabled: false

2. 哪些能热重载、哪些不能（已对照当前实现实测）：

   • ✅ 配置改动 —— 编辑 profile patch（或 home patch）会以新配置重新执行受影响插件的 apply()，无需重启。插件自身配置也通过 settings 命名空间热生效（/router config set 与 GUI 卡片本来就不依赖 HMR）。
   • ❌ 模块（代码）改动 —— 当前 HMR 的 accepted 依赖图只覆盖 harness 自身模块；修改外部插件的编译产物（如 dist/index.js）在现行版本中不会触发重载，因此代码改动仍需重启。这正是上游 TODO 所指的未经测试的 "reload lifecycle"，不是本插件的局限。
   • ❌ client 包元数据 —— dsh.client manifest 与 exports["./client"] 在进程内缓存，新增/修正后必须重启 profile；仅 dist/client.js 内容变化可走 client HMR 重建链。

   实践建议：用 /router config / 设置面板做配置（始终实时）；改模型就编辑 patch（开启 HMR 后实时）；只有改动插件代码时才需要重启。

配置位于 shift-router settings 命名空间：可在 GUI 的 设置 → 插件 → 插件配置（「Shift-Router」卡片）中编辑、用 /router config 命令修改，或通过 profile patch 行配置。所有字段都有安全的默认值。

唯一必须由你决定的是档位模型：docs/MODELS.zh-CN.md 说明如何挑选 Fast 与 Smart 模型（Fast 链同时也是裁判链）、什么样的模型适合做回退、以及哪些模型能接收图片。

所有数字字段都经 schema 范围校验（如 window.minConfidence 必须在 [0,1]、window.size 必须是正整数）；非法值在加载 / set 时被拒绝，绝不静默接受。

从 v0.5.0 升级： 路由决策会立即发生变化（无需改配置）——决策规则从"数窗口票数"改为"权衡期望成本"，另有两个遗留旋钮的含义变更。详见 SPEC.md §15 与 CHANGELOG.md 的 [0.6.0] 段。

插件随包构建一个浏览器端（client）模块，在 GUI 的设置页注册一张 「Shift-Router」 卡片：

• 位置：设置 → 插件 → 插件配置（该页由官方 dsh-client-ui-settings-plugins 提供，卡片注册进 settings.plugin.item 槽位）。
• 能力：以表单编辑全部标量叶子字段（开关、数字、枚举）以及两层模型链，分七个分组（通用 / 模型 / 路由 / 编排 / 故障转移 / 遥测 / 日志与体验），路由分组下再分子组（裁判 / 决策窗口 / 缓存感知）。标量字段采用紧凑的「设置行」版式——左侧标签 + 说明，右侧同行右对齐控件——每个字段只占一行，不再上下堆叠三层。控件全部使用宿主平面设计令牌：开关用拨动开关（浅色/深色主题下对比度都清晰）、枚举用带箭头的下拉、数字输入框内嵌单位后缀（ms、tokens、0–1 等）、模型链用有序行编辑器——行的顺序就是层内回退顺序：优先命中排在最前的可用模型，其余作为后备。provider/model 下拉自动载入 DSH 运行时模型目录（llm.models，与设置页模型目录同源）：只列出当前有模型清单的 provider，无休眠目录噪音，且插件不硬编码任何模型，跟随任何部署的 DSH 实际配置。另有「自定义…」入口填写目录之外的取值。分段保存、单字段恢复默认与覆盖标记与官方卡片完全一致。
• 边界：仅 pricing（可选的 USD 计价表）仍由 /router config 或 patch 行编辑；两层模型链都可以在卡片中直接编辑。
• 构建：npm run build 会同时产出 host 产物（dist/index.js）与 client 产物（dist/client.js）。client 模块通过 dsh.client manifest 被 dsh-client-modules 扫描，要求插件以包名（dsh-shift-router）挂载——源码检出式 patch（name: '/path/dist/index.js'）不会提供卡片。

0.1.0-rc.x 及更早的 harness 会把第三方 settings 命名空间从浏览器的 settings.describe 响应里过滤掉，除非它出现在 WEB_SETTINGS_NAMESPACES 中——这正是 scripts/expose-gui-settings.mjs 存在的原因：它修改 profile 里已安装的 dsh-host-apiproxy（幂等；升级依赖后重跑）。从本项目的基线 0.1.5-rc.2 起，该包与白名单 均已移除，命名空间原生暴露，脚本会输出「不需要」并以 0 退出。该脚本不在发布包内 （files），只能从源码检出获得。

机制到机制的逐项映射是规范，只在 SPEC.md §1.1。这里有两点 值得单独说明，因为它们不在那张表里：

• 吞吐速率刻意不在此列。 DSH 原生渲染 tok/s（消息页脚、trajectory 面板），口径是解码时间； 路由器负责路由决策与花费，不负责速率展示。
• 子代理永不被路由。 subagent 工具派生出的 worker 带 session.header.origin === 'subagent' 并保持其被钉住的模型；路由器只驱动顶层 agent 的轮次。

轮次级路由决定用哪个模型跑这一轮；任务级编排决定复杂任务怎么执行。当裁判判定 smart 且 orchestration.mode 为 auto（默认）时，路由器把这一轮交给 Smart 层担任 CTO：它制定计划、 通过 harness 的 subagent 工具把实现委派给 Fast 层 worker、逐个审查结果并迭代——最后由一次独立的 验收审计核对它的说法。fast 判定永远不会触发这些。

1. 进入 —— 决策档位是 Smart、subagent 工具存在、模式为 auto；编排器指令以系统提示词段落 注入（SPEC §7.2）。
2. 委派 —— CTO 调用 subagent；每次调用算一轮，且在派发时计数（派发出去的委派已经花掉了 预算，这样 maxRounds 才是真正的上限）。
3. 审查与迭代 —— worker 失败会推进失败连击；收敛协议要求每次重派都携带结构化的 ## Failure report（什么失败、在哪、用哪个验收测试复测），重复同一反馈即触发接管 （SPEC §7.2.1）。
4. 停止 —— 触顶后 tools/pre-execute 直接拒绝 subagent 工具、提示词段落切换为「立即 收尾」；agent/turn-stopping 释放状态。编排是单轮的：不跨轮，泄漏的运行会在下一轮开始时清扫。

硬上限能防止跑飞，防不住 CTO 声称验收了却其实没核对。因此真正委派过的运行会被审计：确定性 检查总是跑（每个派发出去的 worker 都回报了、存在 CTO 总结、没有被上限截断），并在 orchestration.audit.enabled 时追加一次小的 Fast 层复核，读取目标、总结与 worker 结果。它从不 阻塞轮次：LLM 那一半是分离执行的，结论以 Last audit: 出现在 /router status。

上游把「每 worker 的模型钉定」称为强制：worker 若继承父会话的模型，编排中途那已是 Smart， 经济学前提直接崩塌。DSH 里这个钉定居于宿主持有的白名单之后（subagent-model-selection，默认 关闭）。/router allow-workers 帮你把 Fast 链写进去；未授权时路由器会在 Worker delegation: 行里如实说明，而不是假装可以（SPEC §7.4）。

/router status 会显示 🪄 active (round x/y, esc a/b, fail streak n)，worker 回报后追加 Orchestration spend: $X · N/M workers reported，审计结束后还有 Last audit: …。进入编排时还会 往对话里写一条路由通知（SPEC §13.1），所以不必去读计数器也能看出这一轮的形态。

fast 判定；orchestration.mode: off（或 /router orchestrate off）；组合里没有 subagent 工具；或解析不到 Smart 模型——这些情况下这一轮就只是跑在 Smart 上，没有委派、也没有审计。

npm run build       # tsc（host → dist/）+ tsc client + tsdown（client bundle → dist/client.js）
npm test            # vitest（18 个文件、336 个测试：EV 路由 / 故障转移签名 / 裁判解析与提示词契约 / 编排 / 配置 schema 与迁移 / 遥测 / 路由通知 / 配置注册表与 GUI 表单模型 + 卡片 UX + 模型目录 / 打包安装契约）
npm run typecheck

npm run test:e2e

该脚本会建一个临时 DSH_HOME，把本检出作为 bundle 装进派生出的 headless profile，用假适配器跑一轮，并断言：

• ROUTER-E2E: turn ran on fake/fake-smart notice=yes —— 裁判确实跑了、EV 规则确实升级了、真的切换了上线模型到 Smart 层，并且 [shift-router] 路由通知确实进入了模型请求（SPEC §13.1）；
• 在 e2e/legacy-config-overlay.yml 下（对齐前配置：遗留旋钮处于旧默认值 + 已被移除的 requireSmartModel 键）结果相同 —— 覆盖的是升级路径，不只是全新安装；
• 在 e2e/orchestration-overlay.yml 下结果相同 —— 使用插件的默认编排模式（auto），并挂载 web 专属的 subagent-model-selection-settings 行，即曾经导致启动失败的那个组合；
• shift-router settings 命名空间能完成一次写入并读回，且 Host 模型目录确实广告出该部署配置的路由（e2e/settings-probe.mjs）；
• 打包产物安装（npm pack → tarball → 第二个 scratch profile）能带着插件启动，浏览器端被提供给 client 模块加载器，且 profile 里没有任何 @deepseek-ai/* 副本 —— 那里没有 devDependencies，因此"运行时导入了未向消费者声明的包"会在 e2e 失败，而不是在用户机器上失败。

它不会碰你真实的 DSH_HOME，跑完自行清理（加 --keep 可保留现场）。手工复现：

DSH_HOME=/tmp/scratch dsh plugin --profile tmp add /path/to/dsh-shift-router
DSH_HOME=/tmp/scratch dsh --profile tmp --patch e2e/overlay.yml "design a migration plan"

仓库结构与模块地图（纯逻辑/接线分工、测试分层）以 CONTRIBUTING.md 的 Repository layout 一节 为唯一权威， 这里只留指针：src/ 是 host 半边（纯决策模块 + index.ts 里的 DSH 接线），src/client/ 是 浏览器半边（设置卡片），tests/ 覆盖两者，e2e/ 启动 scratch profile——包括打包产物。

• pi-shift-router —— 本插件所适配的上游项目： 同一套双层架构（LLM 裁判、回退链、指数退避故障转移、任务级编排），面向 pi-coding-agent。 行为对齐与刻意不对齐之处记录在 ALIGNMENT.md。
• dsh-plugin-dev-skill —— 开发 DSH 插件的 Agent 技能：工具（defineTool）、LLM 适配器、服务、事件、配置与打包，含 Cordis 心智模型与验证 清单。本项目遵循它；可在 DSH、Claude Code 或 Codex 中安装。
• obsidian-llm-wiki —— 把笔记与 PDF 变成互链、 可查询知识库的 Obsidian 插件（实体页与概念页、图检索问答、本地优先、无后端）。同一作者的另一条 产品线。

MIT © 2026 green-dalii and contributors.