使用指南

本文档详细介绍 opencode-cabbage 插件所有命令和模式的用法。

两种工作模式

手动模式

按顺序逐一执行命令，适合需要精细控制的场景：

/setup → /requirements → /design → /tasks → /code → /review → /release

自动模式

需求确认后，输入 @dev-lifecycle 即可全自动完成剩余流程（终点为自动合并，不包含 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 区块
缺失的 CI / release workflow 草案

何时执行：第一次使用插件时，或切换到一个新项目时。

`/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/dev/specs/<title>.md
记录关键 ADR → docs/adr/<date>-<slug>.md
在 Parent Issue 发布评论

产出：

docs/dev/specs/<title>.md — 完整技术方案（技术栈、架构、模块、接口、数据模型）
docs/adr/<date>-<slug>.md — 架构决策记录
Issue comment — 方案摘要

ADR 结构：

标题、状态、日期
背景
决策
备选方案（含未采纳原因）
后果（正面 + 负面）

`/tasks` — 任务拆解

用途：将技术方案拆解为 DAG 任务并创建 Sub Issues。

流程：

委派 @architect 分析技术方案
拆解为独立可执行的任务，标注依赖关系
每个任务创建 task markdown 文件 → docs/dev/tasks/<task-name>.md
为每个任务创建 GitHub Sub Issue，关联 Parent Issue

任务定义格式（frontmatter）：

yaml

---
name: 实现用户注册接口
dependsOn: []           # 依赖的任务 ID
area: developer        # developer | common
parallelSafe: true      # 是否可以与其他任务并行
expectedFiles:
  - src/controllers/AuthController.ts
  - src/services/AuthService.ts
  - src/repositories/UserRepository.ts
testCommands:
  - npm run test:auth
acceptance: 用户可以通过邮箱+密码注册，收到验证邮件
---

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 + 修复后重审（最多 9 轮）

`/release` — 发布（手动阶段）

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

流程（技术栈无关，按 Profile 的 Release 规则）：

调用 release_control{propose-version} 聚合上一 tag 后 main 的变更并提议 SemVer 版本（用户确认）
调用 release_control{open-release-pr} 创建 Release PR（更新版本文件 + Release Notes）
CI 通过 + 人工批准后调用 release_control{merge-release-pr} 合并并打 tag
调用 release_control{monitor} 监控项目 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，通知用户
审查不通过	修复→重审，最多 9 轮
Continuation 耗尽	Pause，用户介入
子 agent 错误	自动重试 3 次 → 跳过 2 次 → Pause

Goal 状态管理

Flow 状态通过 goal tool 管理：

goal({op:"create", objective, completion_criterion}) — 开始 flow
goal({op:"get"}) — 查看当前 flow 状态
goal({op:"pause"}) — 暂停 flow
goal({op:"resume"}) — 恢复 flow
goal({op:"cancel"}) — 取消 flow
goal({op:"complete"}) — 完成 flow（需 goal-verify 子 agent 调用）

只有 @goal-verify 子 agent 可以调用 goal({op:"complete"})，主 agent 和其他子 agent 调用会被 BLOCKED。

最佳实践

什么时候用手动模式

需求还不明确，需要多轮访谈
需要精细控制每一步的产出
部分阶段需要人工参与（如设计评审）

什么时候用自动模式

需求已清晰确认
标准功能开发
希望最大化效率

文档规范

PRD → docs/prd/
ADR → docs/adr/
技术方案 → docs/dev/specs/
任务定义 → docs/dev/tasks/
开发文档 → docs/dev/{api,db,guides}/

分支命名

feat/<task-slug>

提交规范

使用 Conventional Commits：

feat: 新增用户注册接口
fix: 修复登录超时问题
refactor: 重构权限校验逻辑
docs: 更新 API 文档
test: 添加用户模块单元测试

版本发布

发布遵循技术栈无关的 Release 流程（详见 /release 章节）：按 Profile 的版本规则更新版本文件、创建 Release PR、人工批准后合并并打 tag，由项目自己的 GitHub Actions release workflow 完成实际发布。

使用指南 ​

两种工作模式 ​

手动模式 ​

自动模式 ​

命令详解 ​

/setup — 初始化 ​

/requirements — 需求分析 ​

/design — 技术设计 ​

/tasks — 任务拆解 ​

/code — 编码实现 ​

/review — 代码审查 ​

/release — 发布（手动阶段） ​

自动编排（@dev-lifecycle） ​

启动方式 ​

执行流程 ​

异常处理 ​

Goal 状态管理 ​

最佳实践 ​

什么时候用手动模式 ​

什么时候用自动模式 ​

文档规范 ​

分支命名 ​

提交规范 ​

版本发布 ​