model-shunt

Model-Shunt 🔀

一种解耦、零依赖的通用 Shunt 模型路由模式实现（最初由 Spotify Engineering 构想）。

Model-Shunt 可让 AI 编码 Agent（Antigravity、Cursor、Windsurf、Claude Code、Aider、OpenHands 等）将大量消耗令牌的 I/O 操作（批量读取文件／代码分析）和重复的样板代码生成（测试、模拟对象、存根、配置）委派给快速、经济或本地的工作模型（Gemini 2.5 Flash、Groq/Llama、Ollama、DeepSeek、GPT-4o-mini）。这最多可减少主 Agent 90% 的令牌消耗，同时保持主上下文窗口整洁。

---

⚡ 主要亮点

• 零外部依赖： 使用纯 Python 3 标准库（urllib、json、re、argparse）构建。无需 pip install、虚拟环境或 npm。
• 与 Agent 无关： 可通过标准的 MCP（Model Context Protocol）、独立 CLI 脚本或 PreToolUse 生命周期钩子，无缝适用于任何 AI 编码 Agent。
• 动态发现模型并自动路由： 实时查询工作模型端点以发现可用模型，并自动将任务路由到最合适的模型：
  • 阅读模式（批量 I/O）： 优先选择上下文窗口大、成本极低的模型（例如 gemini-2.5-flash、llama-3.3-70b-versatile、gpt-4o-mini）。
  • 写作模式（代码生成）： 优先选择专用编码模型（例如 qwen2.5-coder:latest、gemini-2.5-flash、deepseek-chat）。
• 绕过 Linux ARG_MAX 限制： 不同于将文件内容作为 CLI 参数传递的简单实现（Linux 上限约为 128 KB），Model-Shunt 通过 stdin 流式传输语料数据，可分析数十万行内容而不会缓冲区溢出。
• 确定性行号（N|）： 自动为文件块中的每一行添加从 1 开始的行号前缀，促使工作模型引用可验证、精确的行号，而不是臆测位置。
• 二进制文件保护： 检查字节头，在将二进制文件（PDF、图片、编译后的对象文件）发送给 LLM 前将其拒绝。
• 网络弹性： 针对速率限制（HTTP 429）和临时服务器错误（HTTP 503/502）自动进行指数退避重试，并支持配置超时和令牌限制。
• 超大语料的 Map-Reduce： 当 bulk_read 负载超过直接处理上限（SHUNT_MAX_DIRECT_TOKENS，默认约 200k 个令牌）时，Model-Shunt 会自动将语料拆分为多个块，针对每个块处理问题（保留绝对 N| 行号），然后汇总提取结果，生成一个带引文的答案。超长单行文件（压缩后的 JSON/JS）会按字符切片，并添加明确的位置标记。速率限制节流会等待服务商的配额窗口恢复，而不是直接失败。

---

📁 仓库结构

model-shunt/
├── src/model_shunt/
│   ├── worker.py              # Universal LLM worker engine with model discovery (zero-deps)
│   └── server.py              # Stdio MCP server exposing routing tools
├── bin/model-shunt.js         # npm/npx launcher shim (requires local Python 3)
├── plugin/
│   ├── .claude-plugin/        # Plugin manifest for hook-compatible agents
│   ├── hooks/                 # PreToolUse interceptor hooks (check-file-size, check-bash-read)
│   ├── scripts/               # Executable streaming CLIs (bulk-read, code-write)
│   └── skills/                # Agent skill manifests (/bulk-reader, /code-writer)
├── pyproject.toml             # PyPI packaging (uvx / pip install)
├── package.json               # npm packaging (npx)
├── config.example.json        # Configuration template
├── test_shunt.py              # Automated test suite
└── .gitignore                 # Credential and cache protection

---

⚙️ 配置

通过环境变量或 config.json 文件配置工作模型（将文件放在 ~/.config/model-shunt/config.json 或项目根目录中）：

使用 config.json

{
  "provider": "gemini",
  "model": "auto",
  "timeout": 90,
  "max_tokens": 8192
}

**提示：**将 "model": "auto" 设为自动模式（或在 CLI 中传入 --auto-model），即可自动检查提供商当前启用的模型，并选择最适合读取和编写的模型。

**安全：**请勿将 API 密钥放入 config.json，请改用环境变量（例如 GEMINI_API_KEY、GROQ_API_KEY 或 SHUNT_API_KEY）。api_key 字段仅作为最后手段的备用选项，但强烈建议不要将机密信息保存在文件中。

使用环境变量

# Google Gemini (Recommended: 1M token context, high speed, ultra-low cost)
export SHUNT_PROVIDER="gemini"
export GEMINI_API_KEY="your-api-key"

# Groq (Ultra-low latency inference)
export SHUNT_PROVIDER="groq"
export GROQ_API_KEY="your-api-key"

# Ollama (100% private, local, and free)
export SHUNT_PROVIDER="ollama"
export SHUNT_BASE_URL="http://localhost:11434/v1"

# OpenAI / DeepSeek / OpenRouter / Anthropic
export SHUNT_PROVIDER="deepseek"
export DEEPSEEK_API_KEY="your-api-key"

