GitHub CLI (gh) + Discovery Scripts

Overview

两个层：scripts/ 里 9 个 Python 脚本负责搜索/发现/审计（统一过滤 fork/archived、默认 star 下限、智能去重、relevance 排序、分层摘要+落盘），直接调用 gh 负责管理操作（建 repo、提 PR、改 label、跑 workflow 等）。脚本已做搜索 gotchas 处理，发现类请求优先用脚本。

所有脚本输出格式 --format {table,json,markdown}，默认 markdown（分层摘要 + 落盘），json 供管道处理，table 窄终端 ASCII 视图。注意：不会因为 stdout 被管道就自动切 JSON——要 JSON 必须显式 --format json（见 Common Pitfalls #1）。

安全边界（Security boundaries）

• 默认只读：9 个发现类脚本（find_repos / discover / explore / trending / repo_summary / find_similar / code_search / search_issues / org_landscape）只读，不改远端状态。
• 写操作需确认（全 commands-*.md 适用，含 commands-auth-config.md 与 commands-search-format.md）：管理类 gh 写命令会改变远端状态、本机凭据或配置。执行前必须向用户明确：目标（哪个 repo / org / 资源 / host）、影响范围（改什么、是否可逆、是否触发下游）、最小改动数据，并得到明确确认后再执行。未经确认绝不执行写操作。具体适用范围与例外见 references/SECURITY-NOTES.md。
  • 远端写：create / update / delete / close / merge / dispatch / rerun / cancel / set-default / fork / deploy-key …
  • 凭据写（commands-auth-config.md）：gh auth login/logout/switch/setup-git/refresh --scopes …——影响本机 git credential helper 与 token scopes，refresh --scopes 是权限提升。
  • 配置写（commands-auth-config.md）：gh config set … / gh config clear-cache——改 ~/.config/gh/。
  • API mutation（commands-search-format.md）：gh api --method POST|PUT|DELETE|PATCH …；gh api graphql 中含 mutation 的 query——可触达任意 GitHub 资源（含 admin endpoint），影响面比 gh issue / gh pr 子命令更广。
• 禁止回显 token：认证诊断只用 gh auth status（不回显 token）。禁用 gh auth token、gh auth status --show-token、--with-token 注入；GH_TOKEN 仅用于自动化（CI），不得打印到 transcript。
• 错误脱敏（honest scope）：9 个发现脚本内部走 _lib.warn/die() 的 redact_secrets() 路径，自动遮 ghp_* / github_pat_* / Bearer * / token=* / GH_TOKEN=* / GITHUB_TOKEN=* 形态。但 agent 在 Bash 工具里直接跑 gh … 时，stderr 不经过 Python wrapper，原样进 transcript——分享前手动管道 gh <cmd> 2>&1 | python scripts/redact_stderr.py。脱敏是 best-effort，非常规 token 形态仍可能漏出。
• GH_HOST / GitHub Enterprise 风险：GH_HOST 会切换所有 gh 子命令的 API 流量目的地（纯 git 操作如 git push 不受 GH_HOST 影响，跟 git remote 走）；默认 github.com。切到 GHES on-prem（github.acme.com）必须用 GH_ENTERPRISE_TOKEN 而非 GH_TOKEN；切到 GHEC 租户（*.ghe.com）用 GH_TOKEN。--hostname 不是全局 flag，只在 auth / api / attestation 等约 11 个子命令上存在；通用切换姿势是 GH_HOST=... gh <cmd> 或 gh auth switch --hostname X。gh auth status 默认枚举所有已认证 host，不是只校验当前。skill 不限制、不校验、不警告 host 值——用户负责确保目的地正确；跨 host 误调用 = 跨凭据泄漏（写错组织的 issue / 错仓库开 PR / 错 token 触发 GHES workflow）。

When to Use

• 「找 X 相关的 repo」「search repos about Y」→ find_repos.py
• 「摸清 X 领域全貌」「map out the field」→ discover.py（快）或 explore.py（有目的地多维度）
• 「最近热门 / trending」→ trending.py
• 「这个 repo 怎么样 / overview」→ repo_summary.py
• 「跟 X 类似 / alternatives」→ find_similar.py
• 「找代码片段 / where is pattern used」→ code_search.py
• 「找 issue/PR」→ search_issues.py
• 「审计整个 org / 按语言/活跃度/主题分组」→ org_landscape.py
• 「建 repo / 提 PR / 改 label / 跑 workflow」→ 直接 gh（命令索引见 references/ 下的 commands-* 系列，按类型查）；写操作执行前必须明确目标/影响/最小数据并得到用户确认（见「安全边界」）
• 不要用脚本做：管理类写操作（创建/修改/删除）。

