import { Agent } from "@downcity/agent";
import { ChatAuthorizationPlugin } from "@downcity/plugins";

const agent = new Agent({
  id: "chat-agent",
  path: "/path/to/project",
  tools: {},
  plugins: [new ChatAuthorizationPlugin()],
});

chat-authorization 本身更常被运行时自动消费，而不是像普通业务插件那样由你手动频繁调用。

可调用动作

chat-authorization 暴露了四个最核心的动作。

Action	作用	适合什么时候用
`snapshot`	读取授权快照	想查看当前观测态和配置
`readConfig`	读取授权配置	想做控制面展示或调试
`writeConfig`	写入授权配置	想批量更新授权规则
`setUserRole`	设置用户角色	想单独修改某个用户的角色

读取当前授权快照

const snapshot = await agent.plugins.runAction({
  plugin: "auth",
  action: "snapshot",
});

这个结果通常会包含：

当前授权配置
已记录用户
已记录 chats

读取当前授权配置

const config = await agent.plugins.runAction({
  plugin: "auth",
  action: "readConfig",
});

写入新的授权配置

const result = await agent.plugins.runAction({
  plugin: "auth",
  action: "writeConfig",
  payload: {
    config: {
      telegram: {
        enabled: true,
      },
    },
  },
});

为某个用户设置角色

const result = await agent.plugins.runAction({
  plugin: "auth",
  action: "setUserRole",
  payload: {
    channel: "telegram",
    userId: "123456",
    roleId: "admin",
  },
});

它和 Hook / Resolve 的关系

auth 是理解这些机制最典型的内建样本之一：

guard：阻止不该进入的消息
effect：记录观察到的主体
resolve：给出用户有效角色

如果你读完 auth 还对这些概念不够直观，建议继续看：

它和 runtime ownership 的边界

auth 不是一个长期持有连接或线程的 runtime owner。

它更像一层规则编排：

在关键点上挂规则
把底层授权配置与状态存储统一暴露出来
让别的能力通过标准接口读取角色结果

如果你把它当作长期运行实例，会很容易误以为“权限判断应该塞进某个长期运行实例内部”。当前设计恰恰避免了这种耦合。

需要注意的边界

它只处理 chat 授权与角色解析相关问题

auth 不是一个通用 ACL 系统，也不是任意资源访问控制框架。

它当前聚焦在 chat 渠道场景。

它依赖标准的渠道信息

当前渠道识别依赖的是标准 channel 值，例如：

telegram
feishu
qq

如果传入了无效 channel，相关动作或 hook 会直接报错。

它不是 UI 配置型插件

你不会像 web、asr、tts 那样通过 setup / usage 去安装模型或切换 provider。

auth 的核心价值在规则判断，不在依赖安装。

什么时候优先参考它

当你要设计这些能力时，优先参考 auth：

入站守卫
用户 / 会话主体观测
角色解析
平台级规则型插件

auth Plugin

auth Plugin

它到底做什么

为什么它是“特殊 plugin”

它使用了哪些 plugin 能力

典型运行流

典型场景

场景一：只允许特定 Telegram 用户给 agent 发消息

场景二：第一次接入某个群聊后，想知道系统已经观察到了哪些主体

场景三：下游能力要根据用户角色决定是否放行

在 SDK 里怎么挂载