MonkeyCode GitHub Issue指南：如何高效提交Bug报告和功能请求
📝 为什么写这篇指南？
MonkeyCode已经正式开源，我们非常期待收到来自全球开发者的反馈。一个高质量的Issue不仅能帮助我们快速定位和解决问题，还能让整个社区受益。
本指南将手把手教你如何提交一份专业、清晰、高效的GitHub Issue。
🔧 Issue类型一览
在MonkeyCode仓库中，你可以提交以下类型的Issue：
| 类型 | 图标 | 适用场景 | 响应优先级 |
|---|---|---|---|
| 🐛 Bug报告 | 🐛 | 软件缺陷、异常行为 | 高 |
| ✨ 功能请求 | ✨ | 新功能建议 | 中 |
| 📚 文档改进 | 📚 | 文档错误或不清晰 | 中 |
| 💡 讨论话题 | 💡 | 技术讨论、架构建议 | 低 |
| ❓ 使用疑问 | ❓ | 如何使用的问题 | 低 |
| 🏗️ PR前置讨论 | 🏗️ | 提交PR前的方案讨论 | 高 |
🐛 第一部分：Bug报告（最需要你的帮助！）
1. Bug报告模板
请复制以下模板并填写：
## 🐛 Bug描述
[用一两句话描述这个bug]
## 复现步骤
步骤1：[具体操作]
步骤2：[具体操作]
步骤3：[具体操作]
## 期望行为
[你认为应该发生什么]
## 实际行为
[实际发生了什么，附截图或日志]
## 环境信息
- 操作系统：[如 macOS Sonoma 14.0 / Windows 11 / Ubuntu 22.04]
- IDE及版本：[如 VSCode 1.85.1 / IntelliJ IDEA 2024.1]
- MonkeyCode插件版本：[查看插件设置中的版本号]
- 使用的AI模型：[如 GPT-4 / Claude 3.5 / 本地模型]
- Node.js版本：[如有，运行 node -v]
- Python版本：[如有，运行 python --version]
## 额外信息
[任何其他有助于理解问题的信息]
2. 完整Bug报告示例
示例一：代码补全不工作
## 🐛 Bug描述
在VSCode中使用MonkeyCode插件时，代码补全功能无响应。输入代码后没有出现任何补全建议。
## 复现步骤
1. 打开VSCode
2. 确认MonkeyCode插件已启用（v2.3.0）
3. 新建一个Python文件 test.py
4. 输入 `def hello(` 并等待补全
5. 没有出现参数提示或函数体补全
## 期望行为
输入 `def hello(` 后应显示参数名称提示，按Tab后生成函数体骨架。
## 实际行为
没有任何补全建议出现。状态栏显示"MonkeyCode: 已连接"，但补全不触发。
环境信息：
- OS: Windows 11 Pro (Build 22631)
- IDE: VSCode 1.85.1 (system setup)
- Plugin: MonkeyCode v2.3.0
- Model: GPT-4o
- Extension Host: 正常运行
3. Bug报告最佳实践
✅ DO（应该做的）：
- 复现后再报告：确保bug可以稳定复现
- 提供最小复现案例：删除无关代码，只保留触发bug的最小代码
- 附上截图/GIF：一图胜千言，特别是UI相关bug
- 粘贴完整错误日志：不要截断，完整的堆栈信息更有价值
- 搜索已有Issue：避免重复提交相同问题
- 使用英文标题（可选）：方便国际开发者理解
❌ DON'T（不应该做的）：
- 不要说"它不工作了"而不提供细节
- 不要省略环境信息
- 不要在一个Issue中报告多个不相关的bug
- 不要包含敏感信息（API密钥、密码等）
✨ 第二部分：功能请求
1. 功能请求模板
## ✨ 功能描述
[清晰描述你想要的功能]
## 动机/使用场景
[为什么需要这个功能？什么场景下会用到？]
## 期望的使用方式
[描述理想中的用户体验]
## 替代方案
[目前有没有其他方式可以实现类似效果？]
## 参考实现
[其他工具有类似功能吗？链接？]
2. 功能请求示例
示例：支持Git工作流集成
## ✨ 功能描述
希望MonkeyCode能够与Git深度集成，在生成代码时自动考虑当前的Git分支、最近的commit历史等信息。
## 动机/使用场景
我们的团队使用Git Flow工作流。当在feature分支上开发时，AI生成的代码经常与main分支的最新改动冲突。如果AI能感知当前分支上下文，就能生成更兼容的代码。
## 期望的使用方式
1. MonkeyCode自动检测当前Git分支
2. 在生成代码时参考该分支最近的commits
3. 在code review时自动关联相关的PR/issue
4. 生成commit message时遵循项目的conventional commits规范
## 替代方案
目前我们需要手动在prompt中说明Git上下文，效率较低且容易遗漏。
## 参考实现
- GitHub Copilot有基本的Git感知能力
- Cursor在生成代码时会参考最近修改的文件
📚 第三部分：文档改进
如果你发现文档有问题，欢迎提交Issue！
文档改进模板
## 📚 问题描述
[哪个页面的文档有什么问题]
## 期望内容
[你认为应该怎么写/补充什么内容]
## 当前内容（如有）
[引用或粘贴当前有问题的文档内容]
## 截图
[标注出问题的位置]
💡 第四部分：讨论与技术交流
对于开放性的技术讨论，可以使用以下格式：
## 💡 讨论主题
[你的技术想法或问题]
## 背景
[为什么想讨论这个话题]
## 你的想法/方案
[你的初步思考]
## 期待反馈的方向
[希望听到什么样的意见]
🎯 Issue标题规范
一个好的标题能让维护者快速理解问题：
| 标题风格 | 示例 | 评价 |
|---|---|---|
| ✅ 清晰具体 | "VSCode插件: Python文件中多行字符串导致补全崩溃" | 优秀 |
| ✅ 包含环境 | "[Windows] 安装后启动报错: 找不到.NET Runtime" | 良好 |
| ✅ 包含组件 | "代码审查模块: 大文件(>1000行)分析超时" | 良好 |
| ❌ 太模糊 | "有个bug" | 差 |
| ❌ 无上下文 | "不工作了" | 差 |
| ❌ 情绪化 | "这软件太烂了！！！" | 差 |
推荐格式：
[组件名]: 简短问题描述 [环境标签]
例如：
[VSCode Plugin]: 自动导入在TypeScript项目中失效 [macOS][CLI]: docker-compose部署时数据库连接超时[Core]: 多文件上下文窗口大小计算错误
🖼️ 截图技巧
推荐工具
| 平台 | 工具 | 特点 |
|---|---|---|
| macOS | Cmd+Shift+4（自带） | 区域截图 |
| macOS | CleanShot X | 专业标注 |
| Windows | Win+Shift+S（自带） | 区域截图 |
| Windows | ShareX | GIF录制+上传 |
| Linux | FlameShot | Linux最佳截图工具 |
| VSCode | 内置截图 | 直接截取编辑器内容 |
截图注意事项
✅ 好的截图：
- 标注出问题的关键区域（用箭头/圆圈）
- 包含足够的上下文（显示相关代码行）
- 如果是长内容，考虑分段截图或录制GIF
- 隐藏敏感信息（个人路径、密钥等）
❌ 避免的截图：
- 整屏截图但不指出重点
- 分辨率太低看不清文字
- 包含个人信息或敏感数据
📊 Issue处理流程
提交Issue后，你会经历以下流程：
提交Issue
↓
🏷️ Triaging（分类打标签）
↓
🔍 Reproduction（维护者尝试复现）
↓
├── ✅ 能复现 → 进入修复流程
│ ↓
│ 🔧 Fix & Test
│ ↓
│ 📦 Release（随下一个版本发布）
│ ↓
│ 🔔 通知你Issue已关闭
│
└── ❓ 无法复现 → 请求更多信息
↓
你补充信息
↓
（循环直到复现或关闭）
响应时间预期：
| Issue类型 | 首次响应时间 | 解决时间 |
|---|---|---|
| 严重Bug（崩溃/数据丢失） | 24小时内 | 1周内 |
| 一般Bug | 3天内 | 2周内 |
| 功能请求 | 1周内 | 纳入路线图讨论 |
| 文档改进 | 3天内 | 1周内 |
| 讨论/疑问 | 社区互助 | 不定 |
🤝 成为顶级贡献者
贡献等级
| 等级 | 条件 | 权益 |
|---|---|---|
| 🌟 Reporter | 提交5个有效Issue | 贡献者页面展示 |
| ⭐ Hunter | 提交10个确认Bug | 限量版周边 |
| 🌟 Super Hunter | 提交20个确认Bug | 企业版免费使用权 |
| 💎 MVP | 持续高质量贡献 | 技术顾问委员会邀请 |
贡献技巧
- 从简单Issue开始：新手可以先从标记为
good first issue的任务入手 - 关注标签：订阅你感兴趣的领域的标签通知
- 参与代码审查：对别人的PR提出建设性意见也是贡献
- 帮助回答问题：在Issues中解答其他用户的问题
- 写博客分享：写下你的使用经验，帮助更多人了解MonkeyCode
🔗 快速链接
📢 最后的话
每一个Issue都是MonkeyCode进步的动力。无论你是报告Bug、建议功能还是改进文档，你的贡献都 invaluable（无法估量）。
不要犹豫——现在就点击下方链接，提交你的第一个Issue吧！
👉 https://github.com/monkeycode-ai/monkeycode/issues/new 👈
"在开源世界中，最好的贡献往往始于一个小小的Issue。" —— MonkeyCode团队
本文持续更新，欢迎提出改进建议！如有疑问，同样可以在GitHub提交Issue咨询。
🌟 感谢你成为MonkeyCode社区的一员！让我们一起打造更好的AI编程助手！
浙公网安备 33010602011771号