多用户与权限
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/dmGET /api/dmGET /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/me | networks[].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}/department | owner / 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 返回同样的正文:
{"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。
| 白名单 | 管什么 | 判在哪 |
|---|---|---|
peers | send_task / send_message / retry_task / reassign_task / cancel_task 的目标必须在名单里;发给自己的 alias / node_id 永远允许 | dispatchVerdict |
peers(另一条) | 设了 peers 的节点不能广播——广播的收件人是任意对端,与白名单语义直接冲突 | broadcastVerdict |
tools | MCP 工具名;名单外返回 tool_not_allowed | MCP 工具包装层 |
两条不能省的性质:
always类工具永远放行(get_inbox/ack_inbox/send_reply/report_status等)。挡掉它们,节点既不能干活、也不能报告自己干不了——会变成比「没受限」更隐蔽的假活节点。- 默认
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 同样的正文:
{"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 会变吗 |
|---|---|---|
explicit | mode_readonly / mode_restricted_not_assigned / peer_not_allowed / tool_not_allowed / rest_not_allowed / sender_not_allowed | 不会——这些与开关无关,永远拒 |
likely_already_blocked | human_only | 多数写路由另有一道「只有人能操作」的检查,调用方本来就被拒 ⇒ 通常不是增量 |
changes_behavior | beyond_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 变成空。