gitcode-pr-comment

name	gitcode-pr-comment
description	GitCode Pull Request 评论处理技能。当用户提到"处理PR评论"、"修复评论问题"、"回复评论"、"验证评论有效性"、"查看评论内容"、或提供PR URL询问评论问题时触发。自动获取评论、分析有效性、辅助修复并线程式回复。支持仓库缓存、工作区保护、批量修复。

GitCode PR Comment

对 GitCode 平台的 Pull Request 评论进行自动化处理：获取评论 → 分析有效性 → 辅助修复 → 回复评论。

使用前提

• GitCode access_token（获取评论和发布回复）
• 本地 Git 环境
• Python3 + requests 库

输入参数

参数	说明	必填	示例
PR URL	GitCode PR 链接	是	https://gitcode.com/owner/repo/pulls/3
Token	GitCode 个人访问令牌	是	<your-token>
本地仓库	已有的仓库目录（可选）	否	/path/to/repo

提供 PR URL 可自动提取 owner/repo/number，无需单独提供。

快速流程概览

步骤 0: 解析输入 → 获取/克隆本地仓库
步骤 1: 准备环境 → 记录分支、保护工作区
步骤 2: 获取信息 → PR 基本信息、文件变更、权限检查
步骤 3: 获取评论 → 所有评论、讨论ID
步骤 4: 切换分支 → checkout PR 源分支（需权限）
步骤 5: 分析有效性 → 验证问题是否真实存在
步骤 5.5: 方案设计 → Plan 子 agent 深度设计修复方案（新增）
步骤 5.6: 方案确认 → 展示方案汇总，用户审核确认（新增）
步骤 6: 问题修复 → 按确认方案逐个修复
步骤 7: 提交更新 → 单次提交所有修复（需权限）
步骤 8: 回复评论 → 线程式回复 + 总结
步骤 9: 清理恢复 → 切换回原分支、恢复 stash

权限检查（重要）

步骤 2 获取 PR 信息后，必须检查用户是否有修改权限：

## 权限检查结果

| 检查项 | 结果 | 说明 |
|--------|------|------|
| PR 作者 | `<pr_author>` | PR 创建者 |
| 当前用户 | `<token_user>` | Token 对应用户 |
| 是否本人 | ✅/❌ | PR 作者 == 当前用户 |

处理规则：

• ✅ 本人 PR → 正常执行修复流程（步骤 3-9）
• ❌ 非本人 PR → 输出提醒信息，流程终止

非本人 PR 提醒信息：

❌ 权限不足：此 PR 由 <pr_author> 创建，您无权修改其代码。

建议操作：
- 如需处理评论问题，请联系 PR 作者
- 或等待 PR 作者自行处理

流程已终止。

重要：非本人 PR 无法 push 到源分支，不执行后续修复步骤。

进度指示

执行过程中，每完成一步输出进度提示：

✅ 步骤 0/9 完成: 解析输入并获取本地仓库
✅ 步骤 1/9 完成: 准备工作环境
✅ 步骤 2/9 完成: 获取 PR 信息 [权限: ✅ 本人]
✅ 步骤 3/9 完成: 获取 PR 评论 (5 条)
✅ 步骤 4/9 完成: 切换到 PR 分支
✅ 步骤 5/9 完成: 分析评论有效性 (3 个有效问题)
✅ 步骤 5.5/9 完成: 修复方案设计 (Plan 子 agent)
✅ 步骤 5.6/9 完成: 方案确认 (用户已审核)
✅ 步骤 6/9 完成: 问题修复 (修复了 3 个问题)
✅ 步骤 7/9 完成: 提交修复更新 (SHA: b7da6d8)
✅ 步骤 8/9 完成: 回复评论说明已修复
✅ 步骤 9/9 完成: 清理和恢复

非本人 PR 的进度输出：

✅ 步骤 0/9 完成: 解析输入并获取本地仓库
✅ 步骤 1/9 完成: 准备工作环境
✅ 步骤 2/9 完成: 获取 PR 信息 [权限: ❌ 非本人]
⏹️ 流程终止: 非 PR 作者，无修改权限

