快速开始

本页把安装、初始化、基础配置和 10 分钟上手流程放在一起。按顺序完成后，你就能在一个项目里跑完 OpenFlow 的主工作流。

前置条件

• 已安装 OpenCode。
• 有一个项目目录。OpenFlow 对已有项目尤其有价值。

安装

在项目或全局环境中安装 OpenFlow：

npm install @fastknife/openflow

然后在 OpenCode 配置中注册插件。通常是 ~/.config/opencode/opencode.json 或 opencode.jsonc：

{
  "plugin": ["@fastknife/openflow"]
}

如果已经有其他插件，请把 @fastknife/openflow 追加到已有 plugin 数组，不要覆盖原配置。

让 AI 帮你安装

如果你正在使用 Claude Code、Cursor、Trae 等 AI Agent，直接把下面这段话粘贴给 Agent，它会自动完成安装和配置：

请帮我安装和配置 OpenFlow 插件：

1. 在当前项目中运行 npm install @fastknife/openflow
2. 在 opencode 配置文件（~/.config/opencode/opencode.json 或项目根目录的 opencode.jsonc）中，将 @fastknife/openflow 添加到 plugin 数组。如果配置文件不存在，请创建它。
3. 完成后告诉我安装结果

安装完成后，打开 OpenCode 并运行 /openflow-init 初始化项目。也可以在终端中直接执行：

opencode run --command "/openflow-init"

初始化项目

在 OpenCode 中进入目标项目，运行：

/openflow-init

它会在项目根目录写入或更新 AGENTS.md，把 OpenFlow 的文档目录约定、工作流入口和 AI 行为要求注入项目。之后 AI 进入这个项目时，会知道如何读取 current、changes、decisions 和 archive。

配置

OpenFlow 开箱即用，大多数项目不需要配置。需要自定义时，配置源按以下优先级生效：

1. 项目根目录的 openflow.json
2. 项目根目录的 openflow.jsonc
3. opencode.json 顶层的 openflow 字段

第一个找到的配置源生效，不会跨配置源深度合并。推荐优先使用项目根目录的 openflow.json，因为它更容易随项目版本化和审查。

常见场景配置

关闭自动触发，始终手动进入 Feature 工作流：

{
  "feature": {
    "trigger_mode": "always"
  }
}

自定义归档目录：

{
  "paths": {
    "archive": "docs/history"
  }
}

只运行 lint 和 test：

{
  "verification": {
    "quality": ["lint", "test"]
  }
}

关闭漂移检测自动修复：

{
  "guardian": {
    "auto_fix": false
  }
}

配置速查表

想要什么	配置
关闭 Feature 工作流	feature.enabled: false
始终手动触发	feature.trigger_mode: "always"
使用智能触发	feature.trigger_mode: "smart"
关闭 TDD 注入	tdd.enabled: false
只跑 lint 和 test	verification.quality: ["lint", "test"]
关闭归档能力	archive.enabled: false
关闭漂移检测	guardian.enabled: false
关闭漂移自动修复	guardian.auto_fix: false

10 分钟上手流程

下面用“添加用户资料页”作为例子。你可以替换成自己的任务。

第 1 步：初始化

/openflow-init

确认项目已经拥有 AGENTS.md，AI 能读取 OpenFlow 工作流约定。

第 2 步：brainstorm

我们先 brainstorm，不要写代码。我想给应用加一个用户个人资料页面。

这一步用于低成本澄清需求、比较方案和控制范围。如果你已经非常确定要做什么，可以跳过。

第 3 步：创建 Feature

/openflow-feature add user profile page

OpenFlow 会收集必要事实，读取当前约束，并生成本轮变更的设计与行为文档。通常会落在 docs/changes/YYYY-MM-DD-user-profile-page/。

第 4 步：生成 writing-plan

/openflow-writing-plan user profile page

这一步把设计转成可执行计划，包括任务顺序、涉及文件、验证命令和必要的约束提示。计划生成后会停下来，等待实施。

第 5 步：implement

/openflow-implement user profile page

OpenFlow 会创建实施记录，并根据环境选择 omo 或 OpenCode 原生执行。AI 应在设计边界内完成代码和测试变更。

第 6 步：质量门

实施完成后，AI 必须调用 openflow-quality-gate。你通常不需要手动触发，但需要关注它的输出。

质量门会检查适用性、风险、证据、验证命令和就绪状态。只有通过或允许补文档后通过的结果，才适合继续归档。

第 7 步：处理结果

• 通过：可以归档。
• 需要补文档：先补齐需要提升的文档，再归档。
• 未通过：回到实现或验证，修复问题。
• 需要人工决策：需要人工做取舍，不能让 AI 自行跳过。

第 8 步：archive

/openflow-archive user profile page

归档会冻结变更历史、提升长期事实到 docs/current/，并生成 implementation-mapper.md。这一步之后，变更才真正进入 OpenFlow 意义上的完成状态。

完整链路如下：

初始化 → 头脑风暴 → 需求 → 开发计划 → 实施 → 质量门 → 归档

常用场景速查

中途改需求

/openflow-change user profile page "把头像改成方形裁剪"

用于在不丢失已有上下文的情况下调整范围和设计。

查看状态

/openflow-status

查看当前活跃 feature/change 的状态。

查看配置

/openflow-config

用于检查当前生效配置，或让 AI 帮你解释配置来源。

迁移已有文档

/openflow-migrate-docs

把已有文档迁移到 OpenFlow 的 current / changes / archive 结构中。

查看命令参考

完整命令列表见：命令参考。

下一步

• 核心概念 →
• 与竞品对比 →
• 命令参考 →