yubao — 项目级 Claude Code 开发工作流框架

一行命令 npx yubao init 搭建项目级 Claude Code 工作流。 跨 macOS / Linux / Windows 原生支持，零外部命令依赖（除 git）。

功能

• 自动识别项目架构（Spring / Java / Next / React / Vue / Go / Python / Flutter / Rust）并加载对应规范
• 默认最大化无需授权，危险操作（git push / rm -rf / sudo / eval 等）显式黑名单
• 通过 worktree 隔离多 Agent 任务，自动检测任务范围冲突
• worktree + task 全闭环：worktree new 自动 claim → merge 成功后自动 mark done → task list/release/done 手动管理 status
• yubao test --api/--db 输出 agent-friendly 指令到 stdout，Claude agent parse 后自己调 MCP（yubao 自身不连 MCP）
• 与 superpowers skill 协同：brainstorming / TDD / debugging / verification
• 与 MCP 集成：postgres / mysql 只读、apifox API 测试

Demo

yubao init 在 Spring Boot 项目

$ cd my-spring-boot-app
$ yubao init
[yubao][INFO] yubao init starting in /home/user/my-spring-boot-app
[yubao][INFO] .git exists, skipping git init
[yubao][INFO] hook command: yubao hook session-start
[yubao][INFO] arch-detect: spring-boot
[yubao][INFO] init summary:
[yubao][INFO]   appended    .gitignore             ← 已有 .gitignore：模板缺失行追加（不覆盖）
[yubao][INFO]   created     .claude/settings.json
[yubao][INFO]   created     .claude/rules/base.md
[yubao][INFO]   created     .claude/rules/arch/java.md
[yubao][INFO]   created     .claude/CLAUDE.md       ← 项目特定规范段预填 6 项引导 + [待补]
[yubao][INFO]   created     .claude/mcp-servers/postgres-readonly/run.mjs
[yubao][INFO]   created     .claude/mcp-servers/mysql-readonly/run.mjs
[yubao][INFO]   created     .claude/mcp-servers/apifox/run.mjs
[yubao][INFO]   created     .yubao/config.json
[yubao][INFO]   created     .yubao/arch-detected.json
[yubao][INFO] yubao init complete. Run 'yubao doctor' to verify.

.gitignore 状态语义：

• created — 项目原本没有，复制模板
• appended — 项目已有，模板缺失行追加（CRLF 输入自动归一化为 LF；保留用户自定义规则）
• skipped — 项目已有且包含模板所有行
• overwritten — --force 时强制覆盖

arch-detect: spring-boot 触发 cascade 链 [java]（精简后：spring-boot 模板已删除，arch 标识保留走 java 通用规范）。

yubao doctor 自检

$ yubao doctor
[yubao][INFO] [OK] .claude/ exists
[yubao][INFO] [OK] rules/base.md exists
[yubao][INFO] [OK] arch templates present (chain: java)
[yubao][INFO] [OK] SessionStart hook registered
[yubao][INFO] [OK] permission blacklist contains critical patterns
[yubao][INFO] [OK] git installed
[yubao][INFO] [OK] arch-detected cache fresh
[yubao][INFO] [OK] no legacy bash assets
[yubao][INFO] doctor: all checks passed

加 --deep 还会真 spawn 一次 SessionStart hook 校验可执行性。

多 agent 完整闭环（worktree + task + merge）

$ yubao worktree new feat-login
[yubao][INFO] worktree created: .claude/worktrees/feat-login (branch=feat-login)
# ↑ 自动 task claim（空范围，agent 从 YUBAO_AGENT env 读）

$ yubao task claim feat-login --files "src/auth/**" --files "src/controller/LoginController.java"
[yubao][INFO] task claimed: feat-login (2 file patterns)

# ... 改代码 + commit ...

$ yubao merge feat-login
# ... 默认先跑 yubao test ...
[yubao][INFO] merging feat-login → main
Merge made by the 'ort' strategy.
[yubao][INFO] merged feat-login successfully
[yubao][INFO] task done: feat-login   # ↑ 联动：merge 成功后自动 mark done

