repo wiki

Author: afanty2021

.qoder/repowiki/zh/content/基本使用.md

@@ -0,0 +1,389 @@
+# 故障排除
+
+<cite>
+**本文档中引用的文件**
+- [README.md](file://README.md)
+- [changelog.md](file://changelog.md)
+- [LICENSE.md](file://LICENSE.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [系统要求与兼容性](#系统要求与兼容性)
+3. [认证问题](#认证问题)
+4. [环境问题](#环境问题)
+5. [功能问题](#功能问题)
+6. [性能问题](#性能问题)
+7. [日志收集与分析](#日志收集与分析)
+8. [版本兼容性检查](#版本兼容性检查)
+9. [反馈机制](#反馈机制)
+10. [常见问题解答](#常见问题解答)
+
+## 简介
+
+GitHub Copilot CLI 是一个强大的终端集成AI编码助手，提供了智能的代码补全、重构和开发支持。本故障排除指南旨在帮助用户识别、诊断和解决在使用过程中可能遇到的各种问题。
+
+## 系统要求与兼容性
+
+### 支持的操作系统
+
+GitHub Copilot CLI 支持以下平台：
+- **Linux** - 完全支持
+- **macOS** - 完全支持  
+- **Windows** - 完全支持（实验性警告已移除）
+
+### Node.js 版本要求
+
+**最低要求：** Node.js v22 或更高版本
+**推荐版本：** 最新稳定版
+
+**重要提示：** 在启动时会强制执行最小 Node 版本要求，如果版本不兼容，CLI 将无法启动。
+
+### npm 版本要求
+
+- **npm** v10 或更高版本
+- （仅限 Windows）**PowerShell** v6 或更高版本
+
+**节源码**
+- [README.md](file://README.md#L25-L35)
+
+## 认证问题
+
+### 组织策略限制
+
+**症状：** 访问被拒绝或收到策略限制错误
+
+**诊断步骤：**
+1. 检查是否在企业环境中使用
+2. 验证组织管理员是否启用了 Copilot CLI
+3. 确认网络访问权限
+
+**解决方案：**
+- 联系组织管理员确认 Copilot CLI 的启用状态
+- 检查企业网络策略和防火墙设置
+- 参考官方文档：[管理组织中的 GitHub Copilot 策略](http://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization)
+
+### Personal Access Token (PAT) 权限不足
+
+**症状：** 使用 PAT 登录时出现权限错误
+
+**诊断步骤：**
+1. 检查 PAT 是否具有 "Copilot Requests" 权限
+2. 验证环境变量设置
+3. 确认 PAT 格式正确
+
+**解决方案：**
+1. 访问 [GitHub PAT 设置页面](https://github.com/settings/personal-access-tokens/new)
+2. 添加 "Copilot Requests" 权限
+3. 设置环境变量：
+   - `GH_TOKEN` 或 `GITHUB_TOKEN`（优先级顺序）
+4. 重新启动 CLI 并使用 `/login` 命令
+
+### OAuth 登录失败
+
+**症状：** OAuth 流程中断或浏览器无法打开
+
+**诊断步骤：**
+1. 检查网络连接
+2. 验证防火墙设置
+3. 确认浏览器可正常打开
+
+**解决方案：**
+- 对于 SSH 用户：确保环境支持设备代码轮询
+- 手动复制设备代码到浏览器
+- 使用 PAT 作为替代认证方式
+- 更新至最新版本以获得改进的 OAuth 实现
+
+**节源码**
+- [changelog.md](file://changelog.md#L272-L278)
+- [changelog.md](file://changelog.md#L201-L213)
+
+## 环境问题
+
+### Node.js 版本不兼容
+
+**症状：** 启动时显示版本错误或功能异常
+
+**诊断步骤：**
+1. 运行 `node --version` 检查版本
+2. 验证 npm 版本：`npm --version`
+3. 检查 PowerShell 版本（Windows 用户）
+
+**解决方案：**
+1. 升级 Node.js 到 v22 或更高版本
+2. 使用版本管理器（如 nvm）管理 Node.js 版本
+3. 清理 npm 缓存并重新安装
+
+### 代理配置错误
+
+**症状：** 网络连接超时或代理认证失败
+
+**诊断步骤：**
+1. 检查代理环境变量设置
+2. 验证代理服务器可达性
+3. 确认认证凭据正确
+
+**解决方案：**
+1. 设置代理环境变量：
+   - `HTTPS_PROXY` 或 `HTTP_PROXY`
+   - 格式：`http://username:password@proxy-server:port`
+2. 对于 Node.js v24+ 用户，代理支持已增强
+3. 检查防火墙规则和网络策略
+
+**节源码**
+- [changelog.md](file://changelog.md#L201-L213)
+- [changelog.md](file://changelog.md#L223-L231)
+
+## 功能问题
+
+### 工具调用失败
+
+**症状：** MCP 工具执行失败或无响应
+
+**诊断步骤：**
+1. 检查工具配置文件
+2. 验证环境变量解析
+3. 确认路径权限
+
+**解决方案：**
+1. 更新 MCP 服务器配置格式
+2. 确保环境变量前缀使用 `$` 符号
+3. 检查工具依赖项和权限设置
+4. 使用 `--allow-all-paths` 参数临时解决问题
+
+### 会话卡死
+
+**症状：** 会话无法正常结束或响应停滞
+
+**诊断步骤：**
+1. 检查是否有未完成的工具调用
+2. 验证内存使用情况
+3. 确认网络连接状态
+
+**解决方案：**
+1. 使用 `/exit` 或 `/quit` 命令退出
+2. 强制终止进程（`Ctrl+C`）
+3. 清理会话状态文件
+4. 重启 CLI 并使用 `--resume` 恢复会话
+
+### 多行输入异常
+
+**症状：** 输入框无法正确处理多行文本
+
+**诊断步骤：**
+1. 检查终端协议支持
+2. 验证 Kitty 协议设置
+3. 确认终端配置
+
+**解决方案：**
+1. 在 VSCode 中运行 `/terminal-setup` 命令
+2. 设置 `COPILOT_KITTY` 环境变量
+3. 使用 `/terminal-setup` 命令配置非 Kitty 终端
+4. 检查终端键盘协议支持
+
+**节源码**
+- [changelog.md](file://changelog.md#L120-L132)
+- [changelog.md](file://changelog.md#L182-L199)
+- [changelog.md](file://changelog.md#L134-L141)
+
+## 性能问题
+
+### 响应延迟
+
+**症状：** 命令响应时间过长
+
+**诊断步骤：**
+1. 检查网络连接质量
+2. 监控系统资源使用
+3. 分析对话上下文长度
+
+**解决方案：**
+1. 减少对话上下文长度
+2. 使用 `/clear` 开始新的会话
+3. 检查代理设置和网络配置
+4. 更新到最新版本以获得性能优化
+
+### 内存占用过高
+
+**症状：** 内存使用持续增长
+
+**诊断步骤：**
+1. 监控内存使用趋势
+2. 检查大文件处理
+3. 分析工具调用频率
+
+**解决方案：**
+1. 定期使用 `/clear` 清理会话
+2. 避免处理过大的文件
+3. 使用 `--disable-parallel-tools-execution` 减少并发
+4. 检查是否有内存泄漏问题
+
+**节源码**
+- [changelog.md](file://changelog.md#L53-L70)
+- [changelog.md](file://changelog.md#L215-L221)
+
+## 日志收集与分析
+
+### 启用调试日志
+
+GitHub Copilot CLI 提供了灵活的日志级别配置：
+
+**可用的日志级别：**
+- `none` - 禁用日志
+- `error` - 仅错误信息
+- `warning` - 警告和错误
+- `info` - 基本信息和警告
+- `debug` - 详细调试信息
+- `all` - 全部日志
+- `default` - 默认级别
+
+**启用调试日志的方法：**
+1. 创建或编辑配置文件：`~/.copilot/config`
+2. 添加配置项：`log_level: debug`
+3. 重启 CLI 应用程序
+
+### 日志文件位置
+
+**会话状态文件：**
+- 新格式：`~/.copilot/session-state/`
+- 旧格式：`~/.copilot/history-session-state/`（将迁移）
+
+**启动日志：**
+- 包含当前版本信息，便于问题报告
+- 在调试模式下提供更多详细信息
+
+### 日志分析技巧
+
+**常见日志模式：**
+1. **认证相关：** 查找 API 请求 ID 和认证状态变化
+2. **工具调用：** 监控工具执行时间和结果
+3. **性能问题：** 分析响应时间和资源使用
+4. **错误处理：** 关注错误消息和堆栈跟踪
+
+**节源码**
+- [changelog.md](file://changelog.md#L120-L132)
+- [changelog.md](file://changelog.md#L143-L158)
+
+## 版本兼容性检查
+
+### 当前版本信息
+
+根据 changelog，当前最新版本为 **0.0.353**，发布于 2025年10月28日。
+
+### 版本更新建议
+
+**定期更新的好处：**
+1. 获取最新的功能和改进
+2. 修复已知的安全漏洞
+3. 解决性能问题
+4. 改进用户体验
+
+**更新方法：**
+```bash
+npm update -g @github/copilot
+```
+
+### 已修复问题回顾
+
+**最近的重要修复：**
+- **0.0.353:** 支持自定义代理服务器
+- **0.0.352:** 改进 MCP 工具处理
+- **0.0.351:** 优化路径检测逻辑
+- **0.0.350:** 限制 GitHub MCP 工具数量以节省上下文空间
+
+**节源码**
+- [changelog.md](file://changelog.md#L1-L10)
+
+## 反馈机制
+
+### 提交问题报告
+
+GitHub Copilot CLI 提供多种反馈渠道：
+
+**1. GitHub Issues**
+- 访问项目仓库：[GitHub Copilot CLI Issues](https://github.com/github/copilot-cli/issues)
+- 提交技术问题和功能请求
+- 包含详细的重现步骤和环境信息
+
+**2. Discussions**
+- 参与社区讨论
+- 寻求帮助和最佳实践
+- 分享使用经验和技巧
+
+**3. 内置反馈命令**
+- 在 CLI 中运行 `/feedback` 命令
+- 提交保密的反馈调查
+- 快速报告问题而不离开 CLI 界面
+
+### 报告问题的最佳实践
+
+**完整的错误报告应包含：**
+1. **问题描述：** 清晰描述遇到的问题
+2. **重现步骤：** 详细的操作步骤
+3. **预期行为：** 正确的行为应该是什么
+4. **实际行为：** 实际观察到的现象
+5. **环境信息：**
+   - 操作系统版本
+   - Node.js 版本
+   - Copilot CLI 版本
+   - 终端类型和配置
+6. **日志信息：** 启用调试日志并提供相关输出
+7. **截图或录屏：** 如有必要，提供视觉证据
+
+### 社区参与
+
+**积极参与的好处：**
+- 加速问题解决过程
+- 影响产品发展方向
+- 获得社区支持和帮助
+- 分享您的经验给其他用户
+
+## 常见问题解答
+
+### Q: 我可以使用哪些模型？
+
+**A:** 默认使用 Claude Sonnet 4.5，可通过 `/model` 命令切换：
+- Claude Sonnet 4
+- Claude Sonnet 4.5
+- GPT-5（如果可用）
+
+### Q: 如何重置会话？
+
+**A:** 使用以下命令：
+- `/clear` - 清理当前会话
+- `/exit` 或 `/quit` - 退出 CLI
+- `copilot --resume` - 恢复最近的会话
+
+### Q: 为什么我的输入被截断？
+
+**A:** 可能是由于：
+1. 上下文窗口接近限制
+2. 大量内容粘贴
+3. 终端宽度限制
+
+**解决方案：**
+- 使用 `/clear` 开始新会话
+- 使用 `/terminal-setup` 优化输入
+- 检查终端宽度设置
+
+### Q: 如何处理权限问题？
+
+**A:** 确保：
+1. 具有文件和目录的读写权限
+2. 使用正确的认证方式
+3. 检查组织策略限制
+
+**节源码**
+- [changelog.md](file://changelog.md#L244-L257)
+
+## 结论
+
+GitHub Copilot CLI 是一个功能强大但复杂的工具，可能会遇到各种技术挑战。通过遵循本故障排除指南，您可以有效地诊断和解决大多数常见问题。
+
+记住：
+- 保持软件更新到最新版本
+- 启用适当的日志记录以便调试
+- 充分利用内置的诊断命令
+- 积极参与社区反馈
+
+如果遇到本指南未涵盖的问题，请随时通过 GitHub Issues 或 Discussions 寻求帮助。