GitHub中继

技能文档

---
name: github-access
description: 诊断 GitHub 连接失败并自动选择可用通道完成代码拉取、推送、源码快照下载与 release 资产下载。当用户 git clone/push/pull 超时或失败、GitHub 网页打不开、下载 GitHub 仓库或 release 文件卡住、提到 GitHub 连不上时触发。
title: GitHub中继
category: 开发工具
---

# GitHub 访问故障诊断与降级通道

在 github.com 直连超时的网络环境下，按「探测 → 选通道 → 执行」完成 GitHub 操作。所有通道命令已在本机验证：github.com:443 直连超时，api.github.com、raw.githubusercontent.com、codeload.github.com、ssh.github.com:443 可达。

## 技能工作流（步骤1-3:探测→选通道→执行）

调用 `todo_write` 工具创建待办任务：

连通性探测 → 通道选择 → 执行操作 → 结果验证

### 步骤 1: 运行连通性探测

在任意目录执行探测脚本：

```bash
python3 ~/.zcode/skills/github-access/scripts/github_probe.py
```

已知目标仓库时附加仓库参数，探测结果更精确：

```bash
python3 ~/.zcode/skills/github-access/scripts/github_probe.py --repo owner/repo
```

脚本输出六个目标的连通矩阵和推荐通道。六个目标：`github.com`（git/网页主站）、`api.github.com`（REST API）、`raw.githubusercontent.com`（单文件）、`codeload.github.com`（源码打包）、`ssh.github.com:443`（SSH 备用入口）、本地代理端口（7890/7897/1080/8118/1087）。

### 步骤 2: 按矩阵选择通道

| 探测结果 | 选择通道 | 支持操作 |
| -------- | -------- | -------- |
| 本地代理端口可达 | 代理通道 | 全部 git 操作 |
| ssh.github.com:443 可达且本机已配置 SSH key | SSH 443 通道 | 全部 git 操作 |
| 仅 api/raw/codeload 可达 | API 降级通道 | 快照拉取、单文件、release 资产、API 推送 |

通道判定规则：探测矩阵中任何一条满足即进入对应章节；多条同时满足时代理通道优先于 SSH 443，SSH 443 优先于 API 降级。

### 步骤 3: 执行并验证

按选定通道的章节执行命令。推送后运行 `git log --oneline -1`，拉取后对比 `tar -tzf /tmp/repo.tar.gz | head` 与解压出的 `repo` 目录首层内容，向用户展示验证输出。

## 代理通道（步骤3a:git 原生操作）

**诊断**：github.com 直连超时，本地代理端口（默认探测 7890/7897/1080/8118/1087）有进程监听。

**操作**：仅对单条 git 命令挂代理，不改全局配置：

```bash
git -c http.proxy=http://127.0.0.1:7890 -c https.proxy=http://127.0.0.1:7890 clone https://github.com/owner/repo.git
git -c http.proxy=http://127.0.0.1:7890 -c https.proxy=http://127.0.0.1:7890 push
git -c http.proxy=http://127.0.0.1:7890 -c https.proxy=http://127.0.0.1:7890 pull
```

端口号以步骤 1 探测输出为准。用户要求全局生效时才执行 `git config --global http.proxy http://127.0.0.1:7890`，并告知取消命令 `git config --global --unset http.proxy`。

## SSH 443 通道（步骤3b:完整 clone/push）

**诊断**：ssh.github.com:443 TCP 可达，且 `ls ~/.ssh/id_*.pub` 存在公钥。本机（jensen 的 Mac）已完成该配置：`~/.ssh/config` 已含 github.com → ssh.github.com:443 条目，`ssh -T git@github.com` 已验证返回 "Hi linchuncheng!"，可直接使用 SSH 通道。

**操作**：写入 `~/.ssh/config`（已存在 `Host github.com` 配置时先向用户确认再改）：

```text
Host github.com
  HostName ssh.github.com
  Port 443
  User git
```

验证并使用：

```bash
ssh -T git@github.com          # 首次会提示指纹，输出 "Hi <user>!" 即成功
git clone git@github.com:owner/repo.git
```

前置条件：SSH 公钥已添加到 GitHub 账号。公钥不存在时报错停止，改走 API 降级通道，不代替用户生成密钥。

## API 降级通道（步骤3c:仅 api/raw/codeload 可达）

### 拉取源码快照（codeload tarball）

```bash
curl -sL --connect-timeout 15 --max-time 300 -o /tmp/repo.tar.gz \
  "https://codeload.github.com/owner/repo/tar.gz/refs/heads/main"
tar -xzf /tmp/repo.tar.gz -C 目标父目录 && mv 目标父目录/repo-main 目标父目录/repo
```

分支名替换 `main`；tag 替换为 `refs/tags/<tag>`。产物不含 `.git` 历史，向用户说明这是快照。

