323 lines
12 KiB
Markdown
323 lines
12 KiB
Markdown
# playbook
|
||
|
||
Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）工程规范与代理规则合集。
|
||
|
||
## 原则
|
||
|
||
1. **可读性优先**：读代码的时间远大于写代码
|
||
2. **一致性优先**：同一仓库内保持一致比追求"最优风格"更重要
|
||
3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格
|
||
|
||
## 适用范围
|
||
|
||
- 本指南适用于所有 TSL/C++/Python/Markdown 相关仓库与脚本
|
||
- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移
|
||
|
||
## docs/（开发规范）
|
||
|
||
`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
|
||
|
||
- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python / Markdown）。
|
||
- `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
|
||
- `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end`
|
||
代码块、注释与通用最佳实践。
|
||
- `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。
|
||
- `docs/tsl/syntax_book/index.md`：TSL 语法手册（整理自原始语法/机制目录册；函数库位于
|
||
`docs/tsl/syntax_book/function/`，按需检索）。
|
||
- `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。
|
||
- `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。
|
||
- `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。
|
||
- `docs/cpp/toolchain.md`：C++ 工具链与验证命令模板。
|
||
- `docs/cpp/dependencies_conan.md`：C++ Conan 依赖管理建议。
|
||
- `docs/cpp/clangd.md`：clangd 补全配置建议（`.clangd`）。
|
||
- `docs/python/style_guide.md`：Python 代码风格（Google 基线）。
|
||
- `docs/python/tooling.md`：Python 工具链（black/isort/flake8/pylint/mypy/pytest/pre-commit）。
|
||
- `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/`
|
||
复制到项目根目录）。
|
||
- `docs/markdown/index.md`：Markdown 代码块与行内代码格式（仅代码格式化）。
|
||
- `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。
|
||
- `templates/python/`：Python 落地模板（`pyproject.toml`
|
||
工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。
|
||
- `templates/ci/`：目标项目 CI 示例模板（如 Gitea
|
||
Actions），用于自动化校验部分规范。
|
||
|
||
## templates/（项目架构模板）
|
||
|
||
`templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板：
|
||
|
||
- `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-stack、architecture、progress、decisions）
|
||
- `templates/prompts/`：工作流程模板（agent-behavior、clarify、review）
|
||
- `templates/AGENTS.template.md`：路由中心模板（项目主入口）
|
||
- `templates/AGENT_RULES.template.md`：执行流程模板
|
||
|
||
### 快速部署
|
||
|
||
统一入口（配置驱动，示例见 `playbook.toml.example`）：
|
||
|
||
```bash
|
||
python scripts/playbook.py -config playbook.toml
|
||
```
|
||
|
||
示例配置（部署项目架构模板）：
|
||
|
||
```toml
|
||
[playbook]
|
||
project_root = "/path/to/project"
|
||
|
||
[sync_rules]
|
||
# force = true # 可选
|
||
|
||
[sync_memory_bank]
|
||
project_name = "MyProject"
|
||
|
||
[sync_prompts]
|
||
```
|
||
|
||
**部署行为**：
|
||
|
||
- **配置节存在即启用**：只写需要同步的配置节
|
||
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`）
|
||
- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（会先备份）
|
||
|
||
详见：`templates/README.md`
|
||
|
||
## rulesets/（规则集模板库 - 三层架构）
|
||
|
||
> **重要说明**：playbook 仓库中的 `rulesets/` 是**规则集模板库**，不是 playbook 项目自身的代理规则。
|
||
>
|
||
> Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是：
|
||
>
|
||
> 1. 作为**模板源**，供其他项目复制
|
||
> 2. 通过 playbook.py 的 `[sync_standards]` 部署到目标项目的 `.agents/`
|
||
> 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成）
|
||
|
||
`rulesets/` 是 AI 代理规则集模板（三层架构设计）：
|
||
|
||
### 三层架构设计
|
||
|
||
```txt
|
||
Layer 1: rulesets/ (≤50 行/语言，模板源)
|
||
├─ 核心约束与安全红线
|
||
└─ 指向 Skills 和 docs
|
||
|
||
Layer 2: codex/skills/ (按需加载，$skill-name 触发)
|
||
├─ tsl-guide: TSL 渐进式语法教学
|
||
├─ commit-message: 提交信息规范
|
||
├─ style-cleanup: 代码风格整理
|
||
└─ bulk-refactor-workflow: 批量重构流程
|
||
|
||
Layer 3: docs/ (权威静态文档)
|
||
└─ 完整语法手册/代码风格/工具链配置
|
||
```
|
||
|
||
**各层职责**：
|
||
|
||
| 层级 | 加载方式 | 内容 | 作用 |
|
||
| ------- | ------------------------------ | ------------------------------ | -------------------------- |
|
||
| Layer 1 | 自动，始终在上下文 | 硬约束与安全红线 | 快速判断能做/不能做 |
|
||
| Layer 2 | `$<skill-name>` 触发或代理判定 | 操作指南、最佳实践、工作流 | 指导具体怎么做 |
|
||
| Layer 3 | 按需读取特定章节 | 完整语言手册、代码风格、工具链 | 最终权威（冲突时以此为准） |
|
||
|
||
**目录结构**：
|
||
|
||
- `rulesets/index.md`：规则集索引（跨语言）
|
||
- `rulesets/tsl/index.md`：TSL 核心约定（44 行）
|
||
- `rulesets/cpp/index.md`：C++ 核心约定（47 行）
|
||
- `rulesets/python/index.md`：Python 核心约定（45 行）
|
||
- `rulesets/markdown/index.md`：Markdown 核心约定（31 行，仅代码格式化）
|
||
|
||
更多说明：`rulesets/index.md`
|
||
|
||
### 性能指标
|
||
|
||
| 指标 | 优化前 | 优化后 | 改善 |
|
||
| ------------- | ------- | ------ | ---- |
|
||
| .agents 规模 | ~500 行 | 167 行 | -67% |
|
||
| 持久化 tokens | ~12,500 | ~4,200 | -66% |
|
||
|
||
### 维护原则
|
||
|
||
**.agents/（Layer 1）修改规则**：
|
||
|
||
- 可做：增加安全漏洞类型、更新核心约定、添加硬性约束
|
||
- 不可做：添加推荐型最佳实践（→ skill）、详细语法解释（→ skill/docs）、超过 50 行（→ 拆分）
|
||
|
||
**Skills（Layer 2）创建规则**：
|
||
|
||
- 可做：增加新流程、从零教授新语言、添加跨语言通用知识
|
||
|
||
## SKILLS（Codex CLI）
|
||
|
||
本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于按需加载的工作流与知识库。
|
||
|
||
**核心 Skills**：
|
||
|
||
- **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践）
|
||
|
||
**通用 Skills**：
|
||
|
||
- `$commit-message`：提交信息规范
|
||
- `$style-cleanup`：整理代码风格
|
||
- `$bulk-refactor-workflow`：批量重构流程
|
||
- 更多见 `SKILLS.md`
|
||
|
||
**安装与使用**：详见 `SKILLS.md`
|
||
|
||
## 在其他项目中使用本 Playbook
|
||
|
||
由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内，并用统一入口执行。
|
||
|
||
### 快速决策：我应该用哪种方式？
|
||
|
||
| 你的情况 | 推荐方式 | 优势 |
|
||
| ---------------------------------- | ------------------------------- | ------------------------------- |
|
||
| 新项目，需要持续同步更新 | 方式一：git subtree | 可随时拉取最新标准，版本可追溯 |
|
||
| 只需要一次性引入，不常更新 | 方式二：手动复制快照 | 简单直接，无需 git subtree 知识 |
|
||
| 只需要部分语言（且希望快照也裁剪） | 方式三：CLI 裁剪复制（vendor） | 快照只包含所需语言（更小） |
|
||
| **不确定？** | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新 |
|
||
|
||
---
|
||
|
||
### TL;DR - 30 秒快速开始
|
||
|
||
以 TSL 为例：
|
||
|
||
```bash
|
||
# 1. 引入标准快照
|
||
git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
|
||
|
||
# 2. 在项目根创建配置（示例见 docs/standards/playbook/playbook.toml.example）
|
||
cat <<'EOF' > playbook.toml
|
||
[playbook]
|
||
project_root = "."
|
||
|
||
[sync_standards]
|
||
langs = ["tsl"]
|
||
EOF
|
||
|
||
# 3. 执行统一入口
|
||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||
|
||
# 4. 提交
|
||
git add .
|
||
git commit -m ":package: deps(playbook): add tsl standards"
|
||
```
|
||
|
||
---
|
||
|
||
### 方式一：git subtree 同步（推荐）
|
||
|
||
1. 在目标项目中首次引入：
|
||
|
||
```bash
|
||
git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
|
||
```
|
||
|
||
2. 后续同步更新：
|
||
|
||
```bash
|
||
git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
|
||
```
|
||
|
||
3. 在项目根配置并执行：
|
||
|
||
```toml
|
||
# playbook.toml
|
||
[playbook]
|
||
project_root = "."
|
||
|
||
[sync_standards]
|
||
langs = ["tsl", "cpp"]
|
||
|
||
[sync_rules]
|
||
|
||
[sync_memory_bank]
|
||
project_name = "MyProject"
|
||
```
|
||
|
||
```bash
|
||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||
```
|
||
|
||
配置参数说明见 `docs/standards/playbook/playbook.toml.example`。
|
||
|
||
---
|
||
|
||
### 方式二：手动复制快照
|
||
|
||
如果不使用 git subtree，也可手动复制快照到目标项目：
|
||
|
||
1. 创建目录：`docs/standards/playbook/`。
|
||
2. 复制 Playbook 快照内容（建议使用方式三生成裁剪快照）。
|
||
3. 在项目根执行统一入口：
|
||
|
||
```bash
|
||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||
```
|
||
|
||
---
|
||
|
||
### 方式三：CLI 裁剪复制（按语言，离线）
|
||
|
||
当你希望只 vendoring 需要的语言规范（例如只需要 `tsl` + `cpp`）时：
|
||
|
||
```toml
|
||
# playbook.toml
|
||
[playbook]
|
||
project_root = "/path/to/target-project"
|
||
|
||
[vendor]
|
||
langs = ["tsl", "cpp"]
|
||
```
|
||
|
||
```bash
|
||
python scripts/playbook.py -config playbook.toml
|
||
```
|
||
|
||
该动作仅生成裁剪快照，不会隐式同步 `.agents/` 或 `.gitattributes`；后续请用 `sync_standards` 明确落地。
|
||
|
||
---
|
||
|
||
### 多语言项目落地（TSL + C++/其他语言）
|
||
|
||
多语言项目建议把规范拆成两类：
|
||
|
||
1. **仓库级（跨语言）共识**：对所有语言都成立的规则与流程。
|
||
- 提交信息：`docs/common/commit_message.md`
|
||
- 行尾与文本规范：`.gitattributes`
|
||
- 代理最低要求：`.agents/*`（工作原则、质量底线、安全边界）
|
||
2. **语言级（Language-specific）规范**：只对某个语言成立的风格与工具。
|
||
- 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
|
||
|
||
**建议**：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相"污染"。
|
||
|
||
本仓库提供多套代理规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/markdown/`）：
|
||
|
||
- 三者都包含核心约定与安全红线
|
||
- 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、Markdown 代码格式化等）
|
||
|
||
**多语言项目推荐结构**（示例：TSL + C++ + Python + Markdown）：
|
||
|
||
```txt
|
||
.
|
||
├── .agents/
|
||
│ ├── index.md # 多语言索引（缺省时由 playbook 生成）
|
||
│ ├── tsl/ # 由本 Playbook 同步（适用于 .tsl/.tsf）
|
||
│ ├── cpp/ # 由本 Playbook 同步（适用于 C++23/Modules）
|
||
│ ├── python/ # Python 规则集（同上）
|
||
│ └── markdown/ # Markdown 规则集（仅代码格式化）
|
||
├── .gitattributes # 行尾/文本规范
|
||
├── docs/
|
||
│ ├── standards/
|
||
│ │ └── playbook/ # 本 Playbook 快照（git subtree/vendoring）
|
||
│ └── project/ # 项目自有文档（架构、ADR、运行方式等）
|
||
├── playbook.toml # 统一入口配置
|
||
└── src/ # 源码目录（按项目实际情况）
|
||
```
|
||
|
||
**规则优先级建议**：
|
||
|
||
- 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖
|
||
- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如
|
||
`src/foo/.agents/`），并以"离代码更近者优先"为准
|