常见问题

提供三种安装方式，推荐第一种：

# 方式1: 源码安装（推荐）
git clone https://github.com/VOBC/oh-my-coder.git
cd oh-my-coder
pip install -e '.[dev]'

# 方式2: 使用 requirements.txt
pip install -r requirements.txt

# 方式3: Docker
docker compose up -d

三种配置方式，按优先级从高到低：

方式1：环境变量（高优先级）

# DeepSeek（代码能力强）
export DEEPSEEK_API_KEY=sk_xxxxxxxx

# 智谱 GLM（完全免费，推荐入门）
export ZHIPUAI_API_KEY=xxxxxxxx

# Kimi（128K 长上下文）
export MOONSHOT_API_KEY=sk_xxxxxxxx

方式2：CLI 配置命令

# 设置 DeepSeek Key
omc config set -k DEEPSEEK_API_KEY -v "sk_xxxxxxxx"

# 设置智谱 GLM Key
omc config set -k ZHIPUAI_API_KEY -v "xxxxxxxx"

# 设置默认模型
omc config set --default-model glm-4-flash

# 查看当前配置
omc status

方式3：直接编辑配置文件（~/.omc/config.json）

{
  "defaults": {
    "model": "glm-4-flash"
  },
  "models": {
    "deepseek": {
      "api_key": "sk_xxxxxxxx"
    },
    "glm": {
      "api_key": "xxxxxxxx"
    }
  }
}

⚠️ 常见陷阱：

• 如果配置了智谱 Key 但 CLI 仍然报 DeepSeek 错误 → 检查默认模型是否设为智谱：omc config set --default-model glm-4-flash
• 环境变量名注意大小写：DeepSeek 用 DEEPSEEK_API_KEY，智谱用 ZHIPUAI_API_KEY
• 环境变量设置后要重新打开终端才生效

获取 API Key：

• DeepSeek - 推荐首选，代码能力强
• 智谱 GLM - 完全免费
• Kimi - 128K 长上下文

# 验证 CLI
omc --version

# 查看可用命令
omc --help

如果提示 omc: command not found，见下一个问题。

原因：macOS 使用系统自带 Python 3.9 时，pip 安装的脚本不在默认 PATH 中。

解决：

1. 先找到 pip 安装路径：

   python3 -m site --user-base

2. 把 bin 目录加到 PATH：

   export PATH="$HOME/Library/Python/3.9/bin:$PATH"

3. 加到 ~/.zshrc 永久生效：

   echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

然后重新打开终端，输入 omc --version 验证。

推荐按以下流程开始：

1. 探索项目 - 了解代码库结构

   omc explore .

2. 查看可用 Agent

   omc agents

3. 执行简单任务测试

   omc run "为 utils.py 添加类型注解"

4. 查看系统状态

   omc status

特性	CLI	Web
适用场景	快速操作、脚本集成	可视化、调试、演示
实时反馈	文本流	SSE 动画
学习曲线	需熟悉命令	图形化友好

任务类型	推荐工作流	说明
新功能开发	build	完整流程
代码审查	review	质量+安全
Bug 修复	debug	定位→修复
测试生成	test	自动生成

优化建议：

1. 缩小任务范围

   # 不好的例子
   omc run "重构整个项目"
   
   # 好的例子
   omc run "重构 src/api 模块，使其符合 RESTful 规范"

2. 使用更快的模型

   export DEEPSEEK_MODEL=deepseek-chat  # 比 reasoner 更快

3. 分步执行

   omc explore .
   omc run "第一步：提取公共函数"
   omc run "第二步：添加单元测试"

模型对比：

特性	DeepSeek	GLM
费用	1元/百万tokens	免费
上下文	64K	200K
代码能力	⭐⭐⭐⭐⭐	⭐⭐⭐⭐

可以，系统会自动选择最优模型：

# 配置多个 Key
export DEEPSEEK_API_KEY=sk_xxx
export GLM_API_KEY=sk_yyy
export KIMI_API_KEY=sk_zzz

自动选择优先级：

1. 成本最低的可用模型
2. 响应速度最快的模型
3. 任务类型匹配的模型

立即执行：

1. 登录对应平台，撤销旧 Key
2. 生成新 Key
3. 更新本地配置
4. 检查异常调用记录

检查步骤：

# 1. 检查环境变量
echo $DEEPSEEK_API_KEY

# 2. 检查 .env 文件
cat .env

# 3. 验证配置
omc status

常见原因：

• Key 名称拼写错误（注意大小写）
• 未重启终端/IDE（环境变量需重新加载）
• .env 文件路径错误（应在项目根目录）

排查步骤：

1. 检查网络

   ping api.deepseek.com

2. 切换模型试试 — 如果正在用 DeepSeek，换成智谱 GLM（免费更快）：

   omc config set --default-model glm-4-flash

3. 检查 API Key 是否有效 — 在对应平台后台查看 Key 的状态

原因：CLI 的默认模型还是 DeepSeek，但 DeepSeek 的 API Key 没配。

解决：

# 1. 把默认模型设为智谱
omc config set --default-model glm-4-flash

# 2. 验证
omc status

或者把 DeepSeek Key 也配置上，让系统自动选择可用模型。

处理流程：

1. 使用 VerifierAgent 验证

   omc run "验证生成的代码" -w test

2. 请求修复

   omc run "修复以下代码的语法错误" --file generated.py

3. 使用安全审查

   omc run "审查代码质量" -w review

三步完成自定义 Agent：

# 1. 创建 Agent 类
# src/agents/my_agent.py
from src.agents.base import BaseAgent, AgentResult, AgentContext

class MyAgent(BaseAgent):
    name = "my_agent"
    description = "自定义 Agent"
    default_tier = "medium"

    async def execute(self, context: AgentContext) -> AgentResult:
        result = await self.generate(prompt)
        return AgentResult(
            agent=self.name,
            status="completed",
            result=result
        )

# 2. 注册到 __init__.py
from .my_agent import MyAgent

# 3. 使用
omc run "使用 my_agent 处理任务"

默认 omc run 会走完整工作流（6个步骤：探索→分析→规划→设计→执行→验证），适合复杂开发任务，但简单任务会很慢。

对于简单任务（创建文件、运行命令、查询信息等），加 --simple 或 -s 参数跳过工作流直接执行：

# 快速创建文件（不走工作流）
omc run --simple "帮我在桌面创建一个 hello.txt"
# 简写
omc run -s "帮我打印当前目录结构"
omc run -s "查看当前 Python 版本"

什么情况用 --simple，什么情况不用？

• ✅ 创建文件、改配置、查信息 → 用 --simple
• ✅ 运行一个 shell 命令 → 用 --simple
• ❌ 新功能开发、代码重构 → 不用 --simple，走完整工作流
• ❌ Bug 修复、代码审查 → 不用 --simple

GitHub Action 示例：

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      
      - name: Install OMC
        run: |
          pip install -e '.[dev]'
      
      - name: AI Review
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          omc run "审查本次 PR 的代码变更" -w review > review_report.md
      
      - uses: actions/upload-artifact@v4
        with:
          name: review-report
          path: review_report.md

from src.core.summary import generate_summary, save_summary

# 任务完成后生成报告
summary = generate_summary(
    task="任务描述",
    workflow="build",
    completed_steps=steps
)

# 导出多种格式
save_summary(summary, format="html")  # HTML 报告
save_summary(summary, format="json")  # JSON 数据
save_summary(summary, format="txt")   # 纯文本