---
name: tsl-guide
description: "TSL/TSF 语法与工程实践指南（基础语法/高级特性/函数库/最佳实践）。Triggers: TSL 语法, 写 TSL, 写 TSF, TSL 函数, TSL class, TSL unit, 矩阵操作, TS-SQL, TSL 函数库, tsl basics, tsl advanced, how to write tsl, tsf code, tsl api, 学习 TSL"
---

# TSL 完整指南

> **定位**：TSL 语言的一站式参考，从入门到进阶。本 skill 以语法为主，风格规范单独引用。

## 🚀 快速语法速查（仅语法）

> 代码风格与命名不是语法的一部分，见下方「代码风格与命名」。

### 变量与常量

```tsl
a := 1;
name := "test";
items := array(1, 2, 3);
table_data := array("Code": "0001", "Price": 12.3);
const kMaxRetries = 3;
```

### 函数

```tsl
function Add(a, b);
begin
    return a + b;
end;
```

```tsl
function Parse(const s, var out_value);
begin
    out_value := StrToInt(s);
    return out_value;
end;
```

### 控制流

```tsl
if x > 0 then
    y := 1;
else if x = 0 then
    y := 0;
else
    y := -1;

for i := 0 to 9 do
    sum := sum + i;

for idx, v in items do
    total := total + v;
```

### 异常处理

```tsl
try
    v := StrToInt(s);
except
    v := 0;
    WriteLn(ExceptObject.ErrInfo);
end;
```

### 数组与索引

```tsl
arr := array(10, 20, 30);
value := arr[0];

matrix := array((1, 2), (3, 4));
col_0 := matrix[:, 0];
```

---

## 📌 代码风格与命名（非语法）

- 代码风格：`docs/tsl/code_style.md`
- 命名规范：`docs/tsl/naming.md`
- 本仓库硬约束：`.agents/tsl/index.md`

---

## 📚 详细文档索引（按需加载）

### 📖 基础语法（primer）

**文件**：`references/primer.md`
**内容**：

- 变量/常量、类型与字面量
- 数组与表数组表达
- 运算符与表达式
- 函数定义、参数修饰、默认值、命名参数、变参
- 控制流（if/case/for/while/repeat）
- 异常处理（try/except/finally/raise）
- 编译选项（`{$Explicit+}`/`{$VarByRef-}`）

**适用场景**：第一次写 TSL、查基础语法细节。

---

### 🚀 高级特性（advanced）

**文件**：`references/advanced.md`
**内容**：

- Unit/Namespace/函数文件与调用优先级
- Class/Object 模型（继承/override/Create/Destroy）
- 扩展语法：矩阵、集合运算、结果集过滤
- TS-SQL：select/insert/update/delete/sselect/vselect/mselect
- 运行时与性能语法要点（#网格计算等）
- 新一代语法概览（复数/WeakRef/算符重载）

**适用场景**：面向对象、模块化、矩阵与 TS-SQL、高级特性。

---

### 🔍 函数库速查（index）

**文件**：`references/functions_index.md`
**内容**：

- 函数库分类索引与检索策略
- 对应权威目录：`docs/tsl/syntax_book/function/tsl/index.md`

**重要说明**：

- 函数库已拆分为 `docs/tsl/syntax_book/function/` 多文件，**禁止整目录加载**
- 优先在 `docs/tsl/syntax_book/function/tsl/` 下分文件检索

---

### 💡 常见模式与最佳实践

**文件**：`references/common_patterns.md`
**内容**：参数校验、错误处理、I/O 分层、性能小贴士。

---

## ✅ 语法覆盖清单（对照 `docs/tsl/syntax_book/`）

- `01_language_basics.md` → `references/primer.md`
- `02_control_flow.md` → `references/primer.md`
- `03_functions.md` → `references/primer.md`
- `04_modules_and_namespace.md` → `references/advanced.md`
- `05_object_model.md` → `references/advanced.md`
- `06_extended_syntax.md` → `references/advanced.md`
- `07_debug_and_profiler.md` → `references/advanced.md`（语法要点）
- `08_new_generation.md` → `references/advanced.md`（概览）

---

## 🤖 Agent 使用指南

1. **分析需求**：判断需要基础语法还是高级特性
2. **按需加载**：只读取一个子文档（避免贪婪加载）
3. **必要时检索函数库**：先索引，再定位片段

### 典型场景与 Token 消耗

**场景 1：编写简单的 TSL 函数**

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 SKILL.md
3. 生成代码

Token 消耗：~6,000 tokens
```

**场景 2：编写 TSL 类**

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 SKILL.md + references/advanced.md
3. 生成代码

Token 消耗：~10,000 tokens
```

**场景 3：查询 TSL 函数库条目**

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 references/functions_index.md
3. 使用 rg 定位函数片段
4. 返回答案

Token 消耗：~8,000 tokens
```

---

## ⚠️ 函数库使用规则

- **禁止整目录加载**：`docs/tsl/syntax_book/function/` 体量巨大
- **推荐流程**：
  1. 先看 `docs/tsl/syntax_book/function/tsl/index.md`
  2. 再在 `docs/tsl/syntax_book/function/tsl/*.md` 中搜索
  3. 只读取相关函数片段（≤100 行）

**检索示例**：

```bash
rg -n "\\bTrim\\b" docs/tsl/syntax_book/function/tsl/base.md
rg -n "^######\s+FileExists" docs/tsl/syntax_book/function/tsl/resource.md
```

---

## 🔗 权威文档路径

- 语法手册总览：`docs/tsl/syntax_book/index.md`
- 语言基础：`docs/tsl/syntax_book/01_language_basics.md`
- 控制流与异常：`docs/tsl/syntax_book/02_control_flow.md`
- 函数：`docs/tsl/syntax_book/03_functions.md`
- 模块与命名空间：`docs/tsl/syntax_book/04_modules_and_namespace.md`
- 对象模型：`docs/tsl/syntax_book/05_object_model.md`
- 扩展语法：`docs/tsl/syntax_book/06_extended_syntax.md`
- 运行时与性能工具：`docs/tsl/syntax_book/07_debug_and_profiler.md`
- 新一代语法：`docs/tsl/syntax_book/08_new_generation.md`
- 函数库：`docs/tsl/syntax_book/function/tsl/index.md`
- 代码风格：`docs/tsl/code_style.md`
- 命名规范：`docs/tsl/naming.md`