Oh My OpenCode 使用文档Oh My OpenCode（简称 OMO）是 OpenCode 的超级插件/扩展

Oh My OpenCode 使用文档

1. 详细介绍

1.1 什么是 Oh My OpenCode？

Oh My OpenCode（简称 OMO）是 OpenCode 的超级插件/扩展层，受 oh-my-zsh 启发而设计。它的核心定位是：将单个 AI 代理升级为一个多智能体协作的开发团队。

┌─────────────────────────────────────────┐
│           Oh My OpenCode 架构            │
├─────────────────────────────────────────┤
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        用户指令 (ultrawork)      │   │
│  └────────────────┬────────────────┘   │
│                   ▼                     │
│  ┌─────────────────────────────────┐   │
│  │     Sisyphus (主编排器)          │   │
│  │  • 意图分类 • 任务委派 • 结果验证 │   │
│  └───────┬────────┬────────┬────────┘   │
│          │        │        │            │
│    ┌─────▼─┐ ┌────▼────┐ ┌─▼──────┐    │
│    │Hephae-│ │Promethe-│ │Atlas   │    │
│    │stus   │ │us       │ │(Todo)  │    │
│    │执行器 │ │规划师   │ │调度器  │    │
│    └────┬──┘ └────┬────┘ └─┬──────┘    │
│         │         │        │            │
│    ┌────▼─────────▼────────▼────┐      │
│    │     Subagents (子代理)      │      │
│    │ • Oracle • Librarian       │      │
│    │ • Explore • Metis • Momus  │      │
│    │ • Multimodal Looker        │      │
│    └────────────────────────────┘      │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │      Tools & MCPs (工具层)       │   │
│  │ • LSP • AST-Grep • Hashline     │   │
│  │ • websearch • context7 • grep_app│  │
│  └─────────────────────────────────┘   │
│                                         │
└─────────────────────────────────────────┘

1.2 核心哲学：Ultrawork Manifesto

Oh My OpenCode 基于以下核心设计原则：

原则	含义
🔧 人类干预是失败信号	如果需要不断纠正 AI，说明系统设计有问题
🎯 代码不可区分	AI 写的代码应与资深工程师写的代码无法区分
🧠 最小化认知负担	你只需说"做什么"，Agent 负责"怎么做"
🤖 可预测、可委托	Agent 应像编译器一样稳定可靠

1.3 核心特性

特性	说明
⚡ `ultrawork` / `ulw`	一键激活所有高级功能，多代理并行协作
🤖 多学科代理系统	11+ 专业 Agent，各司其职，协同工作
🔄 Category + Skills	智能任务分类 + 领域技能自动加载
🔗 Hash-Anchored Edits	基于内容哈希的代码编辑，零过时行错误
🛠️ LSP + AST-Grep	IDE 级代码理解，支持 25+ 语言的精准重写
🌐 内置 MCP 服务器	websearch/context7/grep_app 开箱即用
🔁 Ralph Loop / `/ulw-loop`	自循环执行，不完成不罢休
✅ Todo Enforcer	强制任务完成机制，防止中途放弃
💬 Comment Checker	自动审查注释质量，杜绝"AI 味"代码
🔌 Claude Code 完全兼容	现有 hooks/commands/skills/MCPs 无缝迁移

2. 安装指南

2.1 前置要求

✅ OpenCode 已安装并配置完成
✅ Node.js v18+ 或 Bun v1.0+
✅ Git 已初始化项目仓库
✅ 至少一个 LLM Provider 的 API Key（推荐：Claude / Kimi / GLM）

2.2 推荐安装方式：让 AI 帮你安装

# 在 OpenCode 对话中输入以下指令：
"Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md"

OpenCode 将自动读取安装指南并执行配置。

2.3 手动安装

🔹 方式 1: 使用 Bun（推荐）

# 安装 oh-my-opencode 插件
bunx oh-my-opencode install

# 或指定版本安装
bun install oh-my-opencode@3.11.2

🔹 方式 2: 使用 npm

# 企业代理环境需关闭 SSL 验证
npm config set strict-ssl false
npm install oh-my-opencode@2.14.0 --verbose

# 全局安装（可选）
npm install -g oh-my-opencode

