csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl): align agent-facing guidance

Browse Source
This commit is contained in:
csh
2026-05-28 19:12:34 +08:00
parent c48354e0cb
commit d8eb418277
63 changed files with 1921 additions and 371 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tsl/reference/catalog/base.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/client.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/compression.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/digest_encoding.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/graphics.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/index.md
+16 -5
View File
@@ -1,13 +1,17 @@
# Function Catalog
这里是 canonical 函数目录。它只回答“函数在哪个模块里”，不承担基础语法教学。
这里是候选函数索引。它只回答“函数名可能在哪个模块里”，不承担基础语法教学，也不证明函数在当前环境可用。
候选名没有进入 verified 函数页前不能当成可调用事实。agent 真正生成代码前，只从 verified 函数页读取参数类型。
## 使用顺序
1. 不知道函数在哪个模块，先看下面的模块目录。
2. 进入模块页后，在页内搜索具体函数名。
3. 如果问题是语法怎么写，回到 [../../syntax/index.md](../../syntax/index.md)。
4. 如果问题是金融场景如何组织，回到 [../../finance/index.md](../../finance/index.md)。
2. 进入模块页后，在页内搜索具体候选函数名。
3. 如果要生成代码，先看 [../verified/index.md](../verified/index.md)，再进入具体函数页；当前核心函数页是 [../verified/core.md](../verified/core.md)。
4. 如果候选函数没有进入 verified 函数页，不要生成调用代码。
5. 如果问题是语法怎么写，回到 [../../syntax/index.md](../../syntax/index.md)。
6. 如果问题是金融场景如何组织，回到 [../../finance/index.md](../../finance/index.md)。
## 模块目录
@@ -27,4 +31,11 @@
## 说明
- 这套目录页由仓库内的函数语料自动整理生成。
- 当前目标是先提供稳定检索层，再逐步补全更细的 canonical 说明。
- catalog 只保留候选函数索引，不写参数矩阵，不写可调用结论。
- 当前目标是先提供稳定检索层，再逐步补全 agent 可直接读取的参数事实。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
docs/tsl/reference/catalog/math.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/platform.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/resource.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/system.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/catalog/third_party.md
+6
View File
@@ -2,6 +2,12 @@
这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
## 候选函数索引说明
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
## 使用方式
- 返回总目录：[catalog/index.md](index.md)
docs/tsl/reference/index.md
+23 -19
View File
@@ -2,33 +2,37 @@
文档类型：检索页
是否可直接用于生成代码：否
是否含已验证可执行示例：否
是否含已验证反例：否
遇到不确定时跳转到：[catalog/index.md](catalog/index.md)、[../syntax/index.md](../syntax/index.md)、[../finance/index.md](../finance/index.md)
这里是函数查阅层，不是默认通读入口。现在这一页本身就是函数总入口，不再要求先跳到额外的中转页。
## 先看这 5 条
reference 的目标是确认每个方法的参数类型，让 agent 写代码时知道该传什么。文档只保留 agent 生成代码需要的函数事实。
- 这里用于函数查找，不用于建立基础语法模型。
- 不要把 reference 当成默认通读入口；如果任务就是查函数，可以直接从这里开始。
- 函数库规模很大，应先走索引，再做定向检索。
- 如果目录和定向检索都找不到函数，不要默认它是 TSL 内建函数；先回语法层、业务层、模块页或项目文档确认来源。
- 如果你还在问“语言怎么写”，先回 [../syntax/index.md](../syntax/index.md)。
## Agent 函数使用规则
- 只从 verified 函数页读取参数类型、返回值和调用约束。
- catalog 只是候选函数索引，不能把 catalog 里的函数名直接当成可调用事实。
- 函数没有进入 verified 函数页时，不要根据函数名猜参数，也不要生成调用代码。
- 函数参数必须按正确类型传入；TSL 本身弱类型，不等于函数参数无类型。
- 如果函数被记录为当前测试环境不支持，不要使用该函数生成代码。
## 检索策略
1. 先看 [catalog/index.md](catalog/index.md) 的模块目录，确定大类。
2. 进入对应模块页，在页内搜索具体函数名。
3. 仍然不确定时，再用 `rg` 对 `docs/tsl/reference/catalog/` 做定向搜索。
4. 如果目录和定向检索都找不到函数，不要发明函数名，也不要默认它是 TSL 内建函数；回 [../syntax/index.md](../syntax/index.md)、[../finance/index.md](../finance/index.md)、[../modules/index.md](../modules/index.md) 或项目文档确认来源。
1. 先看 [catalog/index.md](catalog/index.md) 的模块目录，确定候选大类。
2. 进入对应模块页，在页内搜索具体候选函数名。
3. 先看 [verified/index.md](verified/index.md)，再进入具体 verified 函数页读取参数类型、返回值和调用约束；当前核心函数页是 [verified/core.md](verified/core.md)。
4. 如果候选函数没有进入 verified 函数页，不要生成调用代码。
5. 当前测试环境不支持的方法见 [unavailable_methods.md](unavailable_methods.md)。
6. 如果目录和定向检索都找不到函数，不要发明函数名，也不要默认它是 TSL 内建函数；回 [../syntax/index.md](../syntax/index.md)、[../finance/index.md](../finance/index.md)、[../modules/index.md](../modules/index.md) 或项目文档确认来源。
## 按任务跳转
| 当前任务 | 先读哪里 |
| ---------------- | ------------------------------------------ |
| 查函数库入口 | [catalog/index.md](catalog/index.md) |
| 直接按模块查函数 | [catalog/index.md](catalog/index.md) |
| 回到语法层 | [../syntax/index.md](../syntax/index.md) |
| 回到金融层 | [../finance/index.md](../finance/index.md) |
| 回到模块层 | [../modules/index.md](../modules/index.md) |
| 当前任务 | 先读哪里 |
| ------------------------ | ------------------------------------------------ |
| 查函数库入口 | [catalog/index.md](catalog/index.md) |
| 直接按模块查函数 | [catalog/index.md](catalog/index.md) |
| 查可调用函数参数类型 | [verified/index.md](verified/index.md) |
| 查当前测试环境不支持方法 | [unavailable_methods.md](unavailable_methods.md) |
| 回到语法层 | [../syntax/index.md](../syntax/index.md) |
| 回到金融层 | [../finance/index.md](../finance/index.md) |
| 回到模块层 | [../modules/index.md](../modules/index.md) |
docs/tsl/reference/unavailable_methods.md
+11
View File
@@ -0,0 +1,11 @@
# Reference Unavailable Methods
文档类型：当前测试环境不支持的方法清单
是否可直接用于生成代码：否
遇到不确定时跳转到：[verified/core.md](verified/core.md)、[catalog/index.md](catalog/index.md)
这里只记录方法不存在，或当前测试环境暂不支持的方法。参数类型事实写在 verified 函数页。
## 当前测试环境不支持的方法
暂无已入档记录。
docs/tsl/reference/verified/core.md
+49
View File
@@ -0,0 +1,49 @@
# Verified Core Reference Functions
文档类型：agent 参数事实表
是否可直接用于生成代码：是
遇到不确定时跳转到：[../catalog/index.md](../catalog/index.md)、[../../syntax/index.md](../../syntax/index.md)
本页只保留 agent 生成代码需要的函数事实：签名、接收类型、返回值和调用约束。
## 使用规则
- 只按“接收类型”传参。
- TSL 是弱类型语言，但函数参数不是任意类型。
- catalog 同名函数没有出现在 verified 页时，不要当作可调用事实。
## 函数参数
### `Abs(value)`
用途：返回数值绝对值。
| 参数 | 接收类型 | 返回 | 说明 |
| ------- | -------- | ---- | ---------- |
| `value` | 整数 | 数值 | 返回绝对值 |
| `value` | 实数 | 数值 | 返回绝对值 |
### `ifInt(value)`
用途：判断值当前是否按整数处理，返回 `1` 或 `0`。
| 参数 | 接收类型 | 返回 | 说明 |
| ------- | --------------------------------------- | ---- | ---------------------- |
| `value` | 任意值；已记录整数、实数、字符串、`nil` | 整数 | 整数返回 `1`，否则 `0` |
### `DateToStr(value)`
用途：把日期时间值转成日期字符串。
| 参数 | 接收类型 | 返回 | 说明 |
| ------- | -------- | ------ | ------------------------------ |
| `value` | 日期时间 | 字符串 | 日期时间字面量可写 `20111231T` |
### `Length(value)`
用途：返回字符串或数组长度。
| 参数 | 接收类型 | 返回 | 说明 |
| ------- | -------- | ---- | ------------ |
| `value` | 字符串 | 整数 | 返回字符长度 |
| `value` | 数组 | 整数 | 返回元素个数 |
docs/tsl/reference/verified/index.md
+19
View File
@@ -0,0 +1,19 @@
# Verified Reference Functions
文档类型：agent 参数事实索引
是否可直接用于生成代码：否
遇到不确定时跳转到：[../catalog/index.md](../catalog/index.md)、[../../syntax/index.md](../../syntax/index.md)
本页只负责定位已经整理成参数事实表的函数页。生成调用代码时，进入具体函数页读取签名、接收类型、返回值和调用约束。
## 使用规则
- 只从具体函数页读取接收类型和返回值。
- catalog 里的候选名没有出现在具体函数页时，不要当作可调用事实。
- 不根据函数名猜参数。
## 参数事实页
| 范围 | 页面 | 当前函数 |
| -------- | ------------------ | ------------------------------------- |
| 核心函数 | [core.md](core.md) | `Abs`、`ifInt`、`DateToStr`、`Length` |