# playbook

Playbook：工程规范与智能体规则合集，当前覆盖：

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

## docs/（开发规范）

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

- `docs/index.md`：文档导航入口
- `docs/common/`：跨语言规范（提交信息、版本号）
- `docs/tsl/`：TSL 静态路由、金融业务、模块、函数检索、代码风格、命名和工具链；语法事实由 `tsl-syntax-reference` 管理
- `docs/cpp/`：C++ 规范（C++23/Modules、Google 基线、Conan、clangd）
- `docs/python/`：Python 规范（Google 基线、black/isort/flake8/pylint/mypy/pytest）
- `docs/typescript/`：TypeScript 规范（Google 基线、prettier/eslint/vitest）
- `docs/markdown/`：Markdown 规范（仅代码格式化）

落地模板：`templates/cpp/`、`templates/python/`、`templates/ci/`。

详见 `docs/index.md`。

## templates/（项目架构模板）

`templates/` 目录除了语言配置模板外，还包含 AI 智能体工作环境的项目架构模板：

- `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-context、system-patterns、active-context、progress、decisions）
- `templates/prompts/`：任务入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review），不是流程权威
- `templates/AGENTS.template.md`：入口导航模板（项目主入口）
- `templates/AGENT_RULES.template.md`：superpowers-first 执行规则模板

### 快速部署

统一入口（配置驱动，示例见 `playbook.toml.example`）：

```bash
python scripts/playbook.py -config playbook.toml
```

示例配置（部署项目架构模板）：

```toml
[playbook]
project_root = "/path/to/project"
playbook_root = "docs/standards/playbook"
install_mode = "snapshot"

[sync_rules]
# force = true # 可选

[sync_memory_bank]
project_name = "MyProject"

[sync_prompts]
```

**部署行为**：

- **配置节存在即启用**：只写需要同步的配置节
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`）
- **CLAUDE.md**：自动检测（根目录 → `.claude/`），不存在则创建；注入 `@AGENTS.md` / `@AGENT_RULES.md`
- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（会先备份）

更多说明详见 [templates/README.md](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: skills/           (按需加载，$skill-name 触发)
  ├─ commit-message: 提交信息规范
  ├─ tsl-syntax-reference: TSL 语法条目、写法验证和错误边界
  ├─ tsl-api-reference: TSL API 名称、签名、参数和返回值
  └─ thirdparty/: 第三方同步 skills

Layer 3: docs/             (仓库内静态文档)
  └─ 静态规范/代码风格/工具链/模块与集成文档
```

**各层职责**：

| 层级    | 加载方式                         | 内容                                   | 作用                                  |
| ------- | -------------------------------- | -------------------------------------- | ------------------------------------- |
| Layer 1 | 自动，始终在上下文               | 核心约束、优先级、所有者路由和阻断规则 | 快速定位事实所有者并判断能做/不能做   |
| Layer 2 | `$<skill-name>` 触发或智能体判定 | 操作指南、工作流和可安装参考知识       | 执行任务或查询 Skill 所拥有的事实     |
| Layer 3 | 按需读取特定章节                 | 静态规范、代码风格、工具链和模块文档   | 管理仓库内静态事实，不覆盖 Skill 事实 |

TSL 语法事实唯一由 `tsl-syntax-reference` 管理；`rulesets/tsl/index.md` 和 `docs/tsl/` 只负责路由、边界及各自拥有的非语法事实。

**目录结构**：

- `rulesets/index.md`：规则集索引（跨语言）
- `rulesets/tsl/index.md`：TSL 领域路由与事实边界
- `rulesets/cpp/index.md`：C++ 核心约定（46 行）
- `rulesets/python/index.md`：Python 核心约定（44 行）
- `rulesets/typescript/index.md`：TypeScript 核心约定（47 行）
- `rulesets/markdown/index.md`：Markdown 核心约定（31 行，仅代码格式化）

更多说明：`rulesets/index.md`

### 维护原则

**.agents/（Layer 1）修改规则**：

- 可做：更新核心约定或事实所有者路由、添加语言特有的项目级硬性边界
- 不可做：添加推荐型最佳实践（→ skill）、复制其他事实所有者的详细内容、超过 50 行（→ 拆分）

**Skills（Layer 2）创建规则**：

- 可做：增加新流程、从零教授新语言、添加跨语言通用知识

## SKILLS（Codex CLI / Claude Code）

本仓库内置 AI agent skills，支持 Codex CLI 和 Claude Code，用于按需加载的工作流与知识库。

TSL 完整能力需要同时安装 `tsl-syntax-reference` 与 `tsl-api-reference`：

```toml
[install_skills]
agents_home = "~/.agents"
mode = "list"
skills = ["tsl-syntax-reference", "tsl-api-reference"]
```

`[sync_standards]` 只部署规则集和文档，不会自动安装 Skill；Skill 安装由 `[install_skills]` 显式配置。

安装与使用详见 [SKILLS.md](SKILLS.md)。

## tools/（维护工具）

- `tools/tsl-codegen/`：TSL 函数文档生成、校验与索引工具套件，供维护 `tsl-api-reference` 的函数文档树使用，详见 [tools/tsl-codegen/README.md](tools/tsl-codegen/README.md)。

套件与 skill 解耦：手动部署 skill 时套件不随行；仅公共同步（`scripts/build_tsl_playbook.py` 构建 + `.gitea/workflows/sync-tsl-playbook.yml` 发布）会把套件随 skill 一起带到 `tsl-playbook` 分支。

## 在其他项目中使用本 Playbook

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

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

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

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

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

   ```bash
   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
   ```

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

   ```toml
   # playbook.toml
   [playbook]
   project_root = "."
   playbook_root = "docs/standards/playbook"
   install_mode = "subtree"

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

   [sync_rules]

   [sync_memory_bank]
   project_name = "MyProject"
   ```

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

配置参数说明见 [playbook.toml.example](playbook.toml.example)。

---

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

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

1. 先在任意位置 clone Playbook：

   ```bash
   git clone https://git.mytsl.cn/csh/playbook.git /opt/playbook
   ```

2. 在目标项目根创建 `playbook.toml`：

   ```toml
   [playbook]
   project_root = "."
   playbook_root = "custom/playbook"
   install_mode = "snapshot"

   [sync_standards]
   langs = ["tsl"]

   [sync_rules]

   [sync_memory_bank]
   project_name = "MyProject"
   ```

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

   ```bash
   python /opt/playbook/scripts/playbook.py -config playbook.toml
   ```

**说明**：`playbook_root` 表示项目内的部署目录，不是外部 clone 的路径。

---

### 多语言项目落地（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 使用语法/API 双 Skill 路由与 fail-closed；其他语言保留各自的版本、风格、类型或格式约束）

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

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

**规则优先级建议**：

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