📝 docs(tsl): restructure agent-facing reference

Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation. Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
2026-06-09 17:24:30 +08:00
parent 9c194170a1
commit 540b3c0a1b
192 changed files with 32929 additions and 13533 deletions
@@ -1,40 +1,99 @@
 # 第三方交互函数

-这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。
+文档类型：函数事实页
+是否可直接用于生成代码：是；本页函数条目均包含参数表
+遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md)

-## 候选函数索引说明
-
- 本页是候选函数索引，只说明函数名被归入当前模块。
- 候选名没有进入 verified 函数页前不能当成可调用事实。
- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。
-
-## 使用方式
-
- 返回总目录：[catalog/index.md](index.md)
- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md)
- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md)
+这一页描述第三方库与外部程序交互能力。生成函数调用时，只按函数条目中的参数表传参。

 ## 模块范围

 - 说明：第三方库与外部程序交互能力
- 主题数：3
- 函数数：8
+- 函数事实数：7

-## 主题目录
+## Python支持函数

-### Python支持函数
+### `pyRun(code)`

- `PyRun`
- `PyCall`
- `PyError`
+用途：执行 Python 代码片段。

-### R支持函数
+参数个数：1
+返回值：处理后的结果值

- `RRelease`
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明              |
+| -------- | ------ | ---- | -------- | ----------------- |
+| 1        | `code` | 是   | 字符串   | Python 代码字符串 |

-### Html
+### `pyCall(module_or_mode, function_or_module[, function_or_arg][, arg_values])`

- `TextToHtml`
- `TextToURL`
- `HtmlToText`
- `URLToText`
+用途：Python支持函数相关函数。
+
+参数个数：2 到 4
+返回值：处理后的结果值
+
+| 参数位置 | 参数名               | 必填 | 接收类型             | 说明                                                                                     |
+| -------- | -------------------- | ---- | -------------------- | ---------------------------------------------------------------------------------------- |
+| 1        | `module_or_mode`     | 是   | 字符串/整数          | Python 模块名；也可传整数模式，例如源文档示例中的 `2`                                    |
+| 2        | `function_or_module` | 是   | 字符串               | 当第 1 参数是模块名时为 Python 函数名；当第 1 参数是模式时为 Python 模块名               |
+| 3        | `function_or_arg`    | 否   | 字符串/任意值        | 当第 1 参数是模块名时为传给 Python 函数的第一个参数；当第 1 参数是模式时为 Python 函数名 |
+| 4        | `arg_values`         | 否   | 任意值/数组/命名参数 | 继续传给 Python 函数的位置参数、数组参数或命名参数                                       |
+
+### `pyError()`
+
+用途：获取最近一次 Python 调用错误信息。
+
+参数个数：0
+返回值：字符串
+
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
+| -------- | ------ | ---- | -------- | ---- |
+
+## Html 和 URL 文本转换函数
+
+### `textToHtml(text)`
+
+用途：将普通文本转换为 HTML 文本；空格会转换为 `&nbsp;`。
+
+适用环境：Windows TSL 解释器。
+参数个数：1
+返回值：字符串
+
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明             |
+| -------- | ------ | ---- | -------- | ---------------- |
+| 1        | `text` | 是   | 字符串   | 待转换的普通文本 |
+
+### `textToURL(text)`
+
+用途：将普通文本转换为 URL 编码文本。
+
+适用环境：Windows TSL 解释器。
+参数个数：1
+返回值：字符串
+
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明             |
+| -------- | ------ | ---- | -------- | ---------------- |
+| 1        | `text` | 是   | 字符串   | 待转换的普通文本 |
+
+### `htmlToText(text)`
+
+用途：将 HTML 文本转换为普通文本；`&nbsp;` 会转换为空格。
+
+适用环境：Windows TSL 解释器。
+参数个数：1
+返回值：字符串
+
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明                                      |
+| -------- | ------ | ---- | -------- | ----------------------------------------- |
+| 1        | `text` | 是   | 字符串   | 待转换的 HTML 文本；`&#160;` 不按空格转换 |
+
+### `urlToText(text)`
+
+用途：将 URL 编码文本转换为普通文本。
+
+适用环境：Windows TSL 解释器。
+参数个数：1
+返回值：字符串
+
+| 参数位置 | 参数名 | 必填 | 接收类型 | 说明                  |
+| -------- | ------ | ---- | -------- | --------------------- |
+| 1        | `text` | 是   | 字符串   | 待转换的 URL 编码文本 |