task status 流转：in_progress (claim 时) → done (merge 后自动 / 手动 yubao task done)。

平台支持

| 平台 | 支持 | 备注 | |---|---|---| | macOS（Intel/Apple Silicon） | ✅ | 主要开发环境 | | Linux（Ubuntu/Debian/CentOS） | ✅ | — | | Windows 10/11（cmd / PowerShell / Git Bash） | ✅ | 原生支持，不需要 WSL | | WSL（Windows 10/11 子系统） | ✅ | — |

跨平台兼容特性

• CRLF 归一化：Windows + core.autocrlf=true 下，.gitignore / CLAUDE.md 行尾自动归一化为 LF；yubao-generated marker hash 不被 CRLF 干扰
• BOM 剥离：Visual Studio / Notepad 默认写出的 UTF-8 BOM 自动剥除
• 路径空格兼容：hook command 路径用双引号包裹（node "<abs>" hook session-start）
• 符号链接防护：NTFS junction 死循环跳过；scanSources maxDepth=20
• Windows 文件占用重试：atomicWrite renameSync 3 次重试（50ms 间隔）+ fsync，给 AV 扫描让出窗口
• git 探测友好：git 不在 PATH 时 WARN 而非静默吞错；timeout 5s 防 AV 慢启动卡死
• shell 提示分流：旧 bash 资产清理提示按 platform 分流（Windows 走 PowerShell Remove-Item）

快速开始

# 1. 安装
npm install -g yubao
# 或临时使用
npx yubao@latest init

# 2. 在项目根初始化（首次非 TTY 初始化必须显式传 --host）
cd /path/to/your/project
yubao init --host=claude-code   # Claude Code 用户
yubao init --host=codex         # OpenAI Codex CLI 用户

# 3. 在 Claude Code / Codex CLI 中启动新会话
# SessionStart hook 会自动加载项目级规范

Host 适配（v0.1.5 新增）

yubao 支持两个 host CLI：

| Host | 命令 | 项目配置目录 | 项目规则文件 | 项目配置格式 | |---|---|---|---|---| | claude-code（默认） | claude | .claude/ | .claude/CLAUDE.md | .claude/settings.json（JSON） | | codex | codex | .codex/ | .codex/AGENTS.md | .codex/config.toml（TOML） |

init 时选择 host：

# TTY 下：yubao init 会询问
yubao init

# CI / 管道：首次初始化必须显式传 --host；已初始化项目会复用 .yubao/config.json.host
yubao init --host=claude-code
yubao init --host=codex

# 切 host（保留旧 host 产物）
yubao init --host=codex --switch-host

未传 --host 时，若 .yubao/config.json 里已有 host 字段，init 会直接复用；若项目还未初始化且当前不是 TTY，会报错要求显式传 --host。切 host 后 .claude/ 和 .codex/ 两个目录共存；worktree / task / merge 等命令按 host 字段走对应路径。详见 CHANGELOG.md v0.1.5 段。

Codex 用户注意

Codex 用户的 yubao init 产物：

project/
├── .codex/
│   ├── config.toml       ← TOML 格式；含 SessionStart / Stop hook + mcp_servers + permissions
│   ├── AGENTS.md          ← 项目规则文件（与 .claude/CLAUDE.md 同源）
│   ├── rules/             ← base.md / yubao.md / arch/<id>.md
│   ├── hooks/             ← check-coordination.mjs（与 Claude Code 协议子集兼容）
│   └── mcp-servers/       ← postgres-readonly / mysql-readonly / apifox
├── .yubao/                ← host 无感（两个 host 共享）
│   ├── config.json        ← 含 host 字段
│   ├── execution.json     ← execution 配置（独立文件）
│   ├── tasks/             ← 多 agent 任务声明
│   └── arch-detected.json

注意：@iarna/toml TOML schema 字段以 codex 官方文档为准；v0.1.5 初版 [permissions] 段可能在校准。

命令

