@punk6529/playbook 0.2.0 → 0.2.2

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），便于持续演进而不破坏现有内容
+
+## 典型工作流
+
+1. `playbook init` 初始化项目知识库与 AI skills (新项目一次即可) 
+2. `playbook global init` 初始化全局知识库（一次即可）  
+3. 新会话开始先调用 `/playbook-advisor`，AI 会列出现有 tags；后续遇到问题时，会按相关 tags 查询案例 summary，并选取最相关案例查看详情  
+4. 问题解决后，用 `/playbook-case` 沉淀经验并更新索引  
+5. 在多个项目间通过全局仓库复用高价值模式
 
 ## 安装
 
@@ -14,65 +46,44 @@ npm install -g @punk6529/playbook
 npx @punk6529/playbook --help
 ```
 
-## 命令
+## 用户命令
 
-```bash
-playbook init [path] [--tools all|none|codex,claude] [--force]
-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 init`
 
-- `playbook init` 项目级：
-  - 创建 `docs/playbook/{cases,patterns,checklists}` 和 `docs/playbook/INDEX.json`
-  - 根据 `--tools` 参数写入 AI skill 模板：
-    - Codex: `.codex/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
-    - Claude: `.claude/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
-- `playbook global init` 全局级：
-  - 创建 `~/.playbook/repo/{cases,patterns,checklists}`
-  - 创建 `~/.playbook/repo/INDEX.json` 和 `~/.playbook/repo/tags.yml`
-  - 不支持 `--tools`
-- `playbook update` 项目级：
-  - 仅更新托管模板文件
-  - 不修改用户业务内容（如 case markdown 文件）
-- V1 暂不支持 `playbook global update`
+在项目中初始化知识库。新项目首次使用时运行一次。
 
-## Skill 交付
+```bash
+playbook init                              # 当前目录，所有 AI 工具
+playbook init ./my-project                 # 指定目录
+playbook init --tools claude               # 仅安装 Claude skill
+playbook init --tools none                 # 不安装任何 AI skill
+```
 
-CLI 为支持的 AI 工具（`codex`、`claude`）安装以下 skill：
+创建 `docs/playbook/{cases,patterns,checklists}`、`INDEX.json`，以及 AI skill 模板。
 
-| Skill | 用途 |
-|-------|------|
-| `playbook-query` | 手动查询知识库 |
-| `playbook-case` | 引导式 case 创建 |
-| `playbook-advisor` | 主动知识应用（自动感知 tag，AI 自主查询） |
+### `playbook global init`
 
-CLI 只负责文件交付（`init`/`update`），skill 的运行时执行由宿主 AI 工具处理。
+初始化全局知识库（跨项目共享的经验）。只需运行一次。
 
-## 冲突策略
+```bash
+playbook global init
+```
 
-- `playbook init` 和 `playbook global init` 默认非破坏性：
-  - 有冲突的托管文件会跳过并报告为 `conflict`
-- `playbook update` 采用分级策略：
-  - skill 模板：内容不同时自动刷新
-  - `docs/playbook/INDEX.json`：保护不覆盖，除非使用 `--force`
-- 使用 `--force` 可强制覆盖受保护的托管文件
+创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。
 
-## 查询命令
+### `playbook update`
 
-`playbook query` 按 tag 搜索 INDEX.json 条目（OR 逻辑），同时搜索项目和全局范围。
+升级 playbook CLI 版本后，更新项目中的 skill 模板到最新版。
 
 ```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 格式输出
+playbook update                            # 更新当前项目
+playbook update --force                    # 强制覆盖（含 INDEX.json）
 ```
 
+仅刷新 skill 模板，不修改用户业务内容（case/pattern/checklist 文件）。`INDEX.json` 默认受保护，需 `--force` 才会覆盖。
+
 ## 在 AI 中使用
 
 `playbook init` 之后，AI 工具中有三个 skill 可用：
@@ -123,6 +134,25 @@ AI：（引导你填写 问题/原因/解决/教训 四个部分）
 AI：（生成 case 文件，更新 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 开销。
+
 ## 错误处理
 
 - 未知命令或无效选项会给出可操作的提示信息

package/package.json

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

package/src/cli.js

@@ -1,9 +1,10 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs } = 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 { printSummary } = require("./reporting");
 
 function usageText() {
@@ -13,6 +14,8 @@ 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]",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -100,6 +103,55 @@ 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 runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -149,11 +201,15 @@ async function runCli(argv, io = process) {
       return runQuery(argv.slice(1), io);
     }
 
+    if (command === "promote") {
+      return runPromote(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`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

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/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,50 @@ 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 };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
+  parsePromoteArgs,
   parseToolsValue,
 };

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.