第十章：实战案例、最佳实践与故障排除

把前面 9 章的概念串起来，最好的方式是看几段真实的工作流。本章用 6 个典型场景演示 OmO 的完整调用链，再总结一份最佳实践速查，最后给一份”卡住时怎么办”的故障排除手册。

10.1 实战案例

10.1.1 案例 1：小补丁——修个文档错字

场景：README.md 里一处英文错字。

做法：直接和 Sisyphus 对话即可。

README.md 第 12 行 "intall" 是错字，正确是 "install"

Sisyphus 不会 over-engineer，直接 read → edit。这种情况不要用 ulw，会浪费一堆并行任务。

10.1.2 案例 2：实现一个新接口（懒人模式）

场景：给 services/auth.ts 添加 sendOtp(phone) 方法，调用 Twilio Verify，带超时与重试，写单测。

做法：

ulw 在 services/auth.ts 添加 sendOtp(phone) 方法：
- 调用 Twilio Verify API 发送验证码；
- 5 秒超时，3 次重试；
- 用现有 logger；
- 写完整的单测覆盖正常 + 超时 + 重试用尽 + Twilio 4xx 用例。

OmO 内部发生了什么：

keyword-detector → ultrawork 模式
IntentGate → "实现 + 测试"
Sisyphus
  ├─ 后台 call_omo_agent(librarian) → 查 Twilio Verify 文档（Tier 1 内置 context7 MCP）
  ├─ 后台 call_omo_agent(explore) → grep services/ 现有 service 模式
  ├─ task(category="deep") → Junior 实现 sendOtp
  └─ task(category="unspecified-low") → Junior 写 vitest 测试
post:
  - lsp_diagnostics 通过
  - vitest 通过
  - comment-checker 删 4 处 AI 套话注释
  - todo-continuation-enforcer 检查 todo 全部 ✅
最终：交付 services/auth.ts + services/auth.test.ts

如果没特别折腾，整套流程自己就跑完。

10.1.3 案例 3：多日工程——重构 auth 系统

场景：把整个 auth 模块从 session-based 重构到 JWT + Refresh Token，估计 5+ 个文件 / 多日。

做法：

Day 1，规划阶段：

（Tab 切到 Prometheus）
我想把 auth 模块从 session-based 迁到 JWT + Refresh Token。要求：
- 渐进迁移，不破坏现有 session 用户；
- token 存 httpOnly cookie；
- refresh token 服务端可吊销。

Prometheus 启动访谈：

现有 session 表是哪个？
如何识别已迁用户 vs 未迁用户？
token 过期时长？refresh 多长？
黑名单（吊销）用 Redis 还是数据库？
灰度计划？
测试策略？
回滚方案？

访谈完成 → 自动调 Metis 缺口分析 →（如果你启用了高准确度）Momus 严审 → 计划落地：

.sisyphus/plans/jwt-migration.md

Day 1，执行阶段：

/start-work

/start-work 触发：

创建 .sisyphus/boulder.json；
切到 Atlas；
从 task 1 开始。

Atlas 派任务：

task(category="deep") → 实现 jwt utils
task(category="deep") → 实现 refresh-token store（Redis）
task(category="visual-engineering") → 修登录页面把 cookie 切到 httpOnly
task(category="unspecified-low") → 写迁移测试

中途机器崩了？没事——会话退出后再 /start-work，从 boulder.json 续作，notepad 里之前累积的”我们这个项目用了 zod 校验”等 wisdom 全在。

Day 3 一切搞定：

@oracle 评审一下整套 auth 实现，看有没有架构问题

Oracle（GPT-5.4 high）做只读评审，给改进建议。Sisyphus 接收建议 → 决定哪些改、哪些不改。

10.1.4 案例 4：UI 闭环——前端 + 浏览器验证

场景：给 dashboard 加一个新的图表卡片，要求设计感强。

做法：

ulw 在 src/pages/Dashboard 加一个"营收趋势"卡片：
- 用 Recharts；
- 颜色与现有主题协调；
- 移动端响应式；
- 加 hover 微交互；
- 完成后用浏览器截图截一张主页给我看。

OmO 内部：

Sisyphus → task({
  category: "visual-engineering",
  load_skills: ["frontend-ui-ux", "playwright"]
})
  ↓
