csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat(playbook): add plan progress tracking and rules updates

Browse Source
This commit is contained in:
csh
2026-01-26 16:51:23 +08:00
parent 6efd637119
commit 278750e3c9
23 changed files with 919 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/AGENTS.template.md
+9 -30
View File
@@ -2,15 +2,6 @@
<!-- playbook:framework:start -->
## 规则优先级
1. 系统/开发者指令与安全约束
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
3. 仓库规则：`.agents/` 与本文件
4. `AGENT_RULES.md` - 执行流程
---
## 快速导航
<!-- playbook:agents:start -->
@@ -25,35 +16,23 @@
### 核心规则
- **项目私有规则**：[AGENT_RULES.local.md](./AGENT_RULES.local.md)
- **执行流程**：[AGENT_RULES.md](./AGENT_RULES.md)
- **AI 行为规范**：[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
- [AGENT_RULES.md](./AGENT_RULES.md) - 执行流程与优先级
### 项目上下文
- **项目定位**：[memory-bank/project-brief.md](memory-bank/project-brief.md)
- **技术栈**：[memory-bank/tech-stack.md](memory-bank/tech-stack.md)
- **架构设计**：[memory-bank/architecture.md](memory-bank/architecture.md)
- **进度追踪**：[memory-bank/progress.md](memory-bank/progress.md)
- **架构决策**：[memory-bank/decisions.md](memory-bank/decisions.md)
- [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位
- [memory-bank/tech-stack.md](memory-bank/tech-stack.md) - 技术栈
- [memory-bank/architecture.md](memory-bank/architecture.md) - 架构设计
- [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪
- [memory-bank/decisions.md](memory-bank/decisions.md) - 架构决策
### 工作流程
- **需求澄清**：[docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md)
- **验证检查**：[docs/prompts/coding/verify.md](docs/prompts/coding/verify.md)
- [docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md) - 需求澄清
- [docs/prompts/coding/verify.md](docs/prompts/coding/verify.md) - 验证检查
- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - AI 行为规范
<!-- playbook:templates:end -->
---
## 新会话开始时
**AI 应该做的**：
1. 读取 [AGENT_RULES.local.md](./AGENT_RULES.local.md)（如存在）
2. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
3. 读取 [memory-bank/](memory-bank/) 核心文档
4. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
5. 查看 `docs/plans/` 下最新计划（如有）
<!-- playbook:framework:end -->
---
templates/AGENT_RULES.template.md
+33 -19
View File
@@ -9,28 +9,44 @@
3. 仓库规则：`.agents/` 与 `AGENTS.md`
4. 本文件
## 安全红线
- 不得在代码/日志/注释中写入明文密钥、密码、Token
- 修改鉴权/权限逻辑必须说明动机与风险
- 不确定是否敏感时按敏感信息处理
## 上下文加载（每次会话开始）
**必读文档**（按顺序）：
1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
2. `memory-bank/project-brief.md` - 项目定位、边界、约束
3. `memory-bank/tech-stack.md` - 技术栈、工具链
4. `memory-bank/architecture.md` - 架构设计、模块职责
5. `docs/plans/` - 最新实施计划（如存在）
2. `.agents/index.md` - 语言规则入口（如存在）
3. `memory-bank/project-brief.md` - 项目定位、边界、约束
4. `memory-bank/tech-stack.md` - 技术栈、工具链
5. `memory-bank/architecture.md` - 架构设计、模块职责
6. `memory-bank/decisions.md` - 重要决策记录（如存在）
7. `memory-bank/progress.md` - 执行进度与状态（如存在）
8. `docs/plans/` - 最新实施计划（如存在）
**目的**：让 AI 快速理解项目全貌，避免重复解释。
## 主循环
1. 选择当前 Plan 文档（优先 `docs/plans/` 最新计划）
2. 阅读 Plan 内容与执行顺序
3. 执行该 Plan 内所有可执行子任务
4. 校验输出结果（运行测试/检查日志）
5. **更新 `memory-bank/progress.md`**（记录已完成事项）
6. 如存在歧义/风险/决策点，在回复中明确提出，并视需要记录到 `memory-bank/decisions.md`
7. 若 Plan 已全部完成，更新 Plan 状态并在 `memory-bank/progress.md` 记录完成
8. 若 Plan 因缺少信息而阻塞，在 `memory-bank/progress.md` 标记阻塞原因
0. 选择 Plan：
- 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
- 如无可执行 Plan，说明情况并询问用户下一步（新增 Plan/切换任务/结束）
1. 标记开始：
- `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md`
2. 阅读 Plan：
- 理解目标、子任务与验证标准
3. 逐步执行：
- 按顺序执行子任务
- 每步完成后进行必要验证（测试/日志/diff）
- 遇到阻塞立即记录并停止
4. 记录结果（写入 `memory-bank/progress.md`）：
- 完成：`python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status done -progress memory-bank/progress.md`
- 阻塞：`python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status blocked -progress memory-bank/progress.md -note <原因>`
5. 如存在歧义/风险/决策点，在回复中明确提出，并视需要记录到 `memory-bank/decisions.md`
## Plan 规则
@@ -39,11 +55,9 @@
- `Parent Plan`（上层/集成计划链接）
- `Verification Scope`（local 或 integration）
- `Verification Gate`（must-pass）
- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 brainstorming 阶段解决后再产出 Plan
- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan
- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
- 不因等待确认而中断可执行步骤；待确认事项在回复中列出
- 执行并验证该 Plan 中所有可执行的子任务
- 若因缺少信息/决策而阻塞：在 `memory-bank/progress.md` 记录阻塞原因
- 每轮只处理一个 Plan
- **小步快跑**：每个 Plan 应该可快速完成
- **可验证**：每个 Plan 必须包含验证步骤
@@ -60,7 +74,7 @@
- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
- **待确认事项**：在回复中列出并等待确认
- **进度留痕**：记录到 `memory-bank/progress.md`（持久化）
- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/plan_progress.py` 写入 `memory-bank/progress.md`，该文件为 Plan 状态唯一权威
## 需要确认的场景
@@ -75,11 +89,11 @@
每个 Plan 完成后，必须验证：
- [ ] 代码修改符合 `.agents/` 下的规则
- [ ] 相关测试通过
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
- [ ] 相关测试通过（如有测试且未被豁免）
- [ ] 换行符正确
- [ ] 无语法错误
- [ ] 更新了 `memory-bank/progress.md`
- [ ] 已更新 `memory-bank/progress.md`
---
templates/README.md
+28 -16
View File
@@ -53,7 +53,7 @@ full = false
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
```
参数说明见 `docs/standards/playbook/playbook.toml.example`。
参数说明见 `playbook.toml.example`（仓库根目录）或 vendoring 后的 `docs/standards/playbook/playbook.toml.example`。
### 部署行为
@@ -92,12 +92,18 @@ project/
| 占位符 | 说明 | 自动替换 |
| ------------------------- | ------------ | -------- |
| `{{DATE}}` | 日期 | ✅ 是 |
| `{{PROJECT_NAME}}` | 项目名称 | ❌ 手动 |
| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 |
| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 |
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 |
| `{{MAIN_LANGUAGE}}` | 主语言 | ❌ 手动 |
| `{{MAIN_LANGUAGE}}` | 主语言 | ✅ 可选 |
| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 |
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
`{{PROJECT_NAME}}` 可通过 `sync_templates.project_name` 自动替换；未配置时保持原样。
`{{MAIN_LANGUAGE}}` 可通过 `sync_templates.main_language` 或 `sync_standards.langs[0]` 自动替换；
未配置时默认 `tsl`。
`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）。
## 模板说明
### memory-bank/
@@ -126,7 +132,9 @@ project/
执行流程规范，定义 AI 的工作循环和约束。
如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
且不会被同步脚本覆盖。
且不会被 `playbook.py` 覆盖。
主循环会根据 `memory-bank/progress.md` 的 Plan 状态与 `docs/plans/` 文件名日期，
自动选择最新未完成的 Plan，并要求通过 `scripts/plan_progress.py` 写入进度。
### 示例：不跑测试的计划提示词
@@ -170,27 +178,30 @@ project/
### ci/、cpp/、python/
语言和 CI 配置模板。通过 playbook.py 的 `[sync_templates]` 部署：
语言和 CI 配置模板。通过 playbook.py 的 `[vendor]` 复制到快照中：
| 目录 | 内容 | 部署位置 |
| ----------- | ----------------------------------------- | ---------- |
| `ci/gitea/` | Gitea Actions 工作流 | `.gitea/` |
| `cpp/` | .clang-format, .clangd, CMakeLists.txt 等 | 项目根目录 |
| `python/` | pyproject.toml, .editorconfig 等 | 项目根目录 |
| 目录 | 内容 | 部署位置 |
| ----------- | ----------------------------------------- | ------------------------ |
| `ci/gitea/` | Gitea Actions 工作流 | 快照 `templates/ci/` |
| `cpp/` | .clang-format, .clangd, CMakeLists.txt 等 | 快照 `templates/cpp/` |
| `python/` | pyproject.toml, .editorconfig 等 | 快照 `templates/python/` |
> 注意：这些模板通过 `[vendor]` 复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。
**使用方式**：
```toml
# playbook.toml
# playbook.toml - 生成包含这些模板的快照
[playbook]
project_root = "/path/to/project"
[sync_templates]
project_name = "MyProject"
[vendor]
langs = ["tsl", "cpp", "python"]
```
```bash
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
python scripts/playbook.py -config playbook.toml
# 然后手动从 docs/standards/playbook/templates/ 复制所需配置到项目根目录
```
## 与 playbook 其他部分的关系
@@ -202,7 +213,8 @@ playbook/
├── docs/ # 权威静态文档
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/
└── playbook.py # 统一入口：vendor/sync_templates/sync_standards/...
├── playbook.py # 统一入口：vendor/sync_templates/sync_standards/...
└── plan_progress.py # Plan 选择与进度记录
```
## 完整部署流程
@@ -218,4 +230,4 @@ python docs/standards/playbook/scripts/playbook.py -config playbook.toml
---
**最后更新**：2026-01-21
**最后更新**：2026-01-26
templates/ci/README.md
+3
View File
@@ -6,6 +6,9 @@
- `gitea/`：Gitea Actions（GitHub Actions 语法）
说明：`templates/ci/gitea/.gitea/` 结构用于与目标项目根目录的 `.gitea/`
保持一致，便于直接复制到项目根目录。
## 使用（Gitea Actions）
前提：目标项目已经 vendoring Playbook（例如 `docs/standards/playbook/`）。
templates/memory-bank/progress.template.md
+5 -34
View File
@@ -1,32 +1,8 @@
# 开发进度追踪
## 当前阶段：{{CURRENT_PHASE}}
## 已知问题
### 最近完成
#### {{DATE}}
- [x] {{COMPLETED_1}}
- [x] {{COMPLETED_2}}
### 进行中
- [ ] {{IN_PROGRESS_1}}
- [ ] {{IN_PROGRESS_2}}
### 待办
#### {{CATEGORY_1}}
- [ ] {{TODO_1}}
- [ ] {{TODO_2}}
#### {{CATEGORY_2}}
- [ ] {{TODO_3}}
- [ ] {{TODO_4}}
### 已知问题
<!-- 记录已知但暂不解决的问题 -->
#### {{ISSUE_CATEGORY_1}}
@@ -34,7 +10,7 @@
- **临时方案**：{{WORKAROUND_1}}
- **长期方案**：{{SOLUTION_1}}
### 里程碑
## 里程碑
#### M1: {{MILESTONE_1}}（目标：{{TARGET_DATE_1}}）
@@ -46,14 +22,9 @@
- [ ] {{MILESTONE_2_TASK_1}}
- [ ] {{MILESTONE_2_TASK_2}}
---
## Plan 状态记录
## 更新日志
### {{DATE}}
- {{LOG_1}}
- {{LOG_2}}
<!-- 由 plan_progress.py 自动管理，请勿手动编辑此节内容 -->
---