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

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

@@ -0,0 +1,241 @@
+---
+name: auto-commit
+description: 当用户完成代码修改、需要提交代码时，必须使用此 skill，而非直接执行 git commit。自动获取 git diff、匹配 iCafe 活跃卡片、生成 commit message，并引导用户完成绑定卡片和代码提交。
+user-invocable: false
+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）
+
+**Agent 必须通过 `__interactive:` UI 组件与用户交互（步骤 4 用 `__interactive:icafe-cards`，步骤 8 用 `__interactive:git-commit`）。禁止自行拼接 payload JSON，必须通过 builder 脚本验证后调用。**
+
+---
+
+## 步骤 0：前置检查（串行执行，完全静默）
+
+**整个前置检查过程完全静默。**
+
+### 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` 则立即结束。脚本会自动将 result 写入统一缓存文件（`/tmp/__comate_auto_commit_cache.json`），供步骤 4 使用。
+
+**失败降级**：脚本报错/超时/非 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 时保持风格一致。**不输出任何内容。** 脚本同时将 diff 结果写入统一缓存文件（`/tmp/__comate_auto_commit_cache.json`），供步骤 8 自动构建 payload。
+
+脚本输出 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。
+
+**否则，必须通过 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：处理用户操作
+
+根据用户选择/创建/跳过处理，参考 `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}"
+```
+
+## 步骤 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：展示提交确认
+
+必须通过 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：执行提交 + 输出结果
+
+参考 `references/interaction_instruction.md` 执行提交。
+
+**推送方式：** 统一使用 `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 仓库）
+
+代码变更未完成，请确认后再提交
+```
+
+---
+
+## 配置
+
+**认证**：token 按优先级读取 `COMATE_AUTH_TOKEN` 环境变量 → `~/.comate/login` 文件。
+
+**跨平台**：统一使用 `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/references/data_structures.md

@@ -0,0 +1,183 @@
+# 数据结构与 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`。
+
+---
+
+## 统一缓存文件
+
+路径：`/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 完整输出 */ }
+  }
+}
+```
+
+写入时机：
+- `icafe_result`：步骤 1 由 `match_card_cli.py` 写入
+- `git_diffs[workspace]`：步骤 2 由 `git_diff_cli.py` 对每个 workspace 写入
+
+清理时机：步骤 9 执行完成后由 Agent 清理（`rm -f /tmp/__comate_auto_commit_cache.json`）。
+
+---
+
+## Payload Builder 脚本
+
+Agent 在构造 `__interactive:` payload 时，**禁止自行拼接 JSON**，必须通过以下脚本验证并生成。脚本会对输入数据进行结构校验，返回验证结果。
+
+### 通用用法
+
+```bash
+__silent: python3 <skill_directory>/scripts/<script_name>.py --json '<camelCase 数据 JSON>'
+```
+
+### 输出格式
+
+- 验证通过：`{"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 中降级格式）
+
+---
+
+### build_icafe_cards_payload.py（步骤 4）
+
+**作用**：从缓存文件读取原始数据，自动完成 snake_case → camelCase 转换并验证，输出 `__interactive:icafe-cards` 的 payload。
+
+**用法**（最简形式）：
+```bash
+python3 build_icafe_cards_payload.py --view-mode list --default-title "优化 xxx 相关功能"
+```
+
+脚本自动读取 `/tmp/__comate_icafe_result.json`（由 `match_card_cli.py` 在步骤 1 自动写入）。
+
+**Agent 不需要手动转换任何字段名，不需要拼 JSON，不需要传文件路径。** 只需传入 2 个必填参数（`--view-mode`、`--default-title`）和 1 个可选参数（`--cards`，排序后的卡片列表）。
+
+**验证规则**：
+- `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)`
+
+---
+
+### 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 结构**：
+
+```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"
+            }
+        }
+    ]
+}
+```
+
+**验证规则**（脚本内部自动保证，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 输出一致）
+
+### 用户操作返回
+
+- 确认：`{"action": "submit", "repos": [{"workspace": "...", "commitMessage": "...", "branch": "..."}]}`
+- 取消：`{"action": "cancel"}`

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

@@ -0,0 +1,19 @@
+{
+  "56075": "Epic",
+  "54443": "Feature",
+  "5007": "Story",
+  "54444": "Task",
+  "54621": "Tech Feature",
+  "54622": "Tech Task",
+  "5009": "Bug",
+  "5811": "Bug(线上)",
+  "5011": "Case",
+  "65085": "非研发任务",
+  "49460": "项目",
+  "5008": "需求",
+  "5010": "任务",
+  "88805": "Prompt Story",
+  "88806": "Prompt Task",
+  "88807": "GenAI Data Story",
+  "88808": "GenAI Data Task"
+}