# TSL 运行时上下文、服务与全局缓存

文档类型：语法主线
是否可直接用于生成代码：仅部分
是否含可直接照写示例：是
是否含不可照写反例：是
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[14_ts_sql.md](14_ts_sql.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)

这一篇只处理运行时环境参数、块环境 `with` 语句、`with` 后缀、`#` 网格调用、`timeout` 后缀、`dupvalue(...)` 和全局缓存，不处理任何金融业务语义。

## 本篇职责

回答“`setSysParam` / `getSysParam` 怎样用、`sysParams[...]` 是什么、块环境 `with *, values do` / `with **, values do` 怎样写、`#Func() with array(...)` 这种后缀环境调用怎样写，网格调用怎样取回结果，以及全局缓存最小读写规则是什么”。

## 智能体运行时上下文判断流程

1. 先判断要操作系统参数、运行时上下文对象、块环境 `with` 语句、`with` 后缀调用、`#` 网格调用、`timeout` 后缀，还是全局缓存函数。
2. 系统参数优先用本页明确的 `setSysParam` / `getSysParam` / `sysParams[...]` 形态。
3. `#Func() with array(...)` 只作为运行时环境调用写法，不要套到普通本地函数。
4. 网格调用返回的不是最终值；需要最终结果时继续写 `dupvalue(...)`。
5. 全局缓存读写要成对出现，并明确键和值的生命周期。
6. 普通函数调用回到 [05_functions_and_calls.md](05_functions_and_calls.md)，不要把运行时服务写成普通语法糖；缓存值参与 `select` 时，查询语法仍回到 [14_ts_sql.md](14_ts_sql.md)。
7. 如果问题是内置运行时对象本身，转到 [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)。
8. 本地函数后缀 `with` 属于反例时不要照写。
9. 没有对应代码块时不要发明运行时上下文/运行时服务/全局缓存写法。

## 核心规则

- TSL 有一组运行时系统参数；本页只写通用语法形态。
- `setSysParam(key, value)` 和 `getSysParam(key)` 可以直接用字符串键。
- `sysParams[key]` 可以直接读写这些运行时参数。
- 块环境语句可写成 `with *, sys_param_values do begin ... end` 或 `with **, sys_param_values do begin ... end`。
- `with *` 会把提供的系统参数合并进当前运行时上下文；不要依赖它在块结束后自动恢复外层值。
- `with **` 会用提供的系统参数建立隔离块环境；块结束后恢复外层系统参数。
- 后缀 `with` 形式写在函数文件调用后面：`#Func() with array(...)`。
- `with array(...)` 只在该次调用里临时覆盖对应键，调用结束后会恢复外部原值。
- 如果外部原值本来不存在，`with array(...)` 调用结束后，对应键会恢复成 `nil`。
- 不要把上面的后缀 `with` 直接泛化成“任何本地函数调用后面都能接 `with array(...)`”；本地函数后缀 `with` 属于反例。
- 本页只收通用键的例子；像 `pn_stock()`、`pn_date()` 这类金融上下文参数，统一到 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) 查函数事实。
- 网格调用的最小写法是 `r := #Func(args);`。
- 网格调用返回的不是最终值；用 `dupvalue(r)` 取回结果。
- `timeout N` 后缀可直接接在网格调用后面。
- 全局缓存函数的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)；本页只保留缓存引用的运行时行为示例。
- 写入和读取全局缓存成功时返回 `1`。
- 从全局缓存取出的值，`ifCache(v)` 会返回 `1`。
- 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 `ifCache(v)` 返回 `0`。
- `checkGlobalCacheExpired(v)` 对同名缓存的最新引用返回 `0`；同名缓存被重置后，旧引用会变成过期状态并返回 `1`。
- 全局缓存取出的值可以直接参与 `select`。

## 可直接照写示例

直接设置和读取系统参数：

代码块身份：可直接照写示例

```tsl
setSysParam("a", 123);
setSysParam("b", "XYZ");
writeLn(getSysParam("a"));
writeLn(getSysParam("b"));
```

结果说明：

- 依次输出 `123`、`XYZ`

代码块身份：输出片段

