已关闭
docs: 补充受限网络下 pre-commit 首次运行的 GitHub 访问前置说明 #612
aflyingto创建于 9月30日关闭于 17 天前
aflyingto
17 天前 评论：
17 天前 评论：
验证记录
- 当前版本或分支: main @ 76bc48d
- 验证时间: 2026-10-20
- 复现命令:
head -15 .pre-commit-config.yaml；grep -n -A10 "### Pre-commit" CONTRIBUTING.md；grep -n "pre-commit" AGENTS.md - 实际结果:
.pre-commit-config.yaml引用远端钩子仓https://github.com/pre-commit/pre-commit-hooks（rev v5.0.0，trailing-whitespace/end-of-file-fixer 等 8 个钩子来自该仓）——首次pre-commit run或首次 commit 触发时需从 GitHub 克隆并初始化环境；CONTRIBUTING.md "Pre-commit" 节（:223-256）仅覆盖安装与运行方式，无任何网络前置说明；AGENTS.md:254 仅有钩子安装纪律，亦无网络说明——issue 主张属实 - 预期结果: 贡献者在受限网络下首次运行 pre-commit 时能从文档直接找到根因（GitHub 不可达）与解法（git 代理，仅作用于 github.com）
- 时间线检查: issue 于 2026-09-30 创建后无评审记录、无关联 PR；现有 84+ open issue 中无 pre-commit 网络主题的重复项（#611 为 dev-setup PATH 主题，与本项正交）
- 结论: 继续修复（docs-only：CONTRIBUTING.md Pre-commit 节补网络前置说明——issue 给出 AGENTS.md §6 或 CONTRIBUTING.md 两个落点，取 CONTRIBUTING.md：其为贡献者环境准备的权威文档且已有 Pre-commit 专节；AGENTS.md:254 为纪律清单，加环境配置说明会稀释其语义）
aflyingto
17 天前 评论：
17 天前 评论：
开发进度
- 当前状态: ready-for-review（PR !596 已完成自检、四角色独立评审全部 approved、双端 CI 全绿，等待人工最终确认与合并）
- 根因: pre-commit 首次运行依赖 GitHub 可达（克隆 pre-commit-hooks 远端钩子仓），文档无网络前置说明，受限网络贡献者遇到 git 层 TLS/超时报错无从联想根因（详见验证记录）
- 主要修改: CONTRIBUTING.md Pre-commit 节新增 "Network prerequisite for the first run" 子节（含评审润色共 25 行）：首跑克隆行为、缓存复用边界（含 rev 变更例外）、git 原生报错示例、github.com 域限定代理占位符示例与撤销出口
- 影响范围: 纯文档，零代码路径
- 单元测试: 未运行——docs-only 按 code-quality-gates §8 跳过（自检已说明理由）
- 构建: 未运行——同上
- 实际命令验证: .pre-commit-config.yaml 远端钩子引用核实（唯一网络源、rev v5.0.0）；文档技术事实经四角色独立核验（含 git 代理域限定语义与 pre-commit 上游缓存行为）
- 安全影响: 占位符代理地址、无凭证、无危险操作引导；域限定 github.com 避免代理截走 GitCode 认证流量（安全评审确认为正确取舍）
- 文档同步: 落点 CONTRIBUTING.md（issue 二选一，评审确认落点决策）；README/AGENTS/spec/docs 无需跟随（文档评审全仓扫描确认）
- 风险或未覆盖项: risk/low，按规范合并前需人工最终确认；无可选项遗留（两项未采纳建议均有评审员判定背书并记录于 PR 自检）
- 关联 PR: !596
背景
.pre-commit-config.yaml引用https://github.com/pre-commit/pre-commit-hooks（rev v5.0.0）。pre-commit 首次运行（pre-commit run或首次 commit 触发钩子）需从 GitHub 克隆该仓库并初始化环境。GnuTLS recv error、i/o timeout），不指向根因，贡献者难以联想到需要为 git 配置 HTTPS 代理。改动建议
AGENTS.md§6 pre-commit 相关段落或CONTRIBUTING.md环境准备部分，补充环境前置说明：git config --global http.https://github.com.proxy http://127.0.0.1:<端口>（占位符，具体代理由使用者自行决定；该配置仅作用于 github.com）验收标准
影响范围
AGENTS.md或CONTRIBUTING.md（docs-only）