专题：AI 编程问题排查手册
专题目标与定位
在日常使用各类 AI 编程工具（Cursor、Claude Code、Gemini CLI 等）与开发环境协作时，常常会遇到因本地环境、端口冲突、沙箱机制或权限位引发的偶发问题。
本专题将零散的排查记录按统一的排查思维模型组织起来，旨在帮助开发者快速定位根因、提供标准化排查步骤，并建立稳固的环境防御机制。
排查四步法则
- 保留第一案发现场：记录原始终端错误信息、报错堆栈、发生时的前置操作与环境状态。
- 区分表象与根因：例如
ERR_CONNECTION_REFUSED只是网络请求失败的表现，真实原因可能是本地端口被占用或证书验证失败。 - 隔离变量并最小复现：通过独立的简单命令（如
curl、lsof、单文件执行）剥离复杂的 IDE 包装层。 - 长效防范：将排查经验固化为脚本、配置文件或项目规则，避免同一问题重复踩坑。
本专题收录文章
AI 编程环境与权限篇
核心排查聚焦本地 CLI 授权、端口冲突与跨平台执行权限问题。
建议阅读顺序：
1
Gemini CLI 登录失败的排查记录
macOS 环境下 OAuth 本地重定向端口被占用导致的回调超时定位与释放技巧。
2
Codex 运行脚本权限 EACCES 报错与权限沙箱治理
AI 工具新建文件默认权限位缺失、跨平台 Git 权限追踪与安全沙箱执行策略。