🔹 方式 3: 离线安装

# 1. 在有网络的环境构建
git clone https://github.com/code-yeongyu/oh-my-opencode.git
cd oh-my-opencode
bun install
bun run build

# 2. 在目标机器配置插件路径
# 编辑 ~/.config/opencode/opencode.json
{
  "plugin": [
    "file:///absolute/path/to/oh-my-opencode/dist/index.js"
  ]
}

⚠️ Windows 用户注意：路径中的 \ 需替换为 /，例如 file:///E:/project/oh-my-opencode/dist/index.js

2.4 验证安装

# 启动 OpenCode
opencode

# 在对话中输入测试命令
/omoc-status

# 应看到插件加载成功提示
# 或尝试 ultrawork 关键词触发
ulw say hello

2.5 配置文件位置

配置类型	路径	说明
用户全局配置	`~/.config/opencode/oh-my-opencode.jsonc`	所有项目通用
项目配置	`./.opencode/oh-my-opencode.jsonc`	当前项目专用
OpenCode 主配置	`~/.config/opencode/opencode.json`	插件注册位置

💡 支持 .jsonc 格式，可写注释和尾随逗号，便于维护

3. 命令大全

3.1 内置命令（以 `/` 开头）

命令	功能	示例
`/init-deep`	深度初始化，生成层级 `AGENTS.md` 文件	`/init-deep`
`/start-work`	调用 Prometheus 进行战略规划	`/start-work 重构用户模块`
`/ulw-loop`	启动 Ralph Loop 自循环模式	`/ulw-loop 修复所有测试`
`/omoc-status`	显示插件状态和配置	`/omoc-status`
`/skills`	列出可用 Skills	`/skills`
`/agents`	列出可用 Agents 及状态	`/agents`
`/undo`	撤销上一次代码修改（继承自 OpenCode）	`/undo`
`/share`	生成会话分享链接	`/share`

3.2 快捷键与交互

快捷键	功能	说明
`Tab`	切换主 Agent	在 Sisyphus ↔ Hephaestus ↔ Atlas 间切换
`Ctrl+P`	打开命令面板	列出所有可用命令/commands/skills
`@agent`	调用子代理	`@oracle 这个架构有问题吗`
`@skill:name`	加载特定技能	`@skill:git-master 提交这次修改`
`↑/↓`	切换历史会话	在子会话/父会话间导航
`Ctrl+R`	重新执行最后命令	快速重试失败任务

3.3 特殊关键词触发器

关键词	触发效果	使用场景
`ultrawork` / `ulw`	激活 Ultrawork 全功能模式	复杂新功能开发、跨模块重构
`think deeply`	启用 Think Mode，强制长思维链	架构决策、疑难问题诊断
`search:`	触发深度搜索模式	查找代码模式、依赖关系
`analyze:`	触发深度分析模式	性能分析、安全审计

# 示例：一键激活全功能
ulw 实现用户登录功能，支持 JWT + 刷新令牌 + 速率限制

# 示例：深度思考模式
think deeply: 这个微服务架构有哪些潜在的单点故障？

3.4 自定义 Commands

在 .opencode/commands/ 创建 .md 文件：

---
name: deploy-staging
description: 部署到预发布环境
agent: sisyphus
skills: [git-master, playwright]
---

# 部署预发布环境

1. 运行类型检查
   !`npm run typecheck`

2. 运行完整测试套件
   !`npm test -- --coverage`

3. 构建生产版本
   !`npm run build`

4. 执行部署脚本（需确认）
   /ask "确认部署到 staging 环境？"
   !`./scripts/deploy-staging.sh`

5. 运行冒烟测试
   delegate_task(agent="explore", prompt="验证 /health 端点")

使用方式：在 OpenCode 中输入 /deploy-staging

3.5 配置示例

