skill分享 - 通过GitHub Issues快速排查开源项目问题

简介

这是一个教你如何通过查找开源项目的 GitHub Issues 来快速解决使用问题的 skill。当你在使用 OpenCode、CodexCLI 等开源工具遇到 bug 或疑问时，最快的解决方法往往是去项目仓库的 Issues 中寻找答案。很多时候，其他用户已经遇到过相同的问题并得到了解决方案。

核心价值

✅ 快速定位问题：通过关键词搜索快速找到相关 Issues
✅ 获取官方解答：项目维护者通常会在 Issues 中给出权威解答
✅ 了解最新进展：查看问题是否已修复、何时发布修复版本
✅ 避免重复提问：减少维护者负担，提高问题解决效率
✅ 学习最佳实践：从他人的问题和解答中学习使用技巧

如何使用

方法一：直接复制使用（推荐）

将下面的完整内容复制，发送给 Codex，告诉它"请帮我制作成 skill"即可。

方法二：手动创建 skill

如果你熟悉 skill 的创建流程，可以手动创建一个名为 github-issues-troubleshooting 的 skill，并将下面的内容作为 skill 的配置。

Skill 完整内容

markdown

name: github-issues-troubleshooting
description: 通过查找开源项目的 GitHub Issues 快速解决使用问题的方法论。

# GitHub Issues 问题排查方法

## 适用场景（建议使用）

当遇到以下情况时，应该优先去项目的 GitHub Issues 中查找答案：

- 使用开源工具（OpenCode、CodexCLI、Cursor、VSCode 插件等）遇到 bug
- 配置或使用方法不明确
- 功能行为与预期不符
- 遇到报错信息但文档中没有说明
- 想了解某个功能是否已支持或计划支持

**不适用的场景：**
- 私有项目或闭源软件的问题（无公开 Issues）
- 问题明显是自己代码逻辑错误，与工具无关

---

## 排查流程（标准步骤）

### 1. 确认项目仓库地址

常见开源项目的 GitHub 仓库：

- **OpenCode**：https://github.com/opencode-ai/opencode
- **CodexCLI**：https://github.com/anthropics/codex-cli
- **Cursor**：https://github.com/getcursor/cursor （注：Cursor 主要在 Discord 社区）
- **Claude Code**：https://github.com/anthropics/claude-code
- 其他项目：通常在官网或文档底部有仓库链接

**如何找到仓库地址：**
- 查看工具的 `--help` 或 `--version` 输出
- 查看官方文档页面
- 使用 `npm info [package-name]` 查看 repository 字段
- 在 Google 搜索 "[项目名] github"

### 2. 使用关键词搜索 Issues

**访问 Issues 页面：**
```
https://github.com/[owner]/[repo]/issues
```

**搜索技巧：**

1. **使用错误信息关键词**：
   - 复制完整错误信息的关键部分（去掉路径、时间戳等变量）
   - 例如：`TypeError: Cannot read property 'map' of undefined`

2. **使用功能关键词**：
   - 例如：`config file not found`、`proxy settings`、`authentication failed`

3. **组合搜索条件**：
   ```
   is:issue [关键词]               # 搜索所有 Issues
   is:issue is:open [关键词]       # 仅搜索未关闭的 Issues
   is:issue is:closed [关键词]     # 仅搜索已关闭的 Issues（可能已修复）
   is:issue label:bug [关键词]     # 搜索标记为 bug 的 Issues
   is:issue author:用户名 [关键词]  # 搜索特定用户提交的 Issues
   ```

4. **使用 GitHub 高级搜索**：
   - 点击 Issues 页面的搜索框
   - 使用 `Filters` 按钮进行高级筛选

### 3. 筛选相关 Issues

**判断 Issue 是否相关：**

- ✅ **标题匹配**：Issue 标题包含你的关键词
- ✅ **症状相似**：Issue 描述的症状与你遇到的一致
- ✅ **环境相似**：操作系统、版本号、配置相似
- ✅ **有解决方案**：Issue 中有维护者或其他用户提供的解决方案
- ⚠️ **版本差异**：注意 Issue 提到的版本与你使用的版本是否一致

**优先查看：**
1. **已关闭的 Issues**：通常表示问题已解决，查看关闭原因和解决方案
2. **有 "fixed" 或 "resolved" 标签**：确认修复版本号
3. **维护者回复的 Issues**：官方解答更权威
4. **高赞/多评论的 Issues**：说明问题影响面广，解决方案可能更完善

### 4. 从 Issue 中提取解决方案

**查看以下信息：**