Junior（Gemini 3.1 Pro high）
  ├─ frontend-ui-ux 注入设计指引
  ├─ 写 RevenueChart.tsx
  ├─ 跑 lsp_diagnostics
  ├─ playwright MCP 启动浏览器
  ├─ navigate http://localhost:3000/dashboard
  ├─ 截图
  ├─ skill_mcp(playwright) → 把截图回传
  └─ Skill MCP 销毁

你拿到代码 + 截图 + 一份”我做了什么”的总结。

10.1.5 案例 5：长链条循环——SaaS 化老应用

场景：把一个 45k 行的 Tauri 桌面应用改造成 SaaS Web 应用。这种活儿一句话 prompt 是不可能的。

做法：

/ulw-loop "把这个 Tauri 桌面应用迁移到 Next.js + Supabase 的 SaaS 形态：
- 复用 src/core 业务逻辑；
- 桌面文件操作改成 Supabase Storage；
- 用户管理用 Supabase Auth；
- 多租户隔离用 Postgres RLS。"
--max-iterations=200

Ralph + ultrawork 双 buff：

持续工作直到 <promise>DONE</promise>；
每个迭代自动续；
中途若 429 → runtime-fallback 切 Kimi K2.5 / GPT-5.4；
preemptive-compaction 提前压缩；
session-recovery / context-window-limit-recovery 修中断；
最大 200 次迭代上限。

通宵跑下来，你早上看到的应该是基本能跑的脚手架（具体效果取决于代码库复杂度）。

10.1.6 案例 6：Git 提交艺术家

场景：你刚 ulw 完了一个改了 17 个文件的功能，想提交。

做法：

/git-master commit these changes

git-master 内部：

分析最近 30 个 commit → 推断出你这个仓库用中文 + 语义化（feat/fix/docs）；
看到 17 个文件 → 必须 ≥5 次提交（参 6.4.1 法则）；
用 LSP / AST-Grep 分析改动依赖关系；
切成 5 个原子提交：
- feat(auth): 添加 JWT 工具函数
- feat(auth): 实现 RefreshToken 仓储
- feat(auth): cookie 切到 httpOnly
- test(auth): 补 JWT 迁移测试
- docs(auth): 更新 README
输出每个 commit 的 hash 和描述给你确认。

如果你想 rebase 到 main：

/git-master rebase onto main

它会自动按依赖顺序 rebase，遇到冲突时进行结构化解决。

10.2 最佳实践速查

10.2.1 模式选择

任务规模	推荐
改字 / 单文件单点	直接对话
几小时内能完成的功能	`ulw <task>`
多日工程 / 关键改动	`@plan` → `/start-work`
想要 GPT-5.4 深度推理	Tab → Hephaestus
不会停的大型重构	`/ulw-loop "..."`
设计审查	`@oracle`
找代码	`@explore`，能后台就后台
找文档	`@librarian`，能后台就后台

10.2.2 prompt 7 要素

每次给子 Agent 派任务（或在 ulw 写需求时）尽量包含：

TASK；2. EXPECTED；3. SKILLS；4. TOOLS；5. MUST DO；6. MUST NOT DO；7. CONTEXT。

10.2.3 模型选择

不要乱给 Hephaestus 配 Claude，不要给 Sisyphus 配老 GPT；
Explore / Librarian 不需要顶级模型；
ultrabrain 类别贵但值，硬骨头才用；
quick 类别真的便宜，能省就省。

10.2.4 多模型阵容建议

预算紧：Claude Pro + OpenCode Go（10$/月）+ Copilot 免费档；
追求质量：Claude Max + ChatGPT Plus + Gemini Pro + Z.ai；
国内偏好：Claude（API 任意中转）+ Kimi for Coding + Z.ai Coding Plan；
完全免费试水：只装 OpenCode Go 或 OpenCode Zen。

10.2.5 项目侧约定

