Fectivnfy112357/github-explore

github-explore

围绕 gh CLI 的发现 + 管理封装，面向 AI 编码代理。

License: MIT
Python 3.10+
Scripts: 9
Schemas: 3/9
gh CLI required

English · 简体中文

这是什么

github-explore 是一个代理技能，可将“在 GitHub 上搜索 X”转化为结构化、去重、带相关性评分的输出。它用智能过滤器、语义多轴探索和分层输出封装了 gh search 和 gh repo view，旨在让代理的上下文窗口保持较小。

当你让代理“查找多代理协作仓库”时，你不想要一个按 star 排序的转储，里面是 ollama、langchain 以及一堆不相关的通用 LLM 框架。你想要的是经典锚点（crewAI、autogen、MetaGPT、langgraph、camel、ChatDev、AutoGPT）首先浮现，协议层（A2A、ANP、ag-ui）作为单独的一个轴，而 awesome- 列表被推到最底部。这就是这个技能所做的事情。

为什么存在

对于代理驱动的研究，普通的 gh search 有三个结构性问题：

1. 默认按 star 排序 = 巨大噪声。 查询 "multi-agent" 会在顶部返回 ollama（180k★）和 langchain（140k★），因为 GitHub 按流行度排序，而不是按主题契合度排序。
2. 没有语义轴。 “搜索关于 Y 的仓库”是一个一维查询。真实主题有多个语义侧面（框架 vs. 协议 vs. 模式），应该并行探索后再取并集。
3. 输出淹没上下文。 gh search repos --json 会为每个仓库返回完整正文、日期和许可证对象。把其中 50 个管道输入 LLM 会浪费数千个 token。

github-explore 通过在 gh 之上加一层薄薄的 Python 封装，解决了这三个问题。

核心特性

- 多轴探索 — explore.py 允许代理为每个主题定义 2-4 个语义轴，并行运行它们，并用一个相关性评分对结果取并集，该评分结合了跨轴命中、经典锚点召回和 awesome-list 信号。
- 智能默认值 — 每个发现脚本默认过滤 fork 和归档仓库，强制执行最低 star 下限，按 fullName 去重，并以分层 markdown 摘要渲染（stdout 约 3KB）。
- 分层输出 — 完整报告会自动写入 %TEMP%/gh-explore-{topic}-{ts}.md；代理读取摘要，仅在需要更多细节时才拉取文件。默认探索会将你的上下文从约 18KB 降到约 2KB。
- 字段级契约 — python scripts/.py --schema 会为支持该功能的三个脚本（find_repos、explore、repo_summary）打印输出 JSON 结构，由 skills/github-explore/scripts/schemas/ 中的 schema 文件提供支持。其他脚本的 JSON 与 gh search 的原生 camelCase 字段一致（记录在 skills/github-explore/references/commands-search-format.md 中）。
- 无新增 CLI 接口 — 每个脚本都是对 gh search 或 gh repo view 的封装。你可以丢弃该 skill，手动运行相同的 gh 命令；其价值在于过滤、去重和相关性评分。

快速开始

1. 安装该 skill（Claude Code、Codex、Cursor 以及 15+ 个 agent CLI）
npx skills add Fectivnfy112357/github-explore

Hermes Agent 用户
hermes skills install https://raw.githubusercontent.com/Fectivnfy112357/github-explore/main/skills/github-explore/SKILL.md --force

2. 确保 gh CLI 已认证
gh auth status

3. 试用 — 脚本位于已安装的 skill 目录下（例如 ~/.claude/skills/github-explore/）
cd ~/.claude/skills/github-explore
python scripts/find_repos.py "vector database" --language python --min-stars 500
python scripts/explore.py "multi-agent" \
--axis "framework|multi-agent framework in:readme; collaborative agents in:readme" \
--axis "protocol|A2A agent protocol in:readme; agent-to-agent communication in:readme"

作为 DeepSeek Harness (dsh) 插件安装

同一个仓库也是一个 dsh profile bundle：其 package.json 声明了
dsh.bundle.patch，因此它可以像任何其他 dsh 插件一样安装，并在运行时注册该
skill（无需手动复制文件）。dsh plugin 会将其参数转发给 pnpm，因此任何 pnpm spec 都可用 — 从最短形式开始：

GitHub 简写（无需发布）— 最短
dsh plugin --profile web add Fectivnfy112357/github-explore

完整 git URL
dsh plugin --profile web add git+https://github.com/Fectivnfy112357/github-explore.git

