连接器的 adapter contract：频道与限额

你的客户本来就在的频道

AI workspace 在对话本来发生的地方最有用。对很多组织来说，那个地方不是你们部署的 web 界面；而是人们不加思索就会打开的即时通讯频道 —— WhatsApp 群、Telegram 会话、Discord 服务器、Slack 工作区。Simmetric Chat 把这些频道当作同一知识库的一等表面：一个连接器把一个频道绑定到某个 workspace 与某个文档归档，从该频道到来的每个问题都由与内部聊天相同的 retrieval pipeline 回答。

标题中的那个词 —— adapter contract —— 命名了让这一切安全的设计规则。每个平台说不同的协议、有不同的凭据语义；因此每个平台都运行在专属 adapter 之后，而所有 adapter 共享的，是同一套固定的字段与限额词汇。结果读起来像一份安全策略：一个频道一个连接器，一个连接器一个 binding，一个 binding 一个语料。

本文从操作者的角度走一遍 contract：创建连接器要配置什么、v0.28 时代哪些表面改变了（编辑分支）、限额如何保护 workspace 不受外部流量冲击，以及语料中没有可引用答案时会发生什么。

仅 Enterprise 版本：connectors_enabled 在 Community 许可证里为 false，adapter 註冊表在那里为空，管理面板显示升级提示而不是创建表单。数据来源：FACT-CENSUS.md F-CONN-1。

创建时的配置

创建表单位于 Settings → Conversations → Connectors，要求两类字段。binding 类字段为集成命名：标识实例的 name、platform（telegram、discord、slack、whatsapp 之一）、频道的秘密 token，以及它服务的 workspace。行为类字段给对话塑形：决定语料的文档归档 binding、对打开对话者发送的欢迎消息、搜索无可引用来源时的 fallback 消息及其 fallbackLocale，以及这两个限额 —— 请求速率与每日会话，0 表示不限。

其中三个字段在创建后不可变，而这个不可变性不是实现细节 —— 它是信任模型。平台与秘密 token 定义谁可以与语料对话；workspace 定义什么可达。二者任一改变，集成的身份就改变，contract 以新建连接器作答，而不是变更。v0.28 系列的 schema 按字面携带这些规则：欢迎与 fallback 消息上限 4000 字符，平台与 token 仅限创建时填写，PUT 从不触碰。

凭据依设计留在服务端。应用以管理员填写的凭据调用频道 API；创建之后秘密 token 从不再出现在界面中，连接器的路由生活在你们自己的基础设施里 —— 频道对你们的机器说话，你们的机器对自家知识库说话。

adapter 层

每个平台运行在专属 adapter 之后，每个 adapter 的注册恰好对应平台真正要求的凭据：

• Telegram —— 来自 @BotFather 的 bot token，同时支持轮询与 webhook（卡片带模式专属按钮）。
• Discord —— Developer Portal 的 bot token 加 message intents；adapter 读取 bot 被授权的频道。
• Slack —— bot token 与 Slack 应用的 signing secret；消息事件经配置的 webhook 到达。
• WhatsApp —— 供应商 Business API 的秘密 token；adapter 调用供应商 API。

adapter 层是平台间差异消亡的地方。webhook 验证、intent 范围、轮询循环、消息形态归一 —— 各自留在自家平台的 adapter 后面，而产品其余部分只看到一种形态：连接器记录。adapter 注册表本身是 gated 的：Community 里它按构造为空，因此 Community 实例在外部流量抵达 workspace 之前就已关上。

编辑：v0.28.1 的可变表面

在 v0.28.1 之前，调整连接器意味着删除再重建。v0.28 系列的变更加上了编辑分支：卡片菜单带上 Edit 项，打开一个预填对话框，覆盖的恰好是可变表面 —— 经 PUT /api/connectors/:id:

• 可变 —— 名称、归档 binding、欢迎与 fallback 消息、fallback locale，以及两个限额（空 = null；0 = 不限）。
• 不可变 —— 平台、bot token、workspace。

isEnabled 开关保留在卡片上（它暂停路由而不删除配置），而这次变更与所有管理操作一样被审计：endpoint 记下 chat_connector.updated 事件，与 DELETE 分支的 chat_connector.deleted 对等。对于操作者的日常，编辑分支的意义很具体：把频道重新绑到现在建好的归档上，或在事件之后收紧限额，都不再以连接器的身份为代价。

回答路径与 fallback

从频道到来的每个问题都经过与内部聊天相同的 pipeline：对绑定归档的混合检索、来源引用、综合 —— 然后有出处的答案沿原频道返回。归档 binding 是 contract 里安静的核心：它让外部对话有出处。

当搜索没有产生可引用的有效内容时，contract 的答案是 fallback 消息 —— 一个以配置的 fallbackLocale 写成的回复。fallback 在位时，外部频道永远不会收到没有根据的生成内容；访客读到的是 fallback，而不是一句背后空无一物的断言。

限额作为 workspace 的舱门

请求限额与每日会话上限是 contract 对外部流量的防护：

• 0 = 不限（router 的哨兵值）。
• N = 每连接器的请求上限，以及每日会话上限。

与 isEnabled 一起，它们让操作者能把知识库暴露给公共频道，而作用半径是有界的：跑飞的机器人、被抓取的频道、或意外扩大的受众，最多消耗 workspace 配好的那部分。停用、收紧或重绑 —— 每项现在都是一次编辑（v0.28.1 分支），无需重建。

继续阅读

操作手册带着完整的操作者流程 —— 表单逐字段、各平台 adapter 表、审计行为 —— 在 /zh/docs/connectors:

• 连接器 —— 操作手册
• 本文数据：FACT-CENSUS.md 行 F-CONN-1（版本门槛）、F-CONN-2（v0.28.1 编辑分支）、F-LIC-1（粘贴密钥即激活 —— 无需触碰服务器）

Provenance：Simmetric Chat 的包 connector.schema.ts（字段形状 + 限额）、routes/connectors.ts（router + limiter）、CHANGELOG.md v0.28.1、license.ts（connectors_enabled），处于 census 固定的文档状态 v0.28.1（SHA aca5b8ff）。