Synapse Proxy：终极 Agentic 防火墙与深度遥测网关

Synapse Proxy 优雅地驻留在您的应用程序和任何兼容 OpenAI 的 LLM 提供商之间。其主要使命是为开发者赋能**深度 Agentic 可观测性**和**智能防火墙**，控制失控的 agent 循环，保护敏感数据，并使多轮 LLM 交互完全可见且可衡量。

在主动保护您的基础设施并监控您的 agent 意图的同时，Synapse Proxy 会在后台通过四级缓存流水线（L0 到 L3）静默优化 token 使用，确保您绝不会为相同的 agentic 思考过程支付两次费用。 **法语版本**：[README_FR.md](README_FR.md) ## 🛡️ Agentic 防火墙与安全 在构建自主 agent（AutoGPT、LangChain、自定义循环）时，最大的风险在于无限循环、失控的成本和 prompt 注入。Synapse Proxy 引入了专为 AI agent 设计的强大防火墙： - **循环熔断开关与自我纠错：** 检测 agent 何时陷入无限循环（重复相同的 tool payload）。它会拦截执行并返回一个模拟的 OpenAI 兼容聊天补全响应（`HTTP 200`），其中包含描述性的自我纠错警告，引导 agent 更改策略，而不会导致进程崩溃。 - **Tool 白名单与指纹识别：** 锁定 agent 的能力。如果 agent 幻觉出一个 tool 或尝试调用未经授权的函数，Proxy 会主动拦截该请求。 - **细粒度 Tool 缓存 TTL：** 为每个 tool 名称配置自定义缓存持续时间（包括将特定有状态 tool 的 TTL 设置为 0s 以禁用缓存）。 - **PII 脱敏：** 在 prompt 到达上游提供商之前，对敏感数据（电子邮件、API 密钥、电话号码）进行原生的基于正则表达式的掩码处理。 - **会话断路器：** 为每个会话定义严格的 prompt-token 限制，以按任务封顶支出。 ## 📊 深度遥测与意图可观测性 每个请求都会持久化存储到 PostgreSQL 数据库中，通过我们令人惊艳的 Next.js 控制平面，将黑盒 agent 行为转化为透明、可分析的流程。 - **本地 AI 意图分类：** 我们使用 `@xenova/transformers`（在本地运行，100% 离线）异步对每个 prompt 的意图（`coding`、`rag`、`chat`、`extraction`）进行分类，而不会给关键代理路径增加一毫秒的延迟。 - **会话回放时间线：** 逐步检查 agent 交互。在统一的可视化时间线上重建 agent 的流程、tool 调用和 payload 延迟。 - **System Prompt 差异比对：** Agent 有时会在会话中途重写其自身的指令。Proxy 会提取并对 system prompt 进行差异比对，在仪表板中精确高亮显示更改的内容。 - **上下文窗口追踪器：** 一张动态图表，随时间比较*原始 Prompt Token*与*L3 压缩 Token*，准确展示上下文是如何增长的，以及 Synapse Proxy 是如何缓解这一问题的。 - **A/B 基准测试：** 切换基准测试模式以并行发起控制请求和优化请求，使用 LLM 评判器对响应相似度进行评分。

## ⚡ 成本优化作为附赠功能 尽管安全性和可观测性占据了中心舞台，Synapse Proxy 仍 featuring 了一个旨在最小化延迟和 token 浪费的最先进的缓存引擎。 - **直接替换 OpenAI：** 无需更改 SDK。只需将您的客户端指向 `http://:8080/v1`，并使用 `Authorization: Bearer sk-opti-...` 虚拟密钥。 - **单一二进制文件中的四个缓存：** - **L0 进行中重去重：** 拦截并对相同的并发请求进行去重（对于 agent 扇出非常有用）。 - **L1 精确匹配：** 针对重试完全相同查询的脚本进行超快速的 SHA-256 匹配。 - **L2 语义匹配：** 基于 ONNX 的向量搜索（MiniLM），用于概念上相同的查询。在多轮对话中自动禁用，以防止状态损坏。 - **L3 前缀保留压缩：** 智能修剪过时的 `` 块，截断过大的 tool 输出，并压缩较早的历史记录。它保持字节精确的前缀，因此上游提供商的原生 prompt 缓存仍保持 99% 的有效性。包含高级钩子： - **SmartCrusher：** 分析 prompt 中大型同构 JSON 数组，提取其 schema，并将它们打包成空间优化的 CSV 格式。当 prompt 余量耗尽时，它会应用有损丢弃（从开头保留 30%，从结尾保留 15%），并带有 `_ccr_dropped` 元数据以保持 schema 的有效性。 - **DiffCompressor：** 通过仅保留修改周围 2 行未更改的上下文来修剪 prompt 中大型的 git diff。超过 50 行的 diff 会自动卸载到 L3 CCR（压缩内容存储库）中，并替换为标准的 `<>` 引用键。 - **ASTCodeCompressor：** 解析 prompt 中的 Python、Go 和 Javascript/Typescript 源文件，并剔除超过 5 行的函数/类主体，将其替换为语法有效的注释。 - **Anthropic KV-Cache 对齐：** 在战略边界（system prompt、最后一个 tool 列表、倒数第二个用户轮次）注入 `"cache_control": {"type": "ephemeral"}`，以最大化 Anthropic 原生缓存的有效性。 - **语义 Tool 去重：** 拦截 LLM tool 调用，并从之前类似的调用中检索缓存的输出，从而绕过客户端执行循环。

