@comate/zulu 1.3.3 → 1.3.4-beta.2

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

@@ -27,64 +27,19 @@ metadata:
 - **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`
+**Agent 必须通过 `__interactive:` UI 组件与用户交互（步骤 4 用 `__interactive:icafe-cards`，步骤 8 用 `__interactive:git-commit`）。禁止自行拼接 payload JSON，必须通过 builder 脚本验证后调用。**
 
 ---
 
 ## 步骤 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 仓库检测
+### iCode 仓库检测
 
 对第一个 workspace 执行：
 ```
-[__silent: ]cd <第一个workspace_path> && git remote -v
+__silent: cd <第一个workspace_path> && git remote -v
 ```
 
 检查输出是否包含 `icode.baidu.com`：包含 → `is_icode_repo = true`，不包含或失败 → `is_icode_repo = false`。
@@ -95,10 +50,10 @@ metadata:
 
 执行：
 ```bash
-[__silent: ]python3 <skill_directory>/scripts/match_card_cli.py --username "${COMATE_USERNAME}"
+__silent: python3 <skill_directory>/scripts/match_card_cli.py --username "${COMATE_USERNAME}"
 ```
 
-解析 stdout 的 JSON 为 `result`。先检查 `result.disabled`，为 `True` 则立即结束。
+解析 stdout 的 JSON 为 `result`。先检查 `result.disabled`，为 `True` 则立即结束。脚本会自动将 result 写入统一缓存文件（`/tmp/__comate_auto_commit_cache.json`），供步骤 4 使用。
 
 **失败降级**：脚本报错/超时/非 JSON → 标记 `icafe_failed = true`，跳过步骤 3-6，直接进入步骤 7 生成无卡片 commit message。
 
@@ -111,15 +66,15 @@ metadata:
 对每个 workspace 执行：
 
 ```bash
-[__silent: ]python3 <skill_directory>/scripts/git_diff_cli.py --workspace <workspace_path>
+__silent: python3 <skill_directory>/scripts/git_diff_cli.py --workspace <workspace_path>
 ```
 
 同时对第一个 workspace 并行执行获取 commit 风格：
 ```bash
-[__silent: ]cd <第一个workspace_path> && git log --oneline -n 20
+__silent: cd <第一个workspace_path> && git log --oneline -n 20
 ```
 
-Agent 从 git log 分析 `commit_style`（前缀格式、语言、描述风格），供步骤 3/7 生成 commit message 时保持风格一致。**不输出任何内容。**
+Agent 从 git log 分析 `commit_style`（前缀格式、语言、描述风格），供步骤 3/7 生成 commit message 时保持风格一致。**不输出任何内容。** 脚本同时将 diff 结果写入统一缓存文件（`/tmp/__comate_auto_commit_cache.json`），供步骤 8 自动构建 payload。
 
 脚本输出 JSON 格式、以及如何构建 `workspace_diffs` 和 `diff_summary`，详见 `references/data_structures.md`（包含脚本输出示例和合并规则）。
 
@@ -159,15 +114,27 @@ Agent 内部基于 diff 内容生成 `defaults.title`（建卡默认标题）：
 
 **上下文快捷匹配：** 如果对话中用户已指定卡片（卡片 ID、iCafe 链接等），直接作为 `selected_card`，跳过 UI。
 
-**否则，必须展示卡片选择 UI，禁止自行替用户选择或创建卡片。** 根据版本展示交互 UI，参考对应 reference 文件。**新版本必须使用 `__interactive:icafe-cards` 展示，禁止用文本列表替代。**
+**否则，必须通过 builder 脚本验证 payload 后展示卡片选择 UI。禁止自行拼接 JSON 或替用户选择/创建卡片。**
+
+具体操作：
+1. 确定模型决策：`viewMode`（`"list"` 或 `"create"`）、`defaults.title`（Agent 根据 diff 语义生成）、`cards`（步骤 3 排序后，可选）
+2. 调用 builder 脚本（脚本自动从 `/tmp/__comate_icafe_result.json` 读取 result，不需要模型传文件）：
+   ```
+   __silent: python3 <skill_directory>/scripts/build_icafe_cards_payload.py --view-mode list --default-title "优化 xxx 相关功能"
+   ```
+   **⚠️ 不需要传 --result-file、不需要手动转换字段名、不需要拼 JSON。脚本自动完成所有转换。`--cards` 可选，不传则使用 result 中的原始顺序。**
+3. 解析输出：
+   - `{"valid": true, "payload": {...}}` → 提取 `payload` 内层 JSON，使用 `run_command` 调用 `__interactive:icafe-cards`（禁止将整个 `{"valid":true,"payload":{...}}` 传入，禁止将 payload 作为文本输出）
+   - `{"valid": false, "errors": [...]}` → 根据 errors 修正数据，重试一次；仍失败则按 `references/interaction_instruction.md` 降级为文本交互
+   - `{"error": "..."}` → 直接降级为文本交互
 
 ## 步骤 5：处理用户操作
 
-根据版本处理用户选择/创建/跳过，参考对应 reference 文件。
+根据用户选择/创建/跳过处理，参考 `references/interaction_instruction.md`。
 
 **创建卡片命令模板：**
 ```