项目根放 AGENTS.md，提一句”这个项目是干嘛的、风格是什么、必须遵守什么”——directory-agents-injector 自动注入；
.claude/rules/*.md 放语言级规则（命名风格、错误处理风格），globs 限定生效范围；
.opencode/skills/ 放仓库自定义 Skill，可与 git 一起版本管理；
.sisyphus/ 目录在 .gitignore 里加进去（除非你想让 plan / notepad 跟仓库一起走）。

10.2.6 安全最佳实践

不要把 API Key 直接写进 oh-my-openagent.json —— 用 ${VAR} 环境变量；
Skill MCP 的 OAuth token 已经按 chmod 0600 存好；
.claude/settings.local.json（git-ignored）放本地 Hook，避免提交命令式 Hook 给协作者带来意外效果；
如果团队里多人共用一份配置，把”个人偏好”放 ~/.config/opencode/oh-my-openagent.json，把”项目共识”放 .opencode/oh-my-openagent.json。

10.2.7 上下文窗口管理

启用 model_capabilities.auto_refresh_on_start，让 OmO 知道每个模型的窗口大小；
不要在主对话粘贴超长日志——丢到一个 tmp/run.log 文件，让 Agent 自己 read（会触发 tool-output-truncator）；
长会话开 preemptive-compaction；
compaction-context-injector 默认会把”重要上下文”在压缩时保留；
离开很久再回来 → /handoff 生成交接文档，新会话粘贴。

10.3 故障排除手册

10.3.1 安装阶段

Q：bunx oh-my-opencode install 报 “Cannot find module”？ A：先升级 Bun（curl -fsSL https://bun.com/install | bash），然后重开终端再装。

Q：装完没在 OpenCode 里看到 OmO 的痕迹？ A：检查 ~/.config/opencode/opencode.json：

jq '.plugin' ~/.config/opencode/opencode.json
# 应当看到 ["oh-my-openagent"] 或 ["oh-my-opencode"]

如果没有，手动加上。

Q：Using legacy package name "oh-my-opencode" 警告？ A：把 opencode.json 里 plugin 数组的 "oh-my-opencode" 换成 "oh-my-openagent"。

Q：OpenCode 启动失败，提示版本太低？ A：opencode --version 必须 ≥ 1.0.150，去 opencode.ai/docs 升级。

10.3.2 Auth & 模型解析

Q：bunx oh-my-opencode doctor 显示某个 Agent 落到了”compatibility fallback”？ A：跑：

bunx oh-my-opencode refresh-model-capabilities

刷新 models.dev 缓存。如果还是不行，说明你给该 Agent 配的模型在 models.dev 里没记录，OmO 用启发式回退——可以改成已知的模型 ID。

Q：Sisyphus 说”我不能在 GPT 上跑”？ A：no-sisyphus-gpt Hook 触发了。要么换成 Claude / Kimi / GLM，要么显式给 Sisyphus 加 ultrawork.model = openai/gpt-5.4（但效果一般）。

Q：Hephaestus 说”我不能在 Claude 上跑”？ A：no-hephaestus-non-gpt Hook 触发了。不要换提示词去硬试，老老实实给一个 GPT 提供商。

10.3.3 运行时错误

Q：突然 429 / rate_limit_exceeded？ A：runtime-fallback Hook 应该已经替你切了备胎，等几十分钟主模型冷却结束自动恢复。如果想加快可以手动改备胎链顺序。

Q：Context window exceeded？ A：anthropic-context-window-limit-recovery 应该自动压缩。如果没生效，开 preemptive-compaction 或者 /handoff 后开新会话。

Q：编辑工具老报 “hash mismatch”？ A：说明文件被外部改过，重新让 Agent read 一次再 edit。这不是 bug，是 Hashline 在保护你。

Q：Ollama 本地模型报 JSON Parse error: Unexpected EOF？ A：在 OpenCode 的 provider 配置里把 stream: false：

{
  "provider": "ollama",
  "model": "qwen3-coder",
  "stream": false
}

Ollama 默认走 NDJSON 流，Claude Code SDK 还没正确解析。详见 ollama 故障排除文档。

10.3.4 行为异常

Q：Agent 总爱写一堆 AI 风格的注释？ A：comment-checker 应当在 PostToolUse 提醒。如果你团队就是要写很多注释，把 comment-checker 加进 disabled_hooks。或者用 /skill ai-slop-remover 清理。

Q：Agent 老说”完成了”但 todo 还有半数没勾？ A：todo-continuation-enforcer 应该把它拽回来。如果没生效，检查是否被加进 disabled_hooks。

Q：Atlas 自己写了代码？ A：理论上不可能。如果发现确实写了，检查 claude_code.hooks 是否覆盖了 atlas Hook。

Q：Prometheus 写了代码而不是 Markdown？ A：prometheus-md-only 失效。检查是否被禁。

10.3.5 多 Agent 协同

Q：后台 Agent 跑完没通知？ A：background-notification 默认开。如果是 Linux 环境装 notify-send；macOS / Windows 自带通知。或者 background_output(task_id=...) 主动取。

Q：Tmux pane 没自动出现？ A：需要 OpenCode 运行在 tmux 会话内，并且 tmux.enabled = true。检查 echo $TMUX 是否非空。

Q：/start-work 提示 “no active plan”？ A：

.sisyphus/plans/ 是不是空？让 Prometheus 先建一个；
或者删 .sisyphus/boulder.json 让它重选最新计划。

10.3.6 Skill / Category

Q：Skill 不生效？ A：检查：

SKILL.md 路径是否对（参考第六章 6.5）；
disabled_skills 里是否屏蔽了；
Frontmatter 是否合法 YAML；
~/.config/opencode/skills/、.claude/skills/ 优先级冲突。

Q：Skill MCP 启动失败？ A：

看 ~/.config/opencode/mcp-oauth.json 是否有过期 token；
bunx oh-my-opencode mcp oauth login <name> 重新登录；
看 command / args 路径是否对。

Q：Category 不生效（Junior 还是用了默认 Sonnet）？ A：

检查你写的是 task({ category: "..." }) 而不是直接 subagent_type；
bunx oh-my-opencode doctor 看 Category 解析是否落到了 fallback。

10.3.7 性能与成本

Q：感觉烧钱很快？ A：

Explore / Librarian 不要配 Opus 这种顶级模型；
简单任务别用 ultrawork / ulw-loop；
看 Token 主要烧在哪里：session_search + session_info 工具可以看；
把 ulw 用作”最后选项”，先 @plan 把范围卡死。

Q：响应慢？ A：

Claude / Opus 大模型本身就慢，急性子可以让 Atlas 走 Sonnet；
关闭 thinking 预算（thinking: { type: "enabled", budgetTokens: 0 }）；
网络问题：把 Provider 切到镜像 / 中转。

10.4 OmO 学习路径建议

如果你刚装好 OmO，下面这条路径会比较顺：

第 1–2 天：跟着第三章把 OmO 装起来，跑一遍 ulw 给 README 加一段中文简介。
第 3–7 天：真实用 ulw 干日常活儿——修小 Bug、补单测、写新接口；同时翻翻第四、第五章，把 11 个 Agent 和三种工作模式心里有底。
第 2 周：碰到第一个”复杂多日活儿”，强制自己走 Prometheus → Atlas，一来体会计划-执行分离的好处，二来熟悉 boulder.json + notepad。
第 3 周：开始用 git-master 切提交、用 /refactor 做重构、用 review-work 自查；学会写 7 要素 prompt。
第 1 个月底：开始写自定义 Skill / Category / Rules / 命令，把 OmO 调成你的”定制开发助手”。
持续：关注 oh-my-openagent 的 dev 分支与 release，OmO 迭代极快，保持升级可获得新模型支持与新特性。

10.5 总结

读完整本教程，回头再看第一章那句话：

OmO 是装在 OpenCode 上的一支自动化的多模型 AI 工程团队。

它不是某种神奇的提示词，也不是某家供应商的预配置工具集。它是：

多模型编排——把每个模型用在它最强的地方；
专业化分工——Sisyphus / Hephaestus / Prometheus / Atlas / Oracle / Junior / Explore / Librarian / Multimodal-Looker / Metis / Momus，11 位选手各司其职；
强制纪律——52 个 Hook 把”AI 偷懒、瞎写、报错就崩”的脆弱性彻底压住；
稳健工具——Hashline + LSP + AST-Grep + Tmux 让 Agent 拥有 IDE 级精度；
三种主线——Ultrawork、Prometheus、Atlas，覆盖 95% 工作场景；
Discipline > Prompt Engineering——你不需要再调提示词，OmO 把”工程师纪律”直接焊死在系统里；
作者中立——和任何模型供应商无利益绑定，纯靠”哪家便宜哪家强用谁”。

把它装上，敲下第一个 ulw，剩下的，让 Agent 替你完成。

The agent should be invisible. You flip the switch. The light turns on.

那才是终点。

—— 完。