Chat Access

了解 Chat 用户进入 Agent 前的准入模型

Chat Access 是 Messenger Power 的准入能力，只回答一个问题：某个外部 Chat 用户的私聊或群聊消息，是否可以进入指定 Agent。

它不是 Agent Core 权限，也不是通用 Role/Permission 系统。用户通过准入后，Messenger Power 只把消息交给 Agent，不会向 Session 或其他 Power 传播角色和权限。

核心规则

  • 默认拒绝：没有明确 allow Grant 时，消息不会进入 Agent。
  • 按 Agent 隔离：访问 Agent A 的批准不会自动允许访问 Agent B。
  • 按 Chat 账号隔离：身份键由 channel + issuer + subject_id 组成，同一用户通过两个 Bot 访问时是两个 Principal。
  • 范围明确：持久化 Grant 只有 direct 和 group；管理命令中的 all 会展开为两条 Grant。
  • deny 和 revoke 不同：拒绝后不再生成请求；撤销后用户可以再次请求。

批准流程

未批准用户发送私聊消息时，Messenger Power 会创建或复用一个 pending Request，并返回类似命令：

city power action chat access-approve assistant --input '{"request_id":"req_xxx"}' --token <token>

管理员也可以先查看请求：

city power action chat access-snapshot assistant --input '{}' --token <token>

群聊中的未批准消息默认静默拒绝，pending Request 仍会进入同一个管理列表。

数据保存位置

每个 Agent 独立保存：

~/.downcity/agents/<agent_id>/powers/messenger/messenger/access.db

Chat Access 数据库包含 Principal、Request、Allow/Deny Grant 和审计事件，不包含 Bot Token、App Secret 或消息正文。Messenger 渠道凭据属于 ~/.downcity/powers/messenger/config.toml 中的唯一明文配置；Messenger Config UI 读取时不会返回凭据原文。

与 City Auth 的区别

Agent Token 负责 HTTP 控制面认证。一个 Token 只属于一个 Agent，并拥有该 Agent API 的完整能力，不包含 User、Role 或 Permission。Chat Access 负责外部 Telegram、飞书或 QQ 用户能否向某个 Agent 发送消息。两者数据、身份和判定路径互不混用。

相关文档