14. 管理成员

人开始出现之后(通过通道邀请或公开 URL),你得能看清他们是谁、决定他们扮演什么角色,偶尔做点清理。本章是这件事的运维侧口袋手册。

14.1 当前的管理面

当前 CLI 还没有 hermit users 命令。请选择以下任一支持路径:

  • Web 管理界面: 网关管理界面的 Users 选项卡可以查看成员及他们绑定的身份。
  • HTTP API: GET /api/agents/<agent-id>/members、POST /api/agents/<agent-id>/members、DELETE /api/agents/<agent-id>/members/<user-id>。
  • 智能体工具: owner 可以让智能体列出用户、提升或降级成员、链接或解链身份、合并重复。底层工具是 user_list、user_role_set、user_identity_link、user_identity_unlink、user_merge。

提升与降级在下一条消息时生效。

14.2 看懂用户列表

一行通常展示:user ID、角色、显示名(根据通道做的最佳猜测)、已链接的身份(telegram:12345、web:abc-uuid)、创建日期、最近活跃日期。

先看两列:

  • 角色 —— guest vs user。新行通常是 guest。
  • 已链接身份 —— 如果一个用户同时挂着 telegram: 和 web: 身份,说明已合并,智能体跨通道把这个人当作同一人。

14.3 Web 管理界面

网关管理界面的 Users 选项卡用于查看成员。按智能体的 Web 聊天管理视图目前还没有专门的成员选项卡。

14.4 角色差异

OwnerUserGuest
列出用户✓——
提升 / 降级✓——
链接 / 解链身份✓——
删除用户✓——

仅 owner 管理成员关系。

14.5 How-to 配方

14.5.1 把两个身份合并成一个人

场景 —— 你在用户列表里出现了两次:一次来自 Telegram 身份,一次来自 Web 登录。你想把它们合并。

步骤

  1. 在管理界面的 Users 选项卡里识别出这两条用户记录,或者以 owner 让智能体说:“列出用户及其链接的身份”。

  2. 挑你要保留的那条(称为 <keep-id>),记下另一个上的通道身份(<drop-id>)。假设保留者有 Web 身份,另一个有 Telegram。

  3. 以 owner 让智能体把 Telegram 身份链接到保留者,或用成员 API 添加该身份。

  4. 如果是两条都已建好的 user 需要合并,以 owner 让智能体把 <drop-id> 合并到 <keep-id>,它会调用 user_merge。

验证 —— Users 选项卡或 user_list 中,保留者下能看到两个身份。分别从两边通道发消息;都应该归属同一个 user。

14.5.2 审核通过后把 guest 提升为 user

以 owner 对智能体说:“把 <user-id> 在 main 上提升为 user。” 它会调用 user_role_set。

验证 —— 让他对智能体说”写一份文件”,成功。

14.5.3 批量清理过期 guest

通过管理界面的 Users 选项卡或 user_list 找到过期 guest,然后用成员 API 删除成员关系。

没有内置的”一键删除所有过期 guest”命令;列表变得吵的时候做一遍即可。

14.5.4 审计谁动过某个敏感工具

这是可观测性的活,不是成员管理。见 第 20 章 · Web 管理界面 的 Observe 选项卡,按工具调用过滤会话。

14.6 FAQ

一个用户能挂多个通道身份吗? 可以 —— 想链接多少链接多少。智能体把他们当作一个人。

同一个通道身份能属于两个用户吗? 不能。元组 (channel, channel_user_id) 唯一解析到一个用户。如果重链到另一个用户,旧链接会先被解开。

删除用户会一并删掉他的会话历史吗? 会话挂了 user ID;默认删除用户不会清除过往会话。要清理会话,用 session 管理命令(第 21 章 · 故障排除 里有列表)。

14.7 指引