@comate/zulu 1.2.1-beta.2 → 1.3.0

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

@@ -0,0 +1,79 @@
+# create_branch
+
+基于已有分支创建新分支。
+
+## 命令格式
+
+```bash
+icode-cli api create_branch --repo <repo-name> --branch <branch-name> --from <source-branch> [-o json|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名，格式如 `baidu/project/repo` |
+| `--branch` | `-b` | 是 | - | 要创建的新分支名 |
+| `--from` | `-f` | 是 | - | 基于哪个来源分支创建 |
+| `--output` | `-o` | 否 | json | 输出格式：json、yaml |
+
+## 使用示例
+
+```bash
+# 基于 master 分支创建 feature-x 分支
+icode-cli api create_branch \
+  --repo baidu/icode/test \
+  --branch feature-x \
+  --from master
+
+# 基于 release 分支创建 hotfix 分支
+icode-cli api create_branch \
+  --repo baidu/icode/test \
+  --branch hotfix-123 \
+  --from release/v1.0
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "Branch created successfully",
+  "data": null
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | 状态码，OK 表示成功 |
+| `message` | string | 状态消息 |
+
+## 使用场景
+
+1. **功能开发**：从主分支创建功能分支
+2. **版本发布**：创建发布分支
+3. **热修复**：从发布分支创建热修复分支
+4. **自动化流程**：CI/CD 中自动创建分支
+
+## 权限要求
+
+- 需要对代码库有写权限
+- 需要 TOKEN 认证
+
+## 错误处理
+
+| 错误信息 | 说明 | 解决方案 |
+|----------|------|----------|
+| `Branch already exists` | 分支已存在 | 使用其他分支名或删除已有分支 |
+| `Source branch not found` | 来源分支不存在 | 检查来源分支名称是否正确 |
+| `Permission denied` | 无权限 | 确认是否有代码库的写权限 |
+
+## 相关命令
+
+- `icode-cli api get_repo_branch`: 获取分支列表
+- `icode-cli git push`: 推送代码
+- `icode-cli git push_cr`: 提交代码评审

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

@@ -0,0 +1,109 @@
+# create_draft_comment
+
+为指定评审创建草稿评论。草稿评论创建后不立即可见，需调用 `publish_comments` 发布后才对其他用户可见。
+
+## 命令格式
+
+```bash
+icode-cli api create_draft_comment --repo <repo-name> --change-number <n> --patch-set-id <n> --path <file-path> --message <message> [--line <n>] [--side <side>] [--unresolved] [-o json|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名 |
+| `--change-number` | `-n` | 是 | - | 评审编号 |
+| `--patch-set-id` | `-p` | 是 | - | PatchSet 编号 |
+| `--path` | - | 是 | - | 文件路径 |
+| `--message` | `-m` | 是 | - | 评论内容 |
+| `--line` | `-l` | 否 | - | 行号（可选） |
+| `--side` | - | 否 | - | diff 侧：PARENT/REVISION |
+| `--unresolved` | - | 否 | true | 是否标记为待解决 |
+| `--output` | `-o` | 否 | json | 输出格式：json、yaml |
+
+## Side 说明
+
+| 值 | 说明 |
+|------|------|
+| `PARENT` | 基准版本（修改前） |
+| `REVISION` | 新版本（修改后） |
+
+## 使用示例
+
+```bash
+# 创建简单草稿评论
+icode-cli api create_draft_comment \
+  --repo baidu/icode/test \
+  --change-number 12345 \
+  --patch-set-id 1 \
+  --path src/main.go \
+  --message "请修改此处逻辑"
+
+# 创建带行号的草稿评论
+icode-cli api create_draft_comment \
+  --repo baidu/icode/test \
+  --change-number 12345 \
+  --patch-set-id 1 \
+  --path src/main.go \
+  --message "建议优化这里的性能" \
+  --line 42 \
+  --side REVISION
+
+# 创建已解决状态的评论
+icode-cli api create_draft_comment \
+  --repo baidu/icode/test \
+  --change-number 12345 \
+  --patch-set-id 1 \
+  --path src/main.go \
+  --message "LGTM" \
+  --unresolved=false
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "",
+  "data": {
+    "id": "comment-123",
+    "path": "src/main.go",
+    "line": 42,
+    "message": "建议优化这里的性能",
+    "unresolved": true,
+    "updated": "2024-01-15 10:30:00"
+  }
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 评论 ID |
+| `path` | string | 文件路径 |
+| `line` | int | 行号 |
+| `message` | string | 评论内容 |
+| `unresolved` | bool | 是否待解决 |
+| `updated` | string | 更新时间 |
+
+## 使用场景
+
+1. **代码评审**：对代码的具体位置添加评论
+2. **批量评论**：先创建多个草稿评论，然后一次性发布
+3. **AI 评审集成**：自动化工具添加评审意见
+
+## 注意事项
+
+- 草稿评论只有创建者可见
+- 需要调用 `publish_comments` 后其他人才能看到
+- 可以在发布前修改或删除草稿
+
+## 相关命令
+
+- `icode-cli api publish_comments`: 发布草稿评论
+- `icode-cli api get_review_comments`: 获取评审评论
+- `icode-cli api get_review_info`: 获取评审详情

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

