csh/tsl-devkit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Squashed 'docs/standards/playbook/' changes from b529012..a854534

Browse Source 
a854534 ✨ feat(plan_progress): auto-detect env for blocked plans
0d9a8ec 🐛 fix(playbook): honor no_backup for sync
2d401fa ✅ test(templates): update prompts validation
e23474e 📝 docs(playbook): update prompts and sync notes
60ff3cd 🐛 fix(playbook): sync templates per file
816f036 ✅ test(playbook): add sync and vendor coverage
625cabb 📝 docs(memory_bank): reformat templates
2554c87 📝 docs(prompts): refresh prompt templates
6774a9d ✨ feat(plan_progress): track plan status in progress.md
73d5c26 🔧 chore(playbook): split sync_templates into sections
278750e ✨ feat(playbook): add plan progress tracking and rules updates
6efd637 🐛 fix(sync): keep agents block blank lines
ea00d43 🐛 fix(playbook): support toml without tomllib
ab0dd11 📝 docs(playbook): drop docs/plans snapshots
398696c ✨ feat(playbook): merge unified cli
d959f80 🎨 style(docs): format markdown
b4f712a 🗑️ remove(legacy): drop old scripts and tests
0c4cd0e ✨ feat(actions): add install_skills and format_md
3d1582c ✨ feat(sync): add templates and standards actions
49bbfa1 ✨ feat(vendor): add playbook snapshot generation
8cfcc25 ✨ feat(cli): parse toml config and dispatch actions
05903c3 ✨ feat(cli): add toml config and dispatch order
65d216e ✅ test(cli): add basic playbook cli tests
f0bcf54 📝 docs(plans): add unified playbook cli plan
0885309 📝 docs(plans): add unified playbook cli design
3483d8a 🔧 chore(git): ignore .worktrees dir
eb75036 🔧 chore(templates): align agent templates and docs
efb93f1 📝 docs(playbook): drop todo/confirm mentions
4a85306 🗑️ remove(workflow): drop todo/confirm artifacts
9c5ee9f 🎨 style(markdown): format docs with prettier
5a2925f 🐛 fix(scripts): repair windows script parsing
26a35e0 ✅ test(ci): update required skills list
8df3883 🐛 fix(test): skip external root doc links
b067fc1 📦 deps(skills): sync superpowers
c03cda0 🔧 chore(ci): sync from origin main
55e05cb 🔧 chore(ci): use superpowers sync script
73c97f3 🔧 chore(ci): centralize superpowers sync
945704f 🔧 chore(ci): add superpowers sync workflow
e5d2c93 🗑️ remove(skills): drop duplicate workflows
3ae9708 🐛 fix(ci): update tests for flag-only scripts
c44b9aa 🔧 chore(scripts): require flag-driven args
e4e1d14 🔧 chore(scripts): unify single-dash options
b2eb475 ✅ test(templates): add template coverage
fc230b7 🎨 style(markdown): format markdown files
8dc8924 🔧 chore(markdown): add prettier config and usage
2045dd4 ✨ feat(vendor_playbook): add apply-templates option
872d8cf ✨ feat(templates): add sync templates scaffolding
5b1ca45 📝 docs(skills): clarify todo-plan template
054967a ✨ feat(skills): add todo-plan skill
cc340f1 🔧 chore(ci): align standards-check workflow template
e9de0aa 🔧 chore(ci): drop removed skill check
e5dd7d9 🔧 fix(sync): avoid backtick expansion
087b0b9 🔧 chore(sync): align agents block across ps1/bat
9481510 🔧 chore(sync): scope agents block to existing langs
b0ca842 🔧 fix(sync): rewrite docs path in agents
c98d65c 🔧 chore(sync): rewrite agents docs paths
c33611c 🗑️ remove(skills): drop unused skills and update references
2b37860 🎨 style(markdown): format markdown files
e3ecd26 📝 docs(tsl): align syntax annotations and examples
37546fe 🐛 fix(playbook): enforce rulesets to agents flow
f2df89d 🐛 fix(scripts): include language list in AGENTS.md
c0d0737 🐛 fix(playbook): add agents mirror for sync
3b8b99b 🎨 style(markdown): normalize md headings and lists
31f3000 ♻️ refactor(playbook): rename agents template directory to rulesets
11b2bed ✨ feat(markdown): add ruleset and sync support
5b89580 ✅ test(scripts): quiet git init warnings
5822a87 ♻️ refactor(playbook): streamline agents and refresh tsl docs

