渠道 runtime、queue worker、chat 授权、chat system text 和 chat 相关 action 的说明

`chat` Plugin

chat 是渠道运行时 plugin。

它主要持有：

channel state
chat queue worker
chat queue store
chat authorization hooks / resolves
chat 相关 actions
chat system text

主要形状

lifecycle
actions
hooks
resolves
system

它主要解决什么问题

当你需要这些能力时，应该关注 chat：

Telegram、Feishu、QQ 这类 chat 渠道 runtime
每个 agent/plugin 实例一条独立 queue worker
消息入站后的执行与消息出站发送
入站用户授权、主体观测和角色解析

用户怎么使用

大多数用户不直接控制渠道 runtime，而是使用 Downcity 暴露出来的 downcity chat 会话命令：

downcity chat
downcity chat list
downcity chat info --chat-key <chatKey>
downcity chat send --chat-key <chatKey> --text "Done"
downcity chat react --chat-key <chatKey> --message-id <messageId> --emoji "👍"
downcity chat context --chat-key <chatKey>
downcity chat history --chat-key <chatKey> --limit 30
downcity chat delete --chat-key <chatKey>

不带子命令的 downcity chat 会打开交互式 chat account 管理器。先在这里添加 Telegram、Feishu 或 QQ 账号，再把 agent 连接到这些账号。

Downcity 会刻意隐藏 status、test、open、close、reconnect、configuration、configure 这些渠道 runtime action。它们存在于 plugin runtime 里，但不是普通用户的 CLI 使用路径。

SDK 装配

本地嵌入 SDK 场景里，ChatPlugin 接收 channel 对象。每个 channel 自己携带 env 或账号池绑定信息：

import {
  ChatPlugin,
  FeishuChannel,
  QqChannel,
  TelegramChannel,
} from "@downcity/plugins";

const plugin = new ChatPlugin({
  channels: [
    new TelegramChannel({
      env: {
        TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
      },
    }),
    new FeishuChannel({
      env: {
        FEISHU_APP_ID: process.env.FEISHU_APP_ID,
        FEISHU_APP_SECRET: process.env.FEISHU_APP_SECRET,
        FEISHU_DOMAIN: process.env.FEISHU_DOMAIN,
      },
    }),
    new QqChannel({
      env: {
        QQ_APP_ID: process.env.QQ_APP_ID,
        QQ_APP_SECRET: process.env.QQ_APP_SECRET,
        QQ_SANDBOX: process.env.QQ_SANDBOX,
      },
    }),
  ],
});

channelAccountId 仍可作为账号池绑定能力使用，但 SDK 主路径推荐直接把 channel 需要的 env 传给对应 channel 对象。

飞书依赖

@downcity/plugins 不再把飞书 / Lark SDK 放进默认生产依赖。不启用飞书的应用可以直接导入 @downcity/plugins，无需安装飞书运行时依赖。

如果宿主应用启用了 FeishuChannel，需要在宿主应用中安装这个依赖：

npm install @larksuiteoapi/node-sdk@^1.66.0

导入路径不需要变化：

import { ChatPlugin, FeishuChannel } from "@downcity/plugins";

如果启用了飞书但没有安装 SDK，运行时错误会明确提示需要安装的包，并说明是在启用 channel "feishu" 前安装。

SDK action 用法

本地嵌入 SDK 场景里，可以按 plugin 名称调用会话 action：

await agent.plugins.runAction({
  plugin: "chat",
  action: "send",
  payload: {
    chatKey: "telegram:123456",
    text: "Done",
  },
});

用户侧最常用的 action 是 list、info、send、react、context、history、delete。

内置授权能力

Chat 授权现在属于 ChatPlugin 自己，不需要额外挂一个独立授权 plugin。

它通过三个 chat plugin 点参与入站链路：

chat.observePrincipal：记录已观测到的用户和会话
chat.authorizeIncoming：根据角色与权限决定当前消息是否允许进入 agent
chat.resolveUserRole：为 history / queue metadata 补齐当前用户角色

授权 action 也挂在 chat 下：

Action	作用
`authorization-snapshot`	读取授权目录、配置、已观测用户和会话
`authorization-read-config`	读取当前授权配置
`authorization-write-config`	覆盖写入授权配置
`authorization-set-user-role`	设置某个渠道用户的角色

SDK 调用示例：

await agent.plugins.runAction({
  plugin: "chat",
  action: "authorization-set-user-role",
  payload: {
    channel: "telegram",
    userId: "12345678",
    roleId: "admin",
  },
});

关键运行语义

queue worker 的生命周期归属于 plugin 实例
渠道 bot 状态也归属于 plugin 实例
入站授权能力归属于 ChatPlugin，但仍通过通用 plugin hooks / resolves 调度
Agent 只负责装配，不直接持有 chat 领域长期状态

公开性说明

ChatPlugin 从 @downcity/plugins 包根导出。

所以它是少数“虽然偏 lifecycle，但本地嵌入 SDK 用户也可能直接理解和装配”的 built-in 之一。

chat Plugin