---

🛠️ 使用模式

模式 1：通用 MCP 服务（推荐）

Model-Shunt 提供标准的 stdio MCP 服务，并暴露三个工具：

1. get_available_models(provider?)：查询提供商端点，并推荐读取和编写模型。如果发现失败或不受支持，则返回内置推荐；这些推荐所对应模型当前是否可用未经验证。
2. bulk_read(question, file_paths, model?, provider?)：读取大型文件或多个文件，并输出简洁、结构化的要点，附带精确的行引用。如果源文件第 k 行不包含名称，则会省略引用 name (N|k)。
3. code_write(spec, reference_path, target_path?, model?, provider?)：根据规范和参考文件生成代码。如果省略 target_path，则返回代码；否则创建缺失的父目录并写入代码，覆盖已有目标文件。

bulk_read 会将所选文件和问题发送给已配置的工作器提供商；code_write 会发送规范和参考文件。提供商可以是远程服务，也可以是本地服务（例如 Ollama）。节省的 token 数量取决于输入和响应。

MCP 服务通过本地 stdio 运行。请通过环境变量设置提供商凭据。文件访问遵循解析后的路径，因此指向允许的工作区根目录之外的符号链接会被拒绝。无效请求会返回结构化错误，且服务仍可处理后续调用。

安装

MCP Registry 名称：mcp-name: io.github.yasmanycastillo/model-shunt

通用一行命令（检测 uv / pip / pipx / npm，安装 model-shunt 命令，并在存在 Claude Code 时为其注册）：

curl -fsSL https://yasmanycastillo.github.io/model-shunt/install.sh | bash

手动替代方案：

claude mcp add model-shunt -- uvx model-shunt      # if you have uv
claude mcp add model-shunt -- npx -y model-shunt   # if you have Node + Python

任何 MCP 客户端（Cursor、Windsurf、Antigravity、Claude Desktop 等）——将以下内容添加到其 MCP 设置中。无需克隆，也无需绝对路径：

{
  "mcpServers": {
    "model-shunt": {
      "command": "uvx",
      "args": ["model-shunt"],
      "env": {
        "SHUNT_PROVIDER": "gemini",
        "SHUNT_MODEL": "auto",
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

**备用方案（离线 / 无 uv / 无 npx）：**使用 Python 3.9+ 直接从克隆的仓库运行——将 "command"/"args" 替换为 "command": "python3", "args": ["/absolute/path/to/model-shunt/src/model_shunt/server.py"]。

**安全：**默认情况下，bulk_read/code_write 只能操作服务工作目录（Agent 工作区）内的文件。设置 SHUNT_ALLOWED_ROOTS（PATH 风格的列表）可扩大沙盒范围。

Map-Reduce 调优（可选）

变量	默认值	用途
SHUNT_MAX_DIRECT_TOKENS	200000	超过此估算大小的负载将切换为 map-reduce
SHUNT_CHUNK_CHARS	600000	分块大小，以字符数计（约 150k tokens）
SHUNT_CHUNK_RETRIES	3	遇到速率限制时，每个分块的重试次数
SHUNT_CHUNK_RETRY_DELAY	60	等待提供商配额窗口（免费层 TPM）恢复的秒数

---

模式 2：PreToolUse 拦截器钩子

适用于支持执行前钩子的 Agent（例如 Claude Code、自定义 Agent 循环）：

1. 文件读取拦截器（check-file-size）：
   • 如果 Agent 尝试读取超过阈值的整份文件（默认：350 行，可通过 SHUNT_MIN_LINES 配置），钩子会阻止此次调用，并指示 Agent 转而使用 bulk-read。
   • 带有 offset 和 limit 的定向读取会被允许，以便在代码编辑时保留精确的上下文。
2. 终端防护（check-bash-read）：
   • 阻止 Agent 通过在终端上下文中直接对大型文件执行 cat、less 或 more 等命令来绕过读取钩子。

---

模式 3：独立 CLI 和脚本

你也可以直接从命令行或 Agent 的 bash 会话中使用 Model-Shunt：

发现可用模型并获取推荐

python3 src/model_shunt/worker.py --list-models --provider gemini

执行批量阅读分析

./plugin/scripts/bulk-read \
  --question "How does the token refresh cycle work?" \
  --paths src/auth.py src/tokens.py \
  --auto-model

直接将样板代码生成到磁盘

./plugin/scripts/code-write \
  --spec "Create unit tests for the BillingService covering charge and refund" \
  --reference tests/test_user.py \
  --target tests/test_billing.py \
  --auto-model

---

🧪 验证

运行内置测试套件以验证你的环境：

python3 test_shunt.py

测试套件会验证：

• 配置解析、回退链和模型选择。
• 二进制文件检测与拒绝。
• Hook 决策（允许精细读取、阻止读取大文件、解析 bash 标志）。
• MCP stdio 协议合规性和工具执行。
• CLI 发现标志。

---

📄 许可证

MIT。灵感来自 Spotify Engineering 的 Shunt 架构。

🔒 隐私

请参阅 PRIVACY.md，了解文件系统范围、提供商数据处理和凭证实践。