@punk6529/playbook 0.2.5 → 0.2.9

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.2.8
+
+- 新增 `playbook root [--scope project|global]` 命令，输出 playbook 目录绝对路径
+- playbook-case skill 写入文件前通过 `playbook root` 获取路径，避免相对路径问题
+- playbook-case skill 新增 Write Procedure 段，明确写入步骤
+
+## 0.2.7
+
+- `playbook query --tags-only` 合并 tags.yml 注册表，即使 INDEX 为空也能显示完整 tag 列表
+- playbook-case skill 改用 `playbook query --tags-only` 获取 tag 建议
+
+## 0.2.6
+
+- 内容文件新增 YAML front matter（title, tags, created），作为元数据主真相源
+- 新增 `playbook reindex [--scope project|global]` 命令，从文件 front matter 重建 INDEX.json
+- reindex 保留已有 hits 统计，跳过无效 front matter 的文件
+- playbook-case skill 模板更新：生成的 case 文件包含 front matter
+
+## 0.2.5
+
+- 新增 `playbook show <entry-id>` 命令，输出案例文件完整内容
+- playbook-advisor 和 playbook-query skill 的 L2 改为调用 `playbook show`，不再要求 AI 猜测文件路径
+
+## 0.2.4
+
+- 移除 init 时创建的 example 文件，INDEX.json 初始为空对象
+
+## 0.2.3
+
+- 新增 `playbook hit <entry-id>` 命令，记录案例阅读次数
+- `playbook query` 输出增加 `hits:N` 字段
+- playbook-advisor skill 阅读案例后自动调用 hit，并优先推荐高 hits 案例
+
+## 0.2.2
+
+- 新增 `playbook promote` 命令，将项目案例移动到全局知识库
+- 支持单个、多个、`--all` 批量提升，`--force` 覆盖冲突
+- 新增 playbook-promote skill 模板
+
+## 0.2.1
+
+- README，补充命令使用场景说明
+- 区分用户命令与内部命令
+
+## 0.2.0
+
+- 新增 `playbook query` 命令（按 tag 检索、`--json`、`--tags-only`）
+- 新增 playbook-advisor skill（主动顾问模式）
+- 新增 playbook-query、playbook-case skill 模板
+
+## 0.1.0
+
+- 初始版本
+- `playbook init`、`playbook global init`、`playbook update`

package/README.md

@@ -24,7 +24,7 @@
   - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
   - `/playbook-query`：手动按标签检索经验
   - `/playbook-case`：引导式记录新 case，并更新索引
-- 一套稳定的 CLI 工作流（init / global init / update / query / promote / hit），便于持续演进而不破坏现有内容
+- 一套稳定的 CLI 工作流（init / global init / update / query / promote / show / hit / reindex），便于持续演进而不破坏现有内容
 
 ## 典型工作流
 
@@ -186,6 +186,17 @@ playbook hit case-001-docker-bind          # 记录一次命中
 
 AI advisor 每次阅读案例详情后自动调用。命中次数在 `playbook query` 输出中以 `hits:N` 显示，帮助识别高价值案例。
 
+### `playbook reindex`
+
+从文件 front matter 重建 INDEX.json。当 INDEX 被清空、损坏或需要同步时使用。
+
+```bash
+playbook reindex                   # 重建项目 INDEX
+playbook reindex --scope global    # 重建全局 INDEX
+```
+
+扫描 `cases/`、`patterns/`、`checklists/` 下的 `.md` 文件，解析 YAML front matter（title, tags, created），重建 INDEX.json。保留已有的 hits 统计。
+
 ## 错误处理
 
 - 未知命令或无效选项会给出可操作的提示信息

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.2.5",
+  "version": "0.2.9",
   "description": "CLI for initializing and updating Playbook & Case workflows.",
   "main": "src/index.js",
   "bin": {
@@ -21,6 +21,7 @@
   "files": [
     "bin",
     "src",
-    "templates"
+    "templates",
+    "CHANGELOG.md"
   ]
 }

package/src/cli.js

