oh-my-deepseek (omd)

中文 | English

DeepSeek 多智能体编排层。 零依赖框架，将 DeepSeek API 转化为多智能体编程系统 — 自主执行、并行团队模式、交互式聊天和 MCP 集成。

v0.3.0 新特性

提示词缓存优化 — 系统提示词现已固定并通过 DeepSeek 的前缀缓存机制缓存。只有用户输入会变化，多轮会话最高可节省约 50% 的 token。无需配置，默认开启。详见提示词缓存。

快速开始

# 全局安装
npm install -g oh-my-deepseek

# 设置 API 密钥
export OMD_API_KEY=sk-your-key-here

# 运行自主模式
omd run "重构认证模块为 JWT"

# 或启动交互式聊天
omd chat

安装并设置 API 密钥后，运行 omd setup 启动交互式向导选择使用模式：

| 模式 | 使用场景 | 功能说明 | |------|---------|---------| | 1 独立模式 | 直接终端使用，无需编码智能体 | 配置 API 密钥 → 验证连通性 → 即可使用 omd run / omd chat | | 2 在智能体内运行 OMD | 想要智能体本身使用 DeepSeek | 自动切换智能体的 API 提供商为 DeepSeek + 注册 OMD 为 MCP | | 3 仅 MCP 模式 | 已有编码智能体，只需添加 OMD 工具 | 注册 OMD 为 MCP 服务器；不修改智能体原有的 API 提供商 | | 4 手动配置 | 需要完全控制或使用非检测 MCP 客户端 | 显示各客户端的 JSON 配置模板 |

快速选择：仅终端 → 选 1。想在 Claude Code/Codex 上使用 DeepSeek + OMD → 选 2。对当前提供商满意，仅添加 OMD → 选 3。

提示词缓存

oh-my-deepseek v0.3.0 引入了 DeepSeek 提示词缓存 — 一种自动优化机制，在多次 API 调用间复用系统提示词的 KV 缓存。

工作原理

DeepSeek 的 API 会缓存消息数组的前缀部分。如果后续请求共享相同的前缀，缓存的运算结果会被复用 — 节省 token 并降低延迟。

请求 1: [系统提示词 (缓存未命中)] → [用户任务] → [助手回复] → [工具结果]
                                                                              ↓
请求 2: [系统提示词 (缓存命中  )] → [新用户任务] → [助手回复] → [工具结果]

改动内容

| 优化项 | 影响 | |--------|------| | 系统消息合并 | 邮箱上下文合并到系统提示词中 → 每个智能体只有一条固定的系统消息 | | cache_control 标记 | 首条系统消息标记为 {type: "ephemeral"} → 提示 DeepSeek 优先缓存 | | 缓存感知压缩 | compactMessages() 保持系统消息不变；仅压缩旧的工具结果 | | 缓存统计 | 每次 API 返回 prompt_cache_hit_tokens / prompt_cache_miss_tokens | | 会话追踪 | 缓存命中率保存到 .omd/state.yml 并记录到 .omd/logs/ |

消息布局（缓存友好）

[0] system → agentPrompt + mailboxContext (固定 — 缓存命中)
[1..N-1] 对话历史
[N] user → task (变化 — 不缓存)

输出示例

缓存统计会以 cache_info 事件形式在执行管道中显示：

⚡ cache — hit: 1,240 tokens | miss: 850 tokens | rate: 59.3%

配置

缓存默认启用。如需禁用：

export OMD_CACHE_ENABLED=false

上手指南

1. 安装

npm install -g oh-my-deepseek

输出：

added 1 package in 2s

验证版本：

omd --version

输出：

omd v0.3.0

2. 设置 API 密钥

export OMD_API_KEY=sk-your-key-here

建议将此行添加到 ~/.bashrc 或 ~/.zshrc 中，避免每次重复输入。

3. 初始化项目结构

omd setup

交互式向导会检测你的环境（已安装的编码智能体、API 密钥、MCP 状态）并引导你完成设置。

4. 环境检查

omd doctor

输出：

  ✓ Node.js v22.x.x
  ✓ API key — sk-abcd1234...
  ✓ .omd/ directory
  ✓ Config loaded — model: deepseek-chat
  ✓ DeepSeek API — connected

所有检查必须通过 ✓ 才能继续。

5. 快速测试

omd run "Reply with: OMD-OK"

如果看到 ▶ Mode: autopilot 和各阶段日志，系统运行正常。

四种模式

Autopilot — omd run "任务"

适用：开发新功能、添加模块、日常编码。

管道：

explore → [gate] → plan → [gate] → execute → [gate] → review → [gate] → fix loop (max 3)

Ralph — omd run '$ralph "任务"'

适用：Bug 修复、疑难排查、需要反复验证的复杂任务。

管道：

explore → plan → execute → review → fix (最多 20 次迭代)
↓ REJECTED 时 ↓
re-explore → re-plan → execute → review → fix (最多 5 个全新周期)

Team — omd team <N> "任务"

适用：大型重构、模块拆分、并行子任务。

管道：

architect 拆分任务 → [gate] → N 个并行 executor → [gate] → reviewer 合并

Chat — omd chat

适用：探索代码、提问、讨论需求。

流程：

输入 → 意图分类 → 路由到对应智能体

模式对比

| 模式 | 命令 | 最大修复次数 | 拒绝后重新探索 | 并行 | 最佳场景 | |------|------|-------------|--------------|------|---------| | Autopilot | omd run "..." | 3 | ❌ | ❌ | 日常编码、新功能 | | Ralph | omd run '\$ralph "..."' | 20 + 5 个周期 | ✅ | ❌ | Bug 修复、疑难问题 | | Team | omd team <N> "..." | 1 轮 | ❌ | ✅ N 个 Worker | 大型重构、模块拆分 | | Chat | omd chat | 单轮 | — | — | 探索、问答、讨论 |

架构

项目结构

oh-my-deepseek/
├── agents/              # 智能体提示模板（可编辑 Markdown）
├── src/
│   ├── index.js         # CLI 入口
│   ├── agent.js         # 智能体系统（缓存优化）
│   ├── client.js        # DeepSeek API 客户端（支持提示词缓存）
│   ├── config.js        # 配置管理
│   ├── mailbox.js       # 智能体间消息传递
│   ├── mcp.js           # MCP 服务器
│   ├── orchestrator.js  # 编排引擎
│   ├── state.js         # 会话持久化
│   └── tools/           # 工具集
└── test/
    └── mcp-test.js      # MCP 协议测试

配置

优先级：环境变量 > 项目 .omd/config.json > 用户 ~/.omd/config.json > 默认值

export OMD_API_KEY=sk-...              # API 密钥（后备：DEEPSEEK_API_KEY）
export OMD_MODEL=deepseek-chat         # 默认模型
export OMD_REASONER_MODEL=deepseek-reasoner  # 推理模型
export OMD_BASE_URL=https://api.deepseek.com
export OMD_MAX_TOKENS=8192
export OMD_TEMPERATURE=0.7
export OMD_DEFAULT_MODE=autopilot
export OMD_CACHE_ENABLED=true          # 提示词缓存（默认开启）

MCP 集成

OMD 作为标准 MCP 服务器运行，兼容 Claude Code、Codex CLI、Cursor 等。

omd mcp  # 启动 MCP 服务器

暴露的工具：omd_autopilot、omd_team、omd_chat、omd_explore、omd_sessions、omd_decisions、omd_memory。

许可证

MIT