GitHub CLI 省 Token 只读工具集

SKILL.md 节选

# GitHub CLI 只读 Skill (Agent专用)

## 0. 核心约束 (HARD RULES)
- **只读**：严禁任何写入/创建/合并/评论/删除操作（见§8黑名单）。
- **省Token**：必带 `--json` 裁剪字段，必带 `--limit` (默认≤10)，必用 `| jq -c` 紧凑输出。
- **超时**：所有 `gh api` 必须通过预置函数 `gh_timed` 调用。
- **缓存**：高频查询必须通过预置函数 `gh_cached` 调用。
- **重试**：网络/限流错误必须通过预置函数 `retry` 包裹。
- **缩写**：全篇使用 `O/R` 代替 `owner/repo`。
- **前置自检**：执行前必须通过 `gh auth status || gh auth login`。
- **Windows CMD**：jq 单引号改为双引号，如 `jq ".content | @base64d"`（CMD 双引号内 `|`、`>` 等特殊符需 `^` 转义）。
- **PowerShell**：推荐单引号包裹 jq 表达式（单引号内可直接写双引号，无需转义），如 `jq -c '.content | @base64d'`；单引号内表示单引号本身写作 `''`。

## 1. 预置环境声明 (Sandbox Pre-installed)
以下函数已在Agent运行时环境预置，直接调用，禁止重新实现：

| 函数签名 | 作用 |
|---|---|
| `gh_timed <args>` | 带30s超时保护的gh调用 |
| `gh_cached <args>` | 带30分钟TTL的脚本层缓存 |
| `retry <args>` | 指数退避重试(最多3次) |
| `gh_read O/R path [ref]` | 读取文件内容并自动base64解码 |
| `gh_tree O/R [depth]` | 获取目录树(默认限制3层，输出去重path列表) |
| `truncate_by_quota O/R path` | 根据TOKEN_QUOTA自适应截断大文件 |
| `gh_default_branch O/R` | 获取默认分支(封装 main→master→API 兜底探测) |

```bash
# === 预置函数实现（bash/Linux-macOS，环境启动时自动加载） ===
gh_timed() { timeout "${GH_TIMEOUT:-30}" gh "$@"; }

gh_cached() {
  local h; h=$(printf '%s' "$*" | (sha256sum 2>/dev/null || shasum -a 256) | cut -c1-16)
  local f="/tmp/gh_${h}.json"
  local mtime; mtime=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo 0)
  if [ -f "$f" ] && [ $(( $(date +%s) - mtime )) -lt 1800 ]; then cat "$f"; else gh "$@" | tee "$f"; fi
}

retry() { for i in 1 2 3; do "$@" && return 0; sleep $((i*i)); done; return 1; }

gh_read() { gh_timed api "repos/$1/contents/$2?ref=${3:-main}" | jq -r '(.content // "") | @base64d'; }

gh_tree() {
  gh_timed api "repos/$1/git/trees/main?recursive=1" \
    | jq -c ".tree[] | select(.type==\"blob\") | .path | split(\"/\")[0:${2:-3}] | join(\"/\")" \
    | sort -u | head -100
}

truncate_by_quota() {
  local quota=${TOKEN_QUOTA:-3000}
  local lines=$((quota / 8))
  [ "$lines" -gt 500 ] && lines=500
  [ "$lines" -lt 50 ] && lines=50
  gh_timed api "repos/$1/contents/$2" | jq -r "(.content // \"\") | @base64d | split(\"\n\") | .[0:$lines] | join(\"\n\")"
}

gh_default_branch() { gh_timed api "repos/$1" | jq -r '.default_branch // "main"'; }
```

### 1.1 Windows / PowerShell 适配（Agent 运行于 pwsh 7 时）
```powershell
function gh_timed { gh @args }  # gh 无原生超时；超时兜底由 sandbox 层或 §9 curl --max-time 承担

function retry {
  # Exponential backoff retry (max 3 attempts), mirrors the bash version.
  param(
    [Parameter(Mandatory = $true, Position = 0)]
    [scriptblock]$Command,
    [int]$MaxAttempts = 3
  )
  for ($i = 1; $i -le $MaxAttempts; $i++) {
    & $Command
    if ($LASTEXITCODE -eq 0) { return $true }
    if ($i -lt $MaxAttempts) { Start-Sleep -Seconds ($i * $i) }
  }
  return $false
}

function gh_cached {
  $key = (($args -join ' ') | Get-FileHash -Algorithm SHA256).Hash.Substring(0,16)
  $f = Join-Path $env:TEMP "gh_$key.json"
  if ((Test-Path $f) -and ((Get-Date) - (Get-Item $f).LastWriteTime).TotalMinutes -lt 30) {
    Get-Content $f -Raw
  } else {
    $r = gh @args | Out-String; Set-Content -Path $f -Value $r; $r
  }
}

function gh_read { param($or,$path,$ref='main') gh api "repos/$or/contents/$path?ref=$ref" | jq -r '(.content // "") | @base64d' }

function gh_tree {
  param($or,$depth=3)
  gh api "repos/$or/git/trees/main?recursive=1" |

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 3 个文件，合计 13.0 KiB