OpenCode 与其他 AI 助手：运行流水线的 3 种方式

学完你能做什么

✅ 使用 OpenCode 启动和运行 Factory 流水线
✅ 使用 Cursor 运行流水线
✅ 理解不同 AI 助手的指令格式差异
✅ 根据使用场景选择合适的 AI 助手

你现在的困境

你已经初始化了 Factory 项目，但除了 Claude Code，不知道如何用其他 AI 助手运行流水线。OpenCode 和 Cursor 是主流的 AI 编程助手，它们能运行 Factory 流水线吗？启动方式和指令格式有什么不同？

什么时候用这一招

AI 助手	推荐使用场景	优势
Claude Code	需要最稳定的 Agent 模式体验	原生支持 Agent 模式，指令格式清晰
OpenCode	多平台用户，需要灵活的 AI 工具	跨平台，支持 Agent 模式
Cursor	VS Code 重度用户，习惯 VS Code 生态	集成度高，无缝切换

核心原则

所有 AI 助手的执行逻辑完全相同：读取 Agent 定义 → 执行流水线 → 生成产物。差异仅在于启动方式和指令格式。

🎒 开始前的准备

在开始之前，请确保：

✅ 已完成安装与配置
✅ 已使用 factory init 初始化项目
✅ 已安装 OpenCode 或 Cursor（至少一个）

核心思路：AI 助手作为流水线执行引擎

AI 助手是流水线的执行引擎，负责解读 Agent 定义并生成产物。核心工作流程包括五个步骤：首先读取 .factory/pipeline.yaml 了解阶段顺序，然后加载调度器掌握执行约束和权限检查规则，接着根据当前状态加载对应的 Agent 定义文件，之后执行 Agent 指令生成产物并验证退出条件，最后等待用户确认后继续下一阶段。

重要：AI 助手必须支持 Agent 模式

Factory 流水线依赖于 AI 助手能够理解并执行复杂的 Markdown 指令。所有支持的 AI 助手（Claude Code、OpenCode、Cursor）都具备 Agent 模式能力。

跟我做

第 1 步：使用 OpenCode 运行流水线

自动启动（推荐）

如果你已经全局安装了 OpenCode CLI：

bash

# 在项目根目录执行
factory init

factory init 会自动检测并启动 OpenCode，传递以下提示词：

text

请阅读.factory/pipeline.yaml和.factory/agents/orchestrator.checkpoint.md，启动流水线，帮我将产品想法碎片转化为可运行的应用，接下来我将会输入想法碎片。注意：Agent引用的skills/和policies/文件需要先查找.factory/目录，再查找根目录。

你应该看到：

终端显示 Starting OpenCode...
OpenCode 窗口自动打开
提示词已经自动粘贴到输入框

手动启动

如果自动启动失败，可以手动操作：

打开 OpenCode 应用
打开你的 Factory 项目目录
复制以下提示词到 OpenCode 输入框：

text

请阅读.factory/pipeline.yaml和.factory/agents/orchestrator.checkpoint.md，启动流水线，帮我将产品想法碎片转化为可运行的应用，接下来我将会输入想法碎片。注意：Agent引用的skills/和policies/文件需要先查找.factory/目录，再查找根目录。

按回车执行

继续执行流水线

如果流水线已运行到某个阶段，你可以使用 factory run 命令继续：

bash

# 查看当前状态并生成指令
factory run

# 或从指定阶段开始
factory run prd

OpenCode 会显示与 Claude Code 类似的指令：

🤖 AI Assistant Instructions:
──────────────────────────────────────────

This is an Agent Factory project. Please:

1. Read .factory/pipeline.yaml
2. Read .factory/agents/orchestrator.checkpoint.md
3. Read .factory/config.yaml
4. Execute pipeline from: bootstrap

Note: Check .factory/ first for skills/policies/ references, then root directory.

第 2 步：使用 Cursor 运行流水线

Cursor 是基于 VS Code 的 AI 编程助手，使用 Composer 功能运行 Factory 流水线。

检测 Cursor

Factory CLI 会自动检测 Cursor 环境（通过 CURSOR 或 CURSOR_API_KEY 环境变量）。

使用 Composer 运行

在 Cursor 中打开你的 Factory 项目目录
执行 factory run 命令：

bash

factory run

终端会显示 Cursor 专用指令：

