@punk6529/playbook 0.2.0 → 0.2.1

package/README.md

@@ -14,55 +14,51 @@ npm install -g @punk6529/playbook
 npx @punk6529/playbook --help
 ```
 
-## 命令
+## 用户命令
+
+日常使用的命令：
+
+### `playbook init`
+
+在项目中初始化知识库。新项目首次使用时运行一次。
 
 ```bash
-playbook init [path] [--tools all|none|codex,claude] [--force]
-playbook global init [--force]
-playbook update [path] [--tools all|none|codex,claude] [--force]
-playbook query [tags...] [--limit N] [--scope project|global|both] [--json] [--tags-only]
+playbook init                              # 当前目录，所有 AI 工具
+playbook init ./my-project                 # 指定目录
+playbook init --tools claude               # 仅安装 Claude skill
+playbook init --tools none                 # 不安装任何 AI skill
 ```
 
-## 作用范围
+创建 `docs/playbook/{cases,patterns,checklists}`、`INDEX.json`，以及 AI skill 模板。
 
-- `playbook init` 项目级：
-  - 创建 `docs/playbook/{cases,patterns,checklists}` 和 `docs/playbook/INDEX.json`
-  - 根据 `--tools` 参数写入 AI skill 模板：
-    - Codex: `.codex/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
-    - Claude: `.claude/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
-- `playbook global init` 全局级：
-  - 创建 `~/.playbook/repo/{cases,patterns,checklists}`
-  - 创建 `~/.playbook/repo/INDEX.json` 和 `~/.playbook/repo/tags.yml`
-  - 不支持 `--tools`
-- `playbook update` 项目级：
-  - 仅更新托管模板文件
-  - 不修改用户业务内容（如 case markdown 文件）
-- V1 暂不支持 `playbook global update`
+### `playbook global init`
 
-## Skill 交付
+初始化全局知识库（跨项目共享的经验）。只需运行一次。
 
-CLI 为支持的 AI 工具（`codex`、`claude`）安装以下 skill：
+```bash
+playbook global init
+```
 
-| Skill | 用途 |
-|-------|------|
-| `playbook-query` | 手动查询知识库 |
-| `playbook-case` | 引导式 case 创建 |
-| `playbook-advisor` | 主动知识应用（自动感知 tag，AI 自主查询） |
+创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。
 
-CLI 只负责文件交付（`init`/`update`），skill 的运行时执行由宿主 AI 工具处理。
+### `playbook update`
 
-## 冲突策略
+升级 playbook CLI 版本后，更新项目中的 skill 模板到最新版。
 
-- `playbook init` 和 `playbook global init` 默认非破坏性：
-  - 有冲突的托管文件会跳过并报告为 `conflict`
-- `playbook update` 采用分级策略：
-  - skill 模板：内容不同时自动刷新
-  - `docs/playbook/INDEX.json`：保护不覆盖，除非使用 `--force`
-- 使用 `--force` 可强制覆盖受保护的托管文件
+```bash
+playbook update                            # 更新当前项目
+playbook update --force                    # 强制覆盖（含 INDEX.json）
+```
+
+仅刷新 skill 模板，不修改用户业务内容（case/pattern/checklist 文件）。`INDEX.json` 默认受保护，需 `--force` 才会覆盖。
+
+## 内部命令
 
-## 查询命令
+以下命令主要由 AI skill 内部调用，用户一般不需要直接使用：
 
-`playbook query` 按 tag 搜索 INDEX.json 条目（OR 逻辑），同时搜索项目和全局范围。
+### `playbook query`
+
+按 tag 搜索 INDEX.json 条目（OR 逻辑），同时搜索项目和全局范围。
 
 ```bash
 playbook query docker env          # 匹配 "docker" 或 "env" 的条目
@@ -73,6 +69,8 @@ playbook query --limit 0           # 不限数量
 playbook query docker --json       # JSON 格式输出
 ```
 
+这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
+
 ## 在 AI 中使用
 
 `playbook init` 之后，AI 工具中有三个 skill 可用：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI for initializing and updating Playbook & Case workflows.",
   "main": "src/index.js",
   "bin": {