@comate/zulu 1.2.1-beta.2 → 1.3.1

package/comate-engine/assets/skills/icode-comate/references/feature/add-reviewer.md

@@ -0,0 +1,92 @@
+# add-reviewer - 添加评审人
+
+按优先级从多个来源自动选择合适的评审人，也支持手动指定。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+获取当前 CR 信息（change-number）
+  │
+  ▼
+用户是否指定了评审人?
+  │
+  ├─ 是 → 直接添加用户指定的评审人 → 结束
+  │
+  └─ 否 → 继续自动选择流程
+           │
+           ▼
+         【按优先级收集候选评审人】
+           │
+           ├─ 1. 当前 CR 已有评审人（续传 CR 场景）
+           │      └─ get_review_info → globalReviewers
+           │
+           ├─ 2. 仓库成员（repo members）
+           │      └─ get_repo_members
+           │
+           └─ 3. 历史 CR 评审人（补充，当前两个来源不足 5 人时）
+                  └─ get_repo_reviews(MERGED) → 遍历获取 reviewers
+           │
+           ▼
+         汇总所有候选评审人，排除自己，去重
+           │
+           ▼
+         是否有符合条件的评审人?
+           │
+           ├─ 是 → 展示候选列表供选择（或随机选取1个）
+           │         │
+           │         ▼
+           │       添加评审人到当前 CR → 结束
+           │
+           └─ 否 → 提示用户手动指定评审人 → 结束
+```
+
+## 评审人来源优先级
+
+| 优先级 | 来源 | 说明 | API |
+|--------|------|------|-----|
+| 1 | 当前 CR 评审人 | 续传 CR 时，优先使用已有评审人 | `get_review_info` |
+| 2 | 仓库成员 | 有仓库权限的成员 | `get_repo_members` |
+| 3 | 历史 CR 评审人 | 当前用户已合入 CR 的评审人 | `get_repo_reviews` + `get_review_info` |
+
+## 快速使用
+
+```bash
+# 自动选择评审人
+./add-reviewer.sh
+
+# 指定 CR 编号，自动选择评审人
+./add-reviewer.sh 120247220
+
+# 手动指定评审人（跳过自动选择）
+./add-reviewer.sh 120247220 zhangsan
+
+# 多个评审人用逗号分隔
+./add-reviewer.sh 120247220 "zhangsan,lisi"
+```
+
+## 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| CR 编号（第1个位置参数） | 可选，不指定则自动检测当前 commit 对应的 CR |
+| 评审人（第2个位置参数） | 可选，指定后跳过自动选择，直接添加指定的评审人 |
+
+## 注意事项
+
+1. **用户指定优先**：如果用户指定了评审人，直接使用指定的，跳过自动选择
+2. **优先级顺序**：当前 CR 评审人 > 仓库成员 > 历史 CR 评审人
+3. **去重处理**：同一用户只添加一次，避免重复
+4. **排除自己**：自动选择时会排除提交者本人
+5. **补充机制**：仅当候选人不足 5 人时才查询历史 CR
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `icode-cli api get_review_info` | 获取 CR 详情（含评审人） |
+| `icode-cli api get_repo_members` | 获取仓库成员列表 |
+| `icode-cli api get_repo_reviews` | 获取仓库 CR 列表 |
+| `icode-cli api add_reviewers` | 添加评审人 |

package/comate-engine/assets/skills/icode-comate/references/feature/fix-machine-check.md

@@ -0,0 +1,144 @@
+# fix-machine-check - 修复机器检查
+
+自动检测 CR 的机器检查结果，分析失败原因，并协助修复代码。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+获取 CR 编号（参数 / 自动检测）
+  │
+  ├─ 无法获取 → 告知原因，退出
+  │
+  ▼
+获取机器检查结果 (get_machine_check)
+  │
+  ▼
+检查是否有问题（遍历 operations，检查 status/score）
+  │
+  ├─ 无问题 → 输出"机器检查通过"，退出
+  │
+  ▼
+【修复循环】(最多 N 次，默认 5 次)
+  │
+  ├─ 1. 输出问题详情（检查项、失败原因、行内评论）
+  │
+  ├─ 2. Agent 分析问题并修复代码
+  │
+  ├─ 3. 调用 submit-cr 提交
+  │
+  ├─ 4. 等待 5 秒
+  │
+  ├─ 5. 重新获取机器检查结果
+  │
+  ├─ 6. 检查是否通过
+  │   │
+  │   ├─ 通过 → 输出"修复成功"，退出
+  │   │
+  │   └─ 未通过 → 继续循环
+  │
+  └─ 达到最大次数 → 输出"修复失败"，退出
+```
+
+## 快速使用
+
+```bash
+# 自动检测当前 CR
+./fix-machine-check.sh
+
+# 指定 CR 编号
+./fix-machine-check.sh 120247220
+
+# 指定最大重试次数
+./fix-machine-check.sh 120247220 10
+```
+
+## 参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| CR 编号（第1个位置参数） | 自动检测 | CR 的 change number |
+| 最大重试次数（第2个位置参数） | 5 | 修复循环的最大次数 |
+
+## 机器检查项说明
+
+| 检查项 | changeType | 说明 |
+|--------|------------|------|
+| 编码规范 | `CODE_STYLE` | 代码格式、命名规范等 |
+| 缺陷检查 | `STATIC_CHECK` | 静态代码分析，潜在 bug |
+| 语言合规 | `LANGUAGE_CHECK` | 语言规范检查 |
+| 开源合规 | - | 开源许可证检查 |
+
+## 检查结果字段
+
+```json
+{
+  "operations": [
+    {
+      "name": "编码规范, 来自于 CodeStyle",
+      "changeType": "CODE_STYLE",
+      "status": "SUCCESS",
+      "score": 1,
+      "comment": "检查结果说明",
+      "lineComments": {
+        "src/main.go": [
+          {
+            "line": 42,
+            "message": "变量名不符合规范"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Agent 修复指南
+
+当机器检查失败时，Agent 需要：
+
+### 1. 分析问题
+
+从检查结果中提取：
+- **检查项名称** (`name`)：了解是哪类检查
+- **失败原因** (`comment`)：理解具体问题
+- **行内评论** (`lineComments`)：定位具体代码位置
+
+### 2. 读取相关文件
+
+根据 `lineComments` 中的文件路径，读取相关代码。
+
+### 3. 修复代码
+
+根据问题类型修复：
+
+| 问题类型 | 修复方法 |
+|----------|----------|
+| 变量命名 | 按规范重命名（camelCase/snake_case） |
+| 缩进问题 | 统一使用 tab 或 space |
+| 未使用变量 | 删除或添加使用 |
+| 缺少注释 | 添加必要注释 |
+| 潜在空指针 | 添加空值检查 |
+
+### 4. 提交修复
+
+修复完成后，调用 submit-cr 提交：
+
+```bash
+./submit-cr.sh
+```
+
+## 注意事项
+
+1. **轮询间隔**：每次检查间隔 5 秒，等待机器检查完成
+2. **最大重试**：默认 5 次，可通过参数调整
+3. **Agent 介入**：修复代码需要 Agent 分析和执行
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `icode-cli api get_machine_check` | 获取机器检查结果 |
+| `icode-cli api get_repo_reviews` | 获取 CR 列表 |

package/comate-engine/assets/skills/icode-comate/references/feature/merge-cr.md

@@ -0,0 +1,100 @@
+# merge-cr - 合入 CR
+
+尝试打分 +2 并合入 CR，通过打分结果判断是否有合入权限。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+获取 CR 编号（参数 / 自动检测）
+  │
+  ├─ 无法获取 → 告知原因，退出 (1)
+  │
+  ▼
+尝试打分 +2 (set_review_score)
+  │
+  ├─ 打分成功 ─────────────────────────────────────
+  │   │
+  │   ├─ 尝试合入 (submit_review)
+  │   │   │
+  │   │   ├─ 成功 → 输出"合入成功"，退出 (0)
+  │   │   │
+  │   │   └─ 失败 → 输出失败原因，退出 (1)
+  │   │
+  └─ 打分失败 ─────────────────────────────────────
+      │
+      └─ 输出"无合入权限"，退出 (1)
+```
+
+## 快速使用
+
+```bash
+# 自动检测当前 CR
+./merge-cr.sh
+
+# 指定 CR 编号
+./merge-cr.sh 120247220
+```
+
+## 参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| CR 编号（`$1`） | 自动检测 | CR 的 change number |
+
+## 退出码说明
+
+| 退出码 | 含义 | 说明 |
+|--------|------|------|
+| 0 | 成功 | CR 已合入 |
+| 1 | 失败 | 无 CR / 无权限 / 打分失败 / 合入失败 |
+
+## 权限检测说明
+
+脚本通过尝试 **打分 +2** 来检测权限：
+
+- **打分成功**：说明用户有该仓库的评审权限，继续尝试合入
+- **打分失败**：说明用户没有评审权限，输出错误信息
+
+## 合入失败常见原因
+
+| 原因 | 说明 | 解决方法 |
+|------|------|----------|
+| 无评审权限 | 用户不是仓库成员或权限不足 | 联系仓库管理员添加权限 |
+| 机器检查未通过 | 存在代码规范或缺陷问题 | 执行 fix-machine-check 修复 |
+| 未解决的评审意见 | 有评审人提出的问题未处理 | 回复或解决评审意见 |
+| 代码冲突 | 目标分支有新提交导致冲突 | Rebase 并解决冲突后重新提交 |
+| 缺少必要审批 | 需要特定角色审批 | 联系有权限的评审人 |
+
+## 完整工作流示例
+
+```bash
+# 场景 1：有权限，合入成功
+./merge-cr.sh
+# 输出: ✓ CR #120247220 合入成功！
+
+# 场景 2：无权限
+./merge-cr.sh
+# 输出: ✗ 打分失败，无合入权限
+
+# 场景 3：有权限但合入失败
+./merge-cr.sh
+# 输出: ✗ CR 合入失败
+#       失败原因: 机器检查未通过
+```
+
+## 注意事项
+
+1. **权限检测**：通过打分 +2 来检测权限
+2. **打分覆盖**：如果之前有其他评分，新评分会覆盖
+3. **合入不可逆**：合入后 CR 状态变为 MERGED，无法撤销
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `icode-cli api set_review_score` | 设置评审分数 |
+| `icode-cli api submit_review` | 提交/合入评审 |
+| `icode-cli api get_review_info` | 获取 CR 详情 |

