📝 docs(tsl): rebuild canonical syntax and routing manual

docs/tsl/naming.md

@@ -1,8 +1,16 @@
 # TSL 命名规范（Naming）
 
+文档类型：规范页
+是否可直接用于生成代码：仅部分
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：[code_style.md](code_style.md)、[syntax/index.md](syntax/index.md)、[syntax/03_core_model.md](syntax/03_core_model.md)
+
 本仓库命名规则与 Google C++ Style
 Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。
 
+以下出现的 `<...>` 形式只表示命名或注释模板占位，不是源码字面量。
+
 ## 1. 选名原则
 
 - **可读一致**：名字清晰可读，并随可见范围调整具体程度。
@@ -42,42 +50,47 @@ Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函
 
 ## 3. 类型命名（Type Names）
 
-TSL 的顶层声明只有三种：`class`、`unit`、`function`（仅适用于 `.tsf`）。因此
-`.tsf` 文件基名必须与顶层声明同名（见“4. 文件命名与顶层声明”）。
+AI 先按四类顶层外形判断文件模型：顶层松散语句、顶层 `function / procedure`、
+顶层 `type Name = class`、顶层 `unit`。本页只覆盖“需要命名的顶层实体”，不覆盖松散语句本身；文件模型判断本身以
+`docs/tsl/syntax/03_core_model.md` 为准。
 
-- **类（class）与单元（unit）**使用
+- **类与单元**使用
   `PascalCase`，不带下划线；名称应为名词/名词短语（通常单数），避免动词开头。
+- 顶层类的正式写法统一按 `type Name = class ... end;` 理解；不要把裸 `class`
+  当成正式顶层类模型的简称。
 - 不推荐 `*Unit` 作为 `unit` 的后缀（`unit`
   本身已表达语义）；需要表达用途时，可使用 `*Shared`/`*Common`/`*Enums`
   等更具体后缀（按团队约定）。
-- **顶层函数（function）**使用 `PascalCase`；名称优先动词/动词短语（例如
+- **顶层函数 / 过程**使用 `PascalCase`；名称优先动词/动词短语（例如
   `Load`/`Parse`/`Build`），详见函数命名章节。
-- 示例：`UserAccount`、`OrderShared`、`LoadMarketData()`。
+- 示例：`UserAccount`、`OrderShared`、`LoadMarketData()`、`FlushCache()`。
 
 ## 4. 文件命名与顶层声明（File Names）
 
 TSL 的语法要求（仅 `.tsf`）：每个 `.tsf`
 文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。
 
-- 顶层声明可能是 `class`、`unit` 或 `function`（见类型命名）。
-- `.tsf` 代码文件：用于库/模块等“顶层声明”的承载文件；顶层声明可为
-  `class`/`unit`/`function`，文件基名需与之同名。
+- 更可靠的判断方式仍然是先看顶层内容，而不是只看扩展名；命名规范只是补充“命名后的实体如何取名”，不替代文件模型判断。
+- 需要命名的顶层实体可以是 `function / procedure`、`type Name = class`、`unit`。
+- `.tsf` 代码文件：用于库/模块等“顶层声明”的首选承载文件；顶层声明可为
+  `function / procedure`、`type Name = class`、`unit`，文件基名需与之同名。
 - `.tsl` 脚本文件：用于入口/编排层；允许直接写语句（如
-  `a := 1; echo a;`），不要求顶层声明，也不强制文件基名与函数名一致；可复用逻辑应下沉到
+  `a := 1; echo a;`），也可能出现顶层 `function / procedure` 骨架或 `program test;`
+  这类验证样例外壳；但风格上不把 `.tsl` 当成可复用顶层声明的默认落点，也不要求文件基名与函数名一致；可复用逻辑优先下沉到
   `.tsf`（见 `docs/tsl/code_style.md`）。
   - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。
 - **硬规则（仅
-  `.tsf`）**：重命名顶层声明时必须同步重命名文件基名，否则语法/加载规则无法识别；批量重命名可参考
-  `$bulk-refactor-workflow`。
+  `.tsf`）**：重命名顶层声明时必须同步重命名文件基名，否则语法/加载规则无法识别；批量重命名时也必须把这两处一起改掉。
 
 命名建议：
 
 - 基名统一使用 `PascalCase`，与顶层声明的推荐写法一致。
 - 示例：
-  - `LoadMarketData.tsl` 中定义 `function LoadMarketData(...)`.
+  - `DailyEntry.tsl` 作为入口 / 编排脚本，主体是松散语句或验证样例外壳。
   - `UserAccount.tsf` 中定义 `type UserAccount = class ... end;`.
   - `DocxEnumerations.tsf` 中定义 `unit DocxEnumerations; ... end.`
   - `ParseConfig.tsf` 中定义 `function ParseConfig(...)`.
+  - `FlushCache.tsf` 中定义 `procedure FlushCache(...);`.
 
 注：TSL 大小写无关，实际编译时按大小写比较不会出错，但仍应保持文件名与声明名的推荐写法一致以便检索与协作。
 
@@ -108,11 +121,13 @@ TSL 的语法要求（仅 `.tsf`）：每个 `.tsf`
     `IsReady`），对应私有成员可用 `is_ready_` 等。
 - 示例：
 
+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 type User = class
 public
     property UserId read user_id_ write user_id_;
-    property IsReady read is_ready_;  // bool property example
+    property IsReady read is_ready_;
 private
     user_id_;
     is_ready_;
@@ -131,8 +146,11 @@ end;
   - 命名仍使用 `snake_case`（不使用 `g_` 前缀）。
   - 必须在声明处写注释说明：它是什么、用于什么、以及（如不明显）为什么需要是全局/静态。
   - 建议补充写入点与生命周期：谁会写、何时写、何时清理/重置；如涉及并发，写明并发假设/保护方式。
-  - 不要在注释/日志中写入任何敏感信息（参考 `.agents/tsl/auth.md`）。
+  - 不要在注释/日志中写入任何敏感信息；如需标识调用上下文，优先使用脱敏后的业务 ID、任务 ID 或路径键。
 - 示例（注释模板，按需裁剪）：
+  - 以下为注释模板占位，不是源码字面量。
+
+代码块身份：配置片段 / 概念骨架
 
 ```tsl
 // <var_name>: <what it is>
@@ -193,6 +211,8 @@ TSL 没有内置 `enum`，推荐使用 `unit` + `const` 在 `interface` 区域
 
 示例：
 
+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 unit AlertEnumerations;
 interface
@@ -202,6 +222,8 @@ interface
 end.
 ```
 
+代码块身份：配置片段 / 概念骨架
+
 ```tsl
 unit DocxEnumerations;
 interface