Sourcemux Go

SourceMux

[](https://github.com/500tpig/sourcemux-go/actions/workflows/ci.yml) [](go.mod) [](LICENSE)

[中文](#中文) | [English](#english)

> SourceMux is a single-binary CLI + stdio MCP agent research router. > It gives agents fast/default search for one-hop work, profile=auto heavy > Grok research when configured, and policy-first URL fetch with quality, > GitHub-aware, and cheap profiles. > > Packaging status: the current verified public baseline is v0.2.1 > (checked 2026-06-03): GitHub Release assets, the Homebrew cask in > 500tpig/homebrew-tap, the Scoop manifest in 500tpig/scoop-bucket, and > the npm package sourcemux are published. Future package-manager claims > still need per-release verification before the docs describe them as > available.

中文

SourceMux 是一个面向 AI Agent、MCP 客户端和命令行自动化的单二进制 CLI + stdio MCP 研究路由器。它把 Grok / OpenAI-compatible endpoint pool、TinyFish、Exa、Tavily、Jina、Firecrawl 等能力接到统一 fallback route：普通查询走快速默认搜索，research / smart-answer 默认用 profile=auto 在适合时切到已配置的 heavy / multi-agent Grok 搜索，URL 抓取默认走 policy-first / quality-first 策略，GitHub URL 优先走 repo-aware enrichment，cheap/zero-key 模式才走 Jina-first。

Firecrawl 通过 SourceMux 自己的 CLI direct commands 和普通 fetch routing 使用，不是 Firecrawl MCP server 集成。默认 fetch --profile auto 在 Firecrawl 配置可用时会把普通网页放到质量优先路线，但不会默认开启 Firecrawl clean-content；fetch --profile quality 才会打开该额外清理。 fetch --profile cheap 才用于轻量、低成本、零 key 优先的 Jina-first 路线。

仓库默认只保存安全示例配置。真实 API key 只应该放在本地 sourcemux.json，或用 --config /path/to/sourcemux.json 显式指定的本地配置文件里。不要提交真实密钥、私有 provider endpoint 或 provider dashboard 导出文件。

适合什么时候用

• 你希望 AI 助手联网搜索当前信息，但要保留可复现的 CLI 命令和 JSON 输出。
• 你想抓取一个 URL 正文，或把网页内容交给后续 Agent / 脚本处理。
• 你想查官方文档、API、SDK、框架用法，并通过 Exa 做文档 / web 搜索。
• 你想生成一个可审计的轻量 research pack：先规划搜索，再收集来源，最后抓取关键页面。
• 你想把同一套搜索能力接入 Codex、Claude Code、Cherry Studio 等 MCP 客户端。

默认路由

| 能力 / 命令 | 默认路线 | | --- | --- | | web_search / sourcemux search | Grok endpoint pool -> TinyFish Search -> Exa Search -> Tavily Search | | web_fetch / sourcemux fetch --profile auto | GitHub Provider for GitHub URLs; otherwise Firecrawl -> Jina Reader -> Exa Contents -> Tavily Extract -> TinyFish Fetch | | sourcemux fetch --profile cheap | Jina Reader -> Firecrawl -> Exa Contents -> Tavily Extract | | docs_search / sourcemux docs-search | Exa docs/web search fallback | | research_run / sourcemux research | 规划 query -> 搜索 -> 收集来源 -> 排序 URL -> 抓取高价值页面（默认 --profile auto） | | smart_answer / sourcemux smart-answer | 先跑 bounded research（默认 --profile auto），再交给配置好的 reasoning endpoint 综合回答 |

为什么不是只用 Jina 或普通搜索

• Jina Reader 是轻量、零 key 的 URL 正文提取 fallback；它不是质量默认，也不是搜索、文档检索、heavy Grok 或最终综合能力的上限。
• 普通搜索适合一次性找结果；SourceMux 额外提供 agent 友好的 route、fallback、get_sources、fetch 验证、bounded research pack 和可复现 JSON。
• 对复杂、当前、对比或高风险问题，research / smart-answer 默认 profile=auto，可以在配置了 heavy Grok profile 时自动用更强搜索，同时仍保留 fallback。

公开用户快速开始

公开用户流程需要先把 sourcemux 安装到 PATH。当前已核验的公开发布基线 （2026-06-03）是 v0.2.1：GitHub Release assets、500tpig/homebrew-tap 里的 Homebrew cask、500tpig/scoop-bucket 里的 Scoop manifest、以及 npm 包 sourcemux 都已发布。之后每个版本仍必须先核验 tag、GitHub Release、 tap/cask、bucket manifest 和 npm registry， 再在文档中声称对应包管理器通道可用。普通用户建议显式使用全局配置文件： ~/.config/sourcemux/sourcemux.json。

任选一个已发布安装通道：

go install github.com/500tpig/sourcemux-go/cmd/sourcemux@latest

GitHub Release 下载页：

https://github.com/500tpig/sourcemux-go/releases/tag/v0.2.1

brew tap 500tpig/tap
brew install --cask sourcemux

不要直接用 brew install sourcemux，除非 SourceMux 之后也进入了 Homebrew core；本项目发布路径是上面的 tap/cask。

scoop bucket add 500tpig https://github.com/500tpig/scoop-bucket.git
scoop install 500tpig/sourcemux

npm install -g sourcemux
npx sourcemux version

确认安装：

sourcemux version
sourcemux config path

生成用户级配置：

sourcemux --config ~/.config/sourcemux/sourcemux.json setup --non-interactive \
  --api-url "https://your-grok-compatible-endpoint.example/v1" \
  --api-key "sk-your-key" \
  --model "grok-4.20-fast" \
  --json

检查配置，输出会遮蔽 key：

sourcemux --config ~/.config/sourcemux/sourcemux.json config list --json
sourcemux --config ~/.config/sourcemux/sourcemux.json doctor --json

跑一次搜索：

sourcemux --config ~/.config/sourcemux/sourcemux.json search "今天 Go 生态有哪些重要更新？" --agent

显式跑较慢的 heavy Grok 搜索时，用户面向的研究应保留 fallback；只有诊断 profile 本身是否可返回时才禁用 fallback：

sourcemux --config ~/.config/sourcemux/sourcemux.json search "复杂搜索问题" --profile heavy --fallback-after 180s --timeout 300s --agent
sourcemux --config ~/.config/sourcemux/sourcemux.json search "ping" --profile heavy --grok-pool-timeout 0 --no-fallback --timeout 120s --json

抓取网页正文：

sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile auto --agent
sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile cheap --agent

--agent 适用于 search / fetch / research，会隐含 JSON 输出，并返回短 JSON：source id、质量分、warnings 和 next actions。普通 --json 的完整 envelope 契约不变，仍适合脚本和调试。

普通已知 URL 先用 fetch --profile auto：GitHub repo / issues / releases / blob / tree URL 会优先走 GitHub enrichment，普通网页在 Firecrawl 配置可用时 优先用 Firecrawl 抓取，再 fallback 到 Jina / Exa / Tavily / TinyFish。 默认 Firecrawl fetch 对齐官方 scrape 默认值，不开启 clean-content；需要额外 清理时用 fetch --profile quality。 只有明确要低成本或零 key sanity check 时才用 fetch --profile cheap。需要 Firecrawl-specific flags 时使用 firecrawl-scrape；站点结构、URL 盘点或按 主题发现站内链接时才用 firecrawl-map。不要安装或调用 Firecrawl MCP。

本地配置示例（只在本机配置文件里填真实 key，不要发到聊天里）：

{
  "firecrawl": {
    "apiURL": "https://api.firecrawl.dev/v2",
    "apiKey": "fc-your-key",
    "enabled": true
  }
}

显式 v2 fetch 顺序配置示例（--profile auto 会尊重这个顺序；未写 v2 顺序时 使用默认 policy-first 质量策略）：

{
  "version": 2,
  "minimum_profile": "off",
  "capabilities": {
    "main_search": {"providers": []},
    "docs_search": {"providers": []},
    "web_fetch": {
      "providers": [
        {
          "type": "firecrawl",
          "apiURL": "https://api.firecrawl.dev/v2",
          "keys": [
            {"name": "acct-a", "apiKey": "fc-your-key-a"},
            {"name": "acct-b", "apiKey": "fc-your-key-b"}
          ],
          "enabled": true
        },
        {"type": "jina", "apiURL": "https://r.jina.ai"}
      ]
    },
    "web_enhance": {"providers": []}
  }
}

填好本地 key 后，smoke 覆盖这三条：

sourcemux --config ~/.config/sourcemux/sourcemux.json fetch "https://example.com" --profile auto --json \
  | jq -e '.policy.effective_profile == "auto" and (.content | length > 0)'

sourcemux --config ~/.config/sourcemux/sourcemux.json firecrawl-scrape "https://example.com" --json \
  | jq -e '.source == "Firecrawl Scrape" and .route_decision[0].provider == "firecrawl-scrape" and (.content | length > 0)'

sourcemux --config ~/.config/sourcemux/sourcemux.json firecrawl-map "https://example.com" --search "docs" --limit 100 --json \
  | jq -e '.source == "Firecrawl Map" and .route_decision[0].provider == "firecrawl-map" and (.count >= 0)'

离线生成结构化 research plan（不调用网络）：

sourcemux --config ~/.config/sourcemux/sourcemux.json plan "对比当前 Go module proxy 方案的风险" --json --depth deep

查库 / 框架 / SDK 文档：

sourcemux --config ~/.config/sourcemux/sourcemux.json docs-search "next.js middleware auth" --json

生成研究包：

sourcemux --config ~/.config/sourcemux/sourcemux.json research "Evaluate the current status of Go modules" --depth deep --profile auto --agent

安装 Agent 路由 skill 时，用户级 scope 会默认使用 ~/.config/sourcemux/sourcemux.json，无需再把源码 checkout 的 ./sourcemux.json 带进全局 skill：

sourcemux bootstrap list-agents
sourcemux bootstrap codex --scope user --dry-run
sourcemux bootstrap codex --scope user
sourcemux bootstrap status --scope user --config-status

bootstrap status --json 会用生成 skill 的 manifest 检查 binary_status、runtime_config_status 和 scope_status；常见问题码包括 missing_binary、stale_binary、missing_config、stale_config 和 wrong_scope。修复时用目标 scope 更新明确的二进制与配置路径：

sourcemux bootstrap update  --scope  --binary  --config 

不要把 user-scope skill 静默切到源码 checkout 的配置，也不要假设隐藏配置 fallback。

只有需要安全合并 Codex/Gemini/OpenCode MCP 客户端配置时才加 --write-config：

sourcemux bootstrap codex --scope user --write-config --dry-run --json

从源码开发

源码 checkout 适合维护者或本地开发。开发模式默认使用项目配置 ./sourcemux.json，并且生成 project-scope skill：

git clone https://github.com/500tpig/sourcemux-go.git
cd sourcemux-go
go build -o sourcemux .
./sourcemux --config ./sourcemux.json setup --non-interactive \
  --api-url "https://your-grok-compatible-endpoint.example/v1" \
  --api-key "sk-your-key" \
  --model "grok-4.20-fast" \
  --json
./sourcemux bootstrap codex --scope project --binary "$(pwd)/sourcemux"

配置文件

SourceMux 只读取一个显式 JSON 配置文件：

• 默认：./sourcemux.json
• 显式：sourcemux --config /path/to/sourcemux.json
• 兼容旧写法：sourcemux cli --config /path/to/sourcemux.json

它不会自动扫描环境变量配置链、~/.config/sourcemux/* 或旧的 endpoints.json。公开用户流程使用全局配置时，必须像上面的例子一样显式传 --config ~/.config/sourcemux/sourcemux.json；bootstrap --scope user 只是把这个路径作为生成 skill 的默认显式配置路径。如果你已有旧版 grok-search.json，可以改名：

mv grok-search.json sourcemux.json

也可以继续显式指定旧文件：

sourcemux --config ./grok-search.json config list --json

最小配置示例：

{
  "grokEndpoints": [
    {
      "name": "primary",
      "baseURL": "https://your-grok-compatible-endpoint.example/v1",
      "apiKey": "sk-your-key",
      "model": "grok-4.20-fast",
      "sendSearchFlag": false
    }
  ],
  "grokPoolTimeoutSec": 45,
  "logLevel": "INFO"
}

安全示例文件：

• [configs/sourcemux.example.json](configs/sourcemux.example.json)
• [configs/sourcemux.reasoning.example.json](configs/sourcemux.reasoning.example.json)

常用命令

| 命令 | 用途 | | --- | --- | | sourcemux search | 按 fallback route 做一次网页搜索 | | sourcemux docs-search | 文档搜索；使用 Exa docs/web search fallback | | sourcemux fetch | 抓取一个 URL 的正文 | | sourcemux map | 用 Tavily 发现站点 URL | | sourcemux crawl | 用 Tavily 抓取站点内容 | | sourcemux plan | 离线生成搜索 / research plan；默认文本兼容，--json 输出结构化计划 | | sourcemux research | 生成 bounded research pack；Agent 默认用 --agent 看短 JSON | | sourcemux smart-answer | research 后交给 reasoning endpoint 综合 | | sourcemux eval-research | 用离线 fixture cases 验证 research 排序、fetch 和 facts 抽取质量 | | sourcemux config path/files/list | 查看当前配置路径和遮蔽后的有效配置 | | sourcemux setup | 生成本地配置，不必手写 JSON | | sourcemux doctor / probe | 本地配置检查 / 显式 live probe | | sourcemux bootstrap list-agents/status | 安装或检查 AI Agent 路由 skill 与 MCP 配置片段 |

MCP 接入

通用 stdio MCP server 配置：

{
  "type": "stdio",
  "command": "/absolute/path/to/sourcemux",
  "args": ["--config", "/absolute/path/to/sourcemux.json"]
}

Claude Code 示例：

claude mcp add-json sourcemux '{
  "type": "stdio",
  "command": "/absolute/path/to/sourcemux",
  "args": ["--config", "/absolute/path/to/sourcemux.json"]
}'

也可以先用内置安装器生成 CLI-first 的 sourcemux-routing skill；公开用户 默认走 user scope，项目开发再使用 project scope。只有显式传 --write-config 或选择 mcp-json / stdio 目标时才输出 MCP 配置指导：

sourcemux bootstrap list-agents
sourcemux bootstrap codex claude-code --scope user --dry-run
sourcemux bootstrap codex --scope user
sourcemux bootstrap codex --write-config --scope user --dry-run --json
sourcemux bootstrap update codex --scope user
sourcemux bootstrap status --scope user --config-status

未传 --write-config 时，生成的 skill 会要求使用 CLI，并在每个 CLI 示例中带上 安装时配置的 --config 路径。传 --write-config 后，支持安全写入的目标会生成 MCP-aware skill，并输出更具体的官方 MCP 接入方式：Codex 的 codex mcp add / config.toml、Claude Code 的 claude mcp add --transport stdio、Gemini CLI 的 gemini mcp add / settings.json，以及 OpenCode 的 opencode.json 配置片段。 --write-config 会为 Codex（.codex/config.toml / ~/.codex/config.toml）、 Gemini（.gemini/settings.json / ~/.gemini/settings.json）和 OpenCode （opencode.json / ~/.config/opencode/opencode.json）安全合并 sourcemux MCP 条目，不调用外部 agent CLI，也不会写入 provider API key。 修改已有配置前会创建带时间戳的备份；--dry-run --json 会显示将创建备份的原因和路径意图，但不会写文件。当前写入器会保留配置语义、 无关 key 和无关 MCP 条目，但可能重新序列化 Codex TOML、Gemini JSON 和 OpenCode JSONC；注释和原始排版不保证保留，备份文件是回滚路径。 sourcemux uninstall --write-config 只删除 sourcemux 条目， 不删除整个配置文件。 生成的 skill 目录会带 .sourcemux-install.json manifest；bootstrap update 会自动刷新未被用户修改的旧生成 skill。uninstall 默认只删除 manifest hash 仍匹配的生成文件；如果用户改过生成 skill，或旧安装没有 manifest，可传 --force 先备份再移除。

MCP 侧常用工具：

| 工具 | 用途 | | --- | --- | | web_search | 紧凑搜索摘要，带 provider fallback 和来源提取 | | docs_search | 文档搜索；使用 Exa docs/web search fallback | | get_sources | 返回上一次 web_search 的 URL 列表 | | web_fetch | 抓取网页正文摘要 | | web_map / web_crawl | 站点 URL 发现 / 站点抓取 | | research_run | 返回紧凑 research pack | | smart_answer | research 后调用 reasoning endpoint 综合 | | get_config_info | 配置诊断和 Grok /models probe |

从 grok-search 迁移

项目已改名为 SourceMux：

• GitHub 仓库目标名：500tpig/sourcemux-go
• 主命令：sourcemux
• 默认配置：sourcemux.json

旧的 cmd/grok-search 仍保留一个迁移窗口，GoReleaser 也会把 grok-search 兼容 binary 一起打包。新文档和新安装请使用 sourcemux。

已有本地 clone 在 GitHub 仓库改名后运行：

git remote set-url origin https://github.com/500tpig/sourcemux-go.git

更多文档

• [docs/QUICKSTART.md](docs/QUICKSTART.md) — 更完整的快速开始。
• [docs/AI_USAGE.md](docs/AI_USAGE.md) — AI Agent / MCP / CLI 使用建议。
• [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构图、核心链路和 provider 路由说明。
• [docs/MIGRATION.md](docs/MIGRATION.md) — 改名与配置迁移。
• [docs/RELEASE.md](docs/RELEASE.md) — 发布、Homebrew、Scoop 和 GoReleaser。

English

SourceMux is a single-binary CLI + stdio MCP agent research router for search, fetch, docs lookup, bounded research, and reasoning synthesis. It gives agents fast/default search for one-hop work, profile=auto heavy Grok research when configured, and policy-first URL fetch with quality, GitHub-aware, and cheap profiles.

The default routing is:

• web_search / sourcemux search: Grok endpoint pool -> TinyFish Search -> Exa Search -> Tavily Search
• web_fetch / sourcemux fetch --profile auto: GitHub Provider for GitHub URLs; otherwise Firecrawl -> Jina Reader -> Exa Contents -> Tavily Extract -> TinyFish Fetch
• sourcemux fetch --profile quality: Firecrawl-first and enables Firecrawl clean-content with a longer timeout budget before fallbacks
• sourcemux fetch --profile cheap: Jina Reader -> Firecrawl -> Exa Contents -> Tavily Extract
• docs_search / sourcemux docs-search: Exa docs/web search fallback
• research_run / sourcemux research: plan queries -> search -> collect sources -> rank URLs -> fetch top pages (defaults to --profile auto)
• smart_answer / sourcemux smart-answer: run bounded research (defaults to --profile auto), then synthesize the final answer with a configured OpenAI-compatible reasoning endpoint

Why not just Jina or simple search?

• Jina Reader is a lightweight, zero-key URL extraction fallback. It is the

cheap profile's first attempt, not the quality default or the ceiling for search, docs discovery, heavy Grok search, or synthesis.

• Simple web search returns candidate results. SourceMux adds agent-oriented

routing, fallback, get_sources, fetch verification, bounded research packs, and reproducible JSON.

• For complex, current, comparative, or high-risk work, research and

smart-answer default to profile=auto; searchPolicy.autoPreference decides when configured heavy Grok profiles are used while fallback remains available.

Features

• Single Go binary for CLI and stdio MCP server modes.
• MCP text responses stay compact; CLI text/JSON remain the canonical full-output surfaces.
• Single explicit JSON config file: ./sourcemux.json by default, or --config /path/to/sourcemux.json.
• Grok/OpenAI-compatible endpoint pool with priority fallback.
• Optional TinyFish, Exa, Tavily, and Jina integrations.
• Source caching via get_sources for MCP workflows.
• Bounded research packs for reproducible

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 500tpig
• Source: 500tpig/sourcemux-go
• License: MIT

Install and usage instructions live in the source repository linked above.