npm package: @punk6529/playbook
Description: CLI for initializing and updating Playbook & Case workflows.
Latest version: 0.3.0

# @punk6529/playbook

把踩过的坑，沉淀成 AI 可读、可查、可复用的工程记忆。

`@punk6529/playbook` 是一个结构化工程知识库 CLI，用于建立并维护全局 Playbook 资产（cases / patterns / checklists + INDEX）。

它不只是"记笔记工具"，而是把"个人经验"变成"可复用资产"的最小基础设施：

- 解决问题后可立即沉淀为 case，避免同类问题反复排查
- AI 可以按 tag 精准检索历史经验，而不是每次从零猜测
- 全局知识库跨项目共享，所有经验统一管理
- 通过结构化索引 + 按需读取，控制上下文体积，降低 token 浪费

## 这个工具适合谁

- 希望减少重复踩坑的个人开发者
- 在 Codex / Claude 工作流中，希望让 AI"带着历史经验工作"的用户

## 你会获得什么

- 一套全局知识库目录结构（`~/.playbook/repo/`）
- 三个可直接使用的 AI skills：
  - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
  - `/playbook-query`：手动按标签检索经验
  - `/playbook-case`：引导式记录新 case，并更新索引
- 一套稳定的 CLI 工作流（global init / init / update / query / show / hit / reindex），便于持续演进而不破坏现有内容

## 典型工作流

1. `playbook global init` 初始化全局知识库（一次即可）
2. `playbook init` 在项目中安装 AI skill 模板（每个项目一次）
3. 新会话开始先调用 `/playbook-advisor`，AI 会列出现有 tags；后续遇到问题时，会按相关 tags 查询案例 summary，并选取最相关案例查看详情，获取问题解决方案
4. 如果遇到新问题，解决后，手动调用 `/playbook-case` 沉淀经验并更新索引
5. 所有经验统一存储在全局知识库，自动跨项目复用

## 安装

```bash
npm install -g @punk6529/playbook
```

或免安装直接运行：

```bash
npx @punk6529/playbook --help
```

## 用户命令

日常使用的命令：

### `playbook global init`

初始化全局知识库。只需运行一次。

```bash
playbook global init
```

创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。

### `playbook init`

在项目中安装 AI skill 模板。每个新项目首次使用时运行一次。

```bash
playbook init                              # 当前目录，所有 AI 工具
playbook init ./my-project                 # 指定目录
playbook init --tools claude               # 仅安装 Claude skill
playbook init --tools none                 # 不安装任何 AI skill
```

安装 AI skill 模板到 `.claude/skills/` 和 `.codex/skills/`。

### `playbook update`

升级 playbook CLI 版本后，更新项目中的 skill 模板到最新版。

```bash
playbook update                            # 更新当前项目
```

仅刷新 skill 模板，不修改知识库内容。

## 在 AI 中使用

`playbook init` 之后，AI 工具中有三个 skill 可用：

### 1. `/playbook-advisor` —— 主动知识顾问

在会话开始时调用一次，AI 会自动加载 tag 感知，后续遇到相关问题时自主查询。

**典型使用流程：**

```
你：/playbook-advisor
AI：（自动执行 playbook query --tags-only）
AI：已加载知识库标签：docker(3) env(5) react(2) ci(1)

...（正常工作中）...

AI：（遇到 Docker 端口绑定问题，发现与 "docker" tag 相关）
AI：（自动执行 playbook query docker）
AI：（发现 "case-001-docker-bind" 标题相关，读取该 case）
AI：根据之前的经验，这个问题是因为 Docker 默认绑定 0.0.0.0，需要改为 127.0.0.1...
```

特点：用户触发一次，之后 AI 自主判断何时查询，无需人工干预。

### 2. `/playbook-query` —— 手动知识查询

用户主动搜索知识库时使用。

```
你：/playbook-query
AI：请提供要搜索的 tag
你：docker
AI：找到以下条目：
    case-001-docker-bind  Docker bind address issue  docker,env  hits:3
    (1 match)
```

### 3. `/playbook-case` —— 记录新 case

解决问题后，用来记录经验到知识库。

```
你：/playbook-case
AI：请描述遇到的问题...
你：Next.js 部署到 Vercel 后 API 路由 404
AI：（引导你填写 问题/原因/解决/教训 四个部分）
AI：（生成 case 文件到 ~/.playbook/repo/，更新 INDEX.json）
```

## 内部命令

以下命令主要由 AI skill 内部调用，用户一般不需要直接使用：

### `playbook query`

按 tag 搜索全局 INDEX.json 条目（OR 逻辑）。

```bash
playbook query docker env          # 匹配 "docker" 或 "env" 的条目
playbook query                     # 所有条目
playbook query --tags-only         # 仅输出 tag 概览：docker(3) env(5) ci(2)
playbook query --limit 0           # 不限数量
playbook query docker --json       # JSON 格式输出
```

这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。

### `playbook show`

输出指定案例的完整内容。AI skill 用它查看案例详情（L2），无需知道文件路径。

```bash
playbook show case-001-docker-bind         # 输出案例文件内容
```

### `playbook hit`

记录一次案例阅读命中，用于追踪案例的实际使用频率。

```bash
playbook hit case-001-docker-bind          # 记录一次命中
```

AI advisor 每次阅读案例详情后自动调用。命中次数在 `playbook query` 输出中以 `hits:N` 显示，帮助识别高价值案例。

### `playbook reindex`

从文件 front matter 重建全局 INDEX.json。当 INDEX 被清空、损坏或需要同步时使用。

```bash
playbook reindex                   # 重建全局 INDEX
```

扫描 `~/.playbook/repo/` 下 `cases/`、`patterns/`、`checklists/` 的 `.md` 文件，解析 YAML front matter（title, tags, created），重建 INDEX.json。保留已有的 hits 统计。

## 错误处理

- 未知命令或无效选项会给出可操作的提示信息
- 托管文件读写失败会包含源路径和原因

## 打包说明

发布前确认包内容：

```bash
npm pack --dry-run
```