Skip to content

配置指南 ​

本文档详细说明 opencode-cabbage 的所有配置选项。

安装配置 ​

基础安装 ​

bash
opencode plugin add @devcxl/opencode-cabbage

等价于在全局 opencode.json 中手动写入:

json
{
  "plugins": ["@devcxl/opencode-cabbage"]
}

自定义覆盖 ​

插件启动后会自动注入 slash command、skills 和 agents。你可以通过 opencode.json 覆盖任何注入项:

json
{
  "plugins": ["@devcxl/opencode-cabbage"],
  "commands": {
    "my-custom-requirements": {
      "template": "自定义需求分析模板...",
      "description": "自定义需求命令"
    }
  },
  "agents": {
    "architect": {
      "description": "自定义架构师",
      "mode": "subagent",
      "color": "#ff5722",
      "system": "自定义 prompt..."
    }
  },
  "skills": ["./my-custom-skills"]
}

插件不会覆盖用户已存在的同名 agent(缺位才注册)。command 注册在 OpenCode V2 中为 transform 式(无同名跳过能力),自定义同名命令可能被插件注册覆盖——建议使用不同名称。

插件自动注入的配置 ​

7 个 Slash Command(/flow-* 前缀避让 OpenCode 内置命令) ​

命令触发 agent说明
/flow-setup—初始化:探测环境、确认 Project Profile
/flow-requirements—需求访谈 → PRD → Parent Issue
/flow-design@architect系统规格 + 必要 ADR → 设计 PR
/flow-tasks@architect垂直切片拆解 → GitHub Sub Issues
/flow-code@developerTask 编码 + TDD → PR
/flow-review@reviewer双轴审查 → 合并(OpenCode 原生 /review 保留给日常快速看 diff)
/flow-release—版本提议 → Release PR → tag push → workflow 监控

每个 command 对应一个 flow-* skill,定义在 assets/skills/ 目录中;阶段契约(阶段顺序、完成权威、门禁规则)内嵌在 assets/agents/dev-lifecycle.md 的《阶段契约》章节。

6 个 Agent ​

Agent模式角色
@dev-lifecycleprimary全流程编排器,自动串联各阶段(全权执行 git/gh)
@architectsubagent架构设计、技术方案、DAG 拆解(只写 docs/assets)
@developersubagent技术栈无关代码 TDD 实现(worktree 内开发,不 push)
@reviewersubagent只读代码审查,输出结构化报告
@researchersubagent独立调研与事实核查(产出带引用的调研文档)
@goal-verifysubagent独立验证 Flow 完成状态(唯一可 complete goal)

12 个 Flow Skills ​

Skill对应命令用途
flow-setup/setup环境初始化 + Profile 确认 + 存量文档接入(adopt)
flow-requirements/requirements需求分析
flow-design/design技术设计 + ADR/RFC 内容标准
flow-tasks/tasks任务拆解
flow-code/code编码实现
flow-tdd—TDD 协议唯一来源(advisory,self-report)
flow-review/review代码审查
flow-release/release发布
flow-research—调研与事实核查(由 @researcher 加载)
flow-change—变更记录:tasks + 专项文档 → 验证/门禁/归档(内置 Cabbage 引擎)
flow-incident—事故复盘:incident → postmortem → 预防措施落地
flow-docs—当前状态文档治理:编号目录、链接、图表、站点

Skills 安装到固定目录(~/.config/opencode/cabbage/skills@<version>/,按插件版本隔离),并通过 V2 原生 skill 注册(references 相对路径随目录解析),不会污染项目目录。

变更记录工具:cabbage(纯 TypeScript,零 Python 依赖) ​

连续自主循环直接复用 OpenCode v2.3 原生 /goal 命令(/goal pause|resume|clear),插件不再提供重复的 goal 工具。 cabbage 用于可选的变更记录留痕(内置纯 TS 引擎),仅 dev-lifecycle 可调用:

op说明
init初始化 .cabbage/ 与统一 docs/ 目录(specs/adr/prd)
adopt盘点 docs/ 规范目录之外的 Markdown → .cabbage/adoption-report.md
new创建记录(type: change / incident)
status / next记录列表 / 阶段就绪与阻塞
impact声明风险标记(design/rfc/architecture/api/database/security/deployment)
verify / gate阶段验证 / 门禁(阶段 ID、merge、archive)
validate结构校验
sync / archive同步文档 / 收尾归档
tasks / discard任务清单视图 / 废弃记录

archive 不检查 Git 合并状态,须人工确认合并后执行;change.yaml 与 state.json 由引擎管理,不得手工编辑。

阶段契约 ​

7 个阶段,顺序推进(阶段契约内嵌在 assets/agents/dev-lifecycle.md):

setup → requirements → design → tasks → code → review → release(手动)
  • 阶段完成 = Parent Issue body checklist - [x] <stage>
  • requirements 完成需用户确认一次
  • 设计基线(docs + ADR)合入后才能拆解任务
  • 测试质量由仓库 CI workflow 把关,插件不重复执行

Task DAG ​

任务支持依赖关系。只有所有依赖任务已合并,当前任务才能开始:

yaml
task-1:
  dependsOn: []          # 无依赖,可先执行
task-2:
  dependsOn: [task-1]    # 依赖 task-1
task-3:
  dependsOn: [task-1]    # 依赖 task-1,可与 task-2 并行
task-4:
  dependsOn: [task-2, task-3]  # 依赖前两者都完成

DAG 依赖由编排器(dev-lifecycle)维护,按拓扑顺序分批执行。

文档目录结构 ​

docs/
├── specs/            # 系统当前规格(Living Specs + Testing Decisions)
├── prd/              # 产品需求文档
├── adr/              # 架构决策记录(不可改写历史)
├── guides/           # 使用与架构指南
├── dev/
│   ├── research/     # 调研报告
│   └── tasks/        # 历史归档记录(不再新增)
└── index.md          # 本站首页

工程状态以 GitHub Issues/PRs/Checks 为权威事实,docs/dev/tasks/ 仅保留历史任务记录;新任务只创建 GitHub Sub Issues,合并后将系统行为变化语义同步至 docs/specs/。

环境要求 ​

工具版本要求用途
Node.js>= 18运行环境
npm>= 9包管理
gh CLI>= 2.0GitHub 操作(Issues/PRs/CI/Releases)
Git>= 2.0版本控制

高级:自定义 Prompt 覆盖 ​

插件支持两级 prompt 加载:项目级 > 内置级。

在项目目录下创建 .opencode/opencode-cabbage/prompts/<name>.md 即可覆盖内置 prompt:

.opencode/
└── opencode-cabbage/
    └── prompts/
        ├── bootstrap.md      # 覆盖启动引导
        ├── PRD-FORMAT.md     # 覆盖 PRD 格式
        └── ADR-FORMAT.md     # 覆盖 ADR 格式