@comate/zulu 1.1.0 → 1.2.0

package/comate-engine/assets/skills/auto-commit/references/old_version_instruction.md

@@ -0,0 +1,189 @@
+# 旧版本 IDE 交互指南
+
+本文档适用于**旧版本 IDE**（IDE 名称占位符未替换、或插件版本 < 4.1.0）的交互方式。旧版本不支持 `__silent:` 和 `__interactive:` 前缀。
+
+---
+
+## 步骤 1：获取 iCafe 数据（旧版本命令）
+
+使用 SKILL.md 步骤 1 中定义的命令模板，**不加 `__silent:` 前缀**直接执行。
+
+---
+
+## 步骤 2：获取 git diff（旧版本命令）
+
+使用 SKILL.md 步骤 2 中定义的命令模板，**不加 `__silent:` 前缀**直接执行。
+
+---
+
+## 步骤 4：展示卡片选择（文本交互）
+
+根据 `viewMode` 输出文本列表。
+
+**当 `viewMode == "list"`（有高匹配卡片）时：**
+
+先展示卡片列表（已按匹配度排序，标注匹配理由），再展示新建选项：
+
+```
+📋 根据代码变更，找到以下匹配的 iCafe 卡片：
+
+1. ⭐ [${spacePrefix}-${card1.sequence}] ${card1.title}
+   类型: ${card1.type} | 状态: ${card1.status}
+   匹配理由: ${reason}
+
+2. [${spacePrefix}-${card2.sequence}] ${card2.title}
+   类型: ${card2.type} | 状态: ${card2.status}
+
+（最多显示 10 张卡片，⭐ 标记匹配度较高的卡片）
+
+---
+🆕 如需新建卡片，为你推荐以下信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}（类型 ID: ${result.defaults.type_id}）
+
+---
+请回复：
+- 输入序号（如 "1"）选择对应卡片
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+**当 `viewMode == "create"`（无高匹配卡片）时：**
+
+先展示新建卡片推荐（突出位置），再附上已有卡片作为备选：
+
+```
+💡 当前代码变更与已有卡片匹配度较低，建议新建卡片：
+
+🆕 推荐新建卡片信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}（类型 ID: ${result.defaults.type_id}）
+
+---
+📋 以下是你当前活跃的卡片（供参考）：
+
+1. [${spacePrefix}-${card1.sequence}] ${card1.title}
+   类型: ${card1.type} | 状态: ${card1.status}
+
+（最多显示 10 张卡片）
+
+---
+请回复：
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入序号（如 "1"）选择对应卡片
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+如果没有找到卡片，输出：
+
+```
+📋 未找到可关联的 iCafe 卡片
+
+🆕 为你推荐以下建卡信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}
+
+---
+请回复：
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+**推荐类型名称的获取方式：** 从 `result.available_spaces` 中找到当前空间（匹配 `space_prefix`），取其 `types` 列表中 `id` 等于 `result.defaults.type_id` 的类型的 `name`。如果找不到，取该空间 `types` 列表第一个的 `name`。
+
+---
+
+## 步骤 5：处理用户操作（旧版本 IDE）
+
+根据用户在对话中的文本回复：
+
+**如果用户输入序号（如 "1"、"2"）：**
+- 解析用户选择的卡片，保存 `selected_card` 信息，继续步骤 7
+
+**如果用户输入卡片 ID（如 "DevOps-iScan-35835"）：**
+- 调用 `recognize_card_cli.py` 获取卡片详情：
+  ```
+  cd <用户项目目录> && python3 <skill_directory>/scripts/recognize_card_cli.py --link "<卡片ID>"
+  ```
+- 保存 `selected_card` 信息，继续步骤 7
+
+**如果用户输入 "new"（使用推荐信息直接新建）：**
+- 使用 `result` 中的推荐信息调用 `create_card_cli.py` 创建卡片
+- 标题 = `result.defaults.title`，空间 = `result.space_prefix`
+- 类型 = 从 `result.available_spaces` 中匹配当前空间，取 `types` 中 `id` 等于 `result.defaults.type_id` 的类型名称
+
+**如果用户输入 "new 自定义标题"：**
+- 与 "new" 逻辑相同，但标题使用用户输入的自定义标题（去掉 "new " 前缀后的部分）
+
+**如果用户输入 "new?"（查看空间和类型枚举）：**
+
+从 `result.available_spaces` 输出完整枚举：
+
+```
+📋 可选空间和类型：
+
+空间 1: ${space1.name} (${space1.prefix})
+  可选类型：
+  - ${type1.name} (ID: ${type1.id})
+  - ${type2.name} (ID: ${type2.id})
+
+---
+请回复以下格式新建卡片：
+  new [标题] | [空间前缀] | [类型名称]
+  例如：new 修复登录问题 | dkx | Bug
+
+也可以只指定部分：
+  new 修复登录问题 | dkx       → 使用指定空间 + 该空间默认类型
+  new 修复登录问题 | | Story   → 使用推荐空间 + 指定类型
+```
+
+**如果用户输入 "new 标题 | 空间 | 类型"（完整指定）：**
+- 按 `|` 分割解析，第一段为标题，第二段（可选）为空间前缀，第三段（可选）为类型名称
+- 为空的部分使用推荐值，调用 `create_card_cli.py` 创建卡片
+
+---
+
+## 步骤 8：展示提交确认（文本确认）
+
+输出：
+
+```
+✅ 已关联卡片: ${spacePrefix}-${sequence}
+   标题: ${title}
+   类型: ${type} | 状态: ${status}
+
+---
+📝 建议的 commit message：
+
+${spacePrefix}-${sequence} ${brief_description}
+
+---
+请确认：
+- 回复 "ok" 或 "确认" 使用此 message 提交
+- 回复 "edit: <新message>" 修改后提交（如 "edit: dkx-200 修复登录bug"）
+- 回复 "no" 或 "取消" 放弃提交
+```
+
+---
+
+## 步骤 9：执行提交（旧版本 IDE）
+
+**如果用户确认提交（回复 "ok"、"确认"、"yes"）：**
+- 执行 `git add . && git commit -m "${commit_message}"`
+
+**如果用户修改后提交（回复 "edit: <新message>"）：**
+- 使用用户提供的新 message 执行提交
+
+**如果用户取消（回复 "no"、"取消"）：**
+- 输出取消信息
+
+旧版本 IDE 提交成功后额外提示：`如需推送到远程，请执行：git push`

package/comate-engine/assets/skills/auto-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/auto-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/auto-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()