@punk6529/playbook 0.2.4 → 0.2.5

package/README.md

@@ -166,6 +166,16 @@ playbook query docker --json       # JSON 格式输出
 
 这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
 
+### `playbook show`
+
+输出指定案例的完整内容。AI skill 用它查看案例详情（L2），无需知道文件路径。
+
+```bash
+playbook show case-001-docker-bind         # 输出案例文件内容
+```
+
+先查项目 INDEX，再查全局 INDEX，找到后输出对应文件内容到 stdout。
+
 ### `playbook hit`
 
 记录一次案例阅读命中，用于追踪案例的实际使用频率。

package/package.json

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

package/src/cli.js

@@ -1,11 +1,12 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs } = 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 { showEntry } = require("./commands/show");
 const { printSummary } = require("./reporting");
 
 function usageText() {
@@ -18,6 +19,7 @@ function usageText() {
     "  playbook promote <entry-id...> [--force]",
     "  playbook promote --all [--force]",
     "  playbook hit <entry-id>",
+    "  playbook show <entry-id>",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -178,6 +180,30 @@ function runHit(args, io) {
   return 0;
 }
 
+function showHelpText() {
+  return [
+    "Usage: playbook show <entry-id>",
+    "",
+    "Display the full content of a playbook entry.",
+    "Searches project INDEX first, then global INDEX.",
+    "",
+    "Options:",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runShow(args, io) {
+  const options = parseShowArgs(args);
+  if (options.help) {
+    writeStdout(io, showHelpText());
+    return 0;
+  }
+
+  const result = showEntry(options);
+  writeStdout(io, result.content);
+  return 0;
+}
+
 function runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -235,11 +261,15 @@ async function runCli(argv, io = process) {
       return runHit(argv.slice(1), io);
     }
 
+    if (command === "show") {
+      return runShow(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, hit`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit, show`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/show.js

@@ -0,0 +1,57 @@
+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 showEntry(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]) {
+    const entryPath = projectIndex[entryId].path;
+    const fullPath = path.resolve(targetPath, "docs/playbook", entryPath);
+    const content = readFile(fullPath, entryId);
+    return { entryId, scope: "project", content };
+  }
+
+  // Fall back to global
+  const globalIndex = readIndex(globalIndexPath);
+  if (globalIndex && globalIndex[entryId]) {
+    const entryPath = globalIndex[entryId].path;
+    const fullPath = path.join(os.homedir(), ".playbook/repo", entryPath);
+    const content = readFile(fullPath, entryId);
+    return { entryId, scope: "global", content };
+  }
+
+  // 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.`);
+}
+
+function readFile(fullPath, entryId) {
+  try {
+    return fs.readFileSync(fullPath, "utf8");
+  } catch {
+    throw new CliError(`File not found for entry '${entryId}': ${fullPath}`);
+  }
+}
+
+module.exports = {
+  showEntry,
+};

package/src/options.js

@@ -240,11 +240,31 @@ function parseHitArgs(args) {
   return { help: false, entryId };
 }
 
+function parseShowArgs(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 show requires an entry ID");
+  }
+
+  if (args.length > 1) {
+    throw new CliError("playbook show accepts exactly one entry ID");
+  }
+
+  return { help: false, entryId };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
   parsePromoteArgs,
   parseHitArgs,
+  parseShowArgs,
   parseToolsValue,
 };

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

@@ -43,11 +43,12 @@ Review the titles in the output. Only proceed to Step 2 for entries whose titles
 
 ### Step 2 — Read specific cases (L2)
 
-For relevant entries only:
-- Project entries: read `docs/playbook/<path>`
-- Global entries: read `~/.playbook/repo/<path>`
+For relevant entries only, run:
+```bash
+playbook show <entry-id>
+```
 
-Do NOT read all matched entries. Only read the ones that look relevant based on title.
+This outputs the full content of the case file. Do NOT read all matched entries. Only show 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.
 

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

@@ -30,14 +30,15 @@ Output format (one line per match):
 (N matches: X project, Y global)
 ```
 
-### Expansion (L2): Read individual case files
+### Expansion (L2): Show entry content
 
 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>`
+```bash
+playbook show <entry-id>
+```
 
-Only expand entries that are actually needed. Do not read all matched entries at once.
+This outputs the full content of the entry file. Only expand entries that are actually needed. Do not show all matched entries at once.
 
 ### Edge Cases