From e23474ef2fb8f528ae89a79bb02fd8aa49c7fa09 Mon Sep 17 00:00:00 2001 From: csh Date: Tue, 27 Jan 2026 17:03:15 +0800 Subject: [PATCH] :memo: docs(playbook): update prompts and sync notes --- README.md | 2 +- playbook.toml.example | 7 +++- templates/README.md | 87 +++++++++++++++++++++++++++++++++++-------- tests/README.md | 2 + 4 files changed, 80 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 7f88b44..77a8d89 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化） `templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板： - `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-stack、architecture、progress、decisions） -- `templates/prompts/`：工作流程模板（agent-behavior、clarify、verify） +- `templates/prompts/`：工作流程模板（agent-behavior、clarify、review） - `templates/AGENTS.template.md`：路由中心模板（项目主入口） - `templates/AGENT_RULES.template.md`：执行流程模板 diff --git a/playbook.toml.example b/playbook.toml.example index 30edfa0..fd09ce1 100644 --- a/playbook.toml.example +++ b/playbook.toml.example @@ -17,13 +17,16 @@ [sync_memory_bank] # 同步 memory-bank/（配置节存在即启用） +# 只更新框架提供的文件，项目新增的文件不会被删除 +# ⚠️ force=true 会覆盖已填写的项目信息（自动备份） # project_name = "MyProject" # 可选：替换 {{PROJECT_NAME}} -# force = false # 可选：覆盖已有目录（会先备份） +# force = false # 可选：覆盖已有文件（会先备份） # no_backup = false # 可选：跳过备份 [sync_prompts] # 同步 docs/prompts/（配置节存在即启用） -# force = false # 可选：覆盖已有目录（会先备份） +# 只更新框架提供的文件，项目新增的文件不会被删除 +# force = false # 可选：覆盖已有文件（会先备份） # no_backup = false # 可选：跳过备份 [sync_standards] diff --git a/templates/README.md b/templates/README.md index 6a17cc4..548252d 100644 --- a/templates/README.md +++ b/templates/README.md @@ -19,9 +19,11 @@ templates/ │ ├── README.md │ ├── system/ │ │ └── agent-behavior.template.md -│ └── coding/ -│ ├── clarify.template.md -│ └── verify.template.md +│ ├── coding/ +│ │ ├── clarify.template.md +│ │ └── review.template.md +│ └── meta/ +│ └── prompt-generator.template.md ├── ci/ # CI 模板 │ └── gitea/ │ └── .gitea/workflows/ @@ -35,6 +37,58 @@ templates/ └── ... ``` +## 文件分类 + +从部署角度，文件分为四类： + +| 类型 | 说明 | 部署行为 | +|------|------|----------| +| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 | +| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 | +| **项目私有** | 项目手动创建 | 不部署 | +| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 | + +### 框架模板（A类） + +``` +AGENT_RULES.md +AGENTS.md（区块更新） +docs/prompts/system/*.md # 框架提供 +docs/prompts/coding/*.md # 框架提供 +docs/prompts/meta/*.md # 框架提供 +``` + +### 项目上下文（B类） + +``` +memory-bank/ +├── project-brief.md +├── tech-stack.md +├── architecture.md +├── progress.md +└── decisions.md +``` + +> ⚠️ B类文件首次创建后应由项目填写。`force=true` 会覆盖已填写内容（自动备份）。 + +### 项目私有（C类，不部署） + +``` +AGENT_RULES.local.md # 项目私有规则 +docs/plans/ # 项目实施计划 +docs/prompts/custom/ # 项目自定义提示词 +docs/prompts/**/* # 项目新增的文件不会被删除 +``` + +### 参考资料（D类，不部署到项目根） + +``` +# 留在 docs/standards/playbook/templates/ 中参考 +ci/ # CI 配置 +cpp/ # C++ 配置 +python/ # Python 配置 +``` + ## 快速部署 使用统一入口 `playbook.py`，配置节存在即启用： @@ -74,7 +128,8 @@ python docs/standards/playbook/scripts/playbook.py -config playbook.toml - **配置节存在即启用**：只写需要同步的配置节 - **AGENTS.md**：始终按区块更新（``），不受配置节控制 -- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（memory-bank/ 和 prompts/ 会先备份） +- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份） +- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除 - **占位符替换**：自动替换 `{{DATE}}`、`{{PLAYBOOK_SCRIPTS}}` 等 ### 典型场景 @@ -112,9 +167,10 @@ project/ └── docs/prompts/ # 提示词库 ├── README.md ├── system/agent-behavior.md - └── coding/ - ├── clarify.md - └── verify.md + ├── coding/ + │ ├── clarify.md + │ └── review.md + └── meta/prompt-generator.md ``` ## 占位符说明 @@ -151,21 +207,22 @@ project/ ### prompts/ -工作流程模板： +工作流程模板（部署后去掉 `.template` 后缀）： -| 文件 | 用途 | -| ----------------------------------- | ------------ | -| `system/agent-behavior.template.md` | AI 行为规范 | -| `coding/clarify.template.md` | 需求澄清模板 | -| `coding/verify.template.md` | 验证检查清单 | +| 文件 | 用途 | 使用场景 | +| ----------------------------------- | -------------- | ---------------------- | +| `system/agent-behavior.template.md` | 工作模式参考 | 切换探索/开发/调试模式 | +| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 | +| `coding/review.template.md` | 复盘总结模板 | Plan 完成后复盘 | +| `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词 | ### AGENT_RULES.template.md 执行流程规范，定义 AI 的工作循环和约束。 如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`， 且不会被 `playbook.py` 覆盖。 -主循环会根据 `memory-bank/progress.md` 的 Plan 状态与 `docs/plans/` 文件名日期， -自动选择最新未完成的 Plan，并要求通过 `scripts/plan_progress.py` 写入进度。 +主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单， +自动选择第一个 pending 的 Plan，并要求通过 `scripts/plan_progress.py` 写入状态。 ### 示例：不跑测试的计划提示词 diff --git a/tests/README.md b/tests/README.md index 487689c..7f25ef3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -11,6 +11,8 @@ tests/ │ └── test_playbook_cli.py # playbook.py 基础功能测试 ├── test_format_md_action.py # format_md 动作测试 ├── test_gitattributes_modes.py # gitattr_mode 行为测试 +├── test_sync_directory_actions.py # sync_memory_bank/sync_prompts 行为测试 +├── test_vendor_snapshot_templates.py # vendor 快照模板完整性测试 ├── test_plan_progress_cli.py # plan_progress CLI 测试 ├── test_superpowers_list_sync.py # superpowers 列表一致性测试 ├── test_sync_templates_placeholders.py # 占位符替换测试（sync_rules/sync_standards）