-[__silent: ]cd <用户项目目录> && python3 <skill_directory>/scripts/create_card_cli.py --title "<card.title>" --space-prefix "<card.spacePrefix>" --type-name "<card.typeName>" --username "${COMATE_USERNAME}"
+__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
@@ -202,11 +169,26 @@ Agent 内部分析以下信号判断是否展示提交确认，**不输出任何
 
 ## 步骤 8：展示提交确认
 
-根据版本展示确认 UI，参考对应 reference 文件。**新版本必须使用 `__interactive:git-commit` 展示，禁止用文本替代。** payload 必须严格遵循 `references/data_structures.md` 中「步骤 8 提交确认 payload」的结构定义，禁止自行发明字段或扁平化结构。
+必须通过 builder 脚本构造并验证 payload 后展示，禁止自行拼接 JSON 或用文本替代。
+
+### 推荐方式：缓存模式（Agent 不需要手动构造 workspaces）
+
+1. 调用 builder 脚本，传入 commit message 和绑定卡片：
+   ```
+   __silent: python3 <skill_directory>/scripts/build_git_commit_payload.py --cache --commit-message "<commit_message>" --bound-card '<card JSON 或 null>'
+   ```
+   - `--cache`：从统一缓存读取 diff 数据，自动执行 git branch 命令获取分支信息
+   - `--commit-message`：必填
+   - `--bound-card`：选定的卡片 JSON（步骤 5 获得），非 iCode 仓库或无卡片传 `'null'`
+
+2. 解析输出：
+   - `{"valid": true, "payload": {...}}` → 提取 `payload` 内层 JSON，使用 `run_command` 调用 `__interactive:git-commit`（禁止将整个 `{"valid":true,"payload":{...}}` 传入，禁止将 payload 作为文本输出）
+   - `{"valid": false, "errors": [...]}` → 根据 errors 修正数据，重试一次；仍失败则按 `references/interaction_instruction.md` 降级为文本交互
+   - `{"error": "..."}` → 直接降级为文本交互
 
 ## 步骤 9：执行提交 + 输出结果
 
-根据版本处理提交，参考对应 reference 文件。
+参考 `references/interaction_instruction.md` 执行提交。
 
 **推送方式：** 统一使用 `git push origin HEAD:refs/for/<branch>` 推送到 Gerrit 代码评审。
 
@@ -247,14 +229,12 @@ Agent 内部分析以下信号判断是否展示提交确认，**不输出任何
 代码变更未完成，请确认后再提交
 ```
 
-旧版本 IDE 提交成功后额外提示推送命令。
-
 ---
 
 ## 配置
 
 **认证**：token 按优先级读取 `COMATE_AUTH_TOKEN` 环境变量 → `~/.comate/login` 文件。
 
-**跨平台**：所有 `python3` 替换为步骤 0b 检测到的命令名；Windows 上 `cd` 改为 `cd /d`，错误抑制用 `2>NUL`。
+**跨平台**：统一使用 `python3` 调用脚本，如果执行失败（命令不存在），自动依次尝试 `python`、`py -3`，某个成功则后续统一使用该命令名。
 
 **卡片链接**：`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

@@ -67,84 +67,90 @@ diff_summary = {
 
 ---
 
-## 步骤 4：卡片选择 payload（新版本 UI）
+## 统一缓存文件
 
-通过 `__interactive:icafe-cards <payload JSON>` 展示。
+路径：`/tmp/__comate_auto_commit_cache.json`
 
-### ⚠️ 字段命名强约束
+结构：
+```json
+{
+  "icafe_result": { /* match_card_cli.py 完整输出 */ },
+  "git_diffs": {
+    "/path/to/workspace1": { /* git_diff_cli.py 完整输出 */ },
+    "/path/to/workspace2": { /* git_diff_cli.py 完整输出 */ }
+  }
+}
+```
 
-payload 使用 **camelCase**，但脚本 `match_card_cli.py` 返回的是 **snake_case**。Agent 必须在构造 payload 时完成转换，禁止将脚本原始字段名直接传入：
+写入时机：
+- `icafe_result`：步骤 1 由 `match_card_cli.py` 写入
+- `git_diffs[workspace]`：步骤 2 由 `git_diff_cli.py` 对每个 workspace 写入
 
-| 脚本返回（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` |
+清理时机：步骤 9 执行完成后由 Agent 清理（`rm -f /tmp/__comate_auto_commit_cache.json`）。
 
-**❌ 禁止直接使用脚本原始字段名：**
-```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
-    }
-}
+## Payload Builder 脚本
+
+Agent 在构造 `__interactive:` payload 时，**禁止自行拼接 JSON**，必须通过以下脚本验证并生成。脚本会对输入数据进行结构校验，返回验证结果。
+
+### 通用用法
+
+```bash
+__silent: python3 <skill_directory>/scripts/<script_name>.py --json '<camelCase 数据 JSON>'
 ```
 
