❧ OpenCode 全栈开发指南

在 2026 年的 AI 辅助编程领域，“The Open Stack” 已成为最受开发者欢迎的开源解决方案。本教程将详细介绍如何搭建和使用这套强大的工具链：

1. OpenCode (底层引擎)：一个开源、隐私优先的 AI 编程终端/IDE。
2. Oh My OpenCode (增强框架)：类似 “Oh My Zsh” 的配置管理框架，提供 Agent 编排（Sisyphus）、技能系统和自动化工作流。
3. OpenSpec (规格驱动开发)：一个轻量级的 AI 编码规格框架，确保在写代码前先与 AI 对齐需求 (SDD)。

---

一、 OpenCode：核心引擎

OpenCode (anomalyco/opencode) 是一个开源的 AI 编程代理，支持在终端、IDE 或独立桌面应用中运行。它不仅能连接 GitHub Copilot、OpenAI、Anthropic 等主流模型，还支持本地模型。

1.1 安装 OpenCode

根据你的操作系统选择安装方式：

MacOS / Linux (推荐):

curl -fsSL https://opencode.ai/install | bash

Windows (PowerShell):

# 使用 npm (需要 Node.js)
npm install -g opencode-ai

# 或者使用 Scoop
scoop install opencode

验证安装:

opencode --version

1.2 初始化与登录

安装完成后，首先进行身份验证和模型配置：

opencode auth login

你通常会有以下几种选择：

• GitHub Copilot: 使用你现有的 Copilot 订阅（最经济实惠的选择）。
• OpenAI / Anthropic: 直接使用 API Key。
• OpenCode Zen: 官方提供的按 Token 付费的精选模型服务。

1.3 基础使用

在项目根目录下启动：

opencode

你会进入一个交互式终端（TUI）。你可以直接通过自然语言让 AI 写代码、重构文件或解释逻辑。

---

二、 Oh My OpenCode (OmO)：增强框架

如果说 OpenCode 是 Linux 内核，那么 Oh My OpenCode (code-yeongyu/oh-my-opencode) 就是 Ubuntu。它为 OpenCode 注入了“灵魂”，引入了多 Agent 协作系统、自动化技能和更智能的上下文管理。

2.1 安装 OmO

注意: 安装 OmO 之前请确保已安装 OpenCode。

使用以下命令启动交互式安装向导：

# 使用 bun (推荐，速度最快)
bunx oh-my-opencode install

# 或者使用 npx
npx oh-my-opencode install

安装向导会自动：

1. 检测你的 OpenCode 版本。
2. 询问你的 API 订阅偏好（用于通过 Sisyphus 编排不同任务给最便宜/最聪明的模型）。
3. 生成优化的配置文件。

2.2 核心功能

OmO 安装后，你的 OpenCode 将获得以下超能力：

🪄 Ultrawork (终极工作流)

这是 OmO 最著名的功能。你不再需要一步步指导 Agent。只需一个命令，Sisyphus (西西弗斯) 编排器就会接管一切。

> ultrawork Refactor the login component to use Vue 3 Composition API and add unit tests

Sisyphus 会自动拆解任务，指派 Librarian 查阅文档，指派 Hephaestus 编写代码，并自我循环直到任务完成。

2.3 核心架构：Discipline Agents (职能特工)

OmO 不再是一个单一的助手，而是一支各司其职的 AI 团队。系统会根据任务性质自动调度最合适的 Agent：

Agent	代号	角色与职责	默认模型
Sisyphus	西西弗斯	总指挥官 (Orchestrator)。负责拆解任务、管理 Todo 列表、调度子 Agent 并行工作。拥有 extended thinking 能力 (32k token)。	claude-opus-4-6
Hephaestus	赫淮斯托斯	工匠 (Deep Worker)。类似于 AmpCode 的深度模式。自主执行复杂任务，绝不半途而废，行动前会进行充分调研。	gpt-5.3-codex
Prometheus	普罗米修斯	战略规划师 (Planner)。通过“面试模式”与用户通过多轮问答澄清需求，产出详尽的 Work Plan。	claude-opus-4-6-thinking
Oracle	神谕者	架构顾问 (Architect)。只读模式，不做修改。仅负责代码审查、架构决策、逻辑推理与 Debug 分析。	gpt-5.3-codex
Librarian	图书管理员	文档专家。跨仓库代码分析、查找第三方库文档、寻找 OSS 实现范例。证据驱动回答。	claude-sonnet-4-5
Explore	探索者	快速侦察兵。负责代码库的快速检索、上下文 grep、文件定位。	claude-haiku-4-5
Multimodal	观察者	视觉专家。分析 PDF、图片、流程图、UI 设计稿。	gemini-3-pro-image
Atlas	阿特拉斯	执行官。系统性地执行由 Prometheus 生成的计划，管理依赖关系。	claude-sonnet-4-5-thinking

2.4 独家黑科技 (Killer Features)

OmO 引入了多项解决 AI 编程痛点的核心技术：

