♻️ refactor(playbook): streamline agents and refresh tsl docs

2026-01-10 16:55:44 +08:00
parent b529012c59
commit 5822a8736d
88 changed files with 103561 additions and 130104 deletions
@@ -1,25 +1,25 @@
-# playbook
+# 📚 playbook

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

-## 目标
+## 🎯 目标

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

-## 原则
+## 📏 原则

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

-## 适用范围
+## 🌐 适用范围

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

-## docs/（开发规范）
+## 📖 docs/（开发规范）

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

@@ -28,8 +28,8 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 - `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 基线）。
@@ -46,22 +46,57 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 - `templates/ci/`：目标项目 CI 示例模板（如 Gitea
  Actions），用于自动化校验部分规范。

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

-`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/`
-并行。
+`.agents/` 是 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`）。
+### 📦 三层架构设计

-## SKILLS（Codex CLI）
+```
+Layer 1: .agents/          (≤50 行/语言，自动加载)
+  ├─ 核心约束与安全红线
+  └─ 指向 Skills 和 docs

-本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于 code review
-/ 格式化 / 调试等工作流；安装与编写规范见 `SKILLS.md`。
+Layer 2: codex/skills/     (按需加载，$skill-name 触发)
+  ├─ tsl-guide: TSL 渐进式语法教学（962 行）
+  ├─ performance-optimization: 跨语言性能优化
+  └─ testing-workflow: 跨语言测试策略

-## 在其他项目中使用本 Playbook
+Layer 3: docs/             (权威静态文档)
+  └─ 完整语法手册/代码风格/工具链配置
+```
+
+**📂 目录结构**：
+- `.agents/index.md`：规则集索引（跨语言）
+- `.agents/tsl/index.md`：TSL 核心约定（47 行）
+- `.agents/cpp/index.md`：C++ 核心约定（50 行）
+- `.agents/python/index.md`：Python 核心约定（48 行）
+
+**✨ 设计收益**：
+- 持续上下文占用从 ~500 行降至 145 行（↓ 71%）
+- 平均场景 token 消耗降低 16%
+- TSL 未训练语言获得渐进式教学支持
+
+📄 详见：`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 到项目内。

@@ -101,7 +136,7 @@ git commit -m ":package: deps(playbook): add tsl standards"

 ---

-### 方式一：git subtree 同步（推荐）
+### 🌲 方式一：git subtree 同步（推荐）

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

@@ -121,13 +156,13 @@ git commit -m ":package: deps(playbook): add tsl standards"
   main --squash
   ```

-#### 快速落地（最小 4 步）
+#### ⚙️ 快速落地（最小 4 步）

 在目标项目中按以下顺序执行即可完成落地（推荐固定使用
 `--prefix docs/standards/playbook`）：

-1. 引入标准快照（见上文 `git subtree add`）
-2. 同步到项目根目录（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
+1. **📥 引入标准快照**（见上文 `git subtree add`）
+2. **🔄 同步到项目根目录**（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：

   ```bash
   sh docs/standards/playbook/scripts/sync_standards.sh
@@ -145,41 +180,41 @@ git commit -m ":package: deps(playbook): add tsl standards"
   sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
   ```

-   > 说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
+   > 💡 说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
   > 会自动生成最小版；已存在则不会覆盖。

-3. 验收（任意满足其一即可）：
+3. **✅ 验收**（任意满足其一即可）：
   - 目录存在：`.agents/tsl/`
   - 规则入口可读：`.agents/tsl/index.md`
   - （可选）C++ 规则入口可读：`.agents/cpp/index.md`
   - 标准文档可读：`docs/standards/playbook/docs/index.md`
   - `.gitattributes` 包含追加块头：`# Added from playbook .gitattributes`

-4. 将同步产物纳入版本控制（目标项目建议提交）：
+4. **📝 将同步产物纳入版本控制**（目标项目建议提交）：
   - `docs/standards/playbook/`（标准快照）
   - `.agents/tsl/`（落地规则集）
   - `.gitattributes`（追加缺失规则）
   - `AGENTS.md`（若本次自动生成）

