@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.4

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/build_git_commit_payload.py

@@ -0,0 +1,195 @@
+"""命令行工具：构建并验证 git-commit UI payload
+
+用法:
+    # 缓存模式（推荐）：脚本自动从缓存读取 diff、执行 git branch 获取分支信息
+    python3 build_git_commit_payload.py --cache --commit-message "msg" --bound-card '{"sequence":"39",...}'
+    python3 build_git_commit_payload.py --cache --commit-message "msg" --bound-card 'null'
+
+    # JSON 模式（降级）：Agent 手动构造完整 workspaces 数组
+    python3 build_git_commit_payload.py --json '<payload JSON>'
+
+缓存模式输入:
+    --commit-message: commit message（必填）
+    --bound-card: 绑定卡片 JSON 对象，或字符串 'null' 表示无卡片（必填）
+
+JSON 模式输入:
+    --json: 完整 payload JSON，包含 commitMessage、boundCard、workspaces。
+    diffSummary 内部保持 snake_case（与 git_diff_cli.py 输出一致）。
+
+输出:
+    验证通过: {"valid": true, "payload": {...}}
+    验证失败: {"valid": false, "errors": ["...", ...]}
+    系统错误: {"error": "..."}
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from cache_manager import get_all_git_diffs, CACHE_PATH
+from payload_validators import convert_git_commit_payload
+
+
+def _get_current_branch(workspace):
+    """通过 git branch --show-current 获取当前分支名。"""
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+            timeout=10, cwd=workspace
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+    return ""
+
+
+def _get_remote_branches(workspace, current_branch):
+    """通过 git branch -r 获取远程分支列表，最多 10 个。"""
+    try:
+        result = subprocess.run(
+            ["git", "branch", "-r", "--sort=-committerdate"],
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+            timeout=10, cwd=workspace
+        )
+        if result.returncode == 0:
+            branches = []
+            for line in result.stdout.splitlines():
+                line = line.strip()
+                if not line or "->" in line:
+                    continue
+                # 去掉 "origin/" 前缀
+                name = line.split("/", 1)[-1] if "/" in line else line
+                is_current = (name == current_branch)
+                branches.append({"name": name, "isCurrent": is_current})
+                if len(branches) >= 10:
+                    break
+
+            # 确保当前分支在列表中
+            if current_branch and not any(b["isCurrent"] for b in branches):
+                branches.insert(0, {"name": current_branch, "isCurrent": True})
+
+            return branches
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+    return []
+
+
+def _build_workspace_entry(workspace_path, diff_data):
+    """为单个 workspace 构建 payload 条目。"""
+    has_changes = diff_data.get("has_changes", False)
+    repo_name = os.path.basename(workspace_path)
+
+    if has_changes:
+        current_branch = _get_current_branch(workspace_path)
+        remote_branches = _get_remote_branches(workspace_path, current_branch)
+        diff_summary = {
+            "changed_files": diff_data.get("changed_files", []),
+            "stat_summary": diff_data.get("stat_summary", ""),
+        }
+    else:
+        current_branch = ""
+        remote_branches = []
+        diff_summary = None
+
+    return {
+        "workspace": workspace_path,
+        "repoName": repo_name,
+        "currentBranch": current_branch,
+        "remoteBranches": remote_branches,
+        "hasChanges": has_changes,
+        "diffSummary": diff_summary,
+    }
+
+
+def _handle_cache_mode(args):
+    """从缓存读取 diff 数据，自动构建 workspaces 并验证。"""
+    git_diffs = get_all_git_diffs()
+
+    if not git_diffs:
+        print(json.dumps({"error": f"缓存中无 git_diffs 数据（缓存路径: {CACHE_PATH}）。"
+                                  "请确保步骤 2 已执行 git_diff_cli.py"}, ensure_ascii=False))
+        sys.exit(1)
+
+    # 解析 bound_card
+    bound_card = None
+    if args.bound_card and args.bound_card.lower() != "null":
+        try:
+            bound_card = json.loads(args.bound_card)
+        except json.JSONDecodeError as e:
+            print(json.dumps({"error": f"--bound-card JSON 解析失败: {e}"}, ensure_ascii=False))
+            sys.exit(1)
+
+    # 构建 workspaces 数组
+    workspaces = []
+    for workspace_path, diff_data in git_diffs.items():
+        ws_entry = _build_workspace_entry(workspace_path, diff_data)
+        workspaces.append(ws_entry)
+
+    # 构建完整 payload
+    raw = {
+        "commitMessage": args.commit_message,
+        "boundCard": bound_card,
+        "workspaces": workspaces,
+    }
+
+    converted, errors = convert_git_commit_payload(raw)
+
+    if errors:
+        print(json.dumps({"valid": False, "errors": errors}, ensure_ascii=False))
+    else:
+        print(json.dumps({"valid": True, "payload": converted}, ensure_ascii=False))
+
+
+def _handle_json_mode(args):
+    """原有 --json 模式，直接解析传入的 JSON 进行验证。"""
+    try:
+        data = json.loads(args.json)
+    except json.JSONDecodeError as e:
+        print(json.dumps({"error": f"JSON 解析失败: {e}"}, ensure_ascii=False))
+        sys.exit(1)
+
+    converted, errors = convert_git_commit_payload(data)
+
+    if errors:
+        print(json.dumps({"valid": False, "errors": errors}, ensure_ascii=False))
+    else:
+        print(json.dumps({"valid": True, "payload": converted}, ensure_ascii=False))
+
+
+def main():
+    """解析命令行参数，构建并验证 git-commit UI payload。"""
+    parser = argparse.ArgumentParser(description="构建并验证 git-commit UI payload")
+
+    # 缓存模式参数
+    parser.add_argument("--cache", action="store_true",
+                        help="从统一缓存读取 git_diff 数据，自动构建 workspaces")
+    parser.add_argument("--commit-message", default=None,
+                        help="commit message（--cache 模式必填）")
+    parser.add_argument("--bound-card", default=None,
+                        help="绑定卡片 JSON（--cache 模式，传 'null' 表示无卡片）")
+
+    # JSON 模式参数（向后兼容）
+    parser.add_argument("--json", default=None,
+                        help="payload 数据 JSON（向后兼容，与 --cache 二选一）")
+
+    args = parser.parse_args()
+
+    if args.cache:
+        if not args.commit_message:
+            print(json.dumps({"error": "--cache 模式下 --commit-message 为必填参数"}, ensure_ascii=False))
+            sys.exit(1)
+        _handle_cache_mode(args)
+    elif args.json:
+        _handle_json_mode(args)
+    else:
+        print(json.dumps({"error": "必须提供 --cache 或 --json 参数"}, ensure_ascii=False))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,80 @@
+"""命令行工具：构建并验证 icafe-cards UI payload
+
+用法:
+    python3 build_icafe_cards_payload.py --view-mode list --default-title "优化 xxx 相关功能"
+
+输入:
+    --result-file: match_card_cli.py 的输出 JSON 文件路径（可选，默认读取 /tmp/__comate_icafe_result.json）
+    --view-mode: "list" 或 "create"（必填，模型决策）
+    --default-title: 推荐卡片标题（必填，模型根据 diff 生成）
+    --cards: 排序后的卡片列表 JSON（可选，不传则使用 result 中的原始 cards）
+
+脚本从 result 文件读取所有数据，完成 snake_case → camelCase 转换，
+覆盖模型决策字段（viewMode、defaults.title、cards），验证后输出 payload。
+Agent 不需要手动转换任何字段名，不需要拼 JSON。
+
+输出:
+    验证通过: {"valid": true, "payload": {...}}
+    验证失败: {"valid": false, "errors": ["...", ...]}
+    系统错误: {"error": "..."}
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from cache_manager import get_icafe_result, CACHE_PATH
+from payload_validators import convert_icafe_cards_payload
+
+
+def main():
+    """解析命令行参数，构建并验证 icafe-cards UI payload。"""
+    parser = argparse.ArgumentParser(description="构建并验证 icafe-cards UI payload")
+    parser.add_argument("--result-file", default=None,
+                        help="已废弃，忽略此参数。脚本自动从统一缓存读取")
+    parser.add_argument("--view-mode", required=True, choices=["list", "create"], help="视图模式")
+    parser.add_argument("--default-title", required=True, help="默认卡片标题")
+    parser.add_argument("--cards", default=None, help="排序后的卡片列表 JSON（可选）")
+    args = parser.parse_args()
+
+    # 从统一缓存读取 result
+    result = get_icafe_result()
+    if result is None:
+        print(json.dumps({"error": f"缓存中无 icafe_result 数据（缓存路径: {CACHE_PATH}）"}, ensure_ascii=False))
+        sys.exit(1)
+
+    if not isinstance(result, dict):
+        print(json.dumps({"error": "result 文件内容必须是 JSON 对象"}, ensure_ascii=False))
+        sys.exit(1)
+
+    # 覆盖模型决策字段
+    result["viewMode"] = args.view_mode
+
+    # 覆盖 defaults.title
+    if "defaults" not in result or not isinstance(result["defaults"], dict):
+        result["defaults"] = {}
+    result["defaults"]["title"] = args.default_title
+
+    # 覆盖 cards（如果传了 --cards）
+    if args.cards is not None:
+        try:
+            cards = json.loads(args.cards)
+            if isinstance(cards, list):
+                result["cards"] = cards
+        except json.JSONDecodeError:
+            print(json.dumps({"error": "--cards 参数 JSON 解析失败"}, ensure_ascii=False))
+            sys.exit(1)
+
+    # 转换 + 验证
+    converted, errors = convert_icafe_cards_payload(result)
+
+    if errors:
+        print(json.dumps({"valid": False, "errors": errors}, ensure_ascii=False))
+    else:
+        print(json.dumps({"valid": True, "payload": converted}, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,69 @@
+"""统一的缓存文件管理模块
+
+所有脚本共享一个缓存文件 /tmp/__comate_auto_commit_cache.json，
+结构为 {"icafe_result": {...}, "git_diffs": {"/path": {...}}}。
+"""
+
+import json
+import os
+
+# 统一缓存文件路径（唯一声明位置）
+CACHE_PATH = "/tmp/__comate_auto_commit_cache.json"
+
+
+def read_cache():
+    """读取完整缓存 dict。文件不存在或解析失败返回空 dict。"""
+    try:
+        with open(CACHE_PATH, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def write_cache(data):
+    """将完整 dict 写入缓存文件。失败静默忽略。"""
+    try:
+        with open(CACHE_PATH, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False)
+    except OSError:
+        pass
+
+
+def update_icafe_result(result):
+    """更新缓存中的 icafe_result 字段。"""
+    cache = read_cache()
+    cache["icafe_result"] = result
+    write_cache(cache)
+
+
+def update_git_diff(workspace, diff_data):
+    """更新缓存中指定 workspace 的 git_diff 数据。"""
+    cache = read_cache()
+    if "git_diffs" not in cache:
+        cache["git_diffs"] = {}
+    cache["git_diffs"][workspace] = diff_data
+    write_cache(cache)
+
+
+def get_icafe_result():
+    """读取缓存中的 icafe_result。不存在返回 None。"""
+    return read_cache().get("icafe_result")
+
+
+def get_git_diff(workspace):
+    """读取缓存中指定 workspace 的 git_diff。不存在返回 None。"""
+    return read_cache().get("git_diffs", {}).get(workspace)
+
+
+def get_all_git_diffs():
+    """读取缓存中所有 workspace 的 git_diff dict。不存在返回空 dict。"""
+    return read_cache().get("git_diffs", {})
+
+
+def cleanup():
+    """删除缓存文件。用于 skill 流程结束时清理。"""
+    try:
+        if os.path.exists(CACHE_PATH):
+            os.remove(CACHE_PATH)
+    except OSError:
+        pass

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()