# 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、verify）
- `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/`），并以"离代码更近者优先"为准