git-subtree-dir: docs/standards/playbook
git-subtree-split: a85453439f65b0c0aa05a5bbece773a02216ce76
This commit is contained in:
csh
2026-02-02 10:51:38 +08:00
parent ac794a6a70
commit b52102b7bd
192 changed files with 109197 additions and 135276 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+204 -318
View File
@@ -1,35 +1,29 @@
# playbook
Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。
## 目标
- 让代码**易读、易维护、易演进**。
- 风格保持一致，减少无意义的差异。
- 在不影响清晰度的前提下，尽量简洁。
Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）工程规范与代理规则合集。
## 原则
1. **可读性优先**：读代码的时间远大于写代码。
2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。
3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。
1. **可读性优先**：读代码的时间远大于写代码
2. **一致性优先**：同一仓库内保持一致比追求"最优风格"更重要
3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格
## 适用范围
- 本指南适用于所有 TSL/C++/Python 相关仓库与脚本。
- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。
- 本指南适用于所有 TSL/C++/Python/Markdown 相关仓库与脚本
- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移
## docs/（开发规范）
`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python）。
- `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 语法手册（整理自原始语法/机制目录册；`function.md`
建议按需检索）。
- `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 基线）。
@@ -40,65 +34,175 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
- `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/（代理规则）
## templates/（项目架构模板）
`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/`
并行。
`templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板：
- `.agents/index.md`：规则集索引（多语言）。
- `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。
- `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。
- `.agents/python/`：Python 规则集（入口：`.agents/python/index.md`）。
- `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`）：
```bash
python scripts/playbook.py -config playbook.toml
```
示例配置（部署项目架构模板）：
```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 代理规则集模板（三层架构设计）：
### 三层架构设计
```txt
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/`），用于 code review
/ 格式化 / 调试等工作流；安装与编写规范见 `SKILLS.md`。
本仓库内置一组 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 到项目内。
由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内，并用统一入口执行。
### 🚀 快速决策：我应该用哪种方式？
### 快速决策：我应该用哪种方式？
| 你的情况 | 推荐方式 | 优势 |
| -------------------------------- | ------------------------------- | ------------------------------- |
| 新项目，需要持续同步更新 | **方式一：git subtree（推荐）** | 可随时拉取最新标准，版本可追溯 |
| 只需要一次性引入，不常更新 | 方式二：手动复制快照 | 简单直接，无需 git subtree 知识 |
| 只需要部分语言（如只要 TSL+C++） | 方式三：脚本裁剪复制 | 自动裁剪，只包含所需语言 |
| **不确定？** | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新 |
**大部分情况推荐使用方式一（git subtree）。**
| 你的情况 | 推荐方式 | 优势 |
| ---------------------------------- | ------------------------------- | ------------------------------- |
| 新项目，需要持续同步更新 | 方式一：git subtree | 可随时拉取最新标准，版本可追溯 |
| 只需要一次性引入，不常更新 | 方式二：手动复制快照 | 简单直接，无需 git subtree 知识 |
| 只需要部分语言（且希望快照也裁剪） | 方式三：CLI 裁剪复制（vendor） | 快照只包含所需语言（更小） |
| **不确定？** | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新 |
---
### ⚡ TL;DR - 30 秒快速开始
### TL;DR - 30 秒快速开始
大部分项目只需运行以下命令即可完成落地（以 TSL 为例）：
以 TSL 为例：
```bash
# 1. 引入标准快照
git subtree add --prefix docs/standards/playbook \
https://git.mytsl.cn/csh/playbook.git main --squash
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
# 2. 在项目根创建配置（示例见 docs/standards/playbook/playbook.toml.example）
cat <<'EOF' > playbook.toml
[playbook]
project_root = "."
# 3. 提交
[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"
```
**完成！** 后续同步更新只需重复步骤 1（把 `add` 改为 `pull`）和步骤 2。
详细说明和其他方式见下文 ↓
---
### 方式一：git subtree 同步（推荐）
@@ -106,213 +210,73 @@ git commit -m ":package: deps(playbook): add tsl standards"
1. 在目标项目中首次引入：
```bash
git subtree add \
--prefix docs/standards/playbook \
https://git.mytsl.cn/csh/playbook.git \
main --squash
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
git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
```
#### 快速落地（最小 4 步）
3. 在项目根配置并执行：
在目标项目中按以下顺序执行即可完成落地（推荐固定使用
`--prefix docs/standards/playbook`）：
```toml
# playbook.toml
[playbook]
project_root = "."
1. 引入标准快照（见上文 `git subtree add`）
2. 同步到项目根目录（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
[sync_standards]
langs = ["tsl", "cpp"]
[sync_rules]
[sync_memory_bank]
project_name = "MyProject"
```
```bash
sh docs/standards/playbook/scripts/sync_standards.sh
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
```
同步 C++ 规则集（同一份快照，不同规则集）：
配置参数说明见 `docs/standards/playbook/playbook.toml.example`。
```bash
sh docs/standards/playbook/scripts/sync_standards.sh cpp
```
一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）：
```bash
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`）：
```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 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 tsl
```
旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。
#### 可选：项目包装脚本（多 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/<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`（项目自行维护）
<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 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
如果不使用 git subtree，也可手动复制快照到目标项目：
步骤：
1. 创建目录：`docs/standards/playbook/`。
2. 复制 Playbook 快照内容（建议使用方式三生成裁剪快照）。
3. 在项目根执行统一入口：
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）。
```bash
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
```
该方式没有自动同步能力，后续更新需重复上述复制流程。
---
### 方式三：脚本裁剪复制（按语言，离线）
### 方式三：CLI 裁剪复制（按语言，离线）
当你希望“只 vendoring 需要的语言规范”（例如只需要 `tsl` +
`cpp`）时，可直接运行本仓库提供的裁剪脚本：
当你希望只 vendoring 需要的语言规范（例如只需要 `tsl` + `cpp`）时：
- macOS/Linux：
```toml
# playbook.toml
[playbook]
project_root = "/path/to/target-project"
```bash
sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh <target-project-root> tsl cpp
```
[vendor]
langs = ["tsl", "cpp"]
```
- PowerShell：
```bash
python scripts/playbook.py -config playbook.toml
```
```powershell
powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -DestRoot <target-project-root> -Langs tsl,cpp
```
该动作仅生成裁剪快照，不会隐式同步 `.agents/` 或 `.gitattributes`；后续请用 `sync_standards` 明确落地。
- Windows bat：
```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++/其他语言）
@@ -323,114 +287,36 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
- 行尾与文本规范：`.gitattributes`
- 代理最低要求：`.agents/*`（工作原则、质量底线、安全边界）
2. **语言级（Language-specific）规范**：只对某个语言成立的风格与工具。
- 例如 TSL 的命名/文件顶层声明限制、C++ 的
`.clang-format/.clang-tidy`、Python 的 `ruff` 等。
- 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。
**建议**：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相"污染"。
本仓库提供两套代理规则集（同步后位于目标项目的 `.agents/tsl/` 与
`.agents/cpp/`）：
本仓库提供多套代理规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/markdown/`）：
- 两者都包含跨语言通用底线：`auth.md`、`code_quality.md`、`performance.md`、`testing.md`
- 并在 `index.md`
中叠加语言级“硬约束”（TSL/TSF 语法限制、C++23/Modules、Windows 支持等）
- 三者都包含核心约定与安全红线
- 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、Markdown 代码格式化等）
多语言项目推荐结构（示例：TSL + C++ + Python）：
**多语言项目推荐结构**（示例：TSL + C++ + Python + Markdown）：
```txt
.
├── .agents/
│ ├── index.md # 多语言索引（缺省时由脚本创建）
│ ├── index.md # 多语言索引（缺省时由 playbook 生成）
│ ├── tsl/ # 由本 Playbook 同步（适用于 .tsl/.tsf）
│ ├── cpp/ # 由本 Playbook 同步（适用于 C++23/Modules）
│ └── python/ # Python 规则集（同上）
├── .gitattributes # 行尾/文本规范（可由某个 playbook 同步）
│ ├── python/ # Python 规则集（同上）
│ └── markdown/ # Markdown 规则集（仅代码格式化）
├── .gitattributes # 行尾/文本规范
├── docs/
│ ├── standards/
│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring；包含 common/tsl/cpp）
│ │ └── python/ # Python playbook 快照（可选）
│ │ └── playbook/ # 本 Playbook 快照（git subtree/vendoring）
│ └── project/ # 项目自有文档（架构、ADR、运行方式等）
├── scripts/
│ └── sync_standards.sh # 项目包装脚本：依次调用各 playbook 的 sync
├── playbook.toml # 统一入口配置
└── src/ # 源码目录（按项目实际情况）
```
规则优先级建议：
**规则优先级建议**：
- 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖。
- 同一项目内多个规则集并行放在 `.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 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 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 形式提交。
- 新规则需包含动机、示例、迁移建议（如有）。
`src/foo/.agents/`），并以"离代码更近者优先"为准