```text
123
XYZ
```

`sysParams[...]` 直接读写：

代码块身份：可直接照写示例

```tsl
sysParams["a"] := 321;
sysParams["b"] := "QQ";
writeLn(sysParams["a"]);
writeLn(sysParams["b"]);
writeLn(getSysParam("a"));
```

结果说明：

- 依次输出 `321`、`QQ`、`321`
- 说明 `sysParams[...]` 和 `getSysParam(...)` / `setSysParam(...)` 指向的是同一组运行时环境参数

### 块环境 `with *`

代码块身份：可直接照写示例

```tsl
setSysParam("a", 1);
sys_param_values := array("a": 2, "b": 3);

with *, sys_param_values do
begin
    writeLn(getSysParam("a"));
    writeLn(getSysParam("b"));
end

writeLn(getSysParam("a"));
writeLn(getSysParam("b"));
```

结果说明：

- 块内输出 `2`、`3`
- 块后输出 `2`、`3`
- 说明 `with *` 会把传入键合并进当前系统参数上下文；不要把它当成自动恢复外层值的隔离块

### 块环境 `with **`

代码块身份：可直接照写示例

```tsl
setSysParam("a", 1);
setSysParam("b", 9);
sys_param_values := array("b": 4);

with **, sys_param_values do
begin
    writeLn(getSysParam("a") = nil);
    writeLn(getSysParam("b"));
end

writeLn(getSysParam("a"));
writeLn(getSysParam("b"));
```

结果说明：

- 块内输出 `1`、`4`
- 块后输出 `1`、`9`
- 说明 `with **` 不继承未传入的外层系统参数，并且块结束后恢复外层系统参数

沿用同一个 `TestDo.tsf`，看 `with array(...)` 的覆盖边界：

代码块身份：配置片段 / 概念骨架
代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。

```text
// TestDo.tsf
function TestDo();
begin
    return array(getSysParam("a"), getSysParam("b"));
end;

// main.tsl
setSysParam("a", 7);
setSysParam("b", 8);
r := #TestDo() with array("a": 101, "b": 202);
writeLn(r[0]);
writeLn(r[1]);
writeLn(getSysParam("a"));
writeLn(getSysParam("b"));
```

结果说明：

- `r[0]` 输出 `101`
- `r[1]` 输出 `202`
- 调用结束后，外层 `getSysParam("a")` 输出 `7`
- 调用结束后，外层 `getSysParam("b")` 输出 `8`
- 说明 `with array(...)` 是“只在该次调用里临时覆盖，再恢复外部原值”

沿用上一个 `TestDo.tsf`，只把 `main.tsl` 改成下面这样：

代码块身份：配置片段 / 概念骨架
代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。

```text
// main.tsl

r := #TestDo() with array("a": 101, "b": 202);
writeLn(r[0]);
writeLn(r[1]);
writeLn(getSysParam("a") = nil);
writeLn(getSysParam("b") = nil);
```

结果说明：

- 依次输出 `101`、`202`、`1`、`1`
- 说明外层原值不存在时，调用后不是“泄露”成 `101` / `202`，而是恢复成 `nil`

### `#` 网格调用与 `dupvalue`

代码块身份：可直接照写示例

```tsl
writeLn(dupvalue(#AddOne(5)));

function AddOne(v);
begin
    return v + 1;
end;
```

结果说明：

- `#AddOne(5)` 可以执行
- `dupvalue(r)` 返回最终结果 `6`

代码块身份：输出片段

```text
6
```

### 网格调用的 `timeout`

代码块身份：可直接照写示例

```tsl
writeLn(dupvalue(#AddOne(5) timeout 3000));

function AddOne(v);
begin
    return v + 1;
end;
```

结果说明：

- `timeout 3000` 这种后缀写法可以通过并正常执行
- 上例输出 `6`

### `setGlobalCache`、`getGlobalCache` 与 `ifCache`

代码块身份：可直接照写示例

```tsl
v1 := array(1, 2, 3);
writeLn(setGlobalCache("PB_TEST_GC_BASIC", v1));
writeLn(getGlobalCache("PB_TEST_GC_BASIC", v2));
writeLn(ifCache(v2));
writeLn(length(v2));
writeLn(v2[0], ',', v2[1], ',', v2[2]);
```

