Skip to content

README.zh-CN.md

Latest commit

 

History

History
379 lines (279 loc) · 13.9 KB

README.zh-CN.md

File metadata and controls

379 lines (279 loc) · 13.9 KB
Raw

boss-skill

npm version CodeRabbit Pull Request Reviews Boss trust badge

English README

boss-skill 宣传图

Boss 是面向 Coding Agent 的可审计 Agent 团队工作流。 它把一个 Coding Agent 组织成结构化研发团队：PM、Architect、UI Designer、Tech Lead、Scrum Master、Frontend、Backend、QA、DevOps。和只靠 prompt 的 Agent 团队不同，Boss 提供 runtime 状态、追加式事件流、质量门禁、确定性 eval、hooks，以及可回放的产物目录。

Boss 支持 Claude Code、Codex、OpenClaw、Antigravity 和 Hermes。

为什么需要 Boss

只靠 prompt 的编排经常“看起来很像团队”，但很难证明计划真的被执行、测试真的跑过、门禁真的通过、状态不是 Agent 自己编出来的。Boss 的核心是证据：

  • 事件溯源 runtime：流水线状态追加到 .boss/<feature>/.meta/events.jsonl，再投影成只读执行状态。
  • 不可绕过门禁：QA、部署、最终检查都作为 runtime 阶段建模，不只是口头约束。
  • 可回放产物：PRD、架构、任务、QA、部署报告和总结都落在 .boss/<feature>/。
  • 确定性 eval：可以用已捕获 transcript 做评分，不需要真实 LLM。
  • Agent 友好的 CLI：支持 JSON 输出、--describe、dry run、字段裁剪和结构化错误。

可以只用一个角色，也可以跑完整团队

Boss 不是一个巨大的单体命令。你可以在已有项目里只调用一个角色，也可以从想法一路跑到交付。

命令 做什么 适合什么时候用
/boss 完整 4 阶段流水线 从想法做到可交付
/boss:plan PM + Architect 规划 先要 PRD 和架构，再决定是否实现
/boss:review Tech Lead 评审 只读审查代码、PR 或设计
/boss:qa QA + 门禁 需要可验证测试证据
/boss:ship DevOps 构建与部署检查 准备发布，需要交付记录
/boss:extend 自定义 Agent、Pack 或 Gate 为自己的团队扩展 Boss
/boss:upgrade 升级 Boss Skill 并重新安装 hooks 需要最新 npm 包和 hook 配置

什么时候适合用

适合 不适合
新 feature，需要需求、设计、开发、测试和交付证据 一行修复、很小的局部修改
API、全栈、UI、中等规模产品功能 单纯读代码或解释实现
需要 .boss/<feature>/ 产物留痕 已有完整 spec，只想快速 patch
团队希望有可重复门禁和审计轨迹 不需要协作或评审证据的小任务

经验法则：如果你不需要一个可追踪的 .boss/ 目录，就不一定要开完整 /boss 流水线。可以只用单个角色，或者直接让 Coding Agent 修改。

没有 CLI 也能用

Boss 会在运行时检测 boss CLI。没有 CLI 时，工作流可以降级成 .boss/<feature>/ 下的 Markdown 产物，而不是事件流。CLI 是“可审计能力升级”：事件溯源、可回放恢复、确定性 eval、runtime 门禁和结构化诊断都依赖它。

Boss 不等于“安装后 100% 自动交付”。它提供 runtime 工作流和证据门禁；当前 Coding Agent 仍然需要遵守 Boss 协议。

5 分钟快速上手

1. 安装

npm install -g @blade-ai/boss-skill
boss-skill

boss-skill 会自动检测支持的 Agent，并尽量把 Boss skill bundle 安装到对应位置。

Claude Code plugin 模式：

claude --plugin-dir "$(boss-skill path)"

2. 跑一条轻量流水线

在 Coding Agent 里输入：

/boss 做一个个人本地 Todo 应用 --roles core --skip-deploy
  • --roles core 只启用 PM、Architect、Dev、QA。
  • --skip-deploy 跑到开发与测试证据后停止，不做部署。

3. 查看结果

boss status todo-app --json
boss runtime inspect-pipeline todo-app

预期产物结构：

.boss/todo-app/
├── design-brief.md
├── prd.md
├── architecture.md
├── tasks.md
├── qa-report.md
└── .meta/
    ├── events.jsonl
    ├── execution.json
    └── workflow-plan.json

安装细节

npm install -g @blade-ai/boss-skill
boss-skill install

常用安装命令：

boss-skill install --dry-run
boss-skill uninstall
boss-skill path
boss-skill --version

