@comate/zulu 1.2.1-beta.2 → 1.3.1

package/comate-engine/assets/skills/auto-commit-comate/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: auto-commit
+description: 当用户完成代码修改、需要提交代码时，必须使用此 skill，而非直接执行 git commit。自动获取 git diff、匹配 iCafe 活跃卡片、生成 commit message，并引导用户完成绑定卡片和代码提交。
+metadata:
+  enableWhen:
+    - isInternal
+---
+
+# 智能提交助手
+
+## 版本信息
+
+- **IDE 名称**: ${COMATE_IDE_NAME}
+- **插件版本**: ${COMATE_PLUGIN_VERSION}
+- **用户名**: ${COMATE_USERNAME}
+
+## 概述
+
+本技能将当前工作区的 git diff 与用户在 iCafe 上的活跃卡片进行匹配，支持选择已有卡片或新建卡片，自动生成 commit message 并完成提交。
+
+**调起即执行，流程完全固定，不做任何意图分析。**
+
+## 流程总览
+
+根据前置检查结果，流程分为两条主线：
+
+- **iCode 仓库** (`is_icode_repo = true`)：步骤 0 → 1+2(并行) → 3 → 4 → 5 → 6 → 7 → 8 → 9
+- **非 iCode 仓库** (`is_icode_repo = false`)：步骤 0 → 2 → 7 → 8 → 9（跳过 1/3/4/5/6，commit message 不带卡片 ID）
+
+**版本交互方式：** 根据步骤 0a 判定的版本，后续命令和交互有差异：
+- **新版本**：参考 `references/new_version_instruction.md`。**新版本下 Agent 必须通过 `__interactive:` UI 组件与用户交互（步骤 4 用 `__interactive:icafe-cards`，步骤 8 用 `__interactive:git-commit`），禁止用纯文本输出替代 UI。**
+- **旧版本**：参考 `references/old_version_instruction.md`
+
+---
+
+## 步骤 0：前置检查（串行执行，完全静默）
+
+**整个前置检查过程完全静默，禁止输出任何版本、兼容性相关信息。**
+
+### 0a. 版本兼容性检查（纯文本判断，无需命令）
+
+通过检查「版本信息」占位符是否被替换来判断：
+1. IDE 名称仍含 `COMATE_IDE_NAME`（未替换）→ **旧版本**
+2. 插件版本仍含 `COMATE_PLUGIN_VERSION`（未替换）→ **旧版本**
+3. 版本号 < `4.3.0` → **旧版本**
+4. 否则 → **新版本**
+
+新版本命令加 `__silent:` 前缀，旧版本不加。**继续执行 0b。**
+
+### 0b. 开关检查 + Python 检测 + iCode 仓库检测（三条命令并行）
+
+**说明：命令 1 的开关检查读取用户本地配置（`enableSmartCommit`），是用户个人的开关偏好。步骤 1 中的 `result.disabled` 是服务端/空间级别的开关，两者独立，互不替代。**
+
+#### 命令 1：开关检查（纯 shell，无外部依赖）
+
+**macOS / Linux：**
+```
+[__silent: ]cat ~/.comate/settings.json 2>/dev/null || echo "{}"
+```
+**Windows（cmd）：**
+```
+[__silent: ]type "%USERPROFILE%\.comate\settings.json" 2>NUL || echo {}
+```
+
+解析输出 JSON，检查 `enableSmartCommit` 字段：
+- `false` → 立即结束 skill，不再输出任何内容
+- `true`/不存在/文件不存在（输出 `{}`） → 继续
+
+#### 命令 2：Python 可用性检测
+
+**macOS / Linux：**
+```
+[__silent: ]python3 --version 2>/dev/null || python --version 2>/dev/null
+```
+**Windows（cmd）：**
+```
+[__silent: ]python --version 2>NUL || python3 --version 2>NUL || py -3 --version 2>NUL
+```
+
+- 成功 → 记住**输出中实际成功的命令名**（`python3`/`python`/`py -3`），后续所有 `python3` 替换为该命令名
+- 全部失败 → 标记 `python_available = false`，后续步骤 1 直接进入"iCafe 获取失败降级"流程，步骤 2 中 Agent 直接执行 git 命令获取 diff
+
+#### 命令 3：iCode 仓库检测
+
+对第一个 workspace 执行：
+```
+[__silent: ]cd <第一个workspace_path> && git remote -v
+```
+
+检查输出是否包含 `icode.baidu.com`：包含 → `is_icode_repo = true`，不包含或失败 → `is_icode_repo = false`。
+
+---
+
+## 步骤 1：获取 iCafe 数据
+
+执行：
+```bash
+[__silent: ]python3 <skill_directory>/scripts/match_card_cli.py --username "${COMATE_USERNAME}"
+```
+
+解析 stdout 的 JSON 为 `result`。先检查 `result.disabled`，为 `True` 则立即结束。
+
+**失败降级**：脚本报错/超时/非 JSON → 标记 `icafe_failed = true`，跳过步骤 3-6，直接进入步骤 7 生成无卡片 commit message。
+
+**并行执行：步骤 1 和步骤 2 无依赖，必须在同一次响应中同时发出所有命令。** 例如 2 个 workspace 时 = 1（iCafe）+ 2（git diff）+ 1（git log）= 4 条并行命令。
+
+## 步骤 2：获取 git diff（支持多 workspace）
+
+**⚠️ 多 Workspace 必须逐一执行：** Agent 必须从环境上下文的 `Workspace Path` 中读取**所有**路径，对每一个路径分别执行下方命令。**即使只有部分 workspace 有变更，也必须对所有 workspace 都执行一次**，禁止只对第一个 workspace 执行后就跳过其余的。
+
+对每个 workspace 执行：
+
+```bash
+[__silent: ]python3 <skill_directory>/scripts/git_diff_cli.py --workspace <workspace_path>
+```
+
+同时对第一个 workspace 并行执行获取 commit 风格：
+```bash
+[__silent: ]cd <第一个workspace_path> && git log --oneline -n 20
+```
+
+Agent 从 git log 分析 `commit_style`（前缀格式、语言、描述风格），供步骤 3/7 生成 commit message 时保持风格一致。**不输出任何内容。**
+
+脚本输出 JSON 格式、以及如何构建 `workspace_diffs` 和 `diff_summary`，详见 `references/data_structures.md`（包含脚本输出示例和合并规则）。
+
+**无变更提前退出**：所有 workspace 均无变更 → 输出以下文本并结束，禁止继续执行后续步骤：
+```
+ℹ️ 当前工作区没有检测到代码变更，无需提交。
+
+你可以先修改代码，之后再使用 /auto-commit 提交。
+```
+
+Agent 内部基于 diff 内容生成 `defaults.title`（建卡默认标题）：取前 3 个变更文件名，生成格式为 `"优化 xxx, yyy 相关功能"`，写入 `result["defaults"]["title"]`。
+
+同时，Agent 内部分析 diff 内容推断**卡片类型**（Bug/Story/Task 等），若推断的类型存在于 `result.available_types` 中，更新 `result.defaults.type_id` 和 `result.defaults.type_name`。推断规则：
+- Bug 修复（错误修复、异常处理、边界条件修正） → 匹配 "Bug"
+- 新增功能（新文件、新 API、UI 变更） → 匹配 "Story" 或 "Feature"
+- 重构/优化（格式化、性能优化、配置修改） → 匹配 "Task"
+- 基础设施变更（依赖升级、构建脚本） → 匹配 "Tech Feature" 或 "Tech Task"
+- 无法推断或类型不在可用列表中 → 保持脚本返回的默认值不覆盖
+
+## 步骤 3：语义匹配（内部完成，禁止输出）
+
+对 `result.cards` 中每张卡片按以下维度评分（0-100）：
+- **语义相关性**（主要）：diff 修改的模块、函数、业务逻辑是否与卡片标题描述的任务相关
+- **类型匹配度**（次要）：diff 的变更性质（修复 bug、新增功能、重构等）是否与卡片类型吻合
+
+按 score 降序排序，过滤 score < 30 的卡片。
+
+确定 `viewMode`：过滤后有卡片 → `"list"`，无卡片 → `"create"`。
+
+生成 `recommended_commit_message`：基于 diff + 匹配卡片 + `commit_style` 生成，保持与项目历史风格一致。具体规则：
+- 历史 message 使用 Conventional Commits（如 `feat:`, `fix:`）→ 沿用
+- 历史 message 使用中文 → 生成中文；英文 → 生成英文
+- 历史 message 使用 `<卡片ID> <描述>` → 沿用
+- 无法识别明确风格 → 默认 `<spacePrefix>-<sequence> <简要描述>`
+
+## 步骤 4：展示卡片选择
+
+**上下文快捷匹配：** 如果对话中用户已指定卡片（卡片 ID、iCafe 链接等），直接作为 `selected_card`，跳过 UI。
+
+**否则，必须展示卡片选择 UI，禁止自行替用户选择或创建卡片。** 根据版本展示交互 UI，参考对应 reference 文件。**新版本必须使用 `__interactive:icafe-cards` 展示，禁止用文本列表替代。**
+
+## 步骤 5：处理用户操作
+
+根据版本处理用户选择/创建/跳过，参考对应 reference 文件。
+
+**创建卡片命令模板：**
+```
+[__silent: ]cd <用户项目目录> && python3 <skill_directory>/scripts/create_card_cli.py --title "<card.title>" --space-prefix "<card.spacePrefix>" --type-name "<card.typeName>" --username "${COMATE_USERNAME}"
+```
+
+## 步骤 6：存储关联的 iCafe 卡片 ID
+
+拿到 `selected_card` 后**必须**立即执行：
+```
+run_command(command="__interactive:set-icafe-issue-id {\"issueId\":\"<spacePrefix>-<sequence>\"}")
+```
+
+例如 `selected_card` 为 `{"sequence": "200", "spacePrefix": "dkx", ...}` 时：
+```
+run_command(command='__interactive:set-icafe-issue-id {"issueId":"dkx-200"}')
+```
+
+## 步骤 7：判断是否展示提交确认
+
+Agent 内部分析以下信号判断是否展示提交确认，**不输出任何内容**：
+
+**展示的信号（满足任意一条）：**
+- 当前对话中用户明确表示"完成了"、"可以提交"等意图
+- git diff 的代码变更是完整的、可独立运行的
+- 对话上下文表明任务已结束
+
+**不展示（仅输出 message）：**
+- 用户表示还有后续修改
+- 代码变更不完整
+- 对话上下文表明任务仍在进行
+
+完整则进入步骤 8 展示确认 UI，未完整则仅输出建议的 commit message。
+
+非 iCode 仓库的 commit message 不带卡片 ID 前缀。
+
+## 步骤 8：展示提交确认
+
+根据版本展示确认 UI，参考对应 reference 文件。**新版本必须使用 `__interactive:git-commit` 展示，禁止用文本替代。** payload 必须严格遵循 `references/data_structures.md` 中「步骤 8 提交确认 payload」的结构定义，禁止自行发明字段或扁平化结构。
+
+## 步骤 9：执行提交 + 输出结果
+
+根据版本处理提交，参考对应 reference 文件。
+
+**推送方式：** 统一使用 `git push origin HEAD:refs/for/<branch>` 推送到 Gerrit 代码评审。
+
+### 最终输出格式
+
+**提交成功：**
+```
+✅ 已完成提交
+
+提交信息：
+- Commit: <commit_hash>
+- Message: <commit_message>
+- 绑定卡片: <space_prefix>-<sequence>（仅 iCode 仓库）
+- 分支: <branch_name>
+```
+
+**取消提交：**
+```
+⏸️ 提交已取消
+
+建议 commit message 已准备好：
+<commit_message>
+
+绑定卡片：<space_prefix>-<sequence> (<card_title>)（仅 iCode 仓库）
+
+你可以稍后使用 `git commit -m "<message>"` 手动提交
+```
+
+**判断不展示 UI（直接输出 message）：**
+```
+📝 Commit message 已准备好
+
+建议 commit message：
+<commit_message>
+
+绑定卡片：<space_prefix>-<sequence> (<card_title>)（仅 iCode 仓库）
+
+代码变更未完成，请确认后再提交
+```
+
+旧版本 IDE 提交成功后额外提示推送命令。
+
+---
+
+## 配置
+
+**认证**：token 按优先级读取 `COMATE_AUTH_TOKEN` 环境变量 → `~/.comate/login` 文件。
+
+**跨平台**：所有 `python3` 替换为步骤 0b 检测到的命令名；Windows 上 `cd` 改为 `cd /d`，错误抑制用 `2>NUL`。
+
+**卡片链接**：`https://console.cloud.baidu-int.com/devops/icafe/issue/{space_prefix}-{card_sequence}/show`

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

