@comate/zulu 1.2.1-beta.2 → 1.3.1

package/comate-engine/assets/skills/icode-comate/references/api/get_review_comments.md

@@ -0,0 +1,87 @@
+# get_review_comments - 获取评审评论
+
+获取代码评审的所有评论信息。
+
+## 命令格式
+
+```bash
+icode-cli api get_review_comments --change-number <评审编号> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--change-number` | `-n` | 是 | - | 评审编号（数字） |
+| `--output` | `-o` | 否 | json | 输出格式：json/yaml/table |
+
+## 使用示例
+
+```bash
+# 获取评审评论
+icode-cli api get_review_comments -n 12345
+
+# 表格格式输出
+icode-cli api get_review_comments --change-number 12345 --output table
+```
+
+## 返回数据
+
+### JSON 格式
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功",
+  "data": {
+    "src/main.go": [
+      {
+        "id": "comment_123",
+        "path": "src/main.go",
+        "author": {
+          "name": "张三"
+        },
+        "line": 42,
+        "unresolved": true,
+        "message": "这里需要添加错误处理"
+      }
+    ],
+    "src/util.go": [
+      {
+        "id": "comment_124",
+        "path": "src/util.go",
+        "author": {
+          "name": "李四"
+        },
+        "line": 15,
+        "unresolved": false,
+        "message": "建议使用常量替代魔数"
+      }
+    ]
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 评论 ID |
+| `path` | string | 文件路径 |
+| `author.name` | string | 评论作者 |
+| `line` | int | 评论所在行号 |
+| `unresolved` | bool | 是否未解决 |
+| `message` | string | 评论内容 |
+
+## 评论状态
+
+| unresolved | 含义 |
+|------------|------|
+| true | 评论未解决，需要处理 |
+| false | 评论已解决 |
+
+## 注意事项
+
+- 需要有该评审的访问权限
+- 评论按文件分组返回
+- 未解决的评论可能阻塞评审合并

package/comate-engine/assets/skills/icode-comate/references/api/get_review_info.md

@@ -0,0 +1,81 @@
+# get_review_info - 获取评审详细信息
+
+获取指定评审的详细信息。
+
+## 命令格式
+
+```bash
+icode-cli api get_review_info --change-number <评审编号> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--change-number` | `-n` | 是 | - | 评审编号（数字） |
+| `--output` | `-o` | 否 | json | 输出格式：json/yaml/table |
+
+## 使用示例
+
+```bash
+# 获取评审详情
+icode-cli api get_review_info -n 12345
+
+# 表格格式输出
+icode-cli api get_review_info --change-number 12345 --output table
+```
+
+## 返回数据
+
+### JSON 格式
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功",
+  "data": {
+    "changeId": "I1234567890abcdef",
+    "subject": "feat: add new feature",
+    "status": "NEW",
+    "branch": "master",
+    "project": "baidu/icode/test",
+    "owner": {
+      "name": "张三",
+      "email": "zhangsan@baidu.com"
+    },
+    "mergeable": true,
+    "created": "2024-01-15 10:00:00",
+    "updated": "2024-01-15 14:30:00",
+    "revisionId": "abc123"
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `changeId` | string | Change ID（Gerrit 格式） |
+| `subject` | string | 评审主题 |
+| `status` | string | 评审状态：NEW/MERGED/ABANDONED |
+| `branch` | string | 目标分支 |
+| `project` | string | 所属项目 |
+| `owner.name` | string | 提交者姓名 |
+| `owner.email` | string | 提交者邮箱 |
+| `mergeable` | bool | 是否可合并 |
+| `created` | string | 创建时间 |
+| `updated` | string | 更新时间 |
+| `revisionId` | string | 当前版本 ID |
+
+## 评审状态说明
+
+| 状态 | 含义 |
+|------|------|
+| `NEW` | 待处理的评审 |
+| `MERGED` | 已合并 |
+| `ABANDONED` | 已放弃 |
+
+## 注意事项
+
+- 需要有该评审的访问权限
+- `mergeable` 为 true 表示评审可以合并

package/comate-engine/assets/skills/icode-comate/references/api/get_submit_settings.md

@@ -0,0 +1,105 @@
+# get_submit_settings
+
+获取代码库的提交规则配置（提交规则、代码质量检查、流水线检查、评审设置、合入策略等）。
+
+## 命令格式
+
+```bash
+icode-cli api get_submit_settings --repo <repo-name> [--check-permission] [-o json|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名，格式如 `baidu/project/repo` |
+| `--check-permission` | - | 否 | false | 查询前检查读权限 |
+| `--output` | `-o` | 否 | json | 输出格式：json、yaml |
+
+## 使用示例
+
+```bash
+# 获取代码库的提交规则配置
+icode-cli api get_submit_settings --repo baidu/icode/test
+
+# 先检查权限再查询
+icode-cli api get_submit_settings --repo baidu/icode/test --check-permission
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "",
+  "data": {
+    "needSubmitCheck": true,
+    "forbidMergedCommit": false,
+    "singleCommitPerReview": false,
+    "checkCodeStyle": true,
+    "needStaticCheck": true,
+    "needSecurityCheck": true,
+    "needUtCheck": false,
+    "utCovRate": 0.6,
+    "ignoreAgileScore": false,
+    "reviewSetting": "REVIEW_REQUIRED",
+    "autoSubmit": false,
+    "submitStrategy": "MERGE_IF_NECESSARY"
+  }
+}
+```
+
+## 返回字段说明
+
+### 提交规则
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `needSubmitCheck` | bool | 是否需要提交检查 |
+| `forbidMergedCommit` | bool | 是否禁止合并提交 |
+| `singleCommitPerReview` | bool | 每次评审是否只能有一个提交 |
+| `needIcafeCard` | bool | 是否需要关联 iCafe 卡片 |
+
+### 代码质量检查
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `checkCodeStyle` | bool | 是否检查代码风格 |
+| `needStaticCheck` | bool | 是否需要静态检查 |
+| `needSecurityCheck` | bool | 是否需要安全检查 |
+| `needUtCheck` | bool | 是否需要单测检查 |
+| `utCovRate` | float | 单测覆盖率要求 |
+
+### 评审设置
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `reviewSetting` | string | 评审设置 |
+| `mustBeFixedBlock` | bool | 是否必须修复所有问题 |
+
+### 合入设置
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `autoSubmit` | bool | 是否自动合入 |
+| `submitStrategy` | string | 合入策略 |
+
+## 使用场景
+
+1. **了解提交要求**：提交代码前了解仓库的各项检查要求
+2. **配置检查**：检查仓库的检查项配置是否符合预期
+3. **自动化流程**：根据配置决定是否执行某些检查
+
+## 错误处理
+
+| 错误信息 | 说明 | 解决方案 |
+|----------|------|----------|
+| `Repository may not exist` | 代码库不存在 | iCode API 对不存在的代码库返回 500 错误，请检查代码库名称 |
+| `No read permission` | 无权限 | 确认是否有该代码库的读取权限 |
+
+## 相关命令
+
+- `icode-cli api get_repo_config`: 获取代码库基本配置
+- `icode-cli api check_repo_permission`: 检查代码库权限

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

@@ -0,0 +1,86 @@
+# iCode API 命令集
+
+通过 `icode-cli api` 命令组访问 iCode 平台的各种 API。
+
+## 命令概览
+
+### 代码库相关
+
+| 命令 | 功能 | 详细文档 |
+|------|------|----------|
+| `get_person_repo` | 查询个人代码库列表 | [get_person_repo.md](get_person_repo.md) |
+| `get_repo_branch` | 查询代码库分支列表 | [get_repo_branch.md](get_repo_branch.md) |
+| `get_person_commit` | 查询个人提交记录 | [get_person_commit.md](get_person_commit.md) |
+| `get_repo_config` | 获取代码库配置 | [get_repo_config.md](get_repo_config.md) |
+| `get_repo_members` | 获取代码库成员列表 | [get_repo_members.md](get_repo_members.md) |
+| `get_submit_settings` | 获取提交规则配置 | [get_submit_settings.md](get_submit_settings.md) |
+| `check_repo_permission` | 检查代码库权限 | [check_repo_permission.md](check_repo_permission.md) |
+| `create_branch` | 创建新分支 | [create_branch.md](create_branch.md) |
+
+### 评审查询
+
+| 命令 | 功能 | 详细文档 |
+|------|------|----------|
+| `get_repo_reviews` | 查询代码库评审列表 | [get_repo_reviews.md](get_repo_reviews.md) |
+| `get_my_reviews` | 获取我的评审列表 | [get_my_reviews.md](get_my_reviews.md) |
+| `get_review_info` | 获取评审详细信息 | [get_review_info.md](get_review_info.md) |
+| `get_review_comments` | 获取评审评论 | [get_review_comments.md](get_review_comments.md) |
+| `get_machine_check` | 获取机器检查结果 | [get_machine_check.md](get_machine_check.md) |
+| `get_diff_file` | 获取 commit 之间的变更文件 | [get_diff_file.md](get_diff_file.md) |
+| `get_diff_content` | 获取文件的 diff 内容 | [get_diff_content.md](get_diff_content.md) |
+| `build_fetch_command` | 生成 git fetch 命令 | [build_fetch_command.md](build_fetch_command.md) |
+
+### 评审操作
+
+| 命令 | 功能 | 详细文档 |
+|------|------|----------|
+| `set_review_score` | 设置评审分数 | [set_review_score.md](set_review_score.md) |
+| `add_reviewers` | 添加评审人 | [add_reviewers.md](add_reviewers.md) |
+| `submit_review` | 提交/合并评审 | [submit_review.md](submit_review.md) |
+| `create_draft_comment` | 创建草稿评论 | [create_draft_comment.md](create_draft_comment.md) |
+| `publish_comments` | 发布草稿评论 | [publish_comments.md](publish_comments.md) |
+
+### AI 智能评审
+
+| 命令 | 功能 | 详细文档 |
+|------|------|----------|
+| `start_ai_review` | 触发 AI 智能评审 | [start_ai_review.md](start_ai_review.md) |
+| `get_ai_review` | 获取 AI 评审结果 | [get_ai_review.md](get_ai_review.md) |
+
+## 通用参数
+
+所有命令支持以下通用参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--output`, `-o` | 输出格式：json（默认）、yaml、table |
+| `--verbose`, `-v` | 显示详细日志 |
+
+## 快速示例
+
+```bash
+# 查看我的代码库
+icode-cli api get_person_repo --output table
+
+# 查看评审详情
+icode-cli api get_review_info -n 12345
+
+# 批准评审
+icode-cli api set_review_score --repo baidu/icode/test -n 12345 --score 2
+
+# 触发 AI 评审
+icode-cli api start_ai_review -n 12345
+
+# 查询 AI 评审结果
+icode-cli api get_ai_review -i <conversation-id>
+```
+
+## 错误处理
+
+常见错误码：
+
+| 错误 | 说明 | 解决方案 |
+|------|------|----------|
+| `ErrAuthMissing` | 未认证 | 执行 `icode-cli login` 查看登录指引 |
+| `ErrMissingParam` | 缺少必填参数 | 检查命令参数 |
+| `ErrAPIRequest` | API 请求失败 | 检查网络连接 |

package/comate-engine/assets/skills/icode-comate/references/api/publish_comments.md

@@ -0,0 +1,72 @@
+# publish_comments
+
+发布指定评审的所有草稿评论。发布后草稿评论将对其他用户可见。
+
+## 命令格式
+
+```bash
+icode-cli api publish_comments --repo <repo-name> --change-number <n> --patch-set-id <n> [-o json|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名 |
+| `--change-number` | `-n` | 是 | - | 评审编号 |
+| `--patch-set-id` | `-p` | 是 | - | PatchSet 编号 |
+| `--output` | `-o` | 否 | json | 输出格式：json、yaml |
+
+## 使用示例
+
+```bash
+# 发布评审的草稿评论
+icode-cli api publish_comments \
+  --repo baidu/icode/test \
+  --change-number 12345 \
+  --patch-set-id 1
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "Comments published successfully",
+  "data": null
+}
+```
+
+## 典型工作流
+
+```bash
+# 1. 创建多个草稿评论
+icode-cli api create_draft_comment --repo baidu/icode/test -n 12345 -p 1 \
+  --path src/main.go -m "请检查空指针" --line 10
+
+icode-cli api create_draft_comment --repo baidu/icode/test -n 12345 -p 1 \
+  --path src/utils.go -m "建议使用更高效的算法" --line 25
+
+# 2. 一次性发布所有草稿评论
+icode-cli api publish_comments --repo baidu/icode/test -n 12345 -p 1
+```
+
+## 使用场景
+
+1. **批量发布评论**：先创建多个草稿评论，然后一次性发布
+2. **评审完成通知**：发布评论后通知代码作者
+3. **自动化评审**：自动化工具完成评审后发布结果
+
+## 注意事项
+
+- 发布后所有草稿评论变为正式评论，其他用户可见
+- 如果没有草稿评论，调用此命令也会成功
+- 发布后无法撤回，但可以编辑已发布的评论
+
+## 相关命令
+
+- `icode-cli api create_draft_comment`: 创建草稿评论
+- `icode-cli api get_review_comments`: 获取评审评论
+- `icode-cli api set_review_score`: 设置评审分数

package/comate-engine/assets/skills/icode-comate/references/api/set_review_score.md

@@ -0,0 +1,58 @@
+# set_review_score - 设置评审分数
+
+为代码评审设置评分。
+
+## 命令格式
+
+```bash
+icode-cli api set_review_score --repo <代码库名称> --change-number <评审编号> --score <分数>
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库名称，三层目录形式 |
+| `--change-number` | `-n` | 是 | - | 评审编号（数字） |
+| `--score` | `-s` | 是 | - | 评分值（-2 到 +2） |
+
+## 使用示例
+
+```bash
+# 批准评审（+2）
+icode-cli api set_review_score --repo baidu/icode/test -n 12345 --score 2
+
+# 表示认可但需要其他人批准（+1）
+icode-cli api set_review_score -r baidu/icode/test -n 12345 -s 1
+
+# 请求修改（-1）
+icode-cli api set_review_score --repo baidu/icode/test --change-number 12345 --score -1
+
+# 拒绝评审（-2）
+icode-cli api set_review_score -r baidu/icode/test -n 12345 -s -2
+```
+
+## 分数含义
+
+| 分数 | 含义 |
+|------|------|
+| `+2` | 批准合并（Looks good to me, approved） |
+| `+1` | 认可但需要其他人批准（Looks good to me, but someone else must approve） |
+| `0` | 无评分 |
+| `-1` | 建议不要提交（I prefer you don't submit this） |
+| `-2` | 拒绝合并（Do not submit） |
+
+## 返回数据
+
+```
+Status: OK
+Message: 操作成功
+Score: 2
+```
+
+## 注意事项
+
+- 需要有该评审的评审权限
+- 评分值必须在 -2 到 +2 之间
+- 评分会影响评审是否可以合并
+- 同一评审者的新评分会覆盖之前的评分

