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
@@ -1,7 +1,17 @@
 # TSL 代码风格（Code Style）

+文档类型：规范页
+是否可直接用于生成代码：仅部分
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md)
+
 本章节规定 TSL 代码的结构与格式约定。

+以下出现的 `<TOKEN>`、`<...>`、模板占位和单独标成 `反例 / 不可照写` 的块，只用于说明风格或反例，不等于可直接复制的源码字面量。
+
+本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法，不等于语法主线里“已验证会编译失败/运行失败”的反向边界；因此页头里的 `是否含已验证反例` 仍保持为 `否`。
+
 相关文档：

 - 命名规范：`docs/tsl/naming.md`
@@ -65,6 +75,8 @@

 - 代码块使用统一的块结构（示例按常见 TSL 写法；若项目语法/约定有差异，以项目现有代码为准）：

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 if cond then
 begin
@@ -81,6 +93,8 @@ end
 - `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
 - 单语句分支可省略 `begin/end`（保持清晰优先；一旦分支变复杂就回退到块结构）：

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 if cond then DoSomething()
 else DoOther()
@@ -100,8 +114,10 @@ else DoOther()
 - 复杂条件拆分为具名布尔变量或小函数。
 - 早返回优于深层嵌套：

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
-if !ok then return err
+if !ok then return err;
 // main path
 ```

@@ -136,6 +152,8 @@ if !ok then return err
 - 注释使用完整句子，末尾带标点。
 - 推荐模板（按需裁剪；语言可中英混写）：

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 // Summary: 一句话说明做什么（以及关键约束/边界）。
 // Args:
@@ -151,8 +169,21 @@ if !ok then return err
 - 避免“显而易见注释”：
 - 尾随注释（写在代码行末）只用于非常短的补充；超过一行时改为写在语句上方，或重构代码提醒意图。

+不推荐这样写：
+
+代码块身份：反例 / 不可照写
+代码块说明：风格反例，不是已验证语法反例。
+
 ```tsl
-count = count + 1  // bad: obvious
+count := count + 1;  // obvious
+```
+
+推荐直接删掉这类显而易见注释：
+
+代码块身份：配置片段 / 概念骨架
+
+```tsl
+count := count + 1;
 ```

 ### 3.4 TODO/FIXME
@@ -164,8 +195,7 @@ count = count + 1  // bad: obvious
 ## 4. 代码实践（Best Practices）

 > 本节偏“实践建议”（should），用于提升可读性/可测试性；若目标项目有更严格的约束与检查命令，以项目落地的工具链为准（参考
-> `docs/tsl/toolchain.md`）。如需给自动化/AI 代理配置强约束，可参考
-> `.agents/tsl/code_quality.md` 与 `.agents/tsl/testing.md`。
+> `docs/tsl/toolchain.md`）。如果项目对自动化或 AI 代理有额外要求，应把约束直接写进仓库内可见的检查脚本、CI 配置或项目文档，而不是依赖隐藏规范。

 ### 4.1 变量与常量

@@ -174,6 +204,8 @@ count = count + 1  // bad: obvious
 - 对外 API 优先只读：对外暴露用只读 property（只有 `read`，不写
  `write`），内部用私有成员保存。

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 type User = class
 public
@@ -196,6 +228,8 @@ end;
  `Style`（建议紧贴类型名书写）。
 - 示例（`{Unit.}` 前缀仅用于阅读，不改变类型名）：

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 type DocxContext = class
 public
@@ -210,6 +244,8 @@ function RenderParagraph(para_: {DocxML.}Paragraph): void;
 - 无返回值函数显式标注返回类型为 `void`；`create`/`destroy`
  作为构造/析构函数不写返回类型。

+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 function Func(a: string; b: ClassName): void;
 ```
@@ -222,21 +258,29 @@ function Func(a: string; b: ClassName): void;
  - 输入参数在前；可选配置/选项（如 `*Options`/`*Config`）居中；输出/回调在后。
  - 避免堆叠多个布尔开关参数；优先收敛到 `*Options`/`*Config`（按需在 `class` 或
    `unit` 中定义）。
- 示例：避免多个布尔开关参数（调用点难以理解 `true/false` 的含义），改为
+- 示例：避免多个开关参数直接堆在签名里（调用点难以理解各参数含义），改为
  `*Options`/`*Config`：

+不推荐这样写：
+
+代码块身份：反例 / 不可照写
+代码块说明：风格反例，不是已验证语法反例。
+
 ```tsl
