README · 参考手册(中文) · English Reference
README 刻意保持简短,其余内容都在这里:安装细节、完整配置项表、手动覆盖命令,以及插件的内部工作原理。
目录
- 安装
- 配置:opencode-switchman.jsonc
- 验证安装
- 侧边栏状态面板(TUI 插件,可选)
- 手动覆盖层
- 核心思想
- 工作原理
- 动态激活矩阵
- 模型评分引擎
- 子代理上下文硬顶
- 工件工作区(.switchman)
- tmux 窗格镜像(可选)
- 模型矩阵维护
- 开发与验证
- 版本亮点
- 延伸文档
一键安装/更新命令见 README,这里是完整版。
- opencode——强烈推荐以 CLI/TUI 为主力界面(插件的操作面——侧栏状态面板、
/poolConfig//modelRank弹窗、实时横幅——在 TUI 里最完整):建议先用 TUI 完成全部配置,之后可自行选择是否换用桌面端体验;两端共享同一份配置与状态 - 任意 opencode 供应商均可接入,以下三池额外享有额度控制(可任意组合,全部可选):
- GitHub Copilot:opencode 内 GitHub 登录(
/connect)即可 - GLM:自定义 provider(
zhipuai-coding-plan,baseURLhttps://open.bigmodel.cn/api/coding/paas/v4+ apiKey) - DeepSeek:自定义 provider(
deepseek+ apiKey)
- GitHub Copilot:opencode 内 GitHub 登录(
- 凭证零配置:插件从 opencode 鉴权层(auth.json / provider options / 环境变量)只读获取,不另存密钥、绝不自行刷新 token
AI 时代强烈推荐由 AI 自主完成安装配置——AI 能读取你的真实环境、写入正确的值,并自行验证结果,比手动复制粘贴更不容易出错。把下面这段话直接复制给你当前使用的 AI:
请严格按照官方说明为我的 opencode 安装并配置 opencode-switchman 插件。
官方来源(以此为准,不要凭记忆猜测):
- GitHub 仓库:https://github.com/mrzturn/opencode-switchman
- npm 包:https://www.npmjs.com/package/opencode-switchman
请先阅读仓库 README 的「安装」章节,然后严格照做。
步骤:
1. 安装 npm 上发布的最新版本:运行 `npx -y opencode-switchman@latest`(或 `bunx opencode-switchman@latest`),它会把我的 opencode 配置里的 `plugin` 条目改写为精确最新版本(若我用的是项目级 `opencode.json`,它同样适用)。
2. 完成功能配置:插件全部配置都在我 opencode 配置目录下独立的 `opencode-switchman.jsonc` 文件中,首次启动自动生成并带注释;请对照我的 provider(如 `zhipuai-coding-plan` / `deepseek` / `github-copilot`)检查并按需调整。
3. 校验配置正确性、确保 opencode 能正常加载启动运行该插件:在 opencode 内运行 `/switchman-doctor` 出本地脱敏诊断报告并修复所有报错;然后重启 opencode 确认插件确实已加载——日志应出现 `[opencode-switchman] injected N model shells (agents)`,且主模型的系统提示中应带有实时 `[ROUTES]/[WATERMARK]/[LIMITS]` 横幅块。
三个步骤全部通过才算完成;请汇报你做的改动并给出验证证据。
两条命令均同时覆盖首次安装与后续更新(幂等,可重复执行):自动把 opencode 配置与 tui.jsonc 的 plugin 条目改写为最新精确版本 opencode-switchman@x.y.z(JSONC 注释原样保留)、清理旧插件缓存(~/.cache/opencode/packages/opencode-switchman*),升级场景在横幅标记「已升级待重启」——重启 opencode 后生效。
插件内升级入口 /switchman-update 调用的是同一更新器(旧版直接 npm install 的方式对 opencode 实际加载路径无效)。
为什么条目是精确版本,而不是裸包名 /
@latest:opencode ≤1.18.x 的插件缓存按 spec 名固定目录(如~/.cache/opencode/packages/opencode-switchman),首次装入后不再向 npm 查询新版本——裸名与@latest会一直复用旧缓存(实测从 0.0.1 钉死不升级)。精确版本号每个版本一个独立缓存目录,所以更新器直接改写版本号。
在 opencode 配置(~/.config/opencode/opencode.json 或项目 opencode.json)中添加:
{
"plugin": ["opencode-switchman"]
}opencode 启动时会自动经 Bun 安装并加载该 npm 包,无需其他步骤。后续升级请用上面的「一键更新」,或在 opencode 内执行 /switchman-update。
除插件安装外无需改 opencode 配置:全部插件配置(水位、计费、高峰、阈值、横幅、矩阵、自定义档链等)都在独立文件
opencode-switchman.jsonc中(见下节),首启自动生成、带注释。旧的元组 options(["opencode-switchman", {...}]第二项)已弃用,兼容保留一代(显式值仍优先,/switchman-doctor会提示 SWM044 并建议迁移)。
git clone https://github.com/mrzturn/opencode-switchman.git
cd opencode-switchman
bun install
bun run build # 生成 dist/opencode-switchman.js然后二选一:
a) 配置引用(推荐,随仓库更新)——在 opencode 配置的 plugin 数组中用 file:// 指向仓库目录:
{
"plugin": ["file:///absolute/path/to/opencode-switchman"]
}插件直接加载仓库内的 dist 产物;git pull 后重跑 bun run build 并重启 opencode 即完成升级。此方式与 plugins 目录部署二选一,同时使用会双重注入。
b) 部署单文件——bun run deploy 构建并复制到全局插件目录 ~/.config/opencode/plugins/opencode-switchman.js,自动加载。桌面端内嵌核心跑 Node 运行时,deploy 产出的单文件 bundle 即为此设计。
注意:
plugin数组中的file://引用与 plugins 目录部署不可并存(同名插件会加载两份);发布 npm 后,把file://...换成"opencode-switchman"即可切换为 npm 安装。重启 opencode 生效。
从旧版(switchman.js)升级:请删除旧的
~/.config/opencode/plugins/switchman.js,避免新旧两份插件同时注入;状态目录已迁移至~/.config/opencode/opencode-switchman/(旧目录可删,全部状态自动重建)。
除插件安装(opencode 配置的 plugin 数组)外,插件全部配置都在独立文件 opencode-switchman.jsonc——首次启动在 OpenCode 配置目录自动生成(优先级:OPENCODE_CONFIG_DIR、$XDG_CONFIG_HOME/opencode、~/.config/opencode),带 $schema 编辑器提示与逐键注释,坏值 fail-open 回退缺省;改文件后在 opencode 内重跑一次配置(或重启)即生效,/switchman-doctor 可出本地、脱敏且不联网的诊断报告。
providers——供应商策略段:随包内置稳定键 deepseek、zhipuai-coding-plan、github-copilot(与 opencode 官方 provider ID 一致),且任意 opencode 官方/自定义 provider 键均合法——未知键按自定义 provider 处理(通用缺省参与编排;对内置键的近似拼写 doctor 会给 warn 建议)。observe 控制配额查询与横幅展示,enabled 独立控制水位、高峰和耗尽是否参与路由(默认分别为 true、false)。billing 显式声明计费结构——subscription(评分系数 1.0)或 api(0.85,同 tier 内沉底);这是计费优先级的唯一来源(不从 models.dev/auth 推断)。peak 高峰区间使用 ISO 周日 1–7 与 [start,end) 的 HH:mm;出厂缺省 GLM 工作日 14:00–18:00、DeepSeek 工作日 09:00–12:00 与 14:00–18:00。
行为段(quota / cost / capability / matrix / banner / rules / lanes):详见下方「配置项」表——同样只写这一个文件。
| 键 | 默认 | 说明 |
|---|---|---|
providers.<id>.enabled / observe / billing / peak |
false / true / 见出厂 / 见出厂 |
供应商策略:路由参与、配额观察、计费结构(subscription=1.0 / api=0.85)、高峰窗口(详见上节) |
quota.glmFiveHourReservePct |
90 |
GLM 5 小时窗预留水位(%):达到即硬拦 GLM 壳避免用满 429;周额度仍只认 100% |
quota.deepseekLowBalanceWarnCny |
10 |
DeepSeek 余额预警阈值(元):低于该值横幅 [WATERMARK] 提示(仅预警不硬拦,按量计费) |
cost.enabled |
true |
models.dev 计价快照作为加权模型评分的一个系数 |
capability.enabled / source / apiKey / tierThresholds / lmarenaCheck |
true / auto / – / 内置分位 / false |
动态能力分级:auto=有 apiKey 先 Artificial Analysis、失败/无 key 转 OpenRouter;key 也可走环境变量 ARTIFICIAL_ANALYSIS_API_KEY |
matrix.mode / watch |
auto / true |
激活矩阵:auto 按宿主自动(desktop=可见模型 / CLI/TUI=favorites),app/tui 强制指定,legacy 旧静态矩阵;watch=配置面变化即重算并全量刷新探针(mode/watch 为启动级,重启生效) |
banner.enabled |
true |
四行横幅注入开关 |
rules.enabled / delegationFloor |
true / 3000 |
调度员规程(AGENTS.md)随包注入开关;delegationFloor=自做底价(token),注入规程时插值 |
context.gates / softTokens / hardTokens / forceTokens / readBudgetTokens / autoHandover |
true / 50000 / 90000 / 130000 / 1500 / true |
会话上下文水位实测+自读预算闸:插件从消息 token usage 实测主会话上下文并每轮注入 [WATERMARK:SESSION] 行(附每轮增速与距硬水位剩余轮数估算)。自读从第 1 轮起按 readBudgetTokens 计费:预估超限的读取自动追加 limit 有界放行,或以精确的有界重试参数拒绝;每轮另有 2× 上限阻断连续读取,无法预估的工具输出事后记账。验证/交付类 bash(git、测试/lint、构建)全水位放行;无界历史翻查(如不带 -n 的 git log -p)任何水位一律拦截并附收窄提示;超硬水位读取类关闭(收尾模式);超压水位横幅强制立即压缩,且 autoHandover: true(默认)时自动触发 /handover:完整分叉备份+压缩,未完成的任务在摘要上下文上继续。壳子代理会话不适用本水位,改走自身的单道硬顶(见 context.subagentForceTokens / context.subagentCap);三档水位在可知时额外以当前会话模型上下文窗口(models.dev)的 90% 封顶 |
context.subagentForceTokens / subagentCap |
跟随 forceTokens(130000)/ true |
子代理上下文硬顶+软档提醒:壳子代理会话只有一道硬顶(实测=最新 assistant 消息的 input + output + reasoning + cache.read,与会话水位同口径),显式覆盖时钳制 20k..1M,并额外以壳模型上下文窗口的 90% 封顶;缺省跟随主会话 forceTokens,默认共享同一条绝对终止线。硬顶终止之前有两档柔性提醒,直接复用主会话的绝对软/硬阈值(softTokens=省着用,hardTokens=收尾交接——子代理上下文与主会话上下文同等昂贵);有效上限(含窗口封顶)按比例下拉两档,档位永不超过真实终止线。触顶即拒绝该会话所有后续工具调用并下达收尾指令,子代理的下一份纯文本答复(详细的工作进度总结)直接作为任务结果返回委派方,会话永久终止。每档每次会话最多触发一次(进程内去重,会话删除即清除;重启后重新武装);调度规程的交接转发规则把该交接块视为剩余工作的权威状态(全新派发、只注入所需上下文,绝不续接已耗尽的会话)。此后带 task_id 恢复该会话的 task 调用一律永久拒绝(持久登记 ~/.config/opencode/opencode-switchman/subagent-cap.json,重启不失效),不带 task_id 的全新派发不受影响;subagentCap: false 既阻止新的终止也一并关闭提醒。subagentForceTokens 覆盖值非法(非有限数 / 超出 20k..1M)时删除该覆盖并报 SWM037 诊断,回退跟随 forceTokens(fail-open) |
builtinAgents.mode |
deny |
内置 explore/general 与壳路由抢任务且此前放行;deny=拦截附 economy/main 改派建议,allow=恢复放行 |
injection.mode |
chain |
壳注入面:chain=六档链精选∪favorites/可见集(task 工具描述每会话省约 6-10k token,链外模型点名走 denyUninjected 提示);all=可用全集(旧行为);configured=[2026-09-11] 配置了 favorites/可见集时仅注入这些模型的壳(自定义泳道/pool-config 强制保留照旧)——链外精选本就过不了运行时 activation 门,删掉纯死的每请求上下文;未配置时与 chain 行为一致。启动级,重启生效 |
dispatch.autoRedirect |
true |
派发被拒时在途改写 subagent_type 到拒绝消息已点名的链首候选(单跳、同快照守卫复检)——首次派发直接落在最优可用壳上,不再烧「拒绝-重试」轮次;false 恢复拒绝-重试 |
dispatch: "off"(.switchman/settings.json) |
缺省(fleet) | 项目级派发退出:.switchman/settings.json 顶层 "dispatch": "off" 让所有派发治理对该项目的 task 调用停摆——整条 task 路径跳过(未注入/内置代理拒绝及其自动改写、全部六闸含熔断拒绝),调用不受治理直接放行。只有精确的字符串 "off" 生效,其他任何值保持 fleet 行为(存在但不同的值会记一条一次性状态日志)。刻意不停摆:子代理硬上限、语言闸、读取/水位闸、自动交接、熔断失败记账,以及横幅/水位/TODO/[LANG] 行——每轮 [ROUTE] 行是唯一隐藏的 prompt 表面。逐调用读取,切换无需重启;settings.json 完全不是合法 JSON 时按进程一次性写入状态日志警告 |
relay.image |
true |
无视觉主模型:用户附带图片自动落盘并替换为路径文本+阅读指引(委托 vision 壳或交给 MCP 视觉工具);本地路径 / http URL 原样透传;全程 fail-open |
lang.enabled / ask / candidates |
true / true / 出厂清单 |
项目级语言偏好:每轮 [LANG] 铁律行(会话 / 注释与提交 / 文档),首次询问未完成配置则每轮用户输入重新询问,未配置期间写入/编辑/bash/派发被硬闸门拒绝(拒绝问卷则本会话豁免),落盘 .switchman/settings.json(AGENTS.md 标记为只读回退),/switchman-lang 重新询问。问卷题文跟随检测到的界面语言(env LC_ALL → LANG,归一化——zh_CN.UTF-8 → zh-CN——无匹配回退英文;仅题文本地化,标记前缀与指令正文保持稳定英文) |
lanes |
内置六档链 | 自定义各档壳链(覆盖内置偏好序);键=economy/mechanical/main/hard/vision/review |
workspace.enabled / dirname |
true / ".switchman" |
工件工作区:每个主会话自动创建 <project-root>/.switchman/<yyyy-mm-dd>/<sessionId>-<title>/ 目录,路径每轮注入调度员规程;目录内含 SESSION.md / dispatches.jsonl / media/。关闭后不再创建目录,规程段落同步失效 |
tmux.enabled / rightPct / maxPanes / mini |
true / 60 / 3 / false |
tmux 窗格镜像(仅当 opencode 服务器自身运行在 tmux 中时生效):每条被委派的子代理在主 tmux 窗口右侧列实时打开一个 opencode attach 窗格;rightPct=右列宽度百分比(10..90,主窗格占其余),maxPanes=可见子代理窗格上限(1..4;超出的派发在 FIFO 队列等待),mini=用极简 attach 界面取代完整 TUI |
旧元组 options 迁移:
quota.*.enabled→providers.<id>.observe(SWM042)、billingWindow.*→providers.<id>.peak(SWM043)、其余行为段(quota阈值/cost/capability/matrix/banner/rules/lanes)→同名 jsonc 段(SWM044);providers.glm/deepseek(凭证收集清单)从未实际生效,已删除。元组显式配置兼容一代(值仍优先),下个大版本移除。
启动 opencode 后,主模型每轮系统提示中会出现实时横幅(即调度依据):
[ROUTES] economy: glm-53f-low→glm-47-off→glm-5t-off | mechanical: glm-53f-high→glm-47-off | main: glm-53f-high | hard: glm-53-high | vision: glm-53f-high | review: glm-53-high-ro
[WATERMARK] GLM 5h 10% weekly 38% (refreshed 09-11 10:00) | Copilot credits 0% left (refreshes 2026-10-01) | DeepSeek balance exhausted | advice: ...
[WATERMARK:SESSION] measured session context ~37k (soft 50k/hard 90k/force 130k) | growth ~5k/turn, ~8 turns to hard | self-read this turn 178/3000
[LIMITS] down: none | reviewer prefers cross-family (same-family self-review = DOWNGRADED, allowed only when no cross-family reviewer exists) | api-billed & unknown models sink by coefficient (explicit billing=subscription wins) | matrix: cli·watch/ok | manual capability rank: 9 models, task-pool selection: 6 pools active (/modelRank /poolConfig to adjust)
[TODO] 0/6 done · in_progress: 撰写 README 章节 — keep todowrite current (update as each item starts/finishes)
[LANG] conversation=zh-CN comments=en docs=en (source: project settings) — 用会话语言回复与推理;代码注释、提交信息与生成文档各随其设置
[UPDATE] new version available: /switchman-update or /switchman-ignore
同时日志可见 [opencode-switchman] injected N model shells (agents)——N 随有凭证 provider 的模型面动态变化。六档候选由能力分×档位亲和×计费/未知组系数算法生成,并经 vision/review 结构门过滤,无任何厂商预留席位;运行期再按健康、水位与成本选出当前链首。
v0.2.0 在 OpenCode TUI 侧边栏底部新增实时 switchman 面板,v1.0.0 又做了全面的排版与配色打磨(并完成英文本地化):各家 provider 的水位以渐变条呈现、对齐到全局 8 列网格(标签、进度条与刷新时间跨块对齐,非零小额配额也保证至少一格填充),带高峰标记、observe-only 折叠标签、六个任务档位当前链首、新增模型/provider 的「需要重启」标记、走马灯行上的版本信息(当前运行版本——本地构建会附上所在提交短 SHA——更新检查发现新版本时以绿色显示 → v<最新版>,本地构建显示 → origin/main;已安装升级待重启时闪烁 [RESTART NEEDED] 标记),以及最新一条运行通知。面板每 2 秒轮询本地状态;非横幅 stderr 通知不会刷屏或遮挡输入框。这是一套独立的 TUI Slot 插件(src/tui.tsx,导出路径 opencode-switchman/tui),与 server 端 hook 插件互相独立。
推荐工作流:先用 TUI 完成全部配置——选好模型收藏、调好
/poolConfig与/modelRank、盯着侧栏看它路由;之后可自行选择是否换用桌面端(两端共享同一份配置与状态,而弹窗、侧栏、横幅等操作面在 TUI 里最完整)。
TUI 插件没有目录自动发现机制,需要在 tui.jsonc/tui.json 的 plugin 数组里加入同一个包 spec(npm 安装或 opencode plugin <spec> 会自动完成;只有手改配置或从源码用 mode:local/mode:prod 时才需要手动确认):
{
"plugin": ["opencode-switchman"]
}手动配置命令让你用配置压过系统默认决策,全部状态落盘、可手改、保存即热加载(mtime 感知,即时生效,侧栏同步刷新)。会话式(AI 交互换算 CLI)版本为同名的 -chat 后缀命令。/poolConfig 与 /modelRank 于 v0.2.5 引入;/switchman-setup 于 v1.2.0 引入。
- TUI(/switchman-setup):可续跑的一站式向导——首页展示实时完成状态(「开始」直达第一个未完成步骤),按车道序逐池弹出多选框(Enter 切换
[x]/[ ],每行标注能力档,含全选/全部取消/返回,每池确认即刻落盘、每池至少一个模型),随后在入选模型并集上按能力强到弱逐个点选排名(至少一个),完成页汇总各池选配、排名次序与仍需重启的 provider。 - 非 TUI / 会话内(/switchman-setup-chat):同流程会话式——agent 展示当前池/排名状态,逐池多选提问,询问能力强到弱的排名,经内置 CLI 落盘,校验六池加排名齐备后收尾。
- 语义——配置硬门槛:未配置的任务池不再默认「全部模型参与」。六池各有 ≥1 模型且排名 ≥1 条之前,主会话的任务派发被拒并附向导指引;未完成期间主会话每轮携带
[SETUP]指令。壳/内部会话豁免,且无豁免开关。门槛叠加于语言闸:项目语言偏好未配置前,语言询问保持唯一拦截声音。配置 mtime 热加载——最后一个文件保存的瞬间门槛即开,无需重启(重启只为注册全新 provider)。 - 配置文件:与下方 /poolConfig、/modelRank 相同的
pool-config.json+capability-rank.json。
- TUI(/poolConfig):弹出选择框(与选模型/思考等级同款交互)——先选任务池(economy / mechanical / main / hard / vision / review),再对全部可用模型上下勾选:选中即参与该池、再选即移出,附能力档标注。快捷项:「全选」与「全部取消」(重建模式——只勾选想保留的几个;一个都没勾就退出则保持原选配不变,清空后第一次勾选即写入新清单)。改动实时落盘并 toast 回执。
- 非 TUI / 会话内(/poolConfig-chat):会话式流程——注入各池选配总览(带池名可看
[x]/[ ]完整清单),回复「main 只留 3 5」「economy 勾 1、取消 2」由 agent 调switchman-config.js落盘。 - 语义:选配=让各任务池的候选模型体现差异化(如 economy 只配轻量模型、hard 只配重思考模型)——某池的手动清单优先于系统默认候选集,清单内模型仍按能力等级排序推荐;同一模型可重复参与多个池;未配置/空清单的池走系统默认决策。「清除配置」=恢复该池系统默认。
- 配置文件:
~/.config/opencode/opencode-switchman/pool-config.json(键=任务池名,值=参与该池的 modelId 数组)。
- TUI(/modelRank):弹窗按有效能力给出单一合并排序——手动条目与基础分模型交错排列;上移/下移会给模型锚定一个介于新上下邻居之间的手动分(一次挪一格,无需把上面的模型全排一遍),另有置顶/移出排名,即时生效。
- 非 TUI / 会话内(/modelRank-chat):会话式流程——注入当前排名与参考排序,回复「把 glm-5.3 排到最前」「清空排名」由 agent 换算
rank命令落盘。 - 语义:手动排名优先于基础能力分(实时第三方指数 → 内置快照 → 策展表全部让位)——命中模型(含其前缀变体)按排名序位取能力分与 S/A/B/C 档:排名 ≤4 项时依次 S/A/B/C;≥5 项按分位口径(top20% S / 次20% A / 次20% B / 其余 C,与 OpenRouter 序位派生同口径);同档内按序位线性分细排。未排名模型不受影响。排名参与所有决策面:六档链排序、档位亲和、能力等级闸与 deny 改派建议。
- 配置文件:
~/.config/opencode/opencode-switchman/capability-rank.json(models数组顺序=能力降序,#1 最强)。
- 用法:
/expert <你的需求或设计问题>— 描述会原样传给专家;不带描述时代理会先询问。 - 行为:把需求派发给当前最强的可用专家——优先 review 链头(跨家族专家席位,只读壳);review 池无可用候选时降级到 hard 链头的只读(
-ro)壳,并声明DOWNGRADED。 - 专家结论完整转述,末尾注明所用壳与车道(如
expert: <shell> (review))。
上述命令亦可用随包 CLI 直操作:node <包目录>/dist/switchman-config.js pool list|add|remove|set|clear(池名=economy/mechanical/main/hard/vision/review)/ rank list|set|add|remove|clear(编号引用 list 输出)。横幅 [LIMITS] 行会标注当前生效的手动覆盖(「manual capability rank: N models / task-pool selection: M pools」)。
多订阅并存的真实痛点:
- 认知错配:让旗舰模型干扫描清点的杂活,token 花在不该花的地方;让轻量模型做架构设计,返工反而最贵
- 水位盲飞:GLM 5 小时窗耗尽了还在硬撞、Copilot premium 积分月底作废没花完、DeepSeek 余额见底才发现
- 单点视角:复审用同一个模型族自查,盲区相同,审不出问题
- 协议松弛:「让 XX 帮我看看」式委派无结构、无校验,子代理拿到的是含糊任务
opencode-switchman 把编排拆成三层,各司其职:
| 层 | 载体 | 职责 |
|---|---|---|
| 认知层 | 主模型(调度员)+ 随包注入的调度员规程 | 任务四维画像(认知强度×机械度×上下文×紧急度)、决定自做还是委派、选档选壳、写 DELEGATION_V1 委派 prompt |
| 执行层 | 「模型×档位」空壳子代理(如 glm-mx-53-high) |
只绑定模型与思考档位,角色由委派 prompt 动态赋予(programmer/tester/reviewer 等 14 角色) |
| 确定性层 | 插件本体 | 六闸拦截、ROUTE_META 校验(缺失→按 lane 合成、非法→拒绝)、加权模型评分、配额/成本感知选链、探针 / 熔断 / 实调隔离自愈、四行横幅实时注入 |
Token 经济学为第一性原则:返工是最贵的 token。由此派生六档认知分层——
| 档位 | 典型角色 | 用什么 |
|---|---|---|
| economy | clerk / scouter 扫描清点 | 最便宜的轻量模型,medium→high→low→minimal 档(先支持哪个用哪个) |
| mechanical | tester / ops 回归与脚本 | 轻量模型,medium→high→xhigh→max 档 |
| main | programmer / uiux / data-analyst | 主力模型,medium→high→xhigh→max 档 |
| hard | planner 架构核心 | 最强模型,high→xhigh→max 档 |
| vision | observer 看图 | 视觉模型,medium→high→xhigh→max 档 |
| review | reviewer / 专家席 审案 | 强制异模型族(防同族盲区),high→xhigh→max 档 |
思考档位偏好是独立的一层路由算法:每档按上表偏好序选思考档(首个被支持的档位即默认档);off 档只作 lane 级兜底——仅当该档没有思考档候选可用时(如只支持开/关的模型)才进链,绝不排到思考档候选之前。壳在排序前还按能力面划池:review 只从 ro(只读)壳池选,其余 lane 只从 rw 壳池选,仅当本池为空才跨池兜底。只读壳以 edit: "deny" 运行,并配只读 bash 白名单(git 查看类子命令——git status/diff/log/show/blame/rev-parse/ls-files/grep/shortlog/describe/merge-base、git stash list,以及 git branch/tag/remote/worktree/config 的仅列表形态——加上 rg、grep、cat、ls、head、tail、stat、tree 等检索/查看工具);其余命令(含带变异形态的 find/sed/awk/echo)全部落到兜底 deny,ro 提示词末尾附一行说明,要求只汇报结论、绝不尝试写入。
水位只影响排序(用满不浪费),唯一硬拦是「调用必失败」(额度确定耗尽或硬门命中);按量计费(billing: "api")provider 在自动路由中不会被 deny——它们经 0.85 系数在同能力档内沉底,未知 provider 模型经 0.75 惩罚沉底,无需任何厂商专属的链尾席位或 deny 规则。
flowchart TD
A[opencode 启动] --> B[config 钩子<br/>注入全量壳矩阵到 cfg.agent<br/>+ 凭证收集]
B --> C[后台预热<br/>探针矩阵 / 三池配额 / 计价快照<br/>10min 周期自愈刷新]
C --> D[主模型工作<br/>按调度员规程决策]
D --> E{自做 or 委派?}
E -->|小任务| Z[主模型直接完成]
E -->|委派| F[选档选壳<br/>写 DELEGATION_V1 + ROUTE_META]
F --> G[task 派发<br/>tool.execute.before 拦截]
G --> H{六闸判定}
H -->|放行| I[壳子代理执行]
H -->|deny| J[报错附原因+改派候选<br/>主模型按链改派]
I --> K{执行结果}
K -->|成功| L[摘要回传主模型]
K -->|失败| M[event 钩子记账<br/>classifyFailure + 隔离<br/>600s 窗 ≥2 败 → 熔断 600s]
M --> D
J --> D
D -.每轮 LLM 请求.-> N[system.transform<br/>注入调度员规程 + 四行横幅<br/>路由/水位/限制 实时可见]
主模型派发子代理时,插件在 task 工具执行前做确定性校验,任一命中即 deny 并附改派候选:
| 闸 | 判定 | 语义 |
|---|---|---|
| 1 注册表 | 壳未启用/未探测 | 禁派未注册面 |
| 2 探针矩阵 | 组合实测 down / retired | 拦明确不可用;连续 404 下线消失模型 |
| 3 熔断 / 隔离 | 600s 窗内 ≥2 败或实调隔离中 | 「连续失败熔断中,约 10 分钟自动恢复」/「实调失败后隔离中」 |
| 4 池耗尽 | 配额判定必失败 | 附人读原因(GLM 100% / Copilot 确定耗尽 / DS 欠费) |
| 5 协议 | ROUTE_META 缺失/非法 | 缺失或无法解析的行 → 按壳所在 lane 合成 META 后放行并记状态日志;存在但错误(非法值 / 缺必填字段)→ deny 附样例与合法值表 |
| 6 语义 | 同族复审 / rw→ro 壳 / 图像→非视觉壳 | 「复审须异族视角」等 |
ROUTE_META 是嵌在委派 prompt 内的单行协议,六键六值,插件逐字段校验:
ROUTE_META {"lane":"main","role":"programmer","producer_family":"glm","capability":"rw","modality":"text","source":"auto"}
- 探针:对三大额度池发起真实请求探活(其余供应商 fail-open 放行),矩阵落盘(TTL 600s)。配置面变化立即全量刷新;平时由 10 分钟周期自愈。
- 配额:GLM monitor / DeepSeek balance / Copilot
copilot_internal/user直查,无代理、分层 TTL 缓存。 - 失败分类:厂商无关的
classifyFailure归一为rate_limit / quota / auth / not_found / server / network / unknown。探针 429 仅置strained(降权留链);实调 429 不再误置 Copilot 池耗尽,只有 402 或 403 且含 quota 文案才置耗尽。1 小时窗内连续 3 次 404 会自动 retired:链路排除、闸 deny、横幅标注。 - 实调失败隔离:探针 ok 但实际委派失败时,combo 进入内存隔离 30 分钟(
rate_limit类 10 分钟),所有会话即时感知,重启即清;它与既有 600s 熔断双轨并行。 - 成本与评分:models.dev 计价与策展能力分共同进入加权评分;硬门命中的候选先出局再评分。
- 决策日志:每次横幅重建把候选链与因子分写入
state/routing-decisions.jsonl(环形 200 行)。 - 横幅:每轮系统提示注入
[ROUTES][WATERMARK][LIMITS][UPDATE]四行,调度员实时可见。[LIMITS] 行包含下线模型数量与降级标注;[UPDATE] 行在发现新版本时给出升级 / 忽略命令入口。 - 自更新:启动检查缓存 24 小时。prod 模式对比 npm registry,可执行
/switchman-update静默升级,随后横幅显示「已升级待重启」并提醒重启;/switchman-ignore仅忽略本会话,重启后恢复提示。local 模式对比origin/main,只提示手动更新并仅注册/switchman-ignore。 - fail-open 铁律:任何钩子异常只写 stderr 绝不阻塞主流程;配额未知不硬拦,熔断、探针与实调隔离互为独立事实源。
~/.config/opencode/opencode-switchman/:shells.json(可选自定义覆盖,缺省用插件内置矩阵)、model-matrix.json(探针)、routing.json(熔断)、routing-decisions.jsonl(200 行评分审计环形日志)、failures.log(记账)、*-quota.json / ds-balance.json(配额缓存)、costs.json(计价)、delegation-template.md(委派模板全文)。
壳矩阵不再是静态清单,而是运行期动态构建、实时更新:
- desktop app 可见模型与 CLI/TUI favorites 双向同步。
mtime决定更新方向;同毫秒平局不写任一侧,必要时使用默认 CLI 路径兜底。 - 两者皆未设置时,自动回退为「当前活跃会话正在使用的模型」;多会话并行取并集,任何会话切换模型,矩阵在下一请求实时跟进。
- 模型管理 / favorites 变更实时监听(fs.watch + mtime 轮询兜底)。任一配置面变化都会立即重算激活矩阵并触发全量探针刷新,不等待 TTL;10 分钟周期刷新继续负责自愈。
- 新增 provider 实时检测并横幅提示(agent 注册表运行期不可变,对应壳重启 opencode 后自动纳入,无需手动维护)。
- 启动即注入超集壳(有凭证 provider 的全部可对话模型 × models.dev 档位),
matrix.mode=legacy可完整回退旧静态矩阵行为。
路由现在是显式、可追溯的评分,而不是隐藏偏好序:
- base 能力分主导:策展的 S/A/B/C 能力分按 exact 模型 id → 前缀 → family → global fallback 四路匹配,并记录命中路径。tier 分组不可逆:低档永远压不过高档。
- 加权系数:最终分数乘以
effortFit × health × water × costBias × peak × billingBoost × unknownPenalty。health 为ok=1.0/strained=0.6;water 取两个窗口中更吃紧者,并会在 Copilot 富余且临期时反向提权烧积分;peak 对任意 provider 的高峰窗口做同档×0.93让位,绝不跨能力级出局。billingBoost只由opencode-switchman.jsonc显式billing字段驱动(subscription=1.0、api=0.85)——编排规则零厂商硬编码;unknownPenalty=0.75施加给精确→前缀→family 全链未命中的未知组模型,同 tier 排已知模型之后。 - 硬门不参与打分:down、熔断、池耗尽、retired、实调隔离中的组合先出局再评分。
immediate紧急档改按探针延迟排序。 - 决策日志:每次横幅重建都会把各档候选与六因子评分写入
state/routing-decisions.jsonl,保留 200 行环形日志。
主会话享有软/硬/压三档水位+自动交接;被委派的壳子代理会话此前完全没有上下文控制,一路跑过 18 万 token 也无人拦截。现在每个壳子代理会话只有一道硬顶(context.subagentForceTokens,可选——缺省跟随主会话 forceTokens,即默认 130,000 token,与主会话共享同一条绝对终止线;显式覆盖时钳制 20k..1M,并在可知时额外以壳模型上下文窗口的 90% 封顶),实测口径与会话水位相同:最新 assistant 消息的 input + output + reasoning + cache.read。硬顶终止之前有两档柔性提醒,直接复用主会话的绝对软/硬阈值(softTokens 省着用 / hardTokens 收尾交接——子代理上下文与主会话上下文同等昂贵),有效上限按比例下拉两档。触顶后,插件拒绝该子代理会话内的所有后续工具调用并下达收尾指令;子代理随后给出的纯文本答复——一份详细的工作进度总结(已完成 / 关键发现含 file:line 证据 / 未完成 / 下一步)——即作为任务结果返回给委派方,会话随即永久终止(终止事件写入状态日志)。合规两侧预先约定:子代理系统提示的壳规则第 6 条(首次触顶拒绝即停止、交回总结),随包调度员规程第 2 节约定编排侧契约(绝不重试已终止的会话;重新派发、只注入所需上下文)。
终止是永久且有意的:此后任何通过 task_id 恢复该会话的 task 调用都会被永久拒绝(持久登记 ~/.config/opencode/opencode-switchman/subagent-cap.json,重启不失效),不带 task_id 的全新派发不受影响。理由:子代理是可复现的工人(其规格写在委派 prompt 里),「终止并交回」优于「压缩后续跑」。context.subagentCap: false 只阻止新的终止——已终止的会话不复活。
由 opencode-switchman.jsonc 的 context.subagentForceTokens(可选——缺省跟随 forceTokens)/ context.subagentCap(默认 true)配置(详见配置项表)。
每个主会话(main)创建时,插件都会自动建立项目内目录 <project-root>/.switchman/<yyyy-mm-dd>/<sessionId>-<title>/(日期取会话创建当天;标题 slug 段会在会话标题生成或修改时自动重命名)。注入的调度员规程每轮插值该目录路径,方案、实现进度、过程管控笔记、设计文档等中间工件默认落到会话目录,不再散落仓库各处或堆进对话。插件同时在目录内维护以下文件:
SESSION.md— 会话元数据(id / 标题 / 项目 / 时间戳)dispatches.jsonl— 每条被放行的任务委派一行 JSON(ts / shell / lane / role / source / redirected)media/— 视觉委派中转的图片(已从旧全局状态目录迁来,fail-open 兜底)
由 opencode-switchman.jsonc 的 workspace.enabled / workspace.dirname 配置(默认 true / ".switchman");关闭后不再创建任何目录,规程中的对应段落同步失效。
opencode 服务器自身运行在 tmux 中时,每条被委派的子代理会话都会以 opencode attach <server> -s <session> 实时窗格打开,在主 tmux 窗口右侧纵向堆叠(主窗格保持左侧份额——默认 40%,子代理列占右侧 60%)。窗口只会在主窗格(服务器启动时所在窗格,即启动时的 TMUX_PANE)上切分:你自己的侧边窗格与 tmux 状态栏绝不会被触碰;从其他窗格接入的 TUI 客户端同样能在那里看到这些子代理窗格。
开箱即用,无需任何配置。唯一前提:在 tmux 会话中运行 opencode;tmux 之外该功能完全惰性、零副作用。
- 可见上限+FIFO:子代理窗格最多同时可见 3 个(
tmux.maxPanes,1..4);超出的并发派发在 FIFO 队列中等待,某个可见子代理结束后,排队者原地接管其窗格(原地重生,窗格数不变)。每次完成都会收缩右列并重新均分布局:3→2 均分 → 1 独占右列 → 0 = 只剩主窗格(全宽恢复)。 - 卫生:窗格通过 pane 标题标记为
swm:<agent-name>;上次崩溃残留的窗格会在插件启动时清扫(kill,按标题前缀或 attach 启动命令匹配)。每次布局操作后都会恢复窗口的活动窗格(焦点保持)。 - 天生安全:不在 tmux 中或
tmux.enabled=false时完全惰性;所有 tmux 失败一律 fail-open——只写状态日志,绝不阻塞派发。 - 观看须知:该窗格是附加到子代理会话的真实交互式 TUI——不要在里面打字(按键会进入子代理会话)。退出观看窗格只是移除显示,子代理继续运行。
由 opencode-switchman.jsonc 的可选 tmux 段配置(enabled / rightPct / maxPanes / mini,默认 true / 60 / 3 / false)。
默认(matrix.mode=auto)矩阵在运行期动态构建:desktop 可见模型与 TUI favorites 自动双向同步,会话模型兜底,任一配置面变化都会触发全量探针重算,无需任何维护;模型临时 down 由探针自愈(每 10 分钟后台刷新,自动进降级/熔断),连续 404 的消失模型会 retired,直到配置面再次变化。
超集保底=opencode 自带免费模型(OpenCode Zen:models.dev opencode provider 下 -free 后缀模型+big-pickle 特例,且剔除 status=deprecated 的已轮换旧模型=「今日可用」集,随目录每 24h 滚动、无需手工维护);目录不可用(无网冷启动)时 fail-open 回退内置静态清单。
内置静态矩阵仅作为 legacy 模式与离线兜底。如需自定义 legacy 静态面:
# 1. 同步权威启用面(opencode 模型管理中打开的模型,每行 provider/model-id)
$EDITOR scripts/visible-models.txt
# 2. 重生成内置矩阵(拉取 models.dev 档位声明)
bun run gen:shells
# 3. 重启 opencode(legacy 模式生效)bun install
bun test # 行为契约 fixture(META/六闸/选链/评分/熔断/配额/更新)
bunx tsc --noEmit # 类型检查
bun run build # 重新生成矩阵并打包单文件 bundle本地调试与正式包可用幂等脚本一键切换,切换后重启 opencode 生效:
bun run mode:local # build + 三处配置切到 file:// 本仓库(仓库根自动推导)
bun run mode:prod # 拉 npm 最新版,切到精确版本条目 + 清旧插件缓存 + 升级横幅
bun run mode:prod --version 0.2.0 # 指定版本回切(免联网)两条命令都会同步三处配置(行级手术保留注释与第三方插件,幂等可重复执行):
opencode.jsonc/opencode.json与tui.jsonc/tui.json的plugin数组(tui 缺失自动补建,侧边栏状态面板跟随 hook 插件一起切源)- 主配置
opencode-switchman.jsonc的$schema(local 指向仓库内 schema,prod 指向 GitHub main)
prod 与一键安装器共用同一套改写/缓存清理逻辑(scripts/update-cli.mjs);从源码切换后若要长期使用正式版,仍推荐 npx -y opencode-switchman@latest。
分版本的用户向摘要;完整发布说明与升级指南见 CHANGELOG.md。
- 壳子代理上下文硬顶:每条壳子代理会话现在都有硬性上下文上限(
context.subagentForceTokens,默认 100k token)——越过上限后每次工具调用都会被拒绝并附收尾指令,子代理以一份详细的进度总结作为任务结果交回主会话,且该会话永远无法再经task_id续接(持久化注册表)。详见 子代理上下文硬顶。 - 常开逐次调用读预算(核心算法更新):用确定性预算闸取代旧的「每工具一次性提醒」(那种优惠券式提醒会被模型用重试/试探理性烧掉)。自第 1 轮起,每次读取都按
context.readBudgetTokens(默认 1500)计费——预估超限的读取就地追加limit有界放行,或以精确的有界重试参数拒绝;每轮 2× 自读上限(用户发言即重置)阻断连续读取链;无法预估的工具输出事后记账。水位只保留生命周期职责(软=建议、硬=收尾拒绝、压=自动交接)。交付/验证类 bash(git、测试/lint、构建)任何水位放行;无界翻史(不带-n的git log -p)任何水位拦截并附收窄提示。 - 项目级语言偏好:每轮注入
[LANG]铁律行(会话 / 注释与提交 / 文档三种语言),首次使用时询问并按项目落盘(未配置则每轮用户输入都会重新询问,且写入/编辑/bash/派发调用会被硬闸门拒绝并指回问卷;用户明确拒绝则本会话豁免),/switchman-lang可随时修改。 - 待办纪律:规程 §0.7 + 每轮
[TODO]状态行,主会话待办实时更新(含委派壳的结果)。 - /expert 专家咨询与随包 agent skills:需求一键派给当前最强跨家族专家;开箱技能启动时同步进 opencode 全局技能目录(只增改不删、标记门控清理、fail-open)。
- review 档兜底:跨家族只读壳全灭时保留最优 ro 壳、允许同族评审并标注
DOWNGRADED,不再出现空链。 - 自动交接健壮性:
[backup]备份自行编号(重启不乱、编号不回收)、压缩走与手动/compact相同通道、压缩腿异步化不再死锁会话。 - 侧栏版本行:走马灯行显示当前运行版本,更新检查发现新版本时同时显示最新版本;闪烁的
[RESTART NEEDED]标记现在也覆盖「已安装升级但未生效」的场景。 - tmux 窗格镜像:opencode 服务器自身跑在 tmux 里时,每条被委派的子代理都会在主 tmux 窗口右侧列以实时
opencode attach窗格打开——可见窗格封顶+FIFO 队列、原地接管、完成即重新均分布局,全程 fail-open。详见 tmux 窗格镜像。
- 协议资产、运行期消息、代码注释与文档全面英文化;横幅锚点更名为
[ROUTES]/[WATERMARK]/[WATERMARK:SESSION]/[LIMITS]/[UPDATE]。 - TUI 侧栏排版配色打磨:8 列对齐的配额网格、渐变水位条叠于暗色轨道、400 级亮色系、observe-only 折叠标签。
v0.2.0 将 switchman 从固定多供应商调度器升级为实时、能力感知的编排层。
- TUI 运行视图:可选侧边栏面板集中展示水位、高峰窗口、六档链首、待重启状态和最新运行通知。
- 动态激活矩阵:双向同步 desktop 可见模型和 CLI/TUI favorites;未配置时以活跃会话模型兜底;模型面变化即刻重算并刷新探针。
- 能力感知路由:运行期动态分级,强模型优先于低级模型;再以档位亲和、健康、水位、高峰、显式计费和未知模型置信度做可追溯的同级排序。
- 供应商中立策略:任意 OpenCode 官方或自定义 provider 都可参与;由显式
billing: "subscription" | "api"取代厂商专属路由偏好。 - 更可靠的在线运行:新增实调失败隔离、重复缺失模型下线、路由决策审计日志和更清晰的重启/更新提示,让失败可观察、可自愈。
- 更简单的配置与升级:全部插件配置统一到自动生成的
opencode-switchman.jsonc;旧元组 options 会被诊断,并再兼容一个版本。/handover直接执行(无 AI 往返):把当前完整会话分叉为[backup]备份并就地压缩当前会话,留在同一会话内(不同于内置/fork会切到分叉会话)。越过压水位也会自动触发(context.autoHandover,默认开启),未完成的任务在压缩后的上下文上继续。
- 技术方案(契约/算法/实测记录)
- 调度员规程:内置于
src/assets/agents-md.ts,随包经系统提示自动注入(仅英文,无需手动安装;仓库根目录的 AGENTS.md 仅为插件开发指南) - 委派模板 DELEGATION_V1:安装后见状态目录
delegation-template.md





