118 lines
5.0 KiB
Markdown
118 lines
5.0 KiB
Markdown
# TSL API 数据维护
|
||
|
||
本文档面向本仓库维护者，不是安装后 API skill 的运行说明。命令均从仓库根目录执行。
|
||
|
||
## 维护 API 页面和索引
|
||
|
||
1. 按 [`STANDARD.md`](STANDARD.md) 修改或生成
|
||
`skills/tsl-api-reference/references/codegen/` 下的页面。
|
||
2. 对修改过的页面运行 lint；确认页面中的每个 `page#anchor` 都能定位。
|
||
3. 重建并检查统一索引：
|
||
|
||
```bash
|
||
python tools/tsl-codegen/scripts/build_index.py \
|
||
--skill-dir skills/tsl-api-reference
|
||
python tools/tsl-codegen/scripts/build_index.py \
|
||
--skill-dir skills/tsl-api-reference --check
|
||
```
|
||
|
||
4. 用 `lookup.py --name` 和 `class_lookup.py --class` 做一次精确查询，确认名称、归属、
|
||
成员和来源没有漂移。
|
||
|
||
## 维护 class：先判断是否真的需要 Framework Profile
|
||
|
||
`function_index.tsv` 中 `kind=class` 的每个 class 都会自动获得成员视图。普通 class 没有
|
||
Framework Profile 是正常且完整的状态，不要为了让它出现在列表里创建空 profile：
|
||
|
||
```bash
|
||
python skills/tsl-api-reference/scripts/class_lookup.py \
|
||
--class TStringList --include-members --format json
|
||
```
|
||
|
||
看到 `profile_status=not_profiled` 时，继续维护 class 页面、成员正文和索引即可。配置、
|
||
生命周期、回调或执行阶段不能从普通 class 成员列表臆造出来。
|
||
|
||
只有在参考页面提供了可核验的生命周期协议，并且 class 确实需要配置字段、回调、状态、
|
||
执行入口或结果查询时，才在
|
||
`skills/tsl-api-reference/data/framework_index.json` 增加 `kind=framework` 的条目。
|
||
Profile 必须为每个引用提供对应的 `page#anchor` 证据，并通过：
|
||
|
||
```bash
|
||
python skills/tsl-api-reference/scripts/class_lookup.py --check
|
||
```
|
||
|
||
如果证据不足，保留 `profile_status=not_profiled`，不要用猜测补齐 framework 生命周期。
|
||
Profile 的 `contract_status` 不是 `resolved` 时，也不能生成依赖未证实回调字段的代码。
|
||
|
||
### 用户或临时索引中的 class
|
||
|
||
维护自定义 `function_index.tsv` 时，可直接查询普通 class；只传 `--tsv` 不加载任何
|
||
curated Framework Profile，这不是错误：
|
||
|
||
```bash
|
||
python <skill-dir>/scripts/class_lookup.py \
|
||
--tsv <index-root>/data/function_index.tsv \
|
||
--class MyClass --include-members --format json
|
||
```
|
||
|
||
若确实维护了自定义 profile，显式传入 `--profiles <path>`，再运行 `--check` 验证引用。
|
||
|
||
## 维护数据字典快照
|
||
|
||
字典生成器属于本工具包，位于 `tools/tsl-codegen/scripts/build_dictionary.py`，不随
|
||
`tsl-api-reference` skill 安装。它依赖 `beautifulsoup4`，并要求导出的原始 HTML 目录：
|
||
|
||
```bash
|
||
python -m pip install beautifulsoup4
|
||
python tools/tsl-codegen/scripts/build_dictionary.py \
|
||
--source-root <exported-html-dir> \
|
||
--output-root skills/tsl-api-reference/references/data_dictionary \
|
||
--index skills/tsl-api-reference/data/dictionary_index.tsv \
|
||
--lexicon skills/tsl-api-reference/data/dictionary_lexicon.json
|
||
```
|
||
|
||
生成完成后，用 `dictionary_lookup.py --help` 中的真实示例做查询检查。
|
||
|
||
## 维护参数取值域
|
||
|
||
`skills/tsl-api-reference/data/value_domains.json` 是 API 参数取值域的检索数据，供
|
||
`lookup.py` 和 `dictionary_lookup.py` 共同读取。它不改变 `function_index.tsv` 的 API 元数据
|
||
职责，也不向 `dictionary_index.tsv` 增加 table/source/field 之外的 kind。
|
||
|
||
以下内容进入参数取值域：
|
||
|
||
- 由外部目录维护、需要跨 API 查询的版本化代码，如分类属性代码；
|
||
- 多个 API 参数共享的封闭枚举；只属于单个 API 的枚举仍留在该 API 页面；
|
||
- 已有正式文档但不构成封闭枚举的特殊字面值，使用 `catalog`；
|
||
- 运行时才完整的系统或用户目录，如市场板块名称；
|
||
- 多个 API 共享的特殊选择器或值模式，如分类节点的 `.N` 后缀。
|
||
|
||
单个 API 自带的封闭枚举仍写在 codegen 录入数据的 `params[].values` 中，由生成器渲染为
|
||
参数取值段，不在两个位置重复维护。
|
||
|
||
维护规则：
|
||
|
||
1. FAQ 或帮助页逐条人工核对，不用脚本从语料批量筛选后直接入库。
|
||
2. 每个值记录原样值、名称、来源和适用的 API 参数；版本化目录按需记录父级、层级、
|
||
有效期及关联表。
|
||
3. `runtime_catalog` 必须为 `complete: false`，并提供系统/用户运行时解析器；静态值只能
|
||
作为已核实样例，不能宣称是完整目录。
|
||
4. 分类名称映射为当前板块名但本地证据不足时，关系标记为 `runtime_required`，由
|
||
`getBkList2` 或 `getUserBkList2` 核验后再用于代码。
|
||
5. 修改后运行参数域 CLI 回归和安装测试：
|
||
|
||
```bash
|
||
python -m unittest tools.tsl-codegen.tests.test_value_domains
|
||
python -m unittest test.test_playbook
|
||
```
|
||
|
||
## 完成检查
|
||
|
||
```bash
|
||
python skills/tsl-api-reference/scripts/class_lookup.py --check
|
||
python tools/tsl-codegen/scripts/build_index.py \
|
||
--skill-dir skills/tsl-api-reference --check
|
||
python -m unittest tools.tsl-codegen.tests.test_value_domains
|
||
python test/integration/check_doc_links.py
|
||
```
|