playbook-web v2.0.6

AI coding 工作流知识库 —— 面向 H5 项目开发的规范、技能与模板

项目介绍

playbook-web 是团队共建的 AI 编码工作流知识库，为 H5 项目开发提供统一的：

开发规则（rules）：编码、组件、API、样式、测试等规范，AI 和人工开发均须遵守
Agent 技能（skills）：可在 Claude Code 中直接调用的专项工作流，覆盖从脚手架到验收的完整链路
项目模板（templates）：随技能附带，存放于各技能目录内

playbook-web/
├── content/
│   └── claude/
│       ├── rules/      # 开发规范（14 个规范文件 + 索引）
│       └── skills/     # Agent 技能（26 个，每个独立目录）
├── src/                # CLI 源码
│   ├── claude-assets/
│   │   ├── selectors.ts      # 选择器归一化
│   │   ├── init-sync.ts      # init / sync 引擎
│   │   ├── report.ts         # status / diff 状态收集
│   │   ├── contribute.ts     # 回写引擎
│   │   ├── uninstall.ts      # 卸载引擎
│   │   └── interactive.ts    # 交互式选择 UI
│   └── commands/             # 各命令入口
├── bin/
│   └── playbook-web.js       # CLI 入口
└── package.json

CLI 命令参考

命令	说明
`playbook-web init`	首次接入，交互式选择 skills/rules 安装到 `.claude/`
`playbook-web init --yes`	跳过交互，安装全部资产
`playbook-web init --force`	覆盖已存在的本地文件
`playbook-web sync`	同步更新，新增/删除/修改的文件自动处理
`playbook-web sync --force`	强制同步，覆盖本地修改过的文件
`playbook-web add`	交互式添加本地或 playbook 资产到管理范围
`playbook-web del`	交互式从 manifest 移除资产（保留本地文件）
`playbook-web uninstall`	交互式卸载，移除选中的文件及目录
`playbook-web uninstall --yes`	跳过交互，卸载全部资产
`playbook-web status`	查看当前安装版本、受管文件数量、本地修改
`playbook-web diff`	显示本地修改了哪些规范/技能文件
`playbook-web contribute --to <path>`	将本地变更复制回 playbook-web 仓库，准备提 PR

接入与同步

安装

在目标项目根目录执行：

bash

pnpm add -D @wenext/playbook-web
pnpm playbook-web init

交互式界面会提示选择需要安装的 skills 和 rules，支持按分类分组展示。选择"全量安装"即可安装所有资产，"跳过"则跳过该类别。

如需跳过交互直接安装全部资产：

bash

pnpm playbook-web init --yes

如需覆盖已存在的本地文件：

bash

pnpm playbook-web init --force

增量管理

已初始化的项目可通过 add / del 增量管理资产：

bash

# 添加新的 skill 或 rule 到管理范围
pnpm playbook-web add

# 从管理范围移除（不删除本地文件）
pnpm playbook-web del

升级

bash

pnpm update @wenext/playbook-web
pnpm playbook-web sync

卸载

bash

pnpm playbook-web uninstall
pnpm remove @wenext/playbook-web

交互式界面会提示选择需要卸载的 skills 和 rules，--yes 可跳过交互卸载全部。

CI/CD

在 CI 流程中，pnpm install 之后执行同步：

yaml

- run: pnpm install
- run: pnpm playbook-web sync

在目标项目中的效果

init 执行后，目标项目结构如下：

.claude/
├── rules/                      # 开发规范文件
└── skills/                     # Agent 技能目录
    ├── domains/
    │   ├── games/
    │   └── vue-optimize/
    └── engineering/
        └── review/

使用方式

调用技能

在 Claude Code 对话框中输入 /技能名 即可触发对应技能：

/h5-pipeline         # 全流程：从 PRD + Swagger + Figma 生成完整 H5 项目
/h5-scaffold         # 单步：创建新 H5 项目脚手架
/h5-contracts        # 单步：生成契约层（types、enums、protocols）
/h5-business         # 单步：生成业务层（apis、services、composables）
/design-analysis     # 单步：分析 Figma 设计稿并生成布局映射
/create-component    # 创建/拆分 Vue 组件
/create-api          # 创建 HTTP 接口层
/create-store        # 创建 Pinia / Vuex store
/create-proposal     # 生成需求实现提案
/ui-verification     # UI 验收：页面截图 vs Figma 对比
/code-review-expert  # 代码审查（P0/P1/P2 分级）
/find-skills         # 查找可用技能

