@comate/zulu 1.1.0 → 1.2.0

package/comate-engine/assets/skills/smart-commit/references/query_reference.md

@@ -0,0 +1,176 @@
+# iCafe 卡片查询 IQL 完整参考
+
+## API 端点
+
+### 条件查询卡片
+
+```
+GET {base_url}/api/spaces/{space_id}/cards?iql={iql_expression}
+```
+
+**请求参数：**
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| space_id | path | string | 是 | 空间 ID |
+| iql | query | string | 是 | IQL 查询表达式 |
+| page | query | int | 否 | 页码 |
+| showDetail | query | flag | 否 | 显示详情（传空字符串即可） |
+| showAssociations | query | flag | 否 | 显示关联信息 |
+| isDesc | query | flag | 否 | 降序排列 |
+| order | query | string | 否 | 排序字段 |
+| showChildren | query | flag | 否 | 显示子卡片 |
+| maxRecords | query | int | 否 | 最大返回数 |
+| showOkr | query | flag | 否 | 显示 OKR |
+| showAccumulate | query | flag | 否 | 显示累计信息 |
+
+**响应示例：**
+
+```json
+{
+  "cards": [
+    {
+      "id": "12345",
+      "sequence": "628",
+      "title": "示例卡片",
+      "type": "Bug",
+      "status": "新建",
+      "assignee": "dongkexin01",
+      "priority": "P1-High",
+      "createdAt": "2025-01-15 10:30:00",
+      "updatedAt": "2025-01-16 14:20:00"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "pageSize": 20
+}
+```
+
+### 获取单张卡片
+
+```
+GET {base_url}/api/spaces/{space_id}/cards/{card_id}
+```
+
+### 查询最近访问空间
+
+```
+GET {base_url}/api/v2/space/latest?currentUser={user_id}
+```
+
+### 获取空间计划
+
+```
+GET {base_url}/api/v2/space/{space_id}/plans
+```
+
+## IQL 查询语法完整参考
+
+### 运算符
+
+| 运算符 | 含义 | 适用类型 | 示例 |
+|--------|------|----------|------|
+| `=` | 等于 | 所有类型 | `类型 = Bug` |
+| `!=` | 不等于 | 所有类型 | `状态 != 已完成` |
+| `>` | 大于 | 日期、数字、流程状态 | `创建时间 > "2025-01-01"` |
+| `<` | 小于 | 日期、数字、流程状态 | `优先级数值 < 3` |
+| `>=` | 大于等于 | 流程状态、数字 | `流程状态 >= 开发中` |
+| `<=` | 小于等于 | 流程状态、数字 | `流程状态 <= 开发中` |
+| `in ()` | 在列表中 | 人员、类型、状态、标签等 | `类型 in (Bug, Story)` |
+| `not in ()` | 不在列表中 | 人员、类型、状态、标签等 | `状态 not in (已完成, 已关闭)` |
+| `is empty` | 为空 | 所有类型 | `负责人 is empty` |
+| `is not empty` | 不为空 | 所有类型 | `截止日期 is not empty` |
+| `~` | 包含（模糊匹配） | 标题、文本、关键字、URL | `标题 ~ 登录` |
+| `!~` | 不包含 | 标题、文本 | `标题 !~ 测试` |
+| `AND` | 逻辑与 | 连接多个条件 | `类型 = Bug AND 状态 = 新建` |
+| `OR` | 逻辑或 | 连接多个条件 | `类型 = Bug OR 类型 = Story` |
+| `()` | 分组 | 控制优先级 | `(类型 = Bug OR 类型 = Story) AND 负责人 = currentUser` |
+
+### 字段参考
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| 类型 | 枚举 | Bug, Story, Task, Epic 等 |
+| 负责人 | 人员 | 用户 ID，如 "dongkexin01" |
+| 创建人 | 人员 | 用户 ID |
+| 流程状态 | 状态枚举 | 新建, 待开发, 开发中, 进行中, 已完成 等 |
+| 优先级 | 枚举 | P0-Urgent, P1-High, P2-Medium, P3-Low 等 |
+| 创建时间 | 日期 | 格式 "YYYY-MM-DD" 或 "YYYY-MM-DD HH:mm:ss" |
+| 更新时间 | 日期 | 格式同上 |
+| 截止日期 | 日期 | 格式同上 |
+| 标题 | 文本 | 卡片标题 |
+| 关键字 | 文本 | 全文搜索关键字 |
+| Label | 标签 | 卡片标签 |
+| 所属计划 | 树 | 需要完整路径，如 "测试/测试1" |
+
+### 常用查询模式
+
+#### 按类型查询
+
+```
+类型 = Bug
+类型 in (Bug, Story, Task)
+类型 != Epic
+```
+
+#### 按人员查询
+
+```
+负责人 = currentUser
+负责人 = dongkexin01
+创建人 = v_liuxiang
+负责人 in (user1, user2, user3)
+负责人 is empty
+```
+
+#### 按状态查询
+
+```
+流程状态 = 新建
+流程状态 in (新建, 开发中, 待开发, 进行中)
+流程状态 <= 开发中
+流程状态 != 已完成
+```
+
+#### 按时间查询
+
+```
+创建时间 > "2025-01-01"
+创建时间 > "2025-01-01 00:00:00" AND 创建时间 < "2025-06-30 23:59:59"
+更新时间 > "2025-03-01"
+```
+
+#### 按内容查询
+
+```
+标题 ~ 登录
+标题 !~ 测试
+关键字 ~ 性能优化
+```
+
+#### 组合查询
+
+```
+类型 = Bug AND 负责人 = currentUser AND 流程状态 != 已完成
+(类型 = Bug OR 类型 = Story) AND 优先级 = P1-High
+创建人 = dongkexin01 AND 创建时间 > "2025-01-01" AND 流程状态 in (新建, 开发中)
+```
+
+## 认证说明
+
+所有请求需要 `x-ac-Authorization` header。Token 获取优先级：
+
+1. 环境变量 `COMATE_AUTH_TOKEN`
+2. 文件 `~/.comate/login`
+
+## 错误码
+
+| HTTP 状态码 | 说明 |
+|-------------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误（如 IQL 语法错误） |
+| 401 | 认证失败（token 无效或过期） |
+| 403 | 无权限访问该空间 |
+| 404 | 空间或卡片不存在 |
+| 500 | 服务端错误 |

