Smart Ai Bridge

Smart AI Bridge v2.15.0

面向 Claude Code 的配置驱动型多 AI 编排。添加任意 OpenAI 兼容提供商，智能路由，并通过 council 系统让多个 AI 协作。

功能

Smart AI Bridge 是一个位于 Claude Code 与 AI 后端之间的 MCP 服务。它提供 17 个工具，用于节省令牌的文件操作、多 AI 工作流、代码质量检查和智能路由——所有配置都通过单个 JSON 文件完成。

• 兼容 OpenAI 的提供商均可使用。 本地模型（vLLM、LM Studio、Ollama）、云 API，或两者混用。内置预设涵盖常见提供商，添加自定义提供商只需增加一项配置。
• 智能路由采用 4 层系统，根据任务选择最佳后端：强制选择、学习所得的偏好、基于规则的启发式判断，以及基于健康状态的回退。
• Council 系统会针对同一提示词查询多个后端，并返回所有响应供 Claude 综合。可按主题配置策略（并行、顺序、辩论、回退）。
• Web 控制面板可用于管理后端和 council 配置，无需编辑 JSON 文件。

工作原理

核心理念：Claude 从不读取文件

在编码任务中，Claude 的上下文大多消耗在文件内容上。Smart AI Bridge 将这项工作交给 另一个模型，只返回结论，因此昂贵的上下文可以留给推理使用。

sequenceDiagram
    accTitle: How Smart AI Bridge saves tokens
    accDescr: Claude Code calls analyze_file. Smart AI Bridge reads the file and sends its contents to a backend model. The backend returns a structured analysis, and only that analysis is returned to Claude. The file contents never enter Claude's context.
    participant C as Claude Code
    participant S as Smart AI Bridge
    participant F as Your files
    participant B as Backend<br/>(local or cloud)

    C->>S: analyze_file({ filePath, question })
    S->>F: read the file
    S->>B: file contents + question
    B-->>S: structured analysis
    S-->>C: { summary, findings[], confidence, tokens_saved }

    Note over C,S: The file contents never enter Claude's context.<br/>tokens_saved is measured from the real bytes,<br/>not estimated.

modify_file 的工作方式相同，但会返回差异；explore 会返回匹配的 file:line 证据；batch_analyze 则会对整个 glob 执行分析。每个工具都会报告 tokens_saved 数值，该数值根据实际读取的字符数与实际返回的响应字符数计算得出。

选择后端：4 层路由器

每次未指定后端的调用都会按顺序经过同一套判定流程。第一个选出健康后端的层级即为最终结果。

flowchart TD
    accTitle: The four-tier backend routing decision
    accDescr: A tool call is routed in four ordered tiers. Tier 1 uses an explicitly named backend. Otherwise Tier 2 uses a learned preference above 0.7 confidence if that backend is healthy. Otherwise Tier 3 applies complexity and task-type rules. Otherwise Tier 4 takes the first healthy backend in the fallback chain.
    A[Tool call] --> B{"backend named<br/>and not 'auto'?"}
    B -- yes --> T1["<b>Tier 1 · Forced</b><br/>use it as given"]
    B -- no --> C{"learned preference<br/>above 0.7 confidence<br/><i>and</i> that backend healthy?"}
    C -- yes --> T2["<b>Tier 2 · Learned</b><br/>from past outcomes"]
    C -- no --> D{"a rule matches on<br/>complexity / task type?"}
    D -- yes --> T3["<b>Tier 3 · Rules</b><br/>heuristic match"]
    D -- no --> T4["<b>Tier 4 · Fallback</b><br/>first healthy backend<br/>in the chain"]

如果学习所得的偏好置信度较高，但指向的后端不健康，系统会转到第 3 层，而不会使用该偏好。健康检查失败会触发断路器，因此宕机的提供商会被跳过，而不会因重试导致超时。

同时询问多个模型：council

council 会将一个提示词发送给多个后端，并返回所有响应供 Claude 综合。它不会投票或选出胜者——模型之间的分歧本身就是信号，因此会予以保留，而不是取平均值。

