playbook/README.md

# 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`：执行流程模板

### 快速部署

使用 `sync_templates` 脚本一键部署项目架构：

```bash
# Linux/macOS
sh scripts/sync_templates.sh -project-root /path/to/project

# PowerShell
.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project

# Windows CMD
scripts\sync_templates.bat -project-root C:\path\to\project
```

**部署行为**：

- **新项目**：创建完整的 `AGENTS.md`、`AGENT_RULES.md`、`memory-bank/`、`docs/prompts/`
- **已有 AGENTS.md**：追加路由链接（使用 `<!-- playbook:templates:start/end -->` 标记）
- **-full 参数**：追加完整框架（规则优先级 + 新会话开始时）到已有 AGENTS.md
- **其他文件**：如果已存在则跳过（使用 `-force` 覆盖）

详见：`templates/README.md`

## rulesets/（规则集模板库 - 三层架构）

> **重要说明**：playbook 仓库中的 `rulesets/` 是**规则集模板库**，不是 playbook 项目自身的代理规则。
>
> Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是：
>
> 1. 作为**模板源**，供其他项目复制
> 2. 通过 `sync_standards.sh` 部署到目标项目的 `.agents/`
> 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成）

`rulesets/` 是 AI 代理规则集模板（三层架构设计）：

### 三层架构设计

```txt
Layer 1: rulesets/          (≤50 行/语言，模板源)
  ├─ 核心约束与安全红线
  └─ 指向 Skills 和 docs

Layer 2: codex/skills/     (按需加载，$skill-name 触发)
  ├─ tsl-guide: TSL 渐进式语法教学（962 行）
  ├─ commit-message: 提交信息规范
  ├─ style-cleanup: 代码风格整理
  └─ bulk-refactor-workflow: 批量重构流程

Layer 3: docs/             (权威静态文档)
  └─ 完整语法手册/代码风格/工具链配置
```

**目录结构**：

- `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 行，仅代码格式化）

详见：`AGENTS.md`

## 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 知识 |
| 只需要部分语言（且希望快照也裁剪） | 方式三：脚本裁剪复制            | 快照只包含所需语言（更小）      |
| **不确定？**                       | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新      |

**大部分情况推荐使用方式一（git subtree）。**
说明：方式一可选择同步哪些语言规则到 `.agents/`，但 `docs/standards/playbook/` 快照仍是全量；方式三会裁剪快照本身。

---

### TL;DR - 30 秒快速开始

大部分项目只需运行以下命令即可完成落地（以 TSL 为例）：

```bash
# 1. 引入标准快照
git subtree add --prefix docs/standards/playbook \
  https://git.mytsl.cn/csh/playbook.git main --squash

# 2. 同步规则到项目根目录
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl

# 3. 提交
git add .
git commit -m ":package: deps(playbook): add tsl standards"
```

**完成！** 后续同步更新只需重复步骤 1（把 `add` 改为 `pull`）和步骤 2。

详细说明和其他方式见下文 ↓

---

### 方式一：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
   ```

#### 快速落地（最小 4 步）

在目标项目中按以下顺序执行即可完成落地（推荐固定使用
`--prefix docs/standards/playbook`）：

1. **引入标准快照**（见上文 `git subtree add`）
2. **同步到项目根目录**（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：

   ```bash
   sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
   ```

   同步 C++ 规则集（同一份快照，不同规则集）：

   ```bash
   sh docs/standards/playbook/scripts/sync_standards.sh -langs cpp
   ```

   一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）：

   ```bash
   sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
   ```

   > 说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
   > 会自动生成最小版；已存在则不会覆盖。

3. **验收**（任意满足其一即可）：

   - 目录存在：`.agents/tsl/`
   - 规则入口可读：`.agents/tsl/index.md`
   - （可选）C++ 规则入口可读：`.agents/cpp/index.md`
   - 标准文档可读：`docs/standards/playbook/docs/index.md`
   - `.gitattributes` 包含追加块头：`# Added from playbook .gitattributes`

4. **将同步产物纳入版本控制**（目标项目建议提交）：
   - `docs/standards/playbook/`（标准快照）
   - `.agents/tsl/`（落地规则集）
   - `.gitattributes`（追加缺失规则）
   - `AGENTS.md`（若本次自动生成）

