kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/scripts/cosmic-form-metadata.py

@@ -0,0 +1,856 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: NOASSERTION
+"""
+cosmic-form-metadata.py — Cosmic form metadata query and cache tool.
+
+Usage:
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formIdOrName>
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId1>,<formId2>,<中文名>   # batch, auto-detect
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --fuzzy qty price amount
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --fuzzy "组织 物料 批号"
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --fuzzy "数量|金额"
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --fuzzy status --show-detail
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --type BaseData
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --type "combo|check"
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --type decimal --fuzzy amount
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --tree
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --op
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --op 审核
+    python3 cosmic-form-metadata.py --config ok-cosmic.json get <formId> --refresh
+
+What it provides:
+1. Form metadata lookup by formId or billName
+2. Local SQLite cache for metadata payloads
+3. Fuzzy field filtering for keys / names
+4. Type-based fuzzy filtering (--type) for field type matching
+5. Optional detail mode for enum mappings and reference types
+
+What it does NOT do:
+- It does not query the form_metadata_cache table directly for user-facing output semantics
+- It does not infer field meaning beyond metadata returned by the configured API
+- It does not rebuild the API knowledge graph database
+
+Prerequisites:
+- A valid ok-cosmic.json project config
+- A reachable route.apiUrl (`runtime/route`) for cache misses
+"""
+
+import sys
+import argparse
+import re
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Dict, List, Optional
+
+from config_loader import load_project_config
+from route_client import RouteClient, unwrap_route_payload
+from sqlite_cache import JsonSqliteCache, resolve_graph_db_path
+from script_utils import FriendlyArgumentParser, run_cli
+
+
+def _looks_like_meta_payload(value: Any) -> bool:
+    return isinstance(value, dict) and (
+        "form" in value
+        or "formFields" in value
+        or "entityFields" in value
+        or value.get("code") in ("MULTI_MATCH", "BILL_NOT_FOUND")
+    )
+
+
+def _unwrap_route_payload(data: Any) -> Any:
+    return unwrap_route_payload(data, _looks_like_meta_payload)
+
+
+class MetadataDbCache:
+    def __init__(self, db_path: str, ttl: int = 600):
+        self._cache = JsonSqliteCache(
+            db_path,
+            table_name="form_metadata_cache",
+            key_column="form_id",
+            create_sql="""
+                CREATE TABLE IF NOT EXISTS form_metadata_cache (
+                    form_id TEXT PRIMARY KEY,
+                    payload TEXT,
+                    updated_at INTEGER
+                )
+            """,
+            ttl=ttl,
+            check_same_thread=False,
+            init_error_message="初始化数据库失败",
+            write_error_message="写入数据库失败",
+        )
+
+    def get(self, form_id: str) -> Optional[Dict[str, Any]]:
+        return self._cache.get(form_id)
+
+    def set(self, form_id: str, payload: Dict[str, Any]):
+        self._cache.set_payload(form_id, payload)
+
+    def remove(self, form_id: str):
+        self._cache.remove(form_id)
+
+    def close(self):
+        """显式关闭数据库连接。"""
+        self._cache.close()
+
+    def __del__(self):
+        self.close()
+
+
+class FormMetadata:
+    def __init__(self, config: Dict[str, Any], debug: bool = False):
+        self.debug = debug
+        route_config = config.get("route", {})
+        if not isinstance(route_config, dict):
+            route_config = {}
+        self.db_path = resolve_graph_db_path(
+            config,
+            "未配置 graph.dbPath，请在 ok-cosmic.json 中指定数据库全路径",
+        )
+        self.cache = MetadataDbCache(self.db_path)
+        self.route_client = RouteClient(
+            route_config,
+            debug=debug,
+            missing_message=(
+                "未配置表单元数据查询 API。请在 ok-cosmic.json 的 route.apiUrl 中配置统一路由，"
+                "或设置 COSMIC_ROUTE_API / COSMIC_RUNTIME_ROUTE_API 环境变量。"
+            ),
+        )
+
+    def _log_debug(self, msg: str):
+        if self.debug:
+            print(f" (DEBUG) {msg}", file=sys.stderr)
+
+    def _post(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self.route_client.post(payload)
+
+    @staticmethod
+    def _normalize_operates(raw_operates: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        兼容旧版 `buttons` 与新版 `operateMetas` 结构:
+        - buttons: {name, key, ...}
+        - operateMetas: {opName, opKey, opType}
+        统一输出为: {name, key, type}
+        """
+        normalized: List[Dict[str, Any]] = []
+        for op in raw_operates:
+            if not isinstance(op, dict):
+                continue
+            key = op.get("key") or op.get("opKey")
+            name = op.get("name") or op.get("opName")
+            op_type = op.get("type") or op.get("opType")
+            if not key and not name:
+                continue
+            normalized.append({
+                "name": name or "-",
+                "key": key or "-",
+                "type": op_type or "-"
+            })
+        return normalized
+
+    @staticmethod
+    def _field_sort_key(field: Dict[str, Any], sort_by: str = "key") -> tuple:
+        value = str(field.get(sort_by, "") or "").lower()
+        key = str(field.get("key", "") or "").lower()
+        name = str(field.get("name", "") or "").lower()
+        node_type = str(field.get("type", "") or "").lower()
+        db_key = str(field.get("dbKey", "") or "").lower()
+        return (value, key, name, node_type, db_key)
+
+    @classmethod
+    def _sort_fields(cls, fields: List[Dict[str, Any]], sort_by: str = "key") -> List[Dict[str, Any]]:
+        return sorted(fields, key=lambda f: cls._field_sort_key(f, sort_by=sort_by))
+
+    @classmethod
+    def _build_tree_lines(
+        cls,
+        fields: List[Dict[str, Any]],
+        filter_patterns: Optional[List[str]] = None,
+        sort_by: str = "key"
+    ) -> List[str]:
+        def is_hit(f: Dict[str, Any]) -> bool:
+            if not filter_patterns:
+                return True
+            target_text = (
+                str(f.get("key", ""))
+                + "|"
+                + str(f.get("name", ""))
+                + "|"
+                + str(f.get("type", ""))
+                + "|"
+                + str(f.get("dbKey", ""))
+                + "|"
+                + str(f.get("refType", ""))
+            ).lower()
+            for p in filter_patterns:
+                try:
+                    if re.search(p, target_text, re.IGNORECASE):
+                        return True
+                except Exception:
+                    if p.lower() in target_text:
+                        return True
+            return False
+
+        by_key: Dict[str, Dict[str, Any]] = {}
+        for f in fields:
+            key = str(f.get("key", "")).strip()
+            if key and key not in by_key:
+                by_key[key] = f
+
+        if not by_key:
+            return []
+
+        children: Dict[Optional[str], List[str]] = {}
+        for k, f in by_key.items():
+            parent = f.get("parentKey")
+            parent_key = str(parent).strip() if parent is not None else None
+            if parent_key == "":
+                parent_key = None
+            children.setdefault(parent_key, []).append(k)
+
+        for parent_key, ks in children.items():
+            children[parent_key] = sorted(
+                ks,
+                key=lambda k: cls._field_sort_key(by_key.get(k, {}), sort_by=sort_by)
+            )
+
+        include_keys = set(by_key.keys())
+        if filter_patterns:
+            include_keys = {k for k, f in by_key.items() if is_hit(f)}
+            # 补齐祖先节点，便于阅读路径
+            queue = list(include_keys)
+            while queue:
+                cur = queue.pop()
+                parent = by_key.get(cur, {}).get("parentKey")
+                parent_key = str(parent).strip() if parent is not None else None
+                if parent_key and parent_key in by_key and parent_key not in include_keys:
+                    include_keys.add(parent_key)
+                    queue.append(parent_key)
+
+        def fmt_node(key: str) -> str:
+            f = by_key[key]
+            name = f.get("name", "-")
+            node_type = f.get("type", "-")
+            db_key = f.get("dbKey", "-")
+            return f"{name} (`{key}`) [{node_type}] dbKey=`{db_key}`"
+
+        lines: List[str] = []
+        visited: set = set()
+
+        def walk(node_key: str, prefix: str, is_last: bool):
+            if node_key in visited or node_key not in include_keys:
+                return
+            visited.add(node_key)
+            branch = "`- " if is_last else "|- "
+            lines.append(f"{prefix}{branch}{fmt_node(node_key)}")
+            child_keys = [ck for ck in children.get(node_key, []) if ck in include_keys]
+            for i, ck in enumerate(child_keys):
+                next_prefix = prefix + ("   " if is_last else "|  ")
+                walk(ck, next_prefix, i == len(child_keys) - 1)
+
+        roots = []
+        for k in sorted(include_keys, key=lambda x: cls._field_sort_key(by_key.get(x, {}), sort_by=sort_by)):
+            parent = by_key.get(k, {}).get("parentKey")
+            parent_key = str(parent).strip() if parent is not None else None
+            if not parent_key or parent_key not in include_keys:
+                roots.append(k)
+
+        roots = sorted(set(roots), key=lambda x: cls._field_sort_key(by_key.get(x, {}), sort_by=sort_by))
+        for i, rk in enumerate(roots):
+            walk(rk, "", i == len(roots) - 1)
+
+        return lines
+
+    def get_meta_fields(
+        self,
+        formId: Optional[str] = None,
+        billName: Optional[str] = None,
+        filter_patterns: Optional[List[str]] = None,
+        raw_patterns: Optional[List[str]] = None,
+        type_patterns: Optional[List[str]] = None,
+        show_detail: bool = False,
+        tree_view: bool = False,
+        sql_mode: bool = False,
+        sort_by: str = "key",
+        view: str = "all",
+        op_mode: bool = False,
+        op_patterns: Optional[List[str]] = None
+    ) -> str:
+        if not formId and not billName:
+            return "✖️ 错误: 必须提供 formId 或 billName"
+
+        target_payload = None
+        if formId:
+            target_payload = self.cache.get(formId)
+            if target_payload: self._log_debug(f"命中缓存 (FormId: {formId})")
+
+        if not target_payload:
+            self._log_debug("数据库无有效缓存，发起远程全量拉取...")
+            # 始终拉取全量用于本地缓存
+            payload = {
+                "data": {
+                    "type": "meta",
+                    "reqData": {
+                        "entityId": formId or "",
+                        "formId": formId or "",
+                        "billName": billName or "",
+                        "full": True,
+                    },
+                }
+            }
+            try:
+                resp = self._post(payload)
+            except RuntimeError as e:
+                return f"✖️ {e}"
+            if not resp.get("status"):
+                return f"✖️ 接口请求失败: {resp.get('message', '未知错误')}"
+
+            data = _unwrap_route_payload(resp.get("data", {}))
+            if data.get("code") in ("MULTI_MATCH", "BILL_NOT_FOUND"):
+                msg = data.get("message", "单据未找到")
+                cand_str = "\n".join([f"- {c.get('formName') or c.get('name') or '-'} (`{c.get('formId') or c.get('id') or '-'}`)" for c in data.get("candidates", [])])
+                return f"✖️ {msg}\n{cand_str}"
+
+            target_payload = data
+            real_form_id = data.get("form", {}).get("formId")
+            if real_form_id:
+                self.cache.set(real_form_id, data)
+
+        # 数据提取
+        form = target_payload.get("form", {})
+        form_fields = target_payload.get("formFields") or []
+        entity_fields = target_payload.get("entityFields") or []
+        raw_operates = (
+            target_payload.get("operateMetas")
+            or target_payload.get("buttons")
+            or []
+        )
+        buttons = self._normalize_operates(raw_operates)
+
+        # ── --op 模式：只输出操作按钮 ──
+        if op_mode:
+            _form_name = form.get('formName') or form.get('name') or form.get('title') or '-'
+            _form_id = form.get('formId') or form.get('id') or form.get('key') or '-'
+            md = [f"## [Op] 操作查询: {_form_name} ({_form_id})"]
+
+            if op_patterns:
+                def _op_hit(b):
+                    target = (str(b.get('name', '')) + '|' + str(b.get('key', '')) + '|' + str(b.get('type', ''))).lower()
+                    for p in op_patterns:
+                        try:
+                            if re.search(p, target, re.IGNORECASE):
+                                return True
+                        except Exception:
+                            if p.lower() in target:
+                                return True
+                    return False
+                matched = [b for b in buttons if _op_hit(b)]
+                md.append(f"筛选: `{', '.join(op_patterns)}`，匹配 {len(matched)}/{len(buttons)} 个操作\n")
+            else:
+                matched = buttons
+                md.append(f"共 {len(matched)} 个操作\n")
+
+            if matched:
+                md.append("| 名称 | 标识 (opKey) | 类型 (opType) |")
+                md.append("| :--- | :--- | :--- |")
+                for b in matched:
+                    md.append(f"| {b.get('name')} | `{b.get('key')}` | {b.get('type')} |")
+            else:
+                md.append("> 未找到匹配的操作按钮")
+            return "\n".join(md)
+
+        # 过滤与搜索逻辑
+        def is_hit(f):
+            if not filter_patterns: return True
+            target_text = (
+                str(f.get('key', ''))
+                + "|"
+                + str(f.get('name', ''))
+                + "|"
+                + str(f.get('type', ''))
+            ).lower()
+            for p in filter_patterns:
+                try:
+                    if re.search(p, target_text, re.IGNORECASE): return True
+                except Exception:
+                    if p.lower() in target_text: return True
+            return False
+
+        def is_type_hit(f):
+            """按 type 字段进行模糊匹配筛选。"""
+            if not type_patterns:
+                return True
+            field_type = str(f.get('type', '')).lower()
+            for p in type_patterns:
+                try:
+                    if re.search(p, field_type, re.IGNORECASE):
+                        return True
+                except Exception:
+                    if p.lower() in field_type:
+                        return True
+            return False
+
+        def is_combined_hit(f):
+            """同时满足 fuzzy 和 type 两个筛选条件。"""
+            return is_hit(f) and is_type_hit(f)
+
+        # 应用过滤
+        biz_form_fields = self._sort_fields(form_fields, sort_by=sort_by)
+        biz_entity_fields = self._sort_fields(entity_fields, sort_by=sort_by)
+
+        def get_match_score(f):
+            if not filter_patterns: return 0
+            k = str(f.get('key', '')).lower()
+            n = str(f.get('name', '')).lower()
+            t = str(f.get('type', '')).lower()
+            db = str(f.get('dbKey', '')).lower()
+            ref = str(f.get('refType', '')).lower()
+            
+            score = 99
+            for p in filter_patterns:
+                p_lower = p.lower()
+                if p_lower == k or p_lower == n:
+                    return 0
+                if k.startswith(p_lower) or n.startswith(p_lower):
+                    score = min(score, 1)
+                elif p_lower in k or p_lower in n:
+                    score = min(score, 2)
+                else:
+                    try:
+                        if re.search(p_lower, f"{k}|{n}", re.IGNORECASE):
+                            score = min(score, 3)
+                        elif p_lower in t or p_lower in db or p_lower in ref or re.search(p_lower, f"{t}|{db}|{ref}", re.IGNORECASE):
+                            score = min(score, 4)
+                    except Exception:
+                        pass
+            return score
+
+        display_form_fields = sorted([f for f in biz_form_fields if is_combined_hit(f)], key=get_match_score)
+        display_entity_fields = sorted([f for f in biz_entity_fields if is_combined_hit(f)], key=get_match_score)
+        display_buttons = sorted([b for b in buttons if is_combined_hit(b)], key=get_match_score)
+
+        # ── 三级降级机制 ────────────────────────────────────────
+        _used_fallback = False
+        _fallback_hint = ""
+        _no_results = lambda: not display_form_fields and not display_entity_fields and not display_buttons
+
+        # 降级 1: 规范化后查不到 → 用原始输入重查
+        #   场景: "物料 编码" 被拆成 ['物料','编码']，但字段名确实是 "物料 编码"
+        if (filter_patterns and raw_patterns
+                and filter_patterns != raw_patterns
+                and _no_results()):
+            filter_patterns = raw_patterns
+            display_form_fields = sorted([f for f in biz_form_fields if is_combined_hit(f)], key=get_match_score)
+            display_entity_fields = sorted([f for f in biz_entity_fields if is_combined_hit(f)], key=get_match_score)
+            display_buttons = sorted([b for b in buttons if is_combined_hit(b)], key=get_match_score)
+            if not _no_results():
+                _used_fallback = True
+                _fallback_hint = f"已降级为原始输入重查: `{' '.join(raw_patterns)}`"
+
+        # 降级 2: 仍查不到 → 转义为纯文本匹配
+        #   场景: "数量(基本)" 括号被当正则 / "C++标记" 加号被当量词
+        if filter_patterns and _no_results():
+            escaped = [re.escape(p) for p in (raw_patterns or filter_patterns)]
+            if escaped != filter_patterns:
+                filter_patterns = escaped
+                display_form_fields = sorted([f for f in biz_form_fields if is_combined_hit(f)], key=get_match_score)
+                display_entity_fields = sorted([f for f in biz_entity_fields if is_combined_hit(f)], key=get_match_score)
+                display_buttons = sorted([b for b in buttons if is_combined_hit(b)], key=get_match_score)
+                if not _no_results():
+                    _used_fallback = True
+                    _src = raw_patterns or filter_patterns
+                    _fallback_hint = f"已降级为纯文本匹配: `{' '.join(_src)}`"
+
+        view = (view or "all").strip()
+        show_form = view in ("form", "all")
+        show_entity = view in ("entity", "all")
+        show_operate = view in ("operate", "all")
+
+        selected_biz_form_fields = biz_form_fields if show_form else []
+        selected_biz_entity_fields = biz_entity_fields if show_entity else []
+        selected_display_form_fields = display_form_fields if show_form else []
+        selected_display_entity_fields = display_entity_fields if show_entity else []
+        selected_display_buttons = display_buttons if show_operate else []
+        selected_buttons = buttons if show_operate else []
+
+        _form_name = form.get('formName') or form.get('name') or form.get('title') or '-'
+        _form_id = form.get('formId') or form.get('id') or form.get('key') or '-'
+        _db_name = form.get('dbName') or target_payload.get('dbName') or '-'
+        md = [f"## [Form] 单据: {_form_name} ({_form_id})"]
+        md.append(
+            "**模型信息**: "
+            f"dbName=`{_db_name}`, "
+            f"dbTableKey=`{form.get('dbTableKey', '-')}`, "
+            f"dbRoute=`{form.get('dbRoute', '-')}`, "
+            f"modelType=`{form.get('modelType', '-')}`"
+        )
+        md.append(f"**视图**: `{view}`")
+        md.append(f"**元数据状态**: 已缓存本地 (DB驱动)")
+        if _used_fallback:
+            md.append(f"> [Warn] {_fallback_hint}")
+        md.append("")
+
+        # 根据是否有过滤词切换视图
+        _has_filter = bool(filter_patterns or type_patterns)
+        _filter_desc_parts = []
+        if filter_patterns:
+            _filter_desc_parts.append(f"fuzzy: {', '.join(filter_patterns)}")
+        if type_patterns:
+            _filter_desc_parts.append(f"type: {', '.join(type_patterns)}")
+        _filter_desc = '；'.join(_filter_desc_parts)
+
+        if tree_view:
+            all_biz = []
+            seen = set()
+            for f in selected_biz_form_fields + selected_biz_entity_fields:
+                k = f.get("key")
+                if k and k not in seen:
+                    all_biz.append(f)
+                    seen.add(k)
+
+            # tree 视图下 type 过滤: 先筛后建树
+            if type_patterns:
+                all_biz = [f for f in all_biz if is_type_hit(f)]
+            tree_lines = self._build_tree_lines(all_biz, filter_patterns=filter_patterns, sort_by=sort_by) if all_biz else []
+            if _has_filter:
+                md.append(f"### [Tree] 字段树 (按条件筛选: {_filter_desc}，排序: {sort_by})")
+            else:
+                md.append(f"### [Tree] 字段树 (按 parentKey，排序: {sort_by})")
+
+            if tree_lines:
+                md.extend(tree_lines)
+            else:
+                md.append("> 未找到匹配字段（当前 view 可能不包含字段类型）")
+
+            if selected_display_buttons:
+                md.append("\n### [Op] 操作按钮 (匹配)")
+                md.append(", ".join([f"{b.get('name')}(`{b.get('key')}`/{b.get('type')})" for b in selected_display_buttons]))
+        elif _has_filter:
+            md.append(f"### [Detail] 字段详情 (按条件筛选: {_filter_desc}，排序: {sort_by})")
+            
+            all_fields_by_key = {str(f.get('key', '')).lower(): f for f in form_fields + entity_fields}
+            
+            def get_entity_info(f):
+                parent_key = f.get('parentKey')
+                if not parent_key:
+                    return "表头"
+                parent_key_lower = str(parent_key).lower()
+                parent = all_fields_by_key.get(parent_key_lower)
+                if not parent:
+                    return f"未知 (`{parent_key}`)"
+                ptype = str(parent.get('type', '')).lower()
+                if 'subentry' in ptype:
+                    grandparent_key = parent.get('parentKey')
+                    if grandparent_key:
+                        return f"子表体 (`{grandparent_key}` -> `{parent_key}`)"
+                    return f"子表体 (`{parent_key}`)"
+                elif 'entry' in ptype:
+                    return f"表体 (`{parent_key}`)"
+                else:
+                    return f"容器 (`{parent_key}`)"
+
+            def get_db_table(f):
+                parent_key = f.get('parentKey')
+                if not parent_key:
+                    ftype = str(f.get('type', '')).lower()
+                    if 'entry' in ftype and f.get('dbKey'):
+                        return f.get('dbKey')
+                    return form.get('dbTableKey') or '-'
+                parent = all_fields_by_key.get(str(parent_key).lower())
+                return parent.get('dbKey') or '-' if parent else '-'
+
+            def get_table_entity_info(f):
+                parent_key = f.get('parentKey')
+                ftype = str(f.get('type', '')).lower()
+                if not parent_key and 'subentry' in ftype:
+                    return f"子表体 (`{f.get('key')}`)"
+                if not parent_key and 'entry' in ftype:
+                    return f"表体 (`{f.get('key')}`)"
+                return get_entity_info(f)
+
+            if selected_display_form_fields or selected_display_entity_fields:
+                if sql_mode:
+                    md.append("### [SQL] 表所在数据库")
+                    md.append(f"> dbName 来自 FormMeta；分录/子分录表一般与单头表位于同一数据库 `{_db_name}`。")
+                    md.append("| 所属实体 | 表名 (dbTableName) | 数据库名 (dbName) |")
+                    md.append("| :--- | :--- | :--- |")
+                    seen_tables = set()
+                    for tf in selected_display_form_fields + selected_display_entity_fields:
+                        table_entity = get_table_entity_info(tf)
+                        table_name = get_db_table(tf)
+                        table_sig = (table_entity, table_name)
+                        if table_sig in seen_tables:
+                            continue
+                        md.append(f"| {table_entity} | `{table_name}` | `{_db_name}` |")
+                        seen_tables.add(table_sig)
+                    md.append("")
+                    md.append("### [SQL] 字段与数据库字段")
+                    md.append("| 名称 | 标识 (Key) | 所属实体 | 表名 (dbTableName) | 数据库字段 (dbKey) |")
+                    md.append("| :--- | :--- | :--- | :--- | :--- |")
+                elif show_detail:
+                    md.append("| 名称 | 标识 (Key) | 类型 | 所属实体 | 详情 (枚举/基础资料引用) |")
+                    md.append("| :--- | :--- | :--- | :--- | :--- |")
+                else:
+                    md.append("| 名称 | 标识 (Key) | 类型 | 所属实体 | 附加信息 (Ext) |")
+                    md.append("| :--- | :--- | :--- | :--- | :--- |")
+
+                # 优先显示表单字段，再显示实体字段（去重）
+                seen_keys = set()
+                for f in selected_display_form_fields + selected_display_entity_fields:
+                    if f.get('key') not in seen_keys:
+                        ent_info = get_entity_info(f)
+                        db_key = f.get('dbKey', '-')
+                        
+                        if sql_mode:
+                            db_table = get_db_table(f)
+                            md.append(f"| {f.get('name')} | `{f.get('key')}` | {ent_info} | `{db_table}` | `{db_key}` |")
+                        elif show_detail:
+                            detail_parts = []
+                            ext_map = f.get('extMap')
+                            ref_type = f.get('refType')
+                            key = f.get('key')
+                            ftype = str(f.get('type', ''))
+                            if ext_map:
+                                detail_parts.append("枚举: " + ", ".join([f"{k}:{v}" for k, v in ext_map.items()]))
+                            if ref_type:
+                                if ftype == 'BasedataPropField':
+                                    detail_parts.append(f"[Note] 取值路径: `{ref_type}`（禁止用控件标识 `{f.get('key')}` 取值）")
+                                else:
+                                    detail_parts.append(f"基础资料引用: `{ref_type}`")
+                            if ftype == 'LargeTextField' and key:
+                                detail_parts.append(f"[Note] 完整取值: `{key}_tag`（LargeTextField 大文本禁止只用 `{key}` 获取完整内容）")
+                            detail_str = "；".join(detail_parts) if detail_parts else "-"
+                            md.append(f"| {f.get('name')} | `{f.get('key')}` | {f.get('type')} | {ent_info} | {detail_str} |")
+                        else:
+                            ext_map = f.get('extMap')
+                            ref_type = f.get('refType')
+                            key = f.get('key')
+                            ftype = str(f.get('type', ''))
+                            ext_parts = []
+                            if ext_map:
+                                ext_parts.append(", ".join([f"{k}:{v}" for k, v in ext_map.items()]))
+                            if ref_type:
+                                if ftype == 'BasedataPropField':
+                                    ext_parts.append(f"[Note] 取值路径:`{ref_type}`（禁用`{f.get('key')}`）")
+                                else:
+                                    ext_parts.append(f"ref:`{ref_type}`")
+                            if ftype == 'LargeTextField' and key:
+                                ext_parts.append(f"[Note] 完整取值:`{key}_tag`（大文本禁用`{key}`取完整内容）")
+                            ext_str = "；".join(ext_parts) if ext_parts else "-"
+                            md.append(f"| {f.get('name')} | `{f.get('key')}` | {f.get('type')} | {ent_info} | {ext_str} |")
+                        seen_keys.add(f.get('key'))
+            else:
+                md.append("> 当前 view 不包含字段类型或无匹配字段")
+
+            if selected_display_buttons:
+                md.append("\n### [Op] 操作按钮 (匹配)")
+                md.append(", ".join([f"{b.get('name')}(`{b.get('key')}`/{b.get('type')})" for b in selected_display_buttons]))
+        else:
+            # 概览模式：只输出紧凑的 Key-Name 映射
+            md.append(f"### [List] 字段概览 (共 {len(selected_biz_form_fields) + len(selected_biz_entity_fields)} 个字段，排序: {sort_by})")
+            # 合并展示
+            all_biz = []
+            seen = set()
+            for f in selected_biz_form_fields + selected_biz_entity_fields:
+                if f.get('key') not in seen:
+                    all_biz.append(f)
+                    seen.add(f.get('key'))
+
+            chunk_size = 3
+            for i in range(0, min(len(all_biz), 120), chunk_size):
+                chunk = all_biz[i:i+chunk_size]
+                line = "  ".join([f"• {f.get('name')}: `{f.get('key')}`" for f in chunk])
+                md.append(line)
+
+            if len(all_biz) > 120:
+                md.append(f"\n> *提示: 字段较多已截断。本地已缓存全量，请传入关键词（支持正则）获取特定字段详情。*")
+
+            if selected_buttons:
+                md.append("\n### [Op] 全部操作按钮")
+                md.append(", ".join([f"{b.get('name')}(`{b.get('key')}`/{b.get('type')})" for b in selected_buttons]))
+
+        return "\n".join(md)
+
+
+_RE_META = re.compile(r'[|*+?\[\]()\\{}^$]')
+
+
+def _normalize_fuzzy_patterns(raw_patterns: List[str]) -> List[str]:
+    """
+    智能拆分 fuzzy 参数，兼容各种 AI/Agent 的传参习惯:
+      --fuzzy 组织 物料 批号       → ['组织', '物料', '批号']      (nargs 原生)
+      --fuzzy "组织 物料 批号"     → ['组织', '物料', '批号']      (引号包裹，按空格拆)
+      --fuzzy "数量|金额"          → ['数量|金额']                 (正则，保持原样)
+      --fuzzy "qty.*amount"       → ['qty.*amount']               (正则，保持原样)
+      --fuzzy "组织" "物料"        → ['组织', '物料']              (多引号，逐个处理)
+    判定规则：含正则元字符 ``|*+?[](){}^$`` 的 token 视为正则，否则按空格拆分。
+    """
+    result: List[str] = []
+    for p in raw_patterns:
+        p = p.strip()
+        if not p:
+            continue
+        if _RE_META.search(p):
+            # 含正则元字符，保持原样
+            result.append(p)
+        else:
+            # 纯文本：可能是 "组织 物料 批号" 这样的引号包裹，按空格拆
+            result.extend(p.split())
+    return [x for x in result if x]
+
+
+def main():
+    parser = FriendlyArgumentParser(
+        description="Cosmic Form Metadata CLI — 苍穹表单元数据字段查询",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+推荐用法
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  # 按 formId 查字段，模糊匹配多个关键词（空格分隔）
+  %(prog)s --config ok-cosmic.json get <formId> --fuzzy qty price amount
+
+  # 按中文名称确认基础资料的真实英文标识
+  %(prog)s --config ok-cosmic.json get <中文名>
+
+  # 批量查询：formId 与中文名可混合，逗号分隔，自动识别
+  %(prog)s --config ok-cosmic.json get "ap_finapbill,物料,bd_supplier" --fuzzy number
+
+  # 查枚举映射 / 基础资料引用类型 (refType)
+  %(prog)s --config ok-cosmic.json get <formId> --fuzzy <字段> --show-detail
+
+  # 按字段类型模糊筛选（如筛出所有 BaseData 类型字段）
+  %(prog)s --config ok-cosmic.json get <formId> --type BaseData
+
+  # 按多种类型筛选（正则 OR）
+  %(prog)s --config ok-cosmic.json get <formId> --type "combo|check"
+
+  # 类型 + 关键词交集筛选（如筛出 Decimal 类型中含 amount 的字段）
+  %(prog)s --config ok-cosmic.json get <formId> --type decimal --fuzzy amount
+
+  # 按字段树结构输出
+  %(prog)s --config ok-cosmic.json get <formId> --tree
+
+  # 查看所有操作按钮
+  %(prog)s --config ok-cosmic.json get <formId> --op
+
+  # 按关键词筛选操作
+  %(prog)s --config ok-cosmic.json get <formId> --op 审核 提交
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AI 调用约束（摘要，完整约束见 SKILL.md 跨脚本硬约束与 coding-preferences.md B2）
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  - formIdOrName 支持逗号分隔批量查询，英文标识与中文名可混合，自动识别。
+  - --fuzzy 多关键词用空格分隔（如 --fuzzy qty price amount），严禁逐个字段多次查询。
+  - ≥ 3 个关键词时自动升级为详情模式；编写枚举判断前必须带 --show-detail。
+""",
+    )
+    parser.add_argument("--config", help="Path to ok-cosmic.json")
+
+    sub_parser = parser.add_subparsers(dest="command")
+    get_parser = sub_parser.add_parser("get")
+    get_parser.add_argument("formIdOrName", help="formId 或中文名，支持逗号分隔批量查询（英文标识与中文名可混合，自动识别）")
+    get_parser.add_argument("--fuzzy", nargs="*", help="筛选关键词或正则模式，触发详情视图。支持多种传参方式: --fuzzy a b c / --fuzzy 'a b c' / --fuzzy 'a|b'。≥ 3 个关键词时自动升级为详情模式（含枚举/refType）")
+    get_parser.add_argument("--type", nargs="*", dest="type_filter", help="按字段类型模糊筛选，触发详情视图。支持正则: --type BaseData / --type 'combo|check' / --type decimal text。可与 --fuzzy 联用做交集筛选")
+    get_parser.add_argument("--show-detail", action="store_true", help="显示枚举值映射(extMap)或基础资料引用类型(refType)")
+    get_parser.add_argument("--tree", action="store_true", help="按 parentKey 输出字段树（可与 --fuzzy 联用）")
+    get_parser.add_argument("--op", nargs="*", help="操作查询模式。不带值列出全部操作；带关键词按 name/key 模糊筛选（如 --op 审核 提交）")
+    get_parser.add_argument("--sql", action="store_true", help="启用 SQL 模式，展示库名、表名与数据库字段名 (dbName/dbTableName/dbKey)")
+    get_parser.add_argument("--sort", choices=["key", "name", "type", "dbKey"], default="key", help="字段排序方式")
+    get_parser.add_argument("--view", choices=["form", "entity", "operate", "all"], default="all", help="元数据视图范围")
+    get_parser.add_argument("--debug", action="store_true")
+    get_parser.add_argument("--refresh", action="store_true")
+
+    args = parser.parse_args()
+    config = load_project_config(args.config)
+    fm = FormMetadata(config, debug=getattr(args, 'debug', False))
+
+    if args.command == "get":
+        # 智能拆分 fuzzy 参数：纯关键词按空格拆开，正则模式保持原样
+        raw_fuzzy = list(args.fuzzy) if args.fuzzy else None
+        if args.fuzzy:
+            args.fuzzy = _normalize_fuzzy_patterns(args.fuzzy)
+        # 智能拆分 type 参数
+        type_patterns = None
+        if args.type_filter:
+            type_patterns = _normalize_fuzzy_patterns(args.type_filter)
+        # 当 fuzzy 关键词 ≥3 个时，自动升级为详情模式（含枚举/refType）
+        auto_detail = False
+        show_detail = args.show_detail
+        if not show_detail and args.fuzzy and len(args.fuzzy) >= 3:
+            show_detail = True
+            auto_detail = True
+
+        # ── 批量查询支持：逗号分隔，自动识别 formId / billName ──
+        _RE_HAS_CJK = re.compile(r'[\u4e00-\u9fff\u3400-\u4dbf]')
+        raw_targets = [t.strip() for t in re.split(r'[,\uff0c]', args.formIdOrName) if t.strip()] if args.formIdOrName else []
+
+        if not raw_targets:
+            print("✖️ 错误: 必须提供 formIdOrName")
+            fm.cache.close()
+            sys.exit(1)
+
+        # 分类：含中文 → billName，否则 → formId
+        query_targets = []
+        for t in raw_targets:
+            if _RE_HAS_CJK.search(t):
+                query_targets.append({"formId": None, "billName": t})
+            else:
+                query_targets.append({"formId": t, "billName": None})
+
+        # refresh 清缓存（串行，SQLite 写操作）
+        if args.refresh:
+            for qt in query_targets:
+                if qt["formId"]:
+                    fm.cache.remove(qt["formId"])
+
+        # ── --op 模式 ──
+        op_mode = args.op is not None
+        op_patterns = None
+        if op_mode and args.op:
+            op_patterns = _normalize_fuzzy_patterns(args.op)
+
+        def _query_one(qt):
+            return fm.get_meta_fields(
+                formId=qt["formId"],
+                billName=qt["billName"],
+                filter_patterns=args.fuzzy,
+                raw_patterns=raw_fuzzy,
+                type_patterns=type_patterns,
+                show_detail=show_detail,
+                tree_view=args.tree,
+                sql_mode=args.sql,
+                sort_by=args.sort,
+                view=args.view,
+                op_mode=op_mode,
+                op_patterns=op_patterns
+            )
+
+        if len(query_targets) == 1:
+            results = [_query_one(query_targets[0])]
+        else:
+            results = [None] * len(query_targets)
+            with ThreadPoolExecutor(max_workers=min(len(query_targets), 4)) as pool:
+                future_to_idx = {
+                    pool.submit(_query_one, qt): i
+                    for i, qt in enumerate(query_targets)
+                }
+                for future in as_completed(future_to_idx):
+                    idx = future_to_idx[future]
+                    try:
+                        results[idx] = future.result()
+                    except Exception as e:
+                        t = query_targets[idx]
+                        label = t["formId"] or t["billName"]
+                        results[idx] = f"✖️ 查询 `{label}` 失败: {e}"
+
+        output = "\n\n---\n\n".join(results)
+        if auto_detail:
+            output += "\n\n> [Tip] 已自动启用详情模式（fuzzy 关键词 ≥3），包含枚举映射和基础资料引用类型。"
+        print(output)
+    else:
+        parser.print_help()
+
+    fm.cache.close()
+
+if __name__ == "__main__":
+    sys.exit(run_cli(main))