使用指南
本文档详细介绍 opencode-cabbage 插件所有命令和模式的用法。
两种工作模式
手动模式
按顺序逐一执行命令,适合需要精细控制的场景:
/flow-setup → /flow-requirements → /flow-design → /flow-tasks → /flow-code → /flow-review → /flow-release自动模式
需求确认后,输入 @dev-lifecycle(配合 OpenCode 内置 /goal 命令可开启自动续跑,终点为自动合并,不包含 release)。
命令详解
/setup — 初始化
用途:首次使用前的环境准备。
检测项:
- gh CLI 是否安装并可执行
- GitHub 远程仓库是否配置
- 是否需要 GitHub CLI 认证
- Project Profile(AGENTS.md)与 CI/release workflow
产出:
docs/prd/、docs/adr/、docs/dev/{specs,tasks,api,db,guides}/目录- 根
AGENTS.md的 Project Profile 区块(用户确认后写入)
何时执行:第一次使用插件时,或切换到一个新项目时。
/requirements — 需求分析
用途:将模糊需求转化为结构化 PRD。
流程:
- 需求访谈 — AI 会追问需求细节,澄清范围
- PRD 输出 →
docs/prd/<title>.md - 创建 GitHub Issue — 作为 Parent Issue,后续 Sub Issues 以此为锚点
产出:
docs/prd/<title>.md— 产品需求文档- GitHub Issue #N — 需求跟踪 Issue
PRD 结构:
- 背景与动机
- 目标
- 范围(In Scope / Out of Scope)
- 用户故事
- 验收标准
- 技术约束
- Open Questions
/design — 技术设计
用途:基于 PRD 输出系统规格、技术方案和架构决策。
流程:
- 委派
@architect阅读 PRD 与既有docs/specs/ - 输出/更新系统规格与技术方案 →
docs/specs/<slug>.md - 记录关键 ADR →
docs/adr/<date>-<slug>.md - 在 Parent Issue 发布评论
产出:
docs/specs/<slug>.md— 系统规格与技术方案(含架构、接口、Testing Decisions)docs/adr/<date>-<slug>.md— 架构决策记录- Issue comment — 方案摘要
ADR 结构:
- 标题、状态、日期
- 背景(Context)
- 决策(Decision)与备选方案
- 后果(Consequences:正面 + 负面)
/tasks — 任务拆解
用途:将技术方案拆解为垂直切片 Task Plan 并创建 GitHub Sub Issues(单一任务账本)。
流程:
- 委派
@architect分析系统规格(docs/specs/) - 拆解为独立可执行的垂直切片任务,标注真实阻塞关系(
Blocked By)并返回结构化 Task Plan - 为每个任务创建 GitHub Sub Issue,关联 Parent Issue(不写本地 task Markdown 或
DAG.md)
Sub Issue 内容:
Builds:这个 Task 完成后哪条端到端行为可以工作Acceptance Criteria:对应 DesignTesting Decisions的可观察行为列表Blocked By:前置 Sub Issue 编号或None
DAG 原则:
- 每个任务应是垂直切片,单人 2-4 小时可完成
- 无依赖的任务可以并行执行
- 有依赖的任务按拓扑排序逐 batch 处理
/code — 编码实现
用途:按 DAG 拓扑排序,逐 batch 实现代码。
流程:
- 按拓扑排序获取 ready 任务
- 为每个任务创建分支
feat/<task-slug> - 并行派发
@developer实现代码 + 单测 - 创建 PR
- 委派
@reviewer审查 PR - CI 通过后自动合并
实现规范:
- 遵循技术方案定义的分层结构与项目现有代码规范(技术栈无关)
- TDD 优先:先写测试 → 最小实现 → 重构
- Conventional Commits,多次提交
禁止事项:
- 不创建与任务无关的文件
- 不引入未在项目中使用的第三方依赖
- 不提交硬编码的密钥/配置
/review — 代码审查
用途:AI 双轴审查 PR 并自动合并。
流程:
- 委派
@reviewer获取 PR diff - 双轴审查:
- 规范轴 — 代码是否符合编码标准?
- 规格轴 — 代码是否忠实实现了 PRD/技术方案?
- 输出审查报告
- 根据结果 Approve 或 Request Changes
审查报告格式:
[CRITICAL] 标题 - 必须修复
- 文件:path:行号
- 问题描述
- 修复建议
[HIGH] 标题 - 应该修复
[MEDIUM] 标题 - 建议修复合并条件:
- 无 Critical/High 问题 → Approve + 合并
- 有 Critical/High → Request Changes + 修复后重审(最多 3 轮)
/release — 发布(手动阶段)
⚠️ 该阶段为手动触发,不会在自动模式中执行。
流程(技术栈无关,按 Profile 的 Release 规则):
- 确定版本:聚合上一 tag 后全部 commit,按 Profile 版本规则分类(breaking→major, feature→minor, fix→patch):bash
git describe --tags --abbrev=0 git log --oneline <last-tag>..HEAD - 创建 Release 分支 + 更新版本文件(用户确认版本后)bash
git checkout -b "release/<version>" # 按 Profile version file 规则更新版本号 git commit -m "chore: release <version>" git push -u origin "release/<version>" - 创建 Release PR(用户确认)→ CI 通过 + 人工批准后合并并打 tag:bash
HEAD_SHA=$(gh pr view <n> --json headRefOid --jq .headRefOid) gh pr merge <n> --squash --delete-branch --match-head-commit "$HEAD_SHA" git tag "v<version>" git push origin "v<version>" - 监控发布:tag push 触发项目 GitHub Actions release workflow,监听运行结果
实际发布由项目自己的 GitHub Actions release workflow 执行,不假设 npm 或其他生态。
自动编排(@dev-lifecycle)
启动方式
需求确认后,直接输入:
@dev-lifecycle执行流程
Phase 1: 技术方案 + ADR (委派 @architect)
Phase 2: DAG 任务拆解 + Sub Issues (委派 @architect)
Phase 3: 并行编码实现 (委派 @developer / @reviewer)
Phase 4: 合并确认
Complete: goal 验证 + 完成异常处理
| 场景 | 处理 |
|---|---|
| 步骤失败 | Pause flow,通知用户 |
| Task 失败 | 自动重试 3 次 → 标记 blocked 并停止下游 |
| 审查不通过 | 修复→重审,最多 3 轮 |
| Continuation 耗尽 | Pause,用户介入 |
| 上下文压力大 | 自动写 handoff 文档,恢复时先读它 |
Goal 状态管理(复用 OpenCode 原生 /goal)
连续无人值守执行直接使用 OpenCode v2.3 内置 /goal 命令:
/goal <目标>— 开启自动续跑循环(例如/goal 完成 Flow #42 全流程开发)/goal pause//goal resume//goal clear— 暂停 / 恢复 / 清除内置目标- 最终完成后由
@dev-lifecycle派发只读@goal-verify对照 Parent Issue 与docs/specs/独立验证並输出证据报告
最佳实践
什么时候用手动模式
- 需求还不明确,需要多轮访谈
- 需要精细控制每一步的产出
- 部分阶段需要人工参与(如设计评审)
什么时候用自动模式
- 需求已清晰确认
- 标准功能开发
- 希望最大化效率
文档规范
- 领域术语 → 根
CONTEXT.md - PRD →
docs/prd/ - 系统当前规格(Living Specs)→
docs/specs/ - ADR →
docs/adr/ - 调研报告 →
docs/dev/research/ - 使用指南 →
docs/guides/ - 任务与进度 → GitHub Parent/Sub Issues(单一任务账本,不再新建本地 task Markdown)
分支命名
feat/<task-slug>提交规范
使用 Conventional Commits:
feat: 新增用户注册接口
fix: 修复登录超时问题
refactor: 重构权限校验逻辑
docs: 更新 API 文档
test: 添加用户模块单元测试版本发布
发布遵循技术栈无关的 Release 流程(详见 /release 章节):按 Profile 的版本规则更新版本文件、创建 Release PR、人工批准后合并并打 tag,由项目自己的 GitHub Actions release workflow 完成实际发布。