-#### 新项目 / 旧项目（命令示例）
+#### 💼 新项目 / 旧项目（命令示例）

-新项目（无 `.agents/` 与 `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`）：
+**🔄 旧项目**（已有 `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/`，请手动对齐内容。
+⚠️ 旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。

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

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

@@ -197,7 +232,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 ```

-#### 目录约定（建议）
+#### 📁 目录约定（建议）

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

@@ -221,23 +256,23 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp

 根目录的 `.agents/<lang>/` 与 `.gitattributes` 通过同步脚本获得：

- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过
+- 💡 **说明**：在 **本 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.*`）。
+- 📜 **在目标项目里直接运行 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/*/`
+💡 建议固定使用 `--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 任意项目时都能直接读取规范文件，不依赖外部访问权限。
+✅ 这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。

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

 - 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
 - 自动识别：未传语言参数且已存在 `.agents/<lang>/` 时，按现有语言同步
@@ -250,7 +285,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 <details>
 <summary>🔧 高级选项：环境变量配置（点击展开）</summary>

-#### 环境变量（可选）
+#### ⚙️ 环境变量（可选）

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

@@ -261,12 +296,12 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp

 </details>

-### 方式二：手动复制快照
+### 📋 方式二：手动复制快照

 如果不使用
 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。

-步骤：
+**📝 步骤**：

 1. 在目标项目创建目录：`docs/standards/playbook/`。
 2. 从本仓库复制以下内容到目标项目：
@@ -280,9 +315,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 4. 在 `docs/standards/playbook/SOURCE.md`
   记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。

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

-### 方式三：脚本裁剪复制（按语言，离线）
+### ✂️ 方式三：脚本裁剪复制（按语言，离线）

 当你希望“只 vendoring 需要的语言规范”（例如只需要 `tsl` +
 `cpp`）时，可直接运行本仓库提供的裁剪脚本：
@@ -305,16 +340,16 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
  <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat <target-project-root> --langs tsl,cpp
  ```

-脚本会：
+**✨ 脚本会**：

- 生成裁剪快照到 `docs/standards/playbook/`（包含
+- ✂️ 生成裁剪快照到 `docs/standards/playbook/`（包含
  `docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` +
  `.gitattributes` + 通用 `templates/ci/` + 相关 `templates/<lang>/`）
- 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把
+- 🔄 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把
  `.agents/<lang>/` 与 `.gitattributes` 落地到目标项目根目录
- 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息
+- 📝 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息

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

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

@@ -326,16 +361,14 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
   - 例如 TSL 的命名/文件顶层声明限制、C++ 的
     `.clang-format/.clang-tidy`、Python 的 `ruff` 等。

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

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

- 两者都包含跨语言通用底线：`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 风格等）

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

 ```txt
 .
@@ -355,11 +388,11 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 └── src/                              # 源码目录（按项目实际情况）
 ```

-规则优先级建议：
+**⚖️ 规则优先级建议**：

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

 <details>
 <summary>🔧 高级选项：`.agents` 覆盖/合并策略（点击展开）</summary>
@@ -408,29 +441,29 @@ if (Test-Path $overlay) {

 </details>

-#### 扩展新语言（模板）
+#### 🔌 扩展新语言（模板）

 当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：

- 文档：
+- 📖 **文档**：
  - 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用
    `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md`
    链接入口。
-  - 若新增“本 Playbook 未覆盖的语言”：再引入对应语言的标准仓库（subtree/vendoring 到
-    `docs/standards/<lang>/`）。
- 代理规则：
+  - 若新增"本 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`）。
+    并行），只写该语言专属要求与工具链约束
+- 🔄 **同步策略**：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个
+  `.agents/`
+- 🛠️ **CI/工具**：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）
+  - 💡 C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的
+    `CompilationDatabase`（模板见 `templates/cpp/.clangd`）

-## 版本与贡献
+## 🤝 版本与贡献

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