| 命令 | 作用 | |---|---| | yubao init | 初始化项目（git init、写规则、装 hooks、注册 MCP、设 permission） | | yubao arch-detect | 推断项目架构 ID | | yubao load-context | 手动输出项目级规范 | | yubao worktree new <branch> | 在 <hostConfigDir>/worktrees/<branch>/ 创建 worktree（claude-code: .claude/；codex: .codex/） | | yubao worktree list | 列出所有 worktree | | yubao worktree remove <branch> [--force] | 删除 worktree（非 TTY 必传 --force，防 CI 误删） | | yubao task claim <branch> --files "<glob>" | 声明任务范围 | | yubao task check <branch> --files "<glob>" | 检查任务冲突（有冲突退 2） | | yubao task list | 列出所有 claim（含 status） | | yubao task done <branch> | 标记任务完成（status=done，幂等；merge 成功后自动调） | | yubao task release <branch> | 放弃任务，删除 claim 文件（不留痕） | | yubao test [--unit\|--integration\|--e2e\|--api\|--db\|--all] [--skip-unit] | 跑测试；默认跑 unit / integration / api / db，--all 额外包含 e2e，--skip-unit 可跳过 unit（--api/--db 输出 JSON 指令到 stdout 供 host agent 调 MCP） | | yubao merge <branch> [--no-test] | 合并 worktree（成功后自动 mark task done） | | yubao doctor [--deep] | 自检（--deep 真跑 SessionStart hook 校验可执行性） | | yubao config <key> [value] | 读 / 写 .yubao/config.json 字段（支持 dot 路径，如 apifox.collection_id） | | yubao execution get | 查看当前 .yubao/execution.json 配置（mode / 阈值 / skillMap） | | yubao execution set --mode <subagent\|inline\|auto> [--max-files N] [--max-tasks N] [--decided-by <by>] | 写 execution 配置（init / 脚本化用） | | yubao execution switch --mode <subagent\|inline\|auto> | 运行期调档（强制 decidedBy=switch，audit 留痕） | | yubao init --host=<claude-code\|codex> [--switch-host] | v0.1.5 新增：指定 host；切 host 时 --switch-host 强制确认 | | yubao arch-detect --host=<host> | v0.1.5 新增：可显式传 host（不传时读 .yubao/config.json.host） |

从 v0.1.0-bash 升级到 v0.1.0-ts

版本号说明：Bash 版与 TS 版首版都用 0.1.0；二者用 git tag 区分（v0.1.0-bash / v0.1.0-ts），npm 上用 dist-tag（bash / latest）。

1. npm install -g yubao（本设计完成后才会发布；当前阶段此步骤不可用）
2. rm -rf .claude/yubao .claude/yubao-lib （旧 Bash 副本）
3. yubao init 重新生成 .claude/ 模板（覆盖式）
4. yubao doctor 自检
5. （可选）rm -rf yubao-tests/ （旧 bash 测试）

从 v0.1.x 升级到 v0.1.5

v0.1.5 主要变化：

1. yubao.execution 配置独立：从 .claude/settings.json.yubao.execution 迁到 .yubao/execution.json（host 无感）。init 时自动迁移，旧字段被删除
2. host 显式选择：首次 init 在 CI / 非 TTY 中必须传 --host=claude-code|codex；TTY 下首次 init 询问；已初始化项目会复用 .yubao/config.json.host
3. Codex 适配：可选 --host=codex，产物在 .codex/（config.toml + AGENTS.md）

升级步骤：

# 1. 升级 yubao
npm install -g [email protected]

# 2. 在项目根重新跑 init（自动迁移）
cd /path/to/your/project
yubao init --host=claude-code    # 现有 claude-code 用户
# 或 yubao init --host=codex --switch-host  # 切到 codex

# 3. 验证
yubao execution get             # 应输出 mode / decidedAt / etc
yubao doctor                    # 应提示 "two host configs coexist"（如切过 host）

--force 模式（yubao init --force）会强制覆盖所有用户改过的文件，谨慎使用。

隐藏命令