When to use which script — the deeper logic

• 单维问题（搜 repo / 看 repo / 找 issue）→ 单发脚本。find_repos.py 是默认起点。
• 多词自由文本：find_repos 默认跑双 scope（in:readme + 默认 scope）再 union，用「star 数 + 软 relevance 加成」排序——没有这个，高星通用 repo（如 ollama 之于 "observability platform"）会挤掉更对题的小项目。--no-semantic 关掉回到单搜索。
• 稀疏结果：find_repos 返回 <5 且无 narrowing qualifier 时，stderr 会提示改用 explore.py 配显式 axes——概念型主题单轴搜覆盖不了。
• 数据驱动拓主题：discover.py 从 seed 结果自动挖 topics 再逐个搜。快、便宜，但质量取决于 seed 是否干净。适合没有清晰维度概念时。
• 有目的地语义探索（"map multi-agent collaboration"）→ explore.py + 内联 axes。agent 决定维度，脚本并行执行并输出软验证信号（awesome 交叉、跨轴计数、canonical 召回）。字段级探索用这个。
• discover 机会主义快；explore 刻意广。默认决策：先 find_repos，稀疏或多维就升级 explore。

Quick start

# 搜索（多词自由文本自动双 scope + relevance）
python scripts/find_repos.py "vector database" --language python --min-stars 500

# 自动拓主题（快）
python scripts/discover.py "agent framework" --depth 6 --per-topic 5

# 有目的地多维度探索（inline axes，agent 定维度）
python scripts/explore.py "multi-agent" \
    --axis "framework|multi-agent framework in:readme; collaborative agents in:readme" \
    --axis "protocol|A2A; ANP; agent-to-agent"

# 时间窗 trending
python scripts/trending.py --window 7d --language rust
python scripts/trending.py --window 1m --topic llm --min-stars 100

# 单发
python scripts/repo_summary.py langchain-ai/langchain --format markdown
python scripts/find_similar.py vercel/next.js --limit 20
python scripts/code_search.py "def authenticate" --language python
python scripts/code_search.py "useEffect" --org vercel --extension tsx
python scripts/search_issues.py "memory leak" --repo langchain-ai/langchain
python scripts/search_issues.py "is:open is:issue label:bug" --org langchain-ai

# Org 审计
python scripts/org_landscape.py vercel --group-by language
python scripts/org_landscape.py langchain-ai --group-by activity

Common options (多数脚本共享)

• --format {table,json,markdown} — 默认 markdown。json 管道处理，table 窄终端。
• --limit N / --min-stars N — 上限 / star 下限。
• --include-forks / --include-archived — 默认都排除，opt-in。
• 时间过滤：--pushed-since 30d、--created-since 1y（后缀 d/w/m/y）。

find_repos.py 特定

• --semantic（默认开）/ --no-semantic：多词自由文本无 narrowing 时跑双 scope + union + relevance 排序。--no-semantic 回到单搜索。
• narrowing qualifier 会关掉 dual-scope：--language、--topic、--owner、--org、--license、--pushed-since、--created-since、--max-stars 任一出现 → 单搜索（否则 in:readme 会让 awesome-list 压过真实项目）。
• --max-stars 也计入 narrowing（stars:<=N）。
• JSON 输出带 _rel 字段（0-3 relevance 分）。
• 用户 --owner → user: qualifier；--org → org: qualifier（与 search_issues 一致）。

explore.py（"map the field" 模式）