@@ -1,5 +1,8 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs, parseReindexArgs } = require("./options");
 const { initProject } = require("./commands/init-project");
 const { initGlobal } = require("./commands/global-init");
 const { updateProject } = require("./commands/update-project");
@@ -7,6 +10,7 @@ const { queryIndex, aggregateTags, formatPlainText, formatJson, formatTagsOnly }
 const { promoteEntries } = require("./commands/promote");
 const { hitEntry } = require("./commands/hit");
 const { showEntry } = require("./commands/show");
+const { reindexPlaybook } = require("./commands/reindex");
 const { printSummary } = require("./reporting");
 
 function usageText() {
@@ -20,6 +24,8 @@ function usageText() {
     "  playbook promote --all [--force]",
     "  playbook hit <entry-id>",
     "  playbook show <entry-id>",
+    "  playbook reindex [--scope project|global]",
+    "  playbook root [--scope project|global]",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -204,6 +210,59 @@ function runShow(args, io) {
   return 0;
 }
 
+function reindexHelpText() {
+  return [
+    "Usage: playbook reindex [options]",
+    "",
+    "Rebuild INDEX.json by scanning playbook files and reading front matter.",
+    "",
+    "Options:",
+    "  --scope X     Scope: project or global (default: project)",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runReindex(args, io) {
+  const options = parseReindexArgs(args);
+  if (options.help) {
+    writeStdout(io, reindexHelpText());
+    return 0;
+  }
+
+  const result = reindexPlaybook(options);
+  writeStdout(io, `Reindexed ${result.scope}: ${result.count} ${result.count === 1 ? "entry" : "entries"} found.`);
+  return 0;
+}
+
+function runRoot(args, io) {
+  let scope = "project";
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      writeStdout(io, "Usage: playbook root [--scope project|global]\n\nOutput the absolute path of the playbook directory.");
+      return 0;
+    }
+    if (arg === "--scope" || arg.startsWith("--scope=")) {
+      const value = arg === "--scope" ? args[args.indexOf(arg) + 1] : arg.slice("--scope=".length);
+      if (value === "global" || value === "project") scope = value;
+    }
+  }
+
+  if (scope === "global") {
+    const globalRoot = path.join(os.homedir(), ".playbook/repo");
+    if (!fs.existsSync(globalRoot)) {
+      throw new CliError("Global playbook not found. Run 'playbook global init' first.");
+    }
+    writeStdout(io, globalRoot);
+  } else {
+    const projectRoot = path.resolve("docs/playbook");
+    if (!fs.existsSync(projectRoot)) {
+      throw new CliError("Project playbook not found. Run 'playbook init' first.");
+    }
+    writeStdout(io, projectRoot);
+  }
+  return 0;
+}
+
 function runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -265,11 +324,19 @@ async function runCli(argv, io = process) {
       return runShow(argv.slice(1), io);
     }
 
+    if (command === "reindex") {
+      return runReindex(argv.slice(1), io);
+    }
+
+    if (command === "root") {
+      return runRoot(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, show`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit, show, reindex, root`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/query.js

@@ -92,11 +92,28 @@ function formatPlainText(result) {
   return lines.join("\n");
 }
 
+function readTagsRegistry(tagsYmlPath) {
+  try {
+    const content = fs.readFileSync(tagsYmlPath, "utf8");
+    const ids = [];
+    for (const line of content.split("\n")) {
+      const match = line.match(/^\s*-\s*id:\s*(.+)/);
+      if (match) {
+        ids.push(match[1].trim());
+      }
+    }
+    return ids;
+  } catch {
+    return null;
+  }
+}
+
 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 tagsYmlPath = path.join(os.homedir(), ".playbook/repo/tags.yml");
 
   const tagCounts = {};
   let anyIndexFound = false;
@@ -125,6 +142,17 @@ function aggregateTags(options) {
     }
   }
 
+  // Merge tags.yml registry — ensures registered tags appear even with count 0
+  const registryTags = readTagsRegistry(tagsYmlPath);
+  if (registryTags) {
+    anyIndexFound = true;
+    for (const tag of registryTags) {
+      if (!(tag in tagCounts)) {
+        tagCounts[tag] = 0;
+      }
+    }
+  }
+
   if (!anyIndexFound) {
     return { tags: {}, found: false };
   }

package/src/commands/reindex.js

@@ -0,0 +1,98 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { CliError } = require("../errors");
+const { parseFrontMatter } = require("../frontmatter");
+
+const TYPE_DIRS = {
+  cases: "case",
+  patterns: "pattern",
+  checklists: "checklist",
+};
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function scanDir(baseDir) {
+  const entries = {};
+
+  for (const [dirName, type] of Object.entries(TYPE_DIRS)) {
+    const dirPath = path.join(baseDir, dirName);
+    if (!fs.existsSync(dirPath)) continue;
+
+    const files = fs.readdirSync(dirPath).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const filePath = path.join(dirPath, file);
+      const content = fs.readFileSync(filePath, "utf8");
+      const fm = parseFrontMatter(content);
+
+      if (!fm.title) continue; // skip files without valid front matter
+
+      const id = file.replace(/\.md$/, "");
+      const relativePath = `${dirName}/${file}`;
+
+      entries[id] = {
+        type,
+        title: fm.title,
+        tags: fm.tags || [],
+        path: relativePath,
+        created: fm.created || new Date().toISOString().slice(0, 10),
+      };
+    }
+  }
+
+  return entries;
+}
+
+function reindexPlaybook(options) {
+  const { scope = "project", targetPath = "." } = options;
+
+  let baseDir;
+  let indexPath;
+
+  if (scope === "global") {
+    baseDir = path.join(os.homedir(), ".playbook/repo");
+    indexPath = path.join(baseDir, "INDEX.json");
+  } else {
+    baseDir = path.resolve(targetPath, "docs/playbook");
+    indexPath = path.join(baseDir, "INDEX.json");
+  }
+
+  if (!fs.existsSync(baseDir)) {
+    throw new CliError(
+      scope === "global"
+        ? "Global playbook not found. Run 'playbook global init' first."
+        : "Project playbook not found. Run 'playbook init' first."
+    );
+  }
+
+  // Read existing index to preserve hits
+  const oldIndex = readIndex(indexPath) || {};
+
+  // Scan files and build new index
+  const newEntries = scanDir(baseDir);
+
+  // Preserve hits from old index
+  for (const [id, entry] of Object.entries(newEntries)) {
+    if (oldIndex[id] && oldIndex[id].hits) {
+      entry.hits = oldIndex[id].hits;
+    }
+  }
+
+  // Write new index
+  fs.writeFileSync(indexPath, JSON.stringify(newEntries, null, 2) + "\n", "utf8");
+
+  return {
+    scope,
+    count: Object.keys(newEntries).length,
+    entries: newEntries,
+  };
+}
+
+module.exports = { reindexPlaybook, scanDir };

package/src/frontmatter.js

@@ -0,0 +1,66 @@
+/**
+ * Parse YAML front matter from markdown content.
+ * Expects format:
+ * ---
+ * title: Some title
+ * tags: [tag1, tag2]
+ * created: 2026-02-01
+ * ---
+ * body content here
+ */
+function parseFrontMatter(content) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) {
+    return { title: null, tags: null, created: null, body: content };
+  }
+
+  const endIndex = trimmed.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { title: null, tags: null, created: null, body: content };
+  }
+
+  const fmBlock = trimmed.slice(4, endIndex);
+  const body = trimmed.slice(endIndex + 4).replace(/^\n/, "");
+
+  let title = null;
+  let tags = null;
+  let created = null;
+
+  for (const line of fmBlock.split("\n")) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith("#")) continue;
+
+    const colonIndex = stripped.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = stripped.slice(0, colonIndex).trim();
+    const value = stripped.slice(colonIndex + 1).trim();
+
+    if (key === "title") {
+      title = value;
+    } else if (key === "tags") {
+      tags = parseTagsValue(value);
+    } else if (key === "created") {
+      created = value;
+    }
+  }
+
+  return { title, tags, created, body };
+}
+
+function parseTagsValue(value) {
+  // Handle [tag1, tag2] format
+  const match = value.match(/^\[(.*)?\]$/);
+  if (match) {
+    if (!match[1] || !match[1].trim()) return [];
+    return match[1]
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean);
+  }
+  // Handle bare value as single tag
+  if (value) return [value];
+  return [];
+}
+
+module.exports = { parseFrontMatter };