#### 新项目 / 旧项目（命令示例）

**新项目**（无 `.agents/` 与 `AGENTS.md`）：

```bash
git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
```

**旧项目**（已有 `AGENTS.md`）：

```bash
git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
```

旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。

#### 可选：项目包装脚本（多 playbook 串联）

多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：

```sh
#!/usr/bin/env sh
set -eu

sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
# sh docs/standards/python/scripts/sync_standards.sh
```

也可以直接一次同步多个规则集：

```sh
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
```

#### 目录约定（建议）

目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：

```txt
.
├── .agents/
│   ├── index.md                   # 多语言代理规则集索引（缺省时由脚本创建）
│   ├── tsl/                       # 从 Playbook 同步（仅覆盖该子目录）
│   └── cpp/                       # 从 Playbook 同步（仅覆盖该子目录，按需）
├── .gitattributes                 # 从 Playbook 同步
├── docs/
│   ├── standards/
│   │   └── tsl/                   # git subtree 快照（只读）
│   │       ├── docs/              # common/ + tsl/ + cpp/
│   │       ├── .agents/           # 标准代理规则快照
│   │       ├── .gitattributes
│   │       └── SOURCE.md          # 记录来源版本/commit（项目自行维护）
│   └── project/                   # 目标项目自己的文档（非语言标准：架构/运行/ADR/使用说明/业务约定等）
└── README.md                      # 说明遵循 standards
```

根目录的 `.agents/<lang>/` 与 `.gitattributes` 通过同步脚本获得：

- **说明**：在 **本 playbook 仓库**内脚本位于 `scripts/`；在 **目标项目**里通过
  `git subtree` 引入到 `docs/standards/playbook/` 后，脚本路径变为
  `docs/standards/playbook/scripts/`。
- **在目标项目里直接运行 Playbook 提供的脚本**（子树快照里自带）：
  - `docs/standards/playbook/scripts/sync_standards.sh`（推荐，支持多语言参数）
  - `docs/standards/playbook/scripts/sync_standards.ps1`（推荐，支持多语言参数）
  - `docs/standards/playbook/scripts/sync_standards.bat`（推荐，支持多语言参数）
- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）

建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/`
会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。同步时需显式指定
语言参数（`-langs`），如需同步 C++ 规则集，推荐直接运行：
`sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp`。

这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。

**同步脚本行为**（目标项目内的最终落地内容）：

- 覆盖/更新：`.agents/<AGENTS_NS>/`（由 `-langs` 或 `AGENTS_NS` 指定）
- 更新 `.gitattributes`：默认追加缺失规则（可用
  `SYNC_GITATTR_MODE=append|block|overwrite|skip` 控制）
- 缺省创建：`.agents/index.md`
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
- 不修改：`.gitignore`（项目自行维护）

<details>
<summary> 高级选项：环境变量配置（点击展开）</summary>

#### 环境变量（可选）

同步脚本支持以下可选环境变量（默认值可满足大多数项目）：

| 变量名              | 默认值   | 说明                                                                                                                                                  |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTS_NS`         | `tsl`    | 同步的规则集名/落地目录名：`.agents/<AGENTS_NS>/`（例如 `tsl`、`cpp`）                                                                                |
| `SYNC_GITATTR_MODE` | `append` | `.gitattributes` 同步模式：`append` 仅追加缺失规则（忽略注释/空行，比对后按块追加）；`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |

</details>

### 方式二：手动复制快照

如果不使用
`git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。

**步骤**：

1. 在目标项目创建目录：`docs/standards/playbook/`。
2. 从本仓库复制以下内容到目标项目：
   - `docs/` → `docs/standards/playbook/docs/`（包含
     `docs/common/`、`docs/tsl/`、`docs/cpp/`、`docs/python/`）
   - `.agents/` → `docs/standards/playbook/.agents/`
   - `.gitattributes` → `docs/standards/playbook/.gitattributes`
   - `scripts/` → `docs/standards/playbook/scripts/`
3. 在目标项目根目录运行同步脚本，把 `.agents/tsl/` 与 `.gitattributes`
   落到根目录（见上文脚本路径）。
4. 在 `docs/standards/playbook/SOURCE.md`
   记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。

该方式没有自动同步能力，后续更新需重复上述复制流程。

### 方式三：脚本裁剪复制（按语言，离线）