-字段直接从 `result` 对象映射：`cards` 已按匹配度排序，`viewMode` 由步骤 3 确定，`defaults` 中的 `title`/`typeName` 由 Agent 根据 diff 语义生成。
+### 输出格式
+
+- 验证通过：`{"valid": true, "payload": {...}}`
+- 验证失败：`{"valid": false, "errors": ["具体错误描述", ...]}`
+- 系统错误：`{"error": "..."}`
+
+### 处理流程
+
+1. Agent 构造 camelCase 数据
+2. 调用 builder 脚本传入数据
+3. 解析脚本输出：
+   - `valid: true` → 用 `payload` 调用 `__interactive:` UI
+   - `valid: false` → 根据 `errors` 修正数据，重新调用脚本（最多重试 1 次）
+   - 重试仍失败或 `error` → 降级为文本交互（参考 interaction_instruction.md 中降级格式）
 
 ---
 
-## 步骤 8：提交确认 payload（新版本 UI）
+### build_icafe_cards_payload.py（步骤 4）
 
-通过 `__interactive:git-commit <payload JSON>` 展示。
+**作用**：从缓存文件读取原始数据，自动完成 snake_case → camelCase 转换并验证，输出 `__interactive:icafe-cards` 的 payload。
 
-Agent 仅对 `hasChanges: true` 的 workspace 执行 `git branch -vv` + `git branch -r --sort=-committerdate`（`__silent:` 前缀），无变更的 workspace 跳过分支查询。多 workspace 的分支查询命令必须并行发出。
+**用法**（最简形式）：
+```bash
+python3 build_icafe_cards_payload.py --view-mode list --default-title "优化 xxx 相关功能"
+```
 
-### ⚠️ payload 顶层结构强约束
+脚本自动读取 `/tmp/__comate_icafe_result.json`（由 `match_card_cli.py` 在步骤 1 自动写入）。
 
-**顶层有且仅有 3 个字段，字段名使用 camelCase：**
+**Agent 不需要手动转换任何字段名，不需要拼 JSON，不需要传文件路径。** 只需传入 2 个必填参数（`--view-mode`、`--default-title`）和 1 个可选参数（`--cards`，排序后的卡片列表）。
 
-| 顶层字段 | 类型 | 说明 |
-|----------|------|------|
-| `commitMessage` | string | commit message（注意：不是 `commit_message`） |
-| `boundCard` | object \| null | 绑定的 iCafe 卡片（注意：不是 `icafe_card`） |
-| `workspaces` | array | workspace 数组（注意：是复数 `workspaces`，不是单数 `workspace`） |
+**验证规则**：
+- `cards` 为数组，每项含 `sequence/title/type/status`
+- `viewMode` 为 `"list"` 或 `"create"`
+- `availableSpaces` 每项含 `id/prefix/name/types`，`types` 每项含 `id/name`
+- `defaults` 含 `title(string)/typeId(string)/typeName(string)/spaceId(int)`
 
-**❌ 禁止出现在顶层的字段（常见错误）：**
-- `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"}
-}
+### build_git_commit_payload.py（步骤 8）
+
+**作用**：验证并输出 `__interactive:git-commit` 的 payload。
+
+**用法**：脚本自动从统一缓存读取 diff 数据，执行 git branch 获取分支信息，Agent 只需传入 commit message 和绑定卡片：
+```bash
+python3 build_git_commit_payload.py --cache --commit-message "<message>" --bound-card '<card JSON 或 null>'
 ```
+- `--commit-message`（必填）：commit message
+- `--bound-card`（必填）：选定卡片 JSON 对象，无卡片传字符串 `'null'`
+
+**输出 payload 结构**：
 
-**✅ 正确结构（即使只有 1 个 workspace 也必须用数组）：**
 ```json
 {
     "commitMessage": "dkx-200 修复登录问题",
@@ -160,28 +166,16 @@ Agent 仅对 `hasChanges: true` 的 workspace 执行 `git branch -vv` + `git bra
                 "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`
+**验证规则**（脚本内部自动保证，Agent 无需关心）：
+- 顶层包含 `commitMessage`, `boundCard`, `workspaces`
+- `boundCard` 为 `null` 或包含 `sequence/title/type/status/spacePrefix` 的对象
+- 每个 workspace 自动填充 `workspace/repoName/currentBranch/remoteBranches/hasChanges/diffSummary`
+- `diffSummary` 内部的 `changed_files` 和 `stat_summary` 保持 snake_case（与 git_diff_cli.py 输出一致）
 
 ### 用户操作返回
 

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 的规则处理对应操作。