@punk6529/playbook 0.2.1 → 0.2.3

package/README.md

@@ -1,6 +1,38 @@
 # @punk6529/playbook
 
-结构化工程知识库 CLI —— 初始化、更新和查询项目 Playbook 资产。
+把团队踩过的坑，沉淀成 AI 可读、可查、可复用的工程记忆。
+
+`@punk6529/playbook` 是一个结构化工程知识库 CLI，用于在项目中快速建立并维护 Playbook 资产（cases / patterns / checklists + INDEX）。
+
+它不只是“记笔记工具”，而是把“个人经验”变成“团队可复用资产”的最小基础设施：
+
+- 解决问题后可立即沉淀为 case，避免同类问题反复排查
+- AI 可以按 tag 精准检索历史经验，而不是每次从零猜测
+- 支持项目级和全局级知识库，单项目沉淀可逐步升级为跨项目最佳实践
+- 通过结构化索引 + 按需读取，控制上下文体积，降低 token 浪费
+
+## 这个工具适合谁
+
+- 希望减少重复踩坑的个人开发者
+- 需要把故障处置经验标准化的技术团队
+- 在 Codex / Claude 工作流中，希望让 AI“带着历史经验工作”的团队
+
+## 你会获得什么
+
+- 一套开箱即用的知识库目录结构（项目级 + 全局级）
+- 三个可直接使用的 AI skills：
+  - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
+  - `/playbook-query`：手动按标签检索经验
+  - `/playbook-case`：引导式记录新 case，并更新索引
+- 一套稳定的 CLI 工作流（init / global init / update / query / promote / hit），便于持续演进而不破坏现有内容
+
+## 典型工作流
+
+1. `playbook init` 初始化项目知识库与 AI skills (新项目一次即可) 
+2. `playbook global init` 初始化全局知识库（一次即可）  
+3. 新会话开始先调用 `/playbook-advisor`，AI 会列出现有 tags；后续遇到问题时，会按相关 tags 查询案例 summary，并选取最相关案例查看详情  
+4. 问题解决后，用 `/playbook-case` 沉淀经验并更新索引  
+5. 在多个项目间通过全局仓库复用高价值模式
 
 ## 安装
 
@@ -52,25 +84,6 @@ playbook update --force                    # 强制覆盖（含 INDEX.json）
 
 仅刷新 skill 模板，不修改用户业务内容（case/pattern/checklist 文件）。`INDEX.json` 默认受保护，需 `--force` 才会覆盖。
 
-## 内部命令
-
-以下命令主要由 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 格式输出
-```
-
-这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
-
 ## 在 AI 中使用
 
 `playbook init` 之后，AI 工具中有三个 skill 可用：
@@ -121,6 +134,48 @@ AI：（引导你填写 问题/原因/解决/教训 四个部分）
 AI：（生成 case 文件，更新 INDEX.json）
 ```
 
+### `playbook promote`
+
+将项目级案例提升到全局知识库，让经验跨项目复用。
+
+```bash
+playbook promote case-001-docker-bind      # 提升单个条目
+playbook promote case-001 case-002         # 提升多个条目
+playbook promote --all                     # 提升所有项目条目
+playbook promote case-001 --force          # 强制覆盖已存在的全局条目
+```
+
+将项目 `docs/playbook/` 下的条目移动到全局 `~/.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 --scope project     # 仅项目范围
+playbook query --limit 0           # 不限数量
+playbook query docker --json       # JSON 格式输出
+```
+
+这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
+
+### `playbook hit`
+
+记录一次案例阅读命中，用于追踪案例的实际使用频率。
+
+```bash
+playbook hit case-001-docker-bind          # 记录一次命中
+```
+
+AI advisor 每次阅读案例详情后自动调用。命中次数在 `playbook query` 输出中以 `hits:N` 显示，帮助识别高价值案例。
+
 ## 错误处理
 
 - 未知命令或无效选项会给出可操作的提示信息

package/package.json

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

package/src/cli.js

