渠道 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
消息入站后的执行与消息出站发送
入站用户授权、主体观测和角色解析

用户怎么使用

CLI 不再为 Chat 建立单独的配置命令。使用统一 Plugin Resource 管理器创建渠道 Resource，再把 Resource ID 保存到当前 Agent 的 Binding：

city plugin resource create chat --interactive
city plugin config chat <agent_id> --resources '["telegram-a1b2c3"]'

需要从终端调用 Chat Action 时，也使用通用 Plugin Action 命令：

city plugin action chat send <agent_id> --input '{"chat_key":"telegram:123456","text":"Done"}' --token <token>

SDK 装配

本地嵌入 SDK 场景里，ChatPlugin 接收已经构造好的 channel 对象。SDK 宿主直接提供 ID、展示名称和运行凭据，不读取 City Plugin Resource：

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

const plugin = new ChatPlugin({
  channels: [
    new TelegramChannel({
      id: "telegram-sdk",
      name: "SDK Telegram Bot",
      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,
      },
    }),
  ],
});

Plugin Resource 的 Schema、Resolver、加密存储和 Binding ID 解析属于 CLI 控制面，不进入 @downcity/agent，也不作为 ChatPlugin 的 Store 依赖。

飞书依赖

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

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

npm install @larksuiteoapi/node-sdk@^1.66.0

使用 Chat plugin 的独立子路径：

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

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

SDK action 用法

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

await agent.plugins.run_action({
  plugin: "chat",
  action: "send",
  payload: {
    chat_key: "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.run_action({
  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