kimi_subagent_router

# 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 自身保持轻量，快速判断后派发）：

| 任务 | subagent | 模型别名 | 思考强度 |
|---|---|---|---|
| 重复性机械操作 | `cheap-coder` | `k2.8-high`（K2.8 Preview） | high |
| 只读探索 | `cheap-explore` | `k2.8-low` | low |
| 单文件修改等局部改动 | `k2.8-medium` | `k2.8-high` | high |
| 简单功能实现、常规测试、常规调试排错 | `k2.8-debug` | `k2.8-max` | max |
| 复杂构思/架构/跨模块重构/非显而易见 bug | `k3-planner` | `k3-256k-max`（K3-256k，**优先使用**） | max |
| 最困难任务**且**预估上下文超过 256k | `k3-max` | `k3-max`（kimi-code/k3，**1M 上下文**） | max |
| 文档编写 | `doc-writer` | `alibaba-cn/qwen3.8-flash`（第三方，需先注册） | xhigh |

档位设计要点：**尽量用 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` 的写法按各档位模型的习性调过：

| 档位（模型） | 模型特点 | 提示词对策 |
|---|---|---|
| `cheap-explore`（K2.8 low） | 不会自己补全意图，容易一次命中就收工 | 编号步骤、检索预算（约 15 次调用）、固定输出格式，禁止开放式判断 |
| `cheap-coder` / `k2.8-medium`（K2.8 high） | 高思考档最爱"顺手改"与过度设计 | 范围锁定、字面执行、改完做机械性验证（旧 token 零命中） |
| `k2.8-debug`（K2.8 max） | 推理预算足，但会写成一篇长文 | 复现→定位→单假设证伪→根因修复的循环；思考留在思考里，结论按格式简短交付 |
| `k3-planner`（K3-256k max） | 长链推理强，容易输出方案菜单与"待验证" | 要求定案一个推荐＋被否方案各一行；无 shell，改为移交验证命令 |
| `k3-max`（k3 1M max） | 上下文是它存在的理由，但要防读散 | 先 Glob/Grep 建地图再大块读，每条结论附 `path:line` |
| `doc-writer`（qwen3.8-flash xhigh） | 文笔好，但易浮夸堆表情、把没读过的细节写得很像真的 | 代码为唯一事实来源、风格禁则、沿用仓库语言（中文文档保持中文） |

`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`（内置托管模型别名由登录流程注入）。

```bash
# 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
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` > 插件目录 > 内置默认值；每次工具调用都会重新读取，改完立即生效，无需重启）。

字段说明：

| 字段 | 含义 |
|---|---|
| `subagents.<名称>.model` | 模型别名。缺失或 `null` 时回退到 `[secondary_model].default_model`。指向内置变体（`k2.8-low` 等）时无需其他操作；指向自定义别名时需先在 `config.toml` 注册该别名并加入 `[secondary_model.models]` 池 |
| `subagents.<名称>.effort` | 思考强度声明（Kimi 档位 `low`/`high`/`max`，第三方模型可为 `xhigh` 等）。实际绑定靠别名的 `default_effort`；声明值用于核对，`doctor` 发现不一致会警告。第三方模型不支持 Kimi 档位时设为 `null` 或删除 |
| `subagents.<名称>.subagent_type` | 该条目继承的内置类型语义（`coder`/`explore`/`plan`），供阅读与工具策略参考 |
| `subagents.<名称>.exclude_tools` | 高风险工具排除说明（信息性；实际强制在 `agents/*.md` 的 `tools`/`disallowedTools`） |
| `subagents.<名称>.description` | 职责描述，会随路由工具返回进入主 Agent 上下文（另见「提示词语言约定」：用英文） |
| `default_model` | 顶层兜底：当某条目 `model` 为 `null` 时用它（本仓库默认为 `"k3-256k-max"`）；若该字段本身缺失或为 `null`，`setup-config` 回退到内置池默认值 `k3-256k-max` 并打印警告 |

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

## 切换到第三方订阅模型

两步，约 5 分钟：

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

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

```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`

```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`。

## 验收自查

```bash
# 复杂任务路由（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