# 使用智能体整理并提交 GitHub Issue

MOI 智能体可以连接用户自己的 GitHub，将对话中的问题描述整理为结构清晰的 Issue，并在用户确认后直接提交到指定仓库。通过为智能体限定目标仓库和操作规则，可以把零散反馈转化为可追踪的研发任务，同时减少手动复制和整理内容的工作。

本教程以一个公开仓库为例，演示如何先在对话中绑定自己的 GitHub，再创建专用智能体，并把一条真实问题反馈整理成 Issue。请将文中的 `YOUR_GITHUB_USERNAME/your-repository` 替换为自己拥有 Issue 创建权限的仓库；也可以先 Fork 一个公开仓库再使用。整个操作预计约 15 分钟。

## 你将完成什么

- 在对话中绑定自己的 GitHub，并选择自己有权限的仓库；
- 用自然语言创建一个 GitHub Issue 提交助手；
- 让智能体先生成 Issue 草稿，再在确认后提交；
- 通过返回的 Issue 链接核对实际创建结果。

## 开始前准备

- 准备一个 MOI 账号，可前往 [MOI 云端登录/注册](https://moi.matrixorigin.cn/)；
- 准备一个 GitHub 账号；
- 准备一条与目标仓库相关的真实问题，例如页面内容错误、步骤缺失、链接失效或表述不清。

```{warning}
本教程会在公开仓库中创建一条真实 Issue。请只提交真实、可核对的问题反馈；如果只是体验流程，请完成到“生成草稿”即可，不要提交示例内容或重复 Issue。请勿在对话或 Issue 正文中发送密码、密钥、客户信息等敏感内容。
```

## 操作步骤

### 1. 在对话中绑定 GitHub

1. 登录 MOI，进入用于创建智能体的工作区，然后新建对话。
2. 在输入框中发送：

   ```text
   我想创建一个用于整理并提交 GitHub Issue 的智能体。
   请先帮我连接自己的 GitHub，暂时不要创建智能体，也不要提交 Issue。
   ```

   如果创建 GitHub 工具实例时需要填写 Token，请先在 GitHub 中创建一个细粒度个人访问令牌（Fine-grained personal access token）：

   1. 打开 [GitHub 创建细粒度个人访问令牌](https://github.com/settings/personal-access-tokens/new)。如果链接要求登录，请先登录 GitHub；也可以依次进入 **头像 > Settings > Developer settings > Personal access tokens > Fine-grained tokens > Generate new token**。
   2. 填写 Token 名称和有效期，在 **Repository access** 中选择 **Only select repositories**，然后选择 `YOUR_GITHUB_USERNAME/your-repository`。仓库必须属于你的账号，或你已拥有协作者权限。
   3. 在 **Repository permissions** 中将 **Issues** 设为 **Read and write**，保留 **Metadata** 的 **Read-only** 权限。
   4. 点击 **Generate token**，立即复制生成的 Token，并粘贴到 MOI 的 GitHub 工具实例配置中。Token 只会在创建后显示一次，请妥善保管，不要发送到对话或 Issue 正文中。

   配置示例如下：仓库范围选择自己有权限的仓库，`Issues` 设为 **Read and write**，`Metadata` 保持 **Read-only**。

   ```{image} ../assets/images/tutorials/agent-github-token-permissions.png
   :alt: GitHub Fine-grained Token 的仓库范围和 Issues 权限配置
   ```

   对话会先加载 GitHub 技能，并请求选择 GitHub 工具实例。如果尚未配置工具实例，点击 **创建工具实例**，完成 GitHub 连接配置后继续。

   ```{image} ../assets/images/tutorials/agent-github-connect-tool.png
   :alt: 在对话中连接 GitHub 并选择工具实例
   ```

   保存工具实例后，对话会返回 GitHub 已成功连接的提示，并显示当前账号信息。看到连接状态正常后，继续选择目标仓库。

   ```{image} ../assets/images/tutorials/agent-github-connected.png
   :alt: 对话返回 GitHub 已成功连接
   ```

3. 按照对话中显示的 GitHub 连接提示完成登录和授权。
4. 返回 MOI 对话，选择 `YOUR_GITHUB_USERNAME/your-repository`，并确认连接成功。

后续创建智能体时，MOI 会使用当前对话中已经绑定的 GitHub 连接。

完成标志：**对话中显示 GitHub 已连接，并且能够选择目标仓库。**

### 2. 创建 GitHub Issue 提交助手

1. 继续使用刚才完成 GitHub 绑定的对话。
2. 在输入框中粘贴以下内容并发送：

   ```text
   创建一个 GitHub Issue 提交助手。

   仅允许在 YOUR_GITHUB_USERNAME/your-repository 中创建 Issue。

   它需要把我提供的问题反馈整理成 GitHub Issue，固定包含以下内容：
   1. 问题背景
   2. 复现步骤
   3. 实际结果
   4. 预期结果
   5. 验收标准

   信息不足时先向我提问，不要编造内容。
   每次先展示 Issue 标题和正文草稿；只有我明确回复“确认提交”后，
   才能在已绑定的 GitHub 仓库中创建 Issue。
   创建成功后返回 Issue 编号、标题和链接。
   未经我明确要求，不要修改或关闭已有 Issue。
   ```

3. 查看 MOI 生成的智能体候选方案，确认目标仓库是 `YOUR_GITHUB_USERNAME/your-repository`。

   候选方案会展示智能体名称、允许访问的仓库和 GitHub 能力。确认这些信息无误后，再点击 **确认创建智能体**。

   ```{image} ../assets/images/tutorials/agent-github-create-confirm.png
   :alt: 检查 GitHub Issue 提交助手配置并确认创建智能体
   ```

4. 展开系统提示词，检查其中是否保留了“先展示草稿、确认后提交”的规则。

如果候选方案提示 GitHub 尚未连接，请不要跳过，直接在当前对话中重新完成 GitHub 绑定后再继续创建。

完成标志：**我的智能体**中出现“GitHub Issue 提交助手”，并且候选方案显示的目标仓库正确。

### 3. 生成 Issue 草稿

进入新智能体的对话，输入自己实际发现的问题。可以参考下面的格式，将尖括号中的内容替换为真实信息：

```text
请把下面的反馈整理成 Issue 草稿，先不要提交：

问题位置：<相关页面、文件或链接>
问题类型：<内容错误、步骤缺失、链接失效或表述不清>
问题背景：<说明在哪里发现了什么问题>

复现步骤：
1. 打开上述页面或文件。
2. <执行的操作或查看的位置>。
3. <出现问题的步骤>。

实际结果：<当前看到的内容或行为>。
预期结果：<期望如何修改>。
验收标准：<如何确认问题已经解决>。
```

如果想直接体验一次完整流程，可以复制下面这条简短示例发送给智能体：

```text
请把下面的反馈整理成 Issue 草稿，先不要提交：

标题：README 中的“快速开始”链接失效
问题背景：README 中的“快速开始”链接无法打开。
复现步骤：打开 README，点击“快速开始”链接。
实际结果：页面返回 404。
预期结果：打开对应的快速开始文档。
验收标准：链接可以正常打开。
```

智能体生成草稿后，确认标题、目标仓库和正文内容无误，即可按下一节发送确认消息完成提交。

智能体会展示整理后的标题、正文和验收标准，并在末尾等待确认。确认内容无误后，回复“确认提交”即可创建 Issue。

```{image} ../assets/images/tutorials/agent-github-issue-draft.png
:alt: 智能体生成 GitHub Issue 草稿并等待确认
```

检查智能体生成的草稿是否满足以下要求：

- 标题能够概括问题现象；
- 正文包含背景、复现步骤、实际结果、预期结果和验收标准；
- 没有添加输入中未提供的版本号、负责人、标签或原因判断；
- 此时目标仓库中尚未出现新 Issue。

如果内容不准确，直接在当前对话中指出要修改的部分。例如：

```text
把标题改得更具体，并在正文开头保留问题页面链接，其余内容不变，仍然不要提交。
```

### 4. 确认并提交 Issue

先在目标仓库的 **Issues** 页面搜索草稿标题中的关键词，确认没有重复 Issue。草稿核对无误且确实需要提交后，发送：

```text
确认提交。不要添加标签，不要指定负责人。
```

这是一次会修改外部系统的操作。如果页面再次要求确认，请核对目标仓库、Issue 标题和正文后再继续。

创建成功后，智能体应返回以下信息：

- Issue 编号；
- Issue 标题；
- GitHub Issue 链接。

打开返回的链接，确认 Issue 位于目标仓库，状态为 **Open**，标题和正文与确认后的草稿一致。

返回的 Issue 页面会显示标题、正文和 **Open** 状态，可在此页面继续跟踪后续处理。

```{image} ../assets/images/tutorials/agent-github-issue-created.png
:alt: 点击返回的 Issue 链接查看已创建的 Issue
```

完成标志：**公开仓库中出现新 Issue，并且智能体返回的编号和链接可以正常打开。**

### 5. 继续使用智能体

后续可以在对话框底部选择 **GitHub Issue 提交助手**，继续提交其他问题反馈。也可以进入 **我的智能体**，查看其提示词和 GitHub 连接。

如果需要改用其他仓库，应先确认当前 GitHub 连接有权访问该仓库，再修改智能体的目标仓库。不要仅在提交 Issue 时临时输入其他仓库名称来绕过已经确认的仓库范围。

## 教程完成

您已经完成了从对话中绑定 GitHub、创建智能体到真实 Issue 提交的完整流程。这个智能体可以继续用于整理缺陷反馈、功能需求和文档问题，同时通过“先预览、再确认”的规则保留人工检查环节。