flowchart LR
    accTitle: Council strategies
    accDescr: One prompt is dispatched by a configurable strategy. Parallel queries all backends at once. Sequential runs them in order, each seeing the previous answer. Debate has models respond to each other. Fallback tries the next backend only if the previous failed. Every response is returned to Claude to synthesize.
    Q[One prompt] --> R{strategy}
    R -->|parallel| P[All backends at once]
    R -->|sequential| S[One after another,<br/>each sees the last]
    R -->|debate| D[Models respond<br/>to each other]
    R -->|fallback| F[Next only if<br/>the previous failed]
    P & S & D & F --> A[All responses returned<br/>to Claude to synthesize]

可按主题配置策略。请参阅 docs/COUNCIL.md。

快速开始

没有 npm 包——请通过克隆安装。需要 Node.js >= 18。

1. 克隆并安装

git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm install

在将其接入任何系统之前，请先确认安装正常：

npm test          # expect: all tests pass, 0 failures

2. 至少配置一个后端

即使没有任何 API 密钥，服务也会启动并列出全部 17 个工具——只有实际调用工具时才需要后端。你需要以下其中一项：

• 本地 OpenAI 兼容服务（llama.cpp、vLLM、LM Studio、Ollama）——会自动发现常见端口上的服务，无需密钥；或
• 任意受支持提供商的一个云 API 密钥。

# Set whichever apply -- one is enough
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"

后端定义位于 src/config/backends.json；完整参考请参阅 CONFIGURATION.md。 缺少密钥绝不会导致错误——启动就绪状态审计会将此类后端报告为 cannot verify，而非故障。

3. 注册到 MCP 客户端

请使用 src/server.js 的绝对路径。相对路径依赖客户端是否支持 cwd，并非所有客户端都支持。

Claude Code —— 将 .mcp.json.example 复制到项目中的 .mcp.json，或添加到 MCP 设置中：

