bwflow

蓝图驱动的结构化 AI 开发伴侣

bwflow 是一个 Blueprint Workflow CLI 工具，它将蓝图优先的理解心智与结构化工作流深度融合，帮助 AI 在更短上下文中理解项目，并在任务结束后保持理解可信。

核心能力

bwflow 围绕三个原语组织：

1. init — 为项目初始化蓝图层和工作流结构
2. explore — 蓝图优先探索，用最小上下文获得足够准确的项目理解
3. align — 任务结束后检查蓝图是否仍与代码对齐

加上从 Trellis 借鉴的：

4. plan — 需求分析，生成 PRD 和任务上下文
5. implement — 实现阶段，Hook 自动注入蓝图和规范上下文
6. check — 质量检查，Ralph Loop 守护直到达标
7. finish — 收尾，align 蓝图 + 记录会话 + 同步规范

快速开始

安装

npm install -g @zj669/bwflow

初始化项目

交互式初始化（推荐）

cd my-project
bw init

交互式流程将引导你完成：

• 选择 AI 平台（Claude Code、Cursor、Kiro）
• 输入开发者名称（自动从 git config 读取默认值）
• 选择 Spec 模板来源（默认模板或远程仓库）

非交互模式（CI/CD）

# 使用默认配置（Claude Code + Cursor）
bw init -y

# 指定开发者名称
bw init -y -u your-name

# 使用远程模板
bw init -y --registry gh:zj669/bwflow-specs

# 强制覆盖已存在的配置
bw init -y -f

远程模板

支持从 Git 仓库下载 Spec 模板：

# GitHub 简写
bw init --registry gh:org/repo

# GitHub 子目录
bw init --registry gh:org/repo/templates/backend

# GitLab
bw init --registry gitlab:org/repo

# 完整 URL
bw init --registry https://github.com/org/repo

设计原则

1. 蓝图优先：优先读取意图层，而不是先散搜实现层
2. 最小上下文：蓝图足够时,不扩读实现细节
3. 结束对齐：每次任务结束都应考虑蓝图是否仍然可信
4. 自我学习：从失败中沉淀经验，形成可复用的 Evolved Skills

CLI 参数说明

init 命令

bw init [options]

选项：

• -u, --user <name> - 开发者名称（交互模式下可跳过）
• -y, --yes - 跳过所有交互式提示，使用默认值
• -f, --force - 强制覆盖已存在的配置文件
• --registry <url> - 远程 Spec 模板 URL（支持 gh:、gitlab: 简写）
• -t, --type <type> - ⚠️ 已废弃，请使用交互式多选

示例：

# 交互式初始化
bw init

# 非交互模式，使用默认配置
bw init -y

# 指定开发者名称和远程模板
bw init -u "张三" --registry gh:myorg/specs

# CI/CD 场景：非交互 + 强制覆盖
bw init -y -f --registry gh:myorg/specs

常见问题（FAQ）

Q: 如何选择多个 AI 平台？

A: 在交互模式下，使用空格键选择/取消选择平台，回车确认。非交互模式默认选择 Claude Code 和 Cursor。

Q: 远程模板下载失败怎么办？

A: bwflow 会自动回退到默认模板，确保初始化流程不中断。检查网络连接或使用 -y 跳过远程模板。

Q: 如何在 CI/CD 中使用？

A: 使用 -y 参数启用非交互模式：

bw init -y --registry gh:myorg/specs

如果命令失败，会返回非零退出码，便于 CI/CD 管道检测错误。

Q: 初始化后如何验证配置？

A: bwflow 会自动验证以下内容：

• .bwflow/config.yaml 配置文件
• .bwflow/blueprint 蓝图目录
• .bwflow/scripts 脚本目录
• 选中平台的配置目录（.claude、.cursor、.kiro）

验证失败会显示详细的错误信息。

Q: 可以同时配置多个平台吗？

A: 可以。所有平台共享同一个 .bwflow 核心目录，你可以在不同 AI 工具间无缝切换。

Q: 如何更新已有的配置？

A: 使用 -f 参数强制覆盖：

bw init -f

或在交互模式下选择"覆盖所有文件"策略。

License

MIT