package/comate-engine/assets/skills/icode-comate/references/api/start_ai_review.md

@@ -0,0 +1,77 @@
+# start_ai_review - 发起 AI 代码评审
+
+发起一个 AI 智能代码评审任务。
+
+## 命令格式
+
+```bash
+icode-cli api start_ai_review --change-number <评审编号> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--change-number` | `-n` | 是 | - | 评审编号（数字） |
+| `--output` | `-o` | 否 | text | 输出格式：json/text |
+
+## 使用示例
+
+```bash
+# 发起 AI 评审
+icode-cli api start_ai_review -n 12345
+
+# JSON 格式输出（获取会话 ID）
+icode-cli api start_ai_review -n 12345 --output json
+```
+
+## 返回数据
+
+### 文本格式
+
+```
+Status: OK
+Message: 操作成功
+Conversation ID: abc123def456
+
+Use 'get_ai_review' with this conversation ID to query results
+```
+
+### JSON 格式
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功",
+  "conversationId": "abc123def456"
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | 操作状态 |
+| `message` | string | 操作消息 |
+| `conversationId` | string | 会话 ID，用于查询评审结果 |
+
+## 使用流程
+
+1. 使用 `start_ai_review` 发起 AI 评审，获取 `conversationId`
+2. 使用 `get_ai_review` 查询评审结果
+
+```bash
+# 1. 发起评审
+icode-cli api start_ai_review -n 12345 -o json
+# 返回: {"conversationId": "abc123"}
+
+# 2. 查询结果
+icode-cli api get_ai_review -i abc123
+```
+
+## 注意事项
+
+- **频率限制**：同一用户 60 秒内只能发起一次 AI 评审
+- AI 评审是异步执行的，需要使用 `get_ai_review` 查询结果
+- 请保存返回的 `conversationId`，用于后续查询
+- 需要有该评审的访问权限

