# 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)