package/src/options.js

@@ -259,6 +259,43 @@ function parseShowArgs(args) {
   return { help: false, entryId };
 }
 
+function parseReindexArgs(args) {
+  let scope = "project";
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--scope") {
+      const next = args[i + 1];
+      if (!next || !["project", "global"].includes(next)) {
+        throw new CliError("--scope must be one of: project, global");
+      }
+      scope = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--scope=")) {
+      const value = arg.slice("--scope=".length);
+      if (!["project", "global"].includes(value)) {
+        throw new CliError("--scope must be one of: project, global");
+      }
+      scope = value;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option for playbook reindex: ${arg}`);
+    }
+  }
+
+  return { help: false, scope };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
@@ -266,5 +303,6 @@ module.exports = {
   parsePromoteArgs,
   parseHitArgs,
   parseShowArgs,
+  parseReindexArgs,
   parseToolsValue,
 };

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

@@ -13,10 +13,11 @@ Use this skill when the user asks to create, review, or inspect case entries.
 - For new cases, enforce this guided flow:
   1. If the user has not provided a concrete problem statement, ask first:
      "你想把之前遇到的哪个问题沉淀为 case？请一句话描述。"
-  2. After problem statement is available, suggest tags from registry/index context first:
-     - Prefer project index: `docs/playbook/INDEX.json`
-     - Use global index only when relevant: `~/.playbook/repo/INDEX.json`
-     - Ask user to choose existing tags or explicitly confirm a new tag
+  2. After problem statement is available, get available tags by running:
+     ```bash
+     playbook query --tags-only
+     ```
+     Suggest relevant existing tags from the output. Ask user to choose existing tags or explicitly confirm a new tag.
   3. If scope is not confirmed, ask for scope confirmation:
      - default is `project`
      - use `global` only when user explicitly confirms
@@ -65,9 +66,51 @@ Format: `{type}-{NNN}-{slug}`
 - `NNN`: zero-padded 3-digit sequence number (check existing entries to determine next number)
 - `slug`: lowercase hyphenated descriptor derived from the title
 
+### Case File Format
+
+Case files MUST include YAML front matter with title, tags, and created:
+
+```markdown
+---
+title: OAuth token refresh race condition under concurrency
+tags: [auth, api]
+created: 2026-02-10
+---
+
+## Problem
+...
+
+## Context
+...
+
+## Solution
+...
+
+## Takeaway
+...
+```
+
+The front matter is the source of truth for metadata. INDEX.json is rebuilt from front matter via `playbook reindex`.
+
+### File Paths
+
+Write files to the correct location based on scope:
+
+- **Project scope:** case file → `<project-root>/docs/playbook/<path>`, INDEX → `<project-root>/docs/playbook/INDEX.json`
+- **Global scope:** case file → `~/.playbook/repo/<path>`, INDEX → `~/.playbook/repo/INDEX.json`
+
+**IMPORTANT:** Always use absolute paths when writing files. Do NOT use relative paths — the current working directory may not be the project root.
+
+Get the playbook directory first:
+```bash
+playbook root                   # project scope
+playbook root --scope global    # global scope
+```
+Then use the output to construct absolute paths, e.g. `<root>/cases/case-001-xxx.md` and `<root>/INDEX.json`.
+
 ### Draft Package Output
 
-When producing the draft package, output the INDEX entry as a ready-to-merge JSON snippet:
+When producing the draft package, output:
 
 ```
 **Entry ID:** case-001-oauth-token-race
@@ -84,3 +127,11 @@ Add this entry to INDEX.json:
   }
 }
 ```
+
+### Write Procedure
+
+After user confirms the draft:
+
+1. Write the case file to the scope-specific path
+2. Read the current INDEX.json, merge the new entry, write back
+3. Run `playbook hit <entry-id>` is NOT needed — hit is only for reads