package/comate-engine/assets/skills/icode-comate/references/feature/ssh-setup.md

@@ -0,0 +1,106 @@
+# ssh-setup - SSH 密钥配置
+
+自动检测并配置 SSH 密钥，用于 iCode Git 操作认证。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+检测本地 SSH 密钥：
+  - 检查 ~/.ssh/id_ed25519 是否存在
+  - 检查 ~/.ssh/id_rsa 是否存在
+  │
+  ├─ 密钥已存在 → 提示"检测到已有 SSH 密钥"
+  │
+  └─ 密钥不存在 → 生成新的 ed25519 密钥
+       │
+       ▼
+     ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
+  │
+  ▼
+复制公钥到剪贴板：
+  ├─ macOS → pbcopy < ~/.ssh/id_ed25519.pub
+  ├─ Linux (xclip) → xclip -selection clipboard < ~/.ssh/id_ed25519.pub
+  └─ 无剪贴板工具 → 打印公钥内容
+  │
+  ▼
+输出引导信息：
+  - 提示公钥已复制（或需手动复制）
+  - 显示 iCode 密钥管理 URL
+  - 提示用户粘贴公钥完成绑定
+  │
+  ▼
+结束
+```
+
+## 快速使用
+
+```bash
+# 执行 SSH 密钥配置
+./ssh-setup.sh
+```
+
+## 参数说明
+
+此脚本无需参数，自动检测和配置。
+
+## 密钥检测逻辑
+
+### 检测优先级
+
+1. **ed25519 密钥**（优先）: `~/.ssh/id_ed25519`
+2. **RSA 密钥**（备选）: `~/.ssh/id_rsa`
+
+### 检测结果处理
+
+| 情况 | 处理方式 |
+|------|----------|
+| ed25519 密钥存在 | 使用已有密钥，不生成新密钥 |
+| 仅 RSA 密钥存在 | 使用已有 RSA 密钥 |
+| 无密钥 | 生成新的 ed25519 密钥 |
+
+## 剪贴板复制
+
+### 平台支持
+
+| 平台 | 工具 | 命令 |
+|------|------|------|
+| macOS | pbcopy | `pbcopy < ~/.ssh/id_ed25519.pub` |
+| Linux | xclip | `xclip -selection clipboard < ~/.ssh/id_ed25519.pub` |
+| Linux | xsel | `xsel --clipboard < ~/.ssh/id_ed25519.pub` |
+
+### 回退机制
+
+如果剪贴板工具不可用，脚本会：
+1. 打印公钥完整内容
+2. 提示用户手动复制
+
+## iCode 密钥绑定
+
+完成密钥配置后，需要将公钥添加到 iCode 账户：
+
+**管理页面**: https://console.cloud.baidu-int.com/devops/icode/account/keys
+
+### 绑定步骤
+
+1. 打开上述 URL
+2. 点击"添加 SSH 密钥"
+3. 粘贴公钥内容（已复制到剪贴板）
+4. 填写密钥标题（如：MacBook Pro）
+5. 点击确认保存
+
+## 注意事项
+
+1. **不覆盖已有密钥**：如果本地已有 SSH 密钥，脚本不会覆盖
+2. **密钥安全**：私钥 (`id_ed25519`) 请勿分享，仅公钥 (`id_ed25519.pub`) 需要上传
+3. **多设备使用**：每台设备需要单独配置密钥
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `ssh-keygen -t ed25519` | 生成 ed25519 密钥 |
+| `cat ~/.ssh/id_ed25519.pub` | 查看公钥内容 |
+| `ssh -T git@icode.baidu.com` | 测试 SSH 连接 |

package/comate-engine/assets/skills/icode-comate/references/feature/submit-acr.md

@@ -0,0 +1,135 @@
+# submit-acr - AI 代码评审
+
+自动触发 AI 代码评审并分析结果，发现需要修复的问题时退出等待 Agent 修复。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+获取 CR 编号（参数 / 自动检测）
+  │
+  ├─ 无法获取 → 告知原因，退出 (1)
+  │
+  ▼
+【主循环】(最多 MAX_LOOPS 次，默认 10)
+  │
+  ├─── AI 代码评审 ────────────────────────
+  │    │
+  │    ├─ 触发 AI 评审 (start_ai_review)
+  │    │
+  │    ├─ 轮询结果 (get_ai_review, 10s/次)
+  │    │   │
+  │    │   ├─ 超时 (默认 20min) → 退出 (1)
+  │    │   ├─ 状态 FAIL/TIMEOUT → 退出 (1)
+  │    │   └─ 状态 SUSS → 继续处理结果
+  │    │
+  │    ├─ 过滤 severityScore >= N (默认 5) 的问题
+  │    │   │
+  │    │   ├─ 无问题 → 流程成功，退出 (0)
+  │    │   │
+  │    │   └─ 有问题 → 输出问题详情，退出 (2)
+  │    │               等待 Agent 修复后重新运行
+  │    │
+  └─── 达到最大循环次数 → 退出 (1)
+```
+
+## 快速使用
+
+```bash
+# 自动检测当前 CR，使用默认参数
+./submit-acr.sh
+
+# 指定 CR 编号
+./submit-acr.sh 120247220
+
+# 指定最大循环次数
+./submit-acr.sh 120247220 10
+
+# 完整参数
+./submit-acr.sh 120247220 10 1200 5
+# 参数顺序: CR编号 最大循环次数 AI超时秒数 严重度阈值
+```
+
+## 参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| CR 编号（`$1`） | 自动检测 | CR 的 change number |
+| 最大循环次数（`$2`） | 10 | 主循环最大次数 |
+| AI 评审超时（`$3`） | 1200 (20min) | AI 评审轮询超时秒数 |
+| 严重度阈值（`$4`） | 5 | 需要修复的 severityScore 阈值 |
+
+## 退出码说明
+
+| 退出码 | 含义 | Agent 动作 |
+|--------|------|-----------|
+| 0 | 成功：AI 评审通过 | 无需操作 |
+| 1 | 失败：无 CR / 超时 / 达到最大次数 | 报告错误 |
+| 2 | 需要 Agent 修复 | 分析问题，修复代码，提交后重新运行 |
+
+## AI 评审问题严重度说明
+
+| severityScore | 严重程度 | 说明 | 默认处理 |
+|---------------|----------|------|----------|
+| 1-3 | 低 | 代码风格、命名建议 | 忽略 |
+| 4 | 中低 | 轻微优化建议 | 忽略 |
+| 5-6 | 中 | 代码优化、性能改进 | **需要修复** |
+| 7-10 | 高 | 潜在 bug、安全问题 | **需要修复** |
+
+## Agent 修复指南
+
+### 收到退出码 2 时
+
+脚本会输出需要修复的问题详情，Agent 需要：
+
+1. **分析问题** - 查看文件、行号、严重度、问题描述
+2. **读取相关文件** - 根据输出的文件路径读取代码
+3. **修复代码** - 使用 Edit 工具修复代码
+4. **提交修复** - 使用 submit-cr 提交
+5. **重新运行检查** - 继续 AI CR 流程
+
+### 常见问题类型修复
+
+| 问题类型 | 修复方法 |
+|----------|----------|
+| 缺少错误处理 | 添加 error check |
+| 潜在空指针 | 添加空值检查 |
+| 性能问题 | 优化算法/数据结构 |
+| 安全问题 | 修复安全漏洞 |
+
+## 完整工作流示例
+
+```bash
+# 1. 提交 CR
+./submit-cr.sh
+
+# 2. 运行 AI CR 完整流程
+./submit-acr.sh
+
+# 3. 如果有问题需要修复，脚本会退出并输出问题
+#    Agent 分析问题并修复代码
+
+# 4. 修复后重新提交
+./submit-cr.sh
+
+# 5. 继续运行 AI CR 流程
+./submit-acr.sh 120247220
+
+# 重复 3-5 直到通过
+```
+
+## 注意事项
+
+1. **轮询间隔**：AI 评审每 10 秒轮询一次
+2. **超时设置**：默认 20 分钟，可根据代码量调整
+3. **严重度阈值**：默认 5，可降低以检查更多问题
+4. **Agent 介入**：修复代码需要 Agent 分析和执行
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `icode-cli api start_ai_review` | 触发 AI 评审 |
+| `icode-cli api get_ai_review` | 获取 AI 评审结果 |