完整技能列表见 content/claude/skills/ 目录。

规范自动加载

rules/ 下标注 alwaysApply: true 的规范在 Claude Code 会话中自动注入为上下文，无需手动引用。标注 NON-NEGOTIABLE 的内容为强制要求，不可绕过。

MCP 与工具配置

Playwright（浏览器自动化）

ui-verification 等技能需要浏览器自动化能力。Playwright MCP 配置需在 Claude Code 的全局 ~/.claude.json 中配置，不通过 playbook-web 分发。

首次使用需安装浏览器：

bash

npx playwright install chromium

Figma（设计稿读取）

design-analysis、ui-verification 等技能需要读取 Figma 数据，依赖 Figma MCP。

1. 获取 Figma Personal Access Token

2. 在 ~/.claude.json 中添加 Figma MCP server

json

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "YOUR_FIGMA_TOKEN"
      },
      "type": "stdio"
    }
  }
}

将 YOUR_FIGMA_TOKEN 替换为第一步生成的 Token。

重启 Claude Code 后，/design-analysis 等技能即可读取 Figma 节点数据。

共建方式

Manifest 机制

playbook-web 在目标项目根目录维护 .playbook-web.manifest.json 文件，记录受管文件列表及其校验和：

json

{
  "schemaVersion": 2,
  "version": "1.0.6",
  "tools": ["claude"],
  "files": [
    ".claude/rules/01-基础规范.md",
    ".claude/skills/domains/games/SKILL.md"
  ],
  "checksums": {
    ".claude/rules/01-基础规范.md": "a1b2c3...",
    ".claude/skills/domains/games/SKILL.md": "d4e5f6..."
  },
  "scopedClaude": true,
  "scopedClaudePrefixes": [
    ".claude/rules",
    ".claude/skills/domains/games"
  ],
  "contributed": {},
  "conflicts": {}
}

核心原则：只有记录在 manifest 中的文件才被 playbook-web 管理。 sync、contribute、uninstall 等命令均以 manifest 为准绳判断哪些文件需要同步、贡献或卸载。

files — 受管文件的完整列表
checksums — 文件上次同步/安装时的 hash，用于检测本地修改
scopedClaudePrefixes — 局部安装模式下选中的范围前缀
contributed — 从目标项目回写过的文件及其 hash

新增 Skill（技能）

在 content/claude/skills/ 下创建以技能名命名的目录（可按领域分类，如 domains/your-skill/）：

content/claude/skills/domains/your-skill/
├── SKILL.md          # 必须，技能主文件
├── templates/        # 可选，脚手架/代码模板
├── references/       # 可选，参考资料、代码示例
├── rules/            # 可选，技能专属规则
└── prompts/          # 可选，多阶段 prompt（复杂编排类技能）

SKILL.md 是技能目录的识别标记，目录下需包含此文件
按照「编写规范」格式编写内容

同步到目标仓库：发版后，目标仓库执行 add 命令将新增资产注册到 manifest：

bash

pnpm update @wenext/playbook-web
pnpm playbook-web add    # 交互式选择新增的 playbook 资产

新增 Rule（规范）

在 content/claude/rules/ 下新建文件，命名格式：NN-模块名.md（NN 为两位数序号）
在文件顶部添加 frontmatter（格式见「编写规范」）
在 content/claude/rules/README.md 中补充对应条目
同步到目标仓库：同 Skill，发版后执行 add 注册

从目标项目反向贡献修改

1. 目标仓库新增资产

在目标项目中直接创建了新的 skill 或 rule 目录后，需执行 add 将其注册到 manifest，contribute 才能识别并回写：

bash

# 假设在目标项目 .claude/skills/ 下创建了新技能
pnpm playbook-web add    # 交互式选择本地新增的资产（标记为 local）
pnpm playbook-web contribute --to ~/repos/playbook-web

不执行 add 直接跑 contribute 不会识别到新文件，因为 contribute 只检查已在 manifest 中登记的文件变更。

2. 目标仓库更新资产

在目标项目中对规范或技能做了本地调整后，可通过以下流程将改动贡献回 playbook-web：

bash

# 1. 查看哪些文件有本地修改
npx playbook-web diff

# 2. 将修改复制到本地 playbook-web 克隆
npx playbook-web contribute --to ~/repos/playbook-web

