渠道插件实现

通过 ChannelPlugin 与 ChannelBase 接入平台消息，正确构造 Envelope 和附件。

This page has not been translated into English yet. The original Chinese version is shown below.

渠道插件封装为 Extension，启动时加载。插件负责平台连接、接收、格式转换和投递；ChannelBase 负责访问门禁、会话路由、排队、命令及崩溃恢复。

公开契约

入口导出名为 plugin 的 ChannelPlugin，含 channelType、displayName、requiredConfigFields 和 createChannel。工厂获得 name、config、bridge、options，再创建继承 ChannelBase 的适配器。

bridge 类型使用 ChannelAgentBridge，不写死 AcpBridge。独立 channel start 当前传 AcpBridge，daemon worker 则提供基于 DaemonChannelBridge 的 facade；旧 TypeScript 插件应迁移类型注解，JavaScript 运行行为不因此改变。

manifest 示例：

{
  "name": "my-channel-extension",
  "version": "1.0.0",
  "channels": {
    "my-platform": {
      "entry": "dist/index.js",
      "displayName": "My Platform Channel"
    }
  }
}

channels 键必须与 plugin.channelType 一致。requiredConfigFields 校验通用 ChannelConfig 之外的必需字段，不替代平台身份校验。

适配器方法

实现 connect() 连接并注册平台消息回调，sendMessage(chatId, text) 格式化/拆分/投递，disconnect() 清理连接。消息规范化后交给 handleInbound(envelope)，不要绕过基类门禁直接 prompt。

多数适配器应原样传递 options。自行创建 SessionRouter 并交给 super 时，需 registerBridgeEvents: true，让 ChannelBase 直接收到 toolCall/sessionDied；gateway 提供 router 时保持未设置。

bridge.shellCommand 和 bridge.btw 是可选方法，先检查存在再开放对应功能。daemon worker 只在服务端公布 session_shell_command/session_btw 时提供它们。

Envelope

字段	要求
channelName	使用当前实例 this.name
senderId	跨消息稳定的平台用户 ID，用于权限和路由
senderName	显示名，不能代替稳定身份
chatId	明确区分私聊与群会话
text	原消息正文，按平台规则去机器人提及
isGroup、isMentioned、isReplyToBot	准确布尔值，直接影响 GroupGate
threadId、messageId	可选线程和消息关联
chatName、referencedText	平台提供的会话名称和引用上下文
attachments	结构化媒体附件

不要因为希望消息通过就把 isMentioned 统一设 true，或把群伪装成私聊。平台身份和 boolean 映射有误会改变授权结果。

附件处理

Attachment.type 为 image、file、audio、video；mimeType 必需，可带 base64 data、绝对 filePath 和 fileName。图片 data 进入视觉输入，文件路径追加到 prompt 供 agent 读取，理解能力仍取决于模型和工具。

新实现使用 attachments，旧 imageBase64/imageMimeType 仅供兼容。官方示例用平台 fileName 拼接临时路径，示例没有完成不可信文件名的路径校验；实际适配器应验证或自行生成落盘名称，不能直接将原始上传名当可信绝对或相对路径。

官方参考包括 packages/channels/plugin-example 的最小 WebSocket adapter，以及 Telegram、DingTalk 实现。输出来源标记和主动目标限制见显示与投递契约。