oh-my-kimi-cli
v1.0.5
Published
Workflow orchestration layer for Kimi Code CLI - Bring structured workflows, agent teams, and persistent execution to your Kimi CLI sessions
Maintainers
spiritpunchReadme
🚀 oh-my-kimi (OMK)
🎯 问题所在
Kimi Code CLI 是一个强大的通用执行引擎。它能读代码、执行 Shell 命令、生成子代理、自主规划任务。但当你用它做真正的软件开发时，很快就会遇到阻力：
| 痛点 | 发生了什么 |
|------|-----------|
| 没有结构化流程 | 直接跳到编码，需求没澄清、架构没设计。后期重构成本是初期的 3 倍。 |
| 会话失忆 | 每次启动 kimi 都从零开始。昨天审批通过的计划、修到一半的 Bug，全部丢失。 |
| 仅靠提示词自律 | Skill 只是 markdown 文件。AI 应该"自觉遵守"——但往往不遵守。 |
| 虚假完成 | Agent 说"测试通过了"，但实际上根本没运行。会话结束后才发现构建损坏。 |
| Token 黑盒消耗 | 不知道一次任务花了多少 Token，没有预算护栏，也无法优化。 |
| 没有质量门控 | 写代码的 Agent 同时审批代码。涉及安全的修改无人审查。 |
| 并行混乱 | Agent() 能生成工作者，但没有槽位管理、没有工作者间通信、没有统一监控。 |
OMK 解决了所有这些问题——不是靠更好的提示词，而是靠一个代码级工作流引擎，坐落在你和 Kimi 之间。
✨ OMK 为 Kimi CLI 带来了什么
| 维度 | 只用 Kimi CLI | Kimi CLI + OMK |
|------|--------------|-------------------|
| 开发流程 | 随意对话 | $deep-interview → $ralplan → $ralph 结构化流水线 |
| 状态持久化 | 退出即遗忘 | .omk/state/ 原子状态；$ralph "continue" 断点续传 |
| 约束执行 | "请遵循 Skill"（提示词层面） | 代码级 Gate 在 Kimi 启动前拦截非法激活 |
| 完成验证 | Agent 自行声明"完成" | 需要证据：测试输出、构建日志、Lint 结果、架构师签字 |
| Token 控制 | 黑盒消耗 | 按技能预算、复杂度路由、实时 HUD 追踪 |
| 质量保证 | 无审查机制 | 交叉验证网络：架构师→评论家、实现→审查员、认证→安全员 |
| 并行执行 | 原始 Agent() 调用 | 团队运行时：槽位限制、邮箱通信、心跳监控 |
| 可观测性 | 盲等输出 | 实时 HUD 仪表盘：工作流阶段、工作者状态、Token 消耗速率 |
| 长期记忆 | 无 | 通过 MemPalace 桥接实现 BM25 语义搜索 |
| 智能体角色 | 需手动配置 | 28 种预定义角色，各带 Token 预算、工具限制和步数限制 |
一句话总结： OMK 不替换 Kimi。它将 Kimi 从会写代码的聊天机器人升级为有流程、有证据、有监督的软件工程团队。
📦 安装
前置要求
- Node.js 20 或更高版本
- 已安装 Kimi Code CLI
安装 OMK
npm install -g oh-my-kimi-cli
omk setup🚀 快速开始
# 启动 Kimi CLI
kimi2. 自然语言（无需命令）
OMK 的智能自动编排器会自动检测您的意图：
kimi然后用自然语言描述您的需求即可：
# OMK 自动识别为需求收集，激活 $deep-interview
"我想构建一个支持 OAuth 和 MFA 的安全认证系统"
# OMK 识别为架构设计意图，激活 $ralplan
"设计认证系统的数据库架构和 API 端点"
# OMK 识别为实现意图，激活 $ralph
"实现已批准的认证系统，包含单元测试"
# 复杂任务自动触发团队模式
"构建一个全栈电商应用，React 前端和 Node.js 后端"3. 显式命令（当您确切知道需要什么时）
需要精确控制时，使用显式技能命令：
# 阶段 1：通过苏格拉底式提问澄清需求
$deep-interview "我想构建一个安全的认证系统"
# 阶段 2：设计架构并获得用户审批
$ralplan "起草认证系统的实现计划"
# 阶段 3：持久化执行直至完全验证
$ralph "实现已批准的计划"🛠️ 内置技能
| 命令 | 描述 | 最佳使用场景 |
| :--- | :--- | :--- |
| 🕵️♂️ $deep-interview | 苏格拉底式需求收集 | 需求不清晰或边界需要澄清时 |
| 📐 $ralplan | 架构规划与审批 | 编码前需要坚实、经过审查的计划时 |
| 🏃♂️ $ralph | 持久化循环执行直至完成 | 编写代码、测试并依据计划验证时 |
| 👥 $team | 并行多智能体执行 | 任务可拆分为独立子任务时 |
| 🛑 $cancel | 优雅中止工作流 | 需要停止当前智能体流程时 |
🏗️ 核心系统
1. 工作流编排
OMK 提供代码强制的开发流水线，引导 Kimi 经历与人类团队相同的阶段：
$deep-interview— 在编写任何代码前锁定目标、范围、约束和风险$ralplan— 生成架构 PRD，在用户明确批准前阻止执行$ralph— 迭代直至完成，在每个关卡要求机器可验证的证据
状态转换由 assertValidTransition() 验证。你不能从 "planning" 直接跳到 "complete" 而不经过验证。
2. Gate 与 Flag 验证
Skill 在 YAML frontmatter 中声明约束。OMK 在代码中强制执行，在 Kimi 收到提示词之前：
gates:
- type: prompt_specificity # 拦截模糊提示词
blocking: true
- type: has_active_plan # 无已批准 PRD 时拦截 $ralph
blocking: true
- type: no_shortcut_keywords # 警告 "just"、"simply"、"quickly"
blocking: falseFlag 如 --deliberate 或 --eco 根据清单验证。未知 Flag 会被拒绝并返回有帮助的错误信息。
3. 证据驱动验证
"任务在完成验证证明之前不算完成。"
$ralph 在标记完成前需要五类证据：
| 证据类型 | 示例 |
|----------|------|
| command_output | npm test 退出码 0 |
| file_artifact | 生成的源文件 |
| review_signature | 架构师子代理审批 |
| diff_record | 增删行数 |
| context_record | 决策依据 |
如果缺少所需证据，阶段转换会抛出 TransitionBlockedError。不再有"应该能跑"——证明它能跑。
4. Token 效率系统
按技能会话跟踪、预算和优化 Token 使用：
- 按技能预算：
deep-interview16K，ralph32K，autopilot128K - Flag 倍率：
--eco0.25×，--quick0.5×，--deliberate4× - 复杂度路由：低复杂度任务（审查、搜索）使用低成本配置；架构工作使用前沿模型
- 证据修剪器：压缩超过 5KB 的证据以回收 Token
- HUD 面板：实时进度条、剩余 Token、效率评分
5. 交叉验证网络
任何智能体不能批准自己的工作。
| 规则 | 触发条件 | 要求审查者 |
|------|----------|-----------|
| architect_output | 任何架构决策 | critic |
| implementation | 代码变更 | test-engineer 或 code-reviewer |
| security_touch | 文件路径匹配 /auth\|password\|token\|secret/ | security-reviewer |
| large_change | 增删行数 >100 | architect |
6. 团队运行时
用 $team N 启动 N 个并行 Kimi 工作者：
- Slot 管理器 — 遵守
~/.kimi/config.toml中的max_running_tasks - 邮箱 — 基于文件的 JSONL 工作者间通信
- KimiRuntime — 生成真实
kimi进程，带心跳检测和自动重启（最多 3 次） - 日志隔离 — 每个工作者写入
.omk/logs/team/latest/w{N}.log
7. 语义记忆与 HUD
- BM25 记忆桥接 — 与 MemPalace 集成，实现项目历史的排序语义搜索（未安装时优雅降级）
- 事件驱动 HUD —
omk hud打开实时终端仪表盘，使用fs.watch（100ms 防抖）。实时监控工作流阶段、团队工作者状态和 Token 消耗速率。
8. 智能体生态
28 种预定义智能体角色，各带校准的 Token 预算、推理力度和工具限制配置：
| 角色 | 预算 | 工具 | 用途 |
|------|------|------|------|
| architect | 128K | 全部 | 系统设计、长期权衡 |
| executor | 64K | 读/搜/编/写/执行 | 代码实现 |
| security-reviewer | 64K | 读/搜/执行 | 漏洞审计 |
| style-reviewer | 8K | 仅读 | 格式与命名规范 |
TOML 配置自动生成，带 # omk: 元数据注释，兼容原生 Kimi Agent。
⚙️ 工作原理
OMK 通过 Kimi 的原生钩子系统集成：
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ Kimi CLI │────▶│ OMK 钩子 │────▶│ 状态文件 │
│ │ │ 处理器 │ │ (.omk/) │
│ $ralph │ │ │ │ │
│ "..." │◀────│ 检测 $命令 │◀────│ skill- │
└─────────────┘ └──────┬──────┘ │ active.json │
│ └──────────────┘
▼
┌─────────────┐
│ Gate 验证 │
│ 通过？ │
└──────┬──────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ 拦截 │ │ SKILL.md │
│ 返回错误 │ │ 注入上下文│
└──────────┘ └────┬─────┘
│
▼
┌──────────┐
│ 交叉验证 │
│ 质量门控 │
└────┬─────┘
│
▼
┌──────────┐
│ 证据提交 │
│ MCP 工具 │
└──────────┘- 钩子拦截 — Kimi
UserPromptSubmit事件触发 OMK 处理器 - Gate 强制执行 — 代码验证 Flag、提示词特异性和工作流前置条件
- 状态跟踪 — 原子文件写入保证并发安全的状态持久化
- 技能注入 — 匹配的
SKILL.md清单加载到 Kimi 上下文 - 自主执行 — Kimi 遵循结构化工作流，通过 MCP 工具提交证据
- 交叉验证 — 关键输出在验收前由独立智能体角色审查
🔧 命令
CLI 命令
omk setup # 安装技能、配置钩子、注册 MCP 服务器
omk doctor # 健康检查 + 版本完整性 + 处理器 SHA-256 校验
omk update # 检查 npm registry 是否有新版本
omk uninstall # 安全移除钩子（备份 config.toml）和技能
omk hud # 实时终端仪表盘
omk explore "auth" # 尊重 .gitignore 的代码库搜索
omk team 3:executor "task" # 启动 3 个并行工作者
omk mcp state # 启动状态 MCP 服务器
omk mcp memory # 启动记忆 MCP 服务器工作流命令（在 Kimi CLI 中使用）
$deep-interview "..." # 澄清意图和边界
$ralplan "..." # 创建已批准的实现计划
$ralph "..." # 持久化执行直至完成
$team "..." # 并行多智能体执行
$cancel # 停止活动工作流📖 文档
🤝 参与贡献
我们欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。
运行本地测试套件：npm run test:all
👥 团队
| 角色 | 姓名 | GitHub | |------|------|--------| | 创建者和负责人 | SpiritPunch | @Goblin1024 |
🙏 致谢
本项目受到以下优秀作品的启发和构建：
- oh-my-codex by Yeachan Heo
- oh-my-claudecode (OMC) — 面向 Claude Code 的开创性多智能体编排层
工作流概念、状态管理模式和技能架构均改编自 oh-my-codex，并针对 Kimi Code CLI 重新设计。此外，本项目的架构和设计理念也深受 oh-my-claudecode (OMC) 的启发，感谢 OMC 项目在智能体工作流编排领域的开创性探索。
📄 许可证
MIT © SpiritPunch