package/comate-engine/assets/skills/smart-commit/scripts/compat.py

@@ -0,0 +1,86 @@
+"""
+版本兼容性检测模块
+
+用于检测当前 IDE 版本是否支持自定义交互式 UI
+"""
+
+# 支持自定义 UI 的最低版本
+MIN_INTERACTIVE_VERSION = '1.2.0'
+
+
+def parse_version(version_str: str) -> tuple:
+    """
+    解析版本号字符串为可比较的元组
+
+    Args:
+        version_str: 版本号字符串，如 "1.2.3"
+
+    Returns:
+        版本号元组，如 (1, 2, 3)
+    """
+    try:
+        parts = version_str.split('.')
+        return tuple(int(p) for p in parts[:3])
+    except (ValueError, AttributeError):
+        return (0, 0, 0)
+
+
+def is_interactive_ui_supported(ide_name: str, plugin_version: str) -> bool:
+    """
+    检测当前 IDE 版本是否支持自定义交互式 UI
+
+    Args:
+        ide_name: 从 ${COMATE_IDE_NAME} 获取的值
+        plugin_version: 从 ${COMATE_PLUGIN_VERSION} 获取的值
+
+    Returns:
+        True 如果支持自定义 UI，否则 False
+    """
+    # 1. 检测占位符是否被替换
+    # 旧版本 CLI 不支持这些占位符，值仍为 "${...}" 原样
+    if not ide_name or ide_name.startswith('${'):
+        return False
+    if not plugin_version or plugin_version.startswith('${'):
+        return False
+
+    # 2. 版本号比较
+    current = parse_version(plugin_version)
+    minimum = parse_version(MIN_INTERACTIVE_VERSION)
+
+    return current >= minimum
+
+
+def check_interactive_support(ide_name: str, plugin_version: str) -> str:
+    """
+    检测并返回应使用的流程模式
+
+    Args:
+        ide_name: 从 ${COMATE_IDE_NAME} 获取的值
+        plugin_version: 从 ${COMATE_PLUGIN_VERSION} 获取的值
+
+    Returns:
+        "INTERACTIVE_MODE" 或 "FALLBACK_MODE"
+    """
+    if is_interactive_ui_supported(ide_name, plugin_version):
+        return "INTERACTIVE_MODE"
+    return "FALLBACK_MODE"
+
+
+if __name__ == "__main__":
+    # 测试用例
+    test_cases = [
+        ("vscode", "1.2.0", "INTERACTIVE_MODE"),
+        ("vscode", "1.3.5", "INTERACTIVE_MODE"),
+        ("vscode", "1.1.9", "FALLBACK_MODE"),
+        ("vscode", "0.9.0", "FALLBACK_MODE"),
+        ("${COMATE_IDE_NAME}", "1.2.0", "FALLBACK_MODE"),
+        ("vscode", "${COMATE_PLUGIN_VERSION}", "FALLBACK_MODE"),
+        ("", "1.2.0", "FALLBACK_MODE"),
+        ("vscode", "", "FALLBACK_MODE"),
+    ]
+
+    print("Running compatibility check tests...")
+    for ide, version, expected in test_cases:
+        result = check_interactive_support(ide, version)
+        status = "PASS" if result == expected else "FAIL"
+        print(f"[{status}] ide={ide!r}, version={version!r} -> {result} (expected: {expected})")