• 轴由 agent 定，无维护 taxonomy 文件。--axis "name|q1; q2 OR q3"（; 或带空格的 OR 拆多角度，结果 union）。--limit-per-axis 默认 20。
• 查询要具体：agent framework 会被 100k+ 星通用 repo 淹没；multi-agent framework in:readme 更准。语义查询建议 in:readme。
• 抽象/多义主题必须拆轴，不能直接搜主题词（见下方"轴设计方法论"，这是抽象主题能否可用的关键）。
• --exclude TERM（可重复，通用噪音过滤）：匹配 fullName/description 子串，大小写不敏感。对抽象主题几乎必用：--exclude awesome（目录不是项目）、--exclude tutorial、--exclude demo、--exclude osint 等。脚本在后合并阶段统一过滤，跨所有轴、与查询写法无关——比在查询里拼 -term 可靠（实测 GitHub 的 -term 排除词经常失效，awesome-* 目录仍会混入）。
• *awesome- 目录自动标记 ☰list 并重度降权（-1000，不删除）**：目录 vs 项目语义不同。探项目类主题时它们沉到所有真实项目之后（可能被 --limit-per-axis 挤出 top N）；若主题本身是资源合集/awesome 目录（"awesome X 有哪些"），别用 explore 轴——用 find_repos.py "awesome <topic>" 直接搜目录。
• --min-stars 挡不住语义噪音：它只过滤低星，高星通用仓库（dify/OpenHands/torvalds/linux 这种 readme 概念密度高的）照样进来。去噪靠查询精确化 + --exclude，不是抬高 min-stars。
• 输出分层：默认 stdout ≤ ~3KB——canonical anchors → 跨轴命中 → top 5/轴；--full 把完整报告打到 stdout；完整报告总是写盘（%TEMP%/gh-explore-{topic}-{YYYYMMDD-HHMMSS}.md，--output PATH 改路径，--output 隐含 --full）。
• 排序 relevance_score：_is_canonical 100万 > _backfilled 10万 > _in_awesome 1万 > 跨轴数×1000 > log10(stars+1)×10，_is_list（awesome 目录）−1000 沉底。100 星 canonical 锚点永远压过 20 万星只提一嘴的通用 repo。
• 信号 flag：★canonical（代码内建的必出锚点集，multi-agent/rag/agent 主题）、↻Naxes（N 轴都出现）、✓awesome（在 awesome list 里）、☰list（是 awesome 目录，不是项目）、⚑backfilled（anchor 缺失时用 core API 补拉）。
• --awesome 真实成本（重要，配额敏感）：每个 slug 变体 1 次 gh search + 找到后 1 次 readme API。多词 topic 最多 ~8 个变体 → 最多 ~8 次 search + 1 次 readme，不是 1-2 次。默认关闭；要交叉验证才开。
• canonical backfill 用 core API quota（5000/hr），不占 search quota（30/min），search 限流后仍可用。
• canonical 锚点只覆盖热门主题（multi-agent/rag/agent）：抽象新概念主题（"主动智能""自反馈自优化"）拿不到锚点验证，此时轴设计的信噪比检查就是唯一的质控手段——跑完看是否有轴被无关巨仓淹没，有就缩查询加排除。
• 轴质量观察指标（explore 自动输出，供判断非定论）：每轴自动算 3 个原始信号——semantic_hit_rate（repo 描述命中查询显著词的比例）、list_dir_ratio（awesome 目录占比）、top3_giant（top3 是否全是 5 万+ 巨仓），JSON 模式在 axes[i].quality，table 在轴名后标 低命中/☰d/⇧巨仓，markdown 在轴标题下加一行注释。只观测不下结论：语义主题（in:readme 召回）的命中率天然偏低，会被误伤，所以指标是给 agent 看的线索，不是自动 verdict，绝不自动改查询。

轴设计方法论（抽象/多义主题必读）

抽象主题（人机协作、主动智能、自反馈自优化……）直接用主题词搜索必被泛词噪音淹没。通用拆法：

1. 拆成 2-4 个"可查询的具体语义单元"，不是搜主题词本身。例：主动智能 → proactive assistance / anticipatory computing / agentic OS / autonomous agent operating system。
2. 每个轴给 1-3 个查询角度，角度要带限定词避免裸宽词。裸 proactive AI 会被 100k+ 通用 repo 淹没；proactive context-aware AI partner in:readme 才能捞到 MineContext 这种真相关项目。
3. 宽泛查询会退化为按 star 排序的宽匹配：当轴查询太宽（如 AI operating system in:readme），GitHub 直接返回 torvalds/linux、vllm 这种巨仓——信噪比检查的信号：若某轴 top 全是明显无关的大仓库，说明查询太宽，缩到更具体语义。
4. 用 --exclude 处理可枚举的噪音类别：awesome、tutorial、demo、osint、course、example……抽象主题几乎必用。
5. min-stars 是最后手段：只在低星噪音泛滥时抬它，别指望它去噪。
6. 先小后大：先跑 2 轴验证信噪比，确认轴方向对了再扩到 4 轴，避免 8 轴全被污染浪费配额。

