feat(tsl-syntax-reference): harden retrieval contracts

Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement.

BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
This commit is contained in:
csh
2026-07-31 10:05:15 +08:00
parent 21e688a436
commit 736d1a8ad7
30 changed files with 1635 additions and 137 deletions
@@ -4,10 +4,14 @@
## 本篇职责
<!-- section-id: syntax-10-001 -->
回答“`setSysParam` / `getSysParam` 怎样用、`sysParams[...]` 是什么、块环境 `with *, values do` / `with **, values do` 怎样写、`#Func() with array(...)` 这种后缀环境调用怎样写,网格调用怎样取回结果,以及全局缓存最小读写规则是什么”。
## 核心规则
<!-- section-id: syntax-10-002 -->
本页示例只说明运行时上下文语法中的调用位置和源码外形。API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对,不能由本页示例反推。
- TSL 有一组运行时系统参数;本页只写通用语法形态。
@@ -33,8 +37,12 @@
## 可直接照写示例
<!-- section-id: syntax-10-003 -->
### `setSysParam` / `getSysParam` / `sysParams[...]` 基础读写
<!-- section-id: syntax-10-004 -->
<!-- tags: 系统参数, 读写运行参数, 环境设置, 全局设置项 -->
直接设置和读取系统参数:
@@ -78,6 +86,8 @@ writeLn(getSysParam("a"));
### 块环境 `with *`
<!-- section-id: syntax-10-005 -->
<!-- tags: 临时改参数, 局部生效, 一段代码内有效, 块内覆盖 -->
代码块身份:可直接照写示例
@@ -131,6 +141,8 @@ end
### 块环境 `with **`
<!-- section-id: syntax-10-006 -->
<!-- tags: 嵌套覆盖, 深层块环境, 多层 with -->
代码块身份:可直接照写示例
@@ -158,6 +170,8 @@ writeLn(getSysParam("b"));
### 后缀 `with array(...)`:网格调用的临时覆盖
<!-- section-id: syntax-10-007 -->
<!-- tags: 调用时临时改参数, 单次覆盖, 调用完恢复 -->
`#Func(...) with array(...)` 在一次网格调用里临时覆盖系统参数,调用结束后恢复外层原值。下面用一个 `TestDo.tsf` 演示覆盖边界:
@@ -212,6 +226,8 @@ writeLn(getSysParam("b") = nil);
### `#` 网格调用与 `dupvalue`
<!-- section-id: syntax-10-008 -->
<!-- tags: 网格调用, 分布式执行, 井号调用, 取回结果 -->
网格调用函数:
@@ -263,6 +279,8 @@ array(2,4,6,8,10)
### 网格调用的 `timeout`
<!-- section-id: syntax-10-009 -->
<!-- tags: 超时, 限制执行时间, 多久不返回就断 -->
代码块身份:可直接照写示例
@@ -283,6 +301,8 @@ end;
### `setGlobalCache`、`getGlobalCache` 与 `ifCache`
<!-- section-id: syntax-10-010 -->
<!-- tags: 全局缓存, 缓存数据, 跨脚本共享, 存起来下次用 -->
代码块身份:可直接照写示例
@@ -310,6 +330,8 @@ writeLn(cached_data[0], ',', cached_data[1], ',', cached_data[2]);
### `checkGlobalCacheExpired`
<!-- section-id: syntax-10-011 -->
<!-- tags: 缓存过期, 缓存失效判断, 什么时候要重算 -->
代码块身份:可直接照写示例
@@ -329,6 +351,8 @@ writeLn(checkGlobalCacheExpired(cache_ref));
### 缓存值本地写入后会实例化
<!-- section-id: syntax-10-012 -->
<!-- tags: 改缓存内容, 缓存副本, 写回不影响原缓存 -->
代码块身份:可直接照写示例
@@ -350,6 +374,8 @@ writeLn(local_copy[0], ',', local_copy[1], ',', local_copy[2]);
### 全局缓存参与 `select`
<!-- section-id: syntax-10-013 -->
<!-- tags: 对缓存做查询, 缓存当表查 -->
代码块身份:可直接照写示例
@@ -373,6 +399,8 @@ writeLn(query_result[0][0], ',', query_result[0][1], ';', query_result[1][0], ',
## 本页不生成的范围
<!-- section-id: syntax-10-014 -->
- 网格超时触发错误时的完整边界
- `getGlobalCacheInfo``listGlobalCache``listGlobalCacheRemoved`
- 初始化 TSL、监控线程、回收策略与兼容旧系统方案
@@ -383,6 +411,8 @@ writeLn(query_result[0][0], ',', query_result[0][1], ';', query_result[1][0], ',
## 默认生成模板
<!-- section-id: syntax-10-015 -->
最小运行时环境入口的默认骨架如下:
代码块身份:可直接照写示例
@@ -409,6 +439,8 @@ end;
## 禁止项
<!-- section-id: syntax-10-016 -->
- 把系统参数页直接写成金融函数页。
-`#Func() with array(...)` 误判成也能直接套在本地函数 `Demo()` 后面。
-`with *` 误判成会自动恢复外层系统参数。