Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d

25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
2026-05-24 13:04:14 +08:00
parent 35e6a301aa
commit 3d83740f88
292 changed files with 30774 additions and 218828 deletions
@@ -24,40 +24,24 @@ Playbook：工程规范与代理规则合集，当前覆盖：

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

- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python / TypeScript / 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 语法手册（整理自原始语法/机制目录册；函数库位于
-  `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 基线）。
- `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），用于自动化校验部分规范。
+- `docs/index.md`：文档导航入口
+- `docs/common/`：跨语言规范（提交信息、版本号）
+- `docs/tsl/`：TSL 规范（语法手册、金融业务、模块、函数检索、代码风格、命名、工具链）
+- `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-stack、architecture、progress、decisions）
- `templates/prompts/`：工作流程模板（agent-behavior、clarify、review）
+- `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`：执行流程模板

@@ -76,7 +60,7 @@ python scripts/playbook.py -config playbook.toml
 project_root = "/path/to/project"

 [sync_rules]
-# force = true  # 可选
+# force = true # 可选

 [sync_memory_bank]
 project_name = "MyProject"
@@ -88,8 +72,29 @@ project_name = "MyProject"

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

+### 工作流留痕 helper
+
+如果项目已经部署了这套模板，并使用 `superpowers` 工作流：
+
+```bash
+# spec 写完后
+python <deploy_root>/scripts/playbook.py \
+  -record-spec docs/superpowers/specs/<topic>-design.md \
+  -progress memory-bank/progress.md
+
+# plan 写完后
+python <deploy_root>/scripts/playbook.py \
+  -record-plan docs/superpowers/plans/<topic>.md \
+  -progress memory-bank/progress.md
+```
+
+这两个 helper 只负责把 `workflow-state` 写入
+`memory-bank/progress.md`。
+真正执行 Plan 仍然走 `main_loop.py claim/finish`。
+
 详见：`templates/README.md`

 ## rulesets/（规则集模板库 - 三层架构）
@@ -111,11 +116,11 @@ Layer 1: rulesets/          (≤50 行/语言，模板源)
  ├─ 核心约束与安全红线
  └─ 指向 Skills 和 docs

-Layer 2: codex/skills/     (按需加载，$skill-name 触发)
-  ├─ tsl-guide: TSL 渐进式语法教学
+Layer 2: skills/           (按需加载，$skill-name 触发)
  ├─ commit-message: 提交信息规范
  ├─ style-cleanup: 代码风格整理
-  └─ bulk-refactor-workflow: 批量重构流程
+  ├─ bulk-refactor-workflow: 批量重构流程
+  └─ thirdparty/: 第三方同步 skills

 Layer 3: docs/             (权威静态文档)
  └─ 完整语法手册/代码风格/工具链配置
@@ -132,21 +137,14 @@ Layer 3: docs/             (权威静态文档)
 **目录结构**：

 - `rulesets/index.md`：规则集索引（跨语言）
- `rulesets/tsl/index.md`：TSL 核心约定（44 行）
- `rulesets/cpp/index.md`：C++ 核心约定（47 行）
- `rulesets/python/index.md`：Python 核心约定（45 行）
+- `rulesets/tsl/index.md`：TSL 核心约定（45 行）
+- `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 规模  | ~500 行 | 167 行 | -67% |
-| 持久化 tokens | ~12,500 | ~4,200 | -66% |
-
 ### 维护原则

 **.agents/（Layer 1）修改规则**：
@@ -158,13 +156,11 @@ Layer 3: docs/             (权威静态文档)

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

-## SKILLS（Codex CLI）
+## SKILLS（Codex CLI / Claude Code）

-本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于按需加载的工作流与知识库。
+本仓库内置一组 AI agent skills（见 `skills/`），支持 Codex CLI 和 Claude Code，用于按需加载的工作流与知识库。

-**核心 Skills**：
-
- **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践）
+TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。

 **通用 Skills**：

@@ -175,28 +171,37 @@ Layer 3: docs/             (权威静态文档)

 **安装与使用**：详见 `SKILLS.md`

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

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

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

-| 你的情况                           | 推荐方式                        | 优势                            |
-| ---------------------------------- | ------------------------------- | ------------------------------- |
-| 新项目，需要持续同步更新           | 方式一：git subtree             | 可随时拉取最新标准，版本可追溯  |
-| 只需要一次性引入，不常更新         | 方式二：手动复制快照            | 简单直接，无需 git subtree 知识 |
-| 只需要部分语言（且希望快照也裁剪） | 方式三：CLI 裁剪复制（vendor）  | 快照只包含所需语言（更小）      |
-| **不确定？**                       | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新      |
+| 你的情况                                                      | 推荐方式                          | 优势                                          |
+| ------------------------------------------------------------- | --------------------------------- | --------------------------------------------- |
+| 新项目，需要持续同步更新                                      | 方式一：`git subtree`             | 标准留在项目内，后续可拉取更新                |
+| 不想把 Playbook 以 subtree 嵌进仓库，但仍要把标准部署到项目内 | 方式二：外部 clone 后执行部署     | Playbook 仓库与业务仓库解耦，部署根目录可配置 |
+| **不确定？**                                                  | **方式一：`git subtree`（推荐）** | 项目内可见、版本可追溯、使用路径最稳定        |

 ---

 ### TL;DR - 30 秒快速开始

