Skip to content

多用户与权限 ​

Hub 0.9.0-preview.68 起,服务器提供两样已经生效的能力:成员能访问哪些 Agent,以及同一网络里人与人的私聊接口。

用户管理、注册、私聊从 app 0.2.153 起。新注册或管理员新建的用户默认看不到任何 Agent,需要管理员在用户管理里授权。已有的账号、令牌和四个网络角色仍以 账号、Token 与角色 为准;命令行注册和邀请码没有因为这一页而取消。

成员能访问哪些 Agent ​

新加入的 member / viewer,agent_access 默认是 granted:还没被逐个授权之前,看不到这个网络里的 Agent。升级到这一版之前就已经在网络里的成员仍是 all,可见范围不因升级改变。owner、admin 和 Hub 管理员不受这道限制。

授权由该网络的 owner / admin,或 Hub 管理员,通过接口整体替换。授权表示能看见、能对话,不是能改这个 Agent 的配置、规则或日志。能看见一个 Agent,就能看到它完整的聊天记录:不同的人打开同一个节点,看到的消息是一样的——包括 owner 和其他成员发给它的消息,以及授权之前的历史。判定和字段见 用户与 Agent 权限端点。

成员能看哪些任务 ​

新加入的 member / viewer,任务范围(task_access)默认是 scoped,也就是「只看相关任务」:自己负责的、参与的、自己建的卡,加上授权给他的项目里的卡(viewer 只看授权项目)。管理员建号、POST /api/networks/{id}/members、邀请码加入都按这个默认值入库。升级到这一版之前就在网络里的成员仍是 all,可见范围不因升级改变。owner、admin 和 Hub 管理员不受这道限制;新加的 admin 照旧存 all。

要让某个成员看全部任务,由 owner / admin 或 Hub 管理员调用 PUT /api/networks/{id}/members/{user_id}/task-grants,传 {"task_access": "all"};传 project_grants 则整体替换他的项目授权。加成员时也可以直接在 POST /api/networks/{id}/members 里带 "task_access": "all"。

人与人私聊 ​

同一网络里的两个用户可以用这些接口互发私聊,只接受用户令牌:

  • POST /api/dm
  • GET /api/dm
  • GET /api/dm/threads

客户端从 app 0.2.153 起,可以在「人员」里和同一网络的人直接发消息。请求字段和错误见 同一节。

节点令牌不能管账号 ​

从这一版起,节点令牌(ntok_)不能访问账号、令牌、网络和成员这些管理接口,返回 403 user_token_required。节点只能给自己改名:必须是它绑定的网络,旧名字就是这个令牌代表的节点。改别的节点需要用户令牌。相关接口在 API 文档里注明了「需要用户令牌」。

部门负责人 ​

Hub 0.9.0-preview.91 起生效;app 从 0.2.196 起有「管理本部门」入口。

组织架构里每个部门可以设一个负责人。负责人管本部门:他负责的部门和它的全部下级部门。没有新角色,负责人身份每次请求都按部门的负责人字段现算。撤掉负责人,下一次请求就失去这些权限。viewer 当负责人不获得任何权限。

负责人能做的(只在本部门里):

  • 在本部门下建子部门;改名、移动、删除(只能删空部门)、换负责人。自己负责的那个部门归上一级负责人或管理员改。
  • 在本部门的子部门之间调人。把人调进或调出本部门(包括「未分配」)只有管理员能做。
  • 看、改、删本部门的任务卡。「本部门的卡」指负责人是本部门成员,或负责 Agent 的主人是本部门成员的卡。只凭负责人身份改卡时,卡只能交给本部门的人、负责人自己,或本部门成员的 Agent。只凭负责人身份删卡时,会记一条审计 requirement_deleted_by_leader,并私信卡的负责人;卡没有负责人时私信负责 Agent 的主人。
  • 只读查看本部门成员的 Agent 的状态和健康。派活、对话仍按 Agent 授权,管理仍只给节点主人和管理员。

越出本部门的写操作返回 403 department_scope_denied。不是负责人的成员,返回与以前相同的 403 owner/admin required。

怎么设负责人:owner / admin 在 app「设置 → 用户管理 → 成员与部门」里选中部门,设负责人。人必须是本网络成员;设成 viewer 不会报错,但 viewer 不获得负责人权限。比如把 alice 设为「研发部」负责人,她就管「研发部」和下面的「前端组」「后端组」。负责人也可以给自己下级部门设负责人,人只能从本部门里选。把负责人清空或换人,原负责人的权限立即失效。

