oh-my-kimi-code

多 Agent 编排层 for Kimi CLI —— 宋江意图门控 + 五路好汉协同作战。

一、项目定位

oh-my-kimi-code（简称 omkc 或 OMKC）是 Kimi CLI 的多 Agent 编排增强层。核心设计哲学：

宋江主导航 → 根据任务复杂度自动路由 → 调度最适合的模型完成任务。

通过自定义 Agent YAML 定义五位专业子 Agent，在 Kimi CLI 原生 TUI 中实现一键调度，无需离开对话即可切换角色。

二、核心概念

Phase 0: 意图门控（Intent Gate）

每轮用户消息，宋江先判断意图类型，自动路由到最适合的处理模式：

| 意图类型 | 描述 | 模式 | 处理方式 | |---------|------|------|---------| | 问候/问答 | 你好/谢谢/再见 | Quick | 宋江直接回复，不调度子 Agent | | 状态查询 | 任务进度/当前状态 | Quick | 宋江直接回复 | | 快速修改 | 改个变量名/加个日志 | Quick | 公孙胜（coder）直接执行，无需完整流程 | | 代码探索 | 这个模块怎么工作的 | Quick | 时迁（explore）探索后直接回复 | | 编码实现 | 实现一个新功能 | Full | 五阶段完整流程 | | 审查/验证 | 审查这段代码 | Full | 林冲 + 武松审查验证 |

五路好汉（子 Agent）

| 好汉 | subagent_type | 角色定位 | 职责 | 工具权限 | |------|---------------|------|------|---------| | 时迁 | shiqian | 探索/搜索 | 代码库探索、搜索、分析 | 只读（ReadFile/Glob/Grep/Shell/SearchWeb） | | 吴用 | wuyong | 架构规划 | 架构规划、方案设计 | 只读（ReadFile/Glob/Grep/SearchWeb） | | 公孙胜 | gongsunsheng | 编码实现 | 编码实现、文件修改 | 读写（+WriteFile/StrReplaceFile） | | 林冲 | linchong | 代码审查 | 代码审查（不同视角） | 只读 | | 武松 | wusong | 测试验证 | 测试验证、类型检查 | 读写 |

模型配置说明：各路好汉的 primary 模型由用户根据本地 Kimi CLI 环境自行配置，OMKC 不做硬编码限制。fallback Agent 使用 Kimi CLI 已配置的可用模型作为回退实例，确保在主模型不可用时仍可继续协作。

Fallback 机制说明：每个好汉都有对应的 fallback YAML（如 wuyong-fallback.yaml）。extend: default 只继承 Kimi CLI 内置默认 Agent 的 spec/tooling，不会继承角色 prompt。主 Agent 与 fallback Agent 通过相同的 system_prompt_path 显式共享同一份角色 prompt。omkc doctor 会校验 primary/fallback 的 system_prompt_path 是否一致。

完整流程（Full Mode）

时迁 探索 → 吴用 规划 → 公孙胜 实现 → 林冲 审查 → 武松 验证
    ←─────────────────────────────────────────────→
              循环最多 3 次（审查严重问题时回退到公孙胜）

三、安装与配置

安装（推荐：通过 npm）

npm install -g oh-my-kimi-code
omkc install

幂等安装：omkc install 支持重复安全执行，不会重复注册 hooks。已有 OMKC hooks 会被自动去重并更新为最新配置，Windows 用户的 CRLF 换行格式也能正确处理。重复安装会保留本地六个入口 Agent（宋江 + 五路主 Agent）已有的 agent.model 自定义；其它手工 YAML 改动仍会被模板覆盖。

开发安装

如需从源码构建：

git clone <repo-url>
cd oh-my-kimi-code
npm install
npm run build
npm link   # 可选全局链接
omkc install

环境变量（可选）

如果你希望通过环境变量注入 API key 或自定义 Kimi CLI 路径，可以在项目根目录或 ~/.omkc/.env 创建 .env 文件：

# 根据你的 Kimi CLI 模型配置按需设置
# PROVIDER_API_KEY=sk-...
# PROVIDER_BASE_URL=<your-provider-url>

# Kimi CLI 路径（可选，默认 "kimi"）
KIMI_BIN=kimi

模型本身由 Kimi CLI 的配置文件管理；.env 只是可选的密钥注入方式。

配置 Kimi CLI 模型

在 ~/.kimi/config.toml 中按 Kimi CLI 规范注册模型别名：

[models.<your-model-alias>]
provider = "<provider-name>"
api_key = "<your-api-key>"
# base_url = "<provider-endpoint>"  # 如需自定义 endpoint 再设置

各路好汉 YAML 中的 model 字段引用这里的模型别名。

通过 omkc model 管理本地模型配置

