RPI Workflow for OpenCode (OpenSpec Integrated)

基于 GudaSpec 的 RPI (Research-Plan-Implementation) 工作流，适配于 OpenCode，完整集成 OpenSpec 规范和 oh-my-opencode Agent 系统。

核心理念

RPI 编码理论将复杂开发任务分解为三个阶段：

1. Research（研究） - 产出约束集，生成 OpenSpec 提案
2. Plan（计划） - 生成零决策可执行任务流
3. Implementation（实现） - 纯机械执行

多模型 Agent 系统

每个阶段由专业化的 Agent 执行，使用最适合的模型：

Agent	Provider	Model	阶段	权限
@rpi-analyst	Anthropic	Claude	Research	READ-ONLY
@rpi-architect	Anthropic	Claude	Plan	READ-ONLY
@rpi-backend	OpenAI	o3	Implementation (Backend)	WRITE
@rpi-frontend	Google	Gemini	Implementation (Frontend)	WRITE
@rpi-reviewer	Anthropic	Claude	Review	READ-ONLY

为什么需要这个工作流？

• 上下文窗口优化：通过人工分割上下文，让 AI 的有效上下文被极致利用
• 减少决策疲劳：所有决策在计划阶段完成，实现阶段只需执行
• 可追溯性：每个阶段产出明确的文档，便于回溯和审计
• 标准化规范：集成 OpenSpec，确保需求和实现的一致性
• 多模型协作：不同阶段使用最适合的模型，发挥各自优势
• 权限控制：Research/Plan/Review 阶段只读，防止意外修改

前置要求

• Node.js >= 20.x
• OpenSpec CLI：npm install -g @fission-ai/openspec@latest
• OpenCode：已安装并配置

可用命令

RPI 工作流命令

命令	描述
/rpi-init	初始化 RPI 工作流环境和 OpenSpec
/rpi-research	执行研究阶段，生成约束集和 OpenSpec 提案
/rpi-plan	执行计划阶段，生成零决策任务列表
/rpi-impl	执行实现阶段，按任务完成开发
/rpi-status	查看当前工作流状态
/rpi-archive	归档完成的工作流

OpenSpec 命令（集成使用）

命令	描述
/opsx:explore	探索需求，澄清范围
/opsx:new	创建新的变更
/opsx:continue	生成下一个工件
/opsx:ff	快速生成所有规划工件
/opsx:apply	执行任务，实现代码
/opsx:verify	验证实现正确性
/opsx:archive	归档完成的变更

快速开始

1. 安装 OpenSpec

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

2. 初始化项目

# 在项目目录中
openspec init

3. 安装 RPI 命令

# 克隆此仓库后
./install.sh --project  # 项目级安装
# 或
./install.sh --user     # 用户级安装

4. 开始使用

# 在 OpenCode 中
/rpi-init                                    # 初始化环境
/rpi-research $REQUIREMENT="实现用户登录"    # 开始研究 (@rpi-analyst)
/rpi-plan                                    # 制定计划 (@rpi-architect)
/rpi-impl                                    # 执行实现 (@rpi-backend/@rpi-frontend)

5. Agent 调用示例

# 显式调用 Agent
Ask @rpi-analyst to analyze the authentication module
Ask @rpi-architect to design the task flow
Ask @rpi-backend to implement the user API
Ask @rpi-frontend to create the login form
Ask @rpi-reviewer to review the implementation

# 后台并行执行
delegate_task(agent="rpi-backend", background=true, prompt="Implement API")
delegate_task(agent="rpi-frontend", background=true, prompt="Create component")

工作流详解

Research 阶段

Agent: @rpi-analyst (Claude, READ-ONLY)

目标：产出约束集和可验证的成功判据

OpenSpec 集成：

• 使用 /opsx:explore 探索需求
• 使用 /opsx:new 创建变更
• 使用 /opsx:ff 生成规划工件

关键活动：

• 代码库评估（按上下文边界划分）
• 结构化探索
• 歧义消解
• 生成 proposal 和 specs

输出：