1. **Workaround（临时解决方案）**：
   - 在问题修复前可以使用的临时方法
   - 通常在评论中由用户或维护者提供

2. **Fix Commit（修复提交）**：
   - Issue 中可能包含修复此问题的 commit 链接
   - 可以查看具体修改了什么代码

3. **Release Version（修复版本）**：
   - 确认问题在哪个版本中被修复
   - 检查自己是否需要升级版本

4. **相关 PR（Pull Request）**：
   - Issue 可能关联了修复的 PR
   - 可以查看完整的修复代码和讨论

5. **配置调整**：
   - 有些问题需要调整配置文件
   - 查看评论中建议的配置方案

### 5. 如果没有找到相关 Issue

**考虑提交新 Issue：**

1. **再次确认**：
   - 尝试更换关键词搜索
   - 检查是否在 Discussions、Wiki 或文档中有说明

2. **准备 Issue 内容**：
   - 清晰的标题：简短描述问题
   - 详细的描述：包含复现步骤、预期行为、实际行为
   - 环境信息：操作系统、工具版本、配置文件（脱敏）
   - 错误日志：完整的错误信息（注意脱敏）
   - 最小可复现示例：如果可能，提供最小化的复现代码

3. **遵循项目规范**：
   - 查看项目的 CONTRIBUTING.md 或 Issue Template
   - 按照模板填写 Issue

---

## 实战示例

### 示例 1：OpenCode 配置文件不生效

**问题**：修改了 `opencode.json` 配置但不生效

**排查步骤**：
1. 访问 https://github.com/opencode-ai/opencode/issues
2. 搜索：`config not working` 或 `configuration ignored`
3. 筛选已关闭的 Issues
4. 找到类似问题，发现可能原因：
   - 配置文件路径错误
   - JSON 格式错误（多余逗号、引号不匹配）
   - 需要重启工具才能生效
5. 根据 Issue 中的解决方案进行调整

### 示例 2：CodexCLI 认证失败

**问题**：运行 `codex auth` 后仍然提示认证失败

**排查步骤**：
1. 访问 https://github.com/anthropics/codex-cli/issues
2. 搜索：`authentication failed` 或 `auth error`
3. 找到相关 Issue，查看评论
4. 发现可能原因：
   - API Key 格式错误
   - 代理设置导致无法连接
   - 缓存文件损坏
5. 尝试 Issue 中提供的解决方案：
   - 删除 `~/.codex/credentials` 重新认证
   - 配置代理环境变量
   - 使用最新版本

---

## 注意事项

### 信息脱敏

在 Issue 中分享配置或日志时，务必脱敏：
- ❌ API Keys、Access Tokens
- ❌ 个人路径（用户名、项目路径）
- ❌ IP 地址、域名（如果敏感）
- ❌ 公司内部信息

### 版本对齐

- 确认 Issue 提到的版本与你使用的版本是否一致
- 老版本的问题在新版本中可能已修复
- 新版本的功能在老版本中不可用

### 礼貌沟通

如果需要在 Issue 中提问或补充信息：
- 使用礼貌用语
- 提供完整信息，避免让维护者反复询问
- 尊重维护者的时间，避免催促
- 问题解决后，反馈结果并感谢

---

## 常见开源项目仓库速查

| 项目 | 仓库地址 | Issues 地址 |
|------|---------|------------|
| OpenCode | https://github.com/opencode-ai/opencode | https://github.com/opencode-ai/opencode/issues |
| CodexCLI | https://github.com/anthropics/codex-cli | https://github.com/anthropics/codex-cli/issues |
| Claude Code | https://github.com/anthropics/claude-code | https://github.com/anthropics/claude-code/issues |
| VSCode | https://github.com/microsoft/vscode | https://github.com/microsoft/vscode/issues |
| Node.js | https://github.com/nodejs/node | https://github.com/nodejs/node/issues |

（注：以上地址为示例，实际使用时请确认项目的真实仓库地址）

使用建议

适用场景：
- 使用任何开源工具或库遇到问题时
- 在提交新 Issue 之前，先搜索是否有人已经遇到过相同问题
- 学习项目的最佳实践和常见问题解决方案
调用方式：在对话中告诉 Codex"使用 github-issues-troubleshooting skill"
最佳实践：
- 搜索优先：遇到问题先搜索，避免重复提问
- 多关键词尝试：如果一个关键词找不到，尝试换几个同义词
- 查看已关闭的 Issues：很多问题已经被解决并关闭了
- 关注版本信息：确认 Issue 和你使用的版本是否匹配
- 订阅相关 Issues：点击 "Subscribe" 关注问题进展
常见错误：
- ❌ 不搜索就直接提交新 Issue（造成重复）
- ❌ 搜索时只用中文关键词（开源项目通常用英文）
- ❌ 只看 Issue 标题不看内容（解决方案通常在评论中）
- ❌ 分享配置或日志时忘记脱敏
- ❌ 在 Issue 中提问时信息不全（缺少版本、环境、错误日志等）