结果说明：

- `setGlobalCache("PB_TEST_GC_BASIC", v1)` 返回 `1`
- `getGlobalCache("PB_TEST_GC_BASIC", v2)` 返回 `1`
- 取出的 `v2` 上 `ifCache(v2)` 返回 `1`
- `v2` 长度是 `3`，内容是 `1,2,3`

### `checkGlobalCacheExpired`

代码块身份：可直接照写示例

```tsl
setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3));
getGlobalCache("PB_TEST_GC_EXPIRE", v);
writeLn(checkGlobalCacheExpired(v));
setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3, 4));
writeLn(checkGlobalCacheExpired(v));
```

结果说明：

- 刚取出的缓存引用上，`checkGlobalCacheExpired(v)` 返回 `0`
- 同名缓存被重新设置后，旧引用上的 `checkGlobalCacheExpired(v)` 返回 `1`

### 写入后会实例化

代码块身份：可直接照写示例

```tsl
setGlobalCache("PB_TEST_GC_DETACH", array(1, 2, 3));
getGlobalCache("PB_TEST_GC_DETACH", v);
writeLn(ifCache(v));
v[0] := 100;
writeLn(ifCache(v));
writeLn(v[0], ',', v[1], ',', v[2]);
```

结果说明：

- 刚取出时 `ifCache(v)` 返回 `1`
- 对 `v[0]` 赋值后，`ifCache(v)` 立即返回 `0`
- 写入后的本地值内容是 `100,2,3`

### 全局缓存参与 `select`

代码块身份：可直接照写示例

```tsl
src := array((1, 2), (3, 4), (2, 1));
setGlobalCache("PB_TEST_GC_SELECT", src);
getGlobalCache("PB_TEST_GC_SELECT", v);
q := select * from v order by [0] desc end;
writeLn(dataType(q));
writeLn(mrows(q));
writeLn(q[0][0], ',', q[0][1], ';', q[1][0], ',', q[1][1], ';', q[2][0], ',', q[2][1]);
```

结果说明：

- 对缓存值做 `select` 可以正常执行
- 返回结果的 `dataType` 是 `5`
- 行数是 `3`
- 排序后内容依次是 `(3,4)`、`(2,1)`、`(1,2)`

## 本页不生成的范围

- 网格超时触发错误时的完整边界
- `getGlobalCacheInfo`、`listGlobalCache`、`listGlobalCacheRemoved`
- 初始化 TSL、监控线程、回收策略与兼容旧系统方案
- `with [S => ..., T => ...] do` 块语句
- `{$include ...}` 包含文件指令

这些名称只作为边界提示，不作为本页可生成模板。

## 默认生成模板

最小运行时环境入口的默认骨架如下：

代码块身份：可直接照写示例

```tsl
setSysParam("a", 1);
writeLn(getSysParam("a"));
```

需要网格调用结果时，优先从下面这个模板起步：

代码块身份：可直接照写示例

```tsl
writeLn(dupvalue(#AddOne(5)));

function AddOne(v);
begin
    return v + 1;
end;
```

需要缓存时，从 `setGlobalCache` / `getGlobalCache` 那一节选择模板。

## 禁止项

- 把系统参数页直接写成金融函数页。
- 把 `#Func() with array(...)` 误判成也能直接套在本地函数 `Demo()` 后面。
- 把 `with *` 误判成会自动恢复外层系统参数。
- 以为 `with array(...)` 改的是全局永久值，不会恢复外层原环境。
- 把网格句柄直接当最终值用，而不做 `dupvalue(...)`。
- 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。
- 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。
- `r := #Func(args);` 保存的是网格调用句柄；需要最终结果时继续写 `dupvalue(r)`。

代码块身份：反例 / 不可照写

```text
r := Demo() with array("a": 11);

function Demo();
begin
    return getSysParam("a");
end;
```

上面这种“本地函数后缀 `with`”写法不作为可写事实；常见报错是 `Statement missing terminator`，随后出现 `function compile error`。