♻️ refactor(playbook): streamline agents and refresh tsl docs

codex/skills/performance-optimization/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: performance-optimization
+description: "性能优化工作流（TSL/Python/C++）：度量→定位→优化→验证。Triggers: 性能优化, 优化性能, 代码慢, 提升速度, performance optimization, slow code, profiling"
+---
+
+# 性能优化工作流
+
+> 适用语言：TSL / Python / C++
+> 核心原则：没有度量就没有优化。
+
+## 使用时机
+
+- 功能正确，但响应慢或资源消耗过高
+- 热路径明显（循环/批处理/大规模数据）
+- 需要在不改变行为的前提下提升性能
+
+## 必备输入
+
+- 目标场景与数据规模（输入大小、并发量）
+- 基线指标（耗时、吞吐、内存、CPU）
+- 约束条件（允许的改动范围、兼容性要求）
+
+## 工作流程（按顺序）
+
+### 1. 度量基线（Baseline）
+
+先拿到“优化前”的数据作为对照。
+
+- TSL（计时示例，使用 MTIC/MTOC）：
+
+```tsl
+T1 := MTIC;
+// ... 逻辑 ...
+Elapsed := MTOC(T1);
+Echo "Elapsed:", Elapsed;
+```
+
+- Python：
+
+```python
+import time
+start = time.time()
+# ... code ...
+print(f"Elapsed: {time.time() - start:.3f}s")
+```
+
+- C++：
+
+```cpp
+auto start = std::chrono::high_resolution_clock::now();
+// ... code ...
+auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+    std::chrono::high_resolution_clock::now() - start);
+std::cout << "Elapsed: " << elapsed.count() << "ms\n";
+```
+
+### 2. 定位瓶颈（Profiling）
+
+只优化热点，不动冷路径。
+
+- TSL：插入关键路径计时，或使用 `docs/tsl/syntax_book/07_debug_and_profiler.md` 中的工具
+- Python：`cProfile` / `line_profiler`
+- C++：`perf` / `gprof` / `valgrind --tool=callgrind`
+
+### 3. 优化策略（从高收益到低收益）
+
+**3.1 算法级（优先级最高）**
+- 降低复杂度：`O(n^2)` → `O(n log n)` → `O(n)`
+- 避免重复计算：缓存、记忆化
+
+**3.2 数据结构级**
+- 选择合适容器：数组 vs 哈希表 vs 树
+- 预分配容量，减少扩容
+
+**3.3 循环级**
+- 循环内不做 I/O
+- 循环内避免重复解析/格式化
+- 提前计算循环不变量
+
+**3.4 I/O 级**
+- 批量读写（减少系统调用）
+- 缓存（明确 TTL 与容量上限）
+
+### 4. 验证效果（Verify）
+
+- 对比优化前后指标
+- 运行回归测试，保证行为一致
+- 在真实数据量下复测
+
+## 反模式（不要做）
+
+- 没有度量就“感觉”优化
+- 牺牲可读性换取微小收益
+- 为冷路径引入复杂缓存
+- 未验证就宣称提升
+
+## 输出清单（交付要求）
+
+- 基线指标（优化前）
+- 瓶颈定位结果（热点函数/路径）
+- 优化方案与改动点
+- 优化后指标（对比数据）
+- 风险说明与回滚策略
+
+## 权威参考
+
+- TSL：`docs/tsl/syntax_book/07_debug_and_profiler.md`
+- Python：`docs/python/tooling.md`
+- C++：`docs/cpp/toolchain.md`

