📝 docs(tsl): align agent-facing guidance

2026-05-28 19:12:34 +08:00
parent c48354e0cb
commit d8eb418277
63 changed files with 1921 additions and 371 deletions
@@ -8,47 +8,61 @@

 手册位置：第 1 篇，共 32 篇。上一篇：手册入口 [index.md](index.md)。下一篇：[02_quickstart.md](02_quickstart.md)。

-这一篇只做一件事：让新 session 在看到 TSL 时，先用正确的读法建立心智模型。
+这一篇只做一件事：给 agent 建立 TSL 的第一判断模型。它不是人类教程，不负责展开所有语法细节；它只告诉 agent 第一次看到 TSL 任务时先判断什么、按什么证据生成代码、哪些直觉不能继承。

 ## 这一篇解决什么问题

-回答“第一次读 TSL 时，应该先把它当成什么来理解，以及最容易和别的语言混淆的差异是什么”。
+回答“agent 第一次读到 TSL 需求时，怎样先识别交付形态，再选择最小可靠代码结构”。

-涉及赋值、命名参数、类外形、`unit` 骨架、数组 / 字符串下标这类高频硬规则时，统一以 [02_quickstart.md](02_quickstart.md) 的“语言核心事实速查”为准；这一页只负责建立第一印象。
+涉及赋值、命名参数、类外形、`unit` 骨架、数组 / 字符串下标这类高频硬规则时，统一以 [02_quickstart.md](02_quickstart.md) 的“语言核心事实速查”为准；这一页只负责建立第一判断模型。

-## 先用什么方式读 TSL
+## Agent 第一判断流程

- 可以先按 Pascal 风格语言去读它：常见外形是 `function ... begin ... end;`、`unit ... interface ... implementation ... end.`、`type Name = class ... end;`；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
- 先看顶层主体，再看细节；不要先被文件扩展名带偏。
- 当前手册把顶层主体优先收敛成四类：松散语句、顶层 `function / procedure`、顶层 `type Name = class`、顶层 `unit`。
- 顶层 `uses` 可以出现，但这里只把它当成辅助组织语句，不把它当成主体声明。
+1. 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。
+2. 用户未给后缀时，先看交付目标：可执行代码对应 `.tsl`，通用模块对应 `.tsf`。
+3. 交付目标仍不明确时，向用户确认；不要替用户发明文件形态。
+4. 写 `.tsl` 时，先生成会顺序执行的语句区；如果需要函数或类，把声明区放在语句区之后。
+5. 写 `.tsf` 时，只生成模块 / 函数扩展代码；部署后的顶层函数可被 `.tsl` 脚本直接调用。
+6. 没有文档证据时不要发明语法；只能回到对应专题页、反例页、项目规则，或记录文档缺口。
+
+## 先用什么方式理解 TSL
+
+- TSL 可以借 Pascal 风格外形理解：`function ... begin ... end;`、`unit ... interface ... implementation ... end.`、`type Name = class ... end;` 都很接近。
+- 这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
+- `.tsl` / `.tsf` 首先是用户交付形态：`.tsl` 是可执行脚本，`.tsf` 是通用模块 / 函数扩展。
 - 日常赋值先记 `:=`，不要把 `=` 当成普通赋值。

-## 第一次写时最容易混淆的差异
-
- `array(...)` 既可以当顺序数组，也可以当字符串键表。
- 数组下标从 `0` 开始，字符串下标从 `1` 开始。
- 顶层类定义按 `type Name = class ... end;` 去写，不使用裸 `class Name`。
- 调用函数时，命名参数写成 `name: value`，例如 `Demo(a: 1, b: 2)`。
-
 ## 已验证的第一印象

-最常见的 `function / procedure` 外形：
+`.tsl` 可执行脚本第一印象：

 代码块身份：已验证可执行示例

 ```tsl
-function Demo();
-begin
-    return 1;
-end;
+a := 1;
+test();

-procedure LogDemo(msg);
+function test();
 begin
-    WriteLn(msg);
+    echo "test";
 end;
 ```

+代码块说明：`.tsl` 的语句区在前，按顺序执行；函数声明区在后，供前面的脚本语句调用。
+
+`.tsf` 通用模块第一印象：
+
+代码块身份：已验证可执行示例
+
+```tsl
+function Test1();
+begin
+    echo "test1";
+end;
+```
+
+代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。文件部署方式属于项目执行层，不写进通用语法页。
+
 赋值、数组、字符串下标的第一印象：

 代码块身份：已验证可执行示例
@@ -56,43 +70,25 @@ end;
 ```tsl
 items := array(10, 20, 30);
 table_data := array("Code": "000001", "Name": "Demo");
-first_item := items[0];
-first_char := "ABC"[1];
+echo items[0];
+echo table_data["Code"];
+echo "ABC"[1];
 ```

-类的第一印象：
+代码块说明：数组下标从 `0` 开始，字符串下标从 `1` 开始；更完整规则见 [04_values_and_literals.md](04_values_and_literals.md)。

-代码块身份：已验证可执行示例
+## 第一次写时最容易混淆的边界

-```tsl
-type DemoType = class
-end;
-```
-
-`unit` 的第一印象：
-
-代码块身份：已验证可执行示例
-
-```tsl
-unit DemoUnit;
-interface
-
-function Demo();
-
-implementation
-
-function Demo();
-begin
-    return 1;
-end;
-
-end.
-```
+- 不要把 `.tsl` / `.tsf` 当成 agent 自行选择的纯语法分支；后缀和用户交付目标优先。
+- 不要把 Pascal 外形直接泛化成 Pascal 文件模型。
+- 不要在 `.tsl` 的函数/类声明区之后继续追加脚本语句。
+- 不要把未验证写法写成语法事实；agent 生成代码时只模仿带证据标签的代码块。

 ## 下一步怎么读

 - 需要立刻开始写代码：看 [02_quickstart.md](02_quickstart.md)
- 需要判断当前文件属于哪一种顶层模型：看 [03_core_model.md](03_core_model.md)
+- 需要判断当前文件组织方式：看 [03_core_model.md](03_core_model.md)
 - 需要先写值、数组、字符串：看 [04_values_and_literals.md](04_values_and_literals.md)
 - 需要先写变量、常量：看 [05_variables_and_constants.md](05_variables_and_constants.md)
 - 需要先写函数和调用：看 [06_functions_and_calls.md](06_functions_and_calls.md)
+- 需要先避开高频误写：看 [12_pitfalls.md](12_pitfalls.md)