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

📝 docs(tsl): clarify syntax constraints and enhance test infrastructure

Browse Source 
- Add TSF file naming constraint to syntax/02_core_model.md
- Clarify semicolon rules: syntax facts vs style preferences
- Separate control flow end semicolon rules (syntax allows both)
- Add function body semicolon requirements to syntax/05_functions_and_calls.md
- Move style preferences to code_style.md (control flow end semicolons)
- Remove cross-references from syntax docs to maintain independence
- Enhance Gitea workflow emoji for better CI output readability
- Fix CI test path from tests/ to test/
- Organize agent test results under test/agent/result/ directory
- Add complete Chinese translation of test cases (test_cases_zh.md)
- Clean up .gitignore to use unified test/agent/result/ directory
- Remove obsolete agent test artifacts (REPORTS_LOCATION.md, old results)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
csh
2026-06-21 17:04:50 +08:00
co-authored by Claude Opus 4.6
parent 6026401907
commit 8b93311cae
138 changed files with 7018 additions and 1705 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/README.md
+134 -285
View File
@@ -1,202 +1,188 @@
# 项目架构模板
本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的
AI 代理工作环境。
本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 代理工作环境。
## 与 Playbook 其他部分的关系
```text
playbook/
├── rulesets/ # 语言级硬规则 → 部署到 .agents/
├── skills/ # 按需加载的技能
├── docs/ # 权威静态文档
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/
└── playbook.py # 统一入口
```
部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。
## 目录结构
```text
templates/
├── README.md # 本文件
├── AGENTS.template.md # 入口导航模板
├── AGENT_RULES.template.md # superpowers-first 执行规则模板
├── memory-bank/ # 项目上下文模板
│ ├── project-brief.template.md
│ ├── tech-context.template.md
│ ├── system-patterns.template.md
│ ├── active-context.template.md
│ ├── progress.template.md
│ └── decisions.template.md
├── prompts/ # 任务入口模板（不是流程权威）
│ ├── README.md
│ ├── system/
│ │ └── agent-behavior.template.md
│ ├── coding/
│ │ ├── clarify.template.md
│ │ ├── verify-change.template.md
│ │ ├── close-task.template.md
│ │ ├── update-memory.template.md
│ │ └── code-review.template.md
├── ci/ # CI 模板
│ ├── README.md
│ └── gitea/
│ └── .gitea/
│ ├── workflows/
│ └── ci/
├── cpp/ # C++ 配置模板
│ ├── .clang-format
│ ├── .clangd
│ └── ...
└── python/ # Python 配置模板
├── .editorconfig
├── pyproject.toml
└── ...
├── AGENT_RULES.template.md # superpowers 执行规则模板
├── memory-bank/ # 项目上下文模板（6 个）
├── prompts/ # 任务入口模板（6 个 + README）
├── ci/ # CI 配置模板
├── cpp/ # C++ 工具链模板
└── python/ # Python 工具链模板
```
## 文件分类
## 模板分类
从部署角度看，本目录的文件分成三类：
从部署和维护角度，模板分为三类：
- **会同步更新的框架模板**
- `AGENT_RULES.md`
- `docs/prompts/README.md`
- `docs/prompts/system/*.md`
- `docs/prompts/coding/*.md`
- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
- **首次创建后由项目维护的上下文文件**
- `memory-bank/*.md`
- `AGENT_RULES.local.md`
- **只保留在快照中参考的模板**
- `ci/`
- `cpp/`
- `python/`
### 1. 框架模板（会自动更新）
补充说明：
这些文件由 playbook 框架维护，每次同步时可能更新：
- `memory-bank/*.md` 首次创建后应由项目填写；`force=true`
会覆盖已填写内容并先备份。
- `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建，
后续不再覆盖。
- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*`
不会被 playbook 删除。
- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用
`@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/`
只负责把代理导向正确的任务入口。
- `AGENT_RULES.md`
- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
- `docs/prompts/README.md`
- `docs/prompts/system/*.md`
- `docs/prompts/coding/*.md`
## 快速部署
### 2. 项目上下文（首次创建后由项目维护）
以下命令假设 **playbook 已经部署到项目内**，使用统一入口 `playbook.py`，配置节存在即启用：
这些文件首次创建后应由项目填写，`force=true` 会覆盖已填写内容并先备份：
- `memory-bank/*.md`
- `AGENT_RULES.local.md`（首次自动创建，后续不再覆盖）
### 3. 参考模板（需手动复制）
这些模板保留在快照中供参考，需手动复制到项目根目录：
- `ci/`：Gitea Actions 工作流
- `cpp/`：C++ 工具链配置
- `python/`：Python 工具链配置
**补充说明**：
- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*` 不会被 playbook 删除
- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 `@AGENTS.md` 则追加；如已手工引用则跳过
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` 只负责把代理导向正确的任务入口
## 部署方式
使用 `playbook.py` 统一入口部署，通过配置节控制同步内容：
```toml
# playbook.toml
[playbook]
project_root = "/path/to/project"
playbook_root = "docs/standards/playbook"
install_mode = "snapshot"
# 同步 AGENT_RULES.md（配置节存在即启用）
[sync_rules]
# force = true # 可选，强制覆盖已存在的文件
# 同步 memory-bank/（配置节存在即启用）
[sync_memory_bank]
project_name = "MyProject"
# force = true # 可选，强制覆盖（会先备份）
# 同步 docs/prompts/（配置节存在即启用）
[sync_prompts]
# force = true # 可选，强制覆盖（会先备份）
[sync_rules] # 同步 AGENT_RULES.md
[sync_memory_bank] # 同步 memory-bank/
[sync_prompts] # 同步 docs/prompts/
```
```bash
python <playbook_root>/scripts/playbook.py -config playbook.toml
```
详细配置说明见主 README.md 和 playbook.toml.example。
参数说明见 `playbook.toml.example`（仓库根目录）或项目内的
`<playbook_root>/playbook.toml.example`。
## 模板说明
其中 `<playbook_root>` 默认为 `docs/standards/playbook`，
也可以按项目配置改成 `custom/playbook` 等自定义目录；
对应文档入口会变成 `<playbook_root>/docs/...`。
### memory-bank/
如果你当前是在 **外部 clone 的 playbook 仓库** 中执行，而不是在目标项目内执行快照，请使用：
项目上下文文档，用于让 AI 快速理解项目：
```bash
python scripts/playbook.py -config playbook.toml
```
| 文件 | 用途 |
| ----------------------------- | -------------------------- |
| `project-brief.template.md` | 项目定位、边界、约束 |
| `tech-context.template.md` | 技术上下文、工具链、入口 |
| `system-patterns.template.md` | 系统模式、边界、不变量 |
| `active-context.template.md` | 当前目标、最近变更、下一步 |
| `progress.template.md` | 人类摘要 + Plan 状态块 |
| `decisions.template.md` | 架构决策记录（ADR） |
此时 `install_mode = "snapshot"` 会把快照写入 `<project_root>/<playbook_root>`；
后续再在目标项目内使用 `<playbook_root>/scripts/playbook.py`
做同步更新。
### prompts/
### 配置节说明
任务入口模板，部署后去掉 `.template` 后缀。`prompts/README.md` 作为任务入口索引。
- `[sync_rules]`：部署 `AGENT_RULES.md`；必要时创建 `.local.md`。
选项：`force`、`no_backup`、`date`
- `[sync_memory_bank]`：部署 `memory-bank/`。
选项：`project_name`、`force`、`no_backup`、`date`
- `[sync_prompts]`：部署 `docs/prompts/`。
选项：`force`、`no_backup`、`date`
- `[sync_standards]`：部署 `.agents/<lang>/`。
选项：`langs`、`gitattr_mode`、`no_backup`
- `[install_skills]`：部署到 `~/.agents/skills/` 或
`~/.claude/skills/`。
选项：`mode`、`skills`、`agents_home`、`skill_link`、
`no_backup`
| 文件 | 用途 | 使用场景 |
| ----------------------------------- | ------------ | ------------------- |
| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 |
| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 |
| `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 |
| `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 |
| `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 |
| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 |
- **配置节存在即启用**：只写需要同步的配置节
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
- **CLAUDE.md**：自动检测/创建；如已存在 playbook 区块则更新，如未引用 `@AGENTS.md` 则追加，否则跳过
- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
- **no_backup**：默认 false；设为 true 时跳过备份直接覆盖
- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_ROOT}}`、`{{PLAYBOOK_SCRIPTS}}`
### AGENT_RULES.template.md
### 典型场景
执行规则模板，定义 AI 的工作循环和约束。如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 playbook 覆盖。
```toml
# 场景 1：初次部署（全部）
[sync_rules]
[sync_memory_bank]
project_name = "MyProject"
[sync_prompts]
计划编排与执行细节统一指向 `docs/superpowers/`、`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`。
# 场景 2：框架升级（只更新规则）
[sync_rules]
force = true
### AGENTS.template.md
# 场景 3：重置项目上下文
[sync_memory_bank]
project_name = "MyProject"
force = true
```
入口导航模板，作为项目的主入口（Codex 入口）。
### docs/superpowers 命名约定
**设计理念**：
- **最小化内容**：只包含导航链接，不包含详细规则
- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
**playbook 标记**（用于自动更新）：
- `<!-- playbook:agents:start/end -->`：语言规则链接，由 `[sync_standards]` 管理
- `<!-- playbook:templates:start/end -->`：路由链接，`AGENTS.md` 始终按区块更新
- `<!-- playbook:framework:start/end -->`：完整框架，`AGENTS.md` 始终按区块更新
### superpowers 工作流约定
`docs/superpowers/` 统一承载设计稿和实施计划：
- 设计只落到 `specs/`
- 计划只落到 `plans/`
- 执行状态只写回 `memory-bank/progress.md`
为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用：
- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`：
`brainstorming` 产出的设计稿
- `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`：
`writing-plans` 产出的实施计划
- **设计稿**：`specs/YYYY-MM-DD-<topic>-design.md`（`brainstorming` 产出）
- **实施计划**：`plans/YYYY-MM-DD-<topic>.md`（`writing-plans` 产出）
- **执行状态**：回写到 `memory-bank/progress.md`
其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。
### 生命周期总览
完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。
这里仅说明职责分层：
**生命周期**：
- `docs/prompts/`：任务入口层，只负责把代理导向正确入口
- `docs/superpowers/specs/`：设计稿
- `docs/superpowers/plans/`：实施计划与主执行输入
- `memory-bank/progress.md`：执行状态留痕
完整主链只在 `AGENT_RULES.template.md` 定义。
### 语言配置模板（ci/、cpp/、python/）
语言和 CI 配置模板，`install_mode = "snapshot"` 安装快照时会复制这些模板：
- `ci/gitea/`：Gitea Actions 工作流与辅助脚本，部署到快照 `templates/ci/`
- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt` 等文件，部署到快照 `templates/cpp/`
- `python/`：`pyproject.toml`、`.editorconfig` 等文件，部署到快照 `templates/python/`
**使用方式**：这些模板保留在快照中供参考，需手动复制到项目根目录使用。其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录。
## 技术细节
### 占位符说明
模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
| 占位符 | 说明 | 自动替换 |
| ------------------------- | ------------ | -------- |
| `{{DATE}}` | 日期 | ✅ 是 |
| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 |
| `{{PLAYBOOK_ROOT}}` | Playbook 根 | ✅ 是 |
| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 |
| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 |
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 |
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
- `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样
- `{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录（默认 `docs/standards/playbook`）
- `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）
### 部署后的目录结构
```text
project/
├── AGENTS.md # 入口导航（Codex 入口）
├── AGENT_RULES.md # superpowers-first 执行规则
├── AGENT_RULES.md # superpowers 执行规则
├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护）
├── CLAUDE.md # Claude Code 入口（按规则维护/追加 playbook 区块）
├── CLAUDE.md # Claude Code 入口
├── memory-bank/ # 项目上下文
│ ├── project-brief.md
│ ├── tech-context.md
@@ -219,143 +205,6 @@ project/
└── plans/ # writing-plans / main_loop 消费
```
## 占位符说明
模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
| 占位符 | 说明 | 自动替换 |
| ------------------------- | ------------ | -------- |
| `{{DATE}}` | 日期 | ✅ 是 |
| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 |
| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 |
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 |
| `{{PLAYBOOK_ROOT}}` | Playbook 根 | ✅ 是 |
| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 |
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
未配置时保持原样。
`{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录
（默认 `docs/standards/playbook`，
也可按项目配置改成 `custom/playbook` 等）。
`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
（默认 `docs/standards/playbook/scripts`，
也可按项目配置改成 `custom/playbook/scripts` 等）。
## 模板说明
### memory-bank/
项目上下文文档，用于让 AI 快速理解项目：
| 文件 | 用途 |
| ----------------------------- | -------------------------- |
| `project-brief.template.md` | 项目定位、边界、约束 |
| `tech-context.template.md` | 技术上下文、工具链、入口 |
| `system-patterns.template.md` | 系统模式、边界、不变量 |
| `active-context.template.md` | 当前目标、最近变更、下一步 |
| `progress.template.md` | 人类摘要 + Plan 状态块 |
| `decisions.template.md` | 架构决策记录（ADR） |
### prompts/
任务入口模板（部署后去掉 `.template` 后缀）：
其中 `templates/prompts/README.md` 部署后对应 `docs/prompts/README.md`，
作为任务入口索引。
| 文件 | 用途 | 使用场景 |
| ----------------------------------- | ------------ | ------------------- |
| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 |
| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 |
| `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 |
| `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 |
| `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 |
| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 |
### AGENT_RULES.template.md
执行规则模板，定义 AI 的工作循环和约束。
如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]`
首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。
计划编排与执行细节统一指向 `docs/superpowers/`、
`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`；
这里仅说明模板职责与部署边界。
### AGENTS.template.md
入口导航模板，作为项目的主入口。
**设计理念**：
- **最小化内容**：只包含导航链接，不包含详细规则
- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
**playbook 标记**（用于自动更新）：
- `<!-- playbook:agents:start/end -->`：语言规则链接。
由 `[sync_standards]` 管理
- `<!-- playbook:templates:start/end -->`：路由链接。
`AGENTS.md` 始终按区块更新
- `<!-- playbook:framework:start/end -->`：完整框架。
`AGENTS.md` 始终按区块更新
### ci/、cpp/、python/
语言和 CI 配置模板。`install_mode = "snapshot"` 安装快照时会复制这些模板：
- `ci/gitea/`：Gitea Actions 工作流与辅助脚本。
部署到快照 `templates/ci/`
- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt`
等文件。
部署到快照 `templates/cpp/`
- `python/`：`pyproject.toml`、`.editorconfig` 等文件。
部署到快照 `templates/python/`
> 注意：这些模板会复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。
> 其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录，而不只是复制 workflows。
**使用方式**：
```toml
# playbook.toml - 生成包含这些模板的快照
[playbook]
project_root = "/path/to/project"
playbook_root = "docs/standards/playbook"
install_mode = "snapshot"
[sync_standards]
langs = ["tsl", "cpp", "python"]
```
```bash
python scripts/playbook.py -config playbook.toml
# 然后手动从 <playbook_root>/templates/ 复制所需配置到项目根目录
```
## 与 playbook 其他部分的关系
```text
playbook/
├── rulesets/ # 语言级硬规则 → 部署到 .agents/
├── skills/ # 按需加载的技能（thirdparty/ 为第三方同步）
├── docs/ # 权威静态文档
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/
└── playbook.py # 统一入口：snapshot install / sync_*
```
## 完整部署流程
```bash
# 1. 准备配置并执行统一入口
python <playbook_root>/scripts/playbook.py -config playbook.toml
# 2. 编辑 memory-bank/*.md 填写项目信息
# 3. 替换剩余的 {{PLACEHOLDER}} 占位符
```
---
**最后更新**：2026-05-18
**最后更新**：2026-06-17