@punk6529/playbook 0.2.2 → 0.2.3

package/README.md

@@ -24,7 +24,7 @@
   - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
   - `/playbook-query`：手动按标签检索经验
   - `/playbook-case`：引导式记录新 case，并更新索引
-- 一套稳定的 CLI 工作流（init / global init / update / query），便于持续演进而不破坏现有内容
+- 一套稳定的 CLI 工作流（init / global init / update / query / promote / hit），便于持续演进而不破坏现有内容
 
 ## 典型工作流
 
@@ -134,6 +134,19 @@ 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 内部调用，用户一般不需要直接使用：
@@ -153,6 +166,16 @@ 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.2",
+  "version": "0.2.3",
   "description": "CLI for initializing and updating Playbook & Case workflows.",
   "main": "src/index.js",
   "bin": {

package/src/cli.js

@@ -1,10 +1,11 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs } = 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() {
@@ -16,6 +17,7 @@ function usageText() {
     "  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.",
@@ -152,6 +154,30 @@ function runPromote(args, io) {
   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) {
@@ -205,11 +231,15 @@ async function runCli(argv, io = process) {
       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, promote`);
+    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/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/options.js

@@ -221,10 +221,30 @@ function parsePromoteArgs(args) {
   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