Kimi Subagent Router（kimi-subagent-router）

为 Kimi Code CLI 提供按 subagent 类型自动路由不同模型与思考强度的插件，解决 [secondary_model] 只能设置一个全局默认模型、无法按任务复杂度分发的问题。

• 默认值只使用 Kimi Code 内置模型（K2.8 Preview、K3-256k），不假设已接入任何第三方模型。
• 所有映射关系可在 subagent-models.json 中配置，后期可切换到第三方订阅模型。
• 同一模型的不同思考强度（如 K2.8 high 与 K2.8 max）通过模型变体别名实现。

工作原理

Kimi Code CLI 的 Agent 工具在配置了 [secondary_model] 模型池后支持 model 参数（池别名或 "primary"），但没有 effort 参数。思考强度按官方机制由模型变体别名的 default_effort 绑定：变体是 [models] 中指向同一底层模型的独立条目，用 [models."<别名>".overrides].default_effort 覆盖档位（变体不继承被指向条目的字段，capabilities、support_efforts 必须完整照抄）。对 subagent 而言，变体的 default_effort 优先于全局 [thinking].effort，只有 [secondary_model].default_effort 优先级更高——所以不要设置 [secondary_model].default_effort。

因此本插件的派发路径为：

1. 主 Agent 以编排器与执行器自居：默认姿态是"这个任务该派给谁"，只有完全指定、无需判断、至多一两步的琐碎任务（如 git init、按字面删一行）才自己做；任何设计/权衡类决策一律先派 k3-planner 思考定案。插件关闭时不注入 SKILL.md，agents/*.md 与 MCP 工具也随插件启停，表现与原生 CLI 完全一致。
2. 主 Agent 依据 SKILL.md 的路由规则选择 subagent 类型，调用 MCP 工具 route_subagent_model 取得当前配置的模型别名（思考强度内嵌在该别名的 default_effort 中；k3-planner 档有快路径，可直接带默认别名 k3-256k-max 派发，跳过路由查询）。
3. 主 Agent 调用 Agent(subagent_type=<类型>, model=<别名>, prompt=..., description=...) 完成派发。
4. 若未传 model，由 [secondary_model].default_model 承接（默认 K3-256k + max，与临时环境基准一致）。

默认路由表（主 Agent 自身保持轻量，快速判断后派发）：

档位设计要点：尽量用 K3-256k——k3-planner 与 k3-max 思考强度都是 max，只有"最困难任务且预估上下文超过 256k"两个条件同时成立时才升级 1M 的 k3-max，其余复杂任务一律 k3-planner。K2.8 一侧按推理量细分：局部单文件修改走 k2.8-medium（high），简单功能实现/常规测试/常规调试排错走 k2.8-debug（max）。doc-writer 默认路由到第三方模型 alibaba-cn/qwen3.8-flash（OpenAI 兼容，xhigh 档位），使用前需按「切换到第三方模型」一节完成注册。

若主 Agent 或某个 subagent 想用其它档位，把 subagent-models.json 中对应条目的 model/effort 改为 k2.8-low/k2.8-high/k2.8-max/k3-256k-high 等即可；这些内置变体 setup-config 都会自动注册。

提示词语言约定

模型实际读到的文本一律用英文：SKILL.md、agents/*.md 的 frontmatter 与正文、subagent-models.json 的 description、MCP 工具描述与返回里的 notes/dispatch 模板、以及 setup-config 写进 [secondary_model.models] 的别名说明。中文提示词会让模型先内部翻译一遍再执行，既占上下文又降低指令服从度。边界按"谁会读这段文字"划：配置解析错误、doctor 的条目正文（[错误] doc-writer: 模型别名 … 未注册）这类指向人的修复指引保持中文——它们的终点是用户去改 config.toml，主 Agent 只是转述；而 doctor --json 的 level 字段与全部路由结果、工具返回是模型要据此行动的，一律英文。--help、setup-config 的提示同样保持中文。

agents/*.md 的写法按各档位模型的习性调过：

doc-writer 同时被明令：不确定的内容写 TODO: verify，宁缺毋造。

目录结构

kimi-subagent-router/
├── kimi.plugin.json      # 插件清单（CLI 实际读取；plugin.json 为同步副本）
├── plugin.json           # 与 kimi.plugin.json 内容一致（交付物命名要求）
├── SKILL.md              # 派发姿态与路由规则，会话启动时自动加载给主 Agent
├── subagent-models.json  # 用户可编辑的映射配置
├── README.md
├── agents/               # 七个 subagent 定义（插件级 agent，自动被发现）
│   ├── cheap-coder.md    # 排除后台任务管理与 Plan 模式进入
│   ├── cheap-explore.md  # 只读工具白名单
│   ├── k2.8-medium.md
│   ├── k2.8-debug.md     # 中等难度调试/排错（K2.8 max）
│   ├── k3-planner.md     # 无 shell，可读可写
│   ├── k3-max.md
│   └── doc-writer.md     # 排除 shell 与后台任务工具
└── scripts/
    ├── kimi_subagent_router.py   # 路由工具：MCP 服务 + CLI（Python 3 标准库，无依赖）
    └── deploy.sh                 # 一键部署脚本：同步到插件安装目录 + setup-config + doctor

安装

要求：Python 3.8+（脚本仅用标准库）；Kimi Code CLI 已 /login（内置托管模型别名由登录流程注入）。

# 1. 安装并启用插件（在 Kimi Code TUI 中）
/plugins install /path/to/kimi-subagent-router   # 也可用 zip URL / GitHub URL
/plugins enable kimi-subagent-router

# 2. 注册模型变体并写入 [secondary_model] 池（幂等，先备份 config.toml）
python3 /path/to/kimi-subagent-router/scripts/kimi_subagent_router.py setup-config

# 3. 检查一致性，然后激活
python3 /path/to/kimi-subagent-router/scripts/kimi_subagent_router.py doctor
# 在 TUI 中执行 /reload 或 /new

也可手动安装：把 scripts/kimi_subagent_router.py print-config 打印的 TOML 片段并入 ~/.kimi-code/config.toml（变体条目 + [secondary_model] 段），效果相同。

setup-config 行为说明：

• 片段包在 # >>> kimi-subagent-router >>> 标记内，重复运行会原地更新（幂等）；改动映射后重跑一次即可。
• 若你的 config.toml 已存在 [secondary_model] 段或冲突的 [models] 条目，脚本拒绝写入并打印需手动合并的片段（不会破坏现有配置）。
• 写入前总是先备份为 config.toml.kimi-subagent-router.bak-<时间戳>；生成的 TOML 经解析校验后才落盘，失败自动回滚。
• 卸载：python3 scripts/kimi_subagent_router.py remove-config（只删标记块，不碰其他配置），再 /plugins remove kimi-subagent-router。

重新部署

维护修改本仓库后，一键同步到已安装的插件目录并刷新配置：

bash scripts/deploy.sh

脚本自动完成：定位插件安装目录（读 ~/.kimi-code/plugins/installed.json，失败回退默认路径）→ rsync 镜像同步（排除 .git/.qoder，目标缺失或非插件目录时中止）→ 重跑 setup-config（幂等，自动备份 config.toml）→ 运行 doctor 验证（有错误则非零退出）。完成后在 Kimi Code TUI 中执行 /reload 或 /new 生效。

修改映射

编辑 subagent-models.json（插件根目录下的副本，或复制到 ~/.kimi-code/subagent-models.json 以获得更高优先级——查找顺序：$KIMI_SUBAGENT_MODELS 环境变量 > $KIMI_CODE_HOME/subagent-models.json > 插件目录 > 内置默认值；每次工具调用都会重新读取，改完立即生效，无需重启）。

字段说明：

可自由增删条目：新增一个 subagent 名称 + 对应 agents/<名称>.md agent 文件即可；自定义模型别名若是第三方模型，按下一节注册。

切换到第三方订阅模型

两步，约 5 分钟：

第一步：在 config.toml 注册第三方模型

以 DeepSeek（OpenAI 兼容协议）为例，在 ~/.kimi-code/config.toml 中添加：

[providers.deepseek]
type = "openai"
base_url = "https://api.deepseek.com/v1"
api_key = "你的API_KEY"

[models."deepseek/deepseek-v4.1-flash"]
provider = "deepseek"
model = "deepseek-chat"
max_context_size = 131072
capabilities = [ "tool_use" ]

也可以直接在 TUI 运行 /provider（或 shell 命令 kimi provider）走交互式向导：选供应商、输 API Key、选模型；models.dev 已收录的供应商会自动拉取模型列表。

注意事项：

• 能力声明：模型不支持 thinking 就不要在 capabilities 里声明。部分第三方模型支持 reasoning_effort 字段，但取值与 Kimi 的 low/high/max 不同，本插件不假设兼容性——不支持 Kimi 档位时把 JSON 里的 effort 设为 null 或删除。
• 池成员：新别名必须加入 [secondary_model.models] 池，Agent 工具的 model 参数只接受池别名或 "primary"。最简单的方式是改完 JSON 后重跑 setup-config（它能自动把新别名补进池中；生成不了条目时会明确提示手动注册）。
• 凭证管理：api_key 可直接写在 config.toml，也可用 [providers.<name>.env] 子表引用环境变量名（仅作回退来源，不会修改 shell 环境）。

第二步：修改 subagent-models.json

"cheap-coder": {
  "model": "deepseek/deepseek-v4.1-flash",
  "effort": null,
  "subagent_type": "coder",
  "description": "Mechanical, pattern-fixed coding: bulk renames, formatting, boilerplate"
}

重跑 doctor 确认无错误，执行 /reload。

验收自查

# 复杂任务路由（k3-planner = K3-256k max；k3-max = kimi-code/k3 1M max）
python3 scripts/kimi_subagent_router.py route --type k3-planner
python3 scripts/kimi_subagent_router.py route --type k3-max
# 廉价任务路由（cheap-coder 应返回 k2.8-high；cheap-explore 应返回 k2.8-low）
python3 scripts/kimi_subagent_router.py route --type cheap-coder
python3 scripts/kimi_subagent_router.py route --type cheap-explore
# K2.8 细分档（应返回 k2.8-high / k2.8-max）
python3 scripts/kimi_subagent_router.py route --type k2.8-medium
python3 scripts/kimi_subagent_router.py route --type k2.8-debug
# 文档任务（应返回 alibaba-cn/qwen3.8-flash，effort 为 xhigh；需先注册该第三方模型）
python3 scripts/kimi_subagent_router.py route --type doc-writer
# 一致性检查（0 错误即通过；doc-writer 未注册第三方模型时会如实报错）
python3 scripts/kimi_subagent_router.py doctor

安装后让主 Agent 执行一个明显复杂的任务（如"为这个项目设计插件架构"），它应派发 k3-planner/k3-max；执行"把 src 下所有 .js 文件重命名为 .ts"这类任务应派发 cheap-coder。

已知限制

1. Agent 工具没有 effort 参数：思考强度只能经由模型变体别名的 default_effort 绑定；插件的 route_subagent_model 工具返回 effort 仅供核对/展示。同理，插件无法实现"封装 dispatch_subagent 内部直接派发"的路径（MCP 工具无法调用 CLI 内部的 Agent 机制），采用的是路径 A：工具返回别名，主 Agent 显式传入 Agent 的 model 参数。
2. 映射是路由建议而非强制：最终由主 Agent 在 Agent 调用中传 model 生效；若主 Agent 省略 model，spawn 落到 [secondary_model].default_model（默认 k3-256k-max）。
3. [secondary_model].default_effort 会击穿路由：该字段优先级最高且段级生效，设置后所有变体档位失效。doctor 会警告；请保持未设置。
4. k2.8-medium 名称含点号：个别 CLI 版本对 agent 名的 kebab-case 校验可能不允许点号，导致该 agent 文件被跳过（派发时提示未知类型）。解决办法：把 agents/k2.8-medium.md 重命名为 k28-medium.md、frontmatter 的 name 改为 k28-medium，并同步修改 subagent-models.json 的键与 SKILL.md 路由表。
5. 单层委派：插件 agent 均声明 subagents: []，无法在 subagent 内继续派发，委派链单层终止。
6. 配置错误 fail-loud：池别名解析不到 [models] 条目时，会话启动/恢复会直接报错并列出断链别名（这是 Kimi Code 的行为，先于插件）。改配置后跑 doctor 可提前发现。

参考文档

• Agents and Sub-Agents：https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents.html
• Plugins：https://www.kimi.com/code/docs/en/kimi-code-cli/customization/plugins.html
• 配置文件（[secondary_model] 与模型变体机制）：https://www.kimi.com/code/docs/en/kimi-code-cli/configuration/config-files.html
• Providers and models：https://www.kimi.com/code/docs/en/kimi-code-cli/configuration/providers.html