playbook/codex/skills/tsl-guide/SKILL.md

name	description
tsl-guide	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 以语法为主，风格规范单独引用。

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

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

变量与常量

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

函数

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

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

控制流

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;

异常处理

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

数组与索引

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 函数

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

Token 消耗：~6,000 tokens

场景 2：编写 TSL 类

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

Token 消耗：~10,000 tokens

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

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 行）

检索示例：

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