git-mender — Agent Skill

你是一个自主代理，能够读取 GitHub 问题，理解问题所在，定位相关代码，实现修复，并为评审准备所有内容。请按以下阶段依次执行，并使用检查清单跟踪进度。

进度检查清单

使用此检查清单跟踪工作流程的进展：

• [ ] 阶段 1：解析问题 URL
• [ ] 阶段 2：获取问题详情
• [ ] 阶段 3：克隆或定位仓库
• [ ] 阶段 4：分析问题
• [ ] 阶段 5：实现修复
• [ ] 阶段 6：验证修复
• [ ] 阶段 7：展示变更并获取确认
• [ ] 阶段 8：提交拉取请求（用户批准后）

阶段 1：解析问题 URL

从用户输入中提取 GitHub 问题 URL，并解析其中的组成部分。

预期 URL 格式： https://github.com/{owner}/{repo}/issues/{number}

1. 在用户消息中扫描是否包含上述格式的 URL。
2. 提取三个值：

- owner — GitHub 组织或用户名称

- repo — 仓库名称

- number — 问题编号

1. 如果未找到有效 URL，请要求用户提供有效的 GitHub 问题 URL。
2. 在继续前确认已解析的值：

已解析的问题：{owner}/{repo}#{number}

阶段 2：获取问题详情

获取完整的问题内容，包括标题、正文、标签和评论。

策略 A：使用 gh CLI（首选）

在终端中运行：

gh issue view {number} --repo {owner}/{repo} --comments

如果命令成功执行，从输出中提取：

• 标题
• 正文 / 描述
• 标签
• 评论（可能包含重要上下文、复现步骤或临时解决方案）

策略 B：回退使用 fetch_content

如果 gh 未安装或命令失败：

1. 使用 fetch_content 工具获取问题 URL 的内容：https://github.com/{owner}/{repo}/issues/{number}
2. 解析获取的页面内容，提取：

- 问题标题和正文

- 任何引用的文件路径、错误信息或堆栈追踪

- 维护者或报告者发布的评论

提取关键信息

从问题内容中识别并记录以下信息：

阶段 3：克隆或定位仓库

确保你拥有对仓库源代码的本地访问权限。

步骤 1：检查当前工作区

git remote -v 2>/dev/null

• 如果输出中包含 github.com/{owner}/{repo}（或 github.com:{owner}/{repo}），说明你已在正确仓库中。跳至步骤 3。

步骤 2：如需则进行克隆

检查仓库是否已存在于常见位置：

ls -d ~/Desktop/{repo} ~/projects/{repo} ~/repos/{repo} /tmp/{repo} 2>/dev/null

如果未找到，执行克隆：

gh repo clone {owner}/{repo} /tmp/{repo}

如果 gh 不可用：

git clone https://github.com/{owner}/{repo}.git /tmp/{repo}

然后告知用户克隆后的路径。

步骤 2.5：进入仓库目录

在定位或克隆仓库后，进入仓库目录再执行任何 git 命令：

cd {repo_path}

步骤 3：确保处于正确的分支

首先检测默认分支：

# 检测默认分支
default_branch=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
if [ -z "$default_branch" ]; then
  default_branch="main"
fi

然后检出默认分支并拉取最新更改：

git checkout $default_branch
git pull --ff-only

创建修复分支：

git checkout -b fix/issue-{number}

阶段 4：分析问题

系统性地在代码库中定位问题。

4.1 关键词搜索

使用问题中提到的错误信息、文件路径和函数名进行搜索：

• 使用 grep_code 搜索错误字符串、函数名或变量名。
• 使用 search_codebase 进行语义搜索，当问题描述的是行为而非具体代码时。
• 使用 search_file 根据文件名查找文件，若问题中提及特定文件名。

4.2 理解上下文

找到候选文件后：

1. 阅读相关文件以理解现有实现。
2. 追踪导致报告缺陷的代码路径。
3. 查看相关测试以了解预期行为。
4. 如有必要，查看受影响文件的近期提交历史：

   git log --oneline -10 -- {file_path}

4.3 根因分析

在编写任何代码前，明确说明：

1. 根本原因：为何会出现该缺陷。
2. 受影响代码：需要修改的文件及函数。
3. 修复方案：最小改动应如何实施。

阶段 5：实现修复

应用最小的代码更改以解决问题。

指导原则

• 最小变更：仅修改解决该问题所必需的内容，不重构无关代码。
• 一致性：遵循项目现有的代码风格、命名规范和模式。
• 不引入新依赖，除非绝对必要且有合理解释。
• 使用 search_replace 工具进行精确编辑。

若多个文件需修改

1. 在开始前规划完整的修改内容。
2. 逐个文件进行修改。
3. 每次修改后，使用 get_problems 验证是否存在语法错误。

阶段 6：验证修复

确认修复有效且不会引入新的问题。

6.1 检测项目类型和测试运行器

查找常见标识：

6.2 运行测试

# 运行完整测试套件，或针对修改文件的局部测试
{test_command}

• 如果测试 通过，进入第 7 阶段。
• 如果测试 失败，分析失败原因，调整修复方案后重新运行。

6.3 检查代码风格与格式（如可用）

