📝 docs(tsl): align agent-facing guidance

docs/tsl/syntax/02_quickstart.md

@@ -8,19 +8,31 @@
 
 手册位置：第 2 篇，共 32 篇。上一篇：[01_introduction.md](01_introduction.md)。下一篇：[03_core_model.md](03_core_model.md)。
 
-这一篇集中回答两个紧邻问题：现在要写 TSL 时，应该从哪一种最短骨架起手；以及落代码前必须先核对哪些语言硬规则。
+这一篇集中回答两个紧邻问题：用户已给出 `.tsl` / `.tsf` 后缀时，agent 应该如何按后缀组织代码；以及落代码前必须先核对哪些语言硬规则。
 
 ## 这一篇解决什么问题
 
-快速回答“当前任务应该从松散语句、函数、类还是 unit 开始”，并提供一份单点的语言核心事实速查。
+快速回答“当前任务已经给出后缀或交付目标时，应该使用哪一种骨架”，并提供一份单点的语言核心事实速查。
+
+## Agent 快速落代码流程
+
+1. 先看用户有没有指定 `.tsl` / `.tsf` 后缀；指定后缀时，后缀就是文件形态判断依据。
+2. 用户未指定后缀时，再根据交付目标判断 `.tsl` 或 `.tsf`：可执行脚本用 `.tsl`，通用模块 / 函数扩展用 `.tsf`。
+3. 只从 `代码块身份：已验证可执行示例` 的骨架起手；遇到 `反例 / 不可照写` 必须避开。
+4. 写 `.tsl` 时，先写会执行的语句区；需要函数或类时，把声明区放在语句区之后。
+5. 写 `.tsf` 时，只写模块 / 函数扩展内容；部署、查找路径和解释器环境属于项目执行层。
+6. 当前页和对应专题页没有覆盖的写法，不要发明语法；改为跳转补证、向用户确认，或记录文档缺口。
 
 ## 语言核心事实速查
 
-这一节是当前语法手册默认的语言硬规则收口点。涉及赋值、顶层外形、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。
+这一节是当前语法手册默认的语言硬规则收口点。涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。
 
 - 普通赋值用 `:=`，不要把 `=` 当成普通赋值。
-- 顶层主体先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
-- 如果当前文件采用顶层 `function / procedure` 模型，就不要再混入松散语句。
+- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；用户未给后缀时，再按交付目标判断。
+- 未给后缀时，可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。
+- `.tsl` 是可执行脚本：语句区在前并按顺序执行；函数/类声明区在后，供前面的语句调用或运行时解析。
+- `.tsf` 是模块/函数扩展文件：部署到解释器 `funcext` 后，脚本可以直接调用其中暴露的顶层函数。
+- 在 `.tsl` 中，如果需要函数或类，先写会执行的语句区，再写函数/类声明区；不要在声明区后面继续追加脚本语句。
 - 无返回值时用 `procedure Name(...); begin ... end;`，不要勉强用 `function`。
 - 顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`。
 - 多文件组织默认先按 `unit Name; interface ... implementation ... end.` 理解。
@@ -29,26 +41,30 @@
 
 ## 术语对照
 
-- 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，指的是同一类顶层模型：文件以顶层 `function` / `procedure` 为主体。
+- 文档里出现的“脚本语句区”，指 `.tsl` 文件开头会按顺序执行的语句。
+- 文档里出现的“声明区”，指 `.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。
+- 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，在 `.tsf` 中指模块暴露的顶层函数，在 `.tsl` 中指脚本声明区里的函数。
 - 文档里出现的 `class function` 和“类方法”，指的是同一件事：前者是代码关键字写法，后者是中文描述。
 
 ## 先选哪一种骨架
 
-| 当前任务                       | 起手骨架            |
-| ------------------------------ | ------------------- |
-| 只写一段一次性脚本逻辑         | 顶层松散语句        |
-| 先沉淀一个可复用逻辑块         | 顶层 `function`     |
-| 需要对象状态、字段、方法       | `type Name = class` |
-| 需要把接口和实现组织进一个模块 | `unit`              |
+| 当前任务                         | 起手骨架                          |
+| -------------------------------- | --------------------------------- |
+| 写一次性可执行逻辑               | `.tsl` 脚本语句区                 |
+| 脚本逻辑需要调用本文件内函数     | `.tsl` 语句区 + 后置函数声明区    |
+| 脚本逻辑需要对象状态、字段、方法 | `.tsl` 语句区 + 后置类声明区      |
+| 沉淀可复用函数并给脚本直接调用   | `.tsf` 顶层函数，部署到 `funcext` |
+| 需要把接口和实现组织进一个模块   | `.tsf` `unit`                     |
 
 默认建议：
 
