♻️ refactor(tsl-api-reference): split lookup workflows and maintenance tooling

2026-08-20 17:47:48 +08:00
parent 9b95bf2682
commit cd0405d64b
18 changed files with 707 additions and 374 deletions
@@ -0,0 +1,83 @@
+# 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` 中的真实示例做查询检查。
+
+## 完成检查
+
+```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 test/integration/check_doc_links.py
+```