xAgent 连接器管理：微信、Telegram、飞书与浏览器
状态：实验性能力，页面、协议和认证流程仍可能调整。
适用对象
- 普通用户通过“我的连接”绑定外部账号，检查认证、通道和可用工具。
- 管理员通过“Connector 管理”接入 Connector 服务，检查 Connector Card、health、协议和工具声明。
这是什么
Connector 是 xAgent 与外部系统之间的协议桥。它既可以把微信、Telegram、飞书等渠道的消息主动送入 xAgent，也可以把 xAgent 的回复、执行状态和文件发送回原渠道。
与 MCP 相比，Connector 更强调外部事件、用户连接和双向通道；MCP 更偏向任务执行时按需调用外部工具。详细区别见什么是连接器。
v0.0.6.beta 的连接器版本
服务端版本与 Connector 版本独立发布。v0.0.6.beta 文档对应的当前 Connector 版本是：
| Connector | 版本 | 主要用途 |
|---|---|---|
| WeChat Connector | 0.0.8 | 微信消息、媒体发送与接收，以及连接上下文续期 |
| Telegram Connector | 0.0.9 | Telegram Bot 私聊和群聊消息 |
| Feishu Connector | 0.0.8 | 国内飞书单聊和群聊 @ 机器人消息 |
二进制统一从 https://downloads.xagent.xiagaogao.com/connector/ 下的 weixin/、telegram/ 和 feishu/ 目录下载。安装步骤见开始安装。
xAgent 还提供 Browser Connector，让受控浏览器扩展把页面交互能力接入当前用户。它由 xAgent 内部管理，不使用上述三个 IM Connector 的独立安装包。
页面入口
| 页面 | 面向对象 | 作用 |
|---|---|---|
| 我的连接 | 普通用户 | 管理当前用户的账号认证、通道状态和可用工具 |
| Connector 管理 | 管理员 | 管理系统级 Connector catalog、Card、health、协议和工具声明 |
“我的连接”在简洁模式下仍然可见；“Connector 管理”只对管理员显示。
连接外部账号
- 打开“我的连接”。
- 选择要连接的外部系统。
- 创建连接或打开已有连接详情。
- 按页面提示完成扫码、授权或参数绑定。
- 确认认证状态和通道状态正常。
- 回到 Agent会话，用自然语言说明要处理的消息或对象。
示例：
请查看最近一条客户微信消息，先整理回复草稿，不要直接发送。
微信
按页面提示扫码并完成连接。微信连接使用收件人范围的 context_token 维持可回复上下文；xAgent 会在到期前提醒并尝试续期。上下文已经失效时，发送动作会被阻止，需要先重新建立有效连接。
Telegram
提交自己的 bot_token 和目标 chat_id。绑定私聊前，先向 Bot 发送 /start 或任意消息。Connector 把 Bot Token 保存在自己的状态目录，不会把它写入 Tool 参数、Skill 或会话消息。
飞书
当前支持国内飞书，暂不支持 Lark。按页面扫码确认创建预设名称的 xAgent助手 应用，不需要手工填写 App ID 或 App Secret。若要让 xAgent 处理飞书图片，需要在飞书开放平台为对应应用开通 im:resource 权限。
双向消息与文件
当前公共 Connector 协议版本为 3.0，IM 通道使用 xagent.im.v2 数据协议。它支持：
- 外部消息进入 xAgent，并把最终回复发回原通道。
- 回复增量、确认消息和执行活动状态。
- 文件引用随消息传递。
- 文件内容通过独立传输平面上传或下载，不在 WebSocket 消息中直接传输 base64 文件内容。
这意味着 Connector 不只负责“收到一条文本”，还要维护消息确认、执行状态、文件引用和最终回复之间的完整链路。
健康状态
xAgent 会连续探测 Connector health，并按连续失败次数更新状态：
| 连续探测结果 | 状态含义 |
|---|---|
| 成功 | 在线；此前失败计数被清除 |
| 失败 1 到 2 次 | 不稳定，连接可能暂时抖动 |
| 失败 3 次及以上 | 离线，当前不应继续依赖该通道 |
后续探测成功时会恢复在线。排查“消息没有到达”时，应同时检查 Connector health、用户认证状态、外部平台权限和消息发送日志。
Connector 管理
管理员添加 Connector 时，xAgent 会读取 Connector Card、探测 health，并保存到系统级 catalog。
| 字段 | 说明 |
|---|---|
| Connector 地址 | xAgent 服务端可以访问的 Connector 服务地址 |
| API Key | 可选；设置后作为 Bearer Token 访问 Connector Server |
接入后重点确认：
- health 正常，连续探测能够恢复状态。
- Card 中的名称、版本、协议和目标系统符合预期。
- 登录流程真实可用，例如扫码、Bot 参数绑定或账号授权。
- 工具声明只包含当前可以执行的动作。
- Connector Skill 和可能触达的数据类型声明完整。
不要把未来可能支持、但当前不可用的能力写进工具声明。工具一旦被公开，就可能被 Agent 在任务中选择。
开放协议与扩展
自定义 Connector 需要提供 Connector Card、health、认证流程、WebSocket 数据通道和必要工具。协议适合扩展新的 IM 渠道、企业内部系统、生成服务或其他智能体入口。当前协议仍处于测试阶段，开发前应先确认目标 xAgent 版本支持的协议和能力边界。
安全注意
- 不要把密码、token、验证码写进会话。
- Connector API Key 只用于 xAgent 后端与 Connector Server 之间的认证。
- Connector 应使用独立运行用户和独立状态目录，管理端口不应直接暴露到公网。
- 发送消息、修改外部数据或读取敏感信息时，应结合审批策略。
- 外部数据权限仍由外部系统账号和 Connector 控制，xAgent 不替代其权限体系。