package/comate-engine/assets/skills/icode-comate/references/feature/submit-cr.md

@@ -0,0 +1,123 @@
+# submit-cr - 提交 CR
+
+自动判断当前提交是新建 CR 还是追加到已有 CR，并执行相应的提交流程。
+
+## 执行流程
+
+```
+开始
+  │
+  ▼
+查询本地信息：
+  - commit hash (git rev-parse HEAD)
+  - commit message (git log -1 --format="%s")
+  - iCafe 卡片号 (从 message 解析，如 ComateStack-5353)
+  │
+  ▼
+获取仓库名称和当前用户
+  │
+  ▼
+查询远程 NEW 状态的 CR 列表 (api get_repo_reviews)
+  │
+  ▼
+过滤当前用户的 CR，执行匹配判断：
+  │
+  ├─【匹配方式一】current_revision == 本地 commit hash
+  │    │
+  │    ▼
+  │  找到匹配 → 【同一个 CR - Amend 模式】
+  │
+  ├─【匹配方式二】远程 CR 的 subject 以相同 iCafe 卡片号开头
+  │    │
+  │    ▼
+  │  找到匹配 → 【同一个 CR - Amend 模式】
+  │
+  └─ 两种方式均未匹配 → 【新 CR 模式】
+
+【同一个 CR - Amend 模式】
+  1. git add -A (添加所有修改)
+  2. git commit --amend --no-edit
+  3. icode-cli git push_cr
+
+【新 CR 模式】
+  1. 使用 icafe-assistant skill 获取 iCafe 卡片 ID
+  2. git add -A (添加所有修改)
+  3. git commit -m "<iCafe卡片号> <commit message>"
+  4. icode-cli git push_cr
+```
+
+## 快速使用
+
+```bash
+# 默认 master 分支
+./submit-cr.sh
+
+# 指定 develop 分支
+./submit-cr.sh develop
+```
+
+## 参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| 目标分支（`$1`） | master | CR 的目标分支 |
+
+## 判断逻辑详解
+
+### 如何判断是否为同一个 CR
+
+有两种匹配方式，满足任一条件即视为同一个 CR：
+
+**方式一：Commit Hash 匹配**
+
+1. 获取本地当前 commit: `git rev-parse HEAD`
+2. 调用 `icode-cli api get_repo_reviews --repo <repo> --status NEW`
+3. 在返回的 CR 列表中查找：
+   - `owner.username` == 当前用户
+   - `current_revision` == 本地 commit hash
+4. 如果找到匹配项，说明当前 commit 已经有对应的远程 CR
+
+**方式二：iCafe 卡片号匹配**
+
+1. 解析本地 commit message 中的 iCafe 卡片号（如 `ComateStack-5353`）
+2. 调用 `icode-cli api get_repo_reviews --repo <repo> --status NEW`
+3. 在返回的 CR 列表中查找：
+   - `owner.username` == 当前用户
+   - `subject` 中包含相同的 iCafe 卡片号
+4. 如果找到匹配项，说明本地修改属于已有的 CR
+
+### iCafe 卡片号解析规则
+
+iCafe 卡片号格式为 `<项目前缀>-<数字>`，位于 commit message 开头：
+
+```
+ComateStack-5353 support agentic
+│              │
+└──────────────┴── iCafe 卡片号
+
+ISSUE-123 fix login bug
+│       │
+└───────┴── iCafe 卡片号
+```
+
+## 注意事项
+
+1. **Amend 模式会修改 commit history**：确保该 commit 尚未被其他人基于开发
+2. **Change-Id 保持不变**：amend 后 Change-Id 不变，Gerrit 会识别为同一个 CR 的新版本
+3. **分支选择**：Amend 模式使用原 CR 的目标分支；新 CR 默认使用 master
+4. **iCafe 绑定**：新 CR 需要绑定 iCafe 卡片，通过 `icafe-cli-assistant` skill 获取卡片 ID
+
+## 相关 Skill
+
+| Skill | 说明 |
+|-------|------|
+| `icafe-cli-assistant` | 获取 iCafe 卡片 ID，用于绑定 CR |
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `icode-cli git push_cr` | 推送代码评审 |
+| `icode-cli api get_repo_reviews` | 获取仓库 CR 列表 |
+| `icode-cli api get_review_info` | 获取 CR 详情 |
+| `icode-cli login` | 检查登录状态 |