裸 npm 名称 — 在此包发布后（npm publish）
dsh plugin --profile web add github-explore

本地检出 / 路径 / tarball（相同流程）
dsh plugin --profile web add /path/to/github-explore

重启 profile 后，github-explore skill 会出现在 agent 的
目录中 — 该插件（lib/index.js）解析
skills/github-explore/SKILL.md 并通过 ctx.skills 注册它，
其中 resourceBase 指向 skill 目录，以便 skill 正文中的
scripts/ / references/ 路径继续可用。使用
dsh plugin --profile web remove github-explore 移除。

作为 Agent Plugins 1.0 插件安装

该仓库也是一个 Agent Plugins 1.0 包：
plugin.json 声明了 manifest，而 skill（自包含，带有
其 scripts/ 和 references/）位于固定的 skills/github-explore/
位置。任何兼容 Agent Plugins 1.0 的客户端（ChatGPT、Codex、Cursor、
GitHub Copilot、Kiro、VS Code 等）都可以直接从该仓库加载它
(https://github.com/Fectivnfy112357/github-explore) 或从本地
检出的副本获取——无需额外构建步骤：

git clone https://github.com/Fectivnfy112357/github-explore.git
point your client at the repo root: plugin.json + skills/github-explore/SKILL.md

一个仓库，三种安装路径——npx skills add（标准 skills）、
dsh plugin --profile web add（DeepSeek Harness），以及任何 Agent Plugins 1.0
客户端都读取相同的文件。

每条命令都会向 stdout 写入一份分层 markdown 摘要（约 3KB），并将完整报告写入临时文件。传入 --format json 可获得机器可读输出（需显式指定；通过管道传递不会自动切换）。

仓库布局

单个仓库服务于全部三种打包格式；该 skill 在 Agent Plugins 固定位置下完全自包含，
因此无论哪个安装器复制它，其行为都完全一致：

github-explore/
├── plugin.json                    # Agent Plugins 1.0 manifest ($schema + name required)
├── skills/
│   └── github-explore/            # the one skill, fully self-contained
│       ├── SKILL.md               #   skill body (frontmatter: name/description)
│       ├── scripts/               #   9 entry scripts + _lib.py + schemas/
│       └── references/            #   gh command references (commands-.md)
├── package.json                   # dsh plugin (dsh.bundle.patch) + npm metadata
├── cordis.patch.yml               # dsh loader patch (inserts the skill entry)
├── lib/index.js                   # dsh plugin: registers the skill via ctx.skills
├── README.md / README_zh.md
└── LICENSE

- Agent Plugins 1.0 读取 plugin.json + skills//SKILL.md（以及可选的 mcp.json）。
- dsh 读取 package.json → dsh.bundle.patch → cordis.patch.yml → lib/index.js。
- npx skills add 会发现 skills//SKILL.md 并安装整个
skill 目录（包含 scripts + references）。

脚本

| 脚本 | 用途 | --schema | 备注 |
|---|---|---|---|
| find_repos.py | 带多维过滤器的智能仓库搜索 | ✅ | 默认入口点。多词自由文本会运行双范围（in:readme + 默认）以进行概念性召回。 |
| explore.py | 多轴主题探索 | ✅ | Agent 内联定义各轴。输出规范锚点 + 跨轴命中 + 每轴前 5 个。 |
| discover.py | 从种子搜索自动扩展主题 | ❌ | 读取种子搜索的顶部结果，提取其主题，按主题分别运行搜索。快速、机会主义。 |
| trending.py | 按时间窗口的热门仓库 | ❌ | 默认 7 天窗口；支持 --topic、--language、--min-stars。 |
| repo_summary.py | 深入分析单个仓库 | ✅ | 主题、语言、近期活动、可提及用户、许可证。 |
| find_similar.py | 给定仓库的替代方案 | ❌ | 跨语言选项（--no-language）。 |
| code_search.py | 按模式进行 GitHub 代码搜索 | ❌ | --repo、--org、--owner、--extension、--filename。 |
| search_issues.py | Issue/PR 搜索 | ❌ | --state、--type、--label、--author、--assignee。 |
| org_landscape.py | 审计整个组织 | ❌ | --group-by {language,topic,activity,stars}。 |
| _lib.py | 共享辅助函数 | 不适用 | ensure_auth、gh_json、parse_since、print_schema。不供直接使用。 |
| __init__.py | 模块文档字符串 | 不适用 | 记录 scripts 包。 |

--schema 缺口： 9 个脚本中有 6 个尚未将 --schema 作为 CLI 标志暴露出来。提供该标志的三个脚本——find_repos、explore、repo_summary——覆盖了最常用的路径，并由 repo.schema.json / explore.schema.json / repo_summary.schema.json 提供支持。

架构

┌─────────────────────────────────────────────┐
│           Agent (LLM, coder, etc.)         │
│  - reads SKILL.md for trigger + protocol   │
│  - decides which script + which axes       │
└──────────────────┬──────────────────────────┘
│ python scripts/.py [args]
▼
┌────────────────────────────────────────────────────┐
│  skills/github-explore/scripts/                   │
│  (9 entry points + _lib + __init__)               │
│  ─────────────────────────────────────────────────│
│  find_repos   explore   discover   trending       │
│  repo_summary find_similar code_search            │
│  search_issues org_landscape                       │
│                                                    │
│  shared: _lib.ensure_auth, _lib.gh_json,           │
│          _lib.print_schema, _lib.parse_since       │
└──────────────────┬─────────────────────────────────┘
│ subprocess.run(['gh', ...])
▼
┌────────────────────────────────────────────────────┐
│  gh CLI  (search repos / repo view / search code)  │
│  Authenticated via gh auth status.                 │
└──────────────────┬─────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│  GitHub REST + Search API                          │
│  ~5000/hr core / ~30/min search (authenticated)    │
└────────────────────────────────────────────────────┘

Output:
- stdout:  ~3KB layered markdown summary (default)
- stdout:  full JSON when --format json (explicit)
- disk:    %TEMP%/gh-explore-{topic}-{ts}.md (always)
两层结构，一个心智模型。 脚本负责发现（搜索 / 去重 / 评分 / 渲染）。直接调用 gh 负责管理（创建 / 更新 / 合并 / 打标签 / 工作流）。references/commands-.md 文件记录了管理侧的内容，而不会让 SKILL.md 变得臃肿。

何时使用什么

| 任务 | 工具 |
|---|---|
| 查找关于某个主题的仓库 | find_repos.py "" |
| 绘制某个领域的完整图景 | explore.py "" --axis ... |
| 自动扩展到相关主题 | discover.py "" |
| 查看最近发布了什么 | trending.py --window 7d |
| 了解某个仓库的详情 | repo_summary.py owner/repo |
| 查找替代方案 | find_similar.py owner/repo |
| 这个模式在哪里被使用？ | code_search.py "" --org ... |
| 搜索 issue / PR | search_issues.py "" |
| 审计一个组织 | org_landscape.py  |
| 创建仓库、发起 PR、打标签、运行 CI | gh （参见 references/commands-.md） |

值得了解的设计决策

以下是该技能做出的非显而易见的决策，呈现出来是为了让你不必去逆向推导它们：

1. 对于多词自由文本，in:readme 是默认值。 Description 太短，无法区分主题。find_repos 运行两个范围并取并集，对 in:readme 命中给予相关性加分，以让规范的小型项目排在通用的大型仓库之上。
2. --exclude 是后置过滤器，而非查询词元。 GitHub 的 -term 排除对于 awesome 列表和教程并不可靠；该技能在合并阶段基于 fullName / description 子串进行过滤。
3. awesome-* 目录被标记为 ☰list 并大幅降权，而非删除。它们是另一种产物（策展 vs. 代码），应出现在真实项目之下，但仍可被找到。
4. 按 star 排序是回退方案，而非默认方案。 explore.py 按相关性评分排序，该评分结合了规范锚点召回、跨轴命中和对数缩放的 star 数。一个 100★ 的规范锚点总能击败一个仅仅提及该主题的 200k★ 仓库。
5. 输出是分层的，而非内联的。 Stdout 保持在约 3KB 以下；完整结果写入临时文件。当 agent 循环处理多个主题时，这是最大的上下文节省手段。

贡献

欢迎提交 issue 和 pull request。这是一个在多次实际使用中重构出来的个人技能；测试面是脚本本身，而非单元测试套件。

在发起 PR 之前：

1. 确保受影响的脚本仍能通过 python scripts/.py --help 以及（在支持的情况下）--schema。
2. 如果你添加了新脚本，请在脚本表中添加一行，并考虑它是否需要在 skills/github-explore/scripts/schemas/ 下添加 schema 文件。
3. 保持分层输出约定：stdout 摘要 + 临时文件完整报告，没有例外。

许可证

MIT。参见 LICENSE。

致谢

由贾晓源（@Fectivnfy112357）构建和维护。