@comate/zulu 1.1.0 → 1.2.0

package/comate-engine/assets/skills/auto-commit/scripts/icafe/matching.py

@@ -0,0 +1,778 @@
+"""iCafe 自动检测和匹配逻辑
+
+包含卡片匹配、自动检测和格式化输出功能。
+"""
+
+import datetime
+import json
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Any, Optional, Tuple
+from concurrent.futures import ThreadPoolExecutor
+
+from .client import ICafeQueryClient, DEFAULT_LOOKBACK_DAYS, DEFAULT_MAX_RECORDS
+from git_utils import get_current_user, extract_space_ids_from_git_log
+from .farseer import get_binding_card_types
+from logger import get_logger
+
+logger = get_logger()
+
+
+def is_smart_commit_enabled() -> bool:
+    """检查绑卡提交功能是否启用
+
+    读取 ~/.comate/settings.json 中的 enableSmartCommit 字段。
+    - 值为 false 时返回 False（功能关闭）
+    - 值为 true 或字段不存在时返回 True（默认开启）
+    """
+    settings_path = Path.home() / ".comate" / "settings.json"
+    try:
+        with open(settings_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+        return config.get("enableSmartCommit", True) is not False
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return True  # 文件不存在或解析失败，默认开启
+
+
+# ========================================
+# 自动检测工具函数
+# ========================================
+
+def parse_card_id_from_link(link: str) -> Optional[Dict[str, str]]:
+    """从 iCafe 卡片链接或卡片 ID 中解析卡片 ID 和空间前缀
+
+    Args:
+        link: iCafe 卡片链接或卡片 ID，支持以下格式：
+            - 完整链接: "https://console.cloud.baidu-int.com/devops/icafe/issue/DevOps-iScan-35835/show"
+            - 卡片 ID: "DevOps-iScan-35835"
+
+    Returns:
+        包含 space_prefix 和 card_id 的字典，解析失败返回 None
+        示例：{"space_prefix": "DevOps-iScan", "card_id": "35835"}
+    """
+    # 先尝试直接解析卡片 ID 格式（如 "DevOps-iScan-35835"）
+    card_id_match = re.match(r'^([A-Za-z][A-Za-z0-9_-]*)-(\d+)$', link.strip())
+    if card_id_match:
+        space_prefix = card_id_match.group(1)
+        card_id = card_id_match.group(2)
+        return {"space_prefix": space_prefix, "card_id": card_id}
+
+    # 匹配格式: https://console.cloud.baidu-int.com/devops/icafe/issue/DevOps-iScan-35835/show
+    match = re.match(r'.*/issue/([^/]+)(?:/show)?$', link)
+    if match:
+        full_card_id = match.group(1)
+        # 尝试解析为 "SpacePrefix-ID" 格式
+        card_match = re.match(r'^(.+)-(\d+)$', full_card_id)
+        if card_match:
+            space_prefix = card_match.group(1)
+            card_id = card_match.group(2)
+            return {"space_prefix": space_prefix, "card_id": card_id}
+        # 如果不是标准格式，直接返回完整的 ID
+        return {"space_prefix": "", "card_id": full_card_id}
+    return None
+
+
+def auto_detect_space(
+    client: 'ICafeQueryClient',
+    current_user: Optional[str] = None
+) -> Optional[Dict[str, Any]]:
+    """自动检测当前项目对应的 iCafe 空间
+
+    交叉匹配 git 提交历史中的卡片引用与用户最近访问的空间，
+    返回最近提交过且用户有访问记录的空间信息。
+
+    Args:
+        client: ICafeQueryClient 实例
+        current_user: 用户 ID。未提供时自动从 git config 获取。
+
+    Returns:
+        检测到的空间信息字典，包含：
+        - prefix_code: 空间前缀（如 "dkx"），用于 IQL 查询
+        - space_id: 数字 ID（如 52862），用于 storyRule 等接口
+        - name: 空间名称
+        检测失败时返回 None
+    """
+    # 1. 获取用户 ID
+    user = current_user or get_current_user()
+    if not user:
+        return None
+
+    # 2. 获取最近访问空间
+    try:
+        api_response = client.get_latest_spaces(user)
+    except Exception:
+        return None
+
+    # API 返回格式: {"status": 200, "message": "OK.", "result": [...]}
+    if isinstance(api_response, dict):
+        spaces = api_response.get('result', [])
+    elif isinstance(api_response, list):
+        spaces = api_response
+    else:
+        return None
+
+    if not spaces:
+        return None
+
+    # 构建 prefixCode -> 完整空间信息的映射（小写归一化）
+    prefix_to_space = {}
+    for space in spaces:
+        prefix = space.get('prefixCode', '')
+        if prefix:
+            prefix_to_space[prefix.lower()] = space
+
+    # 3. 用已知前缀从 git log 提取空间引用，然后交叉匹配
+    known_prefixes = [s.get('prefixCode', '') for s in spaces if s.get('prefixCode')]
+    git_space_ids = extract_space_ids_from_git_log(known_prefixes=known_prefixes)
+
+    if git_space_ids:
+        for git_prefix in git_space_ids:
+            key = git_prefix.lower()
+            if key in prefix_to_space:
+                matched = prefix_to_space[key]
+                return {
+                    'prefix_code': matched.get('prefixCode', git_prefix),
+                    'space_id': matched.get('id'),
+                    'name': matched.get('name', ''),
+                }
+
+    # 4. 回退：git log 无结果或交叉匹配失败，取最近访问的第一个空间
+    first = spaces[0]
+    return {
+        'prefix_code': first.get('prefixCode', ''),
+        'space_id': first.get('id'),
+        'name': first.get('name', ''),
+    }
+
+
+def _quote_iql_value(value: str) -> str:
+    """对含 IQL 特殊字符的值加双引号，安全值保持原样"""
+    if re.search(r'[(),\s"]', value):
+        return f'"{value}"'
+    return value
+
+
+def build_type_filter_iql(type_names: List[str]) -> str:
+    """根据卡片类型名称列表构建 IQL 类型过滤条件
+
+    Args:
+        type_names: 类型名称列表，如 ["Bug", "Task", "Story"]
+
+    Returns:
+        IQL 类型过滤表达式，如 '类型 in (Bug, Task, Story)'。
+        含特殊字符的类型名称会自动加双引号。
+        列表为空时返回空字符串。
+    """
+    if not type_names:
+        return ""
+    quoted = [_quote_iql_value(name) for name in type_names]
+    if len(quoted) == 1:
+        return f"类型 = {quoted[0]}"
+    return f"类型 in ({', '.join(quoted)})"
+
+
+# ========================================
+# 空间匹配相关函数
+# ========================================
+
+def fetch_space_issue_types(
+    client: 'ICafeQueryClient',
+    space_prefix: str
+) -> List[Dict[str, Any]]:
+    """获取单个空间的卡片类型列表
+
+    Args:
+        client: ICafeQueryClient 实例
+        space_prefix: 空间前缀
+
+    Returns:
+        格式化的卡片类型列表
+    """
+    try:
+        raw_response = client.get_space_issue_types(space_prefix)
+        formatted_types = []
+        issue_types = None
+        if isinstance(raw_response, dict):
+            if 'result' in raw_response and isinstance(raw_response['result'], dict):
+                issue_types = raw_response['result'].get('issueTypes', [])
+            elif 'issueTypes' in raw_response:
+                issue_types = raw_response['issueTypes']
+            elif 'data' in raw_response and isinstance(raw_response['data'], dict):
+                issue_types = raw_response['data'].get('issueTypes', [])
+        elif isinstance(raw_response, list):
+            issue_types = raw_response
+
+        if issue_types and isinstance(issue_types, list):
+            for t in issue_types:
+                if isinstance(t, dict):
+                    type_id = t.get('id', t.get('issueTypeId', ''))
+                    type_name = t.get('name', t.get('type', ''))
+                    if type_id or type_name:
+                        formatted_types.append({
+                            'id': str(type_id),
+                            'name': str(type_name)
+                        })
+        return formatted_types
+    except Exception:
+        return []
+
+
+def fetch_all_space_types(
+    client: 'ICafeQueryClient',
+    space_code_map: Dict[str, Dict[str, Any]]
+) -> Dict[str, List[Dict[str, Any]]]:
+    """并行获取所有空间的卡片类型
+
+    Args:
+        client: ICafeQueryClient 实例
+        space_code_map: 空间前缀 -> 空间信息的映射
+
+    Returns:
+        空间前缀 -> 卡片类型列表的映射
+    """
+    space_types_map: Dict[str, List[Dict[str, Any]]] = {}
+    with ThreadPoolExecutor(max_workers=5) as pool:
+        # 同时提交所有任务并记录对应的前缀
+        future_to_prefix = {}
+        for prefix_key, space_info in space_code_map.items():
+            original_prefix = space_info.get('prefixCode', prefix_key)
+            future = pool.submit(fetch_space_issue_types, client, original_prefix)
+            future_to_prefix[future] = prefix_key
+
+        # 收集结果
+        for future in future_to_prefix:
+            types_list = future.result()
+            prefix_key = future_to_prefix[future]
+            space_types_map[prefix_key] = types_list
+
+    return space_types_map
+
+
+def resolve_space(
+    client: 'ICafeQueryClient',
+    user: str,
+    space_prefix: Optional[str],
+    spaces_future,
+    git_log_future
+) -> Tuple[str, Optional[int], str, Dict[str, Dict[str, Any]]]:
+    """解析并匹配空间
+
+    Args:
+        client: ICafeQueryClient 实例
+        user: 用户 ID
+        space_prefix: 指定的空间前缀
+        spaces_future: 并行获取的空间列表 Future
+        git_log_future: 并行获取的 git log Future
+
+    Returns:
+        (space_prefix, space_id_num, space_name, space_code_map)
+    """
+    space_id_num: Optional[int] = None
+    space_name: str = ""
+    space_code_map: Dict[str, Dict[str, Any]] = {}
+
+    try:
+        api_response = spaces_future.result()
+        spaces_list = (api_response.get('result', [])
+                       if isinstance(api_response, dict) else api_response)
+        for s in (spaces_list or []):
+            if isinstance(s, dict):
+                code = s.get('prefixCode', '')
+                if code:
+                    space_code_map[code.lower()] = s
+        logger.info("获取到 %d 个最近访问空间: %s", len(space_code_map), list(space_code_map.keys()))
+    except Exception as e:
+        logger.warning("获取空间列表失败: %s", e)
+
+    # 匹配空间
+    if space_prefix:
+        matched = space_code_map.get(space_prefix.lower())
+        if matched:
+            space_id_num = matched.get('id')
+            space_name = matched.get('name', '')
+            space_prefix = matched.get('prefixCode', space_prefix)
+            logger.info("空间精确匹配成功: prefix=%s, id=%s, name=%s", space_prefix, space_id_num, space_name)
+    else:
+        # 用已知前缀重新跑 git log 精确匹配
+        known_prefixes = [s.get('prefixCode', '') for s in space_code_map.values() if s.get('prefixCode')]
+        git_space_ids = git_log_future.result()
+
+        # 如果有已知前缀但 git_log 返回的是旧的正则结果，需要重新精确匹配
+        if known_prefixes:
+            git_space_ids = extract_space_ids_from_git_log(known_prefixes=known_prefixes)
+
+        logger.info("git log 提取的前缀: %s", git_space_ids)
+
+        matched_space = None
+        if git_space_ids:
+            for git_prefix in git_space_ids:
+                if git_prefix.lower() in space_code_map:
+                    matched_space = space_code_map[git_prefix.lower()]
+                    logger.info("交叉匹配成功: prefix=%s", git_prefix)
+                    break
+
+        if not matched_space and space_code_map:
+            matched_space = next(iter(space_code_map.values()))
+            logger.warning("交叉匹配无结果，回退到最近访问空间: %s", matched_space.get('prefixCode', ''))
+
+        if matched_space:
+            space_prefix = matched_space.get('prefixCode', '')
+            space_id_num = matched_space.get('id')
+            space_name = matched_space.get('name', '')
+        elif not space_code_map and git_space_ids:
+            # space_code_map 为空（API 无返回），使用 git log 最高频前缀兜底
+            # 此时没有 space_id_num，但 IQL 查询仍可通过 space_prefix 工作
+            space_prefix = git_space_ids[0]
+            logger.warning(
+                "最近访问空间列表为空，使用 git log 最高频前缀兜底: %s",
+                space_prefix,
+            )
+            # 补全 space_code_map，使 available_spaces 和 space_types_map 不为空
+            space_code_map[space_prefix.lower()] = {
+                'prefixCode': space_prefix,
+                'id': None,
+                'name': '',
+            }
+
+    if not space_prefix:
+        # 收集候选前缀信息，帮助 Agent 快速重试
+        candidates = []
+        try:
+            fallback_ids = git_log_future.result() if not git_space_ids else git_space_ids
+            candidates = fallback_ids[:5] if fallback_ids else []
+        except Exception:
+            pass
+        hint = ""
+        if candidates:
+            hint = f"，git log 中发现的候选前缀: {candidates}"
+        if not space_code_map:
+            hint += "（注意：最近访问空间列表为空，可能是 API 权限问题或用户无最近访问空间）"
+        logger.error("无法自动检测空间%s", hint)
+        raise ValueError(
+            f"无法自动检测空间，请通过 space_prefix 参数指定空间前缀{hint}"
+        )
+
+    return space_prefix, space_id_num, space_name, space_code_map
+
+
+def build_type_filter(
+    space_id_num: Optional[int],
+    include_type_filter: bool
+) -> Tuple[str, List[Dict[str, Any]]]:
+    """构建类型过滤 IQL
+
+    Args:
+        space_id_num: 空间数字 ID
+        include_type_filter: 是否启用类型过滤
+
+    Returns:
+        (type_filter, available_types)
+    """
+    type_filter = ""
+    available_types = []
+
+    if include_type_filter and space_id_num is not None:
+        type_items = get_binding_card_types(space_id_num)
+        available_types = type_items
+        type_names = [t['name'] for t in type_items]
+        type_filter = build_type_filter_iql(type_names)
+
+    return type_filter, available_types
+
+
+def build_iql_and_query(
+    client: 'ICafeQueryClient',
+    space_prefix: str,
+    space_id_num: Optional[int],
+    lookback_days: int,
+    type_filter: str,
+    max_records: int
+) -> Dict[str, Any]:
+    """构建 IQL 并查询卡片
+
+    Args:
+        client: ICafeQueryClient 实例
+        space_prefix: 空间前缀
+        space_id_num: 空间数字 ID
+        lookback_days: 回溯天数
+        type_filter: 类型过滤 IQL
+        max_records: 最大记录数
+
+    Returns:
+        查询结果
+    """
+    cutoff_date = (datetime.date.today() - datetime.timedelta(days=lookback_days)).isoformat()
+    active_iql = (
+        '负责人 = currentUser'
+        ' AND 流程状态 in (开发中, 进行中, 待开发, 新建, open)'
+        f' AND 最后修改时间 > "{cutoff_date}"'
+    )
+
+    if type_filter:
+        final_iql = f"{type_filter} AND ({active_iql})"
+    else:
+        final_iql = active_iql
+
+    try:
+        result = client.query_cards(
+            space_id=space_prefix,
+            iql=final_iql,
+            max_records=max_records,
+            is_desc=True,
+            order="最后修改时间",
+        )
+    except Exception as e:
+        logger.error("IQL 查询异常: %s", e)
+        result = {"cards": []}
+
+    # 提取简化卡片列表
+    raw_cards = result.get("cards", [])
+    cards = []
+    for card in raw_cards:
+        raw_type = card.get("type", "")
+        card_type = (raw_type.get("name", str(raw_type))
+                     if isinstance(raw_type, dict) else str(raw_type))
+        raw_status = card.get("status", "")
+        card_status = (raw_status.get("name", str(raw_status))
+                       if isinstance(raw_status, dict) else str(raw_status))
+        cards.append({
+            "sequence": card.get("sequence", ""),
+            "title": card.get("title", ""),
+            "type": card_type,
+            "status": card_status,
+        })
+
+    return {"cards": cards, "final_iql": final_iql}
+
+
+def build_output(
+    space_prefix: str,
+    space_id_num: Optional[int],
+    space_name: str,
+    cards: List[Dict],
+    final_iql: str,
+    available_types: List[Dict],
+    space_code_map: Dict[str, Dict[str, Any]],
+    space_types_map: Dict[str, List[Dict]],
+) -> Dict[str, Any]:
+    """构建最终输出
+
+    Args:
+        space_prefix: 空间前缀
+        space_id_num: 空间数字 ID
+        space_name: 空间名称
+        cards: 卡片列表
+        final_iql: 最终 IQL
+        available_types: 可用类型列表
+        space_code_map: 空间映射
+        space_types_map: 空间类型映射
+
+    Returns:
+        完整的输出字典
+    """
+    # 默认兜底卡片类型
+    _fallback_types = [
+        {"id": "5007", "name": "Story"},
+        {"id": "54444", "name": "Task"},
+        {"id": "5009", "name": "Bug"},
+    ]
+
+    # 构建可用空间列表（包含每个空间的卡片类型）
+    available_spaces = []
+    for s in space_code_map.values():
+        prefix = s.get('prefixCode', '')
+        types = space_types_map.get(prefix.lower(), [])
+        available_spaces.append({
+            "id": s.get('id'),
+            "prefix": prefix,
+            "name": s.get('name', ''),
+            "types": types if types else _fallback_types
+        })
+
+    # 构建默认值
+    defaults = {
+        "title": "",
+        "type_id": "",
+        "space_id": space_id_num
+    }
+    # 优先使用 farseer 的绑定类型（更精准，仅含绑定了代码提交流程的类型）
+    # 兜底使用 space_types_map 的全量类型
+    current_space_types = space_types_map.get(space_prefix.lower(), []) if space_prefix else []
+    if available_types:
+        defaults["type_id"] = available_types[0]["id"]
+    elif current_space_types:
+        defaults["type_id"] = current_space_types[0]["id"]
+
+    output: Dict[str, Any] = {
+        "cards": cards,
+        "space_prefix": space_prefix,
+        "space_id": space_id_num,
+        "space_name": space_name,
+        "final_iql": final_iql,
+        "available_types": available_types,
+        "available_spaces": available_spaces,
+        "defaults": defaults,
+    }
+
+    return output
+
+
+def build_match_prompt(
+    diff_summary: Dict[str, Any],
+    cards: List[Dict[str, str]],
+    space_prefix: str,
+) -> str:
+    """构建卡片匹配的 LLM 提示词（内部函数）"""
+    files_list = "\n".join(f"  - {f}" for f in diff_summary["changed_files"])
+
+    card_lines = []
+    for card in cards:
+        seq = card["sequence"]
+        card_id = f"{space_prefix}-{seq}" if seq else "N/A"
+        card_lines.append(
+            f"  - [{card_id}] ({card['type']}) {card['title']}  [状态: {card['status']}]"
+        )
+    cards_text = "\n".join(card_lines) if card_lines else "  (无匹配卡片)"
+
+    truncation_note = ""
+    if diff_summary.get("truncated"):
+        truncation_note = "\n注意：diff 内容因过长已被截断，请基于已展示部分进行判断。\n"
+
+    return f"""请根据以下 git diff 变更内容，对每张候选 iCafe 卡片进行语义匹配度评分，并生成 commit message。
+
+## 变更文件
+{files_list}
+
+## 变更统计
+{diff_summary["stat_summary"]}
+
+## Git Diff 内容
+```
+{diff_summary["diff_content"]}
+```
+{truncation_note}
+## 候选卡片列表
+{cards_text}
+
+## 评分要求
+
+请对**每张**候选卡片进行匹配度评分（0-100 分），评分维度：
+- **语义相关性**（主要）：diff 修改的模块、函数、业务逻辑是否与卡片标题描述的任务相关
+- **类型匹配度**（次要）：diff 的变更性质（修复 bug、新增功能、重构等）是否与卡片类型吻合
+- 60 分及以上视为"匹配"，低于 60 分视为"不匹配"
+
+## 输出格式
+
+请严格按以下 JSON 格式输出，不要输出其他内容：
+
+```json
+{{
+  "ranked_cards": [
+    {{"sequence": "<卡片序号>", "score": <0-100>, "reason": "<一句话匹配理由>"}},
+    ...
+  ],
+  "has_good_match": <true|false>,
+  "recommended_commit_message": "<{space_prefix}-<序号> <简要描述>>"
+}}
+```
+
+说明：
+- `ranked_cards`：所有候选卡片按 score 降序排列，每张卡片都必须包含
+- `has_good_match`：是否存在 score >= 60 的卡片
+- `recommended_commit_message`：如果有匹配卡片，基于最佳匹配卡片生成；如果无匹配卡片，基于 diff 内容生成（卡片 ID 部分留空为 `{space_prefix}-???`）
+- **低于 60 分的卡片将被过滤，不会展示给用户**"""
+
+
+# ========================================
+# 主入口函数
+# ========================================
+
+def find_matching_card(
+    client: Optional['ICafeQueryClient'] = None,
+    space_prefix: Optional[str] = None,
+    current_user: Optional[str] = None,
+    max_records: int = DEFAULT_MAX_RECORDS,
+    lookback_days: int = DEFAULT_LOOKBACK_DAYS,
+    include_type_filter: bool = True,
+) -> Dict[str, Any]:
+    """查询当前用户的活跃 iCafe 卡片
+
+    封装完整流程：
+    1. 并行获取：当前用户 / 最近访问空间 / git log
+    2. 交叉匹配确定 iCafe 空间
+    3. 构建 IQL 查询卡片
+
+    注意：git diff 获取已移至 Agent 侧执行，以支持多 workspace 场景。
+    脚本仅负责 iCafe 数据获取。
+
+    Args:
+        client: ICafeQueryClient 实例。未提供时自动创建。
+        space_prefix: 空间前缀（如 "dkx"）。未提供时自动检测。
+        current_user: 用户 ID。未提供时自动获取。
+        max_records: 查询卡片的最大数量，默认 20。
+        lookback_days: 回溯天数，默认 14。
+        include_type_filter: 是否调用 farseer 获取卡片类型过滤，默认 True。
+
+    Returns:
+        {
+            "cards": [ { sequence, title, type, status }, ... ],
+            "space_prefix": "...",
+            "space_id": 12345,
+            "space_name": "空间名称",
+            "final_iql": "...",
+            "available_types": [{"id": "5009", "name": "Bug"}, ...],
+            "available_spaces": [{"id": 12345, "prefix": "dkx", "name": "空间名称"}, ...],
+            "defaults": {
+                "title": "",         # 由 Agent 根据 diff 生成
+                "type_id": "5009",   # 默认卡片类型 ID
+                "space_id": 12345    # 默认空间 ID
+            }
+        }
+
+    Raises:
+        ValueError: 无法确定空间或用户时
+    """
+    # 前置检查：绑卡提交开关
+    if not is_smart_commit_enabled():
+        logger.info("绑卡提交功能已关闭，跳过执行")
+        return {"disabled": True, "message": "绑卡提交功能已关闭（enableSmartCommit: false）"}
+
+    logger.info("find_matching_card 开始执行, include_type_filter=%s", include_type_filter)
+
+    if client is None:
+        client: ICafeQueryClient = ICafeQueryClient()
+
+    # ---- 阶段 1：并行获取本地 git 数据 + API 空间列表 ----
+    user = current_user or get_current_user()
+    if not user:
+        logger.error("无法获取当前用户 ID")
+        raise ValueError("无法获取当前用户 ID，请通过 current_user 参数指定")
+
+    logger.info("提交并行任务: get_latest_spaces(user=%s), extract_git_log", user)
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        spaces_future = pool.submit(client.get_latest_spaces, user)
+        git_log_future = pool.submit(extract_space_ids_from_git_log)
+
+    # ---- 阶段 2：解析空间列表 + 匹配空间 + 获取各空间卡片类型 ----
+    try:
+        space_prefix, space_id_num, space_name, space_code_map = resolve_space(
+            client, user, space_prefix, spaces_future, git_log_future
+        )
+        logger.info("空间匹配结果: prefix=%s, id=%s, name=%s", space_prefix, space_id_num, space_name)
+    except Exception as e:
+        logger.error("空间解析失败: %s", e)
+        raise
+
+    # 并行获取所有空间的卡片类型
+    space_types_map = fetch_all_space_types(client, space_code_map)
+    logger.info("获取到 %d 个空间的卡片类型", len(space_types_map))
+
+    # ---- 阶段 3：构建 IQL 并查询卡片 ----
+    type_filter, available_types = build_type_filter(space_id_num, include_type_filter)
+
+    # farseer 获取类型失败时（如 space_id_num 为 None），从 space_types_map 兜底
+    if not available_types and space_prefix:
+        available_types = space_types_map.get(space_prefix.lower(), [])
+
+    # 最终兜底：如果仍然为空，使用默认的三种常用卡片类型
+    if not available_types:
+        available_types = [
+            {"id": "5007", "name": "Story"},
+            {"id": "5009", "name": "Bug"},
+            {"id": "54444", "name": "Task"},
+        ]
+        logger.warning("可绑定卡片类型为空，使用默认兜底类型: Story, Bug, Task")
+
+    result = build_iql_and_query(client, space_prefix, space_id_num, lookback_days, type_filter, max_records)
+    logger.info("IQL 查询完成, 获得 %d 张卡片, iql=%s", len(result["cards"]), result["final_iql"])
+
+    # ---- 阶段 4：构建输出 ----
+    output = build_output(
+        space_prefix=space_prefix,
+        space_id_num=space_id_num,
+        space_name=space_name,
+        cards=result["cards"],
+        final_iql=result["final_iql"],
+        available_types=available_types,
+        space_code_map=space_code_map,
+        space_types_map=space_types_map,
+    )
+    logger.info("find_matching_card 执行完成, 返回 %d 张卡片", len(output.get("cards", [])))
+    return output
+
+
+def match_diff_to_cards(
+    client: Optional['ICafeQueryClient'] = None,
+    space_prefix: Optional[str] = None,
+    current_user: Optional[str] = None,
+    max_records: int = DEFAULT_MAX_RECORDS,
+) -> Dict[str, Any]:
+    """向后兼容包装器，委托给 find_matching_card()"""
+    return find_matching_card(
+        client=client,
+        space_prefix=space_prefix,
+        current_user=current_user,
+        max_records=max_records,
+        include_type_filter=True,
+    )
+
+
+# ========================================
+# 格式化输出函数
+# ========================================
+
+def format_card_summary(card: Dict[str, Any], space_id: str) -> str:
+    """将卡片数据格式化为易读的摘要文本
+
+    Args:
+        card: 卡片数据字典
+        space_id: 空间 ID（用于生成链接）
+
+    Returns:
+        格式化的卡片摘要字符串
+    """
+    card_id = card.get('sequence') or card.get('id', 'N/A')
+    title = card.get('title', '无标题')
+    status = card.get('status', 'N/A')
+    assignee = card.get('assignee', 'N/A')
+    card_type = card.get('type', 'N/A')
+    priority = card.get('priority', 'N/A')
+    created = card.get('createdAt', card.get('created_at', 'N/A'))
+    updated = card.get('updatedAt', card.get('updated_at', 'N/A'))
+
+    url = f"https://console.cloud.baidu-int.com/devops/icafe/issue/{space_id}-{card_id}/show"
+
+    lines = [
+        f"[{card_id}] {title}",
+        f"  类型: {card_type} | 状态: {status} | 优先级: {priority}",
+        f"  负责人: {assignee}",
+        f"  创建时间: {created} | 更新时间: {updated}",
+        f"  链接: {url}",
+    ]
+    return "\n".join(lines)
+
+
+def format_query_result(result: Dict[str, Any], space_id: str) -> str:
+    """将查询结果格式化为易读的文本
+
+    Args:
+        result: query_cards 返回的结果字典
+        space_id: 空间 ID
+
+    Returns:
+        格式化的查询结果字符串
+    """
+    cards = result.get('cards', result.get('data', []))
+    total = result.get('total', result.get('totalCount', len(cards)))
+
+    if not cards:
+        return "未查询到符合条件的卡片。"
+
+    lines = [f"共查询到 {total} 张卡片：\n"]
+    for i, card in enumerate(cards, 1):
+        lines.append(f"--- 卡片 {i} ---")
+        lines.append(format_card_summary(card, space_id))
+        lines.append("")
+
+    return "\n".join(lines)