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

skills/tsl-api-reference/scripts/class_lookup.py

@@ -16,6 +16,43 @@ from framework_lookup import (
 from lookup import DEFAULT_TSV, codegen_root_for_tsv, load_rows, normalize
 
 
+HELP_EPILOG = """\
+查询顺序：
+  1. 先按 class 取类摘要或 Framework Profile
+     class_lookup.py --class TStringList
+     class_lookup.py --class TSBackTesting --format json
+  2. 需要成员正文时，再按返回的 qualified_name 调用 lookup.py --name
+
+输出状态：
+  status            resolved、not_found 或 ambiguous
+  profile_status    resolved 表示有 Framework Profile；not_profiled 表示普通 class
+  scaffold_status   生命周期和成员引用是否完整，仅在有 Profile 时输出
+  contract_status   回调字段契约是否完整；非 resolved 时不得生成回调字段
+  diagnostics       消歧、配置或契约缺口及下一步动作
+
+--check 校验全部 Framework Profile 对 class、成员正文和证据的引用。
+使用自定义 --tsv 时默认不加载 Framework Profile；普通 class 仍可正常查询。若该索引
+另有 curated Profile，必须同时显式传入 --profiles。
+
+退出码：
+  0  查询或校验完成；not_found、ambiguous 通过输出状态表达
+  1  function/framework 索引缺失、格式错误、为空或引用校验失败
+  2  参数不合法
+"""
+
+
+def empty_profile_index():
+    return {"schema_version": 1, "frameworks": []}
+
+
+def profile_path_for(args):
+    if args.profiles:
+        return Path(args.profiles)
+    if args.tsv:
+        return None
+    return DEFAULT_INDEX
+
+
 def class_rows(rows):
     return [row for row in rows if row.get("kind") == "class"]
 
@@ -232,24 +269,32 @@ def main(argv=None):
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
     parser = argparse.ArgumentParser(
-        description="Query indexed TSL classes and curated framework profiles.",
+        description="查询 TSL class 摘要及其证据化的 Framework Profile。",
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         allow_abbrev=False,
     )
     action = parser.add_mutually_exclusive_group(required=True)
-    action.add_argument("--class", dest="class_name", help="exact class name")
-    action.add_argument("--list", action="store_true", help="list indexed classes")
-    action.add_argument("--check", action="store_true", help="validate framework profiles")
-    parser.add_argument("--scope", help="filter class scope")
-    parser.add_argument("--module", help="filter class module")
+    action.add_argument("--class", dest="class_name", help="精确 class 名或完全限定名")
+    action.add_argument("--list", action="store_true", help="列出索引中的 class")
+    action.add_argument("--check", action="store_true", help="校验全部 Framework Profile 引用")
+    parser.add_argument("--scope", help="按 class scope 过滤")
+    parser.add_argument("--module", help="按 class module 过滤")
     parser.add_argument(
-        "--config", action="append", default=[], metavar="KEY=VALUE", help="raw config"
+        "--config",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="传入原始框架配置，可重复",
     )
     parser.add_argument(
-        "--include-members", action="store_true", help="include the compact member list"
+        "--include-members", action="store_true", help="在类摘要中包含紧凑成员清单"
     )
-    parser.add_argument("--format", choices=("text", "json"), default="text")
-    parser.add_argument("--profiles", metavar="PATH", help="framework profile index")
-    parser.add_argument("--tsv", metavar="PATH", help="function index")
+    parser.add_argument(
+        "--format", choices=("text", "json"), default="text", help="输出格式"
+    )
+    parser.add_argument("--profiles", metavar="PATH", help="Framework Profile 索引路径")
+    parser.add_argument("--tsv", metavar="PATH", help="function_index.tsv 路径")
     args = parser.parse_args(argv)
 
     if args.config and not args.class_name:
@@ -257,10 +302,12 @@ def main(argv=None):
     if args.include_members and not args.class_name:
         parser.error("--include-members requires --class")
 
-    profile_path = Path(args.profiles) if args.profiles else DEFAULT_INDEX
     tsv_path = Path(args.tsv) if args.tsv else DEFAULT_TSV
+    profile_path = profile_path_for(args)
     try:
-        profiles = load_index(profile_path)
+        profiles = (
+            load_index(profile_path) if profile_path else empty_profile_index()
+        )
         rows = load_rows(tsv_path)
     except (OSError, UnicodeError, ValueError) as error:
         print(f"ERROR: {error}", file=sys.stderr)