Other

技术解读

以下内容由 GitRead 中文社区 编辑团队基于项目 README 与官方资料整理, 结合中文开发者的常见使用场景补充技术选型建议。具体以项目官方文档为准。

把 AI 队友塞进 IM:sandbox-quantum/switch 的架构取舍

项目背景与痛点

过去两年,AI 编程助手几乎都长成同一个样子:一个独立网页、一个 IDE 侧栏,或者一个终端 TUI。但真实的团队协作并不发生在那里。讨论在 Slack 的线程里,需求在 Teams 的频道里,值班告警在 Telegram 群里。当有人问"这个接口的鉴权逻辑是谁改的",接下来的动作通常是:切到另一个标签页,把上下文复制粘贴给 AI,再把答案复制回来。

这一步"复制粘贴"就是 switch 想干掉的东西。它的定位很明确——把 Agent 的前端从独立应用换成团队已经在用的 IM。你在 Slack 线程里 @ 它,它在同一条线程里回你,上下文天然沉淀在讨论中,其他同事还能接着追问。

更关键的是后面半句:“Self-host it, with any agent harness and any model.” 市面上不缺 IM 机器人,缺的是不绑定模型、不绑定执行框架、数据不出内网的那一类。这正是 switch 的切口。

核心技术揭秘

从项目定位反推,switch 的架构重心不在"AI 能力",而在解耦。它更像一个协议转换中枢:左边接五套完全异构的 IM 事件模型,右边接五花八门的 Agent 执行框架。

graph TD A[Slack / Teams / Discord] --> B[平台适配层] C[Telegram / Mattermost] --> B B --> D[统一消息模型与会话映射] D --> E{"消息类型判定"} E -->|"普通对话"| F[Agent 调度器] E -->|"命令与回调"| G[任务编排器] F --> H[Harness 抽象接口] G --> H H --> I[Claude Code / Codex / 自定义 Harness] I --> J[模型网关] J -->|"云模型"| K[OpenAI / Anthropic / Bedrock] J -->|"本地模型"| L[vLLM / Ollama] I --> M[沙箱执行环境] M --> N[持久化:会话 / 任务 / 凭据] I --> O[结果流式回写] O --> B

第一层难点是会话归一化。 五个平台的会话语义差异极大:Slack 靠 thread_ts 把消息串成树,Discord 是 guild/channel/message 三级,Teams 有 conversation reference 这种会话引用,Telegram 只有扁平的 chat_id。switch 必须定义一套内部会话标识,把"线程"抽象成 Agent 的 session 容器——这其实是它最聪明的设计:IM 线程天然就是一个有生命周期、有参与者、有历史记录的上下文窗口,不需要自己造一套会话管理 UI。

第二层难点是 Harness 抽象。 "任意 agent harness"听起来轻巧,实际要做的是把不同执行引擎的异构接口收敛成统一契约:输入是消息 + 会话历史 + 工作目录,输出是流式事件(文本增量、工具调用、状态变更、最终结果)。Claude Code 这类 harness 自带工具循环和文件系统语义,而一个裸模型 harness 什么都没有。抽象层必须容忍这种能力落差,否则上层调度会被某个具体实现绑死。

第三层是回写体验。 IM 不是 WebSocket 长连接那么自由:Slack 对消息编辑有速率限制,Telegram 有消息长度上限。把 Agent 的流式输出映射成"先发一条占位消息、再逐步编辑",还要处理超长内容的分片与折叠,这是纯工程活儿,但直接决定用户觉得它"聪明"还是"卡顿"。

第四层是幂等与安全。 IM 平台普遍会重发事件,没有去重就可能触发重复执行。而沙箱执行环境意味着代码会在你的服务器上跑——凭据隔离、目录挂载范围、网络出口策略,这些是自托管方案必须自己扛的责任。

功能亮点与差异

和三类竞品比,switch 的位置很清晰:

  • 对比 Slack AI / Microsoft Copilot:内置方案开箱即用,但模型绑定、数据出境、无法接自己的 harness。switch 用自托管换来了完全的控制权。
  • 对比 OpenHands / Devin 这类 Agent 平台:它们强在 Web IDE 形态的深度交互,但把 AI 从协作流里抽走了。switch 反过来,牺牲交互丰富度,换取"在讨论现场解决问题"。
  • 对比 Botpress / Rasa 这类对话机器人框架:那是流程编排思维,本质是工单机器人。switch 是 Agent 思维,强调开放式任务执行。

真正的差异点只有一个:它是 harness 的中转层,而不是模型的产品壳。这意味着模型迭代、框架迭代都不会让你重写集成代码。

应用场景与落地建议

最合适的场景是内部工程协作:查代码归属、跑诊断脚本、生成变更摘要、值班时快速定位告警根因。其次是跨时区团队的异步问答——Agent 在线程里留下完整推理过程,比一次性回复更有价值。

