📝 docs(tsl): align agent-facing guidance

This commit is contained in:
csh
2026-05-28 19:12:34 +08:00
parent c48354e0cb
commit d8eb418277
63 changed files with 1921 additions and 371 deletions
+50 -7
View File
@@ -14,6 +14,15 @@
回答“普通变量怎样直接使用、`var` 在什么位置出现、常量有哪些基本写法、哪些名字一旦绑定就不能再赋值”。
## Agent 变量/常量判断流程
1. 普通变量默认直接用 `:=` 首次赋值,不要先补一个没有需求证据的 `var` 段。
2. 只有用户要求显式声明或遇到 `{$Explicit+}` 时才优先写 `var`
3. 顶层脚本常量优先用 `const name := value;`;需要后续脚本语句时,仍按 `.tsl` 语句区规则组织。
4. `const Name = value;` 优先放在函数 `const` 段、`unit` 接口或类成员里;不要和顶层 `const :=` 任意互换。
5. 多参数赋值按 `[a, b] := array(...)` 写;单变量拆包必须写成 `[name, ] := array(...)`
6. 没有已验证代码块时不要发明变量/常量写法;尤其不要从 Pascal 的声明习惯反推 TSL 必须先声明变量。
## 必须记住的规则
- 默认变量模型是“直接赋值即得到变量”,不要求先写 `var`
@@ -41,6 +50,15 @@
```tsl
a := 1;
b := array(1, 2, 3);
WriteLn(a);
WriteLn(b[1]);
```
代码块身份:已验证输出片段
```text
1
2
```
显式 `var` 写法:
@@ -66,6 +84,12 @@ begin
end.
```
代码块身份:已验证输出片段
```text
1
```
顶层最稳的常量写法:
代码块身份:已验证可执行示例
@@ -83,6 +107,12 @@ const value := 1 + 2 * 3;
WriteLn(value);
```
代码块身份:已验证输出片段
```text
7
```
函数内部 `const` 段:
代码块身份:已验证可执行示例
@@ -148,9 +178,12 @@ WriteLn(r1);
WriteLn(r2);
```
已验证运行结果:
代码块身份:已验证输出片段
- 依次输出 `1``3`
```text
1
3
```
单变量拆包时,末尾逗号不能省略:
@@ -161,9 +194,11 @@ WriteLn(r2);
WriteLn(re);
```
已验证运行结果:
代码块身份:已验证输出片段
- 输出 `1`
```text
1
```
左侧变量比右侧数组更长时,多出的变量为 `nil`
@@ -175,10 +210,12 @@ WriteLn(r1);
WriteLn(r2 = nil);
```
已验证运行结果:
代码块身份:已验证输出片段
- `r1` 输出 `1`
- `r2 = nil` 输出 `1`
```text
1
1
```
右侧元素也可以是数组:
@@ -293,6 +330,12 @@ end.
上面这类写法在当前解释器里会编译失败,主因是 `variable not defined`
代码块身份:已验证输出片段
```text
variable not defined
```
## 跳转指引
- 回看基本类型:见 [04_values_and_literals.md](04_values_and_literals.md)