Skip to content

使用指南 ​

本文档详细介绍 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。

流程:

  1. 需求访谈 — AI 会追问需求细节,澄清范围
  2. PRD 输出 → docs/prd/<title>.md
  3. 创建 GitHub Issue — 作为 Parent Issue,后续 Sub Issues 以此为锚点

产出:

  • docs/prd/<title>.md — 产品需求文档
  • GitHub Issue #N — 需求跟踪 Issue

PRD 结构:

  • 背景与动机
  • 目标
  • 范围(In Scope / Out of Scope)
  • 用户故事
  • 验收标准
  • 技术约束
  • Open Questions

/design — 技术设计 ​

用途:基于 PRD 输出系统规格、技术方案和架构决策。

流程:

  1. 委派 @architect 阅读 PRD 与既有 docs/specs/
  2. 输出/更新系统规格与技术方案 → docs/specs/<slug>.md
  3. 记录关键 ADR → docs/adr/<date>-<slug>.md
  4. 在 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(单一任务账本)。

流程:

  1. 委派 @architect 分析系统规格(docs/specs/)
  2. 拆解为独立可执行的垂直切片任务,标注真实阻塞关系(Blocked By)并返回结构化 Task Plan
  3. 为每个任务创建 GitHub Sub Issue,关联 Parent Issue(不写本地 task Markdown 或 DAG.md)

Sub Issue 内容:

  • Builds:这个 Task 完成后哪条端到端行为可以工作
  • Acceptance Criteria:对应 Design Testing Decisions 的可观察行为列表
  • Blocked By:前置 Sub Issue 编号或 None

DAG 原则:

  • 每个任务应是垂直切片,单人 2-4 小时可完成
  • 无依赖的任务可以并行执行
  • 有依赖的任务按拓扑排序逐 batch 处理

/code — 编码实现 ​

用途:按 DAG 拓扑排序,逐 batch 实现代码。

流程:

  1. 按拓扑排序获取 ready 任务
  2. 为每个任务创建分支 feat/<task-slug>
  3. 并行派发 @developer 实现代码 + 单测
  4. 创建 PR
  5. 委派 @reviewer 审查 PR
  6. CI 通过后自动合并

实现规范:

  • 遵循技术方案定义的分层结构与项目现有代码规范(技术栈无关)
  • TDD 优先:先写测试 → 最小实现 → 重构
  • Conventional Commits,多次提交

禁止事项:

  • 不创建与任务无关的文件
  • 不引入未在项目中使用的第三方依赖
  • 不提交硬编码的密钥/配置

/review — 代码审查 ​

用途:AI 双轴审查 PR 并自动合并。

流程:

  1. 委派 @reviewer 获取 PR diff
  2. 双轴审查:
    • 规范轴 — 代码是否符合编码标准?
    • 规格轴 — 代码是否忠实实现了 PRD/技术方案?
  3. 输出审查报告
  4. 根据结果 Approve 或 Request Changes

审查报告格式:

[CRITICAL] 标题 - 必须修复
- 文件:path:行号
- 问题描述
- 修复建议

[HIGH] 标题 - 应该修复
[MEDIUM] 标题 - 建议修复

合并条件:

  • 无 Critical/High 问题 → Approve + 合并
  • 有 Critical/High → Request Changes + 修复后重审(最多 3 轮)

/release — 发布(手动阶段) ​

⚠️ 该阶段为手动触发,不会在自动模式中执行。

流程(技术栈无关,按 Profile 的 Release 规则):

  1. 确定版本:聚合上一 tag 后全部 commit,按 Profile 版本规则分类(breaking→major, feature→minor, fix→patch):
    bash
    git describe --tags --abbrev=0
    git log --oneline <last-tag>..HEAD
  2. 创建 Release 分支 + 更新版本文件(用户确认版本后)
    bash
    git checkout -b "release/<version>"
    # 按 Profile version file 规则更新版本号
    git commit -m "chore: release <version>"
    git push -u origin "release/<version>"
  3. 创建 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>"
  4. 监控发布: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 完成实际发布。