// ~/.config/opencode/oh-my-opencode.jsonc
{
  "$schema": "https://ohmyopenagent.com/schema.json",
  
  // 主 Agent 配置
  "agents": {
    "sisyphus": {
      "model": "kimi/kimi-k2.5",  // 推荐：性价比高
      "temperature": 0.1,
      "max_steps": 100
    },
    "hephaestus": {
      "model": "openai/gpt-5.3-codex",
      "temperature": 0.1
    }
  },
  
  // 后台任务并发控制
  "background": {
    "max_concurrent": 5,
    "provider_limits": {
      "anthropic": 3,
      "openai": 4,
      "google": 2
    }
  },
  
  // 权限控制
  "permissions": {
    "edit": "ask",  // 文件修改需确认
    "bash": {
      "allow": ["npm", "git", "docker"],
      "deny": ["rm -rf", "sudo"]
    }
  },
  
  // 禁用特定 Hooks（按需）
  "disabled_hooks": [
    "comment-checker",  // 如果不需要注释审查
    "todo-enforcer"     // 如果偏好手动管理任务
  ]
}

4. 核心功能

4.1 Agent 角色清单与协作拓扑

Agent	默认模型	温度	模式	核心职责
Sisyphus	claude-opus-4-6-8	0.1	primary	主编排器，意图分类、任务委派、结果验证
Hephaestus	gpt-5.3-codex	0.1	primary	自主深度执行器，端到端完成复杂任务
Prometheus	claude-opus-4-6-8	0.1	—	战略规划师，只输出计划不写代码
Atlas	claude-sonnet-4-6-8	0.1	primary	Todo 列表编排器，按波次并行调度
Oracle	gpt-5.2	0.1	subagent	只读高智商顾问，架构决策/疑难调试
Metis	claude-opus-4-6-8	0.3	subagent	规划前顾问，在 Prometheus 前做 gap 分析
Momus	gpt-5.2	0.1	subagent	计划审查员，验证计划可执行性
Librarian	glm-4.7	0.1	subagent	外部文档/代码搜索，查官方文档、搜 GitHub
Explore	grok-code-fast-1	0.1	subagent	内部代码库搜索，回答"X 在哪里"
Multimodal Looker	gemini-3-flash	0.1	subagent	多模态分析，处理 PDF/图片/图表
Sisyphus-Junior	claude-sonnet-4-6-8	0.1	all	分类任务执行器，不能再委派 task()

4.2 Category + Skills 系统

🔹 Category 分类（任务路由）

当 Sisyphus 委派任务时，不是指定模型，而是指定 Category：

Category	适用场景	默认路由模型
`visual-engineering`	前端、UI/UX、设计系统	Claude Sonnet / Gemini
`deep`	自主研究 + 端到端执行	GPT-5.3 Codex / Kimi K2.5
`quick`	单文件修改、拼写修复	GLM-4.7 / 本地模型
`ultrabrain`	复杂逻辑、架构决策	Claude Opus / GPT-4o
`business-logic`	业务规则、数据流	Claude Sonnet / Kimi

🔹 Skills 技能系统

Skills 是领域专用的能力包，每个 Skill 包含：

skill-name/
├── SKILL.md          # 技能定义（frontmatter + prompt）
├── mcp/              # 可选：技能专属 MCP 服务器
├── rules/            # 可选：领域规则文件
└── examples/         # 可选：示例代码

内置 Skills：

playwright / playwright-cli / agent-browser：浏览器自动化（三选一）
frontend-ui-ux：设计优先的 UI 开发规范
git-master：原子提交、rebase 手术、冲突解决
dev-browser：开发环境浏览器交互

自定义 Skill：

# 项目级：.opencode/skills/my-skill/SKILL.md
# 用户级：~/.config/opencode/skills/my-skill/SKILL.md

4.3 Hash-Anchored Edit Tool（哈希锚定编辑）

解决传统 Agent 编辑工具的"过时行"问题：

# 传统方式（易出错）：
# Agent 复制原始行 → 修改 → 搜索匹配 → 替换
# ❌ 文件变化后匹配失败，导致错误编辑

# Hashline 方式（安全）：
1#A3F| function calculateTotal(items) {
2#B7K|   return items.reduce((sum, item) => {
3#C9M|     return sum + item.price * item.quantity;
4#D2N|   }, 0);
5#E5P| }

# Agent 编辑时引用哈希：
edit(lines=["2#B7K", "3#C9M"], content=`...new code...`)

# 系统验证：如果文件哈希不匹配，拒绝编辑并重新读取
# ✅ 零过时行错误，编辑成功率 6.7% → 68.3%