codex/skills/testing-workflow/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: testing-workflow
+description: "测试策略与最佳实践（TSL/Python/C++）：单元测试→集成测试→回归测试。Triggers: 写测试, 测试策略, 单元测试, 集成测试, testing, unit test, how to test"
+---
+
+# 测试工作流
+
+> 适用语言：TSL / Python / C++
+> 核心原则：新功能与 bug 修复必须有可复现的测试。
+
+## 使用时机
+
+- 新功能开发
+- Bug 修复
+- 重构或行为变更
+
+## 测试层级
+
+### 1. 单元测试（Unit Tests）
+
+**目标**：验证单个函数/类的行为
+
+- 测试纯函数（无副作用）
+- Mock 外部依赖（文件/网络/数据库）
+- 一个测试只验证一个行为点
+
+**命名示例**：
+- `test_add_positive_numbers_returns_sum`
+- `test_add_with_zero_returns_other_number`
+
+### 2. 集成测试（Integration Tests）
+
+**目标**：验证模块间交互
+
+- 关键流程的 end-to-end 测试
+- 使用真实依赖或测试环境
+- 验证数据流与状态转换
+
+### 3. 回归测试（Regression Tests）
+
+**目标**：防止已修复的 bug 复发
+
+- 修 bug 先写失败测试
+- 修复后测试通过
+
+## 何时补测试
+
+| 场景 | 是否需要测试 | 测试类型 |
+|------|-------------|---------|
+| 新功能 | ✅ 必须 | 单元 + 集成 |
+| Bug 修复 | ✅ 必须 | 回归 |
+| 重构 | ✅ 必须 | 运行现有测试 |
+| 文档/注释 | ❌ 不需要 | - |
+| 格式调整 | ❌ 不需要 | - |
+
+## 测试可维护性原则
+
+1. 一个测试一个断言（或一组相关断言）
+2. 测试名称自解释
+3. 避免依赖外部资源（用 Mock/Stub）
+4. 测试代码也要可读
+
+## 反模式
+
+- 依赖执行顺序、随机数、系统时间
+- 单元测试过慢（>1s）
+- Magic number 过多
+- 重复测试相同行为
+
+## 运行测试
+
+### TSL
+
+- 若项目已有测试命令，优先使用项目标准命令
+- 否则建议添加最小可运行脚本并在 README 说明
+
+### Python
+
+```bash
+pytest tests/
+pytest tests/test_module.py::test_function
+```
+
+### C++
+
+```bash
+ctest
+./build/test_runner --gtest_filter=TestSuite.TestName
+```
+
+## 测试失败处理
+
+1. 定位：哪个测试失败、失败条件是什么
+2. 复现：单独运行失败用例
+3. 调试：优先检查本次改动
+4. 无关失败：记录并告知用户
+
+## 可选：测试驱动开发（TDD）
+
+1. Red：先写失败测试
+2. Green：写最少代码让测试通过
+3. Refactor：重构保持测试绿色
+
+## 权威参考
+
+- TSL：`docs/tsl/` 测试相关文档（如有）
+- Python：`docs/python/tooling.md`
+- C++：`docs/cpp/toolchain.md`

codex/skills/tsl-guide/SKILL.md

