@punk6529/playbook 0.1.0 → 0.2.1

package/README.md

@@ -1,67 +1,134 @@
 # @punk6529/playbook
 
-CLI for initializing and updating Playbook workflow assets.
+结构化工程知识库 CLI —— 初始化、更新和查询项目 Playbook 资产。
 
-## Install
+## 安装
 
 ```bash
 npm install -g @punk6529/playbook
 ```
 
-Or run without global install:
+或免安装直接运行：
 
 ```bash
 npx @punk6529/playbook --help
 ```
 
-## Commands
+## 用户命令
+
+日常使用的命令：
+
+### `playbook init`
+
+在项目中初始化知识库。新项目首次使用时运行一次。
+
+```bash
+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 global init`
+
+初始化全局知识库（跨项目共享的经验）。只需运行一次。
+
+```bash
+playbook global init
+```
+
+创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。
+
+### `playbook update`
+
+升级 playbook CLI 版本后，更新项目中的 skill 模板到最新版。
 
 ```bash
-playbook init [path] [--tools all|none|codex,claude] [--force]
-playbook global init [--force]
-playbook update [path] [--tools all|none|codex,claude] [--force]
+playbook update                            # 更新当前项目
+playbook update --force                    # 强制覆盖（含 INDEX.json）
 ```
 
-## Scope Boundaries
+仅刷新 skill 模板，不修改用户业务内容（case/pattern/checklist 文件）。`INDEX.json` 默认受保护，需 `--force` 才会覆盖。
 
-- `playbook init` is project-scoped:
-  - creates `docs/playbook/{cases,patterns,checklists}` and `docs/playbook/INDEX.json`
-  - writes managed skill templates based on `--tools`:
-    - Codex: `.codex/skills/{playbook-query,playbook-case}/SKILL.md`
-    - Claude: `.claude/skills/{playbook-query,playbook-case}/SKILL.md`
-- `playbook global init` is global-scoped:
-  - creates `~/.playbook/repo/{cases,patterns,checklists}`
-  - creates `~/.playbook/repo/INDEX.json` and `~/.playbook/repo/tags.yml`
-  - does not support `--tools`
-- `playbook update` is project-scoped:
-  - updates only managed project templates
-  - does not modify user business content (for example case markdown files)
-- V1 does not include `playbook global update`
+## 内部命令
 
-## Skill Delivery
+以下命令主要由 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 --scope project     # 仅项目范围
+playbook query --limit 0           # 不限数量
+playbook query docker --json       # JSON 格式输出
+```
 
-- This release installs namespaced skills for supported tools (`codex`, `claude`):
-  - `playbook-query`
-  - `playbook-case`
-- CLI responsibility is asset delivery only (`init`/`update`). Runtime skill execution is handled by the host AI tool.
+这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
 
-## Conflict Policy
+## 在 AI 中使用
 
-- `playbook init` and `playbook global init` are non-destructive by default:
-  - conflicting managed files are skipped and reported as `conflict`
-- `playbook update` uses split behavior:
-  - managed skill templates are refreshed by default when content differs
-  - `docs/playbook/INDEX.json` remains conflict-safe unless `--force` is provided
-- Use `--force` to explicitly overwrite conflicting protected managed files.
+`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：找到以下条目：
+    [project] case-001-docker-bind  Docker bind address issue  docker,env
+    (1 match: 1 project)
+```
+
+### 3. `/playbook-case` —— 记录新 case
+
+解决问题后，用来记录经验到知识库。
+
+```
+你：/playbook-case
+AI：请描述遇到的问题...
+你：Next.js 部署到 Vercel 后 API 路由 404
+AI：（引导你填写 问题/原因/解决/教训 四个部分）
+AI：（生成 case 文件，更新 INDEX.json）
+```
 
-## Error Handling
+## 错误处理
 
-- Unknown command or invalid option fails with actionable guidance.
-- Managed file read/write failures include source path and reason.
+- 未知命令或无效选项会给出可操作的提示信息
+- 托管文件读写失败会包含源路径和原因
 
-## Packaging Notes
+## 打包说明
 
-Before publish, verify exact package contents:
+发布前确认包内容：
 
 ```bash
 npm pack --dry-run

package/package.json

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

package/src/cli.js

@@ -1,8 +1,9 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs } = require("./options");
 const { initProject } = require("./commands/init-project");
 const { initGlobal } = require("./commands/global-init");
 const { updateProject } = require("./commands/update-project");
