@comate/zulu 1.1.0 → 1.2.0

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

@@ -0,0 +1,646 @@
+---
+name: smart-commit
+description: 当完成一定量的代码修改后，考虑是否应该提交一个 commit message。如果需要，则使用此 skill 而非直接 git commit。
+---
+
+# 智能提交助手
+
+## 版本信息
+
+- **IDE 名称**: ${COMATE_IDE_NAME}
+- **插件版本**: ${COMATE_PLUGIN_VERSION}
+- **用户名**: ${COMATE_USERNAME}
+
+## 概述
+
+本技能将当前工作区的 git diff 与用户在 iCafe 上的活跃卡片进行匹配，支持选择已有卡片或新建卡片，自动生成 commit message 并完成提交。
+
+**调起即执行，流程完全固定，不做任何意图分析。**
+
+## ⛔ 前置开关检查（最高优先级，必须在一切操作之前执行）
+
+**此检查的优先级高于所有后续步骤。如果开关关闭，禁止执行任何后续操作。**
+
+通过以下方式进行检查（在调用 Python 脚本之前，**必须加 `__silent:` 前缀**）：
+
+```
+__silent: cat ~/.comate/settings.json 2>/dev/null || echo '{}'
+```
+
+解析返回的 JSON，检查 `enableSmartCommit` 字段：
+- 如果值为 `false` → **立即结束 skill，不再输出任何内容，不再执行任何后续步骤**
+- 如果值为 `true` 或字段不存在（默认开启）→ 继续执行后续步骤
+
+## 步骤 0：检测 IDE 版本兼容性（必须首先执行，完全静默）
+
+**⚠️ 重要：此步骤必须在所有其他步骤之前执行，决定后续使用哪套交互方式。**
+
+**⚠️ 静默要求：版本检测过程完全静默，禁止输出任何与版本检测相关的信息，包括但不限于：**
+- "检测到当前 IDE 版本..."
+- "将使用文本交互流程..."
+- "当前版本不支持..."
+- 任何提及"版本"、"降级"、"兼容"等字眼
+
+通过检查上方「版本信息」中的占位符是否被替换来判断：
+
+**判断逻辑：**
+1. 如果 IDE 名称仍包含 `COMATE_IDE_NAME`（未替换）→ **旧版本**
+2. 如果插件版本仍包含 `COMATE_PLUGIN_VERSION`（未替换）→ **旧版本**
+3. 如果版本号 < `4.1.0` → **旧版本**
+4. 否则 → **新版本**
+
+根据判断结果**直接**选择交互方式，**不输出任何解释**：
+- **新版本** → 使用 `__interactive:` UI 组件交互
+- **旧版本** → 使用纯文本交互（不支持 `__silent:` 和 `__interactive:` 前缀）
+
+---
+
+## 全局规则
+
+### 新版本 IDE 规则
+
+**⚠️ 全局静默要求：整个流程中 Agent 仅通过 `__interactive:` UI 组件与用户交互。除步骤 7 的最终结果文字外，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:` 前缀。唯一例外是步骤 6 的 git commit 命令，需要展示提交结果给用户。**
+
+**⚠️ 禁止额外命令：Agent 不得在流程步骤之外自行执行任何 shell 命令（如 `git status`、`ls` 等）。iCafe 数据由步骤 1 的 Python 脚本获取，git diff 由步骤 1.5 中 Agent 按规定命令获取。**
+
+**⚠️ 工作目录规则：Skill 执行时的工作目录可能不是用户项目目录。当命令需要在用户项目目录下执行时（如 git 操作、Python 脚本），必须在命令中加 `cd <用户项目目录> &&` 切换目录。但 `__silent:` 或 `__interactive:` 前缀必须始终在命令最开头。**
+
+**⚠️ 多 Workspace 规则：用户可能打开了多个代码库（multi-root workspace）。环境上下文中的 `Workspace Path` 会列出所有 workspace 路径。在步骤 1.5 和步骤 6 中，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 数据
+
+通过 `run_command` 执行以下命令获取 iCafe 卡片数据。**新版本 IDE 必须使用带 `__silent:` 前缀的命令；旧版本 IDE 不支持 `__silent:` 前缀，去掉前缀后直接执行。**
+
+**新版本 IDE 完整命令（直接复制执行，包含 `__silent:` 前缀）：**
+
+```bash
+__silent: cd <用户项目目录> && PYTHONPATH="<skill_directory>/scripts" python3 -c "
+import sys, json
+sys.path.insert(0, '<skill_directory>/scripts')
+from icafe.matching import find_matching_card
+result = find_matching_card(current_user=sys.argv[1] if len(sys.argv) > 1 else None)
+print(json.dumps(result))
+" '${COMATE_USERNAME}'
+```
+
+**旧版本 IDE 命令（去掉 `__silent:` 前缀）：**
+
+```bash
+cd <用户项目目录> && PYTHONPATH="<skill_directory>/scripts" python3 -c "
+import sys, json
+sys.path.insert(0, '<skill_directory>/scripts')
+from icafe.matching import find_matching_card
+result = find_matching_card(current_user=sys.argv[1] if len(sys.argv) > 1 else None)
+print(json.dumps(result))
+" '${COMATE_USERNAME}'
+```
+
+从 stdout 输出的 JSON 解析为 `result` 对象。
+
+**⚠️ 开关检查：** 解析 `result` 后，**首先**检查 `result.get("disabled")` 是否为 `True`。如果是，**必须立即结束 skill，不再执行任何后续步骤，不输出任何内容**。
+
+`find_matching_card()` 内部自动完成用户获取、空间检测、卡片查询等工作，返回结构化数据。**不再获取 git diff，diff 由 Agent 在步骤 1.5 中自行获取。**
+
+## 步骤 1.5：获取 git diff（Agent 执行，支持多 workspace，per-file 统计）
+
+**⚠️ 多 Workspace 必须逐一执行：** Agent 必须从环境上下文的 `Workspace Path` 中读取**所有**路径。`Workspace Path` 的格式为：
+```
+Workspace Path:
+- /path/to/repo1
+- /path/to/repo2
+```
+Agent 必须对列表中的**每一个路径**分别执行下方的 git diff 命令。**即使只有部分 workspace 有变更，也必须对所有 workspace 都执行一次**，以确定每个仓库是否有变更。禁止只对第一个 workspace 执行后就跳过其余的。
+
+**新版本 IDE 命令必须加 `__silent:` 前缀。**
+
+对每个 workspace 目录依次执行（**每个 workspace 单独一次 `run_command` 调用**）：
+
+```
+__silent: cd <workspace_path> && git diff HEAD --stat 2>/dev/null; echo "---DIFF_CONTENT_SEPARATOR---"; git diff HEAD --numstat 2>/dev/null; echo "---DIFF_CONTENT_SEPARATOR---"; git diff HEAD 2>/dev/null
+```
+
+Agent 从每个 workspace 的输出中解析并在内部构建两级数据结构，**不输出任何内容**：
+
+### 1) `workspace_diffs` — 按 workspace 独立存储
+
+```
+workspace_diffs = {
+    "<workspace_path>": {
+        "changed_files": [
+            {"file": "src/App.tsx", "insertions": 76, "deletions": 66},
+            {"file": "src/components/Header.tsx", "insertions": 24, "deletions": 12}
+        ],
+        "stat_summary": "2 files, +100, -78",
+        "has_changes": true
+    },
+    "<workspace_path_2>": {
+        "changed_files": [],
+        "stat_summary": "",
+        "has_changes": false
+    }
+}
+```
+
+### 2) `diff_summary` — 合并后用于步骤 2 语义匹配
+
+```
+diff_summary = {
+    "changed_files": [...],      # 所有 workspace 的变更文件路径字符串列表（含 workspace 标识）
+    "stat_summary": "...",       # 合并后的统计摘要
+    "diff_content": "...",       # 合并后的 diff 全文（超过 500 行截断）
+    "truncated": true/false
+}
+```
+
+**解析规则：**
+1. 第一个 `---DIFF_CONTENT_SEPARATOR---` 之前是 `git diff HEAD --stat` 的输出：
+   - 每行 `|` 前的部分是文件路径
+   - 最后一行（如 "2 files changed, 15 insertions, 3 deletions"）为该 workspace 的 `stat_summary`
+2. 两个 `---DIFF_CONTENT_SEPARATOR---` 之间是 `git diff HEAD --numstat` 的输出：
+   - 每行格式：`<insertions>\t<deletions>\t<file>`，解析为 `{"file": ..., "insertions": ..., "deletions": ...}` 加入该 workspace 的 `changed_files`
+   - 据此生成该 workspace 的 `stat_summary`，格式 `"N files, +X, -Y"`
+3. 第二个 `---DIFF_CONTENT_SEPARATOR---` 之后是完整 diff 内容
+4. 如果 diff 内容超过 500 行，截断并设置 `truncated = true`
+5. 多 workspace 时，合并 `diff_summary` 将各 workspace 的文件路径加上 workspace 标识，diff 内容按 workspace 分段拼接
+
+**如果所有 workspace 均无变更（所有 `changed_files` 为空），`diff_summary` 设为 `null`。**
+
+同时，Agent 内部基于 diff 内容生成 `defaults.title`（建卡默认标题）：取前 3 个变更文件名，生成格式为 `"优化 xxx, yyy 相关功能"`。将生成的标题写入 `result["defaults"]["title"]`。
+
+Agent 内部分析 git diff 内容，总结代码变更的语义（修改了哪些模块、变更目的、涉及的业务领域），**不输出任何内容**，仅用于后续生成 commit message。
+
+## 步骤 2：语义匹配（内部完成，禁止输出）
+
+在展示 UI 或文本**之前**，Agent 需要在内部（不输出）完成语义匹配：
+- 如果 `diff_summary` 不为 `null` 且 `result["cards"]` 非空：
+  1. 根据 `diff_summary` 中的变更文件、diff 内容，对每张卡片进行语义匹配度评分（0-100 分）
+     - **语义相关性**（主要）：diff 修改的模块、函数、业务逻辑是否与卡片标题描述的任务相关
+     - **类型匹配度**（次要）：diff 的变更性质（修复 bug、新增功能、重构等）是否与卡片类型吻合
+  2. 按 `score` 降序对 `result["cards"]` 重新排序
+  3. **过滤低分卡片**：仅保留 score >= 30 的卡片，score < 30 的卡片从 `result["cards"]` 中移除
+  4. 确定 `viewMode`：过滤后卡片非空 → `"list"`，过滤后卡片为空 → `"create"`
+  5. 记住 `recommended_commit_message` 供后续步骤使用
+- 如果 `diff_summary` 为 `null` 或卡片为空：`viewMode` 默认为 `"create"`
+
+## 步骤 3：展示卡片选择
+
+**禁止跳过此步骤，禁止自行替用户选择或创建卡片。**
+
+### 新版本 IDE（交互式 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"],
+        "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":"测试空间"}],"defaults":{"title":"修复登录验证码刷新问题","typeId":"5009","spaceId":12345}}
+```
+
+### 旧版本 IDE（文本交互）
+
+根据 `viewMode` 输出文本列表。
+
+**当 `viewMode == "list"`（有高匹配卡片）时：**
+
+先展示卡片列表（已按匹配度排序，标注匹配理由），再展示新建选项：
+
+```
+📋 根据代码变更，找到以下匹配的 iCafe 卡片：
+
+1. ⭐ [${spacePrefix}-${card1.sequence}] ${card1.title}
+   类型: ${card1.type} | 状态: ${card1.status}
+   匹配理由: ${reason}
+
+2. [${spacePrefix}-${card2.sequence}] ${card2.title}
+   类型: ${card2.type} | 状态: ${card2.status}
+
+（最多显示 10 张卡片，⭐ 标记匹配度较高的卡片）
+
+---
+🆕 如需新建卡片，为你推荐以下信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}（类型 ID: ${result.defaults.type_id}）
+
+---
+请回复：
+- 输入序号（如 "1"）选择对应卡片
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+**当 `viewMode == "create"`（无高匹配卡片）时：**
+
+先展示新建卡片推荐（突出位置），再附上已有卡片作为备选：
+
+```
+💡 当前代码变更与已有卡片匹配度较低，建议新建卡片：
+
+🆕 推荐新建卡片信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}（类型 ID: ${result.defaults.type_id}）
+
+---
+📋 以下是你当前活跃的卡片（供参考）：
+
+1. [${spacePrefix}-${card1.sequence}] ${card1.title}
+   类型: ${card1.type} | 状态: ${card1.status}
+
+（最多显示 10 张卡片）
+
+---
+请回复：
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入序号（如 "1"）选择对应卡片
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+如果没有找到卡片，输出：
+
+```
+📋 未找到可关联的 iCafe 卡片
+
+🆕 为你推荐以下建卡信息：
+- 推荐标题：${result.defaults.title}
+- 推荐空间：${spaceName} (${spacePrefix})
+- 推荐类型：${推荐的类型名称}
+
+---
+请回复：
+- 输入卡片 ID（如 "DevOps-iScan-35835"）直接关联
+- 输入 "new" 使用推荐信息直接新建卡片
+- 输入 "new 自定义标题" 使用推荐空间和类型、但自定义标题新建
+- 输入 "new?" 查看所有可选空间和类型枚举
+```
+
+**推荐类型名称的获取方式：** 从 `result.available_spaces` 中找到当前空间（匹配 `space_prefix`），取其 `types` 列表中 `id` 等于 `result.defaults.type_id` 的类型的 `name`。如果找不到，取该空间 `types` 列表第一个的 `name`。
+
+## 步骤 4：处理用户操作
+
+### 新版本 IDE
+
+UI 组件返回 JSON，可能的 action 值：
+
+| action | 含义 | 处理方式 |
+|--------|------|----------|
+| `select` | 选择已有卡片 | 保存 `card` 中的卡片信息，继续步骤 5 |
+| `recognize` | 链接或卡片 ID 识别 | 调用 `recognize_card_cli.py` 获取卡片详情，继续步骤 5 |
+| `create` | 新建卡片 | 调用 `create_card_cli.py` 创建卡片，继续步骤 5 |
+| `skip` | 跳过 | 输出"已跳过卡片绑定和代码提交。"，**结束 skill** |
+| `do_not_show_again` | 不再提示 | 输出"已关闭推荐卡片提示。"，**结束 skill** |
+
+**recognize 处理：**
+```
+__silent: cd <用户项目目录> && python3 <skill_directory>/scripts/recognize_card_cli.py --link "<用户返回的link>"
+```
+
+**create 处理：**
+```
+__silent: cd <用户项目目录> && python3 <skill_directory>/scripts/create_card_cli.py --title "<card.title>" --space-prefix "<card.spacePrefix>" --type-name "<card.typeName>" --username "${COMATE_USERNAME}"
+```
+
+### 旧版本 IDE
+
+根据用户在对话中的文本回复：
+
+**如果用户输入序号（如 "1"、"2"）：**
+- 解析用户选择的卡片，保存 `selected_card` 信息，继续步骤 5
+
+**如果用户输入卡片 ID（如 "DevOps-iScan-35835"）：**
+- 调用 `recognize_card_cli.py` 获取卡片详情：
+  ```
+  cd <用户项目目录> && python3 <skill_directory>/scripts/recognize_card_cli.py --link "<卡片ID>"
+  ```
+- 保存 `selected_card` 信息，继续步骤 5
+
+**如果用户输入 "new"（使用推荐信息直接新建）：**
+- 使用 `result` 中的推荐信息调用 `create_card_cli.py` 创建卡片
+- 标题 = `result.defaults.title`，空间 = `result.space_prefix`
+- 类型 = 从 `result.available_spaces` 中匹配当前空间，取 `types` 中 `id` 等于 `result.defaults.type_id` 的类型名称
+
+**如果用户输入 "new 自定义标题"：**
+- 与 "new" 逻辑相同，但标题使用用户输入的自定义标题（去掉 "new " 前缀后的部分）
+
+**如果用户输入 "new?"（查看空间和类型枚举）：**
+
+从 `result.available_spaces` 输出完整枚举：
+
+```
+📋 可选空间和类型：
+
+空间 1: ${space1.name} (${space1.prefix})
+  可选类型：
+  - ${type1.name} (ID: ${type1.id})
+  - ${type2.name} (ID: ${type2.id})
+
+---
+请回复以下格式新建卡片：
+  new [标题] | [空间前缀] | [类型名称]
+  例如：new 修复登录问题 | dkx | Bug
+
+也可以只指定部分：
+  new 修复登录问题 | dkx       → 使用指定空间 + 该空间默认类型
+  new 修复登录问题 | | Story   → 使用推荐空间 + 指定类型
+```
+
+**如果用户输入 "new 标题 | 空间 | 类型"（完整指定）：**
+- 按 `|` 分割解析，第一段为标题，第二段（可选）为空间前缀，第三段（可选）为类型名称
+- 为空的部分使用推荐值，调用 `create_card_cli.py` 创建卡片
+
+## 步骤 4.5：存储关联的 iCafe 卡片 ID（必须执行）
+
+在步骤 4 处理完用户操作、拿到 `selected_card` 后，**必须**立即调用 `run_command` 将卡片 ID 保存到会话中：
+
+```
+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"}')
+```
+
+## 步骤 5：判断是否展示提交确认
+
+Agent 内部分析以下信号判断是否展示提交确认，**不输出任何内容**：
+
+**展示的信号（满足任意一条）：**
+- 当前对话中用户明确表示"完成了"、"可以提交"等意图
+- git diff 的代码变更是完整的、可独立运行的
+- 对话上下文表明任务已结束
+
+**不展示（仅输出 message）：**
+- 用户表示还有后续修改
+- 代码变更不完整
+- 对话上下文表明任务仍在进行
+
+## 步骤 6：展示提交确认
+
+### 新版本 IDE（交互式 UI）
+
+调用 `run_command` 展示提交确认 UI：
+
+```
+run_command(command="__interactive:git-commit <payload JSON>")
+```
+
+Agent 对**每个 workspace** 分别执行 `git branch -vv` + `git branch -r`（使用 `__silent:` 前缀，每个 workspace 单独一次 `run_command`），解析各自的分支信息。然后构造 payload：
+
+**⚠️ 重要：`workspaces` 数组必须包含环境上下文 `Workspace Path` 中列出的所有 workspace，不可遗漏。** 即使某个 workspace 没有变更（`hasChanges: false`），也必须包含在数组中。
+
+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": "main",
+            "remoteBranches": [{"name": "main", "isCurrent": true}],
+            "hasChanges": false,
+            "diffSummary": null
+        }
+    ]
+}
+```
+
+**构造规则：**
+- `commitMessage`：基于 diff 和绑定卡片生成的 commit message（格式 `"<spacePrefix>-<sequence> <brief_description>"`）
+- `boundCard`：步骤 4 中选定的卡片信息
+- `workspaces`：对每个 workspace 目录，使用步骤 1.5 中构建的 `workspace_diffs` 数据：
+  - `workspace`：绝对路径
+  - `repoName`：路径的最后一段
+  - `currentBranch`：从 `git branch -vv` 解析当前分支名
+  - `remoteBranches`：从 `git branch -r` 解析远程分支列表，标记当前远程追踪分支为 `isCurrent: true`
+  - `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"}`
+
+### 旧版本 IDE（文本确认）
+
+输出：
+
+```
+✅ 已关联卡片: ${spacePrefix}-${sequence}
+   标题: ${title}
+   类型: ${type} | 状态: ${status}
+
+---
+📝 建议的 commit message：
+
+${spacePrefix}-${sequence} ${brief_description}
+
+---
+请确认：
+- 回复 "ok" 或 "确认" 使用此 message 提交
+- 回复 "edit: <新message>" 修改后提交（如 "edit: dkx-200 修复登录bug"）
+- 回复 "no" 或 "取消" 放弃提交
+```
+
+## 步骤 7：执行提交 + 输出结果
+
+### 新版本 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 <branch>` 推送到远程
+- 多仓库时逐个执行，每个仓库独立处理
+
+**如果是 action === "cancel"：**
+- 输出"已取消提交"
+
+### 旧版本 IDE
+
+**如果用户确认提交（回复 "ok"、"确认"、"yes"）：**
+- 执行 `git add . && git commit -m "${commit_message}"`
+
+**如果用户修改后提交（回复 "edit: <新message>"）：**
+- 使用用户提供的新 message 执行提交
+
+**如果用户取消（回复 "no"、"取消"）：**
+- 输出取消信息
+
+### 最终输出格式
+
+**提交成功：**
+```
+✅ 已完成提交
+
+提交信息：
+- Commit: <commit_hash>
+- Message: <commit_message>
+- 绑定卡片: <space_prefix>-<sequence>
+- 分支: <branch_name>
+```
+
+**取消提交：**
+```
+⏸️ 提交已取消
+
+建议 commit message 已准备好：
+<commit_message>
+
+绑定卡片：<space_prefix>-<sequence> (<card_title>)
+
+你可以稍后使用 `git commit -m "<message>"` 手动提交
+```
+
+**判断不展示 UI（直接输出 message）：**
+```
+📝 Commit message 已准备好
+
+建议 commit message：
+<commit_message>
+
+绑定卡片：<space_prefix>-<sequence> (<card_title>)
+
+代码变更未完成，请确认后再提交
+```
+
+旧版本 IDE 提交成功后额外提示：`如需推送到远程，请执行：git push`
+
+---
+
+## 返回值说明
+
+### `find_matching_card()` 返回字典
+
+| 字段 | 说明 |
+|------|------|
+| 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}, ...] |
+| defaults | 默认表单值：{title, type_id, space_id}（title 由 Agent 在步骤 1.5 中生成） |
+
+### `diff_summary`（Agent 在步骤 1.5 中构建）
+
+| 字段 | 说明 |
+|------|------|
+| changed_files | 所有 workspace 的变更文件路径字符串列表（用于步骤 2 语义匹配） |
+| stat_summary | 合并后的 git diff --stat 统计行 |
+| diff_content | 合并后的 diff 全文（超过 500 行截断） |
+| truncated | 是否被截断 |
+
+### `workspace_diffs`（Agent 在步骤 1.5 中构建，用于步骤 6 构造 payload）
+
+| 字段 | 说明 |
+|------|------|
+| \<workspace_path\>.changed_files | 该 workspace 的 `[{file, insertions, deletions}]` 列表 |
+| \<workspace_path\>.stat_summary | 该 workspace 的统计摘要（如 "2 files, +100, -78"） |
+| \<workspace_path\>.has_changes | 该 workspace 是否有变更 |
+
+## 卡片链接
+
+```
+https://console.cloud.baidu-int.com/devops/icafe/issue/{space_prefix}-{card_sequence}/show
+```
+
+## 配置
+
+### 认证
+
+token 按优先级读取：
+1. 环境变量 `COMATE_AUTH_TOKEN`
+2. 文件 `~/.comate/login`
+
+### 资源
+
+- **scripts/icafe/** — 核心实现包
+  - `client.py` — ICafeQueryClient、常量、配置、API 客户端
+  - `matching.py` — `find_matching_card()` 主入口、匹配逻辑
+  - `farseer.py` — `get_binding_card_types()` 获取可绑定卡片类型
+- **scripts/git_utils.py** — diff 摘要、用户获取、git log 提取
+- **scripts/create_card_cli.py** — 创建卡片命令行工具
+- **scripts/recognize_card_cli.py** — 识别卡片命令行工具
+- **scripts/compat.py** — 版本兼容性检测模块
+- **scripts/logger.py** — 统一日志模块
+- **references/query_reference.md** — IQL 语法参考
+- **references/issue_type_mapping.json** — 卡片类型 ID 映射

package/comate-engine/assets/skills/smart-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"
+}