4.4 内置 MCP 服务器

MCP	服务地址	用途	认证
websearch	`mcp.exa.ai` (默认) / `mcp.tavily.com`	通用网络搜索	API Key
context7	`mcp.context7.com`	官方库文档查询	可选 API Key
grep_app	`mcp.grep.app`	跨开源仓库代码搜索	无需认证

使用示例：

# 自动触发 websearch
"查找最新 React Server Components 最佳实践"

# 显式调用 context7
@librarian 查询 expressjs.com 的中间件文档

# 搜索开源实现
@grep_app 在 GitHub 搜索 JWT 刷新令牌的 TypeScript 实现

4.5 Ultrawork 模式详解

🔹 触发机制

当消息中包含 ultrawork 或 ulw 关键词时：

设置 message.variant = "max"（最高精度模式）
显示 Toast 通知："Ultrawork Mode Activated"
注入 200+ 行专用指令，包括：
- 要求 100% 确定性后再开始实现
- 强制并行使用背景任务
- 强制使用 Category + Skills 系统
- 强制完成验证（TDD 工作流）
- 禁止任何"我做不到"的借口

🔹 执行流程

用户: ulw 实现用户认证模块
          │
          ▼
┌─────────────────────┐
│ 1. 并行探索代码库    │
│ • delegate_task(Explore, "找现有 auth 模式")
│ • delegate_task(Librarian, "查 JWT 最佳实践")
│ • delegate_task(Oracle, "评估安全方案")
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ 2. Prometheus 规划  │
│ • 生成详细工作计划   │
│ • 输出 .sisyphus/plans/auth.md
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ 3. Atlas 调度执行   │
│ • 按波次并行执行任务 │
│ • 实时监控进度       │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ 4. 验证与交付       │
│ • 运行测试验证结果   │
│ • 生成完成报告       │
│ • 确认 100% 完成    │
└─────────────────────┘

🔹 使用建议

场景	是否使用 `ulw`	原因
复杂新功能开发	✅ 推荐	需要多代理协作、并行探索
紧急故障修复	✅ 推荐	需要快速诊断 + 深度探索
单文件小修改	❌ 不推荐	过度消耗资源，响应变慢
快速想法验证	❌ 不推荐	正常模式更高效

💡 经验法则：任务涉及多个模块/系统 → 用 ulw；单文件小改动 → 不用

5. 项目使用教程

5.1 快速开始

# 1. 进入项目目录
cd /path/to/your/project

# 2. 确保已安装 OpenCode + Oh My OpenCode
opencode --version  # 应显示插件已加载

# 3. 启动会话
opencode

# 4. 深度初始化（首次使用推荐）
# 生成层级 AGENTS.md 帮助 AI 理解项目
> /init-deep

# 5. 开始工作
> ulw 添加用户头像上传功能

5.2 典型工作流

🎯 场景 1：从零开发新功能

# 步骤 1: 战略规划（Prometheus）
> /start-work 实现社交分享功能
[Prometheus 输出计划文件: .sisyphus/plans/social-share.md]

# 步骤 2: 并行探索
> ulw 基于计划开始实现
[后台自动执行:]
- @explore 查找现有分享组件
- @librarian 查询各平台分享 API
- @oracle 评估隐私合规方案

# 步骤 3: 分工执行
[Atlas 调度:]
- Hephaestus: 实现核心分享逻辑
- Sisyphus-Junior: 编写单元测试
- Multimodal Looker: 分析设计稿

# 步骤 4: 验证交付
[完成后自动:]
- 运行测试套件
- 生成使用文档
- 创建 Git 提交建议

🎯 场景 2：重构遗留代码

# 步骤 1: 深度分析
> analyze: 评估 /src/legacy 模块的技术债务

# 步骤 2: 制定重构计划
> @prometheus 为上述模块制定渐进式重构方案

# 步骤 3: 执行重构（ulw 模式）
> ulw 按计划重构用户认证模块
[关键特性:]
- 保持向后兼容
- 每步都有测试覆盖
- 自动回滚机制

# 步骤 4: 验证与文档
[自动完成:]
- 对比重构前后性能
- 更新架构文档
- 生成迁移指南

