GitCode PR Comment Workflow

Workflow: PR Link → Fetch Review Comments → Understand User Approach → Design Document → Checkout Source Branch → Propose Changes → User Confirm → Apply & Push → Reply Unaddressed Comments

Prerequisites

gitcode CLI: GitCode CLI. Source: https://github.com/codeasier/gitcode-cli
git: Standard git CLI
GitCode Token: Stored in MEMORY.md or provided by user
Local repo: User must confirm the local repository path

CLI command name:

gitcode — full command name, works on all platforms (recommended on Windows)
gc — short alias, works on macOS/Linux (conflicts with PowerShell Get-Content on Windows)

gitcode CLI detection (follow this order):

Try gitcode --version first (recommended, works everywhere)
If not found, try gc --version (macOS/Linux fallback)
If neither found, ask user for the full path to the executable
If not installed, prompt to install from https://github.com/codeasier/gitcode-cli

gitcode CLI authentication check: After confirming the CLI is installed, try a lightweight command to verify authentication (e.g., gitcode pr view <number> --repo <owner>/<repo>). If it returns a token-related error, the CLI is not authenticated.

Stop and prompt the user to authenticate first:

gitcode auth login

Or if they have a token, use --with-token (not --token):

echo <your_token> | gitcode auth login --with-token

Windows note: If the CLI outputs emoji characters and throws UnicodeEncodeError: 'gbk' codec can't encode character, set the Python IO encoding before running CLI commands:

$env:PYTHONIOENCODING="utf-8"
gitcode pr view <number> --repo <owner>/<repo>

Do not proceed with the workflow until authentication is successful.

Windows note: On PowerShell, gc is an alias for Get-Content. Always use gitcode on Windows.

9-Step Workflow

Step 1: Parse PR Link & Fetch Info

Accept a PR URL from the user. The URL format is:

https://gitcode.com/<owner>/<repo>/pulls/<number>

Parse from the URL:

owner: Repository owner
repo: Repository name
number: PR number

Fetch PR details:

gitcode pr view <number> --repo <owner>/<repo>

Key info to extract:

PR title and description
Source branch (head): the branch being merged from
Target branch (base): the branch being merged into
Source repo/fork: which repo the source branch is from (may be a fork)
PR state (open/closed/merged)

⚠️ If the PR is closed or already merged, warn the user and stop.

Step 2: Fetch Review Comments

Fetch comments on the PR to identify review feedback:

gitcode pr view <number> --repo <owner>/<repo> --comments

Or use the GitCode API:

curl.exe -s "https://api.gitcode.com/api/v5/repos/<owner>/<repo>/pulls/<number>/comments?access_token=<token>"

Parse and categorize comments:

Review comments: Comments that contain critique, suggestions, or requested changes (look for keywords like "建议", "建议修改", "需要", "请修改", "review", "nit", "concern", "TODO", "FIXME", or inline file-level comments)
General comments: Conversational comments, approvals ("LGTM"), or status updates

Present to user:

Extract all review comments (the ones requesting changes)
For each review comment, show:
- Author and timestamp
- File path and line reference (if inline comment)
- Comment content
Summarize: total review comments found, how many require code changes

Save review comments to temp/pr_review_comments.json for reference:

{
  "pr": {
    "owner": "<owner>",
    "repo": "<repo>",
    "number": <number>,
    "source_branch": "<head_branch>",
    "target_branch": "<base_branch>",
    "source_repo": "<fork_owner>/<repo>"
  },
  "review_comments": [
    {
      "id": <comment_id>,
      "author": "<username>",
      "created_at": "<timestamp>",
      "path": "<file_path_or_null>",
      "line": <line_number_or_null>,
      "body": "<comment_text>",
      "requires_code_change": true
    }
  ]
}

Step 3: Understand & Challenge User's Modification Approach

If no review comments require code changes, summarize the comments and ask whether the user wants any non-code response; do not enter the modification workflow.