package/comate-engine/assets/skills/smart-commit/scripts/create_card_cli.py

@@ -0,0 +1,67 @@
+"""命令行工具：创建 iCafe 卡片
+
+用法:
+    python3 create_card_cli.py --title "标题" --space-prefix "dkx" --type-name "Bug" --username "dongkexin01"
+
+输出:
+    JSON 格式的创建结果，包含 sequence、title、spacePrefix 等字段。
+    失败时输出 {"error": "错误信息"}。
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from icafe.client import ICafeQueryClient
+from git_utils import get_current_user
+
+
+def main():
+    """解析命令行参数并调用 iCafe 接口创建卡片。"""
+    parser = argparse.ArgumentParser(description="创建 iCafe 卡片")
+    parser.add_argument("--title", required=True, help="卡片标题")
+    parser.add_argument("--space-prefix", required=True, help="空间前缀，如 dkx")
+    parser.add_argument("--type-name", required=True, help="卡片类型名称，如 Bug")
+    parser.add_argument("--description", default="", help="卡片描述")
+    parser.add_argument("--username", default=None, help="用户名，如 dongkexin01")
+    args = parser.parse_args()
+
+    try:
+        client = ICafeQueryClient()
+        assignee = get_current_user(username=args.username)
+
+        created = client.create_card(
+            title=args.title,
+            space_id=args.space_prefix,
+            card_type=args.type_name,
+            description=args.description,
+            assignee_id=assignee,
+        )
+
+        if created:
+            issues = created.get("issues", [])
+            if issues:
+                sequence = issues[0].get("sequence")
+                print(json.dumps({
+                    "success": True,
+                    "sequence": str(sequence),
+                    "title": args.title,
+                    "type": args.type_name,
+                    "status": "新建",
+                    "spacePrefix": args.space_prefix,
+                }))
+            else:
+                print(json.dumps({"error": "创建卡片成功但无法获取序列号"}))
+        else:
+            print(json.dumps({"error": "创建卡片失败，请重试"}))
+    except Exception as e:
+        err_name = type(e).__name__
+        print(json.dumps({"error": f"创建卡片异常: {err_name}: {e}"}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/comate-engine/assets/skills/smart-commit/scripts/git_utils.py

@@ -0,0 +1,220 @@
+"""Git 工具函数"""
+
+import os
+import subprocess
+import re
+from typing import Dict, List, Any, Optional
+
+from icafe.client import (
+    DEFAULT_MAX_COMMITS,
+    DEFAULT_MAX_DIFF_LINES,
+    GIT_LOG_FALSE_POSITIVE_PREFIXES,
+)
+from logger import get_logger
+
+logger = get_logger()
+
+
+def _get_username_from_arg_or_env(username: Optional[str] = None) -> Optional[str]:
+    """从命令行参数或环境变量获取用户名
+
+    优先使用传入的 username 参数（来自命令行 --username），
+    回退到环境变量 COMATE_USERNAME。
+
+    Args:
+        username: 通过命令行参数传入的用户名
+
+    Returns:
+        用户名字符串；未设置或未替换时返回 None
+    """
+    # 优先使用命令行参数
+    if username and 'COMATE_USERNAME' not in username:
+        return username
+    # 回退到环境变量
+    value = os.environ.get('COMATE_USERNAME', '')
+    if value and 'COMATE_USERNAME' not in value:
+        return value
+    return None
+
+
+def get_current_user(username: Optional[str] = None) -> Optional[str]:
+    """获取当前用户 ID
+
+    优先级：
+    1. 通过参数传入的用户名（来自命令行 --username）
+    2. 环境变量 COMATE_USERNAME
+    3. git config user.email 提取 @ 前的用户名
+    4. git config user.name
+
+    Args:
+        username: 通过命令行参数传入的用户名
+
+    Returns:
+        用户 ID 字符串，如 "dongkexin01"；无法获取时返回 None
+    """
+    # 1. 优先从参数或环境变量获取用户名
+    comate_username = _get_username_from_arg_or_env(username)
+    logger.info("skill.md username: %s", comate_username)
+    if comate_username:
+        logger.info("用户识别: source=arg_or_env, user=%s", comate_username)
+        return comate_username
+
+    # 2. 从 git config user.email 提取
+    try:
+        result = subprocess.run(
+            ["git", "config", "user.email"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            username = result.stdout.strip().split("@")[0]
+            if username:
+                logger.info("用户识别: source=email, user=%s", username)
+                return username
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    # 3. 回退到 git config user.name
+    try:
+        result = subprocess.run(
+            ["git", "config", "user.name"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            username = result.stdout.strip()
+            logger.info("用户识别: source=name, user=%s", username)
+            return username
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    logger.warning("无法获取用户 ID，所有来源均失败")
+    return None
+
+
+def get_git_diff_summary(max_diff_lines: int = DEFAULT_MAX_DIFF_LINES) -> Optional[Dict[str, Any]]:
+    """获取当前工作区的 git diff 摘要
+
+    执行 git diff HEAD 获取所有未提交的变更（包括暂存和未暂存），
+    并提取变更文件列表和 diff 内容摘要。
+
+    Args:
+        max_diff_lines: diff 输出的最大行数，超出部分截断。默认 500。
+
+    Returns:
+        包含 diff 信息的字典：
+        {
+            "changed_files": ["path/to/file1.ts", ...],
+            "stat_summary": "git diff --stat 输出的摘要行",
+            "diff_content": "截断后的 diff 全文",
+            "truncated": bool
+        }
+        非 git 仓库或无变更时返回 None
+    """
+    try:
+        stat_result = subprocess.run(
+            ["git", "diff", "HEAD", "--stat"],
+            capture_output=True, text=True, timeout=10
+        )
+        if stat_result.returncode != 0 or not stat_result.stdout.strip():
+            logger.info("git diff 无变更")
+            return None
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        logger.info("git diff 无变更")
+        return None
+
+    stat_lines = stat_result.stdout.strip().splitlines()
+    changed_files = []
+    for line in stat_lines[:-1]:
+        file_path = line.split("|")[0].strip()
+        if file_path:
+            changed_files.append(file_path)
+    stat_summary = stat_lines[-1].strip() if stat_lines else ""
+
+    if not changed_files:
+        logger.info("git diff 无变更")
+        return None
+
+    try:
+        diff_result = subprocess.run(
+            ["git", "diff", "HEAD"],
+            capture_output=True, text=True, timeout=30
+        )
+        diff_content = diff_result.stdout if diff_result.returncode == 0 else ""
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        diff_content = ""
+
+    lines = diff_content.splitlines()
+    truncated = len(lines) > max_diff_lines
+    if truncated:
+        diff_content = "\n".join(lines[:max_diff_lines]) + "\n... (truncated)"
+
+    logger.info("git diff: %d 个文件, %s, truncated=%s", len(changed_files), stat_summary, truncated)
+
+    return {
+        "changed_files": changed_files,
+        "stat_summary": stat_summary,
+        "diff_content": diff_content,
+        "truncated": truncated,
+    }
+
+
+def extract_space_ids_from_git_log(
+    max_commits: int = DEFAULT_MAX_COMMITS,
+    known_prefixes: Optional[List[str]] = None,
+) -> List[str]:
+    """从 git commit message 中提取 iCafe 空间前缀
+
+    优先使用已知的空间前缀列表进行精确匹配（支持含连字符的前缀如 DevOps-iScan），
+    回退到正则启发式提取。
+
+    Args:
+        max_commits: 扫描的最大提交数量
+        known_prefixes: 已知的空间 prefixCode 列表（来自 API）。
+                        提供时优先用精确匹配；未提供时用正则启发式。
+
+    Returns:
+        去重后的空间前缀列表（保留原始大小写），按提交次数降序排列。
+        非 git 仓库或无匹配时返回空列表。
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", "--oneline", "-n", str(max_commits)],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.returncode != 0:
+            return []
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []
+
+    log_text = result.stdout.strip()
+    if not log_text:
+        return []
+
+    # 策略 1：用已知前缀精确匹配 "前缀-数字"
+    if known_prefixes:
+        counter: Dict[str, int] = {}
+        for prefix in known_prefixes:
+            pat = re.compile(re.escape(prefix) + r'-\d+', re.IGNORECASE)
+            count = len(pat.findall(log_text))
+            if count > 0:
+                counter[prefix] = count
+        if counter:
+            sorted_prefixes = sorted(counter, key=counter.get, reverse=True)
+            logger.info("git log 提取前缀: %s, 策略=精确匹配", sorted_prefixes)
+            return sorted_prefixes
+
+    # 策略 2：正则启发式兜底（无已知前缀或精确匹配无结果）
+    pattern = re.compile(r'\b([a-zA-Z][a-zA-Z0-9_]*)-(\d+)\b')
+    counter_fallback: Dict[str, int] = {}
+
+    for line in log_text.splitlines():
+        for match in pattern.finditer(line):
+            prefix = match.group(1).lower()
+            if prefix in GIT_LOG_FALSE_POSITIVE_PREFIXES:
+                continue
+            if len(prefix) <= 1:
+                continue
+            counter_fallback[prefix] = counter_fallback.get(prefix, 0) + 1
+
+    sorted_prefixes = sorted(counter_fallback, key=counter_fallback.get, reverse=True)
+    logger.info("git log 提取前缀: %s, 策略=正则启发式", sorted_prefixes)
+    return sorted_prefixes