脚本输出 schema（--format json 通用）

所有发现类脚本 --format json 返回相同字段命名（GitHub API 原生 camelCase，不是 snake_case）。不要猜字段——读契约的两种方式：

1. python scripts/<script>.py --schema（仅 3 个脚本支持：find_repos / explore / repo_summary，以及通过 _lib.print_schema 间接调）
2. 直接看 explore.schema.json / repo.schema.json / repo_summary.schema.json 三个契约文件（位于脚本目录下的 schemas 子目录；其他 6 个脚本的输出结构以 gh search 原生 JSON 字段为准，参考 references/commands-search-format.md）

三个契约文件的关键差异（猜错必踩的坑）：

各脚本完整参数以 python scripts/<name>.py --help 为权威。管道要 JSON 必须显式 --format json。

命令索引（references/，按需查阅）

管理类操作直接 gh，具体命令按类型查对应文件，不内联复制：

搜索 gotchas（脚本已处理，agent 不必重踩）

1. gh search 的 OR 不符合直觉——"A OR B" 返回 0 结果。用 ; 或带空格 OR 拆多 query。
2. 语义查询用 in:readme，description 太短。
3. topic: 作为硬过滤不可靠（项目打标签不一致）；优先 stars:>=。
4. GitHub 限流：认证 ~5000/hr API + search 30/min。脚本默认 --max-workers 2 守住 30/min；撞 403/429 有重试但会慢。8 轴 × 3 角度 = 24+ 次调用，注意配额。
5. gh search repos 的 JSON 没有 topics 字段（只有 gh repo view 有）。discover.py 因此用 N+1 次 repo view 取 topics（只取前 10 个 seed）；find_repos 因此不做 self-echo 过滤。
6. 更多结果 ≠ 完整结果：文本搜索漏知名项目（prometheus 不写 "observability platform"）。生态型问题直接上 explore.py --awesome。

组装脚本（管道友好）

所有脚本 --format json 输出合法 JSON，可链式：

python scripts/discover.py "agent framework" --format json \
  | python -c "import json,sys; r=json.load(sys.stdin)['topics']; print('\n'.join(t for t,v in r.items() if v))"
python scripts/trending.py --window 30d --format json \
  | python -c "import json,sys,datetime; d=json.load(sys.stdin); print(len(d), 'trending repos')"

Common Pitfalls

1. 以为管道会自动 JSON（__init__.py 旧 docstring 说 "auto-select JSON when piped"——假话）。实际默认恒 markdown，要 JSON 必须 --format json。写管道命令时显式加 --format json，否则得到 markdown 文本无法 json.loads。
2. explore 不传 --axis：die("Provide axes via --axis")。axes 是必须的，不是可选。
3. --awesome 成本低估：多词 topic 会触发最多 ~8 次 gh search + 1 次 readme，配额紧张时慎用，或只对最终 topic 跑一次。
4. explore 查询太泛：agent framework 直接被大 repo 淹没。多角度、带 in:readme、带主题词。
5. gh search repos JSON 字段是复数 stargazersCount/forksCount；gh repo view 是单数 stargazerCount/forkCount。手写 jq 时别混。
6. repo_summary 的 users 段是 mentionableUsers（仓库可见的可 @ 成员），标题叫 "Mentionable users"——不是 "被提及最多的用户"，别误解成社区活跃度。
7. Windows 路径：git-bash 下用 C:/... 或 /c/...；反斜杠结尾会转义错。

Verification Checklist

• 用了正确的脚本（发现→脚本，管理→裸 gh）
• 管道场景显式 --format json
• explore 查询角度具体且带 in:readme（语义主题）
• 配额敏感时 --max-workers 2、--awesome 只跑一次
• org/repo 审计确认了过滤条件（fork/archived/stars）符合预期
• 管理操作按类型查 references/ 下的 commands-* 系列（不内联复制，不误用脚本）
• 发现类任务只用只读脚本，未触发任何远端写
• 写操作前已向用户明确目标/影响/最小数据并获得确认
• 认证诊断只用了 gh auth status，未回显任何 token