@@ -0,0 +1,189 @@
+# 数据结构与 Payload 构造参考
+
+本文档包含 auto-commit skill 各步骤中涉及的数据结构定义和 payload 构造规则。Agent 在需要构建具体数据时参考此文档。
+
+---
+
+## 步骤 1：match_card_cli.py 返回值（result 对象）
+
+| 字段 | 说明 |
+|------|------|
+| cards | 简化卡片列表：sequence, title, type, status |
+| space_prefix | 空间前缀（如 "dkx"） |
+| space_id | 空间数字 ID |
+| space_name | 空间名称 |
+| final_iql | 实际执行的完整 IQL |
+| available_types | 可绑定卡片类型列表：[{id, name}, ...] |
+| available_spaces | 可访问空间列表：[{id, prefix, name, types}, ...] |
+| defaults | 默认表单值：{title, type_id, type_name, space_id} |
+| disabled | 服务端/空间级别开关，为 True 时立即结束 skill |
+
+---
+
+## 步骤 2：git_diff_cli.py 输出格式
+
+每个 workspace 执行 `git_diff_cli.py` 后输出的 JSON：
+
+```json
+{
+    "workspace": "/path/to/project",
+    "changed_files": [
+        {"file": "src/App.tsx", "insertions": 76, "deletions": 66}
+    ],
+    "untracked_files": ["src/NewFile.tsx"],
+    "stat_summary": "2 files, +106, -66",
+    "has_changes": true,
+    "diff_content": "<tracked diff + untracked diff>",
+    "truncated": false
+}
+```
+
+### Agent 构建的数据结构
+
+#### workspace_diffs（按 workspace 独立存储）
+
+```
+workspace_diffs = {
+    "<workspace_path>": {
+        "changed_files": [...],   // 脚本输出的 changed_files
+        "stat_summary": "...",
+        "has_changes": true/false
+    }
+}
+```
+
+#### diff_summary（合并后用于语义匹配）
+
+```
+diff_summary = {
+    "changed_files": [...],      # 所有 workspace 的文件路径（多 workspace 时加标识）
+    "stat_summary": "...",       # 合并统计
+    "diff_content": "...",       # 各 workspace diff_content 拼接，超 500 行截断
+    "truncated": true/false
+}
+```
+
+合并规则：各 workspace 的 `diff_content` 按 workspace 分段拼接，总计超 500 行截断。所有 `has_changes` 为 false 时，`diff_summary` 设为 `null`。
+
+---
+
+## 步骤 4：卡片选择 payload（新版本 UI）
+
+通过 `__interactive:icafe-cards <payload JSON>` 展示。
+
+### ⚠️ 字段命名强约束
+
+payload 使用 **camelCase**，但脚本 `match_card_cli.py` 返回的是 **snake_case**。Agent 必须在构造 payload 时完成转换，禁止将脚本原始字段名直接传入：
+
+| 脚本返回（snake_case） | payload 字段（camelCase） |
+|------------------------|--------------------------|
+| `space_prefix` | `spacePrefix` |
+| `space_id` | `spaceId` |
+| `space_name` | `spaceName` |
+| `available_spaces` | `availableSpaces` |
+| `defaults.type_id` | `defaults.typeId` |
+| `defaults.type_name` | `defaults.typeName` |
+
+**❌ 禁止直接使用脚本原始字段名：**
+```json
+{"cards":[],"space_prefix":"dkx","space_id":12345,"space_name":"测试空间","view_mode":"list"}
+```
+
+**✅ 正确结构（camelCase）：**
+```json
+{
+    "cards": [],
+    "spacePrefix": "dkx",
+    "spaceId": 12345,
+    "spaceName": "测试空间",
+    "availableSpaces": [{"id": 12345, "prefix": "dkx", "name": "测试空间", "types": [{"id": "5009", "name": "Bug"}]}],
+    "viewMode": "list",
+    "defaults": {
+        "title": "推荐标题",
+        "typeId": "5009",
+        "typeName": "Bug",
+        "spaceId": 12345
+    }
+}
+```
+
+字段直接从 `result` 对象映射：`cards` 已按匹配度排序，`viewMode` 由步骤 3 确定，`defaults` 中的 `title`/`typeName` 由 Agent 根据 diff 语义生成。
+
+---
+
+## 步骤 8：提交确认 payload（新版本 UI）
+
+通过 `__interactive:git-commit <payload JSON>` 展示。
+
+Agent 仅对 `hasChanges: true` 的 workspace 执行 `git branch -vv` + `git branch -r --sort=-committerdate`（`__silent:` 前缀），无变更的 workspace 跳过分支查询。多 workspace 的分支查询命令必须并行发出。
+
+### ⚠️ payload 顶层结构强约束
+
+**顶层有且仅有 3 个字段，字段名使用 camelCase：**
+
+| 顶层字段 | 类型 | 说明 |
+|----------|------|------|
+| `commitMessage` | string | commit message（注意：不是 `commit_message`） |
+| `boundCard` | object \| null | 绑定的 iCafe 卡片（注意：不是 `icafe_card`） |
+| `workspaces` | array | workspace 数组（注意：是复数 `workspaces`，不是单数 `workspace`） |
+
+**❌ 禁止出现在顶层的字段（常见错误）：**
+- `workspace`（单数字符串）→ 应为 `workspaces`（复数数组）
+- `commit_message`（snake_case）→ 应为 `commitMessage`（camelCase）
+- `changed_files` → 应嵌套在 `workspaces[].diffSummary.changed_files`
+- `icafe_card` → 应为 `boundCard`
+- 任何其他扁平化字段
+
+**❌ 错误示例（绝对禁止生成此结构）：**
+```json
+{
+    "commit_message": "study-ai-823 fix: ...",
+    "workspace": "/path/to/repo",
+    "changed_files": [{"file": "src/service.go", "insertions": 16, "deletions": 8}],
+    "icafe_card": {"sequence": 823, "title": "...", "spacePrefix": "study-ai"}
+}
+```
+
+**✅ 正确结构（即使只有 1 个 workspace 也必须用数组）：**
+```json
+{
+    "commitMessage": "dkx-200 修复登录问题",
+    "boundCard": {"sequence": "200", "title": "修复登录问题", "type": "Bug", "status": "开发中", "spacePrefix": "dkx"},
+    "workspaces": [
+        {
+            "workspace": "/path/to/frontend-app",
+            "repoName": "frontend-app",
+            "currentBranch": "feature/xxx",
+            "remoteBranches": [{"name": "feature/xxx", "isCurrent": true}, {"name": "main", "isCurrent": false}],
+            "hasChanges": true,
+            "diffSummary": {
+                "changed_files": [{"file": "src/App.tsx", "insertions": 76, "deletions": 66}],
+                "stat_summary": "2 files, +100, -78"
+            }
+        },
+        {
+            "workspace": "/path/to/shared-utils",
+            "repoName": "shared-utils",
+            "currentBranch": "",
+            "remoteBranches": [],
+            "hasChanges": false,
+            "diffSummary": null
+        }
+    ]
+}
+```
+
+### 字段构造规则
+
+- `commitMessage`：iCode 仓库格式 `"<spacePrefix>-<sequence> <描述>"`；非 iCode 仓库不带卡片 ID
+- `boundCard`：步骤 5 选定的卡片，非 iCode 或无卡片时为 `null`
+- `workspaces`：必须包含所有 workspace（含无变更的）
+  - `repoName`：路径最后一段
+  - `currentBranch`：有变更时从 `git branch -vv` 解析，无变更时空字符串
+  - `remoteBranches`：有变更时从 `git branch -r` 解析，跳过含 `->` 的行（HEAD 指针），去掉 `origin/` 前缀，标记当前追踪分支为 `isCurrent: true`，最多 10 个分支（当前追踪分支必须包含）
+  - `diffSummary`：有变更时用 `workspace_diffs` 中的 `changed_files` + `stat_summary`，无变更时 `null`
+
+### 用户操作返回
+
+- 确认：`{"action": "submit", "repos": [{"workspace": "...", "commitMessage": "...", "branch": "..."}]}`
+- 取消：`{"action": "cancel"}`

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

