♻️ refactor(tsl-api-reference): split lookup workflows and maintenance tooling
This commit is contained in:
@@ -1,157 +1,50 @@
|
||||
---
|
||||
name: tsl-api-reference
|
||||
description: "当编写、修改或审查 TSL 代码时需要确认 builtin、dotnet 或 module API 是否存在及其精确签名、参数、返回值和示例时使用；也用于按自然语言查找天软数据字典中的表、数据源与字段。"
|
||||
description: "当编写、修改或审查 TSL 代码，需要确认 API、class 成员或框架回调是否存在及其精确签名、参数、返回值和示例时使用；也用于按中文业务说法查找天软数据字典中的表、数据源与字段。触发说法包括「argmax 怎么用」「有没有去重函数」「TStringList 有哪些方法」「TSBackTesting 要重写什么」「销售现金比率在哪个表」。不用于 TSL 语法、控制流、语言对象模型，也不用于决定 TSL 如何运行。"
|
||||
---
|
||||
|
||||
# TSL API 参考
|
||||
|
||||
本 skill 仅用于 TSL API 事实：函数/模块名、精确签名、参数、返回值和示例。
|
||||
若需查询 TSL 语法、控制流、变量、对象模型或运行时语言规则，请改用
|
||||
`tsl-syntax-reference` skill。
|
||||
本 skill 只负责可检索的 TSL API、class/framework 契约和天软数据字典事实。
|
||||
语法、控制流、语言对象模型或运行方式问题不属于本 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。
|
||||
- 已知函数或成员名，或只知道 API 行为：读取
|
||||
[`workflows/api-lookup.md`](workflows/api-lookup.md)。
|
||||
- 查询 class 摘要、实现子类、重写回调或处理生命周期：读取
|
||||
[`workflows/class-and-framework.md`](workflows/class-and-framework.md)。
|
||||
- 按中文业务含义查表、数据源或字段：读取
|
||||
[`workflows/dictionary-lookup.md`](workflows/dictionary-lookup.md)。
|
||||
|
||||
列出和查询 class：
|
||||
具体参数、输出字段和退出码以所选脚本当前的 `--help` 为权威。
|
||||
将 `<this-skill-dir>` 替换为包含本 `SKILL.md` 的目录。
|
||||
|
||||
```bash
|
||||
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`
|
||||
或完全限定名消歧，不能选择第一项。
|
||||
- API 名称按索引原样查询和报告。TSL 名称大小写不敏感，但下划线有意义；不得删除
|
||||
下划线或改写成驼峰式。
|
||||
- 不得凭记忆或参照相似语言推断 API 名称、签名、参数、返回值或回调字段。
|
||||
- 同名结果不得默认取第一条；必须按 `scope`、`module`、owner 或完全限定名消歧。
|
||||
- `lookup.py` 的 rc=1 表示 skill 数据缺失、损坏或正文不可达，不表示 API 不存在。
|
||||
|
||||
普通 class 的 `profile_status=not_profiled` 不是错误，只表示它使用索引自动生成的成员
|
||||
视图。框架类的 Profile 只描述 API 协议，不直接生成 TSL 语法；将结果作为
|
||||
Framework Contract Packet 交给 `tsl-syntax-reference` 组合代码结构。
|
||||
## 🔴 CHECKPOINT · 🛑 STOP
|
||||
|
||||
`scaffold_status=resolved` 只表示类级生命周期和成员引用完整，不表示模式相关的回调
|
||||
记录结构已经确定。只要 `contract_status` 不是 `resolved`，就必须停止生成回调字段，
|
||||
按 `diagnostics` 补齐模式和返回 schema 证据。
|
||||
出现任一情况时，停止生成包含该 API 或回调字段的代码，并明确报告缺口：
|
||||
|
||||
维护 Profile 后运行引用校验：
|
||||
- `lookup.py --name` 无匹配；
|
||||
- `lookup.py --kw` 换用更准确的中文关键词后仍无候选；
|
||||
- 同名 API 或 class 无法按 `scope`、`module`、owner 或完全限定名消歧；
|
||||
- `class_lookup.py` 返回 `status: not_found`；
|
||||
- 请求依赖生命周期、配置或回调，但 `profile_status=not_profiled`；
|
||||
- Framework Profile 的 `contract_status` 不是 `resolved`。
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/class_lookup.py --check
|
||||
```
|
||||
rc=1 不进入上述“API 缺失”分支；应先修复或重新安装 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 时不要删除下划线，也不要把名称改写成驼峰式。
|
||||
|
||||
运行随附的查询脚本。将 `<this-skill-dir>` 替换为包含本 `SKILL.md` 的目录。
|
||||
|
||||
- 已知 API 名称：
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/lookup.py --name argmax
|
||||
```
|
||||
|
||||
- 已知 class/unit 成员的完全限定名称：
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/lookup.py --name DemoUnit.Document.Save
|
||||
```
|
||||
|
||||
- 未知名称，但知道其行为或中文关键词：
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/lookup.py --kw 最大值 位置
|
||||
```
|
||||
|
||||
- 只查询一个 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 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 与模块差异。
|
||||
- 查不到就凭记忆或相似语言推断签名。查不到时说明缺口并停止。
|
||||
报告 API 事实时必须包含：索引中的原样名称或 `qualified_name`、`scope`、`module`、
|
||||
由 `lookup.py --name` 正文取得的精确签名，以及对应的 `page#anchor` 来源。
|
||||
关键词候选的 summary 只能用于选候选，不能作为签名事实。
|
||||
|
||||
Reference in New Issue
Block a user