🤖 Cursor Instructions:
──────────────────────────────────────────

This is an Agent Factory project. Use Cursor Composer to:

1. @ReadFile .factory/pipeline.yaml
2. @ReadFile .factory/agents/orchestrator.checkpoint.md
3. @ReadFile .factory/config.yaml
   (Note: Check .factory/ first for skills/policies/ references)
4. Execute pipeline from: bootstrap

复制这些指令到 Cursor Composer 输入框
执行

检查点 ✅

Cursor Composer 窗口已打开
流水线开始执行，显示当前阶段（如 Running: bootstrap）
生成产物（如 input/idea.md）

第 3 步：理解不同 AI 助手的指令格式

虽然执行逻辑相同，但不同 AI 助手的指令格式有细微差异：

操作	Claude Code 格式	Cursor 格式	其他 AI 助手（OpenCode 等）
读取文件	`Read(filePath)`	`@ReadFile filePath`	`Read filePath`
读取多个文件	`Read(file1)`, `Read(file2)`	`@ReadFile file1`, `@ReadFile file2`	-
写入文件	`Write(filePath, content)`	直接写入	-
执行 Bash 命令	`Bash(command)`	直接执行	-

Factory CLI 自动处理

当你运行 factory run 时，CLI 会自动检测当前 AI 助手类型，并生成对应的指令格式。你只需要复制粘贴即可，无需手动转换。

第 4 步：从指定阶段继续执行

如果流水线已经完成前几个阶段，你可以从任意阶段继续：

bash

# 从 UI 阶段开始
factory run ui

# 从 Tech 阶段开始
factory run tech

# 从 Code 阶段开始
factory run code

Factory CLI 会显示当前流水线状态：

Pipeline Status:
────────────────────────
Project: my-app
Status: Running
Current Stage: ui
Completed: bootstrap, prd

Available stages:
  ✓ bootstrap
  ✓ prd
  → ui
  ○ tech
  ○ code
  ○ validation
  ○ preview

第 5 步：使用 factory continue 节省 Token（仅限 Claude Code）

注意

factory continue 命令目前仅支持 Claude Code。如果你使用 OpenCode 或 Cursor，请直接使用 factory run 手动启动新会话。

为了节省 Token 并避免上下文累积，Claude Code 支持分会话执行：

bash

# 新开终端窗口，执行
factory continue

执行效果：

读取当前状态（.factory/state.json）
自动启动新的 Claude Code 窗口
从上次暂停的阶段继续

适用场景：

已完成 Bootstrap → PRD，想新建会话执行 UI 阶段
已完成 UI → Tech，想新建会话执行 Code 阶段
任何需要避免长对话历史的场景

踩坑提醒

问题 1：OpenCode 启动失败

症状：执行 factory init 后，OpenCode 没有自动启动。

原因：

OpenCode CLI 未添加到 PATH
OpenCode 未安装

解决方案：

bash

# 手动启动 OpenCode
# Windows
%LOCALAPPDATA%\Programs\OpenCode\OpenCode.exe

# macOS
/Applications/OpenCode.app

# Linux（按优先级查找：先 /usr/bin/opencode，再 /usr/local/bin/opencode）
/usr/bin/opencode
# 如果上述路径不存在，尝试：
/usr/local/bin/opencode

然后手动复制提示词粘贴到 OpenCode。

问题 2：Cursor Composer 无法识别指令

症状：复制 factory run 生成的指令到 Cursor Composer，但没有响应。

原因：

Cursor Composer 的 @ReadFile 语法需要精确匹配
文件路径可能不正确

解决方案：

确认使用 @ReadFile 而非 Read 或 ReadFile
确认文件路径相对于项目根目录
尝试使用绝对路径

示例：

text

# ✅ 正确
@ReadFile .factory/pipeline.yaml

# ❌ 错误
Read(.factory/pipeline.yaml)
@readfile .factory/pipeline.yaml

问题 3：Agent 引用技能文件失败

症状：Agent 报错找不到 skills/bootstrap/skill.md 或 policies/failure.policy.md。

原因：

Agent 查找路径顺序错误
项目中同时存在 .factory/ 和根目录的 skills/、policies/

解决方案：所有 AI 助手都遵循相同的查找顺序：

优先查找 .factory/skills/ 和 .factory/policies/
回退到根目录 skills/ 和 policies/

确保：