@@ -0,0 +1,209 @@
+# 新版本 IDE 交互指南
+
+本文档适用于**新版本 IDE**（IDE 名称占位符已替换、插件版本 ≥ 4.1.0）的交互方式。
+
+---
+
+## 全局规则
+
+**⚠️ 全局静默要求：整个流程中 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 中定义的命令模板，**加 `__silent:` 前缀**执行。
+
+---
+
+## 步骤 2：获取 git diff（新版本命令）
+
+使用 SKILL.md 步骤 2 中定义的命令模板，**加 `__silent:` 前缀**执行。
+
+---
+
+## 步骤 4：展示卡片选择（交互式 UI）
+
+调用 `run_command` 展示卡片选择/新建 UI，**禁止在调用前输出任何文字**：
+
+```
+run_command(command="__interactive:icafe-cards <payload JSON>")
+```
+
+payload 构造方法 — 用 `result` 中的字段和匹配结果拼接 JSON：
+```python
+import json
+payload = json.dumps({
+    "cards": result["cards"],        # 已按匹配度排序
+    "spacePrefix": result["space_prefix"],
+    "spaceId": result["space_id"],
+    "spaceName": result["space_name"],
+    "availableSpaces": result["available_spaces"],
+    "viewMode": viewMode,  # "list" 或 "create"
+    "defaults": {
+        "title": result["defaults"]["title"],
+        "typeId": result["defaults"]["type_id"],
+        "typeName": result["defaults"]["type_name"],
+        "spaceId": result["space_id"]
+    }
+})
+command = f"__interactive:icafe-cards {payload}"
+```
+
+完整示例 command 值：
+```
+__interactive:icafe-cards {"cards":[{"sequence":"200","title":"修复登录问题","type":"Bug","status":"开发中"}],"spacePrefix":"dkx","spaceId":12345,"spaceName":"测试空间","viewMode":"list","availableSpaces":[{"id":12345,"prefix":"dkx","name":"测试空间","types":[{"id":"5009","name":"Bug"},{"id":"5007","name":"Story"}]}],"defaults":{"title":"修复登录验证码刷新问题","typeId":"5009","typeName":"Bug","spaceId":12345}}
+```
+
+---
+
+## 步骤 5：处理用户操作（新版本 IDE）
+
+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：展示提交确认（交互式 UI）
+
+调用 `run_command` 展示提交确认 UI：
+
+```
+run_command(command="__interactive:git-commit <payload JSON>")
+```
+
+Agent 仅对 **`hasChanges: true` 的 workspace** 执行 `git branch -vv` + `git branch -r --sort=-committerdate`（使用 `__silent:` 前缀）。**无变更的 workspace 跳过分支查询，`currentBranch` 和 `remoteBranches` 使用空值。** 多 workspace 时，不同 workspace 的分支查询命令必须在同一次响应中并行发出。然后构造 payload：
+
+**⚠️ 重要：`workspaces` 数组必须包含环境上下文 `Workspace Path` 中列出的所有 workspace，不可遗漏。** 即使某个 workspace 没有变更（`hasChanges: false`），也必须包含在数组中。
+
+**⚠️ payload 顶层结构强约束（必须严格遵守）：**
+- 顶层有且仅有 3 个字段：`commitMessage`、`boundCard`、`workspaces`
+- **`workspaces` 是复数（数组），不是单数 `workspace`（字符串）**——即使只有 1 个 workspace 也必须用数组
+- 使用 camelCase 命名：`commitMessage` 不是 `commit_message`，`boundCard` 不是 `icafe_card`
+- `changed_files` 必须嵌套在 `workspaces[].diffSummary` 内，禁止放在顶层
+
+**❌ 禁止生成的扁平化结构：**
+```json
+{"commit_message":"xxx","workspace":"/path","changed_files":[...],"icafe_card":{...}}
+```
+
+payload 结构（多 workspace 格式）：
+```json
+{
+    "commitMessage": "dkx-200 修复登录问题",
+    "boundCard": {"sequence": "200", "title": "修复登录问题", "type": "Bug", "status": "开发中", "spacePrefix": "dkx"},
+    "workspaces": [
+        {
+            "workspace": "/path/to/frontend-app",
+            "repoName": "frontend-app",
+            "currentBranch": "feature/xxx",
+            "remoteBranches": [{"name": "feature/xxx", "isCurrent": true}, {"name": "main", "isCurrent": false}],
+            "hasChanges": true,
+            "diffSummary": {
+                "changed_files": [{"file": "src/App.tsx", "insertions": 76, "deletions": 66}],
+                "stat_summary": "2 files, +100, -78"
+            }
+        },
+        {
+            "workspace": "/path/to/shared-utils",
+            "repoName": "shared-utils",
+            "currentBranch": "",
+            "remoteBranches": [],
+            "hasChanges": false,
+            "diffSummary": null
+        }
+    ]
+}
+```
+
+**构造规则：**
+- `commitMessage`：基于 diff 和绑定卡片生成的 commit message。iCode 仓库格式为 `"<spacePrefix>-<sequence> <brief_description>"`；非 iCode 仓库不带卡片 ID 前缀，仅生成描述性 message
+- `boundCard`：步骤 5 中选定的卡片信息。非 iCode 仓库或无卡片时为 `null`
+- `workspaces`：对每个 workspace 目录，使用步骤 2 中构建的 `workspace_diffs` 数据：
+  - `workspace`：绝对路径
+  - `repoName`：路径的最后一段
+  - `currentBranch`：有变更时从 `git branch -vv` 解析当前分支名，无变更时为空字符串
+  - `remoteBranches`：有变更时从 `git branch -r` 解析远程分支列表；无变更时为空数组。解析规则：
+    1. 跳过包含 `->` 的行（如 `origin/HEAD -> origin/master`，这是 HEAD 指针，不是分支）
+    2. 对每一行 trim 后去掉 `origin/` 前缀，得到分支名
+    3. 从 `git branch -vv` 输出中解析当前分支的远程追踪分支名，将匹配的分支标记为 `isCurrent: true`，其余为 `false`
+    4. 最多取 10 个分支（当前追踪分支必须包含在内），按最近活跃排序
+  - `hasChanges`：该 workspace 是否有变更（`workspace_diffs[path].has_changes`）
+  - `diffSummary`：有变更时为 `workspace_diffs[path]` 中的 `changed_files` + `stat_summary`，无变更时为 `null`
+
+**顶层不再有旧的 `currentBranch`/`remoteBranches`/`diffSummary` 字段。**
+
+完整示例 command 值：
+```
+__interactive:git-commit {"commitMessage":"dkx-200 修复登录验证码刷新问题","boundCard":{"sequence":"200","title":"修复登录问题","type":"Bug","status":"开发中","spacePrefix":"dkx"},"workspaces":[{"workspace":"/home/user/frontend-app","repoName":"frontend-app","currentBranch":"feature/login-fix","remoteBranches":[{"name":"feature/login-fix","isCurrent":true},{"name":"main","isCurrent":false}],"hasChanges":true,"diffSummary":{"changed_files":[{"file":"src/login.ts","insertions":15,"deletions":3}],"stat_summary":"1 file, +15, -3"}}]}
+```
+
+用户操作后，tool output 返回 JSON：
+- 确认提交：`{"action": "submit", "repos": [{"workspace": "...", "commitMessage": "...", "branch": "..."}]}`
+- 取消提交：`{"action": "cancel"}`
+
+---
+
+## 步骤 9：执行提交（新版本 IDE）
+
+从 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"：**
+- 输出"已取消提交"