package/comate-engine/assets/skills/smart-commit/scripts/icafe/__init__.py

@@ -0,0 +1,66 @@
+"""iCafe Card Query Client - 卡片条件查询助手
+
+提供 iCafe 平台卡片条件查询相关的 API 接口封装，
+支持通过 IQL 表达式、卡片 ID、空间等维度灵活查询卡片信息。
+"""
+
+from .client import (
+    ICafeQueryConfig,
+    ICafeQueryClient,
+    # 常量
+    ICAFE_BASE_URL,
+    FARSEER_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_LOOKBACK_DAYS,
+    DEFAULT_MAX_RECORDS,
+    DEFAULT_MAX_COMMITS,
+    DEFAULT_MAX_DIFF_LINES,
+    GIT_LOG_FALSE_POSITIVE_PREFIXES,
+    ISSUE_TYPE_MAP,
+    ISSUE_TYPE_NAME_MAP,
+)
+from git_utils import (
+    get_current_user,
+    get_git_diff_summary,
+    extract_space_ids_from_git_log,
+)
+from .matching import (
+    auto_detect_space,
+    find_matching_card,
+    match_diff_to_cards,
+    build_type_filter_iql,
+    format_card_summary,
+    format_query_result,
+)
+from .farseer import get_binding_card_types
+
+__all__ = [
+    # 配置和客户端
+    'ICafeQueryConfig',
+    'ICafeQueryClient',
+    # 常量
+    'ICAFE_BASE_URL',
+    'FARSEER_BASE_URL',
+    'DEFAULT_TIMEOUT',
+    'DEFAULT_LOOKBACK_DAYS',
+    'DEFAULT_MAX_RECORDS',
+    'DEFAULT_MAX_COMMITS',
+    'DEFAULT_MAX_DIFF_LINES',
+    'GIT_LOG_FALSE_POSITIVE_PREFIXES',
+    'ISSUE_TYPE_MAP',
+    'ISSUE_TYPE_NAME_MAP',
+    # Git 工具
+    'get_current_user',
+    'get_git_diff_summary',
+    'extract_space_ids_from_git_log',
+    # 自动检测和匹配
+    'auto_detect_space',
+    'find_matching_card',
+    'match_diff_to_cards',
+    'build_type_filter_iql',
+    # 格式化
+    'format_card_summary',
+    'format_query_result',
+    # Farseer API
+    'get_binding_card_types',
+]