@@ -0,0 +1,192 @@
+---
+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 := array("Code":"0001","Price":12.3);
+Const MaxRetries = 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];
+
+m := array((1,2),(3,4));
+col0 := m[:,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. **必要时检索函数库**：先索引，再定位片段
+
+---
+
+## ⚠️ 函数库使用规则
+
+- **禁止整目录加载**：`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`

codex/skills/tsl-guide/references/advanced.md

@@ -0,0 +1,230 @@
+# TSL 高级特性
+
+> 本文档是 `$tsl-guide` 的子文档，覆盖模块/对象/扩展语法与新一代特性。
+> 详细规则以 `docs/tsl/syntax_book/` 为准。
+
+## 目录
+
+- [Unit/命名空间/函数文件](#unit命名空间函数文件)
+- [Class/Object 模型](#classobject-模型)
+- [扩展语法：矩阵/集合/过滤](#扩展语法矩阵集合过滤)
+- [TS-SQL（select/insert/update/delete）](#ts-sqlselectinsertupdatedelete)
+- [运行时与性能语法要点](#运行时与性能语法要点)
+- [新一代语法概览](#新一代语法概览)
+
+---
+
+## Unit/命名空间/函数文件
+
+### Unit 基本结构
+
+```tsl
+Unit Demo_Unit;
+
+interface
+
+var Ua,Ub;
+const CS = 888;
+
+function AddV();
+
+implementation
+
+var Uc;
+
+function AddV();
+begin
+  Ua += 10;
+  Uc += 1;
+end;
+
+initialization
+  Ua := 100;
+  Ub := "Tinysoft Unit";
+  Uc := 1;
+
+finalization
+  echo "Demo_Unit End.";
+
+end.
+```
+
+### uses 与调用优先级
+
+```tsl
+uses Demo_Unit;
+
+// 直接调用（按 uses 优先级解析）
+AddV();
+
+// 指定单元调用
+Unit(Demo_Unit).AddV();
+CALL("Demo_Unit.AddV");
+```
+
+### 函数文件（TSF）与命名空间
+
+- `.tsf` 文件可存放 function/class/unit（函数库目录 `funcext`）
+- 命名空间：
+
+```tsl
+NameSpace "ProjectA";
+
+SomeFunction();
+```
+
+如需固定命名空间，可在 `tsl.Conf` 配置 `Namespace=...`（详见 `04_modules_and_namespace.md`）。
+
+---
+
+## Class/Object 模型
+
+### 类定义与继承
+
+```tsl
+Type Base = Class
+  function Speak(); virtual;
+end;
+
+Type Child = Class(Base)
+  function Speak(); override;
+end;
+```
+
+### 构造函数与析构函数
+
+```tsl
+Type User = Class
+  user_id;
+  user_name;
+
+  function Create(id,name); overload;
+  Begin
+    user_id := id;
+    user_name := name;
+  End;
+
+  function Destroy();
+  Begin
+    // 清理资源
+  End;
+end;
+```
+
+### 属性（Property）
+
+```tsl
+Type Account = Class
+  _id;
+  function getId();
+  function setId(v);
+  property Id read _id write setId;
+end;
+```
+
+### 创建对象
+
+```tsl
+Obj := CreateObject("User", 1, "Alice");
+Obj2 := New User(2, "Bob");
+```
+
+更多：`Self`、`FindClass`、`ClassInfo`、`operator` 重载等见 `05_object_model.md`。
+
+---
+
+## 扩展语法：矩阵/集合/过滤
+
+### 矩阵初始化与访问
+
+```tsl
+M1 := zeros(10);           // 一维数组
+M2 := zeros(10,10);        // 二维矩阵
+M3 := rand(5,3);           // 随机矩阵
+M4 := eye(3);              // 单位矩阵
+Seq := 1->10;              // 数列数组
+```
+
+```tsl
+// 子矩阵与索引
+Rows := MRows(M2,1);
+Cols := MCols(M2,1);
+Sub := M2[array(1,3), array(0,2)];
+Col0 := M2[:,0];
+```
+
+### 矩阵查找
+
+```tsl
+A := Rand(10,10);
+B := MFind(A, MCell>0.9);
+```
+
+### 集合运算
+
+```tsl
+A := array((1,2),(3,4));
+B := array((1,2),(5,6));
+C := A Union2 B;
+D := A Intersect B;
+E := A Minus B;
+```
+
+### 结果集过滤
+
+```tsl
+R1 := FilterIn(R, CodeArr, "Code");
+Idx := FilterNotIn(R, CodeArr, "Code", false);
+Sub := R[Idx, array("Code","V1")];
+```
+
+更多细节见 `06_extended_syntax.md`。
+
+---
+
+## TS-SQL（select/insert/update/delete）
+
+```tsl
+T := zeros(10, array("A","B"));
+T[:,"A"] := 1->10;
+
+V1 := select ["A"] from T end;
+V2 := sselect ["A"] from T end;
+V3 := vselect sumof(["A"]) from T end;
+V4 := mselect * from T end;
+
+update T set ["A"] = 100 where ["B"] = 4 end;
+delete from T where ["A"] = 0 end;
+insert into T insertfields(["A"],["B"]) values(1,2);
+```
+
+TS-SQL 语法细节与高级用法见 `06_extended_syntax.md`。
+
+---
+
+## 运行时与性能语法要点
+
+### 网格计算操作符 `#`
+
+```tsl
+R[i] := #CalcStock(B[i]) with array(pn_stock():B[i]) timeout 3000;
+```
+
+### 全局缓存
+
+详见 `07_debug_and_profiler.md` 中的全局缓存管理与相关函数。
+
+---
+
+## 新一代语法概览
+
+### 复数
+
+```tsl
+Z := 4+3j;
+Z2 := complex(4,3);
+```
+
+### WeakRef 与算符重载
+
+新一代语言支持 WeakRef 与对象算符重载，详见 `08_new_generation.md` 与 `05_object_model.md`。

codex/skills/tsl-guide/references/common_patterns.md

@@ -0,0 +1,126 @@
+# TSL 常见编码模式
+
+> 本文档是 `$tsl-guide` 的子文档，汇总常见的组织方式与实践范式。
+> 语法示例以 `docs/tsl/syntax_book/` 为准。
+
+## 目录
+
+- [参数校验](#参数校验)
+- [早返回（减少嵌套）](#早返回减少嵌套)
+- [错误处理与上下文信息](#错误处理与上下文信息)
+- [I/O 分层](#io-分层)
+- [常量与配置管理](#常量与配置管理)
+- [集合与结果集处理](#集合与结果集处理)
+- [性能小贴士](#性能小贴士)
+
+---
+
+## 参数校验
+
+尽早验证输入并给出明确错误信息。
+
+```tsl
+Function ValidateUserId(UserId);
+Begin
+  If UserId <= 0 then
+    Raise "invalid user_id: " + IntToStr(UserId);
+End;
+```
+
+---
+
+## 早返回（减少嵌套）
+
+```tsl
+Function NormalizeName(Name);
+Begin
+  If Trim(Name) = "" then
+    Return "";
+
+  Return UpperCase(Trim(Name));
+End;
+```
+
+---
+
+## 错误处理与上下文信息
+
+```tsl
+Function LoadConfig(Path);
+Begin
+  Try
+    Return ReadFile(Path);
+  Except
+    Raise "load config failed: " + Path + ", " + ExceptObject.ErrInfo;
+  End;
+End;
+```
+
+---
+
+## I/O 分层
+
+```tsl
+Function ReadUserIds(Path);
+Begin
+  Content := ReadFile(Path);
+  Return ParseUserIds(Content);
+End;
+
+Function ParseUserIds(Content);
+Begin
+  // 纯函数：只负责解析
+  Return array();
+End;
+
+Function WriteReport(Path, Report);
+Begin
+  WriteFile(Path, Report);
+End;
+```
+
+---
+
+## 常量与配置管理
+
+```tsl
+Const MaxRetries = 3;
+Const TimeoutMs = 5000;
+
+Function RetryFetch(Url);
+Begin
+  For i := 1 to MaxRetries do
+  Begin
+    // ...
+  End;
+End;
+```
+
+---
+
+## 集合与结果集处理
+
+```tsl
+Function SumPositive(Values);
+Begin
+  Total := 0;
+  For i := 0 to Length(Values) - 1 do
+  Begin
+    If Values[i] > 0 then
+      Total := Total + Values[i];
+  End;
+  Return Total;
+End;
+```
+
+---
+
+## 性能小贴士
+
+仅当明确存在性能瓶颈时采用：
+
+- 把循环内的常量/表达式提到循环外
+- 避免在循环内执行 I/O 或 SQL
+- 对结果集访问做局部缓存（如字段名映射）
+
+详细流程见：`$performance-optimization`。

codex/skills/tsl-guide/references/functions_index.md

@@ -0,0 +1,67 @@
+# TSL 函数库分类索引
+
+> **说明**：本文档是 `$tsl-guide` 的子文档，仅提供分类索引与检索策略。
+> **权威入口**：`docs/tsl/syntax_book/function/tsl/index.md`
+> **注意**：函数库已拆分为 `docs/tsl/syntax_book/function/` 多文件，禁止整目录加载。
+
+## 使用方法
+
+1. 先在 `function/tsl/index.md` 找到所属类别
+2. 进入对应子文件（如 `base.md` / `math.md` / `resource.md`）
+3. 用 `rg` 精确定位函数定义片段（≤100 行）
+
+### 推荐搜索方式
+
+```bash
+# 先读索引
+sed -n '1,120p' docs/tsl/syntax_book/function/tsl/index.md
+
+# 精确定位某个函数
+rg -n "^#######\s+Trim" docs/tsl/syntax_book/function/tsl/base.md
+
+# 模糊搜索关键词
+rg -n "date|time" docs/tsl/syntax_book/function/tsl/base.md
+```
+
+---
+
+## 常用分类（来自 `function/tsl/index.md`）
+
+### 数学与计算（math.md）
+
+- 常见函数示例：Abs, Sqrt, Sin, Cos, Log, Exp, Round...
+
+### 字符串处理（base.md）
+
+- 常见函数示例：Len, Mid, Left, Right, Trim, Replace...
+
+### 日期时间（base.md）
+
+- 常见函数示例：Now, Date, Time, DateAdd, DateDiff...
+
+### 文件操作（resource.md）
+
+- 常见函数示例：FileExists, ReadFile, WriteFile...
+
+### 数组操作（base.md）
+
+- 常见函数示例：Array, UBound, LBound, Sort...
+
+### 类型转换（base.md）
+
+- 常见函数示例：CStr, CInt, CFloat, CBool...
+
+---
+
+## 进一步建议
+
+- 优先用索引确定范围，再定位到具体函数定义
+- 只读取相关片段，避免加载大段内容
+- 若函数名不确定，用关键词在对应分类文件中搜索
+
+---
+
+## 金融函数（独立分类）
+
+- 权威入口：`docs/tsl/syntax_book/function/financial/index.md`
+- 适用范围：行情、财务、技术分析等金融领域函数（与通用字符串/数学函数分开检索）

codex/skills/tsl-guide/references/primer.md

@@ -0,0 +1,354 @@
+# TSL 基础语法完整版
+
+> 本文档是 `$tsl-guide` 的子文档，聚焦基础语法。代码风格与命名规范请见 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`。
+
+## 目录
+
+- [语言元素与注释](#语言元素与注释)
+- [变量与常量](#变量与常量)
+- [数据类型与字面量](#数据类型与字面量)
+- [数组与表数组](#数组与表数组)
+- [运算符与表达式](#运算符与表达式)
+- [函数](#函数)
+- [控制流](#控制流)
+- [异常处理](#异常处理)
+- [调试与性能相关语句](#调试与性能相关语句)
+
+---
+
+## 语言元素与注释
+
+### 标识符与关键字
+
+- 关键字为保留字（完整列表见 `docs/tsl/syntax_book/01_language_basics.md`）
+- 标识符用于变量、函数、类、unit 等命名
+
+### 注释
+
+```tsl
+// 行注释
+{ 块注释 }
+/* 另一种块注释 */
+```
+
+### 编译选项（语法级）
+
+```tsl
+{$Explicit+}  // 要求变量先声明再使用
+{$Explicit-}  // 关闭显式声明
+{$VarByRef-}  // 默认参数按值传递（可用 in/var/out 覆盖）
+```
+
+---
+
+## 变量与常量
+
+### 赋值
+
+```tsl
+A := 1;
+B := 2.5;
+S := "hello";
+```
+
+### 常量
+
+```tsl
+Const PI = 3.14159;
+Const MaxRetry = 3;
+```
+
+### 显式变量声明（配合 `{$Explicit+}`）
+
+```tsl
+{$Explicit+}
+
+Var A,B;          // 多变量声明
+Var C := 10;      // 声明并初始化
+Var D:Integer;    // 类型可写可省（类型信息不做强校验）
+```
+
+---
+
+## 数据类型与字面量
+
+常见类型（参考 `01_language_basics.md`）：
+
+| 类型 | 说明 |
+|------|------|
+| Integer / Int64 | 整数 |
+| Real | 浮点数 |
+| Boolean | 布尔值（true/false） |
+| TDateTime | 日期时间 |
+| String | 字符串 |
+| Binary | 二进制 |
+| Array | 数组 |
+| Matrix / TMatrix | 矩阵 |
+| NIL | 空值 |
+
+示例：
+
+```tsl
+I := 42;
+R := 3.14;
+B := true;
+T := Date();
+S := 'hello';
+N := nil;
+```
+
+字符串支持单引号或双引号，索引访问从 0 开始：
+
+```tsl
+S := "ABC";
+Ch := S[0];
+```
+
+---
+
+## 数组与表数组
+
+### 一维数组（0-based）
+
+```tsl
+Arr := array(2,3,5,7,11);
+First := Arr[0];
+```
+
+### 字符串下标（表数组）
+
+```tsl
+Row := array("Code":"0001","Price":12.3);
+Code := Row["Code"];
+```
+
+### 多维数组
+
+```tsl
+Mat := array((1,2,3),(4,5,6));
+Value := Mat[0][1];
+```
+
+---
+
+## 运算符与表达式
+
+### 常用运算符
+
+- 赋值：`:=`, `+=`, `-=`, `*=`, `/=`
+- 算术：`+ - * / div mod ^`
+- 关系：`= <> < > <= >= like in`
+- 逻辑：`and or not`
+- 三目：`cond ? a : b`
+
+示例：
+
+```tsl
+C := A + B;
+Ok := (A = B) or (A > 0);
+X := (A > B) ? A : B;
+```
+
+矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。
+完整运算符清单见 `01_language_basics.md`。
+
+---
+
+## 函数
+
+### 基本结构
+
+```tsl
+Function HelloTSL();
+Begin
+  D := Date();
+  Return DateToStr(D);
+End;
+```
+
+### 形参与实参（in/const/var/out）
+
+```tsl
+Function Calc(in a, var b, out c);
+Begin
+  b := b + a;
+  c := b * 2;
+  Return c;
+End;
+```
+
+### 缺省参数（新一代语法）
+
+```tsl
+Function Foo(a,b=a+1);
+Begin
+  Return b;
+End;
+```
+
+### 命名参数（新一代语法）
+
+```tsl
+Function FuncA(a,b,c);
+Begin
+  Return array(a,b,c);
+End;
+
+Result := FuncA(1, c:3); // b 默认为 nil
+```
+
+### 变参（`...`）与 Params
+
+```tsl
+Function SumAll(...);
+Begin
+  Total := 0;
+  For i,v in Params do
+    Total := Total + v;
+  Return Total;
+End;
+```
+
+相关内置：`Params`, `ParamCount`, `RealParamCount`。
+
+### 返回与退出
+
+```tsl
+Return X;   // 返回
+Exit;       // 退出函数
+```
+
+### 外部函数声明（external）
+
+```tsl
+Function GetTickCount():Integer; stdcall; external "kernel32.dll" name "GetTickCount" KeepResident;
+```
+
+更多外部接口与调用方式见 `03_functions.md`。
+
+---
+
+## 控制流
+
+### if / else if
+
+```tsl
+If x>0 then
+  y := 1
+else if x=0 then
+  y := 0
+else
+  y := -1;
+```
+
+### if 表达式（新一代语法）
+
+```tsl
+Ret := if x>0 then x*x else 0;
+```
+
+### case
+
+```tsl
+Case Age Of
+  0: Writeln("Baby");
+  1: Writeln("Toddler");
+else
+  Writeln("Other");
+End;
+```
+
+### while / repeat
+
+```tsl
+While cond do
+  DoSomething();
+
+Repeat
+  DoSomething();
+Until cond;
+```
+
+### for（to / downto / step）
+
+```tsl
+For i := 1 to 10 do
+  Sum := Sum + i;
+
+For i := 10 downto 1 step 2 do
+  Sum := Sum + i;
+```
+
+### for ... in（数组遍历）
+
+```tsl
+Data := array('a':1,'b':5,'c':3);
+Sum := 0;
+
+For k,v in Data do
+  Sum := Sum + v;
+```
+
+### break / continue / goto
+
+```tsl
+While cond do
+Begin
+  If stop then Break;
+  If skip then Continue;
+  // ...
+End;
+
+Goto Finded;
+label Finded;
+  Writeln("jumped");
+```
+
+---
+
+## 异常处理
+
+### Try / Except
+
+```tsl
+Try
+  V := StrToInt(S);
+Except
+  V := 0;
+  Writeln(ExceptObject.ErrInfo);
+End;
+```
+
+### Try / Finally
+
+```tsl
+Try
+  DoWork();
+Finally
+  Cleanup();
+End;
+```
+
+### Raise
+
+```tsl
+If A < 0 then Raise "A 不能小于 0";
+```
+
+异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。
+
+---
+
+## 调试与性能相关语句
+
+```tsl
+DebugReturn 1;
+```
+
+```tsl
+T1 := MTIC;
+// ...
+Elapsed := MTOC(T1);
+```
+
+更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。