playbook/skills/tsl-api-reference/SKILL.md

name, description

name	description
tsl-api-reference	当编写、修改或审查 TSL 代码时需要确认 builtin、dotnet 或 module API 是否存在及其精确签名、参数、返回值和示例时使用；也用于按自然语言查找天软数据字典中的表、数据源与字段。

TSL API 参考

本 skill 仅用于 TSL API 事实：函数/模块名、精确签名、参数、返回值和示例。 若需查询 TSL 语法、控制流、变量、对象模型或运行时语言规则，请改用 tsl-syntax-reference skill。

查询路由

先判断用户请求是普通 API、class，还是带生命周期的框架类工作流：

• 普通函数、单个成员或数据字典问题走现有 lookup.py / dictionary_lookup.py。
• 查询或使用任意 class 时，先用 class_lookup.py 取回紧凑的类摘要和成员分类； 需要某个成员正文时，再运行 lookup.py --name 精确查询。
• class_lookup.py 自动覆盖 function_index.tsv 中的全部 class，不要求每个普通对象类 都维护人工脚手架。
• 用户要实现框架子类、重写回调或组合一组有生命周期的 class API 时，类级查询会叠加 framework_index.json 中证据化的 Framework Profile，返回生命周期、必要回调、 状态、执行入口和结果查询。
• 不得因为查询目标是 class 就推断它是框架；普通对象、服务类和数据类只使用自动生成的 类成员视图。只有 kind=framework 且具有证据化生命周期的类才加载人工 Profile。

列出和查询 class：

python <this-skill-dir>/scripts/class_lookup.py --list
python <this-skill-dir>/scripts/class_lookup.py --class TStringList
python <this-skill-dir>/scripts/class_lookup.py --class TSBackTesting
python <this-skill-dir>/scripts/class_lookup.py \
  --class TSBackTesting --config fGroupType=1 --format json

同名 class 出现在多个 scope 或模块时，状态为 ambiguous；使用 --scope、--module 或完全限定名消歧，不能选择第一项。

普通 class 的 profile_status=not_profiled 不是错误，只表示它使用索引自动生成的成员 视图。框架类的 Profile 只描述 API 协议，不直接生成 TSL 语法；将结果作为 Framework Contract Packet 交给 tsl-syntax-reference 组合代码结构。

scaffold_status=resolved 只表示类级生命周期和成员引用完整，不表示模式相关的回调 记录结构已经确定。只要 contract_status 不是 resolved，就必须停止生成回调字段， 按 diagnostics 补齐模式和返回 schema 证据。

维护 Profile 后运行引用校验：

python <this-skill-dir>/scripts/class_lookup.py --check

天软数据字典中的表、数据源和字段不是可调用 API，不进入 function_index.tsv 函数问题使用 lookup.py，表或字段问题使用 dictionary_lookup.py

数据字典查询

用户按中文业务含义描述表或字段时，运行独立的字典查询脚本

python <this-skill-dir>/scripts/dictionary_lookup.py --query "股票现金流指标销售现金比率"

已知业务范围、表名、数据源名或字段名时使用过滤参数

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 时不要删除下划线，也不要把名称改写成驼峰式。

运行随附的查询脚本。将 <this-skill-dir> 替换为包含本 SKILL.md 的目录。

• 已知 API 名称：

  python <this-skill-dir>/scripts/lookup.py --name argmax
  

• 已知 class/unit 成员的完全限定名称：

  python <this-skill-dir>/scripts/lookup.py --name DemoUnit.Document.Save
  

• 未知名称，但知道其行为或中文关键词：

  python <this-skill-dir>/scripts/lookup.py --kw 最大值 位置
  

• 只查询一个 scope：

  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 module --name bondAccruedInterest
  

• 关键词采用字面 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。

精确查询会打印完整的条目正文和来源标记。关键词查询打印候选行； 选定候选项后，再用 --name 重新执行精确查询。

--name 对简单名称和完全限定名称做大小写不敏感的精确匹配。查询简单成员名会 返回所有 owner 下的同名 API；查询 Unit.Class.Member 等完全限定名称可限定所属 class/unit。重载共享 qualified_name，精确查询会返回该名称的全部重载。

混合页面中的精确查询仍按唯一 page#anchor 定位，只截取目标 H2 或成员子树。 每个 H2 的声明类型独立，不使用全局页面类型。

关键词候选优先显示 qualified_name，并根据 kind/binding 显示声明术语：实例 method 显示 function，类方法显示 class function，静态字段与常量分别显示 static field、static const。

同名 API 存在于多个 scope 或模块时（如 host、login、port），--name 会依次打印全部同名条目，每条带自己的来源标记。已知 scope 时先用 --scope 过滤；否则按当前代码所处的 scope 和模块选择条目，不要默认取第一条。

查询脚本兼容旧 8 列和新 13 列 function_index.tsv。旧 8 列索引仍可查询原有 function；完全限定名称、owner、kind、binding、visibility 依赖新索引中的扩展列。

退出码

退出码	含义	处理方式
0	查询完成，含"查无此 API"和关键词零命中	读取输出；无匹配时换中文关键词重试
1	随附数据缺失或为空	重新安装本 skill，或用 --tsv PATH 指向可用索引
2	参数不合法	按提示修正参数后重跑

rc=1 表示 skill 数据本身有问题，不表示该 API 不存在；此时不要据此断言 API 缺失。

常见错误

• 删掉下划线或改写成驼峰式后查询，导致误判 API 不存在。名称按原样查。
• 把关键词查询的 summary 当作签名事实。summary 只用于挑候选，签名必须由 --name 的条目正文提供。
• 多条同名结果里随手取第一条，忽略 scope 与模块差异。
• 查不到就凭记忆或相似语言推断签名。查不到时说明缺口并停止。