📝 docs(tsl): clarify syntax constraints and enhance test infrastructure

- Add TSF file naming constraint to syntax/02_core_model.md - Clarify semicolon rules: syntax facts vs style preferences - Separate control flow end semicolon rules (syntax allows both) - Add function body semicolon requirements to syntax/05_functions_and_calls.md - Move style preferences to code_style.md (control flow end semicolons) - Remove cross-references from syntax docs to maintain independence - Enhance Gitea workflow emoji for better CI output readability - Fix CI test path from tests/ to test/ - Organize agent test results under test/agent/result/ directory - Add complete Chinese translation of test cases (test_cases_zh.md) - Clean up .gitignore to use unified test/agent/result/ directory - Remove obsolete agent test artifacts (REPORTS_LOCATION.md, old results) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-06-21 17:04:50 +08:00
parent 6026401907
commit 8b93311cae
138 changed files with 7018 additions and 1705 deletions
@@ -9,17 +9,6 @@ Playbook：工程规范与代理规则合集，当前覆盖：
 - JavaScript（`.js`/`.mjs`/`.cjs`）
 - Markdown（代码格式化）

-## 原则
-
-1. **可读性优先**：读代码的时间远大于写代码
-2. **一致性优先**：同一仓库内保持一致比追求"最优风格"更重要
-3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格
-
-## 适用范围
-
- 本指南适用于所有 TSL/C++/Python/TypeScript/JavaScript/Markdown 相关仓库与脚本
- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移
-
 ## docs/（开发规范）

 `docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
@@ -77,36 +66,7 @@ project_name = "MyProject"
 - **CLAUDE.md**：自动检测（根目录 → `.claude/`），不存在则创建；注入 `@AGENTS.md` / `@AGENT_RULES.md`
 - **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（会先备份）

-### 工作流留痕 helper
-
-如果项目已经部署了这套模板，并使用 `superpowers` 工作流：
-
-```bash
-# spec 写完后
-python <playbook_root>/scripts/playbook.py \
-  -record-spec docs/superpowers/specs/<topic>-design.md \
-  -progress memory-bank/progress.md
-
-# plan 写完后
-python <playbook_root>/scripts/playbook.py \
-  -record-plan docs/superpowers/plans/<topic>.md \
-  -progress memory-bank/progress.md
-```
-
-这两个 helper 只负责把 `workflow-state` 写入
-`memory-bank/progress.md`。
-spec/plan 产出阶段不单独提交；最终随对应 Plan 的交付变更统一归档。
-真正执行 Plan 仍然走 `main_loop.py claim/finish`。
-
-完整主链只在 `templates/AGENT_RULES.template.md` 定义，这里不重复展开。
-如果项目采用 `superpowers`：
-
- 设计产物落到 `docs/superpowers/specs/`
- 计划产物落到 `docs/superpowers/plans/`
- 状态留痕通过 `playbook.py -record-spec/-record-plan` 与
-  `main_loop.py claim/finish` 维护
-
-详见：`templates/README.md`
+更多说明详见 [templates/README.md](templates/README.md)。

 ## rulesets/（规则集模板库 - 三层架构）

@@ -124,7 +84,7 @@ spec/plan 产出阶段不单独提交；最终随对应 Plan 的交付变更统

 ```txt
 Layer 1: rulesets/          (≤50 行/语言，模板源)
-  ├─ 核心约束与安全红线
+  ├─ 语言特有的核心约束
  └─ 指向 Skills 和 docs

 Layer 2: skills/           (按需加载，$skill-name 触发)
@@ -140,7 +100,7 @@ Layer 3: docs/             (权威静态文档)

 | 层级    | 加载方式                       | 内容                           | 作用                       |
 | ------- | ------------------------------ | ------------------------------ | -------------------------- |
-| Layer 1 | 自动，始终在上下文             | 硬约束与安全红线               | 快速判断能做/不能做        |
+| Layer 1 | 自动，始终在上下文             | 语言特有的核心约束             | 快速判断能做/不能做        |
 | Layer 2 | `$<skill-name>` 触发或代理判定 | 操作指南、最佳实践、工作流     | 指导具体怎么做             |
 | Layer 3 | 按需读取特定章节               | 完整语言手册、代码风格、工具链 | 最终权威（冲突时以此为准） |

@@ -159,7 +119,7 @@ Layer 3: docs/             (权威静态文档)

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

- 可做：增加安全漏洞类型、更新核心约定、添加硬性约束
+- 可做：更新核心约定、添加语言特有的硬性约束(命名/语法/工具链)
 - 不可做：添加推荐型最佳实践（→ skill）、详细语法解释（→ skill/docs）、超过 50 行（→ 拆分）

 **Skills（Layer 2）创建规则**：
