playbook/README.md

# playbook

Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。

## 目标

- 让代码**易读、易维护、易演进**。
- 风格保持一致，减少无意义的差异。
- 在不影响清晰度的前提下，尽量简洁。

## 原则

1. **可读性优先**：读代码的时间远大于写代码。
2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。
3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。

## 适用范围

- 本指南适用于所有 TSL 相关仓库与脚本。
- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。

## docs/（开发规范）

`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。

- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python）。
- `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/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/` 复制到项目根目录）。
- `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`）。

## .agents/（代理规则）

`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/` 并行。

- `.agents/index.md`：规则集索引（多语言）。
- `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。
- `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。

## 在其他项目中使用本 Playbook

由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内。

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

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

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

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

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

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

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

4. 将同步产物纳入版本控制（目标项目建议提交）：
   - `docs/standards/playbook/`（标准快照）
   - `.agents/tsl/`（落地规则集）
   - `.gitattributes`（managed block 更新）

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

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

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

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

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

```sh
sh docs/standards/playbook/scripts/sync_standards.sh 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/...`）。
注：默认同步到 `.agents/tsl/`；如需同步 C++ 规则集，推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。

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

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

- 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
- 更新 `.gitattributes`：默认只维护 `# BEGIN playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
- 缺省创建：`.agents/index.md`
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
- 不修改：`.gitignore`（项目自行维护）

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

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

| 变量名              | 默认值  | 说明                                                                                        |
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `AGENTS_NS`         | `tsl`   | 同步的规则集名/落地目录名：`.agents/<AGENTS_NS>/`（例如 `tsl`、`cpp`）                      |
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |

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

如果不使用 `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）。

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

### 多语言项目落地（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/`）：

- 两者都包含跨语言通用底线：`auth.md`、`code_quality.md`、`performance.md`、`testing.md`
- 并在 `index.md` 中叠加语言级“硬约束”（TSL/TSF 语法限制、C++23/Modules、Windows 支持等）

多语言项目推荐结构（示例：TSL + C++ + Python）：

```txt
.
├── .agents/
│   ├── index.md                      # 多语言索引（缺省时由脚本创建）
│   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
│   ├── cpp/                          # 由本 Playbook 同步（适用于 C++23/Modules）
│   └── python/                       # Python 规则集（同上）
├── .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/`），并以“离代码更近者优先”为准。

#### `.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 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."
}
```

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

当目标项目需要新增一门语言（例如 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 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`）。

## 版本与贡献

- 本项目会持续迭代；变更以 PR 形式提交。
- 新规则需包含动机、示例、迁移建议（如有）。