@comate/zulu 1.3.3-internal.3 → 1.3.3-internal.4

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

@@ -0,0 +1,220 @@
+# 交互指南
+
+本文档描述 auto-commit skill 中 UI 交互和数据提交的具体操作方式。
+
+---
+
+## 全局规则
+
+**⚠️ 全局静默要求：整个流程中 Agent 仅通过 `__interactive:` UI 组件与用户交互。除步骤 9 的最终结果文字外，Agent 禁止向用户输出任何文字内容，包括但不限于：**
+- **过渡性话语**：如 "Now I have the data"、"Let me perform matching"、"让我分析一下"
+- **内部分析过程**：如 "Card 26: xxx - Score: 95"、"Matching analysis:"、匹配评分细节
+- **状态说明**：如 "has_good_match: true"、"Cards sorted by score"
+- **JSON 数据或代码片段**
+
+**Agent 应在内部完成所有思考后，直接调用对应的 `run_command`，不在工具调用之间输出任何文字。**
+
+**⚠️ 重要：所有 `run_command` 调用（`__interactive:` 除外）必须加 `__silent:` 前缀。唯一例外是步骤 9 的 git commit 命令，需要展示提交结果给用户。**
+
+**⚠️ 禁止额外命令：Agent 不得在流程步骤之外自行执行任何 shell 命令（如 `git status`、`ls` 等）。iCafe 数据由步骤 1 的 Python 脚本获取，git diff 由步骤 2 中 Agent 按规定命令获取。**
+
+**⚠️ 工作目录规则：Skill 执行时的工作目录可能不是用户项目目录。当命令需要在用户项目目录下执行时（如 git 操作、Python 脚本），必须在命令中加 `cd <用户项目目录> &&` 切换目录。但 `__silent:` 或 `__interactive:` 前缀必须始终在命令最开头。**
+
+**⚠️ 多 Workspace 规则：用户可能打开了多个代码库（multi-root workspace）。环境上下文中的 `Workspace Path` 会列出所有 workspace 路径。在步骤 2 和步骤 8 中，Agent 必须对每个 workspace 分别执行 git 命令，不可只处理第一个 workspace 后忽略其余的。**
+
+正确格式：
+```
+__silent: cd /path/to/project && git add .
+__interactive:icafe-cards {...}
+```
+
+错误格式（禁止）：
+```
+cd /path/to/project && __silent: git add .
+cd /path/to/project && __interactive:icafe-cards {...}
+```
+
+---
+
+## 步骤 1：获取 iCafe 数据
+
+使用 SKILL.md 步骤 1 中定义的命令模板执行。
+
+---
+
+## 步骤 2：获取 git diff
+
+使用 SKILL.md 步骤 2 中定义的命令模板执行。
+
+---
+
+## 步骤 4：展示卡片选择
+
+### 4a. 构造并通过脚本验证 payload
+
+**⚠️ 不需要手动转换 snake_case/camelCase，不需要拼 JSON，不需要传文件路径。** 脚本自动读取步骤 1 留下的缓存文件，Agent 只需传入简单的 CLI 参数。
+
+```bash
+__silent: python3 <skill_directory>/scripts/build_icafe_cards_payload.py --view-mode list --default-title "优化 xxx 相关功能"
+```
+
+参数说明：
+- `--view-mode`（必填）：`list` 或 `create`，由步骤 3 确定
+- `--default-title`（必填）：Agent 根据 diff 语义生成的推荐标题
+- `--cards`（可选）：排序后的 cards JSON 数组，不传则使用 result 中的原始顺序
+- `--result-file`（可选）：默认读取 `/tmp/__comate_icafe_result.json`（步骤 1 自动写入）
+
+**脚本自动从缓存文件读取所有数据并完成 snake_case → camelCase 转换，Agent 不需要手动处理任何字段名。**
+
+### 4b. 解析脚本输出并调用 UI
+
+**如果脚本返回 `{"valid": true, "payload": {...}}`：**
+
+**⚠️ 必须提取 `payload` 字段的值（内层 JSON），使用 `run_command` 工具调用 UI，禁止将 payload 作为文本输出给用户。**
+
+例如脚本返回：
+```json
+{"valid": true, "payload": {"cards": [...], "spacePrefix": "dkx", ...}}
+```
+则调用：
+```
+run_command(command="__interactive:icafe-cards {\"cards\": [...], \"spacePrefix\": \"dkx\", ...}")
+```
+**禁止**（作为文本输出或传入错误数据）：
+```
+__interactive:icafe-cards {"valid": true, "payload": {"cards": [...], ...}}
+```
+
+**如果脚本返回 `{"valid": false, "errors": [...]}`：**
+
+根据 `errors` 中的具体描述修正数据，重新调用脚本（最多重试 1 次）。如果重试后仍返回 `valid: false`，或脚本返回 `{"error": "..."}`，则**降级为文本交互**（见下方降级格式）。
+
+---
+
+## 步骤 5：处理用户操作
+
+UI 组件返回 JSON，可能的 action 值：
+
+| action | 含义 | 处理方式 |
+|--------|------|----------|
+| `select` | 选择已有卡片 | 保存 `card` 中的卡片信息，继续步骤 7 |
+| `recognize` | 链接或卡片 ID 识别 | 调用 `recognize_card_cli.py` 获取卡片详情，继续步骤 7 |
+| `create` | 新建卡片 | 调用 `create_card_cli.py` 创建卡片，继续步骤 7 |
+| `skip` | 跳过 | 输出"已跳过卡片绑定和代码提交。"，**结束 skill** |
+| `do_not_show_again` | 不再提示 | 输出"已关闭推荐卡片提示。"，**结束 skill** |
+
+**recognize 处理：**
+```
+__silent: cd <用户项目目录> && python3 <skill_directory>/scripts/recognize_card_cli.py --link "<用户返回的link>"
+```
+
+**create 处理：**
+
+使用 SKILL.md 步骤 5 中定义的「创建卡片命令模板」，**加 `__silent:` 前缀**执行。
+
+---
+
+## 步骤 8：展示提交确认
+
+### 8a. 构造并通过脚本验证 payload
+
+**推荐：使用缓存模式**（脚本自动从缓存读取 diff、执行 git branch 获取分支信息）：
+
+```bash
+__silent: python3 <skill_directory>/scripts/build_git_commit_payload.py --cache --commit-message "<commitMessage>" --bound-card '<boundCard JSON 或 null>'
+```
+
+参数说明：
+- `--commit-message`（必填）：iCode 仓库格式 `"<spacePrefix>-<sequence> <描述>"`；非 iCode 仓库不带卡片 ID
+- `--bound-card`（必填）：步骤 5 选定的卡片对象 JSON，无卡片时传字符串 `'null'`
+
+**⚠️ 所有命令必须带 `__silent:` 前缀（`__interactive:` 除外）。**
+
+### 8b. 解析脚本输出并调用 UI
+
+**如果脚本返回 `{"valid": true, "payload": {...}}`：**
+
+**⚠️ 必须提取 `payload` 字段的值（内层 JSON），使用 `run_command` 工具调用 UI，禁止将 payload 作为文本输出给用户。**
+
+例如脚本返回：
+```json
+{"valid": true, "payload": {"commitMessage": "dkx-200 fix", "boundCard": {...}, "workspaces": [...]}}
+```
+则调用：
+```
+run_command(command="__interactive:git-commit {\"commitMessage\": \"dkx-200 fix\", \"boundCard\": {...}, \"workspaces\": [...]}")
+```
+**禁止**（作为文本输出或传入错误数据）：
+```
+__interactive:git-commit {"valid": true, "payload": {"commitMessage": "dkx-200 fix", ...}}
+```
+
+**如果脚本返回 `{"valid": false, "errors": [...]}`：**
+
+根据 `errors` 中的具体描述修正数据，重新调用脚本（最多重试 1 次）。如果重试后仍返回 `valid: false`，或脚本返回 `{"error": "..."}`，则**降级为文本交互**（见下方降级格式）。
+
+用户操作后，tool output 返回 JSON：
+- 确认提交：`{"action": "submit", "repos": [{"workspace": "...", "commitMessage": "...", "branch": "..."}]}`
+- 取消提交：`{"action": "cancel"}`
+
+---
+
+## 步骤 9：执行提交
+
+从 tool output 解析用户操作：
+
+**如果是 action === "submit"：**
+
+UI 返回的结果格式：
+```json
+{"action": "submit", "repos": [{"workspace": "/path/to/repo", "commitMessage": "dkx-200 修复...", "branch": "feature/xxx"}]}
+```
+
+Agent 收到后，对 `repos` 数组中的每个仓库自主决定执行方式：
+- `cd` 到对应 workspace 目录
+- 执行 `git add .`、`git commit -m "<commitMessage>"`（git commit 命令不使用 `__silent:`，展示提交结果给用户）
+- 如果用户选择了特定分支且不是当前分支，先 `git checkout` 切换
+- **推送方式根据仓库类型区分：**
+  - 统一使用 `git push origin HEAD:refs/for/<branch>` 推送到 Gerrit 代码评审
+- 多仓库时逐个执行，每个仓库独立处理
+
+**如果是 action === "cancel"：**
+- 输出"已取消提交"
+
+---
+
+## 降级文本交互格式
+
+当 builder 脚本验证失败且重试仍失败，或脚本返回系统错误时，Agent 降级为纯文本交互。
+
+### 步骤 4 降级（卡片选择）
+
+```
+请选择要绑定的 iCafe 卡片（回复编号）：
+
+1. dkx-200 修复登录问题 [Bug] [开发中]
+2. dkx-198 新增导出功能 [Story] [待开发]
+3. dkx-195 优化查询性能 [Task] [进行中]
+
+回复 N 选择对应卡片，或回复卡片链接/ID，或回复 "新建" 创建卡片，回复 "跳过" 跳过。
+```
+
+用户回复后，Agent 按步骤 5 的规则处理对应操作。
+
+### 步骤 8 降级（提交确认）
+
+```
+📝 提交确认
+
+Commit Message: dkx-200 修复登录问题
+绑定卡片: dkx-200 修复登录问题 (Bug)
+
+变更文件:
+- frontend-app: 2 files, +100, -78
+  - src/App.tsx (+76, -66)
+  - src/utils.ts (+24, -12)
+
+回复 "确认" 提交代码，回复 "取消" 放弃提交。
+```
+
+用户回复后，Agent 按步骤 9 的规则处理对应操作。

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