🗑️ remove(legacy): drop old scripts and tests

2026-01-23 14:58:31 +08:00
parent 0c4cd0e037
commit b4f712acb4
23 changed files with 158 additions and 5516 deletions
@@ -58,25 +58,23 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）
 python scripts/playbook.py -config playbook.toml
 ```

-使用 `sync_templates` 脚本一键部署项目架构：
+示例配置（部署项目架构模板）：

-```bash
-# Linux/macOS
-sh scripts/sync_templates.sh -project-root /path/to/project
+```toml
+[playbook]
+project_root = "/path/to/project"

-# PowerShell
-.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project
-
-# Windows CMD
-scripts\sync_templates.bat -project-root C:\path\to\project
+[sync_templates]
+project_name = "MyProject"
+full = false
 ```

 **部署行为**：

 - **新项目**：创建完整的 `AGENTS.md`、`AGENT_RULES.md`、`memory-bank/`、`docs/prompts/`
 - **已有 AGENTS.md**：追加路由链接（使用 `<!-- playbook:templates:start/end -->` 标记）
- **-full 参数**：追加完整框架（规则优先级 + 新会话开始时）到已有 AGENTS.md
- **其他文件**：如果已存在则跳过（使用 `-force` 覆盖）
+- **full = true**：追加完整框架（规则优先级 + 新会话开始时）到已有 AGENTS.md
+- **其他文件**：如果已存在则跳过（使用 `force = true` 覆盖）

 详见：`templates/README.md`

@@ -87,7 +85,7 @@ scripts\sync_templates.bat -project-root C:\path\to\project
 > Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是：
 >
 > 1. 作为**模板源**，供其他项目复制
-> 2. 通过 `sync_standards.sh` 部署到目标项目的 `.agents/`
+> 2. 通过 playbook.py 的 `[sync_standards]` 部署到目标项目的 `.agents/`
 > 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成）

 `rulesets/` 是 AI 代理规则集模板（三层架构设计）：
@@ -138,7 +136,7 @@ Layer 3: docs/             (权威静态文档)

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

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

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

@@ -146,35 +144,36 @@ Layer 3: docs/             (权威静态文档)
 | ---------------------------------- | ------------------------------- | ------------------------------- |
 | 新项目，需要持续同步更新           | 方式一：git subtree             | 可随时拉取最新标准，版本可追溯  |
 | 只需要一次性引入，不常更新         | 方式二：手动复制快照            | 简单直接，无需 git subtree 知识 |
-| 只需要部分语言（且希望快照也裁剪） | 方式三：脚本裁剪复制            | 快照只包含所需语言（更小）      |
+| 只需要部分语言（且希望快照也裁剪） | 方式三：CLI 裁剪复制（vendor）  | 快照只包含所需语言（更小）      |
 | **不确定？**                       | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新      |

-**大部分情况推荐使用方式一（git subtree）。**
-说明：方式一可选择同步哪些语言规则到 `.agents/`，但 `docs/standards/playbook/` 快照仍是全量；方式三会裁剪快照本身。
-
 ---

 ### 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 -langs 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 同步（推荐）
@@ -182,213 +181,71 @@ 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_templates]
+   project_name = "MyProject"
+   ```

   ```bash
-   sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
+   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 -langs cpp
-   ```
-
-   一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）：
-
-   ```bash
-   sh docs/standards/playbook/scripts/sync_standards.sh -langs 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 -langs 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 -langs tsl
-```
-
-旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。
-
-#### 可选：项目包装脚本（多 playbook 串联）
-
-多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：
-
-```sh
-#!/usr/bin/env sh
-set -eu
-
-sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
-# sh docs/standards/python/scripts/sync_standards.sh
-```
-
-也可以直接一次同步多个规则集：
-
-```sh
-sh docs/standards/playbook/scripts/sync_standards.sh -langs 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/...`）。同步时需显式指定
-语言参数（`-langs`），如需同步 C++ 规则集，推荐直接运行：
-`sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp`。
-
-这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
-
-**同步脚本行为**（目标项目内的最终落地内容）：
-
- 覆盖/更新：`.agents/<AGENTS_NS>/`（由 `-langs` 或 `AGENTS_NS` 指定）
- 更新 `.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 -project-root <target-project-root> -langs tsl,cpp
-  ```
+[vendor]
+langs = ["tsl", "cpp"]
+```

- PowerShell：
+```bash
+python scripts/playbook.py -config playbook.toml
+```

-  ```powershell
-  powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -ProjectRoot <target-project-root> -Langs tsl,cpp
-  ```
+该动作仅生成裁剪快照，不会隐式同步 `.agents/` 或 `.gitattributes`；后续请用 `sync_standards` 明确落地。

- Windows bat：
-
-  ```bat
-  <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat -project-root <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++/其他语言）

@@ -399,8 +256,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
   - 行尾与文本规范：`.gitattributes`
   - 代理最低要求：`.agents/*`（工作原则、质量底线、安全边界）
 2. **语言级（Language-specific）规范**：只对某个语言成立的风格与工具。
-   - 例如 TSL 的命名/文件顶层声明限制、C++ 的
-     `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
+   - 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。

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

@@ -414,19 +270,17 @@ sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
 ```txt
 .
 ├── .agents/
-│   ├── index.md                      # 多语言索引（缺省时由脚本创建）
+│   ├── index.md                      # 多语言索引（缺省时由 playbook 生成）
 │   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
 │   ├── cpp/                          # 由本 Playbook 同步（适用于 C++23/Modules）
 │   ├── python/                       # Python 规则集（同上）
 │   └── markdown/                     # Markdown 规则集（仅代码格式化）
-├── .gitattributes                    # 行尾/文本规范（可由某个 playbook 同步）
+├── .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/                              # 源码目录（按项目实际情况）
 ```

@@ -435,72 +289,3 @@ sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
 - 同一项目内多个规则集并行放在 `.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 -langs 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 -langs 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`）