生产落地有几条必须注意:

  1. 沙箱边界要画死。给 Agent 的工作目录、可访问的网络、可用的凭据,都应该是最小集合。别让它拿着生产环境的管理员 token 跑代码。
  2. 限流要提前压测。多平台的消息编辑频率差异很大,高并发下很容易触发平台侧限流,需要队列 + 退避策略。
  3. 审计链路不能省。谁发起的、用了哪个 harness、调了哪个模型、执行了什么工具,这些都要落日志——自托管的意义就在于你能查。
  4. 别指望它零运维。五个平台的 API 变更、认证方式演进,是需要长期跟进的维护成本。

综合评价

优点:架构分层干净,适配层、调度层、harness 层、模型层各自独立;自托管 + BYOM 切中了有数据合规要求的团队;把 IM 线程复用为会话容器,是省事且符合直觉的设计。

缺点:多平台适配是典型的长尾负担,五个平台的兼容性维护会持续消耗精力;harness 抽象接口的稳定性尚未经过大规模验证,接入自定义引擎时可能要踩坑;自托管意味着安全、备份、升级全部自己负责,对团队的技术水位有要求。

一句话总结:它不是最强的 AI 助手,但它可能是最容易嵌进你现有工作流的那一个。 如果你在意的是"AI 在哪里被使用",而不是"AI 有多强",这个项目的取舍值得认真看一眼。

关于

GitHub 原始描述(英文)

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

描述取自 GitHub 官方 API,保持仓库作者书写的原文。

简要分析

热度分
4737
价值分
2531
活跃状态
活跃

语言占比

CSS
Dockerfile
Go Template
HCL
HTML
JavaScript
Just
Mako
Nix
Python
Shell
TypeScript

README

Agent Switch

Open-source AI teammates, working alongside your team in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent and any model.

Switch - #1 Product of the Day on Product Hunt

Website Product Hunt License: Apache 2.0 + Commons Clause Documentation PRs welcome Release CI Discord

Switch demo — agents and humans collaborating in Slack

More than a single AI bot you ask questions to: Switch turns each channel into a room where your team and everyone’s AI teammates work together, with shared context.

  • 💬 Each channel becomes a room for people and agents. Your agents join the conversation in Slack, Microsoft Teams, Discord, Telegram and Mattermost, and everyone works from the same conversation, decisions and documents. Nobody has to learn a new tool or move anywhere.
  • 🌍 Any agent, any model, any provider. Your Claude Code agent on your laptop, a teammate’s Codex agent on theirs, a LangChain agent on your servers. If it speaks the protocol, it can join.
  • 🧩 AI teammates, not just bots. Give each agent a role, instructions and tools (Google Workspace, Jira, GitHub), and link rooms the way your team works. Context moves with the work, and an agent only sees the rooms it belongs to.
  • 🏠 Self-hosted, and the context is yours. Run Switch on your own servers. Your team’s context stays with your company, so you can change agents, models or vendors at any time without losing it.
  • 🛡️ Run your team with confidence. Decide who can talk to which agent, and in which rooms. Guardrails and cost reporting come with Switch Trust and Switch ROI.

Get started in two steps

  1. Install Switch Console, the desktop app, for your platform.
  2. Open it and talk to switch-buddy, your own assistant in Switch. Tell it what you want: it creates your first agents and channels, helps you connect the chat app your team uses, and answers anything about Switch.
Platform Install
macOS Apple Silicon · Intel
Windows Installer
Linux x64 AppImage · DEB
Linux ARM64 AppImage · DEB

See the latest release for all desktop builds.

Watch it work

The same incident, in the apps teams already use. Someone reports checkout failing, an agent opens an incident channel, pulls the error rate and finds the deploy behind it — with a second agent doing the charting. Under a minute each, no narration.

Slack

https://github.com/user-attachments/assets/d7db7859-c1e0-4d2c-9675-1cc3966a1bfd

Discord

https://github.com/user-attachments/assets/e114cf81-41b0-4cce-a06f-5e78830bf99d

Mattermost

https://github.com/user-attachments/assets/51918de4-4283-4717-bdfa-d63f9da8eae1

Why Switch

Your agents can do far more for your team than answer one question at a time. Switch is what unlocks it.

You do not have to start big. Each level builds on the one before it, the first works on day one, and each one gets more out of your agents than the last.

⚡ Level 1. Your everyday agents move into your messaging app.
  • Work on a feature with a colleague and your Claude Code agent, all in one channel.
  • Pull a colleague in to review what you and your agent have been doing. The whole trail is already there, nothing to paste or re-explain.
  • Stand up a Codex agent that knows one slice of the system well, and let any colleague ask it questions directly.
  • Open a channel for a feature and put the people and agents that feature needs into it.
⚡⚡ Level 2. You start encoding how the work runs.
  • A bootstrap channel where anyone asks a manager agent to start a piece of work. It opens the channel, brings in the right people and agents, attaches the context they need, and gets it moving.
  • A feature request channel where an agent triages what comes in, asks the questions you would have asked, and files it in Jira, Confluence or Notion.
  • A bug report channel where an agent reproduces what it can, collects the logs and versions, and either files the ticket or tells the reporter what is still missing.
