# TSL 快速落代码规则

文档类型：语法主线
是否可直接用于生成代码：是
是否含可直接照写示例：是
是否含不可照写反例：是
遇到不确定时：先按本文“下一步路由”继续判断；文件模型看 [02_core_model.md](02_core_model.md)，函数 / 调用看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)

本篇只回答两个落代码前问题：用户已给出 `.tsl` / `.tsf` 后缀时，智能体如何按后缀组织代码；以及生成代码前必须先核对哪些语言硬规则。

## 本篇职责

快速回答“任务已经给出后缀或交付目标时，应该选择哪一种可直接照写骨架”，并提供一份单点的语言核心事实速查。

## 智能体快速落代码流程

1. 先看用户有没有指定 `.tsl` / `.tsf` 后缀；指定后缀时，后缀就是文件形态判断依据。
2. 用户未指定后缀时，再根据交付目标判断 `.tsl` 或 `.tsf`：入口流程、脚本任务或一次性执行逻辑用 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）用 `.tsf`；如果只是脚本内部封装函数或类，仍按 `.tsl` 处理。
3. 只从 `代码块身份：可直接照写示例` 的骨架起手；遇到 `反例 / 不可照写` 必须避开。
4. 写 `.tsl` 时，先写会执行的语句区；需要函数或类时，把声明区放在语句区之后。
5. 写 `.tsf` 时，只写可复用顶层声明，不写入口脚本流程；部署、查找路径和解释器环境属于项目执行层。
6. 本页和对应专题页没有覆盖的写法，不要发明语法；按“下一步路由”切到对应专题页判断；仍无文档事实时向用户确认或记录文档缺口。

## 语言核心事实速查

这一节是本语法手册默认的语言硬规则收口点。涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。

- 赋值：普通赋值用 `:=`，不要把 `=` 当成普通赋值。
- 后缀：用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；用户未给后缀时，再按交付目标判断。
- 无后缀：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`；只是脚本内部封装函数或类时，仍按 `.tsl` 处理；仍不明确时向用户确认。
- `.tsl`：可执行脚本，语句区在前并按顺序执行；函数 / 类声明区在后，供前面的语句调用或运行时解析。
- `.tsf`：可复用模块 / 函数扩展文件；非 `unit` 顶层函数 / 过程部署到解释器 `funcext` 后，脚本可以直接调用；顶层类声明只按可复用声明理解；`unit` 按模块组织理解。
- `.tsl` 声明区：如果需要函数或类，先写会执行的语句区，再写函数 / 类声明区；不要在声明区后面继续追加脚本语句。
- `function` / `procedure`：用户只说“写一个函数”时默认用 `function`；只有用户明确要求 `procedure` / 过程时才用 `procedure Name(...); begin ... end;`；`procedure` 头后不允许写返回类型。
- 类：顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`；创建对象有两种方式，`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。
- `unit`：涉及多文件组织时，先按 `unit Name; interface ... implementation ... end.` 骨架理解；不要把 `unit` 当默认最小起手。
- 命名参数：写法是 `Func(a:1, b:2)`，不要写成 `Func(a = 1, b = 2)`。
- 下标：`array(...)` 既可以写顺序数组，也可以写字符串键表；数组下标从 `0` 开始，字符串下标从 `1` 开始。

## 术语对照

- “脚本语句区”：`.tsl` 文件开头会按顺序执行的语句。
- “声明区”：`.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。
- “顶层 `function / procedure`”：在 `.tsf` 中指模块暴露的顶层函数 / 过程，在 `.tsl` 中指脚本声明区里的函数 / 过程。
- “顶层函数骨架”“顶层函数定义体”：只指 `function` 骨架；不要因为任务没有返回值就自动改成 `procedure`。
- `class function` / “类方法”：同一件事；前者是代码关键字写法，后者是中文描述。

## 起手骨架选择规则

| 任务                                 | 起手骨架                       |
| ------------------------------------ | ------------------------------ |
| 写入口流程、脚本任务或一次性执行逻辑 | `.tsl` 脚本语句区              |
| 脚本逻辑需要调用本文件内函数         | `.tsl` 语句区 + 后置函数声明区 |
| 脚本逻辑需要对象状态、字段、方法     | `.tsl` 语句区 + 后置类声明区   |
| 沉淀可复用函数、过程或类             | `.tsf` 可复用顶层声明          |
| 需要把接口和实现组织进一个模块       | `.tsf` `unit`                  |