自动检测目标：

Agent 检测条件 安装方式
OpenClaw ~/.openclaw/ 复制到 ~/.openclaw/skills/boss/ 并注入 metadata
Codex ~/.codex/ 复制到 ~/.codex/skills/boss/、注入 metadata、合并 hooks
Antigravity ~/.gemini/antigravity/ 复制到 Antigravity skills 目录并注入 metadata
Hermes ~/.hermes/ 复制到 ~/.hermes/skills/boss/ 并注入 metadata
Claude Code 始终可用 通过 --plugin-dir 使用 Plugin 模式

使用命令

常见 slash command：

/boss 做一个 Todo 应用
/boss 给现有项目加用户认证 --skip-ui
/boss 快速搭建 API 服务 --skip-deploy --quick
/boss 继续上次中断的任务 --continue-from 3
/boss 轻量模式 --roles core --hitl-level off
/boss:upgrade

常用参数：

参数 含义
--roles <preset> full 为 9 个角色完整流水线，core 为 PM/Architect/Dev/QA
--skip-ui 跳过 UI 设计
--skip-deploy 跳过部署
--quick 跳过确认节点和需求澄清
--template 初始化 .boss/templates/ 并暂停
--continue-from <1-4> 从指定流水线阶段继续
--hitl-level <level> 人机协作模式：auto、interactive、off

Boss CLI 常用命令：

boss --help
boss status FEATURE
boss continue FEATURE
boss gate FEATURE
boss qa attack FEATURE
boss project init FEATURE
boss design preview FEATURE
boss packs detect
boss runtime inspect-pipeline FEATURE
boss runtime generate-summary FEATURE

面向 Agent 的 boss 命令在适用场景下使用这些通用参数（where applicable）；可用 --describe 查看单个命令的精确 JSON schema：

  • --json：结构化输出；non-TTY stdout defaults to JSON
  • --describe：JSON command schema
  • --dry-run：对写入或高风险操作输出 structured action plan
  • --json-input=<json|->：JSON input payload
  • --fields=<a,b> 和 --limit=<n>：限制输出字段和数量
  • --yes：仅用于高风险 non-interactive 命令的额外确认

Structured errors 会写到 stderr，格式为 {"error":{...}}，包含 code、message、input、retryable 和 suggestion。

工作流

Boss 使用 4 阶段工作流：

用户需求
  -> 需求澄清
  -> 阶段 1：PM、Architect、UI Designer
  -> 阶段 2：Tech Lead、Scrum Master
  -> 阶段 3：Frontend、Backend、QA、门禁
  -> 阶段 4：DevOps、部署检查、总结

完整角色：

角色 职责
PM 需求穿透、PRD、隐性需求、边界场景
Architect 系统架构、技术设计、API
UI Designer UI/UX 规范和可渲染设计 JSON
Tech Lead 技术评审、风险评估
Scrum Master 任务拆解和验收标准
Frontend UI 实现和前端测试
Backend API、存储、后端测试
QA 测试执行、Bug 报告、验证证据
DevOps 构建、部署、健康检查

Runtime 与质量门禁

Boss 的质量保障分两层：

  • 硬约束：由代码和 CI 验证，包括 runtime 事件、受保护的 execution.json、hooks、安装矩阵测试、harness 场景和 Vitest 覆盖。
  • Agent 协议约束：由 skill bundle 引导，包括 DAG 派发、渐进式读取 reference、测试证据和门禁纪律。

内置门禁：

门禁 时机 检查
Gate 0 开发后、QA 前 TypeScript、lint、基础编译检查
Gate 1 QA 后、部署前 测试证据、无 P0/P1 Bug、E2E 期望
Gate 2 Web 部署前 适用时检查 Lighthouse 和 API 延迟目标

Hook 环境变量：

变量 值
BOSS_HOOK_PROFILE minimal、standard、strict
BOSS_DISABLED_HOOKS 逗号分隔的 hook ID

Runtime 状态由 .boss/<feature>/.meta/workflow-plan.json 和 .boss/<feature>/.meta/execution.json 支撑。Workflow 定义会记录 workflowHash、packHash 和 artifact DAG hashes。恢复执行使用 boss runtime resume <feature> --from-run <run-id> 重新加载 plan、比较 node inputs，并物化 execution.workflow.nextNodeIds 作为下一批可调度节点。GateEvaluated / WaveVerified 事件会在门禁和 evidence wave 完成时更新 workflow node 状态。

安全敏感面

Boss 会尽量保持发布用 plugin manifest 精简：只声明 bundled skills；没有实际 companion 文件时，不声明 MCP server、app manifest 或 assets。Codex hooks 由 boss-skill install 安装流程处理，不放在 marketplace manifest 里。