Factory 项目初始化后，skills/ 和 policies/ 已复制到 .factory/
Agent 定义中明确提示："先查找 .factory/ 目录，再查找根目录"

问题 4：流水线状态不同步

症状：AI 助手显示已完成某个阶段，但 factory run 仍显示 running 状态。

原因：

AI 助手动更新了 state.json，但与 CLI 状态不一致
可能是多个窗口同时修改了状态文件

解决方案：

bash

# 重置项目状态
factory reset

# 重新运行流水线
factory run

最佳实践

避免在多个 AI 助手窗口中同时运行同一项目的流水线。这会导致状态冲突和产物覆盖。

本课小结

本课学习了如何使用 OpenCode、Cursor 等 AI 助手运行 Factory 流水线：

核心要点：

✅ Factory 支持多种 AI 助手（Claude Code、OpenCode、Cursor）
✅ factory init 自动检测并启动可用的 AI 助手
✅ factory run 根据当前 AI 助手生成对应指令
✅ factory continue（仅限 Claude Code）支持分会话执行，节省 Token
✅ 所有 AI 助手遵循相同的执行逻辑，仅指令格式不同

关键文件：

.factory/pipeline.yaml —— 流水线定义
.factory/agents/orchestrator.checkpoint.md —— 调度器规则
.factory/state.json —— 流水线状态

选择建议：

Claude Code：最稳定的 Agent 模式体验（推荐）
OpenCode：跨平台用户首选
Cursor：VS Code 重度用户

下一课预告

下一课我们学习 必需插件安装。
你会学到：
为什么需要安装 superpowers 和 ui-ux-pro-max 插件
如何自动或手动安装插件
插件安装失败时的处理方法

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-29

功能	文件路径	行号
OpenCode 启动	`cli/commands/init.js`	152-215
Claude Code 启动	`cli/commands/init.js`	119-147
AI 助手检测	`cli/commands/run.js`	105-124
指令生成	`cli/commands/run.js`	130-183

关键常量：

CLAUDE_CODE / ANTHROPIC_API_KEY：Claude Code 环境变量检测（run.js:109-110）
CURSOR / CURSOR_API_KEY：Cursor 环境变量检测（run.js:114-115）
OPENCODE / OPENCODE_VERSION：OpenCode 环境变量检测（run.js:119-120）

关键函数：

launchClaudeCode(projectDir)：启动 Claude Code 并传递提示词（init.js:119-147）
launchOpenCode(projectDir)：启动 OpenCode，支持 CLI 和可执行文件两种方式（init.js:152-215）
detectAIAssistant()：通过环境变量检测当前 AI 助手类型（run.js:105-124）
getAssistantInstructions(assistant, ...)：根据 AI 助手类型生成对应指令（run.js:130-183）

OpenCode 与其他 AI 助手：运行流水线的 3 种方式 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路：AI 助手作为流水线执行引擎 ​

跟我做 ​

第 1 步：使用 OpenCode 运行流水线 ​

自动启动（推荐） ​

手动启动 ​

继续执行流水线 ​

第 2 步：使用 Cursor 运行流水线 ​

检测 Cursor ​

使用 Composer 运行 ​

检查点 ✅ ​

第 3 步：理解不同 AI 助手的指令格式 ​

第 4 步：从指定阶段继续执行 ​

第 5 步：使用 factory continue 节省 Token（仅限 Claude Code） ​

踩坑提醒 ​

问题 1：OpenCode 启动失败 ​

问题 2：Cursor Composer 无法识别指令 ​

问题 3：Agent 引用技能文件失败 ​

问题 4：流水线状态不同步 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

OpenCode 与其他 AI 助手：运行流水线的 3 种方式

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路：AI 助手作为流水线执行引擎

跟我做

第 1 步：使用 OpenCode 运行流水线

自动启动（推荐）

手动启动

继续执行流水线

第 2 步：使用 Cursor 运行流水线

检测 Cursor

使用 Composer 运行

检查点 ✅

第 3 步：理解不同 AI 助手的指令格式

第 4 步：从指定阶段继续执行

第 5 步：使用 factory continue 节省 Token（仅限 Claude Code）

踩坑提醒

问题 1：OpenCode 启动失败

问题 2：Cursor Composer 无法识别指令

问题 3：Agent 引用技能文件失败

问题 4：流水线状态不同步

本课小结

下一课预告

附录：源码参考