进度格式：✅ 步骤 N/9 完成: <步骤名称> [<关键数据>]

关键数据示例：

• 步骤 2：权限检查结果（本人/非本人）
• 步骤 3：评论数量
• 步骤 5：有效问题数量
• 步骤 5.5：方案设计方式（Plan 子 agent）
• 步骤 5.6：确认状态（用户已审核/采用所有方案）
• 步骤 6：修复数量
• 步骤 7：提交 SHA

核心命令速查

# 获取本地仓库（自动缓存）
python scripts/repo_cache.py --get "https://gitcode.com/<owner>/<repo>.git" --owner <owner> --repo <repo>

# 获取 PR 信息
python scripts/get_pr_info.py <token> <owner> <repo> <pr_number> --json

# 获取 PR 评论（分析格式）
python scripts/get_pr_comments.py <token> <owner> <repo> <pr_number> --analysis

# 回复评论（线程式，使用 discussion_id）
python scripts/post_comment_reply.py <token> <owner> <repo> <pr_number> \
  --detailed-replies '{"discussion_id": "修复说明"}'

# 发布修复总结
python scripts/post_comment_reply.py <token> <owner> <repo> <pr_number> \
  --summary --commit-sha <sha> --fixed-issues "问题列表"

关键概念

discussion_id vs comment_id

字段	格式	用途
discussion_id	长字符串 b66f1e2e...	线程式回复（推荐）
comment_id	数字 165980011	简单回复

使用 discussion_id 回复会显示在原评论下方，便于追踪。

仓库缓存

自动管理仓库 URL 与本地路径的对应关系：

• 缓存位置：memory/repo_cache.json
• 默认克隆目录：~/gitcode_repos/<owner>_<repo>/
• 自动验证路径有效性

步骤 5：分析有效性（关键步骤）

⚠️ 核心原则：必须读取实际代码验证问题是否存在，绝不依赖 commit message 判断！

为什么不能信任 commit message

判断方式	问题
根据 commit message "fix: 修复安全问题"	❌ 可能只是部分修复、修复方式不当、甚至未真正修复
读取实际代码文件验证	✅ 确认问题是否真实存在、是否已正确修复

代码验证流程

步骤 5.1：读取评论引用的文件

# 必须读取评论中提到的文件
Read: <repo_path>/<文件路径>

步骤 5.2：对比评论引用的代码与实际代码

## 代码验证结果

| 评论序号 | 评论引用代码 | 实际代码（当前行） | 验证状态 |
|----------|--------------|-------------------|----------|
| 1 | `let key = "default_key"` | `let key = Env.get("KEY") ?? "default"` | ⚠️ 部分修复（仍有默认值） |
| 2 | `let iv = "fixed_iv"` | `let iv = "fixed_iv"` | ❌ 未修复 |
| 3 | `return None` (死代码) | `return None` | ❌ 未修复 |

步骤 5.3：输出分析报告

## 评论分析报告

### 有效问题（需要处理）
| 序号 | 讨论ID | 文件 | 行号 | 问题类型 | 问题描述 | 验证结果 |
|------|--------|------|------|----------|----------|----------|
| 1 | b66f1e2e... | src/file.cj | 10 | 🔴 高风险 | 硬编码密钥 | ✅ 确认存在 |

### 已修复问题（可回复说明）
| 序号 | 讨论ID | 文件 | 问题 | 实际修复方式 |
|------|--------|------|------|--------------|
| 1 | a1b2c3d... | src/file.cj | 死代码 | 已删除第 43 行 |

### 非问题评论（无需处理）
| 评论内容 | 非问题原因 |
|----------|------------|
| "代码不错" | 无实质问题 |

### 待确认评论
| 评论内容 | 需用户确认原因 |
|----------|----------------|
| "建议重构" | 涉及设计决策 |

重要：验证结果必须基于实际代码内容，而非 git history 或 commit message。

分析报告格式（旧版，仅供参考）

