ZachariahRedfield/fawxzzy-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`、`knowledge`、`deps`、`ask --repo-context`、`explain` - **治理内核**：`verify` - **变更桥接**：`plan -> apply -> verify` - **交付面**：同一引擎可通过 CLI、CI、自动化及集成方式使用 这一框架是核心承诺：确定性证据优于临时推断，执行前需经审查的意图。 面向操作员的文本界面应保持简短精炼：优先展示决策/状态、受影响面、阻塞点及下一步行动，而将机器重度状态保留在 JSON 契约和 `.playbook/*` 制品中。 - 规则：面向人类的界面应展示决策、行动及原因，而非原始机器状态。 - 模式：制品丰富、界面精简可加速审查。 - 失效模式：让人类解析面向机器的制品会拖慢审查，并将重要决策挤出可见面。 近期实现说明：`pnpm playbook test-autofix --input --json` 现通过编排 `test-triage`、`test-fix-plan`、`apply --from-plan` 以及分类阶段已发出的精确窄优先重试计划，闭环有限的测试修复流程，同时保留相同的受审查执行边界与明确的最终状态分类。 近期实现说明：`test-autofix` 现也会持久化 `.playbook/test-autofix-history.json`，作为有限自修复的证据层，记录稳定的失败签名、采纳与排除的发现、应用的修复类别、验证结果，以及回溯至失败日志、分类制品、修复计划制品、应用结果与最终 autofix 制品的溯源，以便在重试策略自动化前让重复检测变得可信。 近期实现说明：`pnpm playbook test-fix-plan --from-triage --json` 现在在诊断后暴露有限的修复接缝，仅将预先批准的低风险 `test-triage` 发现转为稳定的兼容 apply 的任务，同时将高风险或不支持的发现保留为显式排除。这些制品现可被 `pnpm playbook apply --from-plan` 直接接收，复用现有的已批准计划执行边界，而非引入单独的变更路径。 近期实现说明：`test-autofix` 现在在历史查询与变更之间评估确定性的重复感知修复策略，使用稳定失败签名加修复历史允许一次有限的修复尝试、将先前成功的修复类别作为优先引导，或在重放已知错误修复前停止/升级。该切片每次运行仍仅执行一次有限修复尝试，不引入递归 autofix 循环。 近期实现说明：`pnpm playbook remediation-status --json` 现在是面向操作员的规范只读观测界面，聚合最新 autofix 结果、修复历史、稳定失败签名、重复策略决策、优先修复类别、阻塞的重试、安全可重试签名、置信度校准桶、失败类别成功率、阻塞低置信度遥测、保守置信度建议信号，以及针对失败类别、修复类别、阻塞签名、阈值反事实、dry-run/apply 差异、人工审查压力的确定性观测汇总，使信任不再依赖手工读取原始制品。该遥测仅用于调优/观察，不扩大变更权限或引入第二套策略引擎。 近期实现说明：仓库 CI 现在将失败的 `pnpm test` 输出捕获至 `.playbook/ci-failure.log`，在受保护分支上以 dry-run 模式运行规范 `test-autofix`，要求在任何变更路径被允许前 `autofix_confidence >= confidence_threshold`，在 dry-run 和 apply 两种模式下均上传生成的 `.playbook/` 修复制品，并从这些制品渲染一条粘性 PR 修复评论，而不引入工作流本地修复逻辑。 近期实现说明：`pnpm playbook test-triage` 现在兼任 Playbook 的一流失败摘要界面，将 Vitest/pnpm/GitHub Actions 失败归一化为确定的 `status`、`summary`、`primaryFailureClass`、`failures[]`、`crossCuttingDiagnosis[]` 和 `recommendedNextChecks[]` 字段，同时保留原始 CI 日志以供审计。CI 现发出 `.playbook/failure-summary.json` 和 `.playbook/failure-summary.md`，并将 markdown 摘要直接追加到 GitHub 步骤摘要，提供开箱即复制粘贴的修复上下文。 近期实现说明：`pnpm playbook learn doctrine --json` 现在提供一流的仅报告合并后学习界面，将合并变更摘要转为可复用的规则/模式/失效模式建议、笔记更新指引以及候选未来验证检查，而不会自动将 doctrine 提升为真实来源文档。 近期实现说明：已提升的可复用模式现携带显式生命周期状态（`active`、`superseded`、`retired`、`demoted`），生命周期变更通过 `pnpm playbook promote pattern-retire|pattern-demote|pattern-recall|pattern-supersede` 发出审计回执，建议规划上下文默认仅消费活跃的已提升知识。 近期实现说明：`pnpm playbook receipt ingest --json` 现在将回执、漂移信号、回滚/停用笔记、提升历史及后续可移植性结果转为可审查的 `.playbook/memory/lifecycle-candidates.json` 行，这些行保持仅候选状态，直到进行显式人工生命周期审查。 近期实现说明：`pnpm playbook docs consolidate --json` 现在为受保护单例叙事面提供仅确定性提案的文档接缝，读取工作者片段及受保护面注册表，写入 `.playbook/docs-consolidation.json`，显式暴露重复/冲突的片段目标，并输出一份紧凑的主代理集成简报，而不引入新的文档变更执行器。 近期实现说明：`pnpm playbook docs consolidate-plan --json` 现在将 `.playbook/docs-consolidation.json` 编译为一流的 `.playbook/docs-consolidation-plan.json` 受审查写入制品，将目标锁定的文件/块指纹或锚点上下文标记到每个可执行任务，因此如果受审查的受保护文档目标在执行前发生漂移，`pnpm playbook apply --from-plan .playbook/docs-consolidation-plan.json` 将失败关闭。受保护单例文档仍仅通过 `apply --from-plan` 变更，因此合并规划不会成为影子执行器。 ## 共享核心，项目本地智能 Playbook 采用 **共享核心 + 项目本地 Playbook 状态** 的集成模型： - Playbook 产品（CLI/引擎/契约）是共享核心。 - Playbook 设计为 **按仓库安装**，而非必需的全局二进制。 - 在消费方仓库安装 Playbook 会创建 **项目本地 Playbook 状态**（配置、索引/制品、计划及仓库特定扩展），默认并非分叉。 - 仓库观察默认保持本地/私有。 - 可复用模式和产品改进被有意向上游提升（docs/roadmap/rules），而非通过隐藏变更进行。 模式：**默认私有优先**。标准 Playbook 使用不意味着自动向上游导出内容。 模式：**配置/插件/规则包优先于分叉**，用于项目特定定制。 ## 运行时制品与存储 Playbook 使用 `.playbook/` 作为本地运行时制品的默认主目录（例如仓库智能索引、计划和机器可读报告）。 Playbook 还在 `exports/lifeline/` 下发布签入的机器可读 Lifeline 预设，以便外部工具可直接从本地 Playbook 检出消费稳定默认值，而无需启动 Playbook UI。 ### 使用 Lifeline 运行 Playbook Playbook 可同时用作 Lifeline 约定源和应用目标运行时，来自同一本地检出： - `exports/lifeline/` 故意保持稀疏和通用，用于共享原型默认值。 - `.lifeline/playbook.lifeline.yml` 是本仓库签入的显式可运行应用目标。 在同时检出两个仓库的本地机器上： ``` lifeline resolve .lifeline/playbook.lifeline.yml --playbook-path lifeline up .lifeline/playbook.lifeline.yml --playbook-path lifeline status playbook lifeline logs playbook lifeline down playbook ``` 由 Lifeline 启动的应用进程是 `pnpm start:lifeline`，保留了正常的本地 Playbook CLI 和基于终端的开发流程。 Playbook 路由检查通过 `pnpm playbook route "" --json` 在 `.playbook/execution-plan.json` 发出仅确定性提案的执行计划。 - 生成的运行时制品通常应被 gitignore，除非有意提交为稳定契约/示例。 - `.playbook/demo-artifacts/` 下提交的演示制品是面向产品的快照契约和示例，而非通用运行时日志。 - 允许提交的 `.playbook` 内容仅限于精选的契约/示例夹具（`.playbook/demo-artifacts/*.example.json`）和显式治理元数据（`.playbook/pr-metadata.json`）；生成的运行时输出如 `.playbook/repo-index.json` 和 `.playbook/repo-graph.json` 必须保持未跟踪。 - Playbook 默认保持本地/私有优先：本地扫描和制品生成不意味着自动云同步或向上游导出。 模式：运行时制品存放在 `.playbook/` 下。 模式：演示制品是快照契约，非通用运行时状态。 规则：生成的运行时制品应被 gitignore，除非有意提交为稳定契约/示例。 规则：Playbook 默认保持本地/私有优先。 失效模式：每次运行重新提交生成的运行时制品会导致不必要的仓库历史增长和审查噪音。 ## Playbook 制品生命周期 Playbook 将仓库制品分类为确定性存储类别： - **运行时制品**：本地输出，如 `.playbook/repo-index.json`、`.playbook/plan.json`、`.playbook/verify.json`、`.playbook/session.json`、会话清理报告和缓存文件。 - **自动化制品**：CI 交接输出，如 CI 计划和验证制品。 - **契约制品**：提交的快照和文档契约，如 `tests/contracts/*.snapshot.json`、`.playbook/demo-artifacts/*` 和生成的图表文档。 使用 `.playbookignore` 控制 `pnpm playbook index` 和其他仓库扫描的仓库智能扫描范围。语法与 `.gitignore` 类似。 安全引导流程： ``` pnpm playbook pilot --repo "" --json pnpm playbook ignore suggest --repo "" --json pnpm playbook ignore apply --repo "" --safe-defaults ``` `ignore suggest` 读取排序的运行时建议并报告哪些条目已被覆盖。`ignore apply --safe-defaults` 仅将 `safe-default` 条目写入确定性托管块，并将 `review-first` 建议留作人工审查项。 `pnpm playbook doctor` 现在包含一个 **Playbook Artifact Hygiene** 部分，用于检测制品误用并建议确定性修复。 ## 快速开始（规范阶梯） Playbook 操作员工作流假定 **仓库本地 CLI 安装**（例如通过 `pnpm playbook ...` 使用 `node_modules/.bin/playbook`），因此干净的机器和 CI 不依赖 PATH 全局 Playbook 二进制。 ### 命令真值 - 规范的面向操作员调用形式是 `pnpm playbook `。 - 通过 `node packages/cli/dist/main.js ` 直接执行是内部/调试导向的，除非在实现工作流中明确指出。 - 除非 Playbook 发布/分发文档明确重新引入该路径，否则不要在操作员指引中使用基于 `npx` 的包示例。 运行规范的首选 Playbook 操作阶梯： ``` pnpm playbook ai-context --json pnpm playbook ai-contract --json pnpm playbook context --json pnpm playbook index --json pnpm playbook query modules --json pnpm playbook explain architecture --json pnpm playbook ask "where should a new feature live?" --repo-context --json pnpm playbook verify --json pnpm playbook plan --json --out .playbook/plan.json pnpm playbook apply --from-plan .playbook/plan.json pnpm playbook apply --from-plan .playbook/test-fix-plan.json pnpm playbook test-autofix --input .playbook/ci-failure.log --json pnpm playbook verify --json ``` `analyze` 仍可用于兼容性和轻量级栈检查，但不再是唯一严肃的快速开始路径。 对于本仓库内的本地分支精确验证，建议使用： ``` pnpm playbook plan --json --out .playbook/plan.json pnpm playbook apply --from-plan .playbook/plan.json --json ``` PowerShell 安全本地等价命令： ``` pnpm playbook plan --json --out .playbook/plan.json pnpm playbook apply --from-plan .playbook/plan.json --json ``` 无安装预览流程： ``` pnpm playbook demo ``` `pnpm playbook demo` 遵循相同的规范严肃用户阶梯（`ai-context -> ai-contract -> context -> index -> query/explain -> verify -> plan -> apply -> verify`），不以 `fix` 作为主要入门路径。 ### 外部仓库定位 使用 `--repo ` 从此 monorepo 对另一个本地仓库运行 Playbook，无需更改目录： ``` TARGET_REPO_PATH="../my-repo" pnpm playbook --repo "$TARGET_REPO_PATH" index --json pnpm playbook --repo "$TARGET_REPO_PATH" query modules --json ``` 这保持 `pnpm playbook ` 作为规范调用，同时让操作员从单个工作检出确定性定位外部仓库。 ### 消费方仓库运行时解析契约 消费方仓库应按此确定性顺序解析 Playbook： 1. `PLAYBOOK_BIN` 覆盖（显式操作员/CI 选择）。 2. 仓库本地安装的 CLI（`node_modules/.bin/playbook`，通常通过 `pnpm ...`）。 3. 可选本地检出开发回退（非规范；仅作为临时开发辅助）。 4. 显式失败并提供可操作的指引。 规则： - 基于 PATH 全局的 `playbook` 解析是非规范的，绝不能作为成功操作的必需条件。 - 缺失运行时解析必须大声失败并提供可操作的设置指引；不允许静默 PATH 假设。 - 开发回退必须保持选入，且不能成为默认运行时路径。 当设置 `--repo` 时，运行时制品写入目标仓库的 `.playbook/` 下（例如 `repo-index.json`、`repo-graph.json`、`findings.json`、`plan.json` 和运行时周期制品）。 对于机器消费的 JSON 制品，使用 CLI 拥有的输出标志（例如 `--json --out ...`）。Shell 重定向不是受支持的规范制品生成路径。 ### 外部仓库试点 规范命令： ``` pnpm playbook pilot --repo "C:\Users\zjhre\dev\FawxzzyFitness" ``` 可选便捷别名： ``` pnpm playbook pilot --repo "C:\Users\zjhre\dev\FawxzzyFitness" ``` 可选便捷别名： ``` pnpm pilot "C:\Users\zjhre\dev\FawxzzyFitness" ``` `playbook pilot` 执行一个确定性基线周期（`context -> index -> query modules -> verify -> plan`），直接写入机器可读制品，记录一个顶级运行时周期及其子阶段，并输出紧凑的最终摘要。 写入目标仓库的制品： - `.playbook/repo-index.json` _（仅运行时，gitignored）_ - `.playbook/repo-graph.json` _（仅运行时，gitignored）_ - `.playbook/findings.json` _（仅运行时，gitignored）_ - `.playbook/plan.json` _（仅运行时，gitignored）_ - `.playbook/pilot-summary.json` _（仅运行时，gitignored）_ - `.playbook/runtime/current/*` _（仅运行时，gitignored）_ - `.playbook/runtime/cycles/*` _（仅运行时，gitignored）_ - `.playbook/runtime/history/*` 规则 - 重复的多步操作员工作流应获得一流命令。 模式 - 编排基线分析。 失效模式 - 人工工作流漂移。 失效模式 - 辅助脚本成为影子产品面。 外部入门契约（最小）： - `playbook.config.json` 是可选的；缺失配置不是失败，Playbook 以默认值运行。 - `.playbookignore` 是可选的；添加它以调整大型/高变动路径的仓库扫描范围。 - `.playbook/` 是运行时生成的 Playbook 状态，由 Playbook 命令为目标仓库拥有。 - 首次运行警告指引是可操作的：当需要显式策略/配置时添加 `playbook.config.json`，当需要缩小扫描范围时添加 `.playbookignore`。 `pilot` 后的推荐后续： ``` pnpm playbook ignore suggest --repo "C:\Users\zjhre\dev\FawxzzyFitness" --json pnpm playbook ignore apply --repo "C:\Users\zjhre\dev\FawxzzyFitness" --safe-defaults ``` 规则 - 仅应用受信任的忽略建议。 模式 - 建议先于应用，安全默认值先于审查。 失效模式 - 自动应用模糊的忽略。 失效模式 - 非幂等的忽略管理。 ## 示例输出 `pnpm playbook verify` 和 `pnpm playbook plan` 为人类和 AI 代理提供确定性、可审查的输出。如需完整的演示输出，请使用官方演示仓库： ``` git clone https://github.com/ZachariahRedfield/playbook-demo cd playbook-demo npm install pnpm playbook ai-context --json pnpm playbook index --json pnpm playbook verify --json # bash/zsh pnpm playbook plan --json --out .playbook/plan.json # PowerShell-safe pnpm playbook plan --json --out .playbook/plan.json pnpm playbook apply --from-plan .playbook/plan.json pnpm playbook verify --json ``` ## CLI 命令 ### 核心 - `analyze` - `verify` - `plan` - `apply` ### 仓库工具 - `doctor` - `diagram` - `rules` - `docs` - `schema` - `ignore` - `context` - `ai-context` - `ai-contract` ### 仓库智能 - `index` - `graph` - `query` - `knowledge` - `deps` - `ask` - `explain` 完整命令清单（包括实用命令），见 [docs/commands/README.md](docs/commands/README.md)。 命令真值打包通过 `packages/cli/src/lib/commandMetadata.ts` 元数据驱动，并生成为 `docs/contracts/command-truth.json`（规范 vs 兼容 vs 实用 + 引导/修复排序）。 运行 `pnpm playbook index` 在 `.playbook/repo-index.json`、`.playbook/repo-graph.json` 和 `.playbook/context/modules/*.json` 下的压缩模块摘要生成确定性机器可读仓库智能制品。 压缩带来的复杂度降低：Playbook 通过提取小型确定性制品（索引 -> 图 -> 模块摘要）并在查询/解释/询问面复用它们，而非重复扫描广泛仓库状态，从而降低仓库复杂度。 使用 `pnpm playbook schema` 获取命令输出的 JSON Schema 契约（`rules`、`explain`、`index`、`graph`、`verify`、`plan`、`context`、`ai-context`、`ai-contract`、`query`、`knowledge`、`docs`），以便 CI 和代理可验证载荷。 ## Playbook Context Playbook 为人类和自动化提供确定性机器可读上下文： - `pnpm playbook context --json` 返回更广泛的 CLI 和架构上下文。 - `pnpm playbook ai-context --json` 返回紧凑的 AI 引导载荷。 - `pnpm playbook ai-contract --json` 返回来自 `.playbook/ai-contract.json` 的仓库 AI 可操作性契约（缺失时为确定性生成的默认值）。 ## AI 引导 AI 工具可通过以下方式引导仓库理解： ``` pnpm playbook ai-context --json pnpm playbook ai-contract --json ``` 载荷设计用于： - AI 代理 - IDE 助手 - CI 自动化 示例 AI 优先流程： ``` pnpm playbook ai-context pnpm playbook context pnpm playbook index pnpm playbook query modules pnpm playbook ask "where should a new feature live?" --repo-context pnpm playbook ask "how does auth work?" --repo-context --mode concise pnpm playbook ask "how does this work?" --module workouts --repo-context pnpm playbook ask "what modules are affected by this change?" --diff-context pnpm playbook ask "how do I fix this rule violation?" --mode ultra pnpm playbook explain architecture pnpm playbook verify pnpm playbook plan pnpm playbook apply ``` 在 AI 引导阶梯中推荐使用 `pnpm playbook context`，在查询/询问/解释前获取更广泛的仓库和 CLI 上下文。 在本仓库内，使用本地构建的 CLI 入口点进行分支精确验证： ``` pnpm -r build pnpm playbook ai-context --json pnpm playbook context --json pnpm playbook docs audit --json ``` 首选 AI 操作阶梯：`ai-context -> ai-contract -> context -> index/query/explain/ask --repo-context -> verify/plan/apply`。 未来应用集成方向：应用或仪表板操作应使用受信任的 **服务端 Playbook API/运行时或库层** 进行已验证操作，而非直接执行任意浏览器端 CLI 命令。 模式：`pnpm 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 命令输出并直接从陈旧或不完整文件检查推理时，发生代理漂移。 ### 查询仓库智能 使用 `pnpm playbook query` 直接从 `.playbook/repo-index.json` 读取结构化架构元数据，无需重新扫描仓库。 对于模块化单体仓库，Playbook 将 `src/features/*` 目录索引为一流模块（当 `src/features/*` 不存在时回退到直接 `src/*` 模块目录）。 ``` pnpm playbook index pnpm playbook query modules pnpm playbook query architecture pnpm playbook query risk workouts pnpm playbook query impact workouts pnpm playbook query docs-coverage pnpm playbook query rule-owners pnpm playbook query test-hotspots pnpm playbook knowledge list pnpm playbook knowledge query --type candidate pnpm playbook ask "where should a new feature live?" pnpm playbook ask "what modules exist?" --json pnpm playbook ask "how does auth work?" --repo-context --mode concise pnpm playbook ask "how does this work?" --module workouts --repo-context pnpm playbook ask "what modules are affected by this change?" --diff-context pnpm playbook ask "how do I fix this rule violation?" --mode ultra pnpm playbook explain workouts pnpm playbook explain PB001 pnpm playbook explain architecture ``` `pnpm playbook knowledge` 是归一化证据、候选知识、已提升 doctrine 和已弃用知识的只读检查面。 ### 仓库感知的 ask（`pnpm playbook ask --repo-context`、`--module`） 在询问仓库形态或架构问题时使用 `--repo-context`。 - 它将受信任的 Playbook 管理的制品（例如 `.playbook/repo-index.json` 和 AI 契约元数据）注入 ask 上下文。 - 它避免广泛的临时仓库文件推断。 - 它首先需要来自 `pnpm playbook index` 的仓库智能。 - `--module ` 将 ask 推理缩小到该模块的受信任索引上下文。 示例： ``` pnpm playbook index pnpm playbook ask "where should a new feature live?" --repo-context pnpm playbook ask "how does auth work?" --repo-context --mode concise pnpm playbook ask "how does this work?" --module workouts --repo-context pnpm playbook ask "what modules are affected by this?" --repo-context --json ``` 如果 `.playbook/repo-index.json` 缺失，ask 返回确定性修复指引以运行 `pnpm playbook index` 并重试。 ### 结构化 PR 智能（`pnpm playbook analyze-pr`） 使用 `pnpm playbook analyze-pr` 从本地 git diff + `.playbook/repo-index.json` 获取确定性、机器可读的变更分析。 - `pnpm playbook ask --diff-context` 是对话式变更推理。 - `pnpm playbook analyze-pr` 是面向自动化和预合并检查的结构化审查/报告面。 - `pnpm playbook analyze-pr --json` 仍是自动化的规范确定性分析契约。 - `pnpm playbook analyze-pr --format ` 仅在该契约之上选择呈现方式。 - `pnpm playbook analyze-pr --format github-comment` 将相同确定性分析契约渲染为 GitHub 就绪的 PR 摘要 markdown 导出。 - `pnpm playbook analyze-pr --format github-review` 渲染源自分析契约中规范发现的确定性内联审查注解（`path`/`line`/`body`）。 - GitHub Actions 传输层现将摘要格式化器输出作为一条粘性 Playbook 摘要评论（``）发布，并同步内联诊断（``），以便新诊断被添加、现有诊断不重复、已解决诊断被移除。 - 工作流层仅是传输：它不在 `analyze-pr --format github-comment` 和 `analyze-pr --format github-review` 之外重建分析或格式化。 - 工作流在 `analyze-pr` 前运行 `pnpm playbook index`，因为仅创建 `.playbook/` 目录不够；`analyze-pr` 消费 `.playbook/repo-index.json`。 - 在 CI pull_request 工作流中，传递显式 diff 基准（例如 `--base origin/${{ github.base_ref }}`）并使用完整历史检出（`fetch-depth: 0`）以进行确定性 diff 解析。 ``` pnpm playbook index pnpm playbook analyze-pr --format text pnpm playbook analyze-pr --json pnpm playbook analyze-pr --format github-comment pnpm playbook analyze-pr --format github-review ``` ### 变更范围 ask（`pnpm playbook ask --diff-context`） 使用 `--diff-context` 借助受信任的本地 diff + 索引智能回答分支/工作树问题。 - 需要 `.playbook/repo-index.json` 和本地 git diff 可用性。 - 产生确定性的变更文件、受影响模块、影响、文档和风险上下文。 - 当 diff 上下文不可用时，从不静默扩展到全仓库推断。 - 可选 `--base ` 将 diff 比较缩小到显式基准（例如 `main`）。 - 在 `--json` 模式下，ask 在 `context.sources` 中包含确定性来源元数据，以便代理/CI 可审计哪些索引智能来源告知了答案（不暴露原始文件内容）。 ``` pnpm playbook index pnpm playbook ask "what modules are affected by this change?" --diff-context pnpm playbook ask "what should I verify before merge?" --diff-context --mode concise pnpm playbook ask "summarize the architectural risk of this diff" --diff-context --json ``` ### AI 响应模式（`pnpm playbook ask --mode`） `pnpm playbook ask` 支持响应模式以控制答案密度。 - `normal`（默认）：带上下文的完整解释 - `concise`：压缩但仍提供信息的输出 - `ultra`：针对快速决策优化的最大压缩 示例： ``` pnpm playbook ask "how does auth work?" pnpm playbook ask "how does auth work?" --repo-context --mode concise pnpm playbook ask "how does this work?" --module workouts --repo-context pnpm playbook ask "what modules are affected by this change?" --diff-context pnpm 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` 和 `docs/contracts/command-truth.json`。 会话知识清理可通过 `pnpm playbook session cleanup --hygiene --dry-run --json-report .playbook/session-cleanup.report.json` 获得确定性归一化/去重/截断/修剪报告。 会话连续性通过 `.playbook/session.json` 进行仓库范围限定和确定性管理，使用 `pnpm playbook session show`、`pnpm playbook session pin `、`pnpm playbook session resume` 和 `pnpm playbook session clear`。 ## 演示 见 [`playbook-demo`](https://github.com/ZachariahRedfield/playbook-demo)，也可通过 `pnpm 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 步骤时使用。 ## 确定性编排工作流 使用 `pnpm playbook orchestrate --goal "" --lanes 3 --format both` 为并行 Codex 计划模式工作者编译治理安全的泳道契约集。实现的 v0 命令写入 `.playbook/orchestrator/orchestrator.json` 加泳道提示 markdown 制品（取决于格式），定义泳道边界/依赖，保持提示对人类紧凑，并将受保护单例文档保留为仅片段贡献而非直接并发编辑。它保持仅控制平面（无工作者启动、分支、PR 或合并自动化）。 使用 `pnpm playbook workers --json` 或 `pnpm playbook workers assign` 从泳道状态就绪度和依赖门导出仅提案的工作者分配契约。这写入 `.playbook/worker-assignments.json` 及 `.playbook/prompts/` 中的每泳道提示交接文件，而不启动工作者、创建分支或自动化 PR，同时将完整机器状态保留在 `.playbook` 制品中而非复制到工作者提示。 ## 入门 运行： ``` pnpm playbook doctor ``` `pnpm playbook doctor` 提供高层仓库健康报告，包括框架、架构、治理检查和建议的下一步操作。 ## AI 环境诊断 运行： ``` pnpm playbook doctor --ai ``` 此命令验证仓库是否正确配置用于 AI 辅助 Playbook 工作流，包括确定性 AI 契约就绪验证（契约可用性/有效性、智能来源、必需命令/查询面和修复工作流就绪）。它是未来 Playbook 代理执行的准备门。 使用 `pnpm playbook doctor --help` 查看 doctor 特定标志，包括 `--ai`。 ## 如何发现能力 CLI 帮助输出是受支持命令和标志的权威来源。 - 使用 `pnpm playbook rules` 列出可用规则。 - 使用 `pnpm playbook explain ` 从 `.playbook/repo-index.json` 和规则注册表确定性解释规则、模块和架构。 ## 初始化脚手架契约 运行： ``` pnpm playbook init ``` 保证以下基线项目制品： - Playbook 配置（`playbook.config.json` 或 `.playbook/config.json`） - `docs/PLAYBOOK_NOTES.md` 其他文档如 `docs/PROJECT_GOVERNANCE.md` 可能存在，取决于仓库治理策略，但默认脚手架不要求。 ## CLI 命令契约模式 - 模式：CLI Command Contract — 产生 JSON 的 Playbook CLI 命令必须维护稳定输出契约，以便 AI 代理和自动化可依赖确定性字段。 - 模式：CLI Snapshot Contract Testing — `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 Smoke Testing — 所有 CLI 命令应通过自动冒烟测试执行，以防止运行时回归。 - 规则：CLI Business Logic Location — CLI 命令必须保持为引擎功能的薄包装。 - 模式：Demo Alignment — Playbook 核心仓库必须保证演示仓库使用的命令保持稳定和可测试。 - 模式：Cross-Repo Pattern Learning — `pnpm playbook patterns cross-repo|portability|generalized|repo-delta` 从 `.playbook/cross-repo-patterns.json` 提供确定性可移植性评分，而不引入自主 doctrine 变更。 ## 架构 本仓库中的架构图由 Playbook 自动生成。 从本仓库本地运行（内部执行）： ``` pnpm -r build pnpm playbook diagram --repo . --out docs/ARCHITECTURE_DIAGRAMS.md ``` 对于消费者安装使用，运行： ``` pnpm playbook diagram ``` 包优先运行时一致性说明：`@fawxzzy/playbook-cli` 现在是一个薄入口包，直接委托给 `@fawxzzy/playbook` 运行时实现，因此消费方仓库获得相同语义的 `.playbook/*` 制品（例如 `findings.json`、`plan.json` 和 `repo-graph.json`），而非仅日志的垫片行为。 或在此查看生成的图： - [docs/ARCHITECTURE_DIAGRAMS.md](docs/ARCHITECTURE_DIAGRAMS.md) 这确保架构文档始终反映实际仓库结构。 ## 使用 Playbook 与 GitHub Actions Playbook 包含一个官方复合操作，支持规范流程的确定性 CI 自动化： `verify -> plan -> review -> apply -> verify` 对于仓库 CI 验证，规范契约门是 `pnpm playbook verify --json`、路线图契约验证和 `pnpm playbook docs audit --ci --json`（在 `pnpm -r build` 和 `pnpm test` 之后）。 规则：CI 应强制执行确定性产品/治理正确性和路线图契约一致性。 失效模式：如果交付工作流规则（路线图链接和文档治理）被记录但未在 CI 中强制执行，路线图漂移会加速。 该操作从检出的仓库源运行（它使用工作区锁文件安装、构建 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` - 通过包管理器锁文件解析刷新执行（npm 用 `npm run