TSL API 数据维护

本文档面向本仓库维护者，不是安装后 API skill 的运行说明。命令均从仓库根目录执行。

维护 API 页面和索引

按 STANDARD.md 修改或生成 skills/tsl-api-reference/references/codegen/ 下的页面。
对修改过的页面运行 lint；确认页面中的每个 page#anchor 都能定位。

重建并检查统一索引：

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

用 lookup.py --name 和 class_lookup.py --class 做一次精确查询，确认名称、归属、成员和来源没有漂移。

维护 class：先判断是否真的需要 Framework Profile

function_index.tsv 中 kind=class 的每个 class 都会自动获得成员视图。普通 class 没有 Framework Profile 是正常且完整的状态，不要为了让它出现在列表里创建空 profile：

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 证据，并通过：

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，这不是错误：

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 目录：

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 中的真实示例做查询检查。

完成检查

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 test/integration/check_doc_links.py

3.3 KiB Raw Blame History