GitHub 直连慢/失败（依赖 GitHub 的场景）

你会遇到什么

在 code-review-graph 的构建/更新流程里，凡是碰到 GitHub 的操作（仓库元数据、上游资源）就卡住或失败。你会以为工具坏了，其实大部分场景根本不依赖 GitHub。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

• 本市场连通性基线（connectivity-20260828b）：GitHub 直连慢、raw 超时，国内出口不稳。
• 这个工具的核心用法是解析本地代码（tree-sitter），数据存 SQLite（工作区 .code-review-graph/），build/update 不依赖网络。
• 只有少数场景（仓库元数据、上游资源下载）才需要访问 GitHub。

判断“工具依赖什么”不能看表象（报错在 GitHub 相关环节），要看数据流：code-review-graph 的核心输入是本地代码（tree-sitter 解析），中间产物存在本地 SQLite，输出是本地图数据——整条链路里没有一步必须访问 GitHub，所以它本质是离线工具。会碰 GitHub 的只有“获取元数据/下载上游资源”这类可选的补充环节。

这就是“先分清是哪一步卡”的方法论：卡住的位置决定根因——本地解析卡住（build 阶段）跟网络无关，检查路径与解析器；下载/元数据卡住才是连通性问题。由此也得出加速策略的分层：核心流程不碰网络（离线直接跑），pip 类安装走国内镜像（包分发层），GitHub 下载走 gh-proxy（内容层）——每一层都有自己的加速通道，别用错层。

验证离线能力也有固定方法：断开外网重跑 build，能完成即证明核心不依赖 GitHub。

一步步来

1. 先分清是哪一步卡 — 必做

build/update 本地分析卡住 = 不是 GitHub 问题，检查代码仓库路径与 tree-sitter 解析。下载/元数据类操作卡住才是 GitHub 连通性。

2. 核心用法离线跑 — 必做

code-review-graph build --repo .

数据落在工作区 .code-review-graph/（SQLite），全程不访问 GitHub。

3. 确需联网时走加速 — 必做

GitHub 下载走 gh-proxy 等加速通道或错峰重试；pip 类安装固定走清华镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph

4. 验证本地可离线 — 必做

断开外网后重复 build，能完成即证明核心流程不依赖 GitHub。

怎么确认修好了

build 流程完成且产物落盘（预期形态）：

code-review-graph build --repo .
→ build 完成日志 + 工作区 .code-review-graph/ 下生成图数据文件

安装全程走清华镜像成功（本市场实测）。

其它环境的表现

症状

code-review-graph 构建/更新流程中访问 GitHub（如仓库元数据、上游资源）卡住或失败。

原因

本市场连通性基线：GitHub 直连慢、raw 超时（connectivity-20260828b）；工具本身主要数据源是本地仓库，GitHub 依赖场景较少，但国内出口不稳时仍会受影响。

解法

1. 核心用法不依赖 GitHub：build/update 解析本地代码（tree-sitter，SQLite 存工作区 .code-review-graph/），离线可用。
2. 确需访问 GitHub 时走加速通道（gh-proxy 等）或错峰重试；下载类操作见本市场各条目的连通性情报。

未能实测项（如实标注）

• 真实 codex 平台接入（需平台账号）；install/init 子命令的配置写面（本环境未执行，避免污染真实配置）；完整 build/图构建全流程（需目标仓库与较长执行时间）；Windows/macOS 环境；pipx 安装路径（官方推荐，本机未实测）。