@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. 所有经验统一存储在全局知识库，自动跨项目复用

安装

npm install -g @punk6529/playbook

或免安装直接运行：

npx @punk6529/playbook --help

用户命令

日常使用的命令：

playbook global init

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

playbook global init

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

playbook init

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

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 模板到最新版。

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 逻辑）。

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），无需知道文件路径。

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

playbook hit

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

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

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

playbook reindex

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

playbook reindex                   # 重建全局 INDEX

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

错误处理

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

打包说明

发布前确认包内容：

npm pack --dry-run