-以 TSL 为例：
+先区分三个路径概念：
+
+- `project_root`：目标项目根目录。
+- `deploy_root`：相对于 `project_root` 的项目内目标目录。
+- 外部 clone 出来的 Playbook 路径（如 `/opt/playbook`）：只是执行部署脚本的位置，不是部署目标。
+
+以 TSL 为例，Playbook 在项目内的默认部署根是 `docs/standards/playbook`；如果你把 `deploy_root` 改成 `custom/playbook`，则部署结果会落到 `<project_root>/custom/playbook`，文档和脚本入口也会跟着变成 `custom/playbook/docs/...`、`custom/playbook/scripts/...`。
+
+#### 方式一：`git subtree`

 ```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. 在项目根创建配置（示例见 docs/standards/playbook/playbook.toml.example）
 cat <<'EOF' > playbook.toml
@@ -222,13 +227,13 @@ 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
   ```

 3. 在项目根配置并执行：
@@ -255,38 +260,50 @@ git commit -m ":package: deps(playbook): add tsl standards"

 ---

-### 方式二：手动复制快照
+### 方式二：外部 clone 后执行部署

-如果不使用 git subtree，也可手动复制快照到目标项目：
+如果你不想把 Playbook 以 `git subtree` 嵌进目标项目，可以把 Playbook clone 到项目外部，再由该 clone 直接把标准部署进目标项目。

-1. 创建目录：`docs/standards/playbook/`。
-2. 复制 Playbook 快照内容（建议使用方式三生成裁剪快照）。
-3. 在项目根执行统一入口：
+1. 先在任意位置 clone Playbook：

   ```bash
-   python docs/standards/playbook/scripts/playbook.py -config playbook.toml
+   git clone https://git.mytsl.cn/csh/playbook.git /opt/playbook
   ```

---
+2. 在目标项目根创建 `playbook.toml`，并用 `deploy_root` 指定项目内的部署根。例如：
+   - `project_root` 写目标项目根目录。
+   - `deploy_root` 写目标项目内的相对路径。
+   - 不要把外部 clone 的路径（如 `/opt/playbook`）写进 `deploy_root`；那只是你执行脚本的位置。

-### 方式三：CLI 裁剪复制（按语言，离线）
+   ```toml
+   [playbook]
+   project_root = "."
+   deploy_root = "custom/playbook"

-当你希望只 vendoring 需要的语言规范（例如只需要 `tsl` + `cpp`）时：
+   [vendor]
+   langs = ["tsl"]

-```toml
-# playbook.toml
-[playbook]
-project_root = "/path/to/target-project"
+   [sync_standards]
+   langs = ["tsl"]

-[vendor]
-langs = ["tsl", "cpp"]
-```
+   [sync_rules]

-```bash
-python scripts/playbook.py -config playbook.toml
-```
+   [sync_memory_bank]
+   project_name = "MyProject"
+   ```

-该动作仅生成裁剪快照，不会隐式同步 `.agents/` 或 `.gitattributes`；后续请用 `sync_standards` 明确落地。
+3. 在目标项目根执行外部 clone 里的统一入口：
+
+   ```bash
+   python /opt/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`。

 ---

@@ -305,7 +322,7 @@ python scripts/playbook.py -config playbook.toml

 本仓库提供多套代理规则集（同步后位于目标项目的 `.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）：
@@ -320,10 +337,14 @@ python scripts/playbook.py -config playbook.toml
 │   ├── typescript/                   # TypeScript/JavaScript 规则集（同上）
 │   └── markdown/                     # Markdown 规则集（仅代码格式化）
 ├── .gitattributes                    # 行尾/文本规范
-├── docs/
-│   ├── standards/
-│   │   └── playbook/                 # 本 Playbook 快照（git subtree/vendoring）
-│   └── project/                      # 项目自有文档（架构、ADR、运行方式等）
+├── AGENTS.md                         # Codex 入口（由 playbook 自动生成/更新）
+├── CLAUDE.md                         # Claude Code 入口（自动注入 @AGENTS.md）
+├── <deploy_root>/                    # 本 Playbook 在项目内的部署根（默认 docs/standards/playbook）
+│   ├── docs/
+│   ├── rulesets/
+│   ├── scripts/
+│   └── templates/
+├── docs/project/                     # 项目自有文档（架构、ADR、运行方式等）
 ├── playbook.toml                     # 统一入口配置
 └── src/                              # 源码目录（按项目实际情况）
 ```