0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
cann-robotcann-robotfeat: 新增 GitCode 协作 Skills（infra/ 域，gitcode-pr-handler / gitcode-issue-gen / gitcode-issue-handler / gitcode-toolkit）
49d03914创建于 15 天前历史提交

GitCode API 参考文档

基础地址：https://api.gitcode.com/api/v5

目录

  1. PR 相关 API
  2. Issue 相关 API
  3. 仓库内容 API
  4. 错误处理
  5. 最佳实践
  6. 命令速查

1. PR 相关 API

获取 PR 详情

GET /repos/{owner}/{repo}/pulls/{number}

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}?access_token={token}'

返回字段：

字段 类型 说明
number int PR 编号
title string PR 标题
body string PR 描述
state string 状态 (open, closed)
user.login string 作者用户名
user.name string 作者名称
head.ref string 源分支名
head.sha string 源分支最新 commit
base.ref string 目标分支名
merged bool 是否已合并
mergeable bool 是否可合并
commits int 提交数
additions int 新增行数
deletions int 删除行数
changed_files int 变更文件数

获取 PR 文件列表

GET /repos/{owner}/{repo}/pulls/{number}/files

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/files?access_token={token}&per_page=100'

注意：此 API 可能返回认证错误（Invalid header parameter: private-token, required）。 推荐替代方案：使用 git 命令获取变更文件，详见 本 skill SKILL.md 速查表 及 diff-and-changes.md。

返回字段（每个文件）：

字段 类型 说明
filename string 文件路径
status string 状态 (added, modified, removed, renamed)
additions int 新增行数
deletions int 删除行数
changes int 总变更行数
patch string diff 内容

获取 PR Commits

GET /repos/{owner}/{repo}/pulls/{number}/commits

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/commits?access_token={token}'

获取已有评论列表

GET /repos/{owner}/{repo}/pulls/{number}/comments

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/comments?access_token={token}'

用途：避免重复提交相同评论

提交行内评论

针对具体代码行提交评论：

POST /repos/{owner}/{repo}/pulls/{number}/comments

curl -X POST 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/comments?access_token={token}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "body": "评论内容",
  "path": "src/main.py",
  "position": 45
}'

参数说明：

参数 必填 类型 说明
body Y string 评论内容
path Y string 文件相对路径（如 src/main.py）
position Y int PR 分支版本文件中的绝对行号（1-based）。通过 git clone + git checkout pr_{number} 后，用 Read 工具读取本地文件得到的行号即为该值。不是 diff 相对行号，不是 diff hunk 索引。已在多个 PR 实测验证。
commit_id string 提交 SHA（可选，默认使用最新）
in_reply_to int 回复的评论 ID（用于回复）

提交整体评论

不针对特定代码行的评论：

POST /repos/{owner}/{repo}/pulls/{number}/comments

curl -X POST 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/comments?access_token={token}' \
-H 'Content-Type: application/json' \
-d '{
  "body": "整体评论内容"
}'

更新 PR

PATCH /repos/{owner}/{repo}/pulls/{number}

curl -X PATCH "https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}?access_token={token}" \
  --data-urlencode "title=PR标题" \
  --data-urlencode "body=PR描述内容"

创建 PR

POST /repos/{owner}/{repo}/pulls

curl -X POST "https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "access_token=${token}" \
  -d "title=${pr_title}" \
  -d "body=${pr_body}" \
  -d "head=${username}:${branch_name}" \
  -d "base=master"

head 参数格式：从 fork 仓库向上游创建 PR 时，必须使用 {fork用户名}:{分支名} 格式。

获取已有 PR 列表

GET /repos/{owner}/{repo}/pulls

curl "https://api.gitcode.com/api/v5/repos/${owner}/${repo}/pulls?state=opened&source_branch=${branch_name}&access_token=${token}"

批量提交评论脚本

#!/bin/bash
OWNER="owner"
REPO="repo"
PR_NUMBER="123"
TOKEN="$GITCODE_TOKEN"
COMMENTS_FILE="comments.json"

cat "$COMMENTS_FILE" | jq -c '.[]' | while read -r comment; do
    body=$(echo "$comment" | jq -r '.body')
    path=$(echo "$comment" | jq -r '.path')
    position=$(echo "$comment" | jq -r '.position')

    echo "提交评论: $path:$position"

    response=$(curl -s -w "\n%{http_code}" -X POST \
        "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments?access_token=$TOKEN" \
        -H 'Content-Type: application/json' \
        -d "{\"body\": \"$body\", \"path\": \"$path\", \"position\": $position}")

    http_code=$(echo "$response" | tail -n1)
    if [ "$http_code" -eq 201 ]; then
        echo "  成功"
    else
        echo "  失败: HTTP $http_code"
        echo "$response" | head -n-1
    fi

    sleep 0.5
done

2. Issue 相关 API

获取 Issue 详情

GET /repos/{owner}/{repo}/issues/{number}

curl -s "https://api.gitcode.com/api/v5/repos/${owner}/${repo}/issues/${issue_number}?access_token=${token}" \
  --connect-timeout 60 --max-time 180

响应字段：

字段 说明
title Issue 标题
body Issue 正文（包含模板和待填写内容）
labels 标签列表
state 状态（open/closed）

创建 Issue

POST /repos/{owner}/{repo}/issues

curl -X POST 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/issues?access_token={token}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "title": "Issue 标题",
  "body": "Issue 描述内容",
  "labels": "requirement",
  "assignees": "username"
}'

参数说明：

参数 必填 类型 说明
title Y string Issue 标题（最大 255 字符）
body Y string Issue 描述（支持 Markdown）
labels string 标签名称，单个字符串（如 "requirement"），不支持数组格式
assignees string 指派用户名，单个字符串（如 "username"），不支持数组格式
milestone int 里程碑 ID