🔒 Hash-Anchored Edits (哈希锚定编辑)

解决了 AI 编程最大的噩梦——“Lazy Edit” (懒惰编辑) 和 “Stale Line” (旧代码覆盖)。

• 机制: OmO 的编辑器强制使用 LINE#ID|content 格式。
• 效果: 在应用修改前，系统会校验目标行的 Content Hash。如果代码在 AI 思考期间被修改过（或其他 Agent 修改过），编辑会自动拒绝并重试。以此实现了 0 Stale-Line Error。

♾️ Ralph Loop / Ultrawork Loop

源自 Anthropic 的 “Ralph Wiggum” 插件概念，实现了真正的自指 (Self-Referential) 开发循环。

• 命令: /ralph-loop "Refactor the authentication module"
• 行为: Agent 进入死循环工作模式，直到核心目标达成。它会自动检测 <promise>DONE</promise> 标记。如果 Agent 试图偷懒或提前结束，系统会强制将其”踢回”循环中继续工作。
• Ultawork: /ulw-loop 则是 Ralph Loop 的增强版，开启最高并发模式。

📂 Deep Context (深度上下文注入)

解决大型项目 Context Window 不足的问题。

• 命令: /init-deep
• 原理: 在项目各级目录生成 AGENTS.md。
  • project/AGENTS.md: 项目级规范。
  • src/AGENTS.md: 源码级架构。
  • src/components/AGENTS.md: 组件级设计约定。
• 自动注入: 当 Agent 读取 src/components/Button.tsx 时，它会自动读取沿途所有的 AGENTS.md，获得精准的上下文。

📊 Task System (任务依赖管理)

内置了一个只要 .sisyphus/tasks/ 存在的持久化任务系统，支持依赖管理。

• activeForm: “Running tests”
• blocks: [“T-001”, “T-002”] (支持任务依赖与并行执行)
• 持久化: 即使重启 Session，任务状态依然保留。

🏷️ Category System (任务分类与专精)

OmO 不仅仅是选择 Agent，更是选择任务类别。每个类别预设了最适合的模型、Prompt 和工具权限。

• visual-engineering: 针对前端/UI。默认使用 Gemini 1.5 Pro (视觉能力强)。
• ultrabrain: 针对复杂逻辑。默认使用 GPT-5 / Opus。
• deep: 针对深思熟虑的自主任务。
• quick: 针对即时修改。默认使用 Haiku / Grok。
• writing: 针对文档。默认使用 Kimi (长文本)。

当你下达指令时，Sisyphus 会分析意图，自动切换到对应的 Category。

2.5 常用命令速查

命令	用途
/init-deep	初始化项目的层级化上下文 (AGENTS.md)。
/ralph-loop	开启死循环开发模式，直到任务完成。
/refactor	智能重构。结合 LSP、AST-grep 和 TDD 验证进行安全重构。
/handoff	生成当前工作的详细交接文档，方便在下一个 Session 继续。
/stop-continuation	紧急停止当前的自动循环 (Ralph/Ultrawork)。
/git-master	智能 Git 提交助手。自动检测项目提交风格与语言。

2.6 配置指南 (oh-my-opencode.jsonc)

推荐配置示例：

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
  // 1. Agent 模型配置
  "agents": {
    "sisyphus": {
      "model": "kimi-for-coding/k2p5", // 便宜且聪明的指挥官
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
    },
    // 简单的搜索任务用便宜模型
    "explore":   { "model": "github-copilot/grok-code-fast-1" }
  },
  // 2. 类别 (Category) 配置
  "categories": {
    "visual-engineering": { "model": "google/gemini-3-pro", "variant": "high" }, // 视觉任务交给 Gemini
    "quick": { "model": "opencode/gpt-5-nano" }
  },
  // 3. Tmux 可视化多 Agent (极为推荐)
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60
  },
  // 4. 实验性功能
  "experimental": {
    "task_system": true, // 开启任务系统
    "aggressive_truncation": true // 激进的上下文截断以节省 Token
  }
}

2.7 Tmux Visual Mode (可视化多 Agent)

如果在 oh-my-opencode.jsonc 中启用了 "tmux": { "enabled": true }，当你运行并发任务时（例如让 Explore 搜索文档，同时让 Hephaestus 写代码），OmO 会在 Tmux 中自动切分窗格 (Pane)。

• 左侧: 主指挥官 Sisyphus。
• 右侧: 子 Agent 实时工作的终端输出。
• 效果: 你可以像看监控一样看着多个 AI 协同工作。

---

三、 OpenSpec (SDD)：规格驱动开发框架

OpenSpec (Fission-AI/OpenSpec) 是一个专为 AI 编程助手设计的规格驱动开发 (Spec-Driven Development) 框架。它解决了 AI 编程中最大的痛点：“Prompt and Pray” (提示后祈祷)。

通过 OpenSpec，你不再直接让 AI 凭感觉写代码，而是先让它生成并让你确认规格说明书 (Spec)。这与资深工程师的工作流一致：先设计，后编码。