{
  "mcpServers": {
    "smart-ai-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
      "env": {
        "NVIDIA_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop —— 将相同代码块合并到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

其他 MCP 客户端 —— 它通过 stdio 使用 MCP。运行 node /absolute/path/src/server.js，并通过 JSON-RPC 与其通信。诊断信息会输出到 stderr；stdout 仅承载协议流量。

4. 重启客户端并验证

重启后会显示全部 17 个工具。使用不需要任何后端的调用进行验证：

@get_analytics({})

若要检查已实际配置的后端，请明确指定其名称——如果没有本地模型正在运行，check_backend_health 会将 local 报告为严重问题；对于仅使用云端的配置，这是预期行为，并不表示安装失败：

@check_backend_health({ "backend": "auto" })

更新现有安装

cd /path/to/smart-ai-bridge
git pull origin main
npm install        # only needed when dependencies changed

然后重启 MCP 客户端（在 Claude Code 中，使用 /mcp 重新连接，无需完全重启）。

工具（17 个）

节省令牌的文件操作

工具	描述
analyze_file	由后端读取并分析文件，返回结构化结果
modify_file	后端根据自然语言指令编辑文件，并返回差异
batch_analyze	通过 glob 模式分析多个文件；grepFilter 先按内容缩小范围，singlePass 可在一次调用中作答
batch_modify	将相同指令应用到多个文件
generate_file	根据自然语言规范生成代码
explore	使用智能搜索回答有关代码库的问题

除 generate_file 外，所有工具都会返回 tokens_saved 字段，表示该次调用所节省的字符数：后端代你读取的文件内容字符数，减去返回给你的响应字符数。两侧的数值都基于实际数据测量，而非估算，因此该数值反映了该次调用中的实际情况——不过，字符到令牌的换算（约每个令牌 4 个字符）本身是近似值，因此应将其视为可靠的参考，而非精确的令牌数。节省量会因文件大小和响应长度而有很大差异：小文件可能完全无法节省。我们不会公布概括性的百分比，因为尚未进行过我们有把握为其背书的基准测试。

多 AI 工作流

工具	描述
ask	智能路由，支持自动或强制选择后端
council	在可配置的后端之间达成多 AI 共识
dual_iterate	在两个后端之间循环进行生成、审查和修复
parallel_agents	采用分解任务和质量门禁的 TDD 工作流
spawn_subagent	专用 AI Agent（含 TDD 在内的 10 种角色）

代码质量

工具	描述
review	安全性、性能和质量审查
refactor	跨文件重构并更新引用

基础设施

工具	描述
check_backend_health	对指定后端进行健康诊断
backup_restore	带时间戳的备份管理
write_files_atomic	原子化写入多个文件并创建备份
get_analytics	使用情况分析和优化建议

智能路由

路由器使用 4 层优先级系统选择后端：

1. 强制 —— 显式选择后端（model="my_backend"）
2. 学习 —— 根据以往结果学习到的偏好（置信度 >0.7）
3. 规则 —— 复杂度和任务类型启发式规则
4. 回退 —— 根据健康状态沿优先级链回退

当解析选定的后端发生故障时——也就是你传入了 backend: "auto"，或由路由规则选出的后端——请求会自动转到链中下一个健康的后端。

你显式指定的后端不会级联回退。它只会尝试一次；如果失败，你会收到错误提示。这样可以区分“已尝试你的指定通道但失败”和“根本无法尝试你的指定通道”。这是有意为之：API 密钥由你掌控，而静默地将你固定到某个通道的请求重新路由，可能会在你从未要求使用的通道上消耗额度。想使用回退链时，请传入 backend: "auto"。

熔断器会保护各个后端（连续失败 5 次后进入 30 秒冷却期）。

后端名称

后端名称分为两个层次，两者都有其用意：

• 易读名称是你传给工具的名称（例如 backend: "glm" 或 model="groq"）。它们是稳定且与提供商无关的别名。
• 内部名称是 src/config/backends.json 和分析系统中使用的注册表／配置标识符。

预设名称的映射如下：

易读名称	内部名称	适配器类型
local	local	local
deepseek	nvidia_deepseek	nvidia_deepseek
glm	nvidia_glm	nvidia_glm
gemini	gemini	gemini
groq	groq_llama	groq

已移除：nvidia_qwen / qwen3。 NVIDIA 的代码专家通道曾经使用 Qwen 模型。NVIDIA 后来停用了该通道，其目录现在已不再列出任何类型的 Qwen 模型——因此这些名称被直接移除，而不是保留为指向不同名称通道的别名。nvidia_qwen 和 qwen3 现在都无法解析为任何内容。

请使用 nvidia_glm（易读别名：glm）。如果你保存的配置中有 force_backend: "nvidia_qwen"，或包含 "type": "nvidia_qwen"，请将其改为 nvidia_glm。

这不会影响你在本地运行的 Qwen 模型。桥接程序仍会在你自己的路由器上检测这些模型，并应用针对 Qwen 的处理方式（能力推断、FIM 标记、抑制推理）——这与已停用的 NVIDIA 通道无关。

与 OpenAI 兼容的后端使用内部名称 openai_chatgpt（适配器类型为 openai），通过智能路由而非易读别名接入。对于 ask 工具，openai 可作为已配置的 OpenAI 兼容后端的兼容别名。你通过配置添加的自定义后端会直接使用其 name 字段作为内部名称。

后端漂移与模型退役

提供商会在不事先通知的情况下退役模型，除此之外，只有在请求失败时才会发现问题。以下两项措施可以捕捉这类问题：

启动时进行就绪状态审计。 它会检查每个已配置后端的模型是否在提供商目录中，并将检查结果打印到 stderr。此审计仅在 MCP 握手完成后运行，且不会被等待，因此不会延迟或中止启动。使用 SAB_DISABLE_READINESS_AUDIT=true 可禁用此功能。

按需探测，向每个已配置后端发送一次真实补全请求：

npm run audit:backends            # human-readable table
npm run audit:backends -- --json  # machine-readable

真实补全是唯一可信的检查方式——提供商的 /v1/models 列表中可能包含模型 ID，但这些 ID 对特定账户仍会返回 404。后端会被分类为 OK、RETIRED、TRANSIENT、ERROR、NO_MODEL 或 NO_KEY。只有出现 RETIRED、ERROR 或 NO_MODEL 时，命令才会以非零状态退出，因此可以用作 CI 门禁。

没有 API 密钥的后端绝不会被报告为故障。 你需要提供自己的密钥，而且大多数配置只会使用一个提供商，因此未设置密钥时会报告 cannot verify — <VAR> not set，且不会导致运行失败。local 后端仅进行可达性检查，不检查目录：其配置中的 "model": "dynamic" 是一个句柄，而非目录 ID。

模型退役后，产生的错误会明确说明这一点——列出后端、模型、提供商的生命周期结束文本以及当前可用的替代候选项，而不是只显示泛化的 HTTP 错误。模型退役属于配置错误，因此会立即打开熔断器，不会重试；饱和错误（429/5xx）和身份验证失败（401）则有意不视为模型退役。

响应可靠性（v2.4.0）

所有处理程序都使用统一的响应流水线（extractResponseText），能够正确处理所有已知的大模型响应格式——原始字符串、OpenAI 聊天/补全格式、思考模型的 reasoning_content、数组内容部分以及 Gemini 候选项。本地模型的重复输出会自动合并，分析结果也会去重并限制数量。

写入完整性

fs.writeFile 执行成功并不保证磁盘上的字节与请求写入的内容一致——短写或部分写入、ENOSPC、编码损坏，或并发写入者在写入与返回之间覆盖文件，都可能导致磁盘内容偏离预期内容，而写入调用本身却正常完成。

所有会写入重要内容的路径，都会在报告成功前读回内容并进行比较：

路径	验证内容
modify_file 自动写入	修改后的文件，以及事先创建的备份
generate_file 自动写入	生成的文件及其生成的测试文件
write_files_atomic 的 write	每个写入的文件及其备份
write_files_atomic 的 append	文件是否恰好增长了追加内容的长度，且结尾是否恰好为这些字节
write_files_atomic 回滚	每个还原的文件（只有确认还原完成后才会删除备份）
batch_modify	修改内容（通过 modify_file）及其回滚还原内容
parallel_agents	每个生成的代码文件
backup_restore	备份、还原前的快照以及还原操作本身

如果内容不匹配，就会引发 WRITE_VERIFY_MISMATCH，指出文件名、预期长度与实际长度，以及首个不一致行，而不会在文件已损坏时仍报告 success: true。

恢复路径也会执行同样的验证：备份悄无声息地写入失败比没有备份更糟，因为之后的回滚可能会用损坏的字节覆盖原始内容。

按设计不进行验证的内容：内部运行产物和状态文件，它们是记录而非交付物，包括 parallel_agents 的 decomposed.json/results.json/quality-*.json/synthesis.json、backup_restore 的 .meta.json 伴随文件、模式存储以及对话线程。

Council 系统

Council 会针对同一提示词查询多个后端，并返回所有响应，供 Claude 综合。coding、architecture 和 security 等主题各自映射到一组后端和一种策略（并行、顺序、辩论或回退）。

完整文档请参阅 docs/COUNCIL.md。

Dashboard

可选的 Web Dashboard 提供了用于管理后端（启用/禁用、优先级、健康检查）和配置 Council（策略、主题映射）的 UI。

设置和 API 参考请参阅 docs/DASHBOARD.md。

SmartCrusher（工具结果压缩）

较大的工具结果——例如长篇文件分析、Council 响应和批量输出——可能很快填满 Claude 的上下文窗口。SmartCrusher 会在序列化之前，使用按显著性加权的保留/丢弃策略精简过大的数组，并插入一个标记行，让 Claude 知道数据已被移出。

默认禁用。 只有在针对你自己的本地模型运行保真度评估后，才启用此功能。

启用

# One-time env override (no config edit needed)
SAB_COMPRESSION_ENABLED=true node src/server.js

# Or permanently in src/config/backends.json:
# "compression": { "enabled": true }

保真度评估（启用前运行）

此评估会检查压缩后的响应与原始响应相比是否保留了事实准确性。它需要一个兼容 OpenAI 的本地 API——使用你平常运行的任意模型：

RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

检查输出中每个维度的 original=N/15 与 crushed=M/15。如果压缩后的任一维度得分降低超过 2 分，请保持压缩禁用——该模型的评分方式与参考设置不同。

添加后端

通过 Dashboard（推荐）：将服务器以 SAB_DASHBOARD=true 启动，然后使用 http://localhost:3456 上的 Web UI（使用 SAB_DASHBOARD_PORT 覆盖端口），即可添加、移除、启用/禁用后端并调整其优先级，无需编辑 JSON。Dashboard 还允许为每个后端设置/清除 API 密钥（存储在被 git 忽略的 data/backends-secrets.json 中，模式为 0600——绝不会写入受版本控制的 src/config/backends.json）；已存储的密钥会立即生效，无需重启，并且优先于后端的 process.env 回退值。

默认情况下，Dashboard 仅绑定到 127.0.0.1——它没有身份验证，因此不得从本机以外访问。如需从其他位置访问，请使用 SAB_DASHBOARD_HOST 覆盖；非环回主机启动时会打印警告，指出相关风险。

通过配置文件：任何兼容 OpenAI 的提供方都可以作为配置项添加到 src/config/backends.json 中：

{
  "name": "my_provider",
  "type": "openai",
  "endpoint": "https://api.my-provider.com/v1",
  "model": "my-model",
  "apiKeyEnvVar": "MY_PROVIDER_API_KEY",
  "maxTokens": 8192,
  "priority": 7,
  "enabled": true
}

有关添加自定义适配器类型的详细信息，请参阅 EXTENDING.md。

文档

文档	描述
AGENTS.md	面向 AI Agent 和 Agent 式框架的安装/运行约定，以及仓库规则
CHANGELOG.md	版本历史
CONFIGURATION.md	完整配置参考
EXTENDING.md	添加后端、处理程序和工具
EXAMPLES.md	使用示例
docs/DASHBOARD.md	Dashboard 设置和 API
docs/COUNCIL.md	Council 系统详情

要求

• Node.js >= 18.0.0
• 至少配置一个后端（本地模型或云 API 密钥）
• 用于 MCP 集成的 Claude Code 或 Claude Desktop

测试

npm test              # Run the unit + integration suite (Vitest)
npm run test:watch    # Watch mode
npm run test:bench    # Performance benchmarks (25 benchmarks, 6 categories)
npm run audit:backends # Probe every configured backend with a real completion

# SmartCrusher fidelity eval (opt-in, requires a running local model):
RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

安全说明

• 切勿将 API 密钥提交到版本控制中。请仅使用环境变量。
• 上述 Claude Code 配置示例使用的是占位值——请将其替换为你的实际密钥，或引用 .env 文件。
• 如有密钥意外泄露，请立即轮换。

威胁模型

Smart AI Bridge 是一个可信本地 MCP 服务。它旨在作为 stdio 子进程运行，由你在自己的机器上控制的单个客户端（Claude Code 或 Claude Desktop）启动，并假设该客户端可信。

在此信任边界内：

• 文件工具按设计拥有完整的文件系统访问权限。 write_files_atomic、 modify_file、backup_restore 以及读取／分析工具会操作调用客户端提供的任意路径。它们不会被限制在项目根目录内。safeReadFile 会解析路径并拒绝空字节（用于防御路径注入技巧），但不会将访问限制在工作区内。
• 参数会在工具边界进行验证。 工具调用会在分发前根据各工具的 JSON Schema（通过 Ajv）进行验证；格式错误的调用会以结构化错误形式拒绝。此举可防御格式错误的输入，但无法防御恶意客户端。
• 工具调用以服务进程的权限运行。 请以普通用户身份运行，而不要以 root 身份运行。

这种安全设置适用于预期的单用户本地 Agent 使用场景。它不适合通过网络向不可信调用方或多租户调用方开放服务。如果有此需求，请先在服务前部署身份验证代理，并为文件处理器添加工作区根目录限制——这里两者都未提供。

许可证

Apache-2.0