🎯 场景 3：排查复杂 Bug

# 步骤 1: 诊断
> @oracle 分析这个内存泄漏问题: [粘贴错误日志]

# 步骤 2: 定位
> @explore 查找所有使用 WebSocket 的地方

# 步骤 3: 修复
> ulw 修复 WebSocket 连接未关闭的问题
[自动执行:]
- 添加连接池管理
- 实现优雅断开
- 编写压力测试

# 步骤 4: 预防
> /skills 添加 websocket-best-practice 技能到项目

5.3 高级技巧

🔍 精准上下文管理

# 使用 @ 引用文件（内容自动注入）
> 优化 @src/auth/jwt.ts 的令牌刷新逻辑

# 使用 @agent 调用专家
> @oracle 这个微服务拆分方案合理吗？

# 使用 @skill 加载领域知识
> @skill:frontend-ui-ux 实现这个 Figma 设计

# 组合使用
> @oracle @skill:git-master 审查这次重构的提交历史

🔄 会话与状态管理

# 查看当前会话状态
> /omoc-status

# 列出所有可用 agents
> /agents

# 列出所有可用 skills
> /skills

# 分享会话给团队成员
> /share  # 生成可分享链接

# 清理上下文（节省 Token）
> /clear  # 保留项目状态，清空对话历史

⚙️ 自定义工作流

# 创建项目专用命令
mkdir -p .opencode/commands
cat > .opencode/commands/release.md << 'EOF'
---
name: release
description: 执行预发布检查并生成 Release
agent: sisyphus
skills: [git-master, playwright]
---

# Release 工作流

1. 代码质量检查
   !`npm run lint`
   !`npm run typecheck`

2. 测试验证
   !`npm test -- --coverage`
   delegate_task(agent="explore", prompt="验证关键路径")

3. 版本管理
   /ask "确认版本号为 $VERSION ?"
   !`npm version $VERSION`

4. 生成 Changelog
   @librarian 基于提交历史生成变更日志

5. 创建 Git Tag 并推送
   !`git push --follow-tags`
EOF

# 使用：/release

5.4 配置最佳实践

// .opencode/oh-my-opencode.jsonc - 生产环境推荐
{
  "agents": {
    "sisyphus": {
      // 主编排器：平衡成本与能力
      "model": "kimi/kimi-k2.5",
      "temperature": 0.1,
      "max_steps": 150
    },
    "hephaestus": {
      // 深度执行：用最强模型
      "model": "openai/gpt-5.3-codex",
      "temperature": 0.05
    },
    "oracle": {
      // 顾问角色：高智商+低温度
      "model": "anthropic/claude-opus-4-6-8",
      "temperature": 0.0
    }
  },
  
  "background": {
    // 根据 API 配额调整并发
    "max_concurrent": 4,
    "provider_limits": {
      "anthropic": 2,
      "openai": 3,
      "google": 2,
      "kimi": 5  // Kimi 配额通常更宽松
    }
  },
  
  "permissions": {
    // 生产环境：敏感操作需确认
    "edit": "ask",
    "bash": {
      "allow": ["npm", "pnpm", "git", "docker"],
      "deny": ["rm -rf /", "sudo", "curl | bash", "eval"]
    },
    "webfetch": "ask"  // 外部请求需确认
  },
  
  "features": {
    // 按需启用高级功能
    "hashline_edit": true,      // ✅ 强烈推荐
    "comment_checker": true,    // ✅ 保证代码质量
    "todo_enforcer": true,      // ✅ 防止任务中断
    "ultrawork_auto": false     // ⚠️ 手动触发更可控
  }
}

6. 与 Codex / Claude Code 对比

6.1 核心差异总览

维度	Oh My OpenCode	OpenAI Codex	Claude Code
开源状态	✅ 源码可见 (SUL)	❌ 闭源 API	❌ 闭源 CLI
模型绑定	🔓 任意 Provider + 本地模型	🔒 仅 OpenAI	🔒 仅 Claude
Agent 架构	🤖 11+ 专业 Agent 协作	👤 单 Agent	👤 单 Agent + 规划
多模型编排	✅ Category 自动路由	❌ 固定模型	❌ 固定模型
终端体验	⭐ 专为 TUI 优化	❌ 无终端界面	✅ 良好终端支持
编辑可靠性	🔗 Hash-Anchored Edits	⚠️ 传统匹配	⚠️ 传统匹配
技能系统	✅ Skills + MCP 集成	⚠️ 有限 Skills	✅ Claude Skills
成本	💰 免费插件 + 自选 API	💸 按 Token 计费	💸 按 Token + 订阅
企业适配	🔐 权限控制 + 审计日志	⚠️ 基础控制	⚠️ 基础控制

