playbook

Playbook：工程规范与代理规则合集，当前覆盖：

• TSL（.tsl/.tsf）
• C++
• Python
• TypeScript（.ts/.tsx）
• JavaScript（.js/.mjs/.cjs）
• Markdown（代码格式化）

原则

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

适用范围

• 本指南适用于所有 TSL/C++/Python/TypeScript/JavaScript/Markdown 相关仓库与脚本
• 当现有代码与本指南冲突时，以保持局部一致性为优先，逐步迁移

docs/（开发规范）

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

• docs/index.md：文档导航（跨语言 common / TSL / C++ / Python / TypeScript / Markdown）。
• docs/common/commit_message.md：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
• docs/tsl/index.md：TSL canonical 入口（语法 / 金融 / 模块 / 函数检索四层）。
• docs/tsl/code_style.md：TSL 代码结构、格式、begin/end 代码块、注释与通用最佳实践。
• docs/tsl/naming.md：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。
• docs/tsl/syntax/index.md：TSL 语法手册。
• docs/tsl/finance/index.md：TSL 金融业务层入口（指标、选股、回测与业务流程问题）。
• docs/tsl/modules/index.md：TSL 模块层入口（pyTSL、微信消息、Python 互操作、回测框架）。
• docs/tsl/reference/index.md：TSL 函数检索入口（模块目录位于 docs/tsl/reference/catalog/）。
• 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 代码块与行内代码格式（仅代码格式化）。
• docs/typescript/code_style.md：TypeScript 代码风格（Google 基线）。
• docs/typescript/naming.md：TypeScript 命名规范。
• docs/typescript/toolchain.md：TypeScript 工具链（typescript/prettier/eslint/vitest）。
• docs/typescript/configuration.md：TypeScript 配置清单（tsconfig/eslint/prettier）。
• 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、review）
• 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 触发)
  ├─ 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/typescript/index.md：TypeScript 核心约定（47 行）
• 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/），用于按需加载的工作流与知识库。

TSL 相关问题直接查阅 rulesets/tsl/index.md 与 docs/tsl/。

通用 Skills：

• $commit-message：提交信息规范
• $style-cleanup：整理代码风格
• $bulk-refactor-workflow：批量重构流程
• 更多见 SKILLS.md

安装与使用：详见 SKILLS.md

如果你通过 [install_skills] 更新已经安装过的 skill，默认会先把旧目录备份为 *.bak.<timestamp>；如果你明确希望“删除旧版本后直接重装”，可在 playbook.toml 的 [install_skills] 下设置 no_backup = true。

在其他项目中使用本 Playbook

由于本仓库需要内部权限访问，其他项目不能仅用外链引用；推荐把 Playbook 规范部署到项目内，并用统一入口执行。

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

你的情况	推荐方式	优势
新项目，需要持续同步更新	方式一：git subtree	标准留在项目内，后续可拉取更新
不想把 Playbook 以 subtree 嵌进仓库，但仍要把标准部署到项目内	方式二：外部 clone 后执行部署	Playbook 仓库与业务仓库解耦，部署根目录可配置
不确定？	方式一：git subtree（推荐）	项目内可见、版本可追溯、使用路径最稳定

---

TL;DR - 30 秒快速开始

先区分三个路径概念：

• project_root：目标项目根目录。
• deploy_root：相对于 project_root 的项目内目标目录。
• 外部 clone 出来的 Playbook 路径，例如 C:/tools/playbook：只是执行部署脚本的位置，不是外部 clone 出来的 Playbook 仓库路径对应的部署目标。

以 TSL 为例，Playbook 在项目内的默认部署根是 docs/standards/playbook；如果你把 deploy_root 改成 custom/playbook，则部署结果会落到 <project_root>/custom/playbook，文档和脚本入口也会跟着变成 custom/playbook/docs/...、custom/playbook/scripts/...。

方式一：git subtree

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

---

方式二：外部 clone 后执行部署

如果你不想把 Playbook 以 git subtree 嵌进目标项目，可以把 Playbook clone 到项目外部，再由该 clone 直接把标准部署进目标项目。

1. 先在任意位置 clone Playbook：

   git clone https://git.mytsl.cn/csh/playbook.git C:/tools/playbook
   

2. 在目标项目根创建 playbook.toml，并用 deploy_root 指定项目内的部署根。例如：

   • project_root 写目标项目根目录。
   • deploy_root 写目标项目内的相对路径。
   • 不要把外部 clone 的 C:/tools/playbook 这类路径写进 deploy_root；那只是你执行脚本的位置。

   [playbook]
   project_root = "."
   deploy_root = "custom/playbook"
   
   [vendor]
   langs = ["tsl"]
   
   [sync_standards]
   langs = ["tsl"]
   
   [sync_rules]
   
   [sync_memory_bank]
   project_name = "MyProject"
   

3. 在目标项目根执行外部 clone 里的统一入口：

   python C:/tools/playbook/scripts/playbook.py -config playbook.toml
   

说明：

• 这里的 [vendor] 是“把 Playbook 快照部署进目标项目”的执行步骤，不是第三种正式部署路线。
• deploy_root 永远表示目标项目内的部署目录；它不是外部 clone 出来的 Playbook 仓库路径。
• 外部 clone 场景下必须显式填写 deploy_root；脚本不会替你补默认部署目录。
• 如果 deploy_root = "custom/playbook"，部署后的项目内入口会是 custom/playbook/scripts/playbook.py、custom/playbook/docs/index.md。

---

多语言项目落地（TSL + C++/其他语言）

多语言项目建议把规范拆成两类：

1. 仓库级（跨语言）共识：对所有语言都成立的规则与流程。
   • 提交信息：docs/common/commit_message.md
   • 行尾与文本规范：.gitattributes
   • 代理最低要求：.agents/*（工作原则、质量底线、安全边界）
2. 语言级（Language-specific）规范：只对某个语言成立的风格与工具。
   • 例如 TSL 的命名/文件顶层声明限制、C++ 的 .clang-format/.clang-tidy、Python 的 ruff、TypeScript 的 ESLint/类型约束等。

建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相"污染"。

本仓库提供多套代理规则集（同步后位于目标项目的 .agents/tsl/ / .agents/cpp/ / .agents/python/ / .agents/typescript/ / .agents/markdown/）：

• 三者都包含核心约定与安全红线
• 并在 index.md 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、TypeScript 类型约束、Markdown 代码格式化等）

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

.
├── .agents/
│   ├── index.md                      # 多语言索引（缺省时由 playbook 生成）
│   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
│   ├── cpp/                          # 由本 Playbook 同步（适用于 C++23/Modules）
│   ├── python/                       # Python 规则集（同上）
│   ├── typescript/                   # TypeScript/JavaScript 规则集（同上）
│   └── markdown/                     # Markdown 规则集（仅代码格式化）
├── .gitattributes                    # 行尾/文本规范
├── <deploy_root>/                    # 本 Playbook 在项目内的部署根（默认 docs/standards/playbook）
│   ├── docs/
│   ├── rulesets/
│   ├── scripts/
│   └── templates/
├── docs/project/                     # 项目自有文档（架构、ADR、运行方式等）
├── playbook.toml                     # 统一入口配置
└── src/                              # 源码目录（按项目实际情况）

规则优先级建议：

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