@@ -0,0 +1,190 @@
+# get_ai_cr_result - 获取 AI 评审结果
+
+获取 AI 智能代码评审的执行结果，包括评审状态和具体评论。
+
+## 命令格式
+
+```bash
+icode-cli api get_ai_review --conversation-id <会话ID> --repo <代码库名称> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--conversation-id` | `-i` | 是 | - | 会话 ID（从 start_ai_review 获取） |
+| `--repo` | `-r` | 是 | - | 代码库名称，三层目录形式 |
+| `--output` | `-o` | 否 | text | 输出格式：json/text |
+
+## 使用示例
+
+```bash
+# 获取 AI 评审结果
+icode-cli api get_ai_review --conversation-id abc123def456 --repo baidu/icode/test
+
+# JSON 格式输出
+icode-cli api get_ai_review -i abc123def456 -r baidu/icode/test -o json
+```
+
+## 返回数据结构
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功！",
+  "data": {
+    "conversationId": "abc123def456",
+    "crStatus": "SUSS",
+    "results": [
+      {
+        "id": 1,
+        "sessionId": "abc123def456",
+        "messageType": "OTHER",
+        "processedContent": {
+          "text": "代码整体质量良好，有 2 处建议改进"
+        },
+        "status": "PROCESSED"
+      },
+      {
+        "id": 2,
+        "sessionId": "abc123def456",
+        "messageType": "INTERLINEAR_COMMENT",
+        "processedContent": {
+          "id": 1,
+          "fileName": "src/main.go",
+          "patchSetId": 1,
+          "startLine": 42,
+          "endLine": 42,
+          "severityScore": 7,
+          "message": "建议添加错误处理逻辑，避免空指针异常",
+          "updated": "2024-01-15 10:30:00"
+        },
+        "status": "PROCESSED"
+      }
+    ]
+  }
+}
+```
+
+## 关键字段说明
+
+### crStatus (评审状态)
+
+| 状态 | 含义 | 说明 |
+|------|------|------|
+| `EXECUTING` | 执行中 | AI 评审正在进行 |
+| `TIMEOUT` | 超时 | AI 评审执行超时 |
+| `FAIL` | 失败 | AI 评审执行失败 |
+| `SUSS` | 成功 | AI 评审完成 |
+
+### messageType (消息类型)
+
+| 类型 | 含义 | 说明 |
+|------|------|------|
+| `OTHER` | 文本消息 | 通用文本类型（总结、说明等） |
+| `INTERLINEAR_COMMENT` | 行内评论 | 具体代码位置的评审意见 |
+
+### processedContent (处理后的内容)
+
+#### OTHER 类型
+
+```json
+{
+  "text": "代码整体质量良好..."
+}
+```
+
+#### INTERLINEAR_COMMENT 类型
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | 评论 ID |
+| `fileName` | string | 文件路径 |
+| `patchSetId` | int | 补丁集 ID |
+| `startLine` | int | 起始行号 |
+| `endLine` | int | 结束行号 |
+| `severityScore` | int | 严重程度评分 (1-10) |
+| `message` | string | 评审意见内容 |
+| `updated` | string | 更新时间 |
+
+## severityScore 严重程度说明
+
+| 分数范围 | 严重程度 | 说明 |
+|----------|----------|------|
+| 1-3 | 低 | 代码风格、命名建议等 |
+| 4-6 | 中 | 代码优化、性能改进建议 |
+| 7-10 | 高 | 潜在 bug、安全问题等 |
+
+## 提取需要修复的问题示例
+
+```bash
+# 获取 AI 评审结果
+RESULT=$(icode-cli api get_ai_review -i abc123def456 -r baidu/icode/test -o json)
+
+# 检查状态
+CR_STATUS=$(echo "$RESULT" | icode-cli jq -r '.data.crStatus')
+
+if [ "$CR_STATUS" = "SUSS" ]; then
+    # 提取 severityScore >= 5 的行内评论
+    ISSUES=$(echo "$RESULT" | icode-cli jq '
+        .data.results[] |
+        select(.messageType == "INTERLINEAR_COMMENT") |
+        .processedContent |
+        select(.severityScore >= 5)
+    ')
+
+    # 统计问题数量
+    ISSUE_COUNT=$(echo "$RESULT" | icode-cli jq '
+        [.data.results[] |
+         select(.messageType == "INTERLINEAR_COMMENT") |
+         .processedContent |
+         select(.severityScore >= 5)] | length
+    ')
+
+    echo "发现 $ISSUE_COUNT 个需要修复的问题"
+fi
+```
+
+## 轮询等待完成示例
+
+```bash
+CONVERSATION_ID="abc123def456"
+REPO_NAME="baidu/icode/test"
+MAX_WAIT=1200  # 20 分钟
+POLL_INTERVAL=10
+
+elapsed=0
+while [ $elapsed -lt $MAX_WAIT ]; do
+    RESULT=$(icode-cli api get_ai_review -i "$CONVERSATION_ID" -r "$REPO_NAME" -o json)
+    STATUS=$(echo "$RESULT" | icode-cli jq -r '.data.crStatus')
+
+    case "$STATUS" in
+        "SUSS")
+            echo "AI 评审完成"
+            break
+            ;;
+        "FAIL"|"TIMEOUT")
+            echo "AI 评审失败: $STATUS"
+            exit 1
+            ;;
+        "EXECUTING")
+            echo "AI 评审执行中，等待 ${POLL_INTERVAL} 秒..."
+            sleep $POLL_INTERVAL
+            elapsed=$((elapsed + POLL_INTERVAL))
+            ;;
+    esac
+done
+
+if [ $elapsed -ge $MAX_WAIT ]; then
+    echo "轮询超时"
+    exit 1
+fi
+```
+
+## 注意事项
+
+- **查询者限制**：只有发起 AI 评审的用户才能查询结果
+- 如果状态为 `EXECUTING`，需要稍后再次查询
+- `processedContent` 的结构根据 `messageType` 不同而不同
+- 使用 `severityScore` 字段来判断问题的严重程度
+- 建议设置合理的轮询间隔（10 秒）和超时时间（20 分钟）

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

@@ -0,0 +1,97 @@
+# get_ai_review - 获取 AI 评审结果
+
+获取 AI 智能代码评审的结果。
+
+## 命令格式
+
+```bash
+icode-cli api get_ai_review --conversation-id <会话ID> [--output <格式>]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--conversation-id` | `-i` | 是 | - | 会话 ID（从 start_ai_review 获取） |
+| `--output` | `-o` | 否 | text | 输出格式：json/text |
+
+## 使用示例
+
+```bash
+# 获取 AI 评审结果
+icode-cli api get_ai_review -i abc123def456
+
+# JSON 格式输出
+icode-cli api get_ai_review --conversation-id abc123def456 --output json
+```
+
+## 返回数据
+
+### 文本格式
+
+```
+Status: OK
+Message: 操作成功
+
+Results:
+{
+  "reviewStatus": "COMPLETED",
+  "comments": [
+    {
+      "file": "src/main.go",
+      "line": 42,
+      "message": "建议添加错误处理逻辑",
+      "severity": "WARNING"
+    }
+  ],
+  "summary": "代码整体质量良好，有 2 处建议改进"
+}
+```
+
+### JSON 格式
+
+```json
+{
+  "status": "OK",
+  "message": "操作成功",
+  "data": {
+    "reviewStatus": "COMPLETED",
+    "comments": [
+      {
+        "file": "src/main.go",
+        "line": 42,
+        "message": "建议添加错误处理逻辑",
+        "severity": "WARNING"
+      }
+    ],
+    "summary": "代码整体质量良好，有 2 处建议改进"
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `reviewStatus` | string | 评审状态：PENDING/RUNNING/COMPLETED/FAILED |
+| `comments` | array | AI 评审意见列表 |
+| `comments[].file` | string | 文件路径 |
+| `comments[].line` | int | 代码行号 |
+| `comments[].message` | string | 评审意见内容 |
+| `comments[].severity` | string | 严重程度：INFO/WARNING/ERROR |
+| `summary` | string | 评审总结 |
+
+## 评审状态说明
+
+| 状态 | 含义 |
+|------|------|
+| `PENDING` | 等待处理 |
+| `RUNNING` | 评审进行中 |
+| `COMPLETED` | 评审完成 |
+| `FAILED` | 评审失败 |
+
+## 注意事项
+
+- **查询者限制**：只有发起 AI 评审的用户才能查询结果
+- 如果状态为 `RUNNING`，需要稍后再次查询
+- 会话 ID 来自 `start_ai_review` 命令的返回值

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

@@ -0,0 +1,92 @@
+# get_diff_content
+
+获取文件在两个 commit 之间的 diff 内容。
+
+## 命令格式
+
+```bash
+icode-cli api get_diff_content --repo <repo-name> --commit <commit-id> --file <file-path> [--base <base-commit>] [-o json|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名，格式如 `baidu/project/repo` |
+| `--commit` | `-c` | 是 | - | 目标 commit ID |
+| `--file` | `-f` | 是 | - | 文件路径 |
+| `--base` | `-b` | 否 | commit^ | 基准 commit ID，默认为目标 commit 的父提交 |
+| `--output` | `-o` | 否 | json | 输出格式：json、yaml |
+
+## 使用示例
+
+```bash
+# 获取某个文件相对于父 commit 的 diff
+icode-cli api get_diff_content --repo baidu/icode/test --commit abc123 --file src/main.go
+
+# 获取两个指定 commit 之间某文件的 diff
+icode-cli api get_diff_content --repo baidu/icode/test --commit abc123 --base def456 --file src/main.go
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "",
+  "data": {
+    "metaA": {
+      "name": "src/main.go",
+      "lines": 100
+    },
+    "metaB": {
+      "name": "src/main.go",
+      "lines": 110
+    },
+    "changeType": "MODIFIED",
+    "content": [
+      {
+        "ab": ["package main", "", "import ("],
+        "common": 3
+      },
+      {
+        "a": ["    \"fmt\""],
+        "b": ["    \"fmt\"", "    \"log\""],
+        "editA": [0, 1],
+        "editB": [0, 2]
+      }
+    ],
+    "diff_header": [
+      "diff --git a/src/main.go b/src/main.go",
+      "index abc123..def456 100644"
+    ]
+  }
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | 状态码，OK 表示成功 |
+| `data.metaA` | object | 基准版本文件元信息 |
+| `data.metaB` | object | 目标版本文件元信息 |
+| `data.changeType` | string | 变更类型：MODIFIED、ADDED、DELETED、RENAMED |
+| `data.content` | array | diff 内容块列表 |
+| `data.content[].ab` | array | 未变更的行（两边相同） |
+| `data.content[].a` | array | 基准版本的行（被删除或修改） |
+| `data.content[].b` | array | 目标版本的行（新增或修改后） |
+| `data.diff_header` | array | diff 头信息 |
+
+## 使用场景
+
+1. **代码差异分析**：查看具体代码变更内容
+2. **代码评审**：详细检查修改的代码
+3. **变更追踪**：了解某个文件的具体修改
+
+## 相关命令
+
+- `icode-cli api get_diff_file`: 获取变更文件列表
+- `icode-cli api get_review_comments`: 获取评审评论

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

@@ -0,0 +1,88 @@
+# get_diff_file
+
+获取两个 commit 之间的变更文件列表。
+
+## 命令格式
+
+```bash
+icode-cli api get_diff_file --repo <repo-name> --commit <commit-id> [--base <base-commit>] [-o json|table|yaml]
+```
+
+## 参数说明
+
+| 参数 | 短参数 | 必填 | 默认值 | 说明 |
+|------|--------|------|--------|------|
+| `--repo` | `-r` | 是 | - | 代码库全名，格式如 `baidu/project/repo` |
+| `--commit` | `-c` | 是 | - | 目标 commit ID |
+| `--base` | `-b` | 否 | commit^ | 基准 commit ID，默认为目标 commit 的父提交 |
+| `--output` | `-o` | 否 | json | 输出格式：json、table、yaml |
+
+## 使用示例
+
+```bash
+# 获取某个 commit 相对于其父 commit 的变更文件
+icode-cli api get_diff_file --repo baidu/icode/test --commit abc123
+
+# 获取两个指定 commit 之间的变更文件
+icode-cli api get_diff_file --repo baidu/icode/test --commit abc123 --base def456
+
+# 以表格形式输出
+icode-cli api get_diff_file --repo baidu/icode/test --commit abc123 --output table
+```
+
+## 输出格式
+
+### JSON 格式（默认）
+
+```json
+{
+  "status": "OK",
+  "message": "",
+  "data": {
+    "src/main.go": {
+      "status": "M",
+      "linesInserted": 10,
+      "sizeDelta": 256
+    },
+    "src/utils.go": {
+      "status": "A",
+      "linesInserted": 50,
+      "sizeDelta": 1024
+    }
+  }
+}
+```
+
+### Table 格式
+
+```
+Total: 2 files
+
+File          Status  LinesInserted  SizeDelta
+----          ------  -------------  ---------
+src/main.go   M       10             256
+src/utils.go  A       50             1024
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | 状态码，OK 表示成功 |
+| `message` | string | 状态消息 |
+| `data` | object | 文件变更映射，key 为文件路径 |
+| `data[file].status` | string | 文件状态：A(新增)、M(修改)、D(删除)、R(重命名) |
+| `data[file].linesInserted` | int | 新增行数 |
+| `data[file].sizeDelta` | int | 大小变化（字节） |
+
+## 使用场景
+
+1. **查看提交变更范围**：快速了解某次提交修改了哪些文件
+2. **代码评审准备**：在评审前了解变更文件列表
+3. **自动化脚本**：根据变更文件触发对应的检查或构建
+
+## 相关命令
+
+- `icode-cli api get_diff_content`: 获取具体文件的 diff 内容
+- `icode-cli api get_person_commit`: 查询个人提交记录
+- `icode-cli api get_review_info`: 获取评审详情