6.2 详细对比分析

🔹 Oh My OpenCode 优势

真正的多代理协作 # 传统单 Agent: [User] → [Claude] → [Code]

# OMO 多 Agent:
[User] → [Sisyphus] 
              ├── [Prometheus: 规划]
              ├── [Oracle: 架构审查]
              ├── [Hephaestus: 执行]
              ├── [Librarian: 文档查询]
              └── [Explore: 代码搜索]
              ↓
         [验证通过] → [Code + Tests + Docs]

模型无关的智能路由

// 配置一次，自动选择最优模型
{
  "categories": {
    "visual-engineering": ["claude-sonnet", "gemini-pro"],
    "deep": ["gpt-5.3-codex", "kimi-k2.5"],
    "quick": ["glm-4.7", "ollama/qwen2.5"]
  }
}
// Agent 说"做什么"，系统选"用什么模型做"

编辑可靠性革命
- Hash-Anchored Edits 将编辑成功率从 6.7% 提升至 68.3%
- 零"过时行"错误，避免代码损坏
企业级可控性
- 精细权限系统（文件/命令粒度）
- 完整操作审计日志
- 支持私有模型 + 内网隔离部署

🔹 Codex 现状

已整合: Codex 技术已融入 GitHub Copilot，不再作为独立产品
适用场景: GitHub 生态深度集成项目
局限: 无法脱离 OpenAI 生态，定制性弱，单 Agent 架构

🔹 Claude Code 优势

模型能力: Claude 3.5/4 Opus 当前代码理解能力业界领先
开箱即用: 安装简单，默认配置即可高效工作
规划能力: 内置 Chain-of-Thought，复杂任务规划可靠

🔹 Claude Code 局限

厂商锁定: 必须使用 Anthropic 模型，无法切换
成本较高: 高级模型 Token 价格显著高于开源方案
隐私顾虑: 代码需发送至 Anthropic 服务器
单 Agent 瓶颈: 复杂任务易陷入"思考 - 执行"循环

6.3 选型建议

✅ 选择 Oh My OpenCode 如果：
   • 需要多代理协作处理复杂项目
   • 注重代码隐私/数据主权
   • 希望灵活切换模型控制成本
   • 偏好终端工作流/可定制性
   • 企业环境需要审计/权限控制
   • 已有 OpenCode 使用经验

✅ 选择 Claude Code 如果：
   • 追求最强单模型代码能力
   • 快速启动，不愿配置复杂环境
   • 项目不涉密，可接受云端处理
   • 预算充足，重视开发效率
   • 深度使用 Claude Skills 生态

✅ 选择 GitHub Copilot (Codex) 如果：
   • 深度使用 GitHub 生态
   • 需要 IDE 内无缝集成
   • 团队已采购 GitHub Enterprise
   • 偏好"无感"补全体验

6.4 混合使用策略（推荐）

// 按任务类型分配模型，平衡成本与能力
{
  "agents": {
    "sisyphus": {
      // 主编排：用性价比模型
      "model": "kimi/kimi-k2.5",
      "fallback": ["glm/glm-4.7", "ollama/qwen2.5-coder"]
    },
    "hephaestus": {
      // 深度执行：关键任务用最强模型
      "model": "anthropic/claude-opus-4-6-8",
      "fallback": ["openai/gpt-5.3-codex"]
    },
    "explore": {
      // 快速搜索：用廉价/本地模型
      "model": "ollama/qwen2.5-coder:7b",
      "max_tokens": 2048
    }
  },
  
  "ultrawork": {
    // Ultrawork 模式专属配置
    "force_model_override": true,  // 自动切换到更强模型
    "parallel_limit": 6,           // 最大并行 Agent 数
    "verification_required": true  // 强制完成验证
  }
}

