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

python scripts/playbook.py -config playbook.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 代理规则集模板（三层架构设计）：

三层架构设计

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 为例：

# 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. 在目标项目中首次引入：

   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
   

3. 在项目根配置并执行：

   # playbook.toml
   [playbook]
   project_root = "."
   
   [sync_standards]
   langs = ["tsl", "cpp"]
   
   [sync_rules]
   
   [sync_memory_bank]
   project_name = "MyProject"
   

   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. 在项目根执行统一入口：

   python docs/standards/playbook/scripts/playbook.py -config playbook.toml
   

---

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

当你希望只 vendoring 需要的语言规范（例如只需要 tsl + cpp）时：

# playbook.toml
[playbook]
project_root = "/path/to/target-project"

[vendor]
langs = ["tsl", "cpp"]

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

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