## 🔌 MCP 服务器（Model Context Protocol） Synapse Proxy 同时也是一个强大的 MCP 服务器，将 **17 个专用 tool** 直接暴露给您的 IDE（Cursor、Claude Code、Continue 等）。 所有 tool 均可在本地或您的自托管技术栈上完全免费使用。`synapse_chat_completions` 的进程内执行完全通过 `httptest.NewRecorder()` 在内存中运行，消除了环回 HTTP 依赖，并允许 MCP 服务器在 stdio 模式（`--mcp`）下完全离线运行。 新集成的 tool 包括： * **`synapse_inspect_ccr_store`**：列出当前归档在 L3 CCR 存储中的所有键及其 payload 大小。 * **`synapse_get_ccr_value`**：检索给定 CCR 哈希键的原始未压缩 payload。 * **`synapse_optimize_prompt`**：在本地模拟 prompt 优化钩子，并返回压缩后的 payload 和警报，而无需发起 LLM 调用。 ``` # Stdio 模式（推荐用于本地 Cursor/IDE 集成） ./synapse-proxy --mcp --mcp-tier=full # HTTP SSE 模式（用于远程/多用户服务器设置） ./synapse-proxy --mcp-http --mcp-http-port=8081 --mcp-tier=full --dashboard-url=http://localhost:3000 ``` ## 💻 仪表板（Next.js）— 100% 开源 该仓库在 `./dashboard` 下附带了一个完整的 Next.js 仪表板，可将 Proxy 的原始遥测数据转化为可操作的控制平面。**它与 Proxy 一样在相同的 MIT 许可证下完全开源**：审计它、复刻它、自托管它、定制它的主题——这里没有闭源的纯 SaaS 路径。 | 功能 | 描述 | |---------|-------------| | **实时遥测** | 通过 SSE 查看每个请求的到达。共享同一对话的行会使用对话签名自动分组在一起。 | | **全局指挥中心** | 令人惊艳的 3D/HUD 界面，显示实时 token 流、缓存命中率和实时服务器健康状况。 | | **Agent 防火墙模态框** | 为每个虚拟密钥切换 L1/L2/L3 缓存、熔断开关、PII 脱敏、会话 token 限制和 tool 白名单。更改会即时同步到 Redis。 | | **Playground v3** | 并排的 A/B 聊天：相同的 prompt 并行执行两次，一次通过 Proxy，一次直接发往上游。包含 artifact 渲染器。 | | **管理面板** | 自托管整个产品：管理虚拟密钥、动态模型定价、用户管理、警报规则和 Stripe 计费。 | ### 架构 ``` dashboard/ ├── app/ # Next.js App Router (React Server Components) ├── components/ # LiveTelemetryGrouped, FirewallModal, TokenFlowAnimation, etc. ├── lib/ # authOptions, prisma, stripe, email ├── prisma/ # PostgreSQL schema & migrations └── .env.example # Configuration template ``` 仪表板从与 Proxy 相同的 Postgres + Redis 实例中读取数据，因此自托管部署只需**备份一个数据库**。 ## 🚀 快速开始 ### 1. 通过 Docker Compose 自托管 克隆仓库，并通过一条命令启动整个技术栈（Proxy、Postgres、Redis、Next.js 仪表板、Caddy）： ``` git clone https://github.com/yourusername/synapse-proxy.git cd synapse-proxy # 复制示例环境变量 cp .env.example .env # 构建并启动 stack docker compose -f docker-compose.prod.yml up -d --build ``` ### 2. 快速入门（客户端代码） 一旦您的 Proxy 运行起来，更改您的代码就像更新 `baseURL` 和 `apiKey` 一样简单： ``` from openai import OpenAI client = OpenAI( base_url="http://localhost:8080/v1", # Point to Synapse Proxy api_key="sk-opti-..." # Use your Synapse Virtual Key ) response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Hello!"}] ) ``` ## 📄 许可证 Synapse Proxy **在 MIT 许可证下完全开源**——包括 Proxy、仪表板和 SDK。自托管整个技术栈，审计每一行代码，复刻您需要的任何内容。 我们为那些不愿自己运维 Postgres + Redis 的团队在 [synapse-proxy.com](https://synapse-proxy.com) 提供了一个托管的 SaaS；该托管版本运行与此仓库完全相同的代码。该 SaaS 是一种**便利**，而不是守门人。

标签：AI网关, API缓存, API集成, CNCF毕业项目, DLL 劫持, LLM安全网关, Rust, 可观测性, 可视化界面, 大语言模型, 搜索引擎查询, 日志审计, 测试用例, 网络流量审计, 自动化攻击, 请求拦截