kcode-pi 0.1.5 → 0.1.7

package/vendor/kingdee-skills/ok-cosmic/scripts/cosmic-api-knowledge.py

@@ -1,910 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: NOASSERTION
-"""
-cosmic-api-knowledge.py — Offline Cosmic API knowledge graph query tool.
-
-Usage:
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json search <queryA>,<queryB>              # batch search
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json search <query...>
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json search <query...> --class-prefix kd.bos.servicehelper
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json search-method <queryA>,<queryB>       # batch search-method
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json search-method <query...>
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json detail <full.class.Name1>,<full.class.Name2>   # batch detail
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json detail <full.class.Name>
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json detail <full.class.Name> --method <keyword>
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json detail <full.class.Name> --method <keyword> --declared-only
-    python3 cosmic-api-knowledge.py --config ok-cosmic.json detail <full.class.Name> --method <keyword> --compact
-
-What it provides:
-1. Fuzzy / regex class search against ok-cosmic-knowledge.db
-2. Cross-class method search with ranking and package/category filters
-3. Class detail lookup with signatures, return types, comments and inherited methods
-4. Compact method fact output for downstream AI consumption
-
-What it does NOT do:
-- It does not inspect live jars directly; it only queries the built knowledge database
-- It does not verify runtime availability of a class or method in the current environment
-- It does not rebuild the knowledge database; use ok-cosmic-knowledge for that
-
-Prerequisites:
-- A valid ok-cosmic.json or equivalent graph config
-- A built ok-cosmic-knowledge.db reachable from config / environment / project paths
-"""
-
-import json
-import sys
-import os
-import argparse
-import re
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Set, Tuple
-
-from config_loader import load_project_config
-from script_utils import FriendlyArgumentParser, run_cli
-
-
-CHEAT_SHEET_PATH = Path(__file__).resolve().parent.parent / "rules" / "cheat-sheet.md"
-
-
-def _load_cheat_sheet_index() -> Tuple[Set[str], Set[Tuple[str, str]]]:
-    """解析 cheat-sheet.md，提取已收录的类简名和 (类简名, 方法名) 对。"""
-    classes: Set[str] = set()
-    methods: Set[Tuple[str, str]] = set()
-    try:
-        text = CHEAT_SHEET_PATH.read_text(encoding="utf-8")
-    except (FileNotFoundError, OSError):
-        return classes, methods
-
-    in_code_block = False
-    for line in text.splitlines():
-        stripped = line.strip()
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            continue
-        if not in_code_block or stripped.startswith("//") or stripped.startswith("import "):
-            continue
-        # 匹配 ClassName.methodName( 模式
-        for m in re.finditer(r'\b([A-Z][A-Za-z0-9_]+)\.([a-z][A-Za-z0-9_]*)\s*\(', stripped):
-            cls_name, method_name = m.group(1), m.group(2)
-            classes.add(cls_name)
-            methods.add((cls_name, method_name))
-        # 匹配 new ClassName( 模式
-        for m in re.finditer(r'\bnew\s+([A-Z][A-Za-z0-9_]+)\s*\(', stripped):
-            classes.add(m.group(1))
-    return classes, methods
-
-
-PRIMITIVE_DESCRIPTOR_TYPES = {
-    "V": "void",
-    "Z": "boolean",
-    "B": "byte",
-    "C": "char",
-    "S": "short",
-    "I": "int",
-    "F": "float",
-    "J": "long",
-    "D": "double",
-}
-
-
-class ApiGraph:
-    def __init__(self, config: Dict[str, Any]):
-        graph_config = config.get("graph") if isinstance(config.get("graph"), dict) else config
-        self.config_dir = str(config.get("__config_dir__", "")).strip()
-        self.script_dir = str(Path(__file__).resolve().parent)
-        db_path = str(graph_config.get("dbPath", "")).strip()
-
-        self.db_path = ""
-        if db_path:
-            raw_db_path = os.path.expanduser(db_path)
-            if os.path.isabs(raw_db_path):
-                self.db_path = os.path.normpath(raw_db_path)
-            else:
-                base_dir = self.config_dir or os.getcwd()
-                self.db_path = os.path.normpath(os.path.abspath(os.path.join(base_dir, raw_db_path)))
-
-        self._cheat_classes, self._cheat_methods = _load_cheat_sheet_index()
-
-        self.sqlite_error: Optional[str] = None
-
-
-
-    def _get_conn(self):
-        if hasattr(self, '_conn_cache') and self._conn_cache is not None:
-            return self._conn_cache
-        if self.sqlite_error:
-            return None
-        try:
-            import sqlite3
-            import re
-        except Exception as e:
-            self.sqlite_error = f"sqlite3 or re unavailable: {e}"
-            return None
-
-        if not self.db_path or not os.path.exists(self.db_path):
-            return None
-        conn = sqlite3.connect(self.db_path, check_same_thread=False)
-        conn.execute("PRAGMA journal_mode=WAL")
-        conn.execute("PRAGMA busy_timeout=5000")
-
-        def regexp(expr, item):
-            try:
-                reg = re.compile(expr, re.IGNORECASE)
-                return reg.search(item) is not None
-            except Exception:
-                return False
-        conn.create_function("REGEXP", 2, regexp)
-
-        conn.row_factory = sqlite3.Row
-        self._conn_cache = conn
-        return conn
-
-    @staticmethod
-    def _decode_descriptor_type(descriptor: str, index: int) -> Tuple[str, int]:
-        array_depth = 0
-        while index < len(descriptor) and descriptor[index] == "[":
-            array_depth += 1
-            index += 1
-
-        if index >= len(descriptor):
-            return "Object" + "[]" * array_depth, index
-
-        token = descriptor[index]
-        if token == "L":
-            end = descriptor.find(";", index)
-            if end == -1:
-                return "Object" + "[]" * array_depth, len(descriptor)
-            class_name = descriptor[index + 1:end].replace("/", ".").replace("$", ".")
-            return class_name + "[]" * array_depth, end + 1
-
-        pretty = PRIMITIVE_DESCRIPTOR_TYPES.get(token, token)
-        return pretty + "[]" * array_depth, index + 1
-
-    @classmethod
-    def _normalize_type_name(cls, type_name: Optional[str], *, keep_full_path: bool = False) -> str:
-        raw = (type_name or "").strip()
-        if not raw:
-            return "void"
-        if raw.endswith("[]"):
-            return cls._normalize_type_name(raw[:-2], keep_full_path=keep_full_path) + "[]"
-        if raw.startswith("("):
-            return raw
-        normalized = raw.replace("$", ".")
-        if keep_full_path:
-            return normalized
-        return normalized.split(".")[-1]
-
-    @classmethod
-    def _format_method_signature(cls, method_name: str, method_signature: Optional[str], return_type: Optional[str] = None) -> str:
-        signature = (method_signature or "").strip()
-        if not signature:
-            return f"{method_name}()"
-        if signature.startswith("(") and ("/" not in signature and ";" not in signature):
-            suffix = f" -> {cls._normalize_type_name(return_type, keep_full_path=True)}" if return_type else ""
-            return f"{signature}{suffix}"
-        if not signature.startswith("("):
-            return signature
-
-        index = 1
-        params: List[str] = []
-        while index < len(signature) and signature[index] != ")":
-            param_type, index = cls._decode_descriptor_type(signature, index)
-            params.append(param_type)
-
-        if index >= len(signature) or signature[index] != ")":
-            return f"{method_name}{signature}"
-
-        decoded_return_type, _ = cls._decode_descriptor_type(signature, index + 1)
-        return f"{method_name}({', '.join(params)}) -> {decoded_return_type}"
-
-    @classmethod
-    def _format_method_signature_for_search(cls, method_name: str, method_signature: Optional[str], return_type: Optional[str] = None) -> str:
-        signature = cls._format_method_signature(method_name, method_signature, return_type)
-        if " -> " not in signature:
-            return signature
-        prefix, suffix = signature.rsplit(" -> ", 1)
-        if suffix.startswith("java."):
-            return f"{prefix} -> {cls._normalize_type_name(suffix)}"
-        return signature
-
-    @staticmethod
-    def _parse_method_comment(comment: Optional[str]) -> Tuple[str, List[Tuple[str, str]], Optional[str], List[str]]:
-        text = (comment or "").strip()
-        if not text:
-            return "", [], None, []
-
-        description_lines: List[str] = []
-        params: List[Tuple[str, str]] = []
-        return_desc: Optional[str] = None
-        throws_desc: List[str] = []
-
-        for raw_line in text.splitlines():
-            line = raw_line.strip()
-            if not line:
-                continue
-            if line.startswith("@param"):
-                match = re.match(r"@param\s+`?([A-Za-z_$][A-Za-z0-9_$]*)`?\s*(.*)", line)
-                if match:
-                    params.append((match.group(1), match.group(2).strip()))
-                else:
-                    params.append(("", line[len("@param"):].strip()))
-                continue
-            if line.startswith("@return"):
-                return_desc = line[len("@return"):].strip() or None
-                continue
-            if line.startswith("@throws"):
-                throws_desc.append(line[len("@throws"):].strip())
-                continue
-            description_lines.append(line)
-
-        description = "\n".join(description_lines).strip()
-        return description, params, return_desc, throws_desc
-
-    @classmethod
-    def _summarize_method_comment(cls, comment: Optional[str], limit: int = 48) -> str:
-        description, _, _, _ = cls._parse_method_comment(comment)
-        summary = description.replace("\n", " ").strip()
-        if len(summary) > limit:
-            summary = summary[:limit].rstrip() + "..."
-        return summary
-
-    @staticmethod
-    def _normalize_terms(query: Sequence[str] | str) -> List[str]:
-        if isinstance(query, str):
-            raw_terms = [query]
-        else:
-            raw_terms = list(query)
-
-        terms: List[str] = []
-        for item in raw_terms:
-            if item is None:
-                continue
-            text = str(item).strip()
-            if not text:
-                continue
-            for part in text.split():
-                part = part.strip()
-                if part:
-                    terms.append(part)
-        return terms
-
-    @staticmethod
-    def _build_term_clause(
-        column_expr: str,
-        terms: List[str],
-        *,
-        match_all: bool,
-        use_regex: bool = False,
-    ) -> Tuple[str, List[str]]:
-        if not terms:
-            return "", []
-
-        operator = "REGEXP" if use_regex else "LIKE"
-        glue = " AND " if match_all else " OR "
-        clause_parts: List[str] = []
-        params: List[str] = []
-        for term in terms:
-            clause_parts.append(f"{column_expr} {operator} ?")
-            params.append(term if use_regex else f"%{term}%")
-        return "(" + glue.join(clause_parts) + ")", params
-
-    @staticmethod
-    def _build_prefix_clause(column_expr: str, prefixes: Optional[Sequence[str]]) -> Tuple[str, List[str]]:
-        if not prefixes:
-            return "", []
-        clean_prefixes = [str(prefix).strip() for prefix in prefixes if str(prefix).strip()]
-        if not clean_prefixes:
-            return "", []
-
-        parts = [f"{column_expr} LIKE ?" for _ in clean_prefixes]
-        params = [f"{prefix}%" for prefix in clean_prefixes]
-        return "(" + " OR ".join(parts) + ")", params
-
-    @staticmethod
-    def _build_exact_keyword_clause(column_expr: str, values: Optional[Sequence[str]]) -> Tuple[str, List[str]]:
-        if not values:
-            return "", []
-        clean_values = [str(value).strip() for value in values if str(value).strip()]
-        if not clean_values:
-            return "", []
-
-        parts = [f"LOWER({column_expr}) LIKE ?" for _ in clean_values]
-        params = [f"%{value.lower()}%" for value in clean_values]
-        return "(" + " OR ".join(parts) + ")", params
-
-    def _compose_class_filters(
-        self,
-        *,
-        term_column_expr: str,
-        query_terms: Sequence[str] | str,
-        match_all_terms: bool = False,
-        use_regex: bool = False,
-        class_prefixes: Optional[Sequence[str]] = None,
-        class_regex: Optional[str] = None,
-        class_keywords: Optional[Sequence[str]] = None,
-    ) -> Tuple[str, List[str]]:
-        clauses: List[str] = []
-        params: List[str] = []
-
-        normalized_terms = self._normalize_terms(query_terms)
-        term_clause, term_params = self._build_term_clause(
-            term_column_expr,
-            normalized_terms,
-            match_all=match_all_terms,
-            use_regex=use_regex,
-        )
-        if term_clause:
-            clauses.append(term_clause)
-            params.extend(term_params)
-
-        prefix_clause, prefix_params = self._build_prefix_clause("class_name", class_prefixes)
-        if prefix_clause:
-            clauses.append(prefix_clause)
-            params.extend(prefix_params)
-
-        if class_regex and str(class_regex).strip():
-            clauses.append("(class_name REGEXP ?)")
-            params.append(str(class_regex).strip())
-
-        keyword_clause, keyword_params = self._build_exact_keyword_clause("class_name", class_keywords)
-        if keyword_clause:
-            clauses.append(keyword_clause)
-            params.extend(keyword_params)
-
-        where_sql = " AND ".join(clauses) if clauses else "1=1"
-        return where_sql, params
-
-    @staticmethod
-    def _build_method_relevance_expressions(normalized_terms: Sequence[str], query_label: str) -> Tuple[str, str, List[str]]:
-        select_parts: List[str] = [
-            "CASE WHEN LOWER(method_name) = LOWER(?) THEN 0 ELSE 1 END AS exact_rank",
-            "CASE WHEN LOWER(method_name) LIKE LOWER(?) THEN 0 ELSE 1 END AS prefix_rank",
-        ]
-        params: List[str] = [query_label, f"{query_label}%"]
-
-        if normalized_terms:
-            all_match_parts = ["LOWER(method_name) LIKE LOWER(?)" for _ in normalized_terms]
-            select_parts.append(
-                "CASE WHEN " + " AND ".join(all_match_parts) + " THEN 0 ELSE 1 END AS all_terms_rank"
-            )
-            params.extend([f"%{term}%" for term in normalized_terms])
-
-            ordered_pattern = "%" + "%".join(normalized_terms) + "%"
-            select_parts.append("CASE WHEN LOWER(method_name) LIKE LOWER(?) THEN 0 ELSE 1 END AS ordered_rank")
-            params.append(ordered_pattern)
-
-            comment_match_parts = ["LOWER(COALESCE(method_comment, '')) LIKE LOWER(?)" for _ in normalized_terms]
-            select_parts.append(
-                "CASE WHEN " + " AND ".join(comment_match_parts) + " THEN 0 ELSE 1 END AS comment_rank"
-            )
-            params.extend([f"%{term}%" for term in normalized_terms])
-        else:
-            select_parts.extend([
-                "0 AS all_terms_rank",
-                "0 AS ordered_rank",
-                "0 AS comment_rank",
-            ])
-
-        order_sql = ", ".join([
-            "exact_rank ASC",
-            "all_terms_rank ASC",
-            "ordered_rank ASC",
-            "prefix_rank ASC",
-            "comment_rank ASC",
-            "LENGTH(method_name) ASC",
-            "class_name ASC",
-            "method_name ASC",
-        ])
-        return ", ".join(select_parts), order_sql, params
-
-    def search_methods(
-        self,
-        method_query,
-        page=1,
-        page_size=20,
-        *,
-        match_all_terms: bool = False,
-        class_prefixes: Optional[Sequence[str]] = None,
-        class_regex: Optional[str] = None,
-        class_keywords: Optional[Sequence[str]] = None,
-    ):
-        conn = self._get_conn()
-        if not conn: return f"✖️ 未配置 graph.dbPath，或未在路径 '{self.db_path}' 下找到有效数据库"
-
-        offset = (page - 1) * page_size
-        try:
-            with conn:
-                normalized_terms = self._normalize_terms(method_query)
-                where_sql, where_params = self._compose_class_filters(
-                    term_column_expr="method_name",
-                    query_terms=normalized_terms,
-                    match_all_terms=match_all_terms,
-                    class_prefixes=class_prefixes,
-                    class_regex=class_regex,
-                    class_keywords=class_keywords,
-                )
-
-                count_sql = f"SELECT COUNT(*) as total FROM method_node WHERE {where_sql}"
-                total = conn.execute(count_sql, tuple(where_params)).fetchone()['total']
-                query_label = " ".join(normalized_terms) or str(method_query).strip()
-                relevance_select_sql, order_sql, order_params = self._build_method_relevance_expressions(normalized_terms, query_label)
-
-                sql = """
-                    SELECT class_name, method_name, method_signature, return_type, method_comment,
-                           {relevance_select_sql}
-                    FROM method_node
-                    WHERE {where_sql}
-                    ORDER BY {order_sql}
-                    LIMIT ? OFFSET ?
-                """
-                rows = conn.execute(
-                    sql.format(where_sql=where_sql, order_sql=order_sql, relevance_select_sql=relevance_select_sql),
-                    tuple(order_params + where_params + [page_size, offset]),
-                ).fetchall()
-
-                if not rows:
-                    extra = []
-                    if class_prefixes:
-                        extra.append(f"class-prefix={','.join(class_prefixes)}")
-                    if class_keywords:
-                        extra.append(f"kind={','.join(class_keywords)}")
-                    if class_regex:
-                        extra.append(f"class-regex={class_regex}")
-                    suffix = f"（过滤: {'; '.join(extra)}）" if extra else ""
-                    return f"[Search] 未找到匹配方法 `{query_label}`{suffix}。"
-
-                def relevance_bucket(row):
-                    simple_cls = row['class_name'].rsplit('.', 1)[-1]
-                    cheat_bonus = 0 if (simple_cls, row['method_name']) in self._cheat_methods else 32
-                    return (
-                        cheat_bonus
-                        + int(row["exact_rank"]) * 16
-                        + int(row["all_terms_rank"]) * 8
-                        + int(row["ordered_rank"]) * 4
-                        + int(row["prefix_rank"]) * 2
-                        + int(row["comment_rank"])
-                    )
-
-                if page == 1 and len(rows) >= 3 and all(relevance_bucket(row) <= 4 for row in rows[:3]):
-                    strong_rows = [row for row in rows if relevance_bucket(row) <= 4]
-                    if strong_rows and len(strong_rows) < len(rows):
-                        rows = strong_rows
-
-                total_pages = (total + page_size - 1) // page_size
-                md = [f"### [Method] 方法搜索结果: {query_label} ({page}/{total_pages} 页, 共 {total} 条)\n"]
-                if class_prefixes or class_keywords or class_regex:
-                    filter_desc: List[str] = []
-                    if class_prefixes:
-                        filter_desc.append(f"class-prefix={','.join(class_prefixes)}")
-                    if class_keywords:
-                        filter_desc.append(f"kind={','.join(class_keywords)}")
-                    if class_regex:
-                        filter_desc.append(f"class-regex={class_regex}")
-                    md.append(f"> 过滤条件: {'; '.join(filter_desc)}")
-                    md.append("")
-                full_match_rows = []
-                partial_match_rows = []
-                if len(normalized_terms) >= 2:
-                    for row in rows:
-                        if int(row["all_terms_rank"]) == 0:
-                            full_match_rows.append(row)
-                        else:
-                            partial_match_rows.append(row)
-                else:
-                    full_match_rows = list(rows)
-
-                def append_rows(title: Optional[str], result_rows):
-                    if not result_rows:
-                        return
-                    if title:
-                        md.append(title)
-                    md.append("| 定义类 (Class) | 签名 (Signature) | 说明 (Comment) |")
-                    md.append("| :--- | :--- | :--- |")
-                    for row in result_rows:
-                        comment = self._summarize_method_comment(row["method_comment"])
-                        pretty_signature = self._format_method_signature_for_search(row["method_name"], row["method_signature"], row["return_type"])
-                        simple_cls = row['class_name'].rsplit('.', 1)[-1]
-                        cheat_tag = " ✔️" if (simple_cls, row['method_name']) in self._cheat_methods else ""
-                        md.append(f"| `{row['class_name']}` | `#{row['method_name']}{pretty_signature}`{cheat_tag} | {comment or '-'} |")
-                    md.append("")
-
-                if len(normalized_terms) >= 2 and full_match_rows:
-                    append_rows("#### 全关键词命中", full_match_rows)
-                    if partial_match_rows:
-                        append_rows("#### 部分关键词命中", partial_match_rows)
-                else:
-                    append_rows(None, rows)
-
-                md.append("\n*提示: 使用 `detail <class_name>` 查看类完整继承树和注释。*")
-                return "\n".join(md)
-        except Exception as e: return f"✖️ 搜索失败: {str(e)}"
-
-    def fuzzy_search_classes(
-        self,
-        query,
-        page=1,
-        page_size=20,
-        use_regex=False,
-        *,
-        match_all_terms: bool = False,
-        class_prefixes: Optional[Sequence[str]] = None,
-        class_regex: Optional[str] = None,
-        class_keywords: Optional[Sequence[str]] = None,
-    ):
-        conn = self._get_conn()
-        if not conn:
-            if self.sqlite_error:
-                return f"✖️ 运行环境缺少依赖: {self.sqlite_error}"
-            return f"✖️ 未配置 graph.dbPath，或未在路径 '{self.db_path}' 下找到有效数据库"
-
-        offset = (page - 1) * page_size
-
-        try:
-            with conn:
-                where_sql, where_params = self._compose_class_filters(
-                    term_column_expr="class_name",
-                    query_terms=query,
-                    match_all_terms=match_all_terms,
-                    use_regex=use_regex,
-                    class_prefixes=class_prefixes,
-                    class_regex=class_regex,
-                    class_keywords=class_keywords,
-                )
-                count_sql = f"SELECT COUNT(*) as total FROM class_node WHERE {where_sql}"
-                total_row = conn.execute(count_sql, tuple(where_params)).fetchone()
-                total = total_row['total']
-
-                data_sql = """
-                    SELECT class_name, class_comment
-                    FROM class_node
-                    WHERE {where_sql}
-                    ORDER BY class_name ASC LIMIT ? OFFSET ?
-                """
-                rows = conn.execute(data_sql.format(where_sql=where_sql), tuple(where_params + [page_size, offset])).fetchall()
-
-                query_label = " ".join(self._normalize_terms(query)) or str(query).strip()
-                if not rows:
-                    msg = f"[Search] 未找到匹配 `{query_label}` 的类名"
-                    if use_regex: msg += " (使用正则模式)"
-                    extra = []
-                    if class_prefixes:
-                        extra.append(f"class-prefix={','.join(class_prefixes)}")
-                    if class_keywords:
-                        extra.append(f"kind={','.join(class_keywords)}")
-                    if class_regex:
-                        extra.append(f"class-regex={class_regex}")
-                    if extra:
-                        msg += f"（过滤: {'; '.join(extra)}）"
-                    return msg + f"（第 {page} 页）。"
-
-                total_pages = (total + page_size - 1) // page_size
-                mode_str = "正则" if use_regex else "模糊"
-                md = [f"### [Search] {mode_str}搜索结果 (关键字: {query_label}, 第 {page}/{total_pages} 页, 共 {total} 条)\n"]
-                if class_prefixes or class_keywords or class_regex:
-                    filter_desc: List[str] = []
-                    if class_prefixes:
-                        filter_desc.append(f"class-prefix={','.join(class_prefixes)}")
-                    if class_keywords:
-                        filter_desc.append(f"kind={','.join(class_keywords)}")
-                    if class_regex:
-                        filter_desc.append(f"class-regex={class_regex}")
-                    md.append(f"> 过滤条件: {'; '.join(filter_desc)}")
-                    md.append("")
-                for row in rows:
-                    class_comment = (row['class_comment'] or '').strip()
-                    simple_name = row['class_name'].rsplit('.', 1)[-1]
-                    cheat_tag = " `[速查已收录]`" if simple_name in self._cheat_classes else ""
-                    class_line = f"- **`{row['class_name']}`**{cheat_tag}"
-                    if class_comment:
-                        class_line += f"  \n  > {class_comment}"
-                    md.append(class_line)
-
-                if page < total_pages:
-                    md.append(f"\n*提示: 还有更多结果 (page={page+1})。使用 `detail <classname>` 查看详情。*")
-                else:
-                    md.append("\n*提示: 已显示全部结果。使用 `detail <classname>` 查看详情。*")
-
-                return "\n".join(md)
-        except Exception as e: return f"✖️ 搜索失败: {str(e)}"
-
-    def get_class_details(self, class_name, method_filter: Optional[str] = None, declared_only: bool = False, compact: bool = False):
-        conn = self._get_conn()
-        if not conn:
-            if self.sqlite_error:
-                return f"✖️ 运行环境缺少 sqlite3 依赖: {self.sqlite_error}"
-            return f"✖️ 未配置 graph.dbPath，或未在路径 '{self.db_path}' 下找到有效数据库"
-
-        # SQL with optional method filtering
-        method_clause = ""
-        params = [class_name]
-        if method_filter:
-            method_clause = "AND m.method_name LIKE ?"
-            params.append(f"%{method_filter}%")
-
-        hierarchy_cte = """
-        WITH RECURSIVE hierarchy(class_name, super_class_name, depth) AS (
-            SELECT class_name, super_class_name, 0 FROM class_node WHERE class_name = ?
-        """
-        if not declared_only:
-            hierarchy_cte += """
-            UNION ALL
-            SELECT c.class_name, c.super_class_name, h.depth + 1
-            FROM class_node c JOIN hierarchy h ON c.class_name = h.super_class_name
-            WHERE c.class_name != 'java.lang.Object' AND c.class_name IS NOT NULL
-            """
-        hierarchy_cte += ")"
-
-        sql = f"""
-        {hierarchy_cte}
-        SELECT h.class_name, h.depth, c.class_comment, m.method_name, m.method_signature, m.return_type, m.method_comment
-        FROM hierarchy h JOIN class_node c ON h.class_name = c.class_name
-        LEFT JOIN method_node m ON h.class_name = m.class_name {method_clause}
-        ORDER BY h.depth ASC, m.method_name ASC;
-        """
-        try:
-            with conn:
-                rows = conn.execute(sql, tuple(params)).fetchall()
-                if not rows:
-                    return f"✖️ 未找到类 `{class_name}`" + (f" 或匹配的方法 `{method_filter}`" if method_filter else "") + "。"
-
-                # Check if any methods were found if a filter was provided
-                has_methods = any(r['method_name'] for r in rows)
-                if method_filter and not has_methods:
-                    return f"✖️ 类 `{class_name}` 及其父类中未找到匹配 `{method_filter}` 的方法。"
-
-                chain = []
-                seen_classes = set()
-                for r in rows:
-                    if r['class_name'] not in seen_classes:
-                        chain.append(r['class_name'])
-                        seen_classes.add(r['class_name'])
-
-                method_names = [r['method_name'] for r in rows if r['method_name']]
-                unique_method_names = []
-                seen_method_names = set()
-                for name in method_names:
-                    if name not in seen_method_names:
-                        unique_method_names.append(name)
-                        seen_method_names.add(name)
-
-                md = [f"## `{class_name}`"]
-                class_comment = (rows[0]['class_comment'] or '').strip()
-                if class_comment:
-                    md.append(f"> {class_comment}")
-                if not compact:
-                    if declared_only:
-                        md.append("范围: 仅当前类声明的方法")
-                    elif len(chain) > 1:
-                        md.append(f"继承链: `{' -> '.join(reversed(chain))}`")
-                    if method_filter and len(unique_method_names) == 1:
-                        md.append(f"方法: `{unique_method_names[0]}`")
-
-                last_class = None
-                single_class = len(chain) == 1
-                single_filtered_method = method_filter and len(unique_method_names) == 1
-                for row in rows:
-                    if row['class_name'] != last_class:
-                        if not compact and not single_class:
-                            title = "### 当前类" if row['depth'] == 0 else f"### 父类 L{row['depth']}"
-                            md.append(title)
-                            if row['class_name'] != class_name:
-                                class_comment = (row['class_comment'] or '').strip()
-                                md.append(f"`{row['class_name']}`")
-                                if class_comment:
-                                    md.append(f"> {class_comment}")
-                        last_class = row['class_name']
-                    if row['method_name']:
-                        pretty_signature = self._format_method_signature(row["method_name"], row["method_signature"], row["return_type"])
-                        detail_class_simple = row['class_name'].rsplit('.', 1)[-1]
-                        cheat_tag = " `[速查已收录·免验证]`" if (detail_class_simple, row['method_name']) in self._cheat_methods else ""
-                        if compact:
-                            method_label = row['method_name'] if not (single_filtered_method and len(unique_method_names) == 1) else None
-                            if method_label:
-                                md.append(f"- `{method_label}{pretty_signature}`{cheat_tag}")
-                            else:
-                                md.append(f"- `{pretty_signature}`{cheat_tag}")
-                        elif single_filtered_method:
-                            md.append(f"- `{pretty_signature}`{cheat_tag}")
-                        else:
-                            md.append(f"- **{row['method_name']}** `{pretty_signature}`{cheat_tag}")
-                        description, params, return_desc, throws_desc = self._parse_method_comment(row["method_comment"])
-                        if description:
-                            md.append(f"  - 说明: {description}")
-                        for param_name, param_desc in params:
-                            if param_name and param_desc:
-                                md.append(f"  - 参数 `{param_name}`: {param_desc}")
-                            elif param_name:
-                                md.append(f"  - 参数 `{param_name}`")
-                            elif param_desc:
-                                md.append(f"  - 参数: {param_desc}")
-                        if return_desc:
-                            md.append(f"  - 返回: {return_desc}")
-                        for throws_item in throws_desc:
-                            if throws_item:
-                                md.append(f"  - 异常: {throws_item}")
-                return "\n".join(md)
-        except Exception as e: return f"✖️ 查询失败: {str(e)}"
-
-
-def _split_batch_queries(query_args: list) -> list:
-    """检测逗号分隔的批量查询，返回查询组列表。
-
-    - 无逗号 → [["kw1", "kw2"]]  (单次搜索)
-    - 有逗号 → [["kwA"], ["kwB", "kwC"]]  (批量搜索)
-    """
-    joined = " ".join(query_args)
-    if "," not in joined:
-        return [query_args]
-    groups = [g.strip() for g in joined.split(",") if g.strip()]
-    return [g.split() for g in groups]
-
-
-def main():
-    parser = FriendlyArgumentParser(
-        description="Cosmic API Knowledge CLI — 苍穹 SDK 类名/方法签名离线查询",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""\
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-推荐用法
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  # 查某个领域的 helper
-  %(prog)s --config ok-cosmic.json search Helper --class-prefix kd.bos.servicehelper --kind helper
-
-  # 查某个包下的方法
-  %(prog)s --config ok-cosmic.json search-method send email --class-prefix kd.bos.servicehelper.message
-
-  # 查插件相关类（全部关键词都要命中）
-  %(prog)s --config ok-cosmic.json search plugin operation --kind plugin --all
-
-  # 精确确认某个类有没有目标方法
-  %(prog)s --config ok-cosmic.json detail "类全限定名" --method "关键词"
-
-  # 确认方法是否由当前类自己声明（而非继承）
-  %(prog)s --config ok-cosmic.json detail "类全限定名" --method "关键词" --declared-only
-
-  # 低噪音事实块，适合继续喂给 AI 生成代码
-  %(prog)s --config ok-cosmic.json detail "类全限定名" --method "关键词" --compact
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-AI 调用约束（摘要，完整约束见 SKILL.md 跨脚本硬约束）
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  - 搜索过宽时优先补 --class-prefix 或 --kind 收窄，不要连续无过滤重复搜索。
-  - BOS 核心包前缀: kd.bos.servicehelper / kd.bos.entity / kd.bos.form / kd.bd
-""",
-    )
-    parser.add_argument("--config", help="Path to ok-cosmic.json config file")
-    
-    subparsers = parser.add_subparsers(dest="command", help="Commands")
-    
-    # Search class command
-    search_parser = subparsers.add_parser("search", help="Search for classes (fuzzy or regex)")
-    search_parser.add_argument("query", nargs="+", help="Search keyword(s) or regex pattern")
-    search_parser.add_argument("--regex", action="store_true", help="Use regex for searching")
-    search_parser.add_argument("--all", action="store_true", help="Require all keywords to match. Default is any keyword match")
-    search_parser.add_argument("--class-prefix", action="append", default=[], help="Only include classes under package/class prefix, e.g. kd.bos.servicehelper")
-    search_parser.add_argument("--class-regex", help="Further filter classes by regex on full class name")
-    search_parser.add_argument(
-        "--kind",
-        action="append",
-        default=[],
-        choices=["helper", "servicehelper", "plugin", "service", "utils", "runtime", "entity", "const", "enum", "controller"],
-        help="Common class category filter on class name",
-    )
-    search_parser.add_argument("--page", type=int, default=1, help="Page number")
-    search_parser.add_argument("--page-size", type=int, default=20, help="Items per page")
-    
-    # Search method command
-    msearch_parser = subparsers.add_parser("search-method", help="Search for methods across all classes")
-    msearch_parser.add_argument("query", nargs="+", help="Method name keyword(s)")
-    msearch_parser.add_argument("--all", action="store_true", help="Require all keywords to match. Default is any keyword match")
-    msearch_parser.add_argument("--class-prefix", action="append", default=[], help="Only include methods defined in classes under this prefix")
-    msearch_parser.add_argument("--class-regex", help="Further filter method results by class-name regex")
-    msearch_parser.add_argument(
-        "--kind",
-        action="append",
-        default=[],
-        choices=["helper", "servicehelper", "plugin", "service", "utils", "runtime", "entity", "const", "enum", "controller"],
-        help="Common class category filter on class name",
-    )
-    msearch_parser.add_argument("--page", type=int, default=1, help="Page number")
-    msearch_parser.add_argument("--page-size", type=int, default=20, help="Items per page")
-    
-    # Detail command
-    detail_parser = subparsers.add_parser("detail", help="Get class details")
-    detail_parser.add_argument("classname", help="Full class name(s), comma-separated for batch query")
-    detail_parser.add_argument("--method", help="Filter methods by name (fuzzy)")
-    detail_parser.add_argument("--declared-only", action="store_true", help="Only show methods declared on the target class")
-    detail_parser.add_argument("--compact", action="store_true", help="Compact output for AI consumption")
-    
-    args = parser.parse_args()
-    
-    config = load_project_config(args.config)
-    api = ApiGraph(config)
-    
-    if args.command == "search":
-        query_groups = _split_batch_queries(args.query)
-
-        def _search_one(q):
-            return api.fuzzy_search_classes(
-                q, args.page, args.page_size,
-                use_regex=args.regex,
-                match_all_terms=args.all,
-                class_prefixes=args.class_prefix,
-                class_regex=args.class_regex,
-                class_keywords=args.kind,
-            )
-
-        if len(query_groups) == 1:
-            results = [_search_one(query_groups[0])]
-        else:
-            results = [None] * len(query_groups)
-            with ThreadPoolExecutor(max_workers=min(len(query_groups), 4)) as pool:
-                fut = {pool.submit(_search_one, q): i for i, q in enumerate(query_groups)}
-                for f in as_completed(fut):
-                    idx = fut[f]
-                    try:
-                        results[idx] = f.result()
-                    except Exception as e:
-                        results[idx] = f"✖️ 搜索 `{' '.join(query_groups[idx])}` 失败: {e}"
-        print("\n\n---\n\n".join(results))
-
-    elif args.command == "search-method":
-        query_groups = _split_batch_queries(args.query)
-
-        def _msearch_one(q):
-            return api.search_methods(
-                q, args.page, args.page_size,
-                match_all_terms=args.all,
-                class_prefixes=args.class_prefix,
-                class_regex=args.class_regex,
-                class_keywords=args.kind,
-            )
-
-        if len(query_groups) == 1:
-            results = [_msearch_one(query_groups[0])]
-        else:
-            results = [None] * len(query_groups)
-            with ThreadPoolExecutor(max_workers=min(len(query_groups), 4)) as pool:
-                fut = {pool.submit(_msearch_one, q): i for i, q in enumerate(query_groups)}
-                for f in as_completed(fut):
-                    idx = fut[f]
-                    try:
-                        results[idx] = f.result()
-                    except Exception as e:
-                        results[idx] = f"✖️ 搜索 `{' '.join(query_groups[idx])}` 失败: {e}"
-        print("\n\n---\n\n".join(results))
-    elif args.command == "detail":
-        class_names = [c.strip() for c in args.classname.split(",") if c.strip()]
-
-        def _detail_one(cn):
-            return api.get_class_details(
-                cn,
-                method_filter=args.method,
-                declared_only=args.declared_only,
-                compact=args.compact,
-            )
-
-        if len(class_names) == 1:
-            results = [_detail_one(class_names[0])]
-        else:
-            results = [None] * len(class_names)
-            with ThreadPoolExecutor(max_workers=min(len(class_names), 4)) as pool:
-                future_to_idx = {
-                    pool.submit(_detail_one, cn): i
-                    for i, cn in enumerate(class_names)
-                }
-                for future in as_completed(future_to_idx):
-                    idx = future_to_idx[future]
-                    try:
-                        results[idx] = future.result()
-                    except Exception as e:
-                        results[idx] = f"✖️ 查询 `{class_names[idx]}` 失败: {e}"
-
-        print("\n\n---\n\n".join(results))
-    else:
-        parser.print_help()
-
-
-if __name__ == "__main__":
-    sys.exit(run_cli(main))