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

2026-01-10 16:55:44 +08:00
parent b529012c59
commit 5822a8736d
88 changed files with 103561 additions and 130104 deletions
@@ -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`