npm 包会排除本地开发用 Agent 配置，例如 .claude/settings.json 和 .claude/settings.local.json。可发布的 plugin metadata 只放在 .claude-plugin/、.codex-plugin/ 和 .agents/plugins/marketplace.json。

发布 provenance 位于 .agents/plugins/provenance.json。它记录仓库 HTTPS URL、不可变 source commit SHA、publisher 身份，以及 plugin manifests 和安全敏感组件的 SHA-256 摘要。可用下面命令校验：

npm run provenance:verify

Publisher verification 属于外部平台操作，不在包内完成。HOL registry 可用仓库 owner 的 GitHub 账号在 https://hol.org/guard/plugins 认领插件。公开 trust card 地址是 https://hol.org/registry/plugins/echovic%2Fboss/embed。

发布或安装前应重点关注这些敏感行为：

  • boss-skill install 可能写入 Agent 配置目录，例如 ~/.codex/skills/boss/，并把 Boss 管理的 hook 条目合并到 ~/.codex/hooks.json。
  • Hook 条目会执行 boss hooks run ...，再调度 scripts/hooks/ 下的脚本。
  • .boss/plugins/<name>/plugin.json 下的 runtime 插件可以注册 gate 或 reporter hooks；启用项目前应审查本地插件。
  • 在敏感环境里，可用 BOSS_HOOK_PROFILE=minimal 或 BOSS_DISABLED_HOOKS=<ids> 降低 hook 行为。

流水线产物

.boss/<feature>/
├── design-brief.md
├── prd.md
├── architecture.md
├── ui-spec.md
├── ui-design.json
├── tech-review.md
├── tasks.md
├── qa-report.md
├── deploy-report.md
├── summary-report.md
└── .meta/
    ├── events.jsonl
    ├── execution.json
    └── workflow-plan.json

在交互环境中可以预览生成的 UI 设计：

boss design preview <feature>

Evals

Boss eval 使用已捕获 fixture 评分，不启动真实 LLM：

npm run evals
npm run evals:release

release eval 包含 release-evidence 和 pipeline-compliance 检查。它会验证 runtime command 使用、artifact 记录、避免直接修改 execution.json，以及 workflow 调度字段。

详见 test/evals/README.md。

开发

环境要求：

  • Node.js >= 20
  • jq，供 shell 测试辅助脚本使用

初始化：

git clone https://github.com/echoVic/boss-skill.git
cd boss-skill
npm install
npm run build
npm run typecheck
npm test

常用脚本：

npm run build
npm run typecheck
npm test
npm run test:skills
npm run test:harness
npm run test:install-matrix
npm run evals

仓库结构

boss-skill/
├── packages/boss-cli/          # TypeScript CLI 和 runtime
├── skill/                      # 安装到 Coding Agent 的 skill bundle
├── scripts/hooks/              # Node.js hook 脚本
├── scripts/lib/                # Hook 辅助函数
├── test/                       # Vitest、harness、eval、hook、install 测试
├── docs/superpowers/           # 历史 specs、plans、reports
├── examples/                   # 示例项目
├── .claude-plugin/             # Claude Code plugin manifest
├── .codex-plugin/              # Codex plugin manifest
└── package.json

关键源码位置：

  • packages/boss-cli/src/ 是 CLI 和 runtime 的 TypeScript 源码。
  • packages/boss-cli/dist/ 是发布到 npm bin 的生成产物，不要手工修改。
  • packages/boss-cli/assets/ 保存内置 DAG、pipeline packs、plugin schema 和插件。
  • skill/SKILL.md 是面向 Agent 的主编排入口。
  • skill/agents/ 保存角色 prompts。
  • skill/commands/ 保存 slash commands。
  • skill/templates/ 保存产物模板。

发布

使用发布脚本保持 package metadata、skill manifest、plugin manifest 的版本一致：

npm run release -- patch
npm run release -- minor
npm run release -- major
npm run release -- 3.11.0
npm run release -- 3.11.0 --dry-run
npm run release -- 3.11.0 --no-publish

发布脚本会检查工作区干净、运行测试、同步版本、验证一致性、创建 commit 和 tag；除非使用 --no-publish，否则会发布到 npm。

详见 CONTRIBUTING.md。

设计理念

Boss 受 BMAD（Breakthrough Method of Agile AI-Driven Development）启发，并把它落成面向 Agent 软件工程的可审计 runtime。

更多背景见 DESIGN.md 和 skill/references/bmad-methodology.md。

Star History

Star History Chart

License

MIT