• openspec/changes/<change-name>/proposal.md
• openspec/changes/<change-name>/specs/

Plan 阶段

Agent: @rpi-architect (Claude, READ-ONLY)

目标：生成零决策可执行任务流

关键活动：

• 多维度实现分析
• 不确定性消除审计
• PBT 属性提取
• 任务分解

输出：

• openspec/changes/<change-name>/design.md
• openspec/changes/<change-name>/tasks.md

Implementation 阶段

Agents:

• @rpi-backend (OpenAI o3, WRITE) - Backend 任务
• @rpi-frontend (Google Gemini, WRITE) - Frontend 任务

目标：按任务机械执行

OpenSpec 集成：

• 使用 /opsx:apply 执行任务
• 使用 /opsx:verify 验证实现
• 使用 /opsx:archive 归档变更

关键原则：

• 最小可验证阶段
• 严格控制上下文窗口
• 每阶段后建议清空上下文
• 代码质量优先

Review 阶段

Agent: @rpi-reviewer (Claude, READ-ONLY)

目标：代码审查和质量验证

关键活动：

• 代码风格检查
• 安全审计
• 性能审查
• Backend/Frontend 集成验证

目录结构

project/
├── .opencode/
│   ├── commands/           # RPI 自定义命令
│   │   ├── rpi-init.md
│   │   ├── rpi-research.md
│   │   ├── rpi-plan.md
│   │   ├── rpi-impl.md
│   │   ├── rpi-status.md
│   │   └── rpi-archive.md
│   └── rpi/
│       └── archive/        # 本地归档数据
└── openspec/               # OpenSpec 目录
    ├── AGENTS.md           # 代理约定
    ├── specs/              # 主规格
    ├── changes/            # 活动变更
    │   └── <change-name>/
    │       ├── proposal.md
    │       ├── specs/
    │       ├── design.md
    │       └── tasks.md
    └── archive/            # 归档的变更

上下文管理策略

为了极致利用 AI 的上下文窗口：

1. 每个阶段完成后：清空上下文，重新开始
2. 每次实现前：只加载当前任务相关的代码
3. 任务隔离：不同任务尽量独立处理
4. 增量验证：小步前进，频繁验证

护栏规则

Research 阶段

• 禁止按角色划分（如"架构师agent"）
• 必须按上下文边界划分
• 不做架构决策，只呈现约束

Plan 阶段

• 消除所有决策点
• 每个需求必须有 PBT 属性
• 无法指定则返回研究阶段

Implementation 阶段

• 永不直接应用外部原型
• 强制副作用审查
• 最小化文档，优先自解释代码

与原版 GudaSpec 的对比

特性	GudaSpec (Claude Code)	RPI (OpenCode)
OpenSpec	集成	✓ 完整集成
Agent 系统	内置	✓ oh-my-opencode 兼容
多模型支持	Codex MCP + Gemini MCP	✓ 原生 Agent 路由
并行执行	支持	✓ delegate_task
权限控制	内置	✓ READ-ONLY/WRITE
命令前缀	/gudaspec:	/rpi- + /opsx:

与 oh-my-opencode 集成

本工作流设计为与 oh-my-opencode 配合使用：

• RPI agents 可与 Sisyphus 编排器协同工作
• 支持 ULW (Ultrawork) 模式的并行执行
• 权限配置与 oh-my-opencode 的权限系统兼容
• Provider chain 提供 fallback 支持

最佳实践

1. 不要跳过阶段：每个阶段都有其存在的意义
2. 保持约束具体：模糊的约束会导致模糊的实现
3. 任务粒度要小：便于验证和上下文管理
4. 勤于清空上下文：防止上下文污染
5. 记录决策理由：便于后续回溯
6. 使用专业 Agent：让每个 Agent 专注于其擅长领域
7. 并行执行独立任务：Backend 和 Frontend 任务可并行

许可证

MIT License

致谢

• GuDaStudio/commands - GudaSpec 工作流设计
• fission-ai/openspec - OpenSpec 规范框架
• code-yeongyu/oh-my-opencode - Agent 系统设计