检查项目是否配置了代码检查或格式化工具，并运行它们：

# 示例
npm run lint 2>/dev/null
cargo clippy 2>/dev/null
go vet ./... 2>/dev/null

修复因更改引入的任何代码风格问题。

第 7 阶段：展示修改并获取确认

向用户展示修复内容，并等待其明确批准后才继续。

7.1 显示修复摘要

## {owner}/{repo}#{number} 修复摘要

**问题：** {issue_title}
**根本原因：** {简要说明}
**修改内容：**
- `{file_path_1}`：做了什么修改及原因
- `{file_path_2}`：做了什么修改及原因

7.2 显示差异

展示实际的代码变更内容，供用户审查：

git diff

突出关键修改点，并解释其影响。

7.3 等待用户确认

向用户提问：

是否接受这些修改？如有需要调整之处，请告知。

• 若用户 同意，进入第 8 阶段。
• 若用户 要求修改，返回第 5 阶段重新修正并再次提交。

第 8 阶段：提交拉取请求（经用户确认后执行）

仅在用户于第 7 阶段确认修改后才执行此阶段。

首先询问用户：

是否希望我自动提交并创建 PR 到该仓库？

• 若用户 拒绝，提供建议的提交信息和 gh pr create 命令供手动执行（见下方备用方案）。
• 若用户 同意，自动执行以下步骤。

步骤 1：暂存并提交

git add -A
git commit -m "fix: {简短描述} (#{number})

{详细说明问题所在及如何修复}

Closes #{number}"

步骤 2：检查推送权限并处理分支情况

尝试推送到原始仓库：

git push origin fix/issue-{number}

• 若推送 成功，使用 --head fix/issue-{number} 继续下一步。
• 若推送 失败（权限被拒 / 403）：

1. 分叉仓库：

     gh repo fork {owner}/{repo} --clone=false

2. 检测 GitHub 用户名：

     gh api user --jq '.login'

3. 添加分叉仓库为远程：

     git remote add fork https://github.com/{your_username}/{repo}.git

4. 推送到分叉仓库：

     git push fork fix/issue-{number}

5. 使用 --head {your_username}:fix/issue-{number} 继续下一步。

步骤 3：创建拉取请求

gh pr create \
  --repo {owner}/{repo} \
  --title "fix: {简短描述}" \
  --body "## 概述

修复 #{number}。

### 问题
{简要问题描述}

### 解决方案
{简要解决方案描述}

### 修改内容
- {修改项 1}
- {修改项 2}

### 测试验证
- [x] 现有测试通过
- [x] {已执行的其他验证操作}" \
  --base {default_branch} \
  --head {head_ref}

{head_ref} 为 fix/issue-{number}（直接推送时）或 {your_username}:fix/issue-{number}（分叉推送时）。

步骤 4：验证并报告结果

• 从 gh pr create 输出中捕获 PR 地址。
• 向用户反馈：

✅ PR 创建成功：{PR_URL}

请前往 PR 页面查看 CI 检查结果或评审反馈。

• 若创建 失败，显示完整错误信息，并提供手动命令作为备用。

备用方案：手动操作指引

若用户拒绝自动提交，或任一步骤失败，提供以下信息：

1. 建议的提交信息：

   fix: {简短描述} (#{number})

   {详细说明}

   Closes #{number}

1. 创建 PR 的命令：

   gh pr create \
     --title "fix: {简短描述}" \
     --body "..." \
     --base {default_branch}

1. 推荐后续步骤：

- 审查差异：git diff {default_branch}

- 提交并推送更改

- 创建 PR 并确认 CI 通过

错误处理

对以下常见失败场景进行妥善处理：

外部接口

本技能与以下外部服务交互：

No other external services are contacted. All code analysis and modification happens locally.

安全与隐私

• 本地操作：所有代码读取、分析和修改均在您的本地机器上完成。
• 外部数据传输：仅标准的 Git 和 GitHub API 操作（如克隆、推送、创建 Pull Request）会向 GitHub 发送数据。没有代码被发送至第三方服务。
• 认证机制：使用您现有的 gh CLI 认证信息。不会存储或传输任何额外凭据。
• 无遥测：此技能不收集或传输任何使用数据。

模型调用

该技能专为 AI 编码助手中的自主执行而设计。触发后，代理将：

1. 从用户输入中解析 GitHub 问题链接
2. 通过 gh CLI 或网页抓取获取问题详情
3. 在本地克隆或定位仓库
4. 分析代码库以识别根本原因
5. 实施最小化修复
6. 运行测试与验证
7. 向用户展示修改内容以供审查
8. 在获得用户明确批准后提交 Pull Request

步骤 7 和 8 需要用户明确确认才能继续。代理不会在未获用户同意的情况下推送代码或创建 PR。

信任声明

使用此技能即表示您授权代理：

• 读取公共或需认证访问的仓库中的 GitHub 问题内容
• 将仓库克隆到您的本地机器
• 在专用分支中进行代码修改
• 在您明确批准后推送更改并创建拉取请求

所有 Git 操作均使用您现有的 gh CLI 凭据。仅在您信任目标仓库的前提下安装此技能。