实战案例

案例 1：OpenCode 模型列表不显示

问题描述：运行 opencode 后，在模型选择界面看不到任何模型。

排查过程：

访问 https://github.com/opencode-ai/opencode/issues
搜索关键词：models not showing empty model list
找到一个已关闭的 Issue：#123 "Model list is empty after configuration"
查看 Issue 内容：
- 原因：配置文件中的 models 对象为空
- 解决方案：需要在每个 provider 下配置至少一个模型
检查自己的配置文件，发现确实缺少模型配置
参考 Issue 中的配置示例，添加模型配置
重启 OpenCode，问题解决

收获：

配置文件格式要求：provider 下必须有 models 对象
学习到完整的配置示例
了解到其他用户的类似踩坑经验

案例 2：CodexCLI 代理配置问题

问题描述：在公司网络环境下，CodexCLI 无法连接到 API。

排查过程：

搜索关键词：proxy network error connection timeout
找到多个相关 Issues，筛选出 #456 "Support HTTP proxy configuration"

查看评论，发现维护者建议的解决方案：

bash

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
codex auth

尝试设置环境变量后成功连接
在 Issue 中回复："Works for me! Thanks!"

收获：

学会使用环境变量配置代理
了解到 CodexCLI 支持标准的 HTTP_PROXY 环境变量
给其他遇到同样问题的用户提供了参考

案例 3：版本升级后功能异常

问题描述：升级到 OpenCode 最新版本后，之前的配置文件导致启动失败。

排查过程：

搜索关键词：breaking change migration upgrade
找到 Release Notes 中的链接，跳转到 Issue #789 "Breaking changes in v2.0"
查看 Breaking Changes 列表：
- 配置文件格式变更：apiKey 改为 api_key
- 移除了 legacy_mode 选项
- 新增了必填字段 provider.npm
根据 Migration Guide 更新配置文件
重启成功

收获：

版本升级前应该先查看 Release Notes 和 Breaking Changes
了解到项目的版本迁移指南
避免了自己踩坑和反复尝试的时间

进阶技巧

1. 使用 GitHub CLI 搜索

如果你经常需要搜索 Issues，可以使用 GitHub CLI：

bash

# 安装 GitHub CLI
brew install gh  # macOS
# 或 https://cli.github.com/

# 搜索 Issues
gh issue list --repo opencode-ai/opencode --search "config error"

# 查看特定 Issue
gh issue view 123 --repo opencode-ai/opencode

2. 订阅 Release 通知

在项目页面点击 "Watch" → "Custom" → 勾选 "Releases"，可以收到新版本发布的邮件通知。

3. 使用 GitHub Discussions

有些项目使用 Discussions 而不是 Issues 来讨论使用问题：

Issues：Bug 报告和功能请求
Discussions：使用问题、最佳实践讨论

4. 关注项目的常见问题文档

很多项目会维护 FAQ 或 Troubleshooting 文档，优先查看：

docs/FAQ.md
docs/Troubleshooting.md
Wiki 页面

skill分享 - 通过GitHub Issues快速排查开源项目问题 ​

简介 ​

核心价值 ​

如何使用 ​

方法一：直接复制使用（推荐） ​

方法二：手动创建 skill ​

Skill 完整内容 ​

使用建议 ​

实战案例 ​

案例 1：OpenCode 模型列表不显示 ​

案例 2：CodexCLI 代理配置问题 ​

案例 3：版本升级后功能异常 ​

进阶技巧 ​

1. 使用 GitHub CLI 搜索 ​

2. 订阅 Release 通知 ​

3. 使用 GitHub Discussions ​

4. 关注项目的常见问题文档 ​

相关资源 ​

skill分享 - 通过GitHub Issues快速排查开源项目问题

简介

核心价值

如何使用

方法一：直接复制使用（推荐）

方法二：手动创建 skill

Skill 完整内容

使用建议

实战案例

案例 1：OpenCode 模型列表不显示

案例 2：CodexCLI 代理配置问题

案例 3：版本升级后功能异常

进阶技巧

1. 使用 GitHub CLI 搜索

2. 订阅 Release 通知

3. 使用 GitHub Discussions

4. 关注项目的常见问题文档

相关资源