3.1 安装与初始化

OpenSpec 是一个独立的 CLI 工具，可以配合任何 AI 助手（OpenCode, Cursor, Cline 等）使用。它本身只是一个基于 Markdown 的流程管理工具。

安装:

npm install -g @fission-ai/openspec@latest

在项目中初始化:

cd my-project
openspec init

这会在项目中创建 .openspec/ 目录，用于存放未来的变更记录和规格文件。

3.2 核心工作流 (The OPSX Workflow)

OpenSpec 采用 “Explore -> Plan -> Build -> Verify” 的循环工作流。所有交互均通过以 /opsx: 开头的命令完成。

1. 探索 (Explore): 在正式立项前，与 AI 讨论思路、调查代码库及可行性分析。
2. 规划 (Plan): 创建变更文件夹，生成 Proposal (提案) -> Specs (规格) -> Design (设计) -> Tasks (任务)。
   • 注: 这一步是纯文档生成，不修改代码。
3. 实施 (Build): AI 读取任务清单，逐项编写代码。
4. 验证 (Verify): 检查代码是否符合规格要求。
5. 归档 (Archive): 确认无误后，归档变更记录。

3.3 命令详解

以下命令均在 OpenCode 终端中直接输入。

命令	说明	适用场景
/opsx:explore [topic]	探索思路。不创建文件，仅进行对话分析。可用于调研技术方案或澄清需求。	需求模糊、需要调研现有代码时。
/opsx:new [name]	新建变更。创建一个新的变更文件夹 (如 openspec/changes/add-auth/)。	开始一个新功能或修复 Bug 时。
/opsx:ff [name]	快速规划 (Fast Forward)。一次性生成所有规划文档 (Proposal, Specs, Design, Tasks)。	需求较明确，希望 AI 一气呵成生成变更计划时。
/opsx:continue	渐进规划。分步生成下一个规划文档 (如先 Proposal，确认后再生成 Specs)。	复杂需求，需要每一步人工确认时。
/opsx:apply	执行变更。读取 tasks.md，逐项执行代码编写任务。	规划文档确认无误后，开始写代码。
/opsx:verify	验证结果。检查代码实现的完整性、正确性和一致性。	代码写完后，归档前。
/opsx:archive	归档变更。将当前变更移入归档目录，并清理工作区。	任务彻底完成。
/opsx:onboard	交互式教程。在当前项目中引导你完成一次完整的 OpenSpec 流程。	第一次使用，学习如何操作时。

提示: 不同工具的命令语法可能略有不同。在 OpenCode/Claude Code 中使用 /opsx:command；在 Cursor/Windsurf 中可能需要使用 /opsx-command (如 /opsx-new)。

---

四、 全栈工作流实战

将 OpenCode (IDE), Oh My OpenCode (Execution), OpenSpec (Planning) 结合，打造最强 AI 开发流：

1. 启动与加载:

   opencode
   > /init-deep   # (OmO) 加载项目上下文

2. 前期调研 (OpenSpec):

   > /opsx:explore 如何在本项目中集成 Dark Mode？请检查现有的 CSS 框架。

   AI 会分析现有代码（Tailwind/UnoCSS?），给出方案建议。

3. 新建任务 (OpenSpec):

   > /opsx:new add-dark-mode

4. 生成规划 (OpenSpec):

   > /opsx:ff

   AI 自动生成 proposal.md, specs/..., design.md, tasks.md。 此时人工介入: 打开生成的 Markdown 文件，检查设计是否合理。如果不满意，直接对话让 AI 修改文档。

5. 执行代码 (OmO + OpenSpec): 规划确认后，利用 Ultrawork 的强大能力去执行 OpenSpec 的任务：

   > ultrawork /opsx:apply

   技巧: 这里使用 ultrawork 包装 /opsx:apply，可以让 Sisyphus (OmO 的强力 Agent) 来驱动 OpenSpec 的执行过程，比普通 Agent 更稳定。

6. 验收与归档:

   > /opsx:verify
   > /opsx:archive

五、 常见问题 (FAQ)

Q: old commands 如 /opsx:propose 还能用吗？ A: 旧版命令 (/opsx:propose) 是一次性生成所有文档的旧方式。新版推荐使用 /opsx:new + /opsx:ff (或 /opsx:continue) 的组合，提供了更细粒度的控制力。

Q: 为什么需要 OpenSpec？直接 Prompt 不行吗？ A: 对于简单的单文件修改，直接 Prompt 没问题。但对于复杂功能，AI 经常会“产生幻觉”或漏掉需求。OpenSpec 强制 AI “先想后做”，能显著提高一次性编码成功率。

Q: Oh My OpenCode 和 OpenSpec 冲突吗？ A: 完全不冲突。OmO 提供了强大的执行者 (Agents)，而 OpenSpec 提供了清晰的蓝图 (Specs)。两者结合是 1+1>2 的效果。