From 956da1134880173aac1ca9809501c4fddc8866d1 Mon Sep 17 00:00:00 2001 From: csh Date: Thu, 23 Apr 2026 14:02:42 +0800 Subject: [PATCH] :bug: fix(playbook): publish hidden ci test fixes Unhide the tracked docs and test updates that were left under assume-unchanged, remove the shipped tsl-guide skill, and align the deploy_root-related test coverage with the current external-clone rules. --- codex/skills/tsl-guide/SKILL.md | 230 ----------- codex/skills/tsl-guide/references/advanced.md | 230 ----------- .../tsl-guide/references/common_patterns.md | 124 ------ .../tsl-guide/references/functions_index.md | 66 ---- codex/skills/tsl-guide/references/primer.md | 368 ------------------ docs/index.md | 11 +- rulesets/tsl/index.md | 8 +- templates/ci/README.md | 2 +- tests/test_gitattributes_modes.py | 2 + tests/test_no_backup_flags.py | 3 + tests/test_sync_directory_actions.py | 4 + tests/test_sync_templates_placeholders.py | 4 + tests/test_vendor_snapshot_templates.py | 2 + 13 files changed, 26 insertions(+), 1028 deletions(-) delete mode 100644 codex/skills/tsl-guide/SKILL.md delete mode 100644 codex/skills/tsl-guide/references/advanced.md delete mode 100644 codex/skills/tsl-guide/references/common_patterns.md delete mode 100644 codex/skills/tsl-guide/references/functions_index.md delete mode 100644 codex/skills/tsl-guide/references/primer.md diff --git a/codex/skills/tsl-guide/SKILL.md b/codex/skills/tsl-guide/SKILL.md deleted file mode 100644 index d1b9884..0000000 --- a/codex/skills/tsl-guide/SKILL.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -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` diff --git a/codex/skills/tsl-guide/references/advanced.md b/codex/skills/tsl-guide/references/advanced.md deleted file mode 100644 index f840608..0000000 --- a/codex/skills/tsl-guide/references/advanced.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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`。 diff --git a/codex/skills/tsl-guide/references/common_patterns.md b/codex/skills/tsl-guide/references/common_patterns.md deleted file mode 100644 index 9988326..0000000 --- a/codex/skills/tsl-guide/references/common_patterns.md +++ /dev/null @@ -1,124 +0,0 @@ -# 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 -- 对结果集访问做局部缓存（如字段名映射） diff --git a/codex/skills/tsl-guide/references/functions_index.md b/codex/skills/tsl-guide/references/functions_index.md deleted file mode 100644 index 1573ed1..0000000 --- a/codex/skills/tsl-guide/references/functions_index.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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` -- 适用范围：行情、财务、技术分析等金融领域函数（与通用字符串/数学函数分开检索） diff --git a/codex/skills/tsl-guide/references/primer.md b/codex/skills/tsl-guide/references/primer.md deleted file mode 100644 index 40c10dc..0000000 --- a/codex/skills/tsl-guide/references/primer.md +++ /dev/null @@ -1,368 +0,0 @@ -# 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 kPi = 3.14159; -const kMaxRetry = 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 -matrix := array((1, 2, 3), (4, 5, 6)); -value := matrix[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; -``` - -### 参数分隔与类型注解 - -类型注解仅用于说明与阅读，编译器不做类型检查。 - -- 无类型注解时用逗号分隔参数 -- 带类型注解时用分号分隔参数 -- 返回值类型写在 `)` 之后 - -```tsl -function F1(a, b); -function F2(a: string; b: array of real); -function F3(): void; -``` - -### 形参与实参（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 value; // 返回 -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 found; -label found; - 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`。 diff --git a/docs/index.md b/docs/index.md index d3e56c4..099adbf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,15 +9,14 @@ ## TSL（tsl/tsf） - TSL 源文件后缀同时包含：`.tsl`（脚本）与 `.tsf`（模块/库代码）。 +- TSL 总入口（先判断主问题属于哪一层）：`tsl/index.md` - 代码风格：`tsl/code_style.md` - 命名规范：`tsl/naming.md` -- 语法手册（TSL 语法；函数库按需检索 `tsl/syntax_book/function/`）：`tsl/syntax_book/index.md` +- 语法手册（只处理“语言怎么写”）：`tsl/syntax/index.md` +- 金融业务入口（指标、选股、回测与策略流程）：`tsl/finance/index.md` +- 模块与集成入口（pyTSL、微信消息、Python 互操作、回测框架）：`tsl/modules/index.md` +- 函数检索入口（模块目录位于 `tsl/reference/catalog/`）：`tsl/reference/index.md` - 工具链与验证命令（模板）：`tsl/toolchain.md` -- TSL 模块化文档： - - 微信消息接口说明：`tsl/modules/wechat_message.md` - - 回测框架 TSBackTesting：`tsl/modules/tsbacktesting.md` - - 天软与 Python 交互：`tsl/modules/tsl_python_interop.md` - - pyTSL 接口说明：`tsl/modules/pytsl_api.md` ## C++（cpp） diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index 65f1dc8..c0860d6 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -28,14 +28,16 @@ ## 权威来源 -- 语法手册：`docs/tsl/syntax_book/index.md` -- 函数库：`docs/tsl/syntax_book/function/`（按需检索，禁止整份加载） +- TSL 总入口：`docs/tsl/index.md` +- 语法手册：`docs/tsl/syntax/index.md` +- 金融业务入口：`docs/tsl/finance/index.md` +- 模块与集成入口：`docs/tsl/modules/index.md` +- 函数检索入口：`docs/tsl/reference/index.md` - 代码风格：`docs/tsl/code_style.md` - 命名规范：`docs/tsl/naming.md` ## Skills（按需加载） -- `$tsl-guide` - `$commit-message` ## 与开发规范的关系 diff --git a/templates/ci/README.md b/templates/ci/README.md index 398dc59..e8ebb24 100644 --- a/templates/ci/README.md +++ b/templates/ci/README.md @@ -11,7 +11,7 @@ ## 使用（Gitea Actions） -前提：目标项目已经 vendoring Playbook（例如 `docs/standards/playbook/`）。 +前提：目标项目已经把 Playbook 部署到项目内（例如 `docs/standards/playbook/`）。 复制到目标项目根目录： diff --git a/tests/test_gitattributes_modes.py b/tests/test_gitattributes_modes.py index 2004b7f..3e92131 100644 --- a/tests/test_gitattributes_modes.py +++ b/tests/test_gitattributes_modes.py @@ -7,6 +7,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SCRIPT = ROOT / "scripts" / "playbook.py" SOURCE_GITATTR = ROOT / ".gitattributes" +DEFAULT_DEPLOY_ROOT = "docs/standards/playbook" def run_cli(*args, cwd=None): @@ -33,6 +34,7 @@ class GitattributesModeTests(unittest.TestCase): config_body = f""" [playbook] project_root = \"{root}\" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_standards] langs = [\"tsl\"] diff --git a/tests/test_no_backup_flags.py b/tests/test_no_backup_flags.py index 4f23dff..352296a 100644 --- a/tests/test_no_backup_flags.py +++ b/tests/test_no_backup_flags.py @@ -6,6 +6,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SCRIPT = ROOT / "scripts" / "playbook.py" +DEFAULT_DEPLOY_ROOT = "docs/standards/playbook" def run_cli(*args): @@ -26,6 +27,7 @@ class NoBackupFlagsTests(unittest.TestCase): config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_rules] force = true @@ -54,6 +56,7 @@ no_backup = true config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_standards] langs = ["tsl"] diff --git a/tests/test_sync_directory_actions.py b/tests/test_sync_directory_actions.py index 6d08219..39b423b 100644 --- a/tests/test_sync_directory_actions.py +++ b/tests/test_sync_directory_actions.py @@ -6,6 +6,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SCRIPT = ROOT / "scripts" / "playbook.py" +DEFAULT_DEPLOY_ROOT = "docs/standards/playbook" def run_cli(*args): @@ -28,6 +29,7 @@ class SyncDirectoryActionsTests(unittest.TestCase): config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_memory_bank] project_name = "Demo" @@ -52,6 +54,7 @@ project_name = "Demo" config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_prompts] """ @@ -78,6 +81,7 @@ project_root = "{tmp_dir}" config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_memory_bank] project_name = "Demo" diff --git a/tests/test_sync_templates_placeholders.py b/tests/test_sync_templates_placeholders.py index d8ac06c..0750d4c 100644 --- a/tests/test_sync_templates_placeholders.py +++ b/tests/test_sync_templates_placeholders.py @@ -6,6 +6,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SCRIPT = ROOT / "scripts" / "playbook.py" +DEFAULT_DEPLOY_ROOT = "docs/standards/playbook" def run_cli(*args): @@ -31,6 +32,7 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): config_body = f""" [playbook] project_root = \"{tmp_dir}\" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_rules] @@ -64,6 +66,7 @@ langs = [\"cpp\", \"tsl\"] f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [vendor] langs = ["typescript"] @@ -79,6 +82,7 @@ langs = ["typescript"] f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [sync_standards] langs = ["typescript"] diff --git a/tests/test_vendor_snapshot_templates.py b/tests/test_vendor_snapshot_templates.py index 643c01d..60a54db 100644 --- a/tests/test_vendor_snapshot_templates.py +++ b/tests/test_vendor_snapshot_templates.py @@ -6,6 +6,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] SCRIPT = ROOT / "scripts" / "playbook.py" +DEFAULT_DEPLOY_ROOT = "docs/standards/playbook" def run_cli(*args): @@ -22,6 +23,7 @@ class VendorSnapshotTemplatesTests(unittest.TestCase): config_body = f""" [playbook] project_root = "{tmp_dir}" +deploy_root = "{DEFAULT_DEPLOY_ROOT}" [vendor] langs = ["tsl"]