If one or more review comments require code changes, must stop here before checkout, file editing, or concrete implementation planning. Ask the user for their intended modification approach, then apply the essence of the understand-me workflow until the user explicitly confirms the approach.

Required conversation flow:

Restate the PR context and review comments in your own words.
Identify which comments require code changes and which are informational/nits.
Ask the user for their modification approach if they have not provided one.
Convert the PR comments + user's approach into a design decision tree:
- upstream decisions first: review intent, desired behavior, scope, compatibility, success criteria
- downstream decisions later: target modules/files, implementation strategy, tests, commit/push scope
- mark dependencies explicitly, e.g. depends on: D1
Ruthlessly but constructively interrogate the approach one branch at a time:
- ask exactly one question per turn
- for every question, provide your recommended answer and a short reason
- do not bundle multiple questions
- do not proceed while a dependency blocker is unresolved
If an answer can be found in the PR description, review comments, linked docs, or repository files already fetched/read, search/read those materials first instead of asking the user.
After each user answer, update the decision tree delta and ask the next highest-leverage single question.
Continue until the user explicitly confirms the modification approach (e.g. “确认”, “yes”, “按这个思路改”).

Suggested response shape during this step:

## 我的理解
<PR context + review comment summary + user's approach>

## 设计决策树（当前版本）
- D1: <review intent/scope>
  - A: ...
  - B: ...
- D2: <implementation direction>
  - depends on: D1
  - A: ...
  - B: ...

## 当前要拷问的问题
<one question only>

**我的推荐答案：** <recommended answer>
**推荐理由：** <brief reason>

Do not move to Step 4 until the approach is confirmed.

Step 4: Generate Design Document

Must generate a design document after the user confirms the modification approach and before any code modification.

Create a Markdown design document under temp/ first, for example:

temp/pr-<number>-review-comment-design.md

The design document must include:

PR summary: title, link, source/target branches, current intent.
Review comment summary: comments requiring code changes, comments not requiring code changes, file/line references.
Confirmed modification approach: the final user-confirmed direction from Step 3.
Design decision tree: resolved decisions, rejected branches, and remaining assumptions.
Affected scope: expected modules/files/components to inspect or modify.
Implementation plan: ordered, minimal change steps.
Compatibility and risk analysis: behavior changes, edge cases, regression risk.
Validation plan: tests, commands, manual checks, screenshots if needed.
Non-goals: explicitly list what will not be changed in this PR update.

After writing the document:

Show the design document path and a concise summary to the user.
Ask the user to confirm the design document.
If the user requests changes, revise the document and ask again.
Do not inspect/modify target code for implementation beyond what is necessary to draft the design unless the user confirms.

Do not move to Step 5 until the design document is confirmed.

Step 5: Confirm Local Repository & Checkout Source Branch

Must confirm with user before proceeding:

Ask user for the local repository path (or confirm if already known)
Verify the repo exists:

cd <repo_path>
git status
git log --oneline -3