omkc model 用于管理安装到本机的 ~/.kimi/agents/omkc/*.yaml 中的 agent.model 字段，不会修改 ~/.kimi/config.toml。

omkc model list
omkc model set <agent> <model>
omkc model unset <agent>
omkc model reset

• 支持 Agent：songjiang、shiqian、wuyong、gongsunsheng、linchong、wusong；也支持 sj/sq/wy/gss/lc/ws 和中文别名。
• list 中五路主 Agent 未设置本地覆盖时显示 <inherit default_model>。
• set 会写入对应本地 YAML：宋江写入 omkc-agent.yaml，五路主 Agent 写入各自 YAML。写入前会检查 ~/.kimi/config.toml 是否出现该模型别名；未找到只 warning，不阻塞。
• unset 删除五路主 Agent 的自定义 agent.model；为避免主入口失效，songjiang 不允许 unset。
• reset 只重置五路主 Agent，不影响 songjiang 和任何 *-fallback.yaml。
• omkc install 升级模板时会保留上述六个入口 Agent 已有的本地 agent.model 自定义。

四、使用指南

4.1 启动交互式会话

omkc chat

启动时自动扫描历史会话，显示宋江会话列表：

💬 启动 Kimi CLI — OMKC-宋江 (SongJiang)

  🐉 宋江会话:
     1. 实现用户认证模块                    📁my-project  (5轮 · 2小时前)
     2. 优化数据库查询性能                      📁my-project  (3轮 · 昨天)
     3. 修复 API 响应格式问题                    📁wechat-bot  (2轮 · 3天前)
  💬 其他会话:
     4. 如何使用 React Hook...                  (8轮 · 昨天)
     ... 还有 12 个

  0. 🆕 新建会话

请选择 [0-4]: 1
→ 恢复会话: xxx-xxx-xxx

关键特性：

• 选择历史会话 → 自动切换到该会话的创建目录 → kimi --agent-file omkc-agent.yaml --session <id> 启动
• 选择 0 → 新建宋江会话
• 跨目录会话带 📁 目录标记，恢复时自动 cd 到正确目录

4.2 命令行参数

# 新建会话（跳过选择）
omkc chat --new

# 直接恢复指定会话
omkc chat --session <session-id>

# 只列出会话，不启动
omkc chat --list

# 显示所有会话（含普通 Kimi 会话）
omkc chat --all

4.3 健康检查

omkc doctor

检查 Agent YAML、Hooks、config.toml 注册是否完整。omkc doctor 会逐条语义校验 8 个 OMKC hook 的事件类型、命令路径、超时时间和 matcher 配置是否正确，并检测重复注册、标记块不完整等问题。

五、Session 管理

问题背景

Kimi CLI 的 /sessions、/fork、/undo 命令通过 Reload 异常切换 session，但 Reload 只携带 session_id，不保留 --agent-file 参数。 这导致：用宋江 agent 启动的 session，通过 /sessions 切换后会丢失子 Agent 定义，只剩下默认的 coder/explore/plan。

OMKC 的解决方案

从外部管理 session，而不依赖 Kimi CLI 内部的 /sessions`。

• omkc chat 启动时显示所有宋江会话，选择后自动用 kimi --agent-file omkc-agent.yaml --session <id> 恢复
• session-start hook 自动记录每个 session 的创建目录（~/.kimi/omkc/session-index.json）
• 恢复时自动切换到正确的 work_dir，确保 Kimi CLI 能找到 session 文件

索引文件

~/.kimi/omkc/session-index.json
{
  "sessions": {
    "xxx-xxx": {
      "workDir": "E:\\projects\\my-app",
      "lastSeen": "2026-05-18T...",
      "source": "startup"
    }
  }
}

安装新 hook 后，新启动的 session 会自动被索引。旧 session 的 workDir 需要手动补充或在原目录重新启动一次。

六、CLI 命令速查

| 命令 | 说明 | |------|------| | omkc chat | 启动 Kimi CLI，只显示宋江会话 | | omkc chat --all | 显示所有会话（含普通 Kimi 会话） | | omkc chat --new | 跳过选择，直接新建宋江会话 | | omkc chat --session <id> | 直接恢复指定 session | | omkc chat --list | 列出宋江会话，不启动 | | omkc doctor | 检查 OMKC 安装完整性 | | omkc install | 安装 OMKC agent YAML + hooks 到 Kimi CLI | | omkc model list | 列出所有 agent 的 model 配置 | | omkc model set <agent> <model> | 设置某个 Agent 的本地模型覆盖 | | omkc model unset <agent> | 移除五路主 Agent 的本地模型覆盖（不支持 songjiang） | | omkc model reset | 重置五路主 Agent 模型覆盖，不影响宋江/fallback |

七、常见问题

Q: /sessions 切换后子 Agent 消失了？

A: 这是 Kimi CLI 的设计限制。/sessions、/fork、/undo 切换时不保留 --agent-file。

解决方法：使用 omkc chat 而非 /sessions

• omkc chat --list 查看所有会话
• omkc chat 选择恢复
• omkc chat --session <id> 直接恢复

Q: 恢复旧 session 时提示找不到文件？

A: 旧 session 的创建目录可能未被索引。请在 session 原始目录下运行一次 omkc chat --session <id>，hook 会自动记录目录。

Q: 如何让非宋江 session 也被索引？

A: 当前 session-start hook 只索引 OMKC_AGENT_ACTIVE=1 的 session。非宋江 session 不会被索引，这是正常行为。

八、技术栈

• Runtime: Node.js 24+ (ESM)
• Language: TypeScript 6+
• Deps: execa, chalk, dotenv
• Target: Windows / macOS / Linux
• Requires: Kimi CLI v1.44.0+

oh-my-kimi-code — 宋江调五路好汉，让每个任务都找到最适合的大脑。