-// 注：参数类型名按项目实际替换（此处 bool/Any 仅为示例占位）。
-// bad: 多个 bool 参数在调用点难读、易传错
 function ExportReport(
    path: string;
-    data: Any;
-    include_header: bool;
-    compress: bool;
-    dry_run: bool
+    rows: array;
+    include_header;
+    compress;
+    dry_run
 ): void;
+```

-// good: 将可选开关收敛到 Options（调用点更自解释、后续扩展更稳定）
+推荐把可选开关收敛到 `Options` / `Config`：
+
+代码块身份：配置片段 / 概念骨架
+
+```tsl
 type ExportOptions = class
 public
    property IncludeHeader read include_header_ write include_header_;
@@ -248,7 +292,7 @@ private
    dry_run_;
 end;

-function ExportReport(path: string; data: Any; options: ExportOptions): void;
+function ExportReport(path: string; rows: array; options: ExportOptions): void;
 ```

 - 尽量避免超过 5 个参数；必要时封装为对象（`class`/`unit`）。
@@ -267,22 +311,22 @@ function ExportReport(path: string; data: Any; options: ExportOptions): void;
 - 错误信息与日志（允许在库里打日志，但要克制）：
  - 错误/日志至少包含：**做什么失败** +
    **关键上下文（脱敏）**，便于定位；避免只有“failed”。
-  - 禁止把 Token/密码/个人数据等敏感信息写入日志、注释或错误信息（参考
-    `.agents/tsl/auth.md`）。
+  - 禁止把 Token、密码、个人数据等敏感信息写入日志、注释或错误信息；如需记录标识，优先记录脱敏后的业务 ID 或可复现的上下文键。
  - 避免重复记录：同一个错误链路尽量只在**边界层**记录一次（库里记录后，上层通常不再重复打一遍同等级日志）。
 - 示例：`try/except/end` + 降级（best-effort）：
-  - 注：示例中的 `Any`/`nil`/`LogWarn`/`ReadCacheFromFile`
-    为占位，按项目实际类型与函数替换。
+  - `LoadCacheValue` / `RecordCacheWarning` 代表项目自有函数，重点在结构而不是函数名本身。
+
+代码块身份：配置片段 / 概念骨架

 ```tsl
 // 读取可选缓存：失败允许降级为 cache miss（必须可观测，并说明原因）。
-function ReadOptionalCache(path: string): Any;
+function ReadOptionalCache(path: string);
 begin
    try
-        return ReadCacheFromFile(path)
+        return LoadCacheValue(path)
    except
        // best-effort: cache 仅用于提速，失败不应影响主流程
-        LogWarn("ReadOptionalCache failed; fallback to miss. path=" + path)
+        RecordCacheWarning(path)
        return nil
    end
 end;
@@ -290,22 +334,22 @@ end;

 ### 4.4 性能与可测试性

- 避免过早优化：先写清晰正确的代码，再用数据（profile/trace/log/基准）定位瓶颈并做最小化改动（参考
-  `.agents/tsl/performance.md`）。
- 复杂逻辑要可测试：把“纯计算/解析/规则”与“I/O/环境依赖（文件/网络/DB/全局状态）”分离；I/O 层做薄封装，核心逻辑保持可单测（参考
-  `.agents/tsl/testing.md`）。
+- 避免过早优化：先写清晰正确的代码，再用项目实际可用的 profile、trace、日志或基准数据定位瓶颈，并做最小化改动。
+- 复杂逻辑要可测试：把“纯计算/解析/规则”与“I/O/环境依赖（文件/网络/DB/全局状态）”分离；I/O 层做薄封装，核心逻辑保持可单测。
 - 避免在热路径里做隐式昂贵操作：循环内重复 I/O、重复解析/格式化、无界缓存、隐式复制等；缓存如必须引入，明确生命周期与上限（大小/TTL/清理点）。
 - 示例：薄 I/O + 厚纯逻辑（便于测试与复用）：
-  - 注：示例中的 `Any`/`ReadAllText` 为占位，按项目实际类型与函数替换。
+  - `LoadConfigText` 代表项目自己的 I/O 边界函数；`ParseConfig` 只负责解析与校验。
+
+代码块身份：配置片段 / 概念骨架

 ```tsl
 // pure: 只做解析/校验，不做 I/O，便于单元测试
-function ParseConfig(text: string): Any;
+function ParseConfig(text: string): array;

 // I/O: 只负责读文件与兜底处理，把逻辑交给 ParseConfig
-function LoadConfig(path: string): Any;
+function LoadConfig(path: string): array;
 begin
-    text = ReadAllText(path)
+    text := LoadConfigText(path);
    return ParseConfig(text)
 end;
 ```