external-mindstudio-gitcode-code-reviewer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitCode 代码审查助手

GitCode Code Review Assistant

针对 GitCode PR 做“有上下文”的代码审查。

diff

只是入口，不是全部证据；必须结合 PR 标题/描述、变更文件、调用链、相邻模块、历史实现、测试与配置来判断改动是否真的正确。

Perform "context-aware" code reviews for GitCode PRs. The

diff

is just an entry point, not all evidence; you must combine PR title/description, changed files, call chains, adjacent modules, historical implementations, tests and configurations to determine if the changes are truly correct.

前置要求

Prerequisites

GitCode 访问令牌

GitCode Access Token

本技能需要 GitCode 访问令牌，用于获取 PR 信息和发布评论。令牌可通过以下方式之一配置：

环境变量（推荐）：
```
GITCODE_TOKEN
```

Git 配置：

git config --global gitcode.token <your-token>

如果没有找到令牌，需要提示用户提供。

This skill requires a GitCode access token to obtain PR information and publish comments. The token can be configured in one of the following ways:

Environment Variable (Recommended):
```
GITCODE_TOKEN
```

Git Configuration:

git config --global gitcode.token <your-token>

If no token is found, prompt the user to provide one.

获取 GitCode 令牌

Obtaining a GitCode Token

登录 https://gitcode.com
点击头像，进入“设置”
打开“私人令牌”
创建新令牌，并授予以下权限：
- ```
pull_requests
```
  （读写）
- ```
issues
```
  （读写）
- ```
projects
```
  （只读）

Log in to https://gitcode.com
Click your avatar and enter "Settings"
Open "Personal Tokens"
Create a new token and grant the following permissions:
- ```
pull_requests
```
  (Read/Write)
- ```
issues
```
  (Read/Write)
- ```
projects
```
  (Read-only)

工作流程

Workflow

1. 解析 PR 信息

1. Parse PR Information

当用户提供类似

https://gitcode.com/Ascend/msprof/pull/109

的 GitCode PR 链接时：

提取：
```
owner=Ascend
```
、
```
repo=msprof
```
、
```
pull_number=109
```

When the user provides a GitCode PR link like

https://gitcode.com/Ascend/msprof/pull/109

Extract:
```
owner=Ascend
```
,
```
repo=msprof
```
,
```
pull_number=109
```

2. 获取 PR 信息

2. Retrieve PR Information

使用

scripts/fetch_pr_info.py

获取 PR 详情：

bash

python scripts/fetch_pr_info.py \
  --owner <OWNER> --repo <REPO> --pull-number <NUMBER> \
  [--token <TOKEN>] [--output-dir <DIR>]

该脚本会获取：

PR 元数据，例如标题、描述、作者、状态
发生变更的文件及其 diff 内容
PR 评论（可选）

Use

scripts/fetch_pr_info.py

to get PR details:

bash

python scripts/fetch_pr_info.py \
  --owner <OWNER> --repo <REPO> --pull-number <NUMBER> \
  [--token <TOKEN>] [--output-dir <DIR>]

This script will retrieve:

PR metadata such as title, description, author, status
Changed files and their diff content
PR comments (optional)

3. 准备分析工作区

3. Prepare Analysis Workspace

优先使用用户当前 workspace；如果当前目录已经是目标仓库，并且可以拿到 PR 对应分支或 commit，就直接在当前仓库分析，不要重复克隆。

只有在当前 workspace 不是目标仓库，或无法获取 PR 对应代码时，才克隆到临时目录：

bash

export GITCODE_TOKEN="your-token"
TEMP_DIR="/tmp/gitcode-review-<REPO>-<TIMESTAMP>"
git clone --depth=50 "https://oauth2:${GITCODE_TOKEN}@gitcode.com/<OWNER>/<REPO>.git" "${TEMP_DIR}"
cd "${TEMP_DIR}"

Prioritize using the user's current workspace; if the current directory is already the target repository and the PR's corresponding branch or commit is accessible, analyze directly in the current repository without cloning again.

Only clone to a temporary directory if the current workspace is not the target repository or the PR's corresponding code cannot be obtained:

bash

export GITCODE_TOKEN="your-token"
TEMP_DIR="/tmp/gitcode-review-<REPO>-<TIMESTAMP>"
git clone --depth=50 "https://oauth2:${GITCODE_TOKEN}@gitcode.com/<OWNER>/<REPO>.git" "${TEMP_DIR}"
cd "${TEMP_DIR}"

获取 PR 分支

Fetch PR branch

git fetch origin "refs/merge-requests/<NUMBER>/head:pr-<NUMBER>-source" git checkout "pr-<NUMBER>-source"

