95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# Introduction
|
||
|
||
文档类型：语法主线
|
||
是否可直接用于生成代码：仅部分
|
||
是否含已验证可执行示例：是
|
||
是否含已验证反例：否
|
||
遇到不确定时跳转到：[02_quickstart.md](02_quickstart.md)、[03_core_model.md](03_core_model.md)、[12_pitfalls.md](12_pitfalls.md)
|
||
|
||
手册位置：第 1 篇，共 32 篇。上一篇：手册入口 [index.md](index.md)。下一篇：[02_quickstart.md](02_quickstart.md)。
|
||
|
||
这一篇只做一件事：给 agent 建立 TSL 的第一判断模型。它不是人类教程，不负责展开所有语法细节；它只告诉 agent 第一次看到 TSL 任务时先判断什么、按什么证据生成代码、哪些直觉不能继承。
|
||
|
||
## 这一篇解决什么问题
|
||
|
||
回答“agent 第一次读到 TSL 需求时，怎样先识别交付形态，再选择最小可靠代码结构”。
|
||
|
||
涉及赋值、命名参数、类外形、`unit` 骨架、数组 / 字符串下标这类高频硬规则时，统一以 [02_quickstart.md](02_quickstart.md) 的“语言核心事实速查”为准；这一页只负责建立第一判断模型。
|
||
|
||
## Agent 第一判断流程
|
||
|
||
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` 是通用模块 / 函数扩展。
|
||
- 日常赋值先记 `:=`，不要把 `=` 当成普通赋值。
|
||
|
||
## 已验证的第一印象
|
||
|
||
`.tsl` 可执行脚本第一印象：
|
||
|
||
代码块身份：已验证可执行示例
|
||
|
||
```tsl
|
||
a := 1;
|
||
test();
|
||
|
||
function test();
|
||
begin
|
||
echo "test";
|
||
end;
|
||
```
|
||
|
||
代码块说明：`.tsl` 的语句区在前，按顺序执行；函数声明区在后，供前面的脚本语句调用。
|
||
|
||
`.tsf` 通用模块第一印象：
|
||
|
||
代码块身份：已验证可执行示例
|
||
|
||
```tsl
|
||
function Test1();
|
||
begin
|
||
echo "test1";
|
||
end;
|
||
```
|
||
|
||
代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。文件部署方式属于项目执行层，不写进通用语法页。
|
||
|
||
赋值、数组、字符串下标的第一印象：
|
||
|
||
代码块身份：已验证可执行示例
|
||
|
||
```tsl
|
||
items := array(10, 20, 30);
|
||
table_data := array("Code": "000001", "Name": "Demo");
|
||
echo items[0];
|
||
echo table_data["Code"];
|
||
echo "ABC"[1];
|
||
```
|
||
|
||
代码块说明：数组下标从 `0` 开始，字符串下标从 `1` 开始；更完整规则见 [04_values_and_literals.md](04_values_and_literals.md)。
|
||
|
||
## 第一次写时最容易混淆的边界
|
||
|
||
- 不要把 `.tsl` / `.tsf` 当成 agent 自行选择的纯语法分支；后缀和用户交付目标优先。
|
||
- 不要把 Pascal 外形直接泛化成 Pascal 文件模型。
|
||
- 不要在 `.tsl` 的函数/类声明区之后继续追加脚本语句。
|
||
- 不要把未验证写法写成语法事实；agent 生成代码时只模仿带证据标签的代码块。
|
||
|
||
## 下一步怎么读
|
||
|
||
- 需要立刻开始写代码：看 [02_quickstart.md](02_quickstart.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)
|