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

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

@@ -35,6 +35,24 @@ REQUIRED_COLUMNS = (
     "tags",
 )
 
+HELP_EPILOG = """\
+按中文业务含义查询表、数据源或字段：
+  dictionary_lookup.py --query "股票现金流指标销售现金比率"
+  dictionary_lookup.py --query "市值" --scope fund
+  dictionary_lookup.py --query "买一量" --table TradeTable
+  dictionary_lookup.py --query "9900700" --field 销售现金比率
+
+输出第一行是 in-band 状态：
+  status: ok         最高分候选唯一
+  status: ambiguous  多个同分候选；必须补充 scope、table 或 field 范围
+  status: no_match   数据字典无匹配，不等于 API not found
+
+退出码：
+  0  查询完成；ok、ambiguous、no_match 均由 status 表达
+  1  dictionary_index.tsv 或词表缺失、损坏、格式错误
+  2  参数不合法
+"""
+
 
 @dataclass(frozen=True)
 class QueryItem:
@@ -318,14 +336,21 @@ def _positive_int(value: str) -> int:
 
 
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description=__doc__, allow_abbrev=False)
-    parser.add_argument("--query", required=True)
-    parser.add_argument("--scope")
-    parser.add_argument("--table")
-    parser.add_argument("--field")
-    parser.add_argument("--limit", type=_positive_int, default=10)
-    parser.add_argument("--tsv", type=Path, default=DEFAULT_TSV)
-    parser.add_argument("--lexicon", type=Path, default=DEFAULT_LEXICON)
+    parser = argparse.ArgumentParser(
+        description="查询独立的天软表、数据源与字段字典索引。",
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument("--query", required=True, help="中文业务描述、名称或 ID")
+    parser.add_argument("--scope", help="按业务范围过滤")
+    parser.add_argument("--table", help="按表名或数据源名过滤")
+    parser.add_argument("--field", help="按字段名或字段 ID 过滤")
+    parser.add_argument("--limit", type=_positive_int, default=10, help="候选条数上限")
+    parser.add_argument("--tsv", type=Path, default=DEFAULT_TSV, help="字典索引路径")
+    parser.add_argument(
+        "--lexicon", type=Path, default=DEFAULT_LEXICON, help="受控同义词词表路径"
+    )
     return parser.parse_args(argv)