当你希望“只 vendoring 需要的语言规范”（例如只需要 `tsl` +
`cpp`）时，可直接运行本仓库提供的裁剪脚本：

- macOS/Linux：

  ```bash
  sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh -project-root <target-project-root> -langs tsl,cpp
  ```

- PowerShell：

  ```powershell
  powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -ProjectRoot <target-project-root> -Langs tsl,cpp
  ```

- Windows bat：

  ```bat
  <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat -project-root <target-project-root> -langs tsl,cpp
  ```

**脚本会**：

- 生成裁剪快照到 `docs/standards/playbook/`（包含
  `docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` +
  `.gitattributes` + 通用 `templates/ci/` + 相关 `templates/<lang>/`）
- 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把
  `.agents/<lang>/` 与 `.gitattributes` 落地到目标项目根目录
- 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息

### 多语言项目落地（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                      # 多语言索引（缺省时由脚本创建）
│   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
│   ├── cpp/                          # 由本 Playbook 同步（适用于 C++23/Modules）
│   ├── python/                       # Python 规则集（同上）
│   └── markdown/                     # Markdown 规则集（仅代码格式化）
├── .gitattributes                    # 行尾/文本规范（可由某个 playbook 同步）
├── docs/
│   ├── standards/
│   │   ├── tsl/                      # 本 Playbook 快照（git subtree/vendoring；包含 common/tsl/cpp）
│   │   └── python/                   # Python playbook 快照（可选）
│   └── project/                      # 项目自有文档（架构、ADR、运行方式等）
├── scripts/
│   └── sync_standards.sh             # 项目包装脚本：依次调用各 playbook 的 sync
└── src/                              # 源码目录（按项目实际情况）
```

**规则优先级建议**：

- 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖
- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如
  `src/foo/.agents/`），并以"离代码更近者优先"为准

<details>
<summary> 高级选项：`.agents` 覆盖/合并策略（点击展开）</summary>

#### `.agents` 的覆盖/合并策略（可执行流程）

同步脚本会同步到项目根目录的 `.agents/tsl/`（并不会覆盖 `.agents/`
下的其他语言目录）。若项目需要追加 C++ 等语言/模块专属规则，建议二选一：

1. **推荐：子目录规则覆盖（无需改同步脚本）**
   - 让本 Playbook 的规则集固定落在 `.agents/tsl/`，由同步脚本维护。
   - 在其他语言/模块目录下新增更具体规则，例如
     `.agents/cpp/`、`cpp/.agents/`、`src/.agents/`。
2. **Overlay 合并：项目维护叠加层并在同步后覆盖回去**
   - 约定项目自定义规则放在 `docs/project/agents_overlay/`（不叫
     `.agents`，避免被同步覆盖）。
   - 每次运行 `sync_standards.*` 后，再把 overlay 覆盖回
     `.agents/tsl/`（建议封装成项目脚本）。

macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）：

```sh
#!/usr/bin/env sh
set -eu

sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp

OVERLAY="docs/project/agents_overlay"
if [ -d "$OVERLAY" ]; then
  cp -R "$OVERLAY"/. ".agents/tsl/"
  echo "Applied agents overlay."
fi
```

PowerShell 示例（目标项目的 `scripts/sync_standards.ps1`）：

```powershell
& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs tsl,cpp

$overlay = "docs/project/agents_overlay"
if (Test-Path $overlay) {
  Copy-Item "$overlay\\*" ".agents\\tsl" -Recurse -Force
  Write-Host "Applied agents overlay."
}
```

</details>

#### 扩展新语言（模板）

当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：

- **文档**：
  - 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用
    `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md`
    链接入口。
  - 若新增"本 Playbook 未覆盖的语言"：再引入对应语言的标准仓库（subtree/vendoring 到
    `docs/standards/<lang>/`）
- **代理规则**：
  - C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh -langs cpp`（或
    `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到
    `.agents/cpp/`（与 `.agents/tsl/` 并行）。
  - 其他语言：在目标项目增加 `.agents/<lang>/`（与 `.agents/tsl/`
    并行），只写该语言专属要求与工具链约束
- **同步策略**：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个
  `.agents/`
- **CI/工具**：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）
  - C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的
    `CompilationDatabase`（模板见 `templates/cpp/.clangd`）