@comate/zulu 1.2.1-beta.2 → 1.3.1

package/comate-engine/assets/skills/icode-comate/references/git/clone.md

@@ -0,0 +1,67 @@
+# clone - 克隆代码库
+
+从 iCode 平台克隆代码库。
+
+## 命令格式
+
+```bash
+icode-cli git clone --repo <代码库名称> [--path <本地路径>] [--verbose]
+```
+
+如果 `icode-cli` 不在全局 PATH 中，可以使用：
+
+```bash
+~/.icode/bin/icode-cli git clone --repo <代码库名称>
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库名称，三层目录形式 |
+| `--path` | `-p` | 否 | 代码库名称 | 本地克隆路径 |
+| `--verbose` | `-v` | 否 | false | 显示详细输出 |
+
+## 使用示例
+
+```bash
+# 克隆代码库（路径默认为代码库名称）
+icode-cli git clone --repo baidu/icode/agent-sandbox
+
+# 克隆到指定路径
+icode-cli git clone --repo baidu/icode/agent-sandbox --path ./my-agent
+
+# 显示详细输出
+icode-cli git clone --repo baidu/icode/agent-sandbox --verbose
+```
+
+## 执行流程
+
+克隆命令会自动执行以下操作：
+
+1. **SSH 配置**：执行 SSH 配置脚本（可选，失败不影响克隆）
+2. **HTTPS 克隆**：使用 HTTPS 协议下载代码
+3. **配置用户信息**：自动设置 `user.name` 和 `user.email`
+4. **安装 Hook**：安装 Gerrit 的 `commit-msg` hook
+
+## 输出示例
+
+```
+✓ Repository cloned successfully!
+  Location: agent-sandbox
+  Remote: origin (HTTPS)
+
+Next steps:
+  cd agent-sandbox
+  # Make your changes
+  git add .
+  git commit -m 'Your message'
+  icode-cli git push_cr --branch master
+```
+
+## 注意事项
+
+- 代码库名称必须是完整的三层目录形式（如 `baidu/icode/test`）
+- 如果目标路径已存在，克隆会失败
+- 需要有该代码库的访问权限
+- `commit-msg` hook 用于自动生成 Gerrit Change-Id

package/comate-engine/assets/skills/icode-comate/references/git/icode-git.md

@@ -0,0 +1,68 @@
+# iCode Git 操作
+
+提供与 iCode 平台集成的 Git 操作命令，包括代码克隆、推送和代码评审（CR）提交。
+
+## 命令概览
+
+| 命令 | 说明 | 文档 |
+|------|------|------|
+| `clone` | 克隆代码库 | [clone.md](clone.md) |
+| `push` | 直接推送到远程分支 | [push.md](push.md) |
+| `push_cr` | 推送到 Gerrit 进行代码评审 | [push_cr.md](push_cr.md) |
+
+## 快速开始
+
+### 1. 克隆代码库
+
+```bash
+icode-cli git clone --repo baidu/icode/test
+```
+
+### 2. 提交代码评审
+
+```bash
+cd test
+# 修改代码...
+git add .
+git commit -m "feat: add new feature"
+
+# 推送到 Gerrit 进行代码评审
+icode-cli git push_cr --branch master
+```
+
+### 3. 直接推送
+
+```bash
+# 推送到远程分支（不经过代码评审）
+icode-cli git push --branch develop
+```
+
+## 特性
+
+- **HTTPS 克隆**：自动使用 HTTPS 协议克隆代码
+- **Git 配置**：自动配置 user.name 和 user.email
+- **Gerrit Hook**：自动安装 commit-msg hook，确保提交包含 Change-Id
+- **智能推送**：自动识别远程仓库并配置 HTTPS remote
+
+## 工作流示例
+
+### 完整的代码评审流程
+
+```bash
+# 1. 克隆仓库
+icode-cli git clone --repo baidu/icode/my-project
+
+# 2. 进入目录并创建特性分支
+cd my-project
+git checkout -b feature/new-feature
+
+# 3. 开发并提交
+# ... 编写代码 ...
+git add .
+git commit -m "feat: implement new feature"
+
+# 4. 推送到 Gerrit 进行代码评审
+icode-cli git push_cr --branch master
+
+# 5. 评审通过后，代码会被合并到 master 分支
+```

package/comate-engine/assets/skills/icode-comate/references/git/push.md

@@ -0,0 +1,64 @@
+# push - 直接推送到远程分支
+
+将当前分支直接推送到远程仓库。
+
+## 命令格式
+
+```bash
+icode-cli git push [--repo-path <仓库路径>] [--branch <分支名>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo-path` | `-r` | 否 | 当前目录 | Git 仓库路径 |
+| `--branch` | `-b` | 否 | 当前分支 | 目标分支名称 |
+
+## 使用示例
+
+```bash
+# 推送当前分支到远程
+icode-cli git push
+
+# 推送到指定分支
+icode-cli git push --branch develop
+
+# 从指定仓库路径推送
+icode-cli git push --repo-path ./my-project --branch main
+```
+
+## 执行流程
+
+1. **检查仓库**：确认当前目录是 Git 仓库
+2. **检查凭证**：检查 Git 凭证配置
+3. **获取远程**：从 origin 获取远程 URL
+4. **配置 HTTPS**：确保 HTTPS 远程可用
+5. **推送代码**：执行 `git push`
+
+## 输出示例
+
+```
+✓ Push successful!
+
+Output:
+To https://icode.baidu.com/baidu/icode/test
+   abc123..def456  develop -> develop
+```
+
+## push vs push_cr
+
+| 命令 | 用途 | 推送目标 |
+|------|------|----------|
+| `push` | 直接推送到远程分支 | `origin/branch` |
+| `push_cr` | 提交代码评审 | `refs/for/branch` |
+
+- **push**：适用于有直接推送权限的分支（如个人分支）
+- **push_cr**：适用于需要代码评审的分支（如 master）
+
+## 注意事项
+
+- 必须在 Git 仓库内执行，或使用 `--repo-path` 指定仓库路径
+- 需要有目标分支的推送权限
+- 如果远程分支有新的提交，可能需要先拉取合并
+- 某些分支可能配置了保护规则，不允许直接推送

package/comate-engine/assets/skills/icode-comate/references/git/push_cr.md

@@ -0,0 +1,103 @@
+# push_cr - 推送代码评审
+
+将当前分支推送到 Gerrit 进行代码评审（Code Review）。
+
+## 命令格式
+
+```bash
+icode-cli git push_cr [--repo-path <仓库路径>] [--branch <目标分支>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo-path` | `-r` | 否 | 当前目录 | Git 仓库路径 |
+| `--branch` | `-b` | 否 | master 或当前分支 | 目标分支名称 |
+
+## 使用示例
+
+```bash
+# 推送到 master 分支进行代码评审
+icode-cli git push_cr
+
+# 推送到指定分支
+icode-cli git push_cr --branch develop
+
+# 从指定仓库路径推送
+icode-cli git push_cr --repo-path ./my-project --branch feature/test
+```
+
+## 执行流程
+
+1. **检查仓库**：确认当前目录是 Git 仓库
+2. **检查凭证**：检查 Git 凭证配置
+3. **获取远程**：从 origin 获取远程 URL
+4. **配置 HTTPS**：确保 HTTPS 远程可用
+5. **推送到 Gerrit**：执行 `git push origin HEAD:refs/for/<branch>`
+6. **返回 CR URL**：解析并输出代码评审链接
+
+## 输出示例
+
+```
+https://icode.baidu.com/c/baidu/icode/test/+/123456
+```
+
+输出的 URL 即为代码评审（CR）的链接，可以直接在浏览器中打开进行评审操作。
+
+## Gerrit 代码评审说明
+
+### refs/for 机制
+
+Gerrit 使用特殊的 `refs/for/<branch>` 引用来接收代码评审：
+
+- 推送到 `refs/for/master` 会创建一个针对 master 分支的 CR
+- 代码不会直接合并到目标分支，而是进入评审流程
+- 评审通过后，代码才会被合并
+
+### Change-Id
+
+每个提交需要包含 Change-Id，用于标识同一个变更的多次修订：
+
+```
+commit abc123
+Author: zhangsan <zhangsan@baidu.com>
+Date:   Mon Jan 15 10:00:00 2024 +0800
+
+    feat: add new feature
+
+    Change-Id: I1234567890abcdef
+```
+
+使用 `icode-cli git clone` 克隆的仓库会自动安装 `commit-msg` hook，自动生成 Change-Id。
+
+## 代码评审流程
+
+```
+1. 提交代码评审
+   icode-cli git push_cr --branch master
+
+2. 获得 CR URL，分享给评审人
+   https://icode.baidu.com/c/baidu/icode/test/+/123456
+
+3. 评审人在 iCode 平台进行评审
+   - 查看代码变更
+   - 添加评论
+   - 给出评分（+2 批准，-2 拒绝）
+
+4. 根据评审意见修改代码
+   git add .
+   git commit --amend  # 修订同一个变更
+   icode-cli git push_cr --branch master
+
+5. 评审通过后合并
+   - 在 iCode 平台点击 Submit
+   - 或使用 API: icode-cli api submit_review
+```
+
+## 注意事项
+
+- 必须在 Git 仓库内执行，或使用 `--repo-path` 指定仓库路径
+- 提交必须包含 Change-Id（使用 `commit-msg` hook 自动生成）
+- 需要有代码库的提交权限
+- 同一个 Change-Id 的多次推送会更新同一个 CR（而不是创建新的）

package/comate-engine/assets/skills/icode-comate/references/install.md

@@ -0,0 +1,144 @@
+# 工具安装指南
+
+iCode Skill 依赖以下工具，请按需安装。
+
+## icode-cli
+
+iCode 命令行工具，提供 Git 操作、API 调用等功能。
+
+### 版本要求
+
+- 最低版本：>= 0.1.8
+
+### 检测方式
+
+```bash
+# 检查是否已安装
+which icode-cli
+
+# 或检查用户目录
+ls ~/.icode/bin/icode-cli
+
+# 查看版本
+icode-cli --version
+```
+
+### 安装方式
+
+#### Linux / macOS
+
+```bash
+# 安装开发版（推荐，包含最新功能）
+curl -sSL http://icode-cli.bj.bcebos.com/install.sh | bash -s -- --no-skills
+
+# 安装稳定版（尚未发布，暂时不能使用）
+curl -fsSL http://icode-cli.bj.bcebos.com/install.sh | bash -s -- --force
+```
+
+#### Windows
+
+请使用 Git Bash 或 WSL 运行上述安装命令。
+
+### 安装位置
+
+默认安装到 `~/.icode/bin/icode-cli`，安装脚本会自动配置 PATH。
+
+如果 PATH 未生效，可手动添加：
+
+```bash
+# bash
+echo 'export PATH="$HOME/.icode/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# zsh
+echo 'export PATH="$HOME/.icode/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### 验证安装
+
+```bash
+icode-cli --version
+# 输出: icode-cli version 0.1.8
+
+icode-cli login
+# 检查登录状态
+```
+
+---
+
+## Git
+
+分布式版本控制系统。
+
+### 版本要求
+
+- 最低版本：>= 2.0
+
+### 检测方式
+
+```bash
+git --version
+# 输出: git version 2.x.x
+```
+
+### 安装方式
+
+#### macOS
+
+```bash
+# 使用 Homebrew
+brew install git
+
+# 或使用 Xcode Command Line Tools
+xcode-select --install
+```
+
+#### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install git
+```
+
+#### CentOS / RHEL
+
+```bash
+sudo yum install git
+```
+
+#### Windows
+
+1. 下载 [Git for Windows](https://git-scm.com/download/win)
+2. 运行安装程序，按默认选项安装
+3. 安装完成后可使用 Git Bash
+
+### 配置 Git
+
+```bash
+# 配置用户名和邮箱
+git config --global user.name "你的名字"
+git config --global user.email "你的邮箱@baidu.com"
+
+# 验证配置
+git config --list
+```
+
+---
+
+## 环境验证
+
+安装完成后，运行以下命令验证环境：
+
+```bash
+# 检查 icode-cli
+icode-cli --version
+
+# 检查 git
+git --version
+
+# 检查登录状态
+icode-cli login
+```
+
+所有检查通过后，即可开始使用 iCode Skill。

package/comate-engine/assets/skills/icode-comate/references/login.md

@@ -0,0 +1,111 @@
+# login - 登录认证
+
+检查当前用户的认证状态，或进行登录。
+
+## 命令格式
+
+```bash
+# 交互式登录（默认使用 UGate）
+icode-cli login
+
+# 非交互式登录
+icode-cli login --token "eyJ..."
+
+# 指定认证方式
+icode-cli login --method ugate --token "eyJ..."
+icode-cli login --method comate --token "Bearer-xxx"
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 默认值 | 说明 |
+|------|--------|--------|------|
+| `--method` | `-m` | `ugate` | 认证方式（ugate/comate） |
+| `--token` | `-t` | - | Token（非交互式模式） |
+
+## 使用示例
+
+```bash
+# 检查登录状态（已登录则直接返回，未登录则提示输入 token）
+icode-cli login
+
+# 使用 UGate token 直接登录
+icode-cli login --token "eyJhbGciOiJIUzI1NiIsInR..."
+
+# 使用 Comate token 登录
+icode-cli login --method comate --token "Bearer-abc123"
+```
+
+## 返回信息
+
+### 已登录状态
+
+```
+Already logged in as: zhangsan (ugate)
+```
+
+### 登录成功
+
+```
+Logged in as: zhangsan (ugate)
+```
+
+## 在脚本中使用
+
+```bash
+# 获取当前用户名
+USERNAME=$(icode-cli login 2>&1 | grep "logged in as" | sed 's/.*as: \([^ ]*\).*/\1/')
+
+# 检查是否登录成功
+if icode-cli login 2>&1 | grep -q "logged in as"; then
+    echo "已登录"
+else
+    echo "未登录"
+    exit 1
+fi
+```
+
+## 认证方式
+
+| 认证方式 | Token 获取 | Token 存储 | 优先级 |
+|---------|-----------|-----------|--------|
+| ugate（默认） | https://uuap.baidu.com/agent/token | `~/.config/uuap/` | order=10 |
+| comate | Comate IDE 自动保存 | `~/.comate/login` | order=20 |
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 已登录或登录成功 |
+| 1 | 登录失败 |
+
+---
+
+# logout - 登出
+
+登出并清除认证信息。
+
+## 命令格式
+
+```bash
+icode-cli logout
+```
+
+## 使用示例
+
+```bash
+icode-cli logout
+```
+
+## 返回信息
+
+```
+Logging out zhangsan (ugate)...
+Logged out successfully
+```
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 登出成功 |

package/comate-engine/assets/skills/icode-comate/scripts/add-reviewer.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+# add-reviewer.sh - 智能添加评审人脚本 (Linux/macOS)
+# 按优先级从多个来源自动选择评审人，或使用用户指定的评审人
+#
+# 评审人来源优先级:
+#   1. 当前 CR 已有评审人（续传 CR 场景）
+#   2. 仓库成员（repo members）
+#   3. 历史 CR 评审人（补充，当候选人不足 5 人时）
+#
+# 使用方法:
+#   ./add-reviewer.sh [CR编号] [评审人]
+#
+# 示例:
+#   ./add-reviewer.sh                    # 自动检测 CR，自动选择评审人
+#   ./add-reviewer.sh 120247220          # 指定 CR，自动选择评审人
+#   ./add-reviewer.sh 120247220 zhangsan # 指定 CR 和评审人
+
+set -e
+
+# 加载公共函数
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# 获取候选评审人（按优先级）
+get_reviewer_candidates() {
+    local repo_name=$1
+    local username=$2
+    local change_number=$3
+
+    local seen=""
+    local candidates=""
+
+    # 优先级 1: 当前 CR 已有评审人
+    if [ -n "$change_number" ] && [ "$change_number" != "0" ]; then
+        local cr_info
+        cr_info=$("$ICODE_CLI" api get_review_info --change-number "$change_number" -o json 2>/dev/null || echo '{"data":{"globalReviewers":[]}}')
+
+        local cr_reviewers
+        cr_reviewers=$(echo "$cr_info" | "$ICODE_CLI" jq -r ".data.globalReviewers[]? | select(.username != \"$username\") | .username" 2>/dev/null || true)
+
+        for r in $cr_reviewers; do
+            if [[ ! " $seen " =~ " $r " ]]; then
+                seen="$seen $r"
+                candidates="$candidates $r"
+            fi
+        done
+    fi
+
+    # 优先级 2: 仓库成员
+    local members
+    members=$("$ICODE_CLI" api get_repo_members --repo "$repo_name" -o json 2>/dev/null || echo '{"data":[]}')
+
+    local member_reviewers
+    # 注意：API 返回的字段是 userName（驼峰式）而不是 username
+    member_reviewers=$(echo "$members" | "$ICODE_CLI" jq -r ".data[]? | select(.userName != \"$username\") | .userName" 2>/dev/null || true)
+
+    for r in $member_reviewers; do
+        if [[ ! " $seen " =~ " $r " ]]; then
+            seen="$seen $r"
+            candidates="$candidates $r"
+        fi
+    done
+
+    # 优先级 3: 历史 CR 评审人（当候选人不足 5 人时补充）
+    local candidate_count
+    candidate_count=$(echo "$candidates" | wc -w | tr -d ' ')
+
+    if [ "$candidate_count" -lt 5 ]; then
+        local merged_crs
+        merged_crs=$("$ICODE_CLI" api get_repo_reviews --repo "$repo_name" --status MERGED -o json 2>/dev/null || echo '{"data":{"changes":[]}}')
+
+        local my_cr_numbers
+        my_cr_numbers=$(echo "$merged_crs" | "$ICODE_CLI" jq -r ".data.changes[] | select(.owner.username == \"$username\") | ._number" 2>/dev/null || true)
+
+        for cr_num in $my_cr_numbers; do
+            local cr_info
+            cr_info=$("$ICODE_CLI" api get_review_info --change-number "$cr_num" -o json 2>/dev/null || echo '{"data":{"globalReviewers":[]}}')
+
+            local cr_reviewers
+            cr_reviewers=$(echo "$cr_info" | "$ICODE_CLI" jq -r ".data.globalReviewers[]? | select(.username != \"$username\") | .username" 2>/dev/null || true)
+
+            for r in $cr_reviewers; do
+                if [[ ! " $seen " =~ " $r " ]]; then
+                    seen="$seen $r"
+                    candidates="$candidates $r"
+                fi
+            done
+        done
+    fi
+
+    # 输出去重后的候选人列表
+    echo "$candidates" | tr ' ' '\n' | grep -v '^$' | head -20
+}
+
+# ========== 主流程 ==========
+
+# 初始化环境
+init_toolkit_env
+
+CHANGE_NUMBER=${1:-""}
+SPECIFIED_REVIEWER=${2:-""}
+
+# 如果没有指定 CR 编号，自动检测
+if [ -z "$CHANGE_NUMBER" ]; then
+    log_step "检测当前 CR..."
+    CHANGE_NUMBER=$(get_current_cr "$ICODE_CLI" "$REPO_NAME" "$USERNAME")
+
+    if [ -z "$CHANGE_NUMBER" ]; then
+        log_error "未找到当前 commit 对应的 CR"
+        log_warn "请先使用 'icode-cli git push_cr' 提交 CR，或手动指定 CR 编号"
+        exit 1
+    fi
+fi
+log_info "CR 编号: $CHANGE_NUMBER"
+echo ""
+
+# 如果用户指定了评审人，直接添加
+if [ -n "$SPECIFIED_REVIEWER" ]; then
+    log_step "添加用户指定的评审人: $SPECIFIED_REVIEWER"
+    $ICODE_CLI api add_reviewers --change-number "$CHANGE_NUMBER" --reviewers "$SPECIFIED_REVIEWER"
+    echo ""
+    log_info "评审人 $SPECIFIED_REVIEWER 已添加到 CR #$CHANGE_NUMBER"
+    exit 0
+fi
+
+# 获取候选评审人（按优先级）
+log_step "获取候选评审人..."
+REVIEWERS=$(get_reviewer_candidates "$REPO_NAME" "$USERNAME" "$CHANGE_NUMBER")
+
+if [ -z "$REVIEWERS" ]; then
+    log_warn "未找到候选评审人"
+    log_warn "请手动指定评审人: $0 $CHANGE_NUMBER <reviewer_username>"
+    exit 1
+fi
+
+# 转为数组
+IFS=$'\n' read -r -d '' -a REVIEWER_ARRAY <<< "$REVIEWERS" || true
+
+COUNT=${#REVIEWER_ARRAY[@]}
+log_info "找到 $COUNT 个候选评审人: ${REVIEWER_ARRAY[*]}"
+
+# 随机选择一个
+RANDOM_INDEX=$((RANDOM % COUNT))
+SELECTED_REVIEWER=${REVIEWER_ARRAY[$RANDOM_INDEX]}
+
+log_info "随机选择评审人: $SELECTED_REVIEWER"
+echo ""
+
+# 添加评审人
+log_step "添加评审人..."
+$ICODE_CLI api add_reviewers --change-number "$CHANGE_NUMBER" --reviewers "$SELECTED_REVIEWER"
+
+echo ""
+log_info "评审人 $SELECTED_REVIEWER 已添加到 CR #$CHANGE_NUMBER"