ZachariahRedfield/playbook

# Playbook 面向人类和 AI 代理的确定性仓库运行时与信任层。  [](https://github.com/ZachariahRedfield/playbook/actions/workflows/playbook-diagrams-check.yml)  [](docs/ARCHITECTURE_DIAGRAMS.md)  Playbook 通过确定性仓库智能和经审查的修复方案，帮助人类和 AI 代理理解、治理并安全地更改真实仓库。 Playbook 并非定位为通用聊天助手。它是介于助手与生产代码库之间的运行时：提供明确的合约、确定性的发现结果以及基于策略的变更闭环。 ## 类别与产品主张 Playbook 最好被理解为 **确定性仓库智能 + 治理 + 安全修复运行时**： - **读取基座**：`ai-context`, `ai-contract`, `index`, `query`, `deps`, `ask --repo-context`, `explain` - **治理内核**：`verify` - **变更桥梁**：`plan -> apply -> verify` - **交付面**：通过 CLI, CI, 自动化和集成使用同一引擎 这一框架是其核心承诺：以确定性证据取代临时推断，以审查过的意图先于执行。 ## 共享核心，项目本地智能 Playbook 采用 **共享核心 + 项目本地 Playbook 状态** 的集成模型： - Playbook 产品（CLI/引擎/合约）是共享核心。 - 在消费者仓库中安装 Playbook 会创建 **项目本地 Playbook 状态**（配置、索引/产物、计划以及特定于仓库的扩展），默认情况下并非分叉。 - 仓库观察结果默认保持本地/私有。 - 可重用的模式和产品改进会被有意识地向上游推广（docs/roadmap/rules），而非通过隐式变更。 模式：**默认私有优先**。标准 Playbook 使用并不隐含自动上游内容导出。 模式：**通过 config/plugins/rule packs（而非 forks）** 进行项目特定的定制。 ## 运行时产物与存储 Playbook 使用 `.playbook/` 作为本地运行时产物的默认主目录（例如仓库智能索引、计划和机器可读报告）。 - 生成的运行时产物通常应被 gitignore，除非有意将其作为稳定合约/示例提交。 - 在 `.playbook/demo-artifacts/` 下提交的演示产物是面向产品的快照合约和示例，而非通用的运行时日志。 - Playbook 默认保持本地/私有优先：本地扫描和产物生成不隐含自动云同步或上游导出。 模式：运行时产物存放在 `.playbook/` 下。 模式：演示产物是快照合约，而非通用运行时状态。 规则：生成的运行时产物应被 gitignore，除非有意将其作为稳定合约/示例提交。 规则：Playbook 默认保持本地/私有优先。 故障模式：每次运行都重新提交生成的运行时产物会导致不必要的仓库历史增长和审查噪音。 ## Playbook 产物生命周期 Playbook 将仓库产物分类为确定的存储类别： - **运行时产物**：本地输出，如 `.playbook/repo-index.json`, `.playbook/plan.json`, `.playbook/verify.json`，会话清理报告和缓存文件。 - **自动化产物**：CI 交接输出，例如 CI 计划和验证产物。 - **合约产物**：提交的快照和文档合约，如 `tests/contracts/*.snapshot.json`, `.playbook/demo-artifacts/*` 和生成的图表文档。 使用 `.playbookignore` 来控制 `playbook index` 和其他仓库扫描的仓库智能扫描范围。其语法与 `.gitignore` 相似。 推荐的起始条目： ``` node_modules dist build coverage .next .playbook/cache ``` `playbook doctor` 现已包含 **Playbook 产物卫生** 部分，用于检测产物误用并建议确定性修复。 ## 快速开始（规范阶梯） 安装当前的公共 CLI 包： ``` npm install -g @fawxzzy/playbook ``` 然后运行规范的 Playbook 优先操作阶梯： ``` playbook ai-context --json playbook ai-contract --json playbook context --json playbook index --json playbook query modules --json playbook explain architecture --json playbook ask "where should a new feature live?" --repo-context --json playbook verify --json playbook plan --json > .playbook/plan.json playbook apply --from-plan .playbook/plan.json playbook verify --json ``` `analyze` 仍可用于兼容性和轻量级堆栈检查，但它不再是唯一的重要快速入门路径。 对于本仓库内的本地分支准确验证，建议使用： ``` node packages/cli/dist/main.js plan --json > .playbook/plan.json node packages/cli/dist/main.js apply --from-plan .playbook/plan.json --json ``` PowerShell 安全的本地等效命令： ``` node packages/cli/dist/main.js plan --json | Out-File -FilePath .playbook/plan.json -Encoding utf8 node packages/cli/dist/main.js apply --from-plan .playbook/plan.json --json ``` 对于无需安装的预览流程： ``` npx @fawxzzy/playbook demo ``` `playbook demo` 遵循相同的规范严肃用户阶梯（`ai-context -> ai-contract -> context -> index -> query/explain -> verify -> plan -> apply -> verify`），并且不使用 `fix` 作为主要的引导路径。 ## 示例输出 `playbook verify` 和 `playbook plan` 为人类和 AI 代理提供确定性的、可审查的输出。如需完整的演示输出，请使用官方演示仓库： ``` git clone https://github.com/ZachariahRedfield/playbook-demo cd playbook-demo npm install npx @fawxzzy/playbook ai-context --json npx @fawxzzy/playbook index --json npx @fawxzzy/playbook verify --json # bash/zsh npx @fawxzzy/playbook plan --json > .playbook/plan.json # PowerShell-safe npx @fawxzzy/playbook plan --json | Out-File -FilePath .playbook/plan.json -Encoding utf8 npx @fawxzzy/playbook apply --from-plan .playbook/plan.json npx @fawxzzy/playbook verify --json ``` ## CLI 命令 ### 核心 - `analyze` - `verify` - `plan` - `apply` ### 仓库工具 - `doctor` - `diagram` - `rules` - `docs` - `schema` - `context` - `ai-context` - `ai-contract` ### 仓库智能 - `index` - `graph` - `query` - `deps` - `ask` - `explain` 有关完整的命令清单（包括实用工具命令），请参阅 [docs/commands/README.md](docs/commands/README.md)。 命令真值打包是通过 `packages/cli/src/lib/commandMetadata.ts` 驱动的元数据，并生成为 `docs/contracts/command-truth.json`（规范 vs 兼容 vs 实用 + 引导/修复序列）。 运行 `npx @fawxzzy/playbook index` 以在 `.playbook/repo-index.json`, `.playbook/repo-graph.json` 以及 `.playbook/context/modules/*.json` 下的压缩模块摘要中生成确定性的机器可读仓库智能产物。 通过压缩降低复杂度：Playbook 通过提取小型确定性产物（index -> graph -> module digests）并在 query/explain/ask 面中重用它们，而不是重复扫描广泛的仓库状态，从而降低仓库复杂度。 使用 `playbook schema` 检索命令输出的 JSON Schema 合约（`rules`, `explain`, `index`, `graph`, `verify`, `plan`, `context`, `ai-context`, `ai-contract`, `docs`），以便 CI 和代理可以验证负载。 ## Playbook Context Playbook 为人类和自动化提供确定性的机器可读上下文： - `playbook context --json` 返回更广泛的 CLI 和架构上下文。 - `playbook ai-context --json` 返回紧凑的 AI 引导负载。 - `playbook ai-contract --json` 从 `.playbook/ai-contract.json`（缺失时采用确定性生成的默认值）返回仓库 AI 可操作性合约。 ## AI 引导 AI 工具可以通过以下方式引导仓库理解： ``` playbook ai-context --json playbook ai-contract --json ``` 该负载专为以下设计： - AI 代理 - IDE 助手 - CI 自动化 AI 优先流程示例： ``` playbook ai-context playbook context playbook index playbook query modules playbook ask "where should a new feature live?" --repo-context playbook ask "how does auth work?" --repo-context --mode concise playbook ask "how does this work?" --module workouts --repo-context playbook ask "what modules are affected by this change?" --diff-context playbook ask "how do I fix this rule violation?" --mode ultra playbook explain architecture playbook verify playbook plan playbook apply ``` 在 AI 引导阶梯中，建议在 query/ask/explain 之前使用 `playbook context` 获取更广泛的仓库和 CLI 上下文。 在本仓库内，使用本地构建的 CLI 入口点进行分支准确验证： ``` pnpm -r build node packages/cli/dist/main.js ai-context --json node packages/cli/dist/main.js context --json node packages/cli/dist/main.js docs audit --json ``` 首选 AI 操作阶梯：`ai-context -> ai-contract -> context -> index/query/explain/ask --repo-context -> verify/plan/apply`。 未来应用集成方向：应用或仪表板操作应使用可信的 **服务端 Playbook API/运行时或库层** 进行已验证的操作，而不是直接执行任意浏览器端 CLI 命令。 模式：`playbook ai-context` 是 Playbook 感知 AI 工作流的首选代理引导命令。 模式：`.playbook/ai-contract.json` 是 Playbook 启用仓库的规范 AI 可操作性握手产物。 规则：当命令覆盖范围存在时，AI 代理应优先使用 Playbook 命令，而非广泛的仓库推断。 规则：在 Playbook 仓库内，使用本地构建的 CLI 入口点以反映当前分支行为。 模式：`ai-context -> ai-contract -> context -> index/query/explain/ask --repo-context -> verify/plan/apply` 是首选的 AI 操作阶梯。 故障模式：当 AI 工具绕过 Playbook 命令输出并直接从过时或不完整的文件检查中进行推理时，会发生代理漂移。 ### 查询仓库智能 使用 `playbook query` 直接从 `.playbook/repo-index.json` 读取结构化架构元数据，而无需重新扫描仓库。 对于模块化单体仓库，Playbook 将 `src/features/*` 目录索引为一级模块（当 `src/features/*` 缺失时，回退到直接的 `src/*` 模块目录）。 ``` playbook index playbook query modules playbook query architecture playbook query risk workouts playbook query impact workouts playbook query docs-coverage playbook query rule-owners playbook query test-hotspots playbook ask "where should a new feature live?" playbook ask "what modules exist?" --json playbook ask "how does auth work?" --repo-context --mode concise playbook ask "how does this work?" --module workouts --repo-context playbook ask "what modules are affected by this change?" --diff-context playbook ask "how do I fix this rule violation?" --mode ultra playbook explain workouts playbook explain PB001 playbook explain architecture ``` ### 感知仓库的 ask (`playbook ask --repo-context`, `--module`) 在询问仓库形状或架构问题时使用 `--repo-context`。 - 它将可信的 Playbook 管理的产物（例如 `.playbook/repo-index.json` 和 AI 合约元数据）注入到 ask 上下文中。 - 它避免广泛的临时仓库文件推断。 - 它首先需要来自 `playbook index` 的仓库智能。 - `--module ` 将 ask 推理范围缩小到该模块的可信索引上下文。 示例： ``` playbook index playbook ask "where should a new feature live?" --repo-context playbook ask "how does auth work?" --repo-context --mode concise playbook ask "how does this work?" --module workouts --repo-context playbook ask "what modules are affected by this?" --repo-context --json ``` 如果 `.playbook/repo-index.json` 缺失，ask 将返回确定性的修复指导以运行 `playbook index` 并重试。 ### 结构化 PR 智能 (`playbook analyze-pr`) 使用 `playbook analyze-pr` 从本地 git diff + `.playbook/repo-index.json` 进行确定性的、机器可读的变更分析。 - `playbook ask --diff-context` 是对话式变更推理。 - `playbook analyze-pr` 是用于自动化和预合并检查的结构化审查/报告面。 - `playbook analyze-pr --json` 仍是自动化的规范确定性分析合约。 - `playbook analyze-pr --format ` 仅在该合约之上选择呈现方式。 - `playbook analyze-pr --format github-comment` 将相同的确定性分析合约渲染为 GitHub 就绪的 PR 摘要 markdown 导出。 - `playbook analyze-pr --format github-review` 从分析合约中的规范发现渲染确定性行内审查注释（`path`/`line`/`body`）。 - GitHub Actions 传输现在将摘要格式化器输出发布为一条粘性 Playbook 摘要评论（``），并同步行内诊断（``），以便添加新诊断，不重复现有诊断，并移除已解决的诊断。 - 工作流层仅负责传输：它不在 `analyze-pr --format github-comment` 和 `analyze-pr --format github-review` 之外重建分析或格式化。 - 工作流在 `analyze-pr` 之前运行 `playbook index`，因为仅创建 `.playbook/` 目录是不够的；`analyze-pr` 消费 `.playbook/repo-index.json`。 - 在 CI pull_request 工作流中，传递显式的 diff base（例如 `--base origin/${{ github.base_ref }}`）并使用完整历史检出（`fetch-depth: 0`）以进行确定性 diff 解析。 ``` npx @fawxzzy/playbook index npx @fawxzzy/playbook analyze-pr --format text npx @fawxzzy/playbook analyze-pr --json npx @fawxzzy/playbook analyze-pr --format github-comment npx @fawxzzy/playbook analyze-pr --format github-review ``` ### 变更范围的 ask (`playbook ask --diff-context`) 使用 `--diff-context` 结合可信的本地 diff + 索引智能来回答分支/工作树问题。 - 需要 `.playbook/repo-index.json` 和本地 git diff 可用性。 - 生成确定性的变更文件、受影响模块、影响、文档和风险上下文。 - 当 diff 上下文不可用时，绝不静默扩展为全仓库推断。 - 可选的 `--base ` 将 diff 比较范围缩小到显式的 base（例如 `main`）。 - 在 `--json` 模式下，ask 在 `context.sources` 中包含确定性来源元数据，以便代理/CI 可以审计哪些索引智能来源为答案提供了依据（不暴露原始文件内容）。 ``` playbook index playbook ask "what modules are affected by this change?" --diff-context playbook ask "what should I verify before merge?" --diff-context --mode concise playbook ask "summarize the architectural risk of this diff" --diff-context --json ``` ### AI 响应模式 (`playbook ask --mode`) `playbook ask` 支持响应模式以控制答案密度。 - `normal`（默认）：带上下文的完整解释 - `concise`：压缩但仍具信息量的输出 - `ultra`：为快速决策优化的最大压缩 示例： ``` playbook ask "how does auth work?" playbook ask "how does auth work?" --repo-context --mode concise playbook ask "how does this work?" --module workouts --repo-context playbook ask "what modules are affected by this change?" --diff-context playbook ask "how do I fix this rule violation?" --mode ultra ``` 权威命令状态位于 [docs/commands/README.md](docs/commands/README.md)。 本仓库的 AI 操作合约位于 [AGENTS.md](AGENTS.md)。托管命令清单/示例通过 `pnpm agents:update` 从共享 CLI 命令元数据生成，并使用 `pnpm agents:check` 进行验证。 托管命令文档通过 `pnpm docs:update` 和 `pnpm docs:check` 生成/验证，以减少 `AGENTS.md` 和 `docs/commands/README.md` 之间的命令面漂移。 会话知识卫生可通过 `playbook session cleanup --hygiene --dry-run --json-report .playbook/session-cleanup.report.json` 获得确定性规范化/去重/截断/修剪报告。 ## 演示请参阅 [`playbook-demo`](https://github.com/ZachariahRedfield/playbook-demo)，也可通过 `playbook demo` 发现。 ## 演示仓库合约模式 - 模式：演示仓库应为命令导向的，以便最强大的产品命令在标准快乐路径中成功执行。 - 模式：演示产物应由真实 CLI 命令生成并提交在 `.playbook/demo-artifacts/` 下。 - 规则：演示文档应总结生成的产物，而不是取代它们作为事实来源。 - 规则：文档/演示中的 `explain ` 示例必须引用保证在 `.playbook/repo-index.json` 中存在的模块。 - 模式：添加单一的演示刷新脚本以确定性地重新生成 index/explain/rules/verify/plan/apply/diagram/doctor 输出。 - 模式：跨仓库演示产物刷新自动化应在专用维护工作流中运行，并针对 `ZachariahRedfield/playbook-demo` 开启 PR，而不是直接变更 `main`。 ## 规范修复工作流 Playbook 的规范修复循环是： `verify -> plan -> apply -> verify` - `verify` 检测确定性策略发现。 - `plan` 生成可审查的修复产物（包括用于自动化的 JSON 输出）。 - `apply` 从新的计划或序列化的计划产物执行确定性的可自动修复任务。 - 最终的 `verify` 确认仓库返回到符合策略的状态。 `fix` 仍作为便捷的直接修复路径可用（例如 `--dry-run`, `--yes`, `--only`），当你需要单命令本地工作流而不是显式的 plan/apply 步骤时。 ## 入门 运行： ``` npx @fawxzzy/playbook doctor ``` `playbook doctor` 提供高级仓库健康报告，包括框架、架构、治理检查和建议的后续操作。 ## AI 环境诊断 运行： ``` npx @fawxzzy/playbook doctor --ai ``` 此命令验证仓库是否正确配置用于 AI 辅助的 Playbook 工作流，包括确定性 AI 合约就绪性验证（合约可用性/有效性、智能源、所需命令/查询面以及修复工作流就绪性）。它是未来 Playbook 代理执行之前的就绪门槛。 使用 `playbook doctor --help` 查看特定于 doctor 的标志，包括 `--ai`。 ## 如何发现功能 CLI 帮助输出是支持的命令和标志的权威来源。 - 使用 `playbook rules` 列出可用的规则。 - 使用 `playbook explain ` 从 `.playbook/repo-index.json` 和规则注册表确定性地解释规则、模块和架构。 ## Init 脚手架合约 运行： ``` npx @fawxzzy/playbook init ``` 保证以下基线项目产物： - Playbook 配置（`playbook.config.json` 或 `.playbook/config.json`） - `docs/PLAYBOOK_NOTES.md` 其他文档如 `docs/PROJECT_GOVERNANCE.md` 可能存在，具体取决于仓库治理策略，但默认脚手架不要求。 ## CLI 命令合约模式 - 模式：CLI 命令合约 — 产生 JSON 的 Playbook CLI 命令必须维护稳定的输出合约，以便 AI 代理和自动化可以依赖确定性字段。 - 模式：CLI 快照合约测试 — `packages/cli/test/cliContracts.test.ts` 将 `rules --json`, `explain --json`, `index --json`, `verify --json`, 和 `plan --json` 的确定性 JSON 负载快照到 `tests/contracts/*.snapshot.json`；仅在合约变更是有意为之时运行 `pnpm test:update-snapshots`。 - 模式：CLI 冒烟测试 — 所有 CLI 命令都应由自动化冒烟测试执行，以防止运行时回归。 - 规则：CLI 业务逻辑位置 — CLI 命令必须保持为引擎功能的薄包装器。 - 模式：演示对齐 — Playbook 核心仓库必须保证演示仓库使用的命令保持稳定和可测试。 ## 架构 本仓库中的架构图由 Playbook 自动生成。 从本仓库本地运行（内部执行）： ``` pnpm -r build node packages/cli/dist/main.js diagram --repo . --out docs/ARCHITECTURE_DIAGRAMS.md ``` 对于消费者安装的使用，运行： ``` npx --yes @fawxzzy/playbook diagram ``` 或在此处查看生成的图表： - [docs/ARCHITECTURE_DIAGRAMS.md](docs/ARCHITECTURE_DIAGRAMS.md) 这确保架构文档始终反映实际的仓库结构。 ## 配合 GitHub Actions 使用 Playbook Playbook 包含一个官方复合操作，支持规范流程的确定性 CI 自动化： `verify -> plan -> review -> apply -> verify` 对于仓库 CI 验证，规范合约门槛是 `playbook verify --json`、路线图合约验证以及 `playbook docs audit --ci --json`（之前需执行 `pnpm -r build` 和 `pnpm test`）。 规则：CI 应强制执行确定性的产品/治理正确性和路线图合约一致性。 故障模式：如果交付工作流规则（路线图链接和文档治理）被记录但未在 CI 中强制执行，路线图漂移会加速。 该操作从检出的仓库源运行（它使用工作区 lockfile 安装，构建 CLI，并调用 `node packages/cli/dist/main.js`）。它**不**需要 `npm install -g` 或发布的 npm 包。 该操作位于本仓库的 `./.github/action.yml` 并接受： - `mode`：`verify | plan | apply` - `plan-artifact`：`mode: apply` 时必需 - `repo-path`：可选，默认为 `.` - `node-version`：可选，默认为 `22` - `verify-args`：可选，默认为 `--ci` ### 可选维护工作流 自动化维护检查（托管文档生成/验证）可以在计划的或手动触发的工作流中运行，位于主 CI 门槛之外： - `pnpm agents:update` - `pnpm agents:check` 请参阅 `.github/workflows/maintenance.yml`。 ### 演示刷新维护工作流 跨仓库 `playbook-demo` 产物/文档刷新自动化与主正确性 CI 路径隔离，并通过专用维护工作流运行： - dry-run/integration: `.github/workflows/demo-integration.yml` - 基于 PR 的刷新编排: `.github/workflows/demo-refresh.yml` `demo-refresh` 使用本地分支构建的 CLI 位（`packages/cli/dist/main.js`）并运行 `scripts/demo-refresh.mjs`，该脚本： - 克隆 `ZachariahRedfield/playbook-demo` - 注入 `PLAYBOOK_CLI_PATH` - 通过包管理器 lockfile 解析刷新执行（npm 用 `npm run