+const { queryIndex, aggregateTags, formatPlainText, formatJson, formatTagsOnly } = require("./commands/query");
 const { printSummary } = require("./reporting");
 
 function usageText() {
@@ -11,10 +12,12 @@ function usageText() {
     "  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]",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
     "  - `global init` initializes ~/.playbook/repo and does not support --tools.",
+    "  - `query` searches INDEX.json by tags and returns matching entries.",
     "  - V1 does not support `playbook global update`.",
   ].join("\n");
 }
@@ -62,6 +65,41 @@ function runUpdate(args, io) {
   return 0;
 }
 
+function queryHelpText() {
+  return [
+    "Usage: playbook query [tags...] [options]",
+    "",
+    "Search INDEX.json entries by tags (OR logic).",
+    "Without tags, returns all entries.",
+    "",
+    "Options:",
+    "  --limit N     Max results to return (default: 7, 0 = unlimited)",
+    "  --scope X     Search scope: project, global, or both (default: both)",
+    "  --json        Output results as JSON array",
+    "  --tags-only   Output only tag names with case counts",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runQuery(args, io) {
+  const options = parseQueryArgs(args);
+  if (options.help) {
+    writeStdout(io, queryHelpText());
+    return 0;
+  }
+
+  if (options.tagsOnly) {
+    const result = aggregateTags(options);
+    writeStdout(io, formatTagsOnly(result));
+    return 0;
+  }
+
+  const result = queryIndex(options);
+  const output = options.json ? formatJson(result) : formatPlainText(result);
+  writeStdout(io, output);
+  return 0;
+}
+
 function runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -107,11 +145,15 @@ async function runCli(argv, io = process) {
       return runUpdate(argv.slice(1), io);
     }
 
+    if (command === "query") {
+      return runQuery(argv.slice(1), io);
+    }
+
     if (command === "global") {
       return runGlobal(argv.slice(1), io);
     }
 
-    throw new CliError(`Unknown command: ${command}. Supported: init, global, update`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/query.js

@@ -0,0 +1,172 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const DEFAULT_LIMIT = 7;
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function filterByTags(index, tags) {
+  const entries = [];
+  for (const [id, entry] of Object.entries(index)) {
+    if (tags.length === 0 || entry.tags.some((t) => tags.includes(t))) {
+      entries.push({ id, ...entry });
+    }
+  }
+  return entries;
+}
+
+function queryIndex(options) {
+  const { tags = [], limit = DEFAULT_LIMIT, scope = "both", targetPath = "." } = options;
+
+  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+  const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+
+  let projectEntries = [];
+  let globalEntries = [];
+  let anyIndexFound = false;
+
+  if (scope === "both" || scope === "project") {
+    const projectIndex = readIndex(projectIndexPath);
+    if (projectIndex) {
+      anyIndexFound = true;
+      projectEntries = filterByTags(projectIndex, tags).map((e) => ({ ...e, scope: "project" }));
+    }
+  }
+
+  if (scope === "both" || scope === "global") {
+    const globalIndex = readIndex(globalIndexPath);
+    if (globalIndex) {
+      anyIndexFound = true;
+      globalEntries = filterByTags(globalIndex, tags).map((e) => ({ ...e, scope: "global" }));
+    }
+  }
+
+  const all = [...projectEntries, ...globalEntries];
+
+  if (!anyIndexFound) {
+    return { entries: [], found: false };
+  }
+
+  const limited = limit > 0 ? all.slice(0, limit) : all;
+
+  return { entries: limited, total: all.length, found: true };
+}
+
+function formatPlainText(result) {
+  if (!result.found) {
+    return "No playbook INDEX found.";
+  }
+
+  if (result.entries.length === 0) {
+    return "No matching entries.";
+  }
+
+  const lines = result.entries.map(
+    (e) => `[${e.scope}]\t${e.id}\t${e.title}\t${e.tags.join(",")}`
+  );
+
+  const displayed = result.entries.length;
+  const total = result.total;
+  const projectCount = result.entries.filter((e) => e.scope === "project").length;
+  const globalCount = result.entries.filter((e) => e.scope === "global").length;
+
+  const parts = [];
+  if (projectCount > 0) parts.push(`${projectCount} project`);
+  if (globalCount > 0) parts.push(`${globalCount} global`);
+
+  let summary = `(${total} match${total === 1 ? "" : "es"}`;
+  if (displayed < total) {
+    summary += `, showing ${displayed}`;
+  }
+  summary += `: ${parts.join(", ")})`;
+
+  lines.push(summary);
+  return lines.join("\n");
+}
+
+function aggregateTags(options) {
+  const { scope = "both", targetPath = "." } = options;
+
+  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+  const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+
+  const tagCounts = {};
+  let anyIndexFound = false;
+
+  function countTags(index) {
+    for (const entry of Object.values(index)) {
+      for (const tag of entry.tags) {
+        tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+      }
+    }
+  }
+
+  if (scope === "both" || scope === "project") {
+    const projectIndex = readIndex(projectIndexPath);
+    if (projectIndex) {
+      anyIndexFound = true;
+      countTags(projectIndex);
+    }
+  }
+
+  if (scope === "both" || scope === "global") {
+    const globalIndex = readIndex(globalIndexPath);
+    if (globalIndex) {
+      anyIndexFound = true;
+      countTags(globalIndex);
+    }
+  }
+
+  if (!anyIndexFound) {
+    return { tags: {}, found: false };
+  }
+
+  return { tags: tagCounts, found: true };
+}
+
+function formatTagsOnly(result) {
+  if (!result.found) {
+    return "No playbook INDEX found.";
+  }
+
+  const entries = Object.entries(result.tags);
+  if (entries.length === 0) {
+    return "No tags found.";
+  }
+
+  return entries.map(([tag, count]) => `${tag}(${count})`).join(" ");
+}
+
+function formatJson(result) {
+  if (!result.found) {
+    return JSON.stringify([]);
+  }
+
+  const output = result.entries.map((e) => ({
+    id: e.id,
+    scope: e.scope,
+    type: e.type,
+    title: e.title,
+    tags: e.tags,
+    path: e.path,
+  }));
+
+  return JSON.stringify(output, null, 2);
+}
+
+module.exports = {
+  queryIndex,
+  aggregateTags,
+  formatPlainText,
+  formatJson,
+  formatTagsOnly,
+  DEFAULT_LIMIT,
+};

package/src/manifest.js

@@ -45,6 +45,18 @@ const PROJECT_MANAGED_FILES = [
     tool: "claude",
     overwriteOnUpdate: true,
   },
+  {
+    relativePath: ".codex/skills/playbook-advisor/SKILL.md",
+    templatePath: "project/skills/playbook-advisor/SKILL.md",
+    tool: "codex",
+    overwriteOnUpdate: true,
+  },
+  {
+    relativePath: ".claude/skills/playbook-advisor/SKILL.md",
+    templatePath: "project/skills/playbook-advisor/SKILL.md",
+    tool: "claude",
+    overwriteOnUpdate: true,
+  },
 ];
 
 const GLOBAL_SKELETON_DIRS = ["cases", "patterns", "checklists"];

package/src/options.js

@@ -106,8 +106,84 @@ function parseGlobalInitArgs(args) {
   return { help: false, force };
 }
 
+function parseQueryArgs(args) {
+  let limit = 7;
+  let scope = "both";
+  let json = false;
+  let tagsOnly = false;
+  const tags = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+
+    if (arg === "--tags-only") {
+      tagsOnly = true;
+      continue;
+    }
+
+    if (arg === "--limit") {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("-")) {
+        throw new CliError("Missing value for --limit");
+      }
+      limit = parseInt(next, 10);
+      if (Number.isNaN(limit) || limit < 0) {
+        throw new CliError("--limit must be a non-negative integer");
+      }
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--limit=")) {
+      const value = arg.slice("--limit=".length);
+      limit = parseInt(value, 10);
+      if (Number.isNaN(limit) || limit < 0) {
+        throw new CliError("--limit must be a non-negative integer");
+      }
+      continue;
+    }
+
+    if (arg === "--scope") {
+      const next = args[i + 1];
+      if (!next || !["project", "global", "both"].includes(next)) {
+        throw new CliError("--scope must be one of: project, global, both");
+      }
+      scope = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--scope=")) {
+      const value = arg.slice("--scope=".length);
+      if (!["project", "global", "both"].includes(value)) {
+        throw new CliError("--scope must be one of: project, global, both");
+      }
+      scope = value;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option for playbook query: ${arg}`);
+    }
+
+    tags.push(arg);
+  }
+
+  return { help: false, tags, limit, scope, json, tagsOnly };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
+  parseQueryArgs,
   parseToolsValue,
 };

package/templates/project/skills/playbook-advisor/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: playbook-advisor
+description: Automatically leverage playbook knowledge when encountering problems related to known topics.
+license: MIT
+---
+
+Use this skill to proactively apply playbook knowledge during your work.
+
+## Bootstrap: Load Tag Awareness
+
+On activation, immediately run:
+```bash
+playbook query --tags-only
+```
+
+This outputs all available tags with their case counts, e.g.: `docker(3) react(2) env(5)`
+
+Internalize this tag list. It tells you what domains have recorded experience.
+
+If the output is "No playbook INDEX found." — inform the user that no playbook knowledge is available and suggest running `playbook init` to get started. Stop here.
+
+## When to Query
+
+Query the playbook when you encounter:
+- An error or unexpected behavior related to a known tag
+- Uncertainty about how to approach a task in a domain with known experience
+- A recurring pattern that might have documented guidance
+
+**Do NOT query** during routine work with no errors or uncertainty. Only query when there is a specific reason.
+
+## How to Query (Progressive Disclosure)
+
+Follow this L1 → L2 flow:
+
+### Step 1 — Title list (L1)
+
+Run:
+```bash
+playbook query <tag>
+```
+
+Review the titles in the output. Only proceed to Step 2 for entries whose titles suggest relevance to your current problem.
+
+### Step 2 — Read specific cases (L2)
+
+For relevant entries only:
+- Project entries: read `docs/playbook/<path>`
+- Global entries: read `~/.playbook/repo/<path>`
+
+Do NOT read all matched entries. Only read the ones that look relevant based on title.
+
+## Guidelines
+
+- Keep queries focused — use specific tags, not broad searches
+- If multiple tags match your situation, query the most specific one first
+- Apply learnings from cases directly to your current work
+- Do not mention the playbook to the user unless they ask about it

package/templates/project/skills/playbook-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playbook-query
-description: Query project and global playbook knowledge in a concise, index-first way.
+description: Query project and global playbook knowledge using CLI for token-efficient discovery.
 license: MIT
 ---
 
@@ -8,43 +8,39 @@ Use this skill when the user asks to search, filter, or inspect playbook knowled
 
 ## Behavior
 
-### Lookup Sequence
+### Discovery (L1): Use CLI command
 
-**IMPORTANT: Only read the specific files listed below by their exact path. Do NOT use broad file search, glob, or grep across the filesystem — this can trigger macOS privacy prompts.**
+**IMPORTANT: Do NOT read INDEX.json directly. Use the CLI command to filter entries locally and save tokens.**
 
-1. **Project first**: Read `docs/playbook/INDEX.json` (relative to project root)
-2. **Global fallback**: If no matches found, or user asks for broader results, read `~/.playbook/repo/INDEX.json` (this exact path only)
-3. Merge results if both scopes have relevant entries. Label scope in output.
-
-### Matching
-
-- Parse INDEX.json: each key is an entry ID, each value has `type`, `title`, `tags`, `path`, `created`
-- Match user query against:
-  - `tags` array (primary match — compare with tag IDs and aliases from `tags.yml`)
-  - `title` text (secondary match — keyword overlap)
-  - `type` filter (if user specifies "show me patterns" or "any checklists for...")
-- If no matches found in either scope, say so clearly
-
-### Progressive Disclosure
+Run:
+```bash
+playbook query <tag1> <tag2> ...
+```
 
-Return results in order of increasing detail and token cost:
+This searches both project and global INDEX.json, returns matching entries (max 7 by default), with project results first.
 
-1. **Checklists first** — actionable, cheapest to show. Display inline if short.
-2. **Patterns next** — show title + tags summary. Offer to expand.
-3. **Cases last** — show title + tags summary only. Expand full content only when user explicitly asks.
+Options:
+- `--limit N` — change max results (0 = unlimited)
+- `--scope project|global|both` — restrict search scope
+- `--json` — output as JSON array
 
-For each match, show:
+Output format (one line per match):
 ```
-[{type}] {title}  (tags: {tags})  [{scope}]
+[scope]  entry-id  title  tags
+(N matches: X project, Y global)
 ```
 
-### Expanding Entries
+### Expansion (L2): Read individual case files
+
+When the user asks to see details of a specific entry, or when you need full context for a task:
+
+- For project entries: read `docs/playbook/<path>` where `<path>` is from the query result
+- For global entries: read `~/.playbook/repo/<path>`
 
-- When user asks to see details, read the content file at the entry's `path` (relative to `docs/playbook/` for project, `~/.playbook/repo/` for global)
-- Show the full markdown content of the referenced file
+Only expand entries that are actually needed. Do not read all matched entries at once.
 
 ### Edge Cases
 
-- If INDEX.json is empty (`{}`), tell the user: "No entries yet. Use playbook-case to create your first entry."
-- If a referenced file at `path` doesn't exist, report it as a broken reference
-- If user query is vague, show all entries grouped by type
+- If query returns "No playbook INDEX found." — tell the user: "No playbook initialized. Run `playbook init` to get started."
+- If query returns "No matching entries." — suggest trying different tags or running without tags to see all entries
+- If user query is vague, run `playbook query` without tags to list everything