yubao hook <event> 是专供 Claude Code hook 触发器调用的内部命令，不出现在 yubao --help 里（避免 --help 噪音），但实际可执行。

| Event | 触发时机 | 行为 | |---|---|---| | session-start | Claude Code 启动新会话 | 跑 arch-detect + load-context，输出项目级规范到 stdout（自动注入 Claude 上下文） | | pre-compact | Claude Code 上下文压缩前 | 同 session-start（重注入以防压缩丢规范） |

调用方式：自动通过 .claude/settings.json 的 SessionStart hook 触发，用户不应手动跑。手动跑示例：

# 在项目根手动跑（验证 hook 工作正常）
CLAUDE_PROJECT_DIR=$(pwd) yubao hook session-start

未支持的 event 会 die：

$ yubao hook foo
[yubao][ERROR] unknown hook event: foo

与 superpowers 协同

启动新会话收到需求时，Claude 会自动调 superpowers:brainstorming 对齐。

| 场景 | 调用的 skill | 然后跑 | |---|---|---| | 收到新需求 | superpowers:brainstorming | yubao worktree new <branch> | | 写代码 | superpowers:test-driven-development | yubao test | | 遇 bug | superpowers:systematic-debugging | — | | 完成前 | superpowers:verification-before-completion | yubao merge |

worktree 职责划分（避免与 superpowers:using-git-worktrees 撞车）：

| 维度 | yubao 负责 | superpowers 负责 | |---|---|---| | 物理动作 | yubao worktree new <branch>（创建 .claude/worktrees/<branch>） | — | | 思考方法 | — | superpowers:using-git-worktrees（教 agent 怎么用 worktree 隔离开发） |

协同汇报义务（硬约束，Stop hook 守门）：

# 调完 superpowers:test-driven-development 后必须：
yubao skill invoked superpowers:test-driven-development <branch>

缺汇报 → Stop hook reject stop，agent 强制继续工作。不靠 LLM 自觉，靠 Claude Code host 强制执行。详见项目级 CLAUDE.md 的"协同汇报义务"段。

项目执行约定

• Plan 完成后默认 Subagent-Driven（直接派 subagent，不询问）
• 例外：单文件改动 → 自动转 Inline Execution
• 此约定由项目级 .claude/CLAUDE.md 或 .codex/AGENTS.md 持久化
• worktree new 成功后 yubao 根据 .yubao/execution.json 自动追加第 2 行 trigger（subagent-driven-development 或 executing-plans），mode = auto 时按 --files glob 展开后的文件数决定

配置

.yubao/config.json 关键字段：

{
  "arch": "spring-boot",
  "apifox": { "collection_id": "<your apifox collection id>" },
  "test": {
    "integration_cmd": "mvn verify -Pintegration",
    "e2e_cmd": "npx playwright test",
    "run_e2e_on_merge": false
  },
  "db": { "readonly_url": "postgresql://readonly:..." }
}

当前 merge 默认前置测试会跑 unit / integration / api / db；e2e 默认不随 merge 自动执行，显式 yubao test --all 时会包含 e2e。

MCP 环境变量

• YUBAO_DB_URL：postgres / mysql 只读连接串
• APIFOX_ACCESS_TOKEN：apifox 访问 token
• APIFOX_PROJECT_ID / APIFOX_COLLECTION_ID：apifox 项目/集合

故障排查

跑 yubao doctor 自检。常见问题：

• SessionStart hook 不生效：检查 .claude/settings.json 的 hooks.SessionStart 是否存在
• MCP 启动失败：检查 YUBAO_DB_URL / APIFOX_* 环境变量
• worktree 创建失败：检查 .git/ 存在、.claude/worktrees/ 目录可写
• Node 版本 < 18：yubao 强依赖 Node 18+（node --version 检查）

开发（贡献 yubao 本身）

npm install
npm test          # lint + typecheck + unit + integration + e2e + build

Roadmap

后续 backlog 按 ROI 排序见 ROADMAP.md。P1 优先 = 真实使用暴露的问题。

许可

MIT