playbook/docs/tsl/syntax/11_pitfalls.md

TSL 高频误写

文档类型：反例索引页 是否可直接用于生成代码：否 是否含可直接照写示例：否 是否含不可照写反例：是 遇到不确定时：先按本页候选页继续判断；02_core_model.md、03_values_and_literals.md、05_functions_and_calls.md、06_expressions_and_operators.md、08_objects_and_classes.md、09_units_and_scope.md；仍不命中时回到语法路由中心 index.md；如果问题已经超出语法层，回到 TSL 总入口 ../index.md

这一篇不讲新知识，只做反例索引。

本篇职责

回答“哪些写法最容易凭直觉写出来，但在 TSL 里会编译失败、运行出错，或语义并不可靠”。

智能体常见误写判断流程

1. 先识别用户写法属于值、变量、函数、表达式、对象、unit、TS-SQL 还是外部调用误区。
2. 遇到本页反例时，不要修成相邻语言习惯，必须跳回对应语法页找可直接照写示例。
3. 反例只用于排错和避免误写，不作为可照写模板。
4. 修复时保留 .tsl / .tsf 文件模型判断，不要只改局部语句。
5. 没有对应条目时不要发明替代语法。

这页怎么用

• 先按主题扫一遍，再回到对应正文看正确写法。
• 这里不重复讲完整规则，只保留“错法 -> 正确页”的索引。
• 只有已经有明确反例边界的误写，才会列在这里。
• 细节型边界放回对应专题页；本页只保留最容易诱导智能体写错的高频误写。

反例索引

文件模型与基础值

1. 把裸 class Name 当成顶层类声明

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

class Person
end;

这会编译失败。正确页：见 08_objects_and_classes.md

2. 把 = 当成赋值

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

a = 1;

代码块身份：输出片段

invalid statement

这会编译失败。正确页：见 06_expressions_and_operators.md

3. 把字符串当成 0 基下标

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

s := "ABC";
writeLn(s[0]);

这会在运行时报字符串下标越界。正确页：见 03_values_and_literals.md

4. 在 .tsl 声明区后面继续写脚本语句

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

a := 1;
test();

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

echo "after declaration";

.tsl 可以有语句区和声明区，但顺序必须清楚：语句区在前并按顺序执行，函数 / 类声明区在后。不要在声明区后面继续写脚本语句。正确页：见 02_core_model.md

函数与调用

5. 把 a = 1 当成命名参数

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

Pack(a = 1, b = 2);

不要把这当成可靠的命名参数写法。它虽然可能编译通过，但返回结果不符合命名参数预期。正确页：见 05_functions_and_calls.md

6. 把 like 当成 SQL % / _ 通配

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

writeLn("abc" like "a%");

这里输出 0，不要按 SQL LIKE 去理解。本手册中，like 的右侧按正则模式解释。正确页：见 06_expressions_and_operators.md

unit / uses

7. 把函数体或类定义体里的 uses 写错位置，或重复写第二个 uses

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

function Run();
begin
    a := 1;
    uses DemoUnit;
    return Ping();
end;

type Worker = class
    uses UnitA;
    uses UnitB;
end;

上面这两类写法都会失败。函数里的错法会报 invalid statement，类里的错法会报 invalid class definition。失败点分别是：函数体里的 uses 不是第一条语句；类定义体里出现了第二条 uses。

注意：这个反例只针对函数体和类定义体里的 uses；需要多个 unit 时，默认回到顶层写成单条 uses UnitA, UnitB;。正确页：见 09_units_and_scope.md

类与对象

8. 把裸类名当成 class function 或静态字段的直接访问入口

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

MathBox.Add(1, 2);

THuman.mCount := 7;

这两种写法都不作为可写事实。可用写法是先拿到类类型，再用 class(MathBox).Add(...) / findClass("MathBox").Add(...) 调类方法，以及 class(THuman).mCount 访问静态字段。正确页：见 08_objects_and_classes.md

9. 把 private / protected create 当成一定会执行的构造函数

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

a := new A(111);
writeLn(a.value);

type A = class
public
    value;
private
    function create(v);
    begin
        value := v;
    end;
end;

这不会报“不能创建对象”，但 create 不会执行；上面的 a.value 输出 <NIL>。正确页：见 08_objects_and_classes.md

10. 在子类里把父类 private 成员当成 protected 成员用

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

b := new B();
writeLn(b.TryCall());

type A = class
private
    function Hidden();
    begin
        return 77;
    end;
end;
type B = class(A)
public
    function TryCall();
    begin
        return Hidden();
    end;
end;

这会在执行时报父类 private 方法不可访问。正确页：见 08_objects_and_classes.md

禁止项收口

• 不要把本页任何 反例 / 不可照写 代码块改写成默认正向模板。
• 不要只凭 Pascal、JavaScript、Python 或 SQL 直觉修正 TSL 写法。
• 不要在本页发明替代语法；每个反例都要回到条目末尾标出的正确专题页。
• 不要把反例边界写成可用语法。