@@ -1,9 +1,11 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs } = 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 { promoteEntries } = require("./commands/promote");
+const { hitEntry } = require("./commands/hit");
 const { printSummary } = require("./reporting");
 
 function usageText() {
@@ -13,6 +15,9 @@ function usageText() {
     "  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 promote <entry-id...> [--force]",
+    "  playbook promote --all [--force]",
+    "  playbook hit <entry-id>",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -100,6 +105,79 @@ function runQuery(args, io) {
   return 0;
 }
 
+function promoteHelpText() {
+  return [
+    "Usage: playbook promote <entry-id...> [options]",
+    "       playbook promote --all [options]",
+    "",
+    "Move project entries to global knowledge base.",
+    "",
+    "Options:",
+    "  --all         Promote all project entries",
+    "  --force       Overwrite if entry already exists in global",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runPromote(args, io) {
+  const options = parsePromoteArgs(args);
+  if (options.help) {
+    writeStdout(io, promoteHelpText());
+    return 0;
+  }
+
+  const result = promoteEntries(options);
+
+  if (result.message) {
+    writeStdout(io, result.message);
+    return 0;
+  }
+
+  let hasError = false;
+  for (const r of result.results) {
+    if (r.action === "promoted") {
+      writeStdout(io, `[promoted] ${r.entryId}\t${r.title}`);
+    } else if (r.action === "conflict") {
+      writeStderr(io, `[conflict] ${r.entryId}\t${r.reason}`);
+      hasError = true;
+    } else if (r.action === "error") {
+      writeStderr(io, `[error] ${r.entryId}\t${r.reason}`);
+      hasError = true;
+    }
+  }
+
+  const promoted = result.results.filter((r) => r.action === "promoted").length;
+  if (promoted > 0) {
+    writeStdout(io, `(${promoted} ${promoted === 1 ? "entry" : "entries"} promoted to global)`);
+  }
+
+  return hasError ? 1 : 0;
+}
+
+function hitHelpText() {
+  return [
+    "Usage: playbook hit <entry-id>",
+    "",
+    "Record a read hit on a playbook entry.",
+    "Searches project INDEX first, then global INDEX.",
+    "",
+    "Options:",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runHit(args, io) {
+  const options = parseHitArgs(args);
+  if (options.help) {
+    writeStdout(io, hitHelpText());
+    return 0;
+  }
+
+  const result = hitEntry(options);
+  writeStdout(io, `[${result.scope}] ${result.entryId} hits:${result.hits}`);
+  return 0;
+}
+
 function runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -149,11 +227,19 @@ async function runCli(argv, io = process) {
       return runQuery(argv.slice(1), io);
     }
 
+    if (command === "promote") {
+      return runPromote(argv.slice(1), io);
+    }
+
+    if (command === "hit") {
+      return runHit(argv.slice(1), io);
+    }
+
     if (command === "global") {
       return runGlobal(argv.slice(1), io);
     }
 
-    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/hit.js

@@ -0,0 +1,51 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { CliError } = require("../errors");
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function writeIndex(indexPath, data) {
+  fs.writeFileSync(indexPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function hitEntry(options) {
+  const { entryId, targetPath = "." } = options;
+
+  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+  const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+
+  // Try project first
+  const projectIndex = readIndex(projectIndexPath);
+  if (projectIndex && projectIndex[entryId]) {
+    projectIndex[entryId].hits = (projectIndex[entryId].hits || 0) + 1;
+    writeIndex(projectIndexPath, projectIndex);
+    return { entryId, scope: "project", hits: projectIndex[entryId].hits };
+  }
+
+  // Fall back to global
+  const globalIndex = readIndex(globalIndexPath);
+  if (globalIndex && globalIndex[entryId]) {
+    globalIndex[entryId].hits = (globalIndex[entryId].hits || 0) + 1;
+    writeIndex(globalIndexPath, globalIndex);
+    return { entryId, scope: "global", hits: globalIndex[entryId].hits };
+  }
+
+  // Not found
+  if (!projectIndex && !globalIndex) {
+    throw new CliError("No INDEX.json found. Run 'playbook init' or 'playbook global init' first.");
+  }
+
+  throw new CliError(`Entry '${entryId}' not found in project or global INDEX.`);
+}
+
+module.exports = {
+  hitEntry,
+};

package/src/commands/promote.js

@@ -0,0 +1,96 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { CliError } = require("../errors");
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function writeIndex(indexPath, data) {
+  fs.writeFileSync(indexPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function promoteEntry(entryId, projectIndex, globalIndex, projectBase, globalBase, force) {
+  const entry = projectIndex[entryId];
+  if (!entry) {
+    return { action: "error", entryId, reason: `Entry '${entryId}' not found in project INDEX` };
+  }
+
+  if (globalIndex[entryId] && !force) {
+    return {
+      action: "conflict",
+      entryId,
+      reason: `Entry '${entryId}' already exists in global INDEX (use --force to overwrite)`,
+    };
+  }
+
+  const srcFile = path.join(projectBase, entry.path);
+  const destFile = path.join(globalBase, entry.path);
+
+  // Write to global first (safety: write before delete)
+  try {
+    fs.mkdirSync(path.dirname(destFile), { recursive: true });
+    fs.copyFileSync(srcFile, destFile);
+  } catch (err) {
+    return { action: "error", entryId, reason: `Failed to copy file to global: ${err.message}` };
+  }
+
+  globalIndex[entryId] = entry;
+
+  // Now safe to remove from project
+  delete projectIndex[entryId];
+  try {
+    fs.unlinkSync(srcFile);
+  } catch {
+    // File may not exist, that's ok — INDEX entry already removed
+  }
+
+  return { action: "promoted", entryId, title: entry.title };
+}
+
+function promoteEntries(options) {
+  const { entryIds = [], all = false, force = false, targetPath = "." } = options;
+
+  const projectBase = path.resolve(targetPath, "docs/playbook");
+  const globalBase = path.join(os.homedir(), ".playbook/repo");
+
+  const projectIndexPath = path.join(projectBase, "INDEX.json");
+  const globalIndexPath = path.join(globalBase, "INDEX.json");
+
+  const projectIndex = readIndex(projectIndexPath);
+  if (!projectIndex) {
+    throw new CliError("Project INDEX.json not found. Run 'playbook init' first.");
+  }
+
+  const globalIndex = readIndex(globalIndexPath);
+  if (!globalIndex) {
+    throw new CliError("Global INDEX.json not found. Run 'playbook global init' first.");
+  }
+
+  const ids = all ? Object.keys(projectIndex) : entryIds;
+
+  if (all && ids.length === 0) {
+    return { results: [], message: "No entries in project INDEX to promote." };
+  }
+
+  const results = [];
+  for (const id of ids) {
+    results.push(promoteEntry(id, projectIndex, globalIndex, projectBase, globalBase, force));
+  }
+
+  // Write updated indices
+  writeIndex(projectIndexPath, projectIndex);
+  writeIndex(globalIndexPath, globalIndex);
+
+  return { results };
+}
+
+module.exports = {
+  promoteEntries,
+};

package/src/commands/query.js

@@ -70,7 +70,7 @@ function formatPlainText(result) {
   }
 
   const lines = result.entries.map(
-    (e) => `[${e.scope}]\t${e.id}\t${e.title}\t${e.tags.join(",")}`
+    (e) => `[${e.scope}]\t${e.id}\t${e.title}\t${e.tags.join(",")}\thits:${e.hits || 0}`
   );
 
   const displayed = result.entries.length;
@@ -157,6 +157,7 @@ function formatJson(result) {
     title: e.title,
     tags: e.tags,
     path: e.path,
+    hits: e.hits || 0,
   }));
 
   return JSON.stringify(output, null, 2);

package/src/manifest.js

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

package/src/options.js

@@ -181,9 +181,70 @@ function parseQueryArgs(args) {
   return { help: false, tags, limit, scope, json, tagsOnly };
 }
 
+function parsePromoteArgs(args) {
+  let force = false;
+  let all = false;
+  const entryIds = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "--all") {
+      all = true;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option for playbook promote: ${arg}`);
+    }
+
+    entryIds.push(arg);
+  }
+
+  if (!all && entryIds.length === 0) {
+    throw new CliError("playbook promote requires entry IDs or --all");
+  }
+
+  if (all && entryIds.length > 0) {
+    throw new CliError("Cannot use --all with specific entry IDs");
+  }
+
+  return { help: false, force, all, entryIds };
+}
+
+function parseHitArgs(args) {
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+  }
+
+  const entryId = args[0];
+  if (!entryId || entryId.startsWith("-")) {
+    throw new CliError("playbook hit requires an entry ID");
+  }
+
+  if (args.length > 1) {
+    throw new CliError("playbook hit accepts exactly one entry ID");
+  }
+
+  return { help: false, entryId };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
+  parsePromoteArgs,
+  parseHitArgs,
   parseToolsValue,
 };

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

@@ -49,6 +49,17 @@ For relevant entries only:
 
 Do NOT read all matched entries. Only read the ones that look relevant based on title.
 
+When multiple entries have similar titles, prefer entries with higher `hits` count — they have been used more often and are likely more effective.
+
+### Step 3 — Record hit
+
+After reading a case, run:
+```bash
+playbook hit <entry-id>
+```
+
+This records usage and helps prioritize effective cases in future queries.
+
 ## Guidelines
 
 - Keep queries focused — use specific tags, not broad searches

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

@@ -0,0 +1,32 @@
+---
+name: playbook-promote
+description: Guide when to promote project-level playbook entries to global knowledge base.
+license: MIT
+---
+
+Use this skill to suggest promoting valuable project experiences to the global knowledge base for cross-project reuse.
+
+## When to Suggest Promote
+
+Suggest `playbook promote <entry-id>` to the user when:
+- A project case was successfully used to resolve a problem and the lesson is not project-specific
+- A pattern or checklist has proven useful and would benefit other projects
+- The user explicitly asks about sharing knowledge across projects
+
+## When NOT to Suggest
+
+Do not suggest promote when:
+- The entry references project-specific configuration, paths, or dependencies
+- The entry is still being refined or hasn't been validated
+- The user is focused on other work (don't interrupt)
+
+## How to Promote
+
+```bash
+playbook promote <entry-id>              # promote a single entry
+playbook promote <id1> <id2>             # promote multiple entries
+playbook promote --all                   # promote all project entries
+playbook promote <entry-id> --force      # overwrite if already exists in global
+```
+
+The command moves entries from project to global: copies the file, updates both INDEX.json files, and removes the project copy.