### 拉取单文件（raw）

```bash
curl -sL "https://raw.githubusercontent.com/owner/repo/main/path/to/file"
```

### 下载 release 资产（api octet-stream 直连）

github.com/releases 页面下载地址落在 github.com 域，直连超时；改走 api.github.com 资产端点：

```bash
ASSET_ID=$(curl -s "https://api.github.com/repos/owner/repo/releases/latest" | python3 -c "
import json,sys
print([a['id'] for a in json.load(sys.stdin)['assets'] if a['name']=='文件名'][0])")
curl -sL -H "Accept: application/octet-stream" -o 文件名 \
  "https://api.github.com/repos/owner/repo/releases/assets/$ASSET_ID"
```

api.github.com 返回 302 到 release-assets.githubusercontent.com，跟随重定向即可下载。列出版本号把 `releases/latest` 换成 `releases/tags/<tag>`。

### 推送本地变更（Git Data API）

github.com 的 git 传输不可达时，把本地文件变更经 REST API 提交为远端 commit：

```bash
export GITHUB_TOKEN=gh_xxx    # 需要 repo 权限的 PAT，从用户环境获取，不写入文件
python3 ~/.zcode/skills/github-access/scripts/github_api_push.py owner/repo main \
  --message "提交说明" path/to/file1 path/to/file2
```

脚本执行五步：读分支头 commit → 逐文件建 blob → 以 base_tree 建树 → 建 commit → 快进分支引用。仅标准库实现，默认读当前目录下的相对路径。覆盖「改动若干文本文件推上去」的场景；二进制大文件与批量超过 50 个文件时报告边界，建议代理或 SSH 通道。

## 使用说明

用户报 GitHub 推拉失败时，从步骤 1 开始走完整诊断流程；用户已说明「只有某些域可达」时，直接跳到 API 降级通道对应小节。所有 curl 命令必须带 `--connect-timeout` 与 `--max-time`，不允许无超时下载。涉及删除、强制推送（`git push --force`、PATCH 非快进引用）时先向用户确认。

## 错误处理

| 信号 | 处置 |
| ---- | ---- |
| 探测输出「无可用通道」 | 报告矩阵原文，请用户检查网络或启动本地代理后重跑步骤 1，不重复探测超过两次 |
| `github_api_push.py` 报 401 | token 无效或权限不足，请用户提供新的 `GITHUB_TOKEN`，不重试 |
| `github_api_push.py` 报 404 | 仓库或分支名不存在，用 `GET /repos/{owner}/{repo}` 核对后向用户确认名称 |
| 分支引用 PATCH 返回非快进错误 | 远端已有新提交，告知用户先经可用通道拉取合并，不使用 `force: true` 绕过 |
| curl 下载产物小于预期或 `file` 判定非 gzip | 删除产物重试一次，仍失败则换 `--repo` 指定仓库重测 codeload |

## 边界与禁止事项

- tarball 快照不含 git 历史，需要完整历史时改走代理或 SSH 443 通道，不模拟。
- API 推送缺少 `GITHUB_TOKEN` 时报错停止并要求用户提供，不猜测 token。
- token 只经环境变量传递，不写入命令历史、日志、SKILL.md 或任何文件。
- unauthenticated API 限额每小时 60 次，批量操作前先用 `GET /rate_limit` 检查余量。
- 不修改用户 `~/.gitconfig` 与 `~/.ssh/config` 的既有条目；新增配置前先展示内容并确认。

使用说明

# GitHub中继

github.com 直连超时的网络下，一条命令探测可达性并给出可用通道，完成 git 推拉、源码快照、release 资产下载。

## 快速使用

```bash
python3 ~/.zcode/skills/github-access/scripts/github_probe.py
```

输出六个目标的连通矩阵和推荐通道（代理 → SSH 443 → API 降级），按提示执行对应 git 命令即可。

## 典型场景

| 场景 | 通道 |
|------|------|
| clone/pull/push 超时 | 代理通道：`git -c http.proxy=http://127.0.0.1:7890 clone ...` |
| 无代理但 SSH 可用 | SSH 443：`ssh.github.com:443` 接管 github.com |
| 只有 API 可达 | 拉取走 `codeload.github.com` tarball；推送用 `github_api_push.py` |
| release 文件下载卡住 | `api.github.com` 资产端点（octet-stream） |

## 工作原理

依次探测 github.com、api.github.com、raw/codeload.githubusercontent、ssh.github.com:443 与常见本地代理端口，按「代理 > SSH 443 > API 降级」给出唯一推荐通道和下一步命令，避免逐个试错。

## 常见问题

- tarball 快照不含 git 历史，需要完整历史走代理或 SSH 443。
- API 推送需要 `GITHUB_TOKEN`（repo 权限），仅经环境变量传递。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。