7. 最佳实践与技巧

7.1 提示词工程

✅ 优秀的 Ultrawork Prompt:
"ulw 实现用户头像上传功能
要求：
- 支持 JPG/PNG/WebP，最大 10MB
- 上传后生成 3 种尺寸缩略图
- 存储到 S3，CDN 分发
- 添加上传进度回调
- 编写完整单元测试
参考：@src/components/ImageUploader.tsx 的实现风格"

❌ 模糊的 Prompt:
"加个头像上传"

7.2 上下文管理技巧

技巧	方法	效果
精准引用	用 `@文件` 代替"这个文件"	避免歧义，节省 Token
分层 AGENTS.md	`/init-deep` 生成层级文档	Agent 自动读取相关上下文
分步任务	复杂需求拆为规划→确认→执行	提高成功率，便于回滚
及时清理	长对话用 `/clear`	避免上下文膨胀导致遗忘

7.3 安全实践

// 生产环境权限配置
{
  "permissions": {
    "edit": "ask",           // 所有文件修改需人工确认
    "bash": {
      "allow": ["npm", "git", "pnpm", "docker"],
      "deny": ["rm -rf", "sudo", "curl | bash", "eval", "chmod 777"]
    },
    "webfetch": "deny",      // 禁止外部请求（防数据泄露）
    "mcp": {
      "websearch": "ask",    // 网络搜索需确认
      "context7": "allow",   // 官方文档可自动查询
      "grep_app": "allow"    // 开源代码搜索可自动
    }
  },
  
  "audit": {
    "log_all_edits": true,   // 记录所有代码修改
    "log_all_commands": true, // 记录所有命令执行
    "retention_days": 90     // 日志保留 90 天
  }
}

7.4 性能优化

优化项	方法	预期效果
减少 Token	用 `@file` 引用代替粘贴代码	节省 70%+ 上下文
本地模型	简单任务用 Ollama + Qwen-Coder	零 API 成本
缓存策略	重复查询启用 `cache: true`	加速 3-5 倍
并行子任务	Ultrawork 模式自动并行	缩短 40-60% 等待
模型降级	配置 fallback 链避免超时	提升稳定性

7.5 团队协作规范

# 1. 共享配置
git add .opencode/oh-my-opencode.jsonc
git add .opencode/commands/
git add .opencode/skills/

# 2. 统一 Agent 规范
# 在 .sisyphus/AGENTS.md 中定义：
# - 代码风格要求
# - 提交信息格式
# - 测试覆盖率标准

# 3. 团队专用 Commands
# .opencode/commands/team/
# - /lint-all: 全项目代码检查
# - /test-critical: 运行核心测试
# - /deploy-staging: 预发布部署

# 4. 会话分享
> /share  # 生成链接发给同事审查
# 链接包含：对话历史 + 代码变更 + 验证结果

8. 常见问题

8.1 Oh My OpenCode 需要付费吗？

插件本身: 完全免费开源（源码可见）
模型成本:
- 本地模型 (Ollama): 免费，仅需硬件
- 云端 API: 按提供商计费（可自选廉价模型如 GLM/Kimi）
- 推荐组合：主任务用 Kimi ($10/月)，深度任务用 Claude 按量

8.2 支持中文吗？

✅ 完全支持。推荐模型配置：

{
  "agents": {
    "sisyphus": { "model": "qwen/qwen2.5-coder-32b" },  // 通义千问
    "hephaestus": { "model": "kimi/kimi-k2.5" },        // 月之暗面
    "explore": { "model": "ollama/qwen2.5-coder:7b" }   // 本地
  }
}

8.3 如何保证 AI 不写 Bug？

Hash-Anchored Edits: 编辑前验证内容哈希，防止错误修改
权限控制: 敏感操作设为 ask 需人工确认
可撤销: 所有修改支持 /undo 回退
测试先行: Ultrawork 模式强制要求先写测试
多代理审查: Oracle/Momus 自动审查架构和计划
CI 集成: 配合 GitHub Actions 自动验证

8.4 能离线使用吗？

✅ 可以，需配置本地模型：