Add the source repo as a remote (if it's a fork and not already added):

# Check if remote already exists
git remote -v

# Add remote for the source fork if needed
git remote add <source_remote_name> <source_repo_url>
# or if it already exists, just fetch
git fetch <source_remote_name>

Checkout the PR's source branch:

# Create/check out the local tracking branch
git checkout -b <local_branch_name> <source_remote_name>/<source_branch>
# Or if already exists locally:
git checkout <local_branch_name>
git pull <source_remote_name> <source_branch>

⚠️ Important:

If the working tree is dirty, stash first (git stash) and warn the user
Pull latest from the source branch to ensure we're on the current code
Verify the branch is correct: git log --oneline -3 should show PR-related commits

Pull latest code to ensure we're up to date:

git pull <source_remote_name> <source_branch>

Step 6: Read Files & Propose Changes

For each review comment that requires code changes:

Read the relevant file(s) using the read tool
Locate the problematic code referenced by the comment
Propose a modification plan

Present the modification plan to the user:

For each review comment:

## 检视意见 #N

**Reviewer**: <author>
**文件**: <file_path>
**行号**: L<line>
**意见**: <original comment text>

### 修改方案

**修改文件**: <file_path>
**修改位置**: L<start>-L<end>
**修改方式**: <description of the change>

```diff
- <old code>
+ <new code>

理由: <explanation of how this addresses the review comment>


**Group related changes** if multiple comments affect the same file.

**Wait for user confirmation before proceeding.** If the user requests adjustments, revise the plan and re-present.

**⚠️ External write constraint:** All file modifications require explicit user approval. Show the complete plan first, then ask: "是否确认按以上方案进行修改？(yes/no)"

Step 7: Apply Changes

After user approval:

Apply each change using the edit tool:

# Use edit tool for precise replacements
edit <file_path> oldText -> newText

Verify changes:

cd <repo_path>
git diff

Show the complete diff to the user for final confirmation before committing.

Step 8: Commit & Push to Source Branch

8.1 Commit

Commit message format: [type]([module]): address review comments

Use a descriptive type:

fix: Bug fixes from review
refactor: Code structure improvements
style: Formatting/style changes
docs: Documentation updates

git add <changed_files>
git commit -m "<type>(<module>): address review comments on PR #<number>"

For multiple distinct changes, consider separate commits per logical change.

8.2 Push

⚠️ Must confirm the push remote with the user.

# Show available remotes
git remote -v

# Push to the source branch
git push <source_remote_name> HEAD:<source_branch>

Important:

Push to the same branch that the PR is based on
If the user's fork is the source, push to their fork remote
If the user has write access to the upstream repo, they may push directly

8.3 Confirm & Report

After push, present a summary:

| Item | Value | |:---|:---| | PR URL | https://gitcode.com/<owner>/<repo>/pulls/<number> | | PR Number | #<number> | | Source Branch | <source_branch> | | Target Branch | <target_branch> | | Files Changed | <count> | | Review Comments Addressed | <count> | | Status | Changes pushed |

Optionally, post a comment on the PR acknowledging the review and confirming changes:

感谢审查！已根据检视意见修改并推送到源分支。

修改内容：
- <summary of change 1>
- <summary of change 2>

⚠️ Posting PR comments requires user confirmation before executing.

Step 9: Reply to Unaddressed Review Comments

After pushing code changes, identify review comments that were not addressed in this round (skipped, deferred, or out of scope) and reply to them on the PR to close the loop.

9.1 Identify Unaddressed Comments

From the review comments collected in Step 2, identify comments that:

Were not modified in the code changes (Steps 6-7)
Were not already resolved/closed by the reviewer
Were not already replied to by the PR author

Cross-reference with the design document's "Non-goals" section and the user's confirmed modification scope.

9.2 Ask User for Confirmation

Present the list of unaddressed comments to the user:

## 未修改的检视意见

| # | 严重度 | 文件 | 意见摘要 | 建议回复 |
|---|--------|------|----------|----------|
| 8 | 建议 | interface.ts | status 移除 \| string | 暂不修改，后续单独处理 |
| 14 | 建议 | KernelE2ETimeTable.tsx | rowClassName 性能优化 | 暂不修改，建议级优化后续单独处理 |
| ... | ... | ... | ... | ... |

是否需要回复这些检视意见？

Ask the user:

Whether to reply to unaddressed comments
If yes, whether to use the suggested replies or customize them
For each comment, the user may provide a different reply text

⚠️ Must get user confirmation before posting any replies.

9.3 Reply via GitCode API

Use the Reply to PR Comment API to post replies within each comment's discussion thread.

Get the access token from gitcode CLI config:

TOKEN=$(python -c "from gitcode_cli.config import get_token; print(get_token())")

Reply to a comment using its discussion_id (obtained from Step 2's API response):

# Write body to file to avoid encoding issues on Windows
echo '{"body": "<reply text>"}' > /tmp/reply_body.json

curl -s -X POST \
  "https://api.gitcode.com/api/v5/repos/<owner>/<repo>/pulls/<number>/discussions/<discussion_id>/comments?access_token=${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/reply_body.json

Batch reply example (same reply for multiple comments):

TOKEN=$(python -c "from gitcode_cli.config import get_token; print(get_token())")
echo '{"body": "暂不修改，建议级优化后续单独处理。"}' > /tmp/reply_body.json

for did in "<discussion_id_1>" "<discussion_id_2>" "<discussion_id_3>"; do
  curl -s -X POST \
    "https://api.gitcode.com/api/v5/repos/<owner>/<repo>/pulls/<number>/discussions/${did}/comments?access_token=${TOKEN}" \
    -H "Content-Type: application/json" \
    -d @/tmp/reply_body.json
done

⚠️ Notes:

The discussion_id comes from the GET /repos/{owner}/{repo}/pulls/{number}/comments API response's discussion_id field
On Windows, always write JSON body to a file first and use -d @file.json to avoid encoding issues with non-ASCII characters
Each reply is posted within the existing discussion thread, keeping the conversation context
Clean up temp files after replying: rm -f /tmp/reply_body.json

9.4 Confirm & Report

After replying, present a summary:

| # | 检视意见 | discussion_id | 回复内容 | note_id | |---|----------|---------------|----------|---------| | 8 | status | string | 92909e71... | 暂不修改，后续单独处理 | 173582636 | | ... | ... | ... | ... | ... |

Total: N unaddressed comments replied.

Key Constraints

Safety Rules

Never push to the wrong branch — always verify the source branch before pushing
Never modify files without user approval — always show proposed changes first
Never assume repository paths — always confirm with user
Never assume push remote — always list remotes and ask user to choose
All external write operations require explicit user confirmation

Git Workflow Rules

Always pull latest from source branch before making changes
Stash dirty working trees before checking out
Commit messages must be descriptive and reference the PR number
Always verify changes with git diff before committing

Asking vs Doing

| Action | Ask First? | |:---|:---| | Parse PR URL, fetch PR info | ❌ Just do it | | Fetch review comments | ❌ Just do it | | Confirm local repo path | ✅ Must confirm | | Checkout source branch | ✅ Confirm branch name | | Ask/challenge modification approach | ✅ Required if comments need code changes | | Generate design document | ✅ Required before code modification | | Confirm design document | ✅ Required before code modification | | Read files, analyze code | ❌ Just do it after design confirmation | | Propose changes | ❌ Present plan | | Modify files | ✅ Wait for approval | | Commit changes | ✅ Show commit message | | Push to remote | ✅ Confirm remote and branch | | Post PR comment | ✅ Always confirm | | Reply to unaddressed review comments | ✅ Always confirm |

Temp File Management

All temporary files generated during the workflow must be stored in temp/ directory under the workspace:

workspace/temp/
├── pr_review_comments.json              # Downloaded review comments
├── pr-<number>-review-comment-design.md # Confirmed design document
├── *.md                                 # Review notes
└── *                                    # Other temp files

⚠️ Clean up temp/ directory after workflow completion:

Remove-Item -Recurse -Force temp/  # Windows
rm -rf temp/                        # Linux/macOS

GitCode API Reference (PR Comments)

See references/gitcode-api.md for full API reference.

Get PR Comments

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

Post PR Comment

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

Body:

{
  "body": "<comment text (markdown)>",
  "commit_id": "<commit_sha>",
  "path": "<file_path>",
  "position": <line_number>
}

Get PR Diff

GET https://gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/diff

Headers:

Authorization: Bearer <token>

Note: Diff endpoint uses gitcode.com not api.gitcode.com.

Reply to PR Comment

Reply to an existing PR review comment within its discussion thread.

POST https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{number}/discussions/{discussion_id}/comments?access_token=<token>