默认建议：

- 用户只要求写一段代码、脚本或示例，且没有明确复用、模块或 `.tsf` 交付需求时，优先从 `.tsl` 脚本语句区开始。
- 不要因为代码里需要函数或类就自动升级成 `.tsf`；`.tsl` 也可以在语句区后放声明区。
- 不要把 `unit` 当成最小起手骨架；只有用户明确要模块接口 / 实现组织，或项目已有 `unit` 边界时，才进入 `unit` 写法。
- `uses` 往往天然进入多文件查找路径问题，所以不放进这篇的最小起手骨架里。

## 最小骨架

使用这些骨架时遵守：

- 可以模仿已经出现的代码外形、语句顺序和块级结构。
- 不要从骨架推断未出现的语法、内置函数、部署方式、文件名规则或模块查找规则。
- 需要扩展写法时，先进入对应专题页读取规则。

本页只列最短高频骨架；`procedure`、参数、返回类型和调用细节见 [05_functions_and_calls.md](05_functions_and_calls.md)。

### `.tsl` 脚本骨架

`.tsl` 脚本语句区骨架：

代码块身份：可直接照写示例

```tsl
a := 1;
```

代码块说明：这是 `.tsl` 语句区最小形态，只证明脚本语句可以从文件开头顺序执行。

`.tsl` 语句区调用后置函数声明：

代码块身份：可直接照写示例

```tsl
a := 1;
test();

function test();
begin
    echo "test";
end;
```

代码块身份：输出片段

```text
test
```

代码块说明：这个骨架证明 `.tsl` 语句区可以调用后置函数声明；不要在函数声明区之后继续追加脚本语句。

`.tsl` 语句区调用后置类声明：

代码块身份：可直接照写示例

```tsl
obj := new MyClass();
obj.value := 5;
echo obj.value;

type MyClass = class
    value;
end;
```

代码块身份：输出片段

```text
5
```

代码块说明：这个骨架证明 `.tsl` 语句区可以通过 `new MyClass()` 使用后置类声明；普通对象创建默认优先 `new ClassName()`。`createObject(...)` 也是对象创建方式，但作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`，细节见 [08_objects_and_classes.md](08_objects_and_classes.md)。

### `.tsf` 可复用骨架

`.tsf` 顶层函数骨架：

代码块身份：可直接照写示例

```tsl
function Test1();
begin
    echo "test1";
end;
```

代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。部署方式属于项目执行层，不写进通用语法页。

代码块身份：输出片段

```text
test1
```

`.tsf` `unit` 骨架：

代码块身份：可直接照写示例

```tsl
unit DemoUnit;

interface

function Ping();

implementation

function Ping();
begin
    return 1;
end;

end.
```

代码块说明：这个 `.tsf` 骨架用于模块接口 / 实现组织；`.tsl` 脚本 `uses DemoUnit` 后可调用 `Ping()`，返回值为 `1`。调用脚本和查找路径边界见 [09_units_and_scope.md](09_units_and_scope.md)。

## 默认起手骨架

如果用户只要求写一段代码、脚本或示例，且没有明确 `.tsf`、`unit`、模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始：

代码块身份：可直接照写示例

```tsl
echo "hello";
```

代码块身份：输出片段

```text
hello
```

代码块说明：这是默认可执行脚本骨架；没有复用或模块需求时，不要主动改成 `.tsf`。

## 最高频禁止项

- `.tsl` 可以同时有语句区和声明区；真正要避免的是在声明区后面继续追加脚本语句。

代码块身份：反例 / 不可照写

```text
a := 1;
test();

function test();
begin
    echo "test";
end;

echo "after declaration";
```

代码块说明：这是不可照写的错误形态；最后一行属于“声明区之后继续写脚本语句”。正确做法是把所有会执行的脚本语句放在声明区之前。

代码块身份：输出片段

```text
Execute script error at Line:9
function:__main__:line 9: invalid statement
```