# 1. 安装并启动 Ollama
ollama pull qwen2.5-coder:7b
ollama serve

# 2. 配置 Oh My OpenCode
{
  "agents": {
    "explore": {
      "model": "ollama/qwen2.5-coder:7b",
      "api_base": "http://localhost:11434"
    }
  },
  "features": {
    "hashline_edit": true,  // 离线也可用
    "websearch": false      // 禁用需联网的 MCP
  }
}

8.5 与 Cursor / Windsurf 区别？

工具	核心定位	开源	多代理	终端支持
Oh My OpenCode	OpenCode 插件/扩展层	✅	✅ 11+ Agents	⭐ 原生优化
Cursor	AI 优先的编辑器	❌	❌ 单 Agent	❌
Windsurf	IDE 插件	❌	❌ 单 Agent	❌
Claude Code	官方 CLI Agent	❌	⚠️ 规划+执行	✅

Oh My OpenCode 更适合：终端重度用户、远程开发、复杂项目协作、企业定制场景

8.6 Ultrawork 模式为什么有时不触发？

常见原因及解决方案：

问题	检查项	解决方案
关键词未识别	是否在代码块中写了 `ulw`	关键词需在普通文本中，不在 ``` 代码块内
背景会话	是否在子 Agent 会话中触发	Ultrawork 仅在主会话生效
配置禁用	`disabled_hooks` 是否包含 `keyword-detector`	从禁用列表中移除
Provider 不可用	配置的模型是否有效	检查 API Key 和网络连接

8.7 如何升级到最新版本？

# Bun 用户
bunx oh-my-opencode upgrade

# npm 用户
npm update oh-my-opencode

# 或手动指定版本
bun install oh-my-opencode@latest

# 验证版本
> /omoc-status  # 应显示新版本号

9. 实战截图

9.1 链接地址

github.com/tanghong199…

Oh My OpenCode 使用文档

Oh My OpenCode 使用文档

目录

1. 详细介绍

1.1 什么是 Oh My OpenCode？

1.2 核心哲学：Ultrawork Manifesto

1.3 核心特性

2. 安装指南

2.1 前置要求

2.2 推荐安装方式：让 AI 帮你安装

2.3 手动安装

🔹 方式 1: 使用 Bun（推荐）

🔹 方式 2: 使用 npm

🔹 方式 3: 离线安装

2.4 验证安装

2.5 配置文件位置

3. 命令大全

3.1 内置命令（以 / 开头）

3.2 快捷键与交互

3.3 特殊关键词触发器

3.4 自定义 Commands

3.5 配置示例

4. 核心功能

4.1 Agent 角色清单与协作拓扑

4.2 Category + Skills 系统

🔹 Category 分类（任务路由）

🔹 Skills 技能系统

4.3 Hash-Anchored Edit Tool（哈希锚定编辑）

4.4 内置 MCP 服务器

4.5 Ultrawork 模式详解

🔹 触发机制

🔹 执行流程

🔹 使用建议

5. 项目使用教程

5.1 快速开始

5.2 典型工作流

🎯 场景 1：从零开发新功能

🎯 场景 2：重构遗留代码

🎯 场景 3：排查复杂 Bug

5.3 高级技巧

🔍 精准上下文管理

🔄 会话与状态管理

⚙️ 自定义工作流

5.4 配置最佳实践

6. 与 Codex / Claude Code 对比

6.1 核心差异总览

6.2 详细对比分析

🔹 Oh My OpenCode 优势

🔹 Codex 现状

🔹 Claude Code 优势

🔹 Claude Code 局限

6.3 选型建议

6.4 混合使用策略（推荐）

7. 最佳实践与技巧

7.1 提示词工程

7.2 上下文管理技巧

7.3 安全实践

7.4 性能优化

7.5 团队协作规范

8. 常见问题

8.1 Oh My OpenCode 需要付费吗？

8.2 支持中文吗？

8.3 如何保证 AI 不写 Bug？

8.4 能离线使用吗？

8.5 与 Cursor / Windsurf 区别？

8.6 Ultrawork 模式为什么有时不触发？

8.7 如何升级到最新版本？

9. 实战截图

9.1 链接地址

9.2 截图

3.1 内置命令（以 `/` 开头）