# 3. 进入 playbook-web，提交 PR
cd ~/repos/playbook-web
git checkout -b fix/your-description
git add content/
git commit -m "fix: describe your change"
# → 提 PR → review → merge

# 4. 发版后，目标项目升级
pnpm update @wenext/playbook-web
pnpm playbook-web sync

contribute 会同步三类变更：内容修改的文件（checksum 不同）、新增的文件（add 注册且待贡献）、已删除的文件（从 playbook-web 仓库中同步删除并清理 manifest）。未改动的文件不受影响。

本地调试

克隆仓库，安装依赖，在本地直接运行 CLI：

bash

git clone git@github.com:wenext-limited/playbook-web.git
cd playbook-web
npm install
npm run build          # 编译 TypeScript → dist/

在另一个测试项目中链接本地包：

bash

# 方式 A：pnpm link（全局链接）
cd playbook-web
npm run build
pnpm link --global

cd /path/to/test-project
pnpm link --global @wenext/playbook-web
pnpm playbook-web init

# 方式 B：直接执行 bin（无需 link，最简单，推荐）
node /path/to/playbook-web/bin/playbook-web.js init

修改 content/ 下的规则或技能后，无需重新编译，直接重新执行 playbook-web sync 即可看到效果。

修改 src/ 下的 CLI 代码后需要重新编译：

bash

npm run build
# 或开启 watch 模式
npm run dev

编写规范

Skill 文件（`SKILL.md`）

Frontmatter 字段：

yaml

---
name: skill-name                    # kebab-case，与目录名一致
description: 一句话描述触发场景      # 用于 Claude 判断何时自动加载
metadata:                           # 可选
  mcp-server: figma                 # 依赖的 MCP 服务
alwaysApply: false                  # true = 每个会话自动注入（慎用）
---

必须包含的章节（中文标题）：

章节	说明
`## 概述`	技能做什么、适用场景
`## 前置条件`	执行前必须满足的条件（用 `- [ ]` 清单）
`## 工作流程`	分步骤说明，复杂步骤用子标题展开
`## 快速检查清单`	交付前验收项（用 `- [ ]` 清单）
`## 相关规范`	引用的 `content/claude/rules/` 文件链接

建议包含（视复杂度）：

## 与其它技能的关系 — 依赖链、被哪些 pipeline 调用
## 注意事项 — 常见错误、NON-NEGOTIABLE 项

风格要求：

中文正文，代码示例/frontmatter 字段用英文
步骤使用有序列表，检查项使用 - [ ]
代码块标注语言（```typescript、```vue 等）
代码模板放在 templates/ 或 references/ 目录，SKILL.md 中通过路径引用

Rule 文件（`content/claude/rules/NN-xxx.md`）

yaml

---
description: 本规范的一句话摘要
alwaysApply: true    # NON-NEGOTIABLE 规范设为 true，上下文相关规范设为 false
---

# 规范标题

## 核心原则
...

## 详细规范
...

## NON-NEGOTIABLE 项
> 以下内容不允许任何例外：
- 条目一
- 条目二

## 示例
...

playbook-web v2.0.6 ​

项目介绍 ​

CLI 命令参考 ​

接入与同步 ​

安装 ​

增量管理 ​

升级 ​

卸载 ​

CI/CD ​

在目标项目中的效果 ​

使用方式 ​

调用技能 ​

规范自动加载 ​

MCP 与工具配置 ​

Playwright（浏览器自动化） ​

Figma（设计稿读取） ​

共建方式 ​

Manifest 机制 ​

新增 Skill（技能） ​

新增 Rule（规范） ​

从目标项目反向贡献修改 ​

1. 目标仓库新增资产 ​

2. 目标仓库更新资产 ​

本地调试 ​

编写规范 ​

Skill 文件（SKILL.md） ​

Rule 文件（content/claude/rules/NN-xxx.md） ​

相关资源 ​

playbook-web v2.0.6

项目介绍

CLI 命令参考

接入与同步

安装

增量管理

升级

卸载

CI/CD

在目标项目中的效果

使用方式

调用技能

规范自动加载

MCP 与工具配置

Playwright（浏览器自动化）

Figma（设计稿读取）

共建方式

Manifest 机制

新增 Skill（技能）

新增 Rule（规范）

从目标项目反向贡献修改

1. 目标仓库新增资产

2. 目标仓库更新资产

本地调试

编写规范

Skill 文件（`SKILL.md`）

Rule 文件（`content/claude/rules/NN-xxx.md`）

相关资源