@punk6529/playbook 0.2.2 → 0.2.4

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.4",
   "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/manifest.js

@@ -9,18 +9,6 @@ const PROJECT_MANAGED_FILES = [
     relativePath: "docs/playbook/INDEX.json",
     templatePath: "project/docs/playbook/INDEX.json",
   },
-  {
-    relativePath: "docs/playbook/cases/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/cases/_example-001-delete-me.md",
-  },
-  {
-    relativePath: "docs/playbook/patterns/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/patterns/_example-001-delete-me.md",
-  },
-  {
-    relativePath: "docs/playbook/checklists/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/checklists/_example-001-delete-me.md",
-  },
   {
     relativePath: ".codex/skills/playbook-query/SKILL.md",
     templatePath: "project/skills/playbook-query/SKILL.md",

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/global/INDEX.json

@@ -1,9 +1 @@
-{
-  "_example-001-delete-me": {
-    "type": "case",
-    "title": "Example entry — delete this and add real entries via playbook-case skill",
-    "tags": ["workflow"],
-    "path": "cases/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  }
-}
+{}

package/templates/project/docs/playbook/INDEX.json

@@ -1,23 +1 @@
-{
-  "case-001-example-node-version-mismatch": {
-    "type": "case",
-    "title": "Deployment failed due to Node.js version mismatch",
-    "tags": ["env", "ci"],
-    "path": "cases/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  },
-  "pattern-001-example-pin-runtime-versions": {
-    "type": "pattern",
-    "title": "Pin runtime versions before upgrading dependencies",
-    "tags": ["env", "workflow"],
-    "path": "patterns/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  },
-  "checklist-001-example-pre-publish": {
-    "type": "checklist",
-    "title": "Pre-publish checklist",
-    "tags": ["workflow", "ci"],
-    "path": "checklists/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  }
-}
+{}

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/docs/playbook/cases/_example-001-delete-me.md

@@ -1,24 +0,0 @@
-# Deployment failed due to Node.js version mismatch
-
-> Delete this example file and create real cases using the playbook-case skill.
-
-## Problem
-
-Production deployment failed silently. The build succeeded locally but crashed on startup in CI with `SyntaxError: Unexpected token ??=`.
-
-## Context
-
-- Local dev environment: Node 20
-- CI runner: Node 16 (inherited from base image, not pinned)
-- The `??=` operator (logical nullish assignment) requires Node 15+
-- No `engines` field in package.json to catch this earlier
-
-## Solution
-
-1. Added `"engines": { "node": ">=20" }` to package.json
-2. Updated CI base image to `node:20-slim`
-3. Added `engine-strict=true` to `.npmrc` so mismatches fail fast on `npm install`
-
-## Takeaway
-
-Always pin the Node.js version in `engines` and enforce it. Silent version mismatches cause the worst kind of debugging — everything works locally.

package/templates/project/docs/playbook/checklists/_example-001-delete-me.md

@@ -1,10 +0,0 @@
-# Pre-publish checklist
-
-> Delete this example file and create real checklists using the playbook-case skill.
-
-- [ ] Run `npm pack --dry-run` and verify included files
-- [ ] Check `files` field in package.json matches intended contents
-- [ ] Verify version number is correct and not already published
-- [ ] Run full test suite: `npm test`
-- [ ] Check for accidentally included secrets or credentials
-- [ ] Confirm README is up to date with current API/usage

package/templates/project/docs/playbook/patterns/_example-001-delete-me.md

@@ -1,15 +0,0 @@
-# Pin runtime versions before upgrading dependencies
-
-> Delete this example file and create real patterns using the playbook-case skill.
-
-## When to Use
-
-Apply this pattern whenever you upgrade a major runtime (Node.js, Python, Ruby) or a core dependency that has runtime version requirements.
-
-## Pattern
-
-1. **Pin the current version first** — add `engines` field (Node), `python_requires` (Python), or equivalent before making any changes
-2. **Upgrade in CI first** — update the CI base image/config before changing local dev setup
-3. **Run full test suite against new version** — don't rely on local smoke tests
-4. **Update lockfile** — regenerate `package-lock.json` / `yarn.lock` under the new runtime
-5. **Communicate** — update README and onboarding docs with new version requirement