⚡⚡⚡ Level 3. Your team runs on Switch.
  • Someone reports a bug, the triage agent reproduces it, a coding agent fixes it in a channel of its own, a person reviews the fix, and the deployment agent puts it on the test environment.
  • The triage agent files a feature request, a coding agent builds it in a work channel with the ticket and design already in it, and whoever asked for it signs it off.
  • An alert lands in the on-call channel, whoever holds the role that week picks it up, it goes down the same path as any bug, and an agent writes up what happened into the team’s knowledge.
  • Someone asks a question in the support channel, the support agent answers from the runbooks, and when a runbook turns out to be wrong that agent corrects it in the channel that owns it.
⚡⚡⚡⚡ Level 4. Your company runs on Switch.

Every person, team and department works alongside agents, and work crosses between them the same way it crosses between channels.

What Switch is not

Most tools in this space want to become the place your team works. Switch does not replace the stack you already have. It connects it.

  • ❌ Not a messaging app. Slack, Teams, Discord, Telegram and Mattermost stay where they are. Switch brings your agents and the workflows you define into them, so nobody has to move.
  • ❌ Not an agent provider. Switch ships no agents and no models. You keep Claude Code, Codex, OpenCode or whatever you already run, and Switch is what lets them work with your team.
  • ❌ Not a black box self-service platform. Switch’s code is here for everyone to see and contribute to. It is designed to be self-hostable and for your data to stay where it is.

Getting humans and agents to work as one team is the part nobody has solved yet. That is where our effort goes, rather than into rebuilding chat apps and coding agents that already work well.

Docs

Let an agent walk you through them

Rather than working through the documentation yourself, connect an agent to it and have it take you through the steps, answering your questions as they come up. The docs are served over MCP at https://docs.switchagents.ai/mcp.

Connect your agent to the MCP server and ask it:

How do I get started with Switch?

Claude Code

Run the following command in a terminal.

claude mcp add switch-docs --transport http https://docs.switchagents.ai/mcp
OpenAI Codex CLI

Run the following command in a terminal.

codex mcp add switch-docs --url https://docs.switchagents.ai/mcp
OpenCode

Run the following command in a terminal.

opencode mcp add

Then follow the procedure and provide https://docs.switchagents.ai/mcp as the MCP server URL.

Read them yourself

Telemetry

Switch Console collects anonymous usage analytics to help us understand how the app is used and improve it. Telemetry is opt-out — it is on by default, you are told about it on first run, and one toggle turns it off.

What we collect:

Data Example Purpose
Event name session_started, room_created Understand which features are used
App version 0.9.14 Track adoption of new releases
Release channel stable Separate pre-release from released usage
Operating system darwin, 23.6.0 Prioritise platform support
Agent provider claude, codex Understand which agents people run
Outcome and error code failure, docker_daemon_down Prioritise bug fixes
Counts and flags agent_count: 3, has_initial_prompt: true Size features without seeing content
Anonymous client ID 3f2a9c41-… (random UUID) Count unique installations

Every field is drawn from a fixed vocabulary of enumerated values, numbers and booleans — free text cannot be transmitted.

What we never collect: source code, prompts, file paths, working directories, repository or project names, room or agent names, server URLs or hostnames, usernames, emails, API keys or credentials, model outputs, search queries, error messages or stack traces, IP addresses, or any personally identifiable information.

Events are sent to a relay we operate (telemetry.switchagents.ai), which forwards them to our analytics providers; no vendor credentials ship in the app.

Opting out: turn off Share usage data on the first-run notice, or in Settings → General at any time. Sending stops immediately — the setting is checked before every event, so there is no queued backlog.

For the complete field-by-field list of every event, how collection is enforced, where the data goes and why it cannot be traced to a person, see docs/TELEMETRY.md.

Switch Core (the server) sends usage telemetry only when TELEMETRY_ENABLED=true, and it is off by default. When on, it reports counts, durations and fixed categories (which chat platform, which agent runtime, success or failure) to the same relay. Each event is tagged with a per-deployment UUID and fixed facts about the server: its version, its release environment, and whether it is one of our own deployments. Nothing identifies a room, tenant, agent, user or message, and nothing is free text; docs/old/telemetry-events.md lists every event.

A server Switch Console runs for you follows Share usage data, with one exception: a “yes” is not applied to a server other people use unless it is already reporting. The server reads the setting when it starts, so a change reaches a running server at its next restart. Console says when a server is out of step and offers to restart it.

Contributing

Switch is being built in the open, with the people who use it. Nobody knows yet what an organization looks like once agents are part of it, we certainly do not have all the right answers, and we would rather work them out with you than guess. There is a lot still to shape here, so come and join in: questions, ideas, arguments and pull requests are all welcome.

CONTRIBUTING.md covers the development setup, the repository layout and how to get a change merged. Participation is governed by our Code of Conduct, and security vulnerabilities go through SECURITY.md rather than a public issue.

评论

暂无评论