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），用于自动化校验部分规范。

.agents/（代理规则 - 三层架构）

.agents/ 是 AI 代理的极简铁律（三层架构设计）：

三层架构设计

Layer 1: .agents/          (≤50 行/语言，自动加载)
  ├─ 核心约束与安全红线
  └─ 指向 Skills 和 docs

Layer 2: codex/skills/     (按需加载，$skill-name 触发)
  ├─ tsl-guide: TSL 渐进式语法教学（962 行）
  ├─ performance-optimization: 跨语言性能优化
  └─ testing-workflow: 跨语言测试策略

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

目录结构：

• .agents/index.md：规则集索引（跨语言）
• .agents/tsl/index.md：TSL 核心约定（47 行）
• .agents/cpp/index.md：C++ 核心约定（50 行）
• .agents/python/index.md：Python 核心约定（48 行）
• .agents/markdown/index.md：Markdown 核心约定（23 行，仅代码格式化）

详见：AGENTS.md

SKILLS（Codex CLI）

本仓库内置一组 Codex CLI skills（见 codex/skills/），用于按需加载的工作流与知识库。

核心 Skills：

• $tsl-guide：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践）
• $performance-optimization：跨语言性能优化工作流
• $testing-workflow：跨语言测试策略

通用 Skills：

• $code-review-workflow：代码审查流程
• $commit-message：提交信息规范
• $systematic-debugging：系统化调试
• 更多见 SKILLS.md

安装与使用：详见 SKILLS.md

在其他项目中使用本 Playbook

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

快速决策：我应该用哪种方式？

你的情况	推荐方式	优势
新项目，需要持续同步更新	方式一：git subtree（推荐）	可随时拉取最新标准，版本可追溯
只需要一次性引入，不常更新	方式二：手动复制快照	简单直接，无需 git subtree 知识
只需要部分语言（如只要 TSL+C++）	方式三：脚本裁剪复制	自动裁剪，只包含所需语言
不确定？	方式一：git subtree（推荐）	最灵活，后续可随时同步更新

大部分情况推荐使用方式一（git subtree）。

---

TL;DR - 30 秒快速开始

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

# 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 tsl

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

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

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

---

方式一：git subtree 同步（推荐）

1. 在目标项目中首次引入：

   git subtree add \
   --prefix docs/standards/playbook \
   https://git.mytsl.cn/csh/playbook.git \
   main --squash
   

2. 后续同步更新：

   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）：

   sh docs/standards/playbook/scripts/sync_standards.sh
   

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

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

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

   sh docs/standards/playbook/scripts/sync_standards.sh 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）：

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

旧项目（已有 AGENTS.md）：

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

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

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

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

#!/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 docs/standards/playbook/scripts/sync_standards.sh tsl cpp

目录约定（建议）

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

.
├── .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/<lang>/，将按现有语言同步；否则默认 .agents/tsl/。如需同步 C++ 规则集， 推荐直接运行：sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp。

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

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

• 覆盖/更新：.agents/<AGENTS_NS>/（默认 .agents/tsl/）
• 自动识别：未传语言参数且已存在 .agents/<lang>/ 时，按现有语言同步
• 更新 .gitattributes：默认追加缺失规则（可用 SYNC_GITATTR_MODE=append|block|overwrite|skip 控制）
• 缺省创建：.agents/index.md
• 覆盖前备份：写入同目录的 *.bak.*（或 Windows 下随机后缀）
• 不修改：.gitignore（项目自行维护）

高级选项：环境变量配置（点击展开）

环境变量（可选）

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

变量名	默认值	说明
AGENTS_NS	tsl	同步的规则集名/落地目录名：.agents/<AGENTS_NS>/（例如 tsl、cpp）
SYNC_GITATTR_MODE	append	.gitattributes 同步模式：append 仅追加缺失规则（忽略注释/空行，比对后按块追加）；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）。

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

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

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

• macOS/Linux：

  sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh <target-project-root> tsl cpp
  

• PowerShell：

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

• Windows bat：

  <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat <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）：

.
├── .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/），并以"离代码更近者优先"为准

高级选项：`.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）：

#!/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）：

& "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）