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):

1. Try gitcode --version first (recommended, works everywhere)
2. If not found, try gc --version (macOS/Linux fallback)
3. If neither found, ask user for the full path to the executable
4. 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:

bash

gitcode auth login

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

bash

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:

powershell

$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:

text

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

Parse from the URL:

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

Fetch PR details:

bash

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:

bash

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

Or use the GitCode API:

bash

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:

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

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

json

{
  "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:

1. Restate the PR context and review comments in your own words.

2. Identify which comments require code changes and which are informational/nits.

3. Ask the user for their modification approach if they have not provided one.

4. 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

5. 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

6. 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.

7. After each user answer, update the decision tree delta and ask the next highest-leverage single question.

8. Continue until the user explicitly confirms the modification approach (e.g. “确认”, “yes”, “按这个思路改”).

Suggested response shape during this step:

markdown

## 我的理解
<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:

text

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

The design document must include:

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

After writing the document:

1. Show the design document path and a concise summary to the user.
2. Ask the user to confirm the design document.
3. If the user requests changes, revise the document and ask again.
4. 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:

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

bash

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

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

bash

# 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>

1. Checkout the PR's source branch:

bash

# 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

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

bash

git pull <source_remote_name> <source_branch>

Step 6: Read Files & Propose Changes#

For each review comment that requires code changes:

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

Present the modification plan to the user:

For each review comment:

text

## 检视意见 #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>

理由:

text

**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:

1. Apply each change using the edit tool:

bash

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

1. Verify changes:

bash

cd <repo_path>
git diff

1. 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

bash

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.

bash

# 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:

ItemValuePR URLhttps://gitcode.com/<owner>/<repo>/pulls/<number>PR Number#<number>Source Branch<source_branch>Target Branch<target_branch>Files Changed<count>Review Comments Addressed<count>StatusChanges pushed

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

markdown

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

修改内容：
- <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:

text

## 未修改的检视意见

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

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

Ask the user:

1. Whether to reply to unaddressed comments
2. If yes, whether to use the suggested replies or customize them
3. 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:

bash

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):

bash

# 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):

bash

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_id8status | string92909e71...暂不修改，后续单独处理173582636...............

Total: N unaddressed comments replied.

Key Constraints#

Safety Rules#

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

Git Workflow Rules#

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

Asking vs Doing#

ActionAsk First?Parse PR URL, fetch PR info❌ Just do itFetch review comments❌ Just do itConfirm local repo path✅ Must confirmCheckout source branch✅ Confirm branch nameAsk/challenge modification approach✅ Required if comments need code changesGenerate design document✅ Required before code modificationConfirm design document✅ Required before code modificationRead files, analyze code❌ Just do it after design confirmationPropose changes❌ Present planModify files✅ Wait for approvalCommit changes✅ Show commit messagePush to remote✅ Confirm remote and branchPost PR comment✅ Always confirmReply 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:

text

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:

bash

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#

text

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

Post PR Comment#

text

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

Body:

json

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

Get PR Diff#

text

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

Headers:

text

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.

text

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

Body:

json

{
  "body": "<reply text (markdown)>"
}

The discussion_id is obtained from the GET /repos/{owner}/{repo}/pulls/{number}/comments response's discussion_id field.

PowerShell Notes#

• Use ; to chain commands (not &&)
• Use curl.exe (not curl which aliases to Invoke-WebRequest)
• For JSON payloads, write to file first then use -d @file.json to avoid escaping issues
• Remove temp files: Remove-Item -Recurse -Force temp/