@@ -168,20 +128,9 @@ Layer 3: docs/             (权威静态文档)

 ## SKILLS（Codex CLI / Claude Code）

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

-TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。
-
-**通用 Skills**：
-
- `$commit-message`：提交信息规范
- `$gitea-fix-ci`：诊断 Gitea Actions / PR checks 失败并按批准计划修复
- `$style-cleanup`：整理代码风格
- 更多见 `SKILLS.md`
-
-**安装与使用**：详见 `SKILLS.md`
-
-如果你通过 `[install_skills]` 更新已经安装过的 skill，默认会先把旧目录备份为 `*.bak.<timestamp>`；如果你明确希望“删除旧版本后直接重装”，可在 `playbook.toml` 的 `[install_skills]` 下设置 `no_backup = true`。
+安装与使用详见 [SKILLS.md](SKILLS.md)。

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

@@ -195,46 +144,6 @@ TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。
 | 不想把 Playbook 以 subtree 嵌进仓库，但仍要把标准部署到项目内 | 方式二：外部 clone 后执行部署     | Playbook 仓库与业务仓库解耦，部署根目录可配置 |
 | **不确定？**                                                  | **方式一：`git subtree`（推荐）** | 项目内可见、版本可追溯、使用路径最稳定        |

---
-
-### TL;DR - 30 秒快速开始
-
-先区分三个路径概念：
-
- `project_root`：目标项目根目录。
- `playbook_root`：相对于 `project_root` 的项目内 Playbook 根目录。
- `install_mode`：`subtree` 表示 Playbook 已由 git subtree 放在项目内；`snapshot` 表示从外部 clone 安装裁剪快照。
- 外部 clone 出来的 Playbook 路径（如 `/opt/playbook`）：只是执行安装脚本的位置，不是项目内 Playbook 根目录。
-
-以 TSL 为例，Playbook 在项目内的默认根是 `docs/standards/playbook`；如果你把 `playbook_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
-
-# 2. 在项目根创建配置（示例见 docs/standards/playbook/playbook.toml.example）
-cat <<'EOF' > playbook.toml
-[playbook]
-project_root = "."
-playbook_root = "docs/standards/playbook"
-install_mode = "subtree"
-
-[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"
-```
-
---
-
 ### 方式一：git subtree 同步（推荐）

 1. 在目标项目中首次引入：
@@ -271,7 +180,7 @@ git commit -m ":package: deps(playbook): add tsl standards"
   python docs/standards/playbook/scripts/playbook.py -config playbook.toml
   ```

-配置参数说明见 `docs/standards/playbook/playbook.toml.example`。
+配置参数说明见 [playbook.toml.example](playbook.toml.example)。

 ---

@@ -285,11 +194,7 @@ git commit -m ":package: deps(playbook): add tsl standards"
   git clone https://git.mytsl.cn/csh/playbook.git /opt/playbook
   ```

-2. 在目标项目根创建 `playbook.toml`，并用 `playbook_root` 指定项目内的 Playbook 根。例如：
-   - `project_root` 写目标项目根目录。
-   - `playbook_root` 写目标项目内的相对路径。
-   - `install_mode = "snapshot"` 表示由外部 clone 安装项目内快照。
-   - 不要把外部 clone 的路径（如 `/opt/playbook`）写进 `playbook_root`；那只是你执行脚本的位置。
+2. 在目标项目根创建 `playbook.toml`：

   ```toml
   [playbook]
@@ -312,12 +217,7 @@ git commit -m ":package: deps(playbook): add tsl standards"
   python /opt/playbook/scripts/playbook.py -config playbook.toml
   ```

-说明：
-
- `install_mode = "snapshot"` 会先把 Playbook 裁剪快照安装到目标项目的 `playbook_root`，再执行后续同步动作。
- `playbook_root` 永远表示目标项目内的 Playbook 根；它不是外部 clone 出来的 Playbook 仓库路径。
- 外部 clone 场景下必须显式填写 `playbook_root`；脚本不会替你补默认项目内根目录。
- 如果 `playbook_root = "custom/playbook"`，部署后的项目内入口会是 `custom/playbook/scripts/playbook.py`、`custom/playbook/docs/index.md`。
+**说明**：`playbook_root` 表示项目内的部署目录，不是外部 clone 的路径。

 ---

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

 本仓库提供多套代理规则集（同步后位于目标项目的 `.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）：
@@ -366,5 +266,4 @@ git commit -m ":package: deps(playbook): add tsl standards"
 **规则优先级建议**：

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