在 app 里:负责人会看到「管理本部门」。电脑端在侧栏「人员」上方,手机端在「设置」页最上面。点开是同一棵部门树,本部门之外的部门灰显。每个部门有成员、任务、Agent 三部分,Agent 只读。界面上只出现 Hub 允许的操作。不是负责人的成员看不到这个入口。

部门项目授权:owner / admin 可以把项目授权给部门,授权同时覆盖它的全部下级部门。和按人授权一样,有授权就能看,can_edit 为真才能改。

和已有权限取并集:负责人权限和部门项目授权只会多给,不会收回任何人已有的按人授权、任务范围或参与人权限。任务范围为「全部任务」的成员,以及 owner / admin,行为不变。节点令牌不经过部门判定。

相关接口:

接口说明
GET /api/auth/menetworks[].managed_department_ids:本部门的部门 id(含下级),空数组表示不是负责人
GET /api/networks/{id}/departments每个部门多一个 viewer_can: {manage, create_child};owner / admin 另外拿到 project_grants。两个部门轴分开给:member_count 是直属人数(人轴,network_members.department_id),agent_count 是显式归属这个部门的 Agent 数(Agent 轴,nodes.department_id,同 alias 只算一次、保留 updated_at 最新的一行);agents_unassigned 是没有显式部门的 Agent 数。不按「负责人在哪个部门」推断 Agent 归属(#1976 / #2822)
POST / PATCH / DELETE /api/networks/{id}/departments[/{dept}]、PUT /api/networks/{id}/members/{uid}/departmentowner / admin,或在本部门范围内的负责人
GET / PUT /api/networks/{id}/departments/{dept}/project-grants部门项目授权,PUT 整体替换 {project_grants: [{project_id, can_edit}]}。只给 owner / admin;有一条项目不属于本网络,整批不写,返回 400
GET /api/networks/{id}/departments/{dept}/nodes本部门(含下级)成员拥有的节点:别名、状态、健康、主人,只读。负责人或 owner / admin 可用
GET /api/requirements?department_id=只要负责人在这个部门(含下级)、或负责 Agent 归这些人所有的卡;仍在调用者可见范围内。MCP requirements_list 同名参数

设计和取舍见 RFC-040。

节点自己的权限 ​

节点(Agent)的权限是它主人权限的子集,再按节点自己的模式往下收。主人是令牌绑定节点的 nodes.owner_user_id;没绑定节点的老令牌,主人是铸令牌的人。

三种模式,默认「正常」,升级不改任何节点的行为:

模式能做什么
normal 正常和今天一样;按 Hub 开关决定是否收紧到主人的权限(见下)
readonly 只读能读、能上报状态、能回复派给它的任务;写任务、派活、广播、管理节点一律拒
restricted 受限只看、只改派给它的任务卡(负责 Agent 是它、参与人有它、它建的,及这些卡的子任务);新建的卡必须把负责 Agent 设成自己;派活只能给主人被授权的 Agent;不能广播,不能订阅别的会话或整个网络的推送

模式设了就立刻生效,不看开关。只有节点主人、网络 owner / admin(和 Hub 管理员)能改,节点令牌不能改自己的模式,部门负责人也不能改:

PUT /api/nodes/{node_id}/permission-mode   {"mode": "normal" | "readonly" | "restricted"}

返回 {ok, node_id, permission_mode, previous},记审计 node_permission_mode_changed。不是这个网络的成员返回 404;成员但不是主人或 owner / admin 返回 403 permission_denied;节点令牌返回 403 user_token_required;模式写错返回 400 invalid_permission_mode。GET /api/nodes 的每一行多一个 permission_mode,以及 viewer_can.permission_mode:当前调用者能不能改这个节点的模式(与上面的写接口同一判据,节点令牌恒为 false)。客户端据此决定显示不显示「权限」设置。支持这些的 Hub 在 /health 的 capabilities 里带 node_permission_mode。

正常模式的收紧先记录、后执行。Hub 环境变量 COMMHUB_NODE_PERMISSIONS:

值行为
log(默认)照常放行;「本来会被拒」的按 (节点, 路由, 原因, 小时) 合并记进 node_permission_log
enforce记录并拒绝
off正常模式不判也不记(显式的只读 / 受限仍然生效)

正常模式会被收紧的情况(原因码):主人看不见或改不了的任务卡 beyond_owner_visibility、主人没被授权的 Agent agent_not_granted_to_owner、只有人能做的事 human_only(改别的节点、建 / 改项目、写供应商 / 网络密钥、审技能)、不知道主人是谁 owner_unknown。显式模式的原因码是 mode_readonly 和 mode_restricted_not_assigned。

被拒时 REST 返回 403,MCP 返回同样的正文:

json
{"ok": false, "error": "node_permission_denied", "reason": "mode_readonly", "route": "PATCH /api/requirements/:id", "hint": "…"}

节点级白名单:只能联系谁、只能用哪些工具 ​

readonly / restricted 是粗粒度模式。要更细,用两张白名单——它们都是主人设的,设了就立刻生效,与 COMMHUB_NODE_PERMISSIONS 无关(原因码 peer_not_allowed / tool_not_allowed 属于显式原因)。

PUT /api/nodes/{node_id}/peer-allowlist   {"peers": ["alice", "n_xxx"]}   // alias 或 node_id
PUT /api/nodes/{node_id}/peer-allowlist   {"peers": null}                  // 清空
PUT /api/nodes/{node_id}/tool-allowlist   {"tools": ["send_task", "requirements_comment"]}
PUT /api/nodes/{node_id}/tool-allowlist   {"tools": null}                  // 清空

清空只能传 null。空数组 [] 会被拒(400 empty_allowlist_ambiguous) —— 因为它是歧义的: 有人读成「不限制」,有人读成「一个都不许」。曾经真的出现过这种分歧:客户端把 [] 显示成 「不允许任何工具」,而 Hub 把 [] 规范化成 null 也就是全放开 —— 界面说收紧了,系统其实放开了。 与其猜,不如拒收;GET /api/nodes 读回来只会是 null 或非空数组,永远不会是 []。

授权口径与 permission-mode 相同(用户令牌 + 节点主人 / 网络 owner·admin / Hub 管理员),分别记审计 node_peer_allowlist_changed / node_tool_allowlist_changed。

白名单管什么判在哪
peerssend_task / send_message / retry_task / reassign_task / cancel_task 的目标必须在名单里;发给自己的 alias / node_id 永远允许dispatchVerdict
peers(另一条)设了 peers 的节点不能广播——广播的收件人是任意对端,与白名单语义直接冲突broadcastVerdict
toolsMCP 工具名;名单外返回 tool_not_allowedMCP 工具包装层

两条不能省的性质:

  1. always 类工具永远放行(get_inbox / ack_inbox / send_reply / report_status 等)。挡掉它们,节点既不能干活、也不能报告自己干不了——会变成比「没受限」更隐蔽的假活节点。
  2. 默认 NULL = 不限制。两张白名单为空时,行为与没有这两个字段完全一致。

目前 tools 只覆盖 MCP 工具;REST 路由的白名单尚未提供。

收件白名单:谁能给这个节点派活 ​

上面两张白名单管的是节点自己能做什么(发送侧)。收件白名单管的是谁能找它(接收侧):目标节点的主人限定「只有这些发件人能给它派活 / 发消息」。两侧独立,都要过。

PUT /api/nodes/{node_id}/inbox-allowlist   {"senders": ["planner", "n_xxx", "user:alice"]}
PUT /api/nodes/{node_id}/inbox-allowlist   {"senders": null}                 // 清空 = 谁都能发

与 peer-allowlist 完全同形:授权口径相同(用户令牌 + 节点主人 / 网络 owner·admin / Hub 管理员),[] 同样拒收(400 empty_allowlist_ambiguous),最多 200 条(400 too_many_senders),senders 不是数组也不是 null 返回 400 invalid_senders,节点令牌返回 403 user_token_required。成功返回 {ok, node_id, senders},记审计 node_inbox_allowlist_changed({from, to})。GET /api/nodes 每行带 inbox_allowlist(null 或非空数组)。支持的 Hub 在 /health 的 capabilities 里带 node_inbox_allowlist。

条目怎么匹配发件人:

条目匹配
<alias> / <node_id>Agent 发件人(节点令牌)
user:<username> / user:<user_id>人(Dashboard / 桌面端 / anet 的用户令牌)
user:*任何人
dept:<department_id>这个部门及其所有子部门里的 Agent(节点所属部门)和人(成员所属部门)
!strict关掉下面的隐式放行

隐式放行(不会把自己锁在门外):没有 !strict 时,以下发件人不看名单直接放行 —— 节点主人、网络 owner / admin、Hub 管理员,以及没有用户身份的旧式调用(open / legacy 模式,本来就「谁都是谁」)。要连他们也必须列名,就加一条 !strict。节点发给自己永远放行(含 !strict)。

判在哪:MCP send_task / send_message / retry_task / reassign_task / broadcast,REST POST /api/task / POST /api/broadcast,以及定时任务每次触发(按建排程的人 / 节点现判,被拒的这次运行记 sender_not_allowed)。判定放在各入口原有的权限检查之后:没权限 / 没授权的调用方仍然拿到原来那条统一错误,不能借它探测别人设没设名单。

被拒时是显式原因(不看 COMMHUB_NODE_PERMISSIONS,与 peer_not_allowed 同类),REST 403,MCP 同样的正文:

json
{"ok": false, "error": "node_permission_denied", "reason": "sender_not_allowed", "route": "POST /api/task", "hint": "…", "target": "reviewer", "sender": "user:bob"}

每次拒绝按目标节点记一行权限报表(sample = 发件人),主人能看到谁被挡在门外。广播不会因此失败:不收这个发件人的收件人被跳过,响应里 inbox_skipped: [{alias, node_id, reason: "sender_not_allowed"}] 列出它们(没人被跳过时没有这个键,回执与以前逐字节相同)。

命令行:anet node perm <node> --inbox planner,user:alice(见 CLI)。

报表:网络 owner / admin(用户令牌)可以看过去一段时间每个节点「本来会被拦」的次数,默认 7 天:

GET /api/networks/{id}/node-permission-report?since=<ISO 时间>

返回 {ok, network_id, since, mode, total, nodes: [{node_id, alias, permission_mode, total, by_reason, routes: [{route, reason, hits, sample, last_hour}], tool_calls: [{tool, hits}], tool_calls_total}], tool_calls: {total, by_tool: [{tool, hits}]}}。mode 是当前开关。记录保留 30 天,最多 20000 行;满了以后只给已有的行加次数。

total 与 nodes[] 只数「本来会被拦」的次数;tool_calls 是分母:受限工具实际被调用了多少次(按小时合并)。两套数字分表存储,放行的调用不会进拒绝统计。没有分母时「0 次拦截」既可能是没人越界,也可能是没人碰过这些工具,两者结论相反。

设计和取舍见 RFC-041。

enforce_impact —— 切 enforce 到底会影响多少(#2970 演练发现的口径问题):

node_permission_log 的行数是「本层本来会拒」,不等于「打开 enforce 后行为会变」。演练实测:projects_create 在 log 模式下已被处理函数自己的「只有人能操作」检查拒掉(user_token_required),却仍记了一行 human_only。所以报表把原因码分三层:

层含义打开 enforce 会变吗
explicitmode_readonly / mode_restricted_not_assigned / peer_not_allowed / tool_not_allowed / rest_not_allowed / sender_not_allowed不会——这些与开关无关,永远拒
likely_already_blockedhuman_only多数写路由另有一道「只有人能操作」的检查,调用方本来就被拒 ⇒ 通常不是增量
changes_behaviorbeyond_owner_visibility / agent_not_granted_to_owner / owner_unknown / unbound_token会——这才是真实影响面

估算影响时看 enforce_impact.changes_behavior,不要看 total。

nodes[] 里如果出现 unbound_token: true,那一项是未绑定节点的令牌(node_id 形如 token:<token_id>),同项还带 unbound_token_name(令牌名,通常形如 node:<alias>)。账本沿用老路径按令牌记账,而这类令牌没有 nodes 行 —— 所以两张白名单都管不到它们。报表把它们标出来,是为了不让管理员以为「名单之外没有别人在派活」;这类令牌的写类调用(派活 / 广播 / 建项目 …)会记一条 unbound_token 到权限报表:默认 log 模式只记录不拦,切到 enforce 才会拒。这就是「要不要强制要求绑定令牌」的判断依据 —— 先看有多少,再决定。最常见的原因是节点改过名而令牌没改——令牌名里的 alias 在 nodes 表里已经查不到,于是解析成「未注册」。处理方式是把令牌改名到当前 alias,或把它绑定到节点。

按节点的明细(nodes[].tool_calls):设「只能用哪些工具」之前先看这台节点实际用过哪些,否则白名单只能凭想象写,第一次上线就拦掉在用的东西。它在两处比网络级合计更有用:① 一台从不越界但天天在用的节点,过去只从「被拒过的行」聚合,在报表里根本不存在,而它恰恰最该出现在名单里;② nodes[] 按 tool_calls_total 降序,用得最多的排最前。

REST 写接口白名单:只允许这些写路由 ​

节点令牌除了 MCP 工具,还能直接打 REST 写接口(派活、广播、改需求、改节点属性…)。 tool_allowlist 管不到这一面,所以另有 rest_allowlist:

PUT /api/nodes/{node_id}/rest-allowlist  {"routes": ["POST /api/task", "PATCH /api/requirements/:id"]}
PUT /api/nodes/{node_id}/rest-allowlist  {"routes": null}     // 清空 = 不限制

GET /api/nodes 的每行带 rest_allowlist(null = 不限制)。清空只能传 null,[] 会被拒。

判定发生在请求入口的唯一 choke point,因为节点令牌的 REST 写面分散在两套既有判据里 (server.ts 的 restNodeDenied 与 requirements.ts 的 nodeTaskGate)。逐路由各加一次会形成 第三套规则,而且漏掉任一处就是「装了一半的安全开关」——那比没有更危险。

三条边界:

边界说明
只对节点令牌用户令牌 / daemon 令牌不受影响
只对写方法GET / HEAD / SSE 永不经过它——挡掉 SSE,节点会变聋(收不到派活),表现为静默失联而不是报错
只在设置时生效默认 NULL = 不限制,与 MCP 工具白名单同构

拒绝时返回 node_permission_denied / reason=rest_not_allowed,正文里的 route 是实际算出的标签, 照着加进清单即可。标签是归一化的(/api/nodes/n_abc123/attrs → PUT /api/nodes/:id/attrs), 所以换一台节点不用改清单。

节点目前能被拦到的 REST 写路由一共 9 条(另有 2 条 SSE 不在写方法内):

POST   /api/task
POST   /api/broadcast
DELETE /api/nodes/:id
PUT    /api/nodes/:id/attrs
PUT    /api/nodes/:id/avatar
POST   /api/requirements
POST   /api/requirements/:id/comments
PATCH  /api/requirements/:id
PATCH  /api/requirements/:id/checklist/:id

密钥传输闸门(管理员开关) ​

把密钥从 Hub 转发给节点,走明文公网等于裸奔。闸门按节点最近一次上报的 env_transport 判,只看 put(list / delete 不带密钥):

节点上报的 transport判定
loopback / https放行
plain拒,secret_transport_plain
未上报(NULL)默认放行;显式打开 strict 才拒,secret_transport_unknown
ANET_SECRET_TRANSPORT_GATE=off | log | enforce     # 默认 log:只记不拒
ANET_SECRET_TRANSPORT_GATE_STRICT=1                # 默认关:连「未上报」一起拒

为什么「未上报」默认放行:2026-10-29 生产只读统计,373 个会话里 332 个(89%)从未上报过 transport。把「未知即拒」设成默认,等于打开 enforce 当天拦掉近九成节点 —— 那不是收紧,是一次不在计划内的下线。

两个原因码要分开看:secret_transport_plain 要去查那台机器的网络链路;secret_transport_unknown 要做的是让节点上报。不同的人在不同的机器上做。

log 模式记在 GET /api/networks/{id}/env-transport-log(网络 owner / admin),按小时聚合,回答的是「如果现在打开 enforce,哪几笔会被拒、原因是什么」。

Agent 团队 ​

Agent(节点)有自己的一棵组织树「Agent 团队」,和人的部门树互不相关。团队可以多层,同一上级下不重名;一个 Agent 最多归一个团队,不归就是「未分配」。团队只用于组织 Agent,不给任何人新权限:谁能看、能对话哪个 Agent,仍按 Agent 授权。

  • 读:GET /api/networks/{id}/agent-teams 返回整棵树,每个团队带 members(node_id、alias、display_name)、lead(负责的 Agent)和 owner(user_id 和显示名)。网络成员和本网络的节点令牌都能读;只看授权 Agent 的成员只看到授权给他的那些。
  • 建、改、删:POST /api/networks/{id}/agent-teams {name, parent_id?};PATCH …/agent-teams/{team_id} {name?, parent_id?, sort?, lead_node_id?, owner_user_id?}(不能挂到自己或下级下面;lead_node_id 必须是本网络的节点,owner_user_id 必须是本网络成员);DELETE …/agent-teams/{team_id} 只能删没有子团队的团队,里面的 Agent 变回未分配。
  • 归团队:PUT /api/networks/{id}/nodes/{node_id}/agent-team {"team_id": "<团队 id>"},传 null 表示未分配。
  • 谁能改:owner / admin 全部;团队的 owner 管这个团队的子树(改名、建子团队、在子树里移动、把 Agent 放进或移出子树、设 lead),但不能改自己那个团队的 owner,也不能把它移出去或删掉。其他成员和节点令牌只读,写返回 403 agent_team_scope_denied。
  • 删除节点时,它的团队归属一起清掉,以它为 lead 的团队 lead 变成空。

相关 ​

Powered by Sleep2AGI

下载客户端