步骤 5 输出标准分析报告：

## 评论分析报告

### 有效问题（需要处理）
| 序号 | 讨论ID | 文件 | 行号 | 问题类型 | 问题描述 | 验证结果 |
|------|--------|------|------|----------|----------|----------|
| 1 | b66f1e2e... | src/file.cj | 10 | 🔴 高风险 | 硬编码密钥 | ✅ 确认存在 |

### 非问题评论（无需处理）
| 评论内容 | 非问题原因 |
|----------|------------|
| "代码不错" | 无实质问题 |

### 待确认评论
| 评论内容 | 需用户确认原因 |
|----------|----------------|
| "建议重构" | 涉及设计决策 |

修复方案设计（步骤 5.5）- 必须严格执行

⚠️ 强制要求：步骤 5.5 必须使用 Plan 子 agent 设计方案，不可跳过或简化！

为什么必须使用子 agent

对比项	主 agent 直接设计（错误做法）	Plan 子 agent 设计（正确做法）
思考深度	快速提出方案，可能不完整	深度分析根因，全面考虑
方案数量	通常只提一个	多个备选方案对比
安全评估	可能忽略安全影响	系统评估安全风险
影响范围	可能遗漏相关模块	全面考虑副作用

正确执行方式

使用 Agent 工具启动 Plan 子 agent：

Agent 工具调用（必须执行）：
- subagent_type: "Plan"
- description: "设计 PR 评论问题修复方案"
- prompt: 包含问题列表、代码上下文、设计要求

子 agent 输出格式

对每个问题输出：

• 根因分析 - 问题产生的根本原因
• 方案选项 - 至少 2 个备选方案（含代码示例）
• 推荐方案 - 最佳方案 + 理由说明
• 影响范围 - 相关模块和文档更新需求

重要：不执行步骤 5.5 的 Plan 子 agent 设计，视为流程错误！

修复方案确认（步骤 5.6）

展示 Plan 子 agent 设计的方案，让用户审核确认。

方案汇总展示

## 修复方案汇总

### 问题 #1: 硬编码加密密钥
推荐方案: 环境变量 + 强制配置
修复说明: 未设置环境变量时抛出异常

### 问题 #2: IV 硬编码
推荐方案: 随机 IV + 与密文一起存储
修复说明: 每次加密生成随机 IV，解密时从数据中提取

用户确认选项

使用 AskUserQuestion 提供以下选项：

• 采用所有推荐方案 - 批量确认，直接执行修复
• 逐个审核方案 - 每个问题单独展示详细方案，逐个确认
• 查看方案详情 - 展示完整的方案设计输出（含根因分析、方案对比）
• 我有其他修改方案 - 用户提供自定义修复代码

重要：用户确认后才执行修复，不自动修改代码。

注意事项

• 权限检查必须：步骤 2 后检查用户是否为 PR 作者，非本人无法修改代码
• 必须记录 discussion_id：用于后续线程式回复
• 修复需用户确认：不自动修改代码
• 单次提交所有修复：commit message 包含详细修复列表
• 必须回复每个修复的评论：使用 --detailed-replies
• 保护用户工作区：自动 stash，完成后恢复
• 使用 git -C "$REPO_DIR"：命令指定仓库路径
• ⚠️ 代码验证必须：步骤 5 必须读取实际代码文件验证问题存在，绝不依赖 commit message 判断修复状态
• ⚠️ Plan 子 agent 必须执行：步骤 5.5 不可跳过，必须使用 Plan 子 agent 设计方案，不允许主 agent 直接提出修复方案

详细文档索引

需要更多细节时，阅读以下 reference 文件：

文件	内容	使用场景
workflow.md	完整工作流程、变量管理、异常处理	执行中遇到问题
scripts.md	脚本详细参数和使用示例	需要特定脚本用法
examples.md	端到端执行示例	了解完整流程

与其他技能的关系

• 可调用 gitcode-api-helper 技能查询 GitCode API 信息
• 与 gitcode-pr-review 技能互补：review 发起审查，comment 处理审查反馈