-- 如果你只是要让新 session 先写出一段最稳、最容易续写的基础语法，优先从顶层 `function` 开始。
+- 如果你只是要让 agent 先写出一段最稳、最容易续写的可执行代码，优先从 `.tsl` 脚本语句区开始。
+- 不要把 `unit` 当成最小起手骨架；只有用户明确要模块接口 / 实现组织，或项目已有 `unit` 边界时，才进入 `unit` 写法。
 - `uses` 往往天然进入多文件查找路径问题，所以不放进这篇的最小起手骨架里。
 
 ## 已验证最小骨架
 
-顶层松散语句骨架：
+`.tsl` 脚本语句区骨架：
 
 代码块身份：已验证可执行示例
 
@@ -56,27 +72,66 @@
 a := 1;
 ```
 
-顶层函数骨架：
+`.tsl` 语句区调用后置函数声明：
 
 代码块身份：已验证可执行示例
 
 ```tsl
-function Demo();
+a := 1;
+test();
+
+function test();
 begin
-    return 1;
+    echo "test";
 end;
 ```
 
-顶层类骨架：
+代码块身份：已验证输出片段
+
+```text
+test
+```
+
+`.tsl` 语句区调用后置类声明：
 
 代码块身份：已验证可执行示例
 
 ```tsl
-type DemoType = class
+obj := CreateObject("MyClass");
+obj.value := 5;
+echo obj.value;
+
+type MyClass = class
+    value;
 end;
 ```
 
-顶层 `unit` 骨架：
+代码块身份：已验证输出片段
+
+```text
+5
+```
+
+`.tsf` 顶层函数骨架：
+
+代码块身份：已验证可执行示例
+
+```tsl
+function Test1();
+begin
+    echo "test1";
+end;
+```
+
+代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。部署方式属于项目执行层，不写进通用语法页。
+
+代码块身份：已验证输出片段
+
+```text
+test1
+```
+
+`.tsf` `unit` 骨架：
 
 代码块身份：已验证可执行示例
 
@@ -93,35 +148,50 @@ implementation
 end.
 ```
 
+代码块说明：这个 `.tsf` 骨架用于模块接口 / 实现组织；已通过 `.tsl` 脚本 `uses DemoUnit` 调用 `Ping()` 验证返回值为 `1`。调用脚本和查找路径边界见 [10_units_and_scope.md](10_units_and_scope.md)。
+
 ## 最常用起手版本
 
-如果你现在没有明确的多文件或对象建模需求，直接从函数版本开始：
+如果你现在没有明确的模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始：
 
 代码块身份：已验证可执行示例
 
 ```tsl
-function Hello();
-begin
-    return 1;
-end;
+echo "hello";
+```
+
+代码块身份：已验证输出片段
+
+```text
+hello
 ```
 
 ## 最容易写错的一件事
 
-- 不要把“顶层函数定义”和“顶层松散语句”混写在同一个最小文件里。
+- `.tsl` 可以同时有语句区和声明区；真正要避免的是在声明区后面继续追加脚本语句。
 
 代码块身份：反例 / 不可照写
 
 ```text
-function Add(a, b);
+a := 1;
+test();
+
+function test();
 begin
-    return a + b;
+    echo "test";
 end;
 
-value := Add(1, 2);
+echo "after declaration";
 ```
 
-上面这种“先定义顶层函数，再接松散语句”的混合写法会编译失败。
+上面最后一行属于“声明区之后继续写脚本语句”。写 `.tsl` 时先把会执行的语句放在前面，再把函数/类声明放在后面。
+
+代码块身份：已验证输出片段
+
+```text
+Execute script error at Line:9
+function:__main__:line 9: invalid statement
+```
 
 ## 跳转指引