重要：GitCode API 的 labels 和 assignees 参数与 GitHub API 不同，必须使用字符串格式，不支持 JSON 数组。传入数组（如 ["bug", "enhancement"]）会导致 400 BAD_REQUEST 错误。多个标签可用逗号分隔（如 "bug,enhancement"）。

获取 Issue 列表

GET /repos/{owner}/{repo}/issues

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/issues?access_token={token}&state=open'

更新 Issue

PATCH /repos/{owner}/{repo}/issues/{number}

curl -X PATCH 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/issues/{number}?access_token={token}' \
-H 'Content-Type: application/json' \
-d '{
  "title": "更新后的标题",
  "body": "更新后的描述"
}'

关闭 Issue

PATCH /repos/{owner}/{repo}/issues/{number}

curl -X PATCH 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/issues/{number}?access_token={token}' \
-H 'Content-Type: application/json' \
-d '{"state": "closed"}'

提交 Issue 评论

POST /repos/{owner}/{repo}/issues/{number}/comments

curl -X POST "https://api.gitcode.com/api/v5/repos/${owner}/${repo}/issues/${issue_number}/comments" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d "{
    \"access_token\": \"${token}\",
    \"body\": \"${comment_body}\"
  }" \
  --connect-timeout 60 --max-time 300

3. 仓库内容 API

获取仓库内容

用于获取模板文件：

GET /repos/{owner}/{repo}/contents/{path}

curl 'https://api.gitcode.com/api/v5/repos/{owner}/{repo}/contents/{path}?ref={branch}&access_token={token}'

返回示例（目录）：

[
  {
    "name": "bug_report.md",
    "path": ".github/ISSUE_TEMPLATE/bug_report.md",
    "type": "file",
    "download_url": "https://gitcode.com/..."
  }
]

返回示例（文件）：

{
  "name": "bug_report.md",
  "content": "LS0tCm5hbWU6IEJ1ZyByZXBvcnQK...",
  "encoding": "base64"
}

需要解码：echo "${content}" | base64 -d

常见模板位置

类型 路径
GitHub PR 模板 .github/PULL_REQUEST_TEMPLATE.md
GitCode PR 模板 .gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md
GitHub Issue 模板 .github/ISSUE_TEMPLATE/*.md
GitCode Issue 模板 .gitcode/ISSUE_TEMPLATE/
GitLab MR 模板 .gitlab/merge_request_templates/*.md

4. 错误处理

HTTP 状态码

状态码 说明 处理方式
200 成功（GET/PATCH） 正常处理响应
201 创建成功（POST） 正常处理响应
401 Token 无效或过期 提示用户提供新 token
403 无权限访问 确认用户是否有仓库写权限
404 资源不存在 确认链接是否正确
409 冲突 PR 可能已更新，重新获取代码
422 参数验证失败 检查参数格式和有效性
429 请求频率限制 等待后重试

错误响应格式

{
  "error_code": 422,
  "error_code_name": "VALIDATION_ERROR",
  "error_message": "错误描述",
  "trace_id": "abc123def456"
}

常见错误处理

行号无效 (422)

原因：提交的行号在文件中不存在
解决：重新使用 Read 工具或 git show 获取正确的行号

# 重新获取行号
git show pr_{number}:{file_path} | grep -n "代码片段"

文件路径错误 (404)

原因：文件路径不正确或文件不在 PR 变更中
解决：确认文件在 PR 的变更文件列表中

Token 权限不足 (403)

原因：Token 没有写权限
解决：提示用户生成具有 repo 权限的新 token

Title 过长 (422)

原因：标题超过 255 字符
解决：截断标题或重新生成更简洁的标题

Label 不存在 (422)

原因：指定的标签在仓库中不存在
解决：先获取可用标签列表，或跳过标签参数

5. 最佳实践

提交策略

  1. 逐条提交：避免批量提交失败导致全部丢失
  2. 按优先级排序：先提交高严重程度的问题
  3. 添加延迟：避免请求频率限制（建议 sleep 0.5）
  4. 记录结果：跟踪每条评论的提交状态

内容生成

  1. 标题简洁：控制在 50-80 字符内
  2. 结构清晰：使用 Markdown 标题分隔不同部分
  3. 关联明确：包含 PR 链接或编号
  4. 可追溯：记录变更原因和影响范围

安全考虑

  1. Token 保护：不在日志中输出 token
  2. 敏感信息：不在评论/Issue 中包含敏感信息
  3. 权限最小化：只申请必要的权限

6. 命令速查

# 获取 PR 详情
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR?access_token=$TOKEN"

# 获取 PR 文件
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR/files?access_token=$TOKEN"

# 获取 PR Commits
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR/commits?access_token=$TOKEN"

# 提交行内评论
curl -X POST "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR/comments?access_token=$TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"body":"评论内容","path":"文件路径","position":行号}'

# 获取已有评论
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR/comments?access_token=$TOKEN"

# 更新 PR
curl -X PATCH "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls/$PR?access_token=$TOKEN" \
  --data-urlencode "title=PR标题" --data-urlencode "body=PR描述"

# 创建 PR
curl -X POST "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/pulls?access_token=$TOKEN" \
  -d "title=标题" -d "body=描述" -d "head=user:branch" -d "base=master"

# 获取 Issue 详情
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/issues/$ISSUE?access_token=$TOKEN"

# 创建 Issue
curl -X POST "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/issues?access_token=$TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"标题","body":"描述"}'

# 提交 Issue 评论
curl -X POST "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/issues/$ISSUE/comments?access_token=$TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"body":"评论内容"}'

# 获取仓库内容/模板
curl "https://api.gitcode.com/api/v5/repos/$OWNER/$REPO/contents/{path}?access_token=$TOKEN"