undefined

git fetch origin "refs/merge-requests/<NUMBER>/head:pr-<NUMBER>-source" git checkout "pr-<NUMBER>-source"

undefined

4. 构建审查上下文（必做）

4. Build Review Context (Mandatory)

先读

summary.json

、

pr_metadata.json

、

pr_files.json

、

pr_diff.patch

，再开始看代码。必须先回答下面几个问题：

这个 PR 想解决什么问题
- 从标题、描述、标签、关联 issue、文件分布中推断目标，是修 bug、加功能、重构、补测试、回滚还是兼容性修复。
- 如果 PR 描述不足，要根据修改内容自行归纳目的，并在结论里说明你的判断依据。
改动落在系统的哪一层
- 识别变更文件分别属于入口层、核心逻辑层、数据模型层、接口/协议层、配置/构建层、测试层、生成产物。
- 如果是生成文件、lockfile、SDK 产物，继续追到“源头文件”审查，不要只评论生成结果。
这些改动与仓库中的哪些实现有关
- 查调用方、被调用方、同类实现、适配层、配置项、feature flag、schema、迁移脚本、测试夹具、文档。
- 审查时必须看修改行的上下文文件，不要只看 patch hunk。
基线行为是什么
- 通过 base 分支代码、历史提交或已有测试确认原本行为，再判断这次改动是否破坏兼容性或遗漏分支。

推荐优先使用这些工具建立上下文：

```
rg -n "<symbol>|<config>|<endpoint>" .
```
：查调用链、配置项、同类实现、测试覆盖
```
git diff --stat <base_sha>...<head_sha>
```
：快速识别高风险改动面

git diff --name-only <base_sha>...<head_sha>

：按模块分组变更文件

```
git show <base_sha>:<path>
```
：对比基线实现
```
git log --follow -- <path>
```
：看文件演进和历史意图
```
git blame -L <start>,<end> -- <path>
```
：定位历史上下文和责任归属
项目自带测试/构建命令：验证推断是否成立

如果某个结论依赖推断而不是直接证据，必须明确写出条件，例如“如果这里允许空集合输入，那么当前实现会……”。不要把猜测写成确定事实。

Read

summary.json

pr_metadata.json

pr_files.json

pr_diff.patch

first before reviewing code. You must answer the following questions:

What problem is this PR trying to solve?
- Infer the goal from the title, description, tags, linked issues, and file distribution—whether it's fixing a bug, adding a feature, refactoring, supplementing tests, rolling back, or compatibility fixes.
- If the PR description is insufficient, summarize the purpose based on the changes and explain your reasoning in the conclusion.
Which layer of the system do the changes belong to?
- Identify whether the changed files belong to the entry layer, core logic layer, data model layer, interface/protocol layer, configuration/build layer, test layer, or generated artifacts.
- If they are generated files, lockfiles, or SDK artifacts, trace back to the "source files" for review instead of only commenting on the generated results.
Which implementations in the repository are related to these changes?
- Check callers, callees, similar implementations, adaptation layers, configuration items, feature flags, schemas, migration scripts, test fixtures, and documentation.
- When reviewing, you must look at the context files of the modified lines, not just the patch hunk.
What is the baseline behavior?
- Confirm the original behavior through the base branch code, historical commits, or existing tests, then determine if this change breaks compatibility or omits branches.

Recommended tools to build context:

```
rg -n "<symbol>|<config>|<endpoint>" .
```
: Check call chains, configuration items, similar implementations, test coverage
```
git diff --stat <base_sha>...<head_sha>
```
: Quickly identify high-risk change areas

git diff --name-only <base_sha>...<head_sha>

: Group changed files by module

```
git show <base_sha>:<path>
```
: Compare baseline implementations
```
git log --follow -- <path>
```
: View file evolution and historical intent
```
git blame -L <start>,<end> -- <path>
```
: Locate historical context and responsible parties
Project-specific test/build commands: Verify if your inferences are valid

If a conclusion relies on inference rather than direct evidence, clearly state the conditions, e.g., "If empty set input is allowed here, then the current implementation will...". Do not present guesses as facts.

5. 深入审查代码

5. In-Depth Code Review

在完成上下文构建后，从以下维度审查，并尽量结合项目实际实现给出判断：

目标一致性：实现是否真的满足 PR 目标，是否只改了表层而漏掉调用链上的必要改动
正确性与回归风险：老行为是否被意外改变，边界条件、异常路径、状态切换是否完整
契约兼容性：函数签名、接口字段、返回值、序列化格式、错误码、配置项是否与上下游兼容
项目一致性：是否偏离仓库中已有模式，导致后续维护成本升高或行为不一致
性能与资源：是否引入不必要的遍历、重复 I/O、锁竞争、缓存失效、N+1 调用等问题
安全性：输入校验、权限边界、敏感数据处理、命令/SQL/路径注入等风险
可测试性：关键分支是否有测试支撑；没有测试时，至少指出应补哪类用例

