📦 deps(tsl): sync tsl-playbook from a71480a4

Source-Commit: a71480a4ae

skills/tsl-api-reference/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tsl-api-reference
-description: "当编写、修改或审查 TSL 代码时需要确认 builtin、dotnet 或模块 API 是否存在及其精确签名、参数、返回值和示例时使用；也用于只记得函数用途而想不起函数名，或不确定记忆中的 TSL API 名称与参数是否准确时。"
+description: "当编写、修改或审查 TSL 代码时需要确认 builtin、dotnet、third 或模块 API 是否存在及其精确签名、参数、返回值和示例时使用；也用于按自然语言查找天软数据字典中的表、数据源与字段。"
 ---
 
 # TSL API 参考
@@ -9,6 +9,34 @@ description: "当编写、修改或审查 TSL 代码时需要确认 builtin、do
 若需查询 TSL 语法、控制流、变量、对象模型或运行时语言规则，请改用
 `tsl-syntax-reference` skill。
 
+天软数据字典中的表、数据源和字段不是可调用 API，不进入 `function_index.tsv`
+函数问题使用 `lookup.py`，表或字段问题使用 `dictionary_lookup.py`
+
+## 数据字典查询
+
+用户按中文业务含义描述表或字段时，运行独立的字典查询脚本
+
+```bash
+python <this-skill-dir>/scripts/dictionary_lookup.py --query "股票现金流指标销售现金比率"
+```
+
+已知业务范围、表名、数据源名或字段名时使用过滤参数
+
+```bash
+python <this-skill-dir>/scripts/dictionary_lookup.py --query "市值" --scope fund
+python <this-skill-dir>/scripts/dictionary_lookup.py --query "买一量" --table TradeTable
+python <this-skill-dir>/scripts/dictionary_lookup.py --query "9900700" --field 销售现金比率
+```
+
+查询结果包含表或数据源名称、表 ID、字段名称、字段 ID、类型、单位、提取方式、
+访问代码、对应 API 和字典页面
+
+- 标识符匹配不删除下划线
+- 同义词只从 `dictionary_lexicon.json` 中取受控映射
+- `status: ambiguous` 时必须向用户列出候选并要求补充表或数据源范围，不能默认选择第一项
+- `MarketTable` 和 `TradeTable` 是 TS-SQL 数据源，不是函数
+- `status: no_match` 表示字典无匹配，不能改述为 API 的 `not found`
+
 不要凭记忆或参照相似语言推断 API 签名。TSL 名称大小写不敏感，但下划线是有意义的：
 查询或报告 API 时不要删除下划线，也不要把名称改写成驼峰式。
 
@@ -29,12 +57,22 @@ description: "当编写、修改或审查 TSL 代码时需要确认 builtin、do
 - 未知名称，但知道其行为或中文关键词：
 
   ```bash
-  python <this-skill-dir>/scripts/lookup.py --kw 数组 排序
+  python <this-skill-dir>/scripts/lookup.py --kw 最大值 位置
   ```
 
-- 关键词采用 AND 语义；增加关键词可缩小结果范围。
-- 关键词会搜索原有字段及 `qualified_name`、`owner`、`kind`、`binding`、
-  `visibility`；因此可用 `--kw protected method` 等组合缩小成员范围。
+- 只查询一个 scope：
+
+  ```bash
+  python <this-skill-dir>/scripts/lookup.py --scope builtin --name boolToStr
+  python <this-skill-dir>/scripts/lookup.py --scope dotnet --kw argmax
+  python <this-skill-dir>/scripts/lookup.py --scope third --name getOleObject
+  ```
+
+- 关键词采用字面 AND 语义；增加关键词可缩小结果范围。常用同义词由 API 条目的
+  Tags 提供，例如“位置/下标”“列表/数组”“打印/输出”。
+- 关键词会搜索 `name`、`signature`、`tags`、`summary`、`module`、`scope` 及
+  `qualified_name`、`owner`、`kind`、`binding`、`visibility`，并按字段加权稳定排序；
+  因此也可用 `--kw dotnet argmax` 或 `--kw protected method` 缩小范围。
 - 使用 `--limit N` 调整打印的候选行数量，N 必须 >= 1。
 
 精确查询会打印完整的条目正文和来源标记。关键词查询打印候选行；
@@ -52,8 +90,8 @@ method 显示 `function`，类方法显示 `class function`，静态字段与常
 `static field`、`static const`。
 
 同名 API 存在于多个 scope 或模块时（如 `host`、`login`、`port`），`--name`
-会依次打印全部同名条目，每条带自己的来源标记。按当前代码所处的 scope 和模块
-选择条目，不要默认取第一条。
+会依次打印全部同名条目，每条带自己的来源标记。已知 scope 时先用 `--scope`
+过滤；否则按当前代码所处的 scope 和模块选择条目，不要默认取第一条。
 
 查询脚本兼容旧 8 列和新 13 列 `function_index.tsv`。旧 8 列索引仍可查询原有
 function；完全限定名称、owner、kind、binding、visibility 依赖新索引中的扩展列。