package/comate-engine/assets/skills/icode-comate/references/api/submit_review.md

@@ -0,0 +1,50 @@
+# submit_review - 提交/合并评审
+
+提交代码评审进行合并。
+
+## 命令格式
+
+```bash
+icode-cli api submit_review --repo <代码库名称> --change-number <评审编号>
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库名称，三层目录形式 |
+| `--change-number` | `-n` | 是 | - | 评审编号（数字） |
+
+## 使用示例
+
+```bash
+# 提交评审进行合并
+icode-cli api submit_review --repo baidu/icode/test -n 12345
+
+# 简写形式
+icode-cli api submit_review -r baidu/icode/test -n 12345
+```
+
+## 返回数据
+
+```
+Status: OK
+Message: 操作成功
+Review 12345 has been submitted
+```
+
+## 合并前提条件
+
+评审必须满足以下条件才能被合并：
+
+1. 已获得必要的评审批准（+2）
+2. 所有机器检查已通过
+3. 没有未解决的评审意见
+4. 代码可以无冲突合并
+
+## 注意事项
+
+- 需要有该评审的提交权限
+- 评审必须处于 NEW 状态
+- 如果评审不满足合并条件，操作会失败
+- 合并后评审状态变为 MERGED

package/comate-engine/assets/skills/icode-comate/references/api/trigger_ai_cr.md

@@ -0,0 +1,63 @@
+# trigger_ai_cr - 触发 AI 代码评审
+
+触发一次 AI 智能代码评审任务，返回会话 ID 用于后续查询结果。
+
+## 命令格式
+
+```bash
+icode-cli api start_ai_review --repo <代码库名称> --change-number <CR编号> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库名称，三层目录形式 |
+| `--change-number` | `-n` | 是 | - | CR 编号 |
+| `--output` | `-o` | 否 | text | 输出格式：json/text |
+
+## 使用示例
+
+```bash
+# 触发 AI 评审
+icode-cli api start_ai_review --repo baidu/icode/test --change-number 120247220
+
+# JSON 格式输出（获取会话 ID）
+icode-cli api start_ai_review -r baidu/icode/test -n 120247220 -o json
+```
+
+## 返回数据结构
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功！",
+  "data": {
+    "conversationId": "abc123def456"
+  }
+}
+```
+
+## 关键字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | 操作状态：OK/FAIL |
+| `message` | string | 操作消息 |
+| `data.conversationId` | string | 会话 ID，用于查询评审结果 |
+
+## 获取会话 ID 示例
+
+```bash
+# 触发并提取会话 ID
+RESULT=$(icode-cli api start_ai_review -r baidu/icode/test -n 120247220 -o json)
+CONVERSATION_ID=$(echo "$RESULT" | icode-cli jq -r '.data.conversationId')
+echo "会话 ID: $CONVERSATION_ID"
+```
+
+## 注意事项
+
+- **频率限制**：同一用户 60 秒内只能发起一次 AI 评审
+- AI 评审是异步执行的，需要使用 `get_ai_review` 查询结果
+- 请保存返回的 `conversationId`，用于后续查询
+- 需要有该 CR 的访问权限