After building the context, review from the following dimensions and try to combine the project's actual implementation to make judgments:

Goal Consistency: Does the implementation truly meet the PR's goal? Are only surface changes made while necessary changes in the call chain are missed?
Correctness and Regression Risk: Is the old behavior accidentally changed? Are boundary conditions, exception paths, and state transitions complete?
Contract Compatibility: Are function signatures, interface fields, return values, serialization formats, error codes, and configuration items compatible with upstream and downstream?
Project Consistency: Does it deviate from existing patterns in the repository, leading to higher maintenance costs or inconsistent behavior?
Performance and Resources: Does it introduce unnecessary traversals, repeated I/O, lock contention, cache invalidation, N+1 calls, etc.?
Security: Risks such as input validation, permission boundaries, sensitive data handling, command/SQL/path injection
Testability: Are critical branches supported by tests? If there are no tests, at least indicate what types of use cases should be added

6. 整理审查结论

6. Organize Review Conclusions

按照严重程度组织问题：

严重：会导致 bug、安全问题或破坏性变更
建议：建议优化代码质量、性能或实现方式
提示：格式、风格或其他可选的小问题

默认聚焦真正影响行为、可靠性、兼容性、可维护性的发现；不要把纯风格意见堆成主要结论。

每条发现必须包含：

文件路径
行号
严重程度
四段式结构：
1. 严重程度：明确标注问题级别，并与实际影响一致
2. 问题：具体指出当前代码存在什么问题
3. 原因：解释为什么这是个问题，会带来什么风险或影响，并尽量说明它和仓库中哪段实现、哪条调用链、哪类已有约束相关
4. 怎么改：给出可执行的修改建议，必要时附代码示例

额外要求：

不要只复述 diff 表面现象；每条重要评论都应体现你查过周边上下文
如果问题来自“改动不完整”，说明还缺哪些文件、分支、调用点或测试
如果没有发现问题，要明确说出你检查过哪些关键上下文，而不是只说“LGTM”

Organize issues by severity:

Critical: Will cause bugs, security issues, or breaking changes
Suggestion: Suggest optimizing code quality, performance, or implementation methods
Hint: Formatting, style, or other optional minor issues

By default, focus on findings that truly affect behavior, reliability, compatibility, and maintainability; do not pile pure style opinions as main conclusions.

Each finding must include:

File path
Line number
Severity
Four-part structure:
1. Severity: Clearly mark the issue level, consistent with actual impact
2. Problem: Specifically point out what is wrong with the current code
3. Reason: Explain why this is a problem, what risks or impacts it will bring, and try to relate it to which implementation, call chain, or existing constraint in the repository
4. Fix: Provide executable modification suggestions, attach code examples if necessary

Additional requirements:

Do not only repeat the surface phenomenon of the diff; each important comment should reflect that you have checked the surrounding context
If the problem comes from "incomplete changes", explain which files, branches, call points, or tests are missing
If no issues are found, clearly state which key contexts you have checked instead of just saying "LGTM"

7. 先向用户展示审查结果

7. Show Review Results to the User First

在正式发布评论前，先将审查结果展示给用户：

markdown

undefined

Before officially publishing comments, present the review results to the user:

markdown

undefined

代码审查摘要

Code Review Summary

PR：标题
作者：@author
结论： [通过 / 请求修改]

PR: Title
Author: @author
Conclusion: [Approved / Request Changes]

发现的问题

Issues Found

🔴 严重问题（N 个）

🔴 Critical Issues (N)

文件：
```
path/to/file.py
```
（第 42 行）
- 严重程度：严重
- 问题：描述问题
- 原因：解释原因
- 怎么改：提供代码示例

File:
```
path/to/file.py
```
(Line 42)
- Severity: Critical
- Problem: Describe the issue
- Reason: Explain the reason
- Fix: Provide code examples

🟡 改进建议（N 个）

🟡 Improvement Suggestions (N)

...

🟢 细节建议（N 个）

🟢 Detail Suggestions (N)

...

总结

Summary

[给出清晰结论及其原因]


在摘要中，除了列问题，还应补一小段“审查覆盖面”，简述你看过的关键上下文，例如“检查了调用方 `A/B`、对照了基线实现 `C`、确认了测试 `D` 的覆盖情况”。

[Provide clear conclusion and its reasons]


In the summary, in addition to listing issues, add a short "Review Coverage" section to briefly describe the key contexts you have checked, e.g., "Checked callers `A/B`, compared baseline implementation `C`, confirmed test coverage of `D`".

8. 将评论发布到 PR（可选）

8. Publish Comments to the PR (Optional)

先询问用户：“是否要把这些发现作为逐行评论发布到 PR？”

如果用户确认，则创建评论 JSON 文件，并使用

scripts/post_pr_comment.py

发布：

bash

python scripts/post_pr_comment.py \
  --owner <OWNER> --repo <REPO> --pull-number <NUMBER> \
  --comments-file /tmp/pr_comments.json \
  --inline

评论正文示例（四段式）：

markdown

**严重程度：** 建议

**问题：** 代码中存在不规范的空格

**原因：** `node = int (node_str)` 不符合 PEP 8 规范，影响可读性

**怎么改：**
```python

First ask the user: "Do you want to publish these findings as line-by-line comments to the PR?"

If the user confirms, create a comment JSON file and use

scripts/post_pr_comment.py

to publish:

bash

python scripts/post_pr_comment.py \
  --owner <OWNER> --repo <REPO> --pull-number <NUMBER> \
  --comments-file /tmp/pr_comments.json \
  --inline

Example Comment Body (Four-part Structure):

markdown

**Severity:** Suggestion

**Problem:** There are inconsistent spaces in the code

**Reason:** `node = int (node_str)` does not comply with PEP 8 standards, affecting readability

**Fix:**
```python

修改前

Before modification

node = int (node_str)

修改后

After modification

node = int(node_str)

undefined

优先在

comments.json

中使用结构化字段：

severity

、

problem

、

reason

、

fix

。

scripts/post_pr_comment.py

会在发布前将这些字段统一整理为四段式 Markdown 正文，默认输出中文严重程度（

严重

、

建议

、

提示

），也会兼容旧版英文值和旧版三段式

body

内容。

node = int(node_str)

undefined

Prioritize using structured fields in

comments.json

severity

problem

reason

fix

scripts/post_pr_comment.py

will uniformly organize these fields into a four-part Markdown body before publishing, defaulting to Chinese severity values (

严重

建议

提示

), and also compatible with old English values and old three-part

body

content.

9. 清理临时目录

9. Clean Up Temporary Directory

审查完成后，清理临时仓库：

bash

rm -rf /tmp/gitcode-review-<REPO>-<TIMESTAMP>

After the review is completed, clean up the temporary repository:

bash

rm -rf /tmp/gitcode-review-<REPO>-<TIMESTAMP>

审查语气要求

Review Tone Requirements

保持建设性、专业、友好
解释清楚为什么需要修改
如果给出通过结论，要明确指出本次提交的价值
使用尊重式表达，避免命令式语气
所有发现都必须使用四段式结构
一条评论只聚焦一个问题，严重程度要和实际风险一致
行级评论尽量具体、可执行，避免只有结论没有修改方向
优先指出真正影响业务或系统行为的问题，少给脱离项目上下文的泛泛建议

Keep constructive, professional, and friendly
Clearly explain why modifications are needed
If giving an approval conclusion, clearly point out the value of this submission
Use respectful expressions, avoid imperative tone
All findings must use the four-part structure
Each comment focuses on only one issue, and the severity must match the actual risk
Line-level comments should be as specific and executable as possible, avoiding conclusions without modification directions
Prioritize pointing out issues that truly affect business or system behavior, and give fewer generic suggestions脱离项目上下文

审查底线

Review Bottom Lines

不要只基于 diff 下结论；diff 只是定位入口
不要为了凑数量输出低价值评论
不要忽略测试、配置、调用链和兼容性影响
不确定时先补代码搜索和上下文验证，再决定是否提出问题

Do not draw conclusions based only on diff; diff is just a positioning entry point
Do not output low-value comments just to meet quantity requirements
Do not ignore tests, configurations, call chains, and compatibility impacts
When uncertain, first supplement code search and context verification before deciding whether to raise an issue

脚本说明

Script Explanations

fetch_pr_info.py

用于从 GitCode API 获取 PR 信息。

bash

python scripts/fetch_pr_info.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  [--token TOKEN] \
  [--output-dir DIR] \
  [--include-comments]

Used to retrieve PR information from GitCode API.

bash

python scripts/fetch_pr_info.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  [--token TOKEN] \
  [--output-dir DIR] \
  [--include-comments]

post_pr_comment.py

用于向 GitCode PR 发布评论。

发布逐行行级评论：

bash

python scripts/post_pr_comment.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  --comments-file COMMENTS_JSON \
  --inline

发布整体审查结论：

bash

python scripts/post_pr_comment.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  --body "审查总结" \
  --review-event COMMENT|APPROVE|REQUEST_CHANGES

Used to publish comments to GitCode PRs.

Publish line-by-line comments:

bash

python scripts/post_pr_comment.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  --comments-file COMMENTS_JSON \
  --inline

Publish overall review conclusion:

bash

python scripts/post_pr_comment.py \
  --owner OWNER \
  --repo REPO \
  --pull-number NUMBER \
  --body "Review Summary" \
  --review-event COMMENT|APPROVE|REQUEST_CHANGES

setup_token.py

用于配置并验证 GitCode 访问令牌。

bash

undefined

Used to configure and verify GitCode access tokens.

bash

undefined

交互式配置

Interactive configuration

python scripts/setup_token.py

仅验证现有令牌

Only verify existing token

python scripts/setup_token.py --verify-only

undefined

python scripts/setup_token.py --verify-only

undefined

参考资料

Reference Materials

GitCode API 文档：见 references/gitcode_api.md
如需查看 API 细节，按需阅读对应参考文件

GitCode API Documentation: See references/gitcode_api.md
For API details, read the corresponding reference files as needed

技术说明

Technical Notes

API 版本

API Versions

GitCode 同时支持 v4（兼容 GitLab）和 v5（兼容 GitHub）两套 API：

v5 API：用于获取 PR 信息、文件列表和普通评论
- 基础地址：
```
https://api.gitcode.com/api/v5
```
- 认证方式：
```
PRIVATE-TOKEN
```
  请求头

v4 API：用于创建逐行行级评论

基础地址：
```
https://api.gitcode.com/api/v4
```
认证方式：
```
PRIVATE-TOKEN
```
请求头

接口：

POST /projects/{encoded_project}/merge_requests/{mr_iid}/discussions

GitCode supports two sets of APIs: v4 (compatible with GitLab) and v5 (compatible with GitHub):

v5 API: Used to retrieve PR information, file lists, and regular comments
- Base URL:
```
https://api.gitcode.com/api/v5
```
- Authentication:
```
PRIVATE-TOKEN
```
  request header

v4 API: Used to create line-by-line comments

Base URL:
```
https://api.gitcode.com/api/v4
```
Authentication:
```
PRIVATE-TOKEN
```
request header

Endpoint:

POST /projects/{encoded_project}/merge_requests/{mr_iid}/discussions

评论 JSON 格式

Comment JSON Format

json

[
  {
    "path": "relative/path/to/file.py",
    "line": 42,
    "severity": "严重",
    "problem": "描述问题",
    "reason": "解释为什么这是个问题",
    "fix": "给出修改建议",
    "side": "RIGHT"
  }
]

```
path
```
：相对仓库根目录的文件路径
```
line
```
：新文件中的行号
```
severity
```
：问题级别，建议使用
```
严重
```
、
```
建议
```
、
```
提示
```
；脚本兼容旧值
```
Critical
```
、
```
Improvement
```
、
```
Nitpick
```
```
problem
```
：当前代码具体有什么问题
```
reason
```
：为什么这是个问题，以及会产生什么影响
```
fix
```
：建议如何修改，可附带 Markdown 代码示例
```
body
```
：可选的旧版输入；如果提供，脚本会将其规范化为四段式
```
严重程度
```
、
```
问题
```
、
```
原因
```
、
```
怎么改
```
```
side
```
：
```
"RIGHT"
```
表示新代码，
```
"LEFT"
```
表示被删除的旧代码

json

[
  {
    "path": "relative/path/to/file.py",
    "line": 42,
    "severity": "严重",
    "problem": "Describe the issue",
    "reason": "Explain why this is an issue",
    "fix": "Provide modification suggestions",
    "side": "RIGHT"
  }
]

```
path
```
: File path relative to the repository root
```
line
```
: Line number in the new file
```
severity
```
: Issue level, recommended to use
```
严重
```
,
```
建议
```
,
```
提示
```
; the script is compatible with old values
```
Critical
```
,
```
Improvement
```
,
```
Nitpick
```
```
problem
```
: Specific issue with the current code
```
reason
```
: Why this is an issue and what impact it will have
```
fix
```
: Suggestions for modification, can include Markdown code examples
```
body
```
: Optional old-format input; if provided, the script will normalize it into the four-part structure of
```
Severity
```
,
```
Problem
```
,
```
Reason
```
,
```
Fix
```
```
side
```
:
```
"RIGHT"
```
indicates new code,
```
"LEFT"
```
indicates deleted old code