Broker 能力参考
Broker 开发者可申请的能力（capability）完整清单。能力是 Broker manifest 声明的"我需要什么权限"，安装时用户会看到能力列表并同意后才能安装；运行时 broker 只能调用已授权能力对应的 API。
1. 能力模型
1.1 三类能力
| 类别 | 说明 | 默认授予 |
|---|---|---|
| UI 组件（Vue/iframe） | graph-editor / theme / form-builder / media-viewer | ✅ 默认授予 |
| API 访问 | rooms.read / rooms.write / guild.tasks.read / storage 等 | 部分默认，其余按需 |
| 沙箱（仅 Python plugin） | network / filesystem.read / filesystem.write / extra_modules | ❌ 需明确同意 |
1.2 风险等级
| 等级 | 含义 | 用户提示 |
|---|---|---|
| low | 只读访问，无副作用 | 通常自动授予 |
| medium | 写访问，有限影响 | 需要用户同意 |
| high | 破坏性操作或资金转移 | 需要用户明确同意 |
2. 完整能力清单
2.1 沙箱能力（Sandbox）
| Capability | 风险 | 说明 |
|---|---|---|
network | high | 访问外部网络（HTTP 请求），可能泄露数据 |
filesystem.read | medium | 读文件系统 |
filesystem.write | high | 写文件系统，可修改用户文件 |
extra_modules | medium | 导入额外 Python 模块（见 AST 白名单） |
沙箱能力只在 plugin 路径生效。纯 Vue/iframe broker 不需要沙箱能力。
2.2 UI 能力
| Capability | 风险 | 默认 | 说明 |
|---|---|---|---|
graph-editor | low | ✅ | 使用交互式图编辑器组件（VueFlow） |
theme | low | ✅ | 自动同步应用主题（light/dark） |
form-builder | low | ✅ | 使用动态表单构建器 |
media-viewer | low | ✅ | 使用图片/视频查看器 |
2.3 API 能力
| Capability | 风险 | 默认 | 说明 |
|---|---|---|---|
rooms.read | low | ✅ | 读房间列表与元数据 |
rooms.write | medium | ❌ | 创建/更新房间 |
rooms.delete | high | ❌ | 删除房间 |
guild.tasks.read | low | ✅ | 读任务列表与详情 |
guild.tasks.write | medium | ❌ | 创建/更新任务 |
guild.tasks.delete | high | ❌ | 删除任务 |
guild.tokens.write | high | ❌ | 转移代币 |
profile.read | low | ✅ | 读用户档案 |
profile.write | medium | ❌ | 更新用户档案 |
agents.read | low | ✅ | 读 agent 列表 |
agents.chat | medium | ❌ | 发消息给 agent |
storage | low | ✅ | broker-scoped KV 存储 |
2.4 高级能力（manifest capabilities_required）
这些是更粗粒度的"业务层能力"，manifest 里直接声明：
| Capability | 说明 |
|---|---|
guild | 公会/房间/帖子/任务库 |
ledger | 代币账本（发行/转账/结算） |
recipe_call | 调用本地 Recipe（如生成画像/合同） |
scheduler | 定时触发（cron） |
settle.trigger | 触发结算 |
3. Role 权限矩阵
3.1 默认 role → caps ladder
manifest 没声明 role_defs 时，使用默认 ladder：
| Role | Caps |
|---|---|
owner | *（全部） |
admin | room.* / thread.* / message.* / reputation.rate / deal.* / ledger.append / ledger.read |
mod | message.* / room.members.role / room.members.remove |
member | message.post / room.read / thread.read / reputation.rate |
guest | message.post / room.read |
3.2 自定义 role_defs
json
"role_defs": {
"owner": {"caps": ["*"]},
"approver": {"caps": ["task.approve", "task.verdict", "settle.trigger", "message.post", "message.read", "task.read"]},
"issuer": {"caps": ["task.publish", "task.propose", "task.read", "message.post", "message.read", "thread.join"]},
"developer": {"caps": ["task.accept", "task.deliver", "task.read", "message.post", "message.read", "thread.join"]},
"audience": {"caps": ["task.read", "message.read"]}
}3.3 通配符匹配
Capability 用点分命名空间，支持通配：
room.*匹配room.create/room.archive/room.members.add/ ...*匹配全部
room.create room.archive room.rename
room.members.add room.members.remove room.members.role
thread.create thread.archive
message.post message.delete
reputation.rate
deal.propose deal.transition
ledger.append ledger.read3.4 room.owner 超级角色
room.owner（创建者）被 registry 当作 super-role：无论 manifest 怎么写，role=owner 直接允许所有操作。防止错误 manifest 把房主锁在自己房间外。
4. 授权流程
4.1 安装时
- 用户点击安装 → bridge 解析
manifest.capabilities_required+manifest.permissions - 前端渲染能力列表 + 风险等级
- 用户勾选同意 →
POST /api/broker_workshop/instances/consent - 同意后 broker 启动 worker（沙箱）或注册到内存（进程内）
4.2 运行时
- 每个
(broker_id, role)组合有独立 caps 集合 PermissionRegistry是单源真相：bridge 路由、SDK 调用、plugin 代码都向它要答案capability_grants/（src/broker/capability_grants/repos.py）持久化 per-(broker, cluster) 的具体授予记录
4.3 漂移检测
manifest 升级后若能力 hash 变化 → 抛 CapabilityDrifted，需要用户重新同意。
5. 已知 broker 的能力需求
5.1 Ventaris（公会协作）
json
"capabilities_required": ["guild", "ledger", "recipe_call", "scheduler"]role_defs 完整示例见 §3.2。
reputation_dimensions：
json
[
{"key": "delivery", "label": "交付质量", "min": 0, "max": 10},
{"key": "punctuality", "label": "准时率", "min": 0, "max": 10},
{"key": "collaboration", "label": "协作", "min": 0, "max": 10},
{"key": "leadership", "label": "统筹", "min": 0, "max": 10}
]5.2 starter_broker
无显式 capabilities_required（纯 UI demo）。
5.3 hello_broker
json
"capabilities": ["rooms.read", "rooms.write"]5.4 example_broker
json
"capabilities": ["graph-editor", "theme", "rooms.read", "rooms.write",
"guild.tasks.read", "guild.tasks.write"],
"permissions": {"network": false, "storage": true}6. 能力注册表 REST API
6.1 查注册表
http
GET /api/broker_workshop/capabilities/registry返回所有已知 capability 的 CapabilityInfo 列表。
6.2 描述能力
http
GET /api/broker_workshop/capabilities/describe?names=rooms.read,guild返回指定能力的 {name, description, category, risk_level} 列表。
6.3 查审批状态
http
GET /api/broker_workshop/instances/{broker_id}/capabilities/status返回当前 broker 的能力审批状态。
6.4 批准能力
http
POST /api/broker_workshop/instances/{broker_id}/capabilities/approve
Body: {"capabilities": ["network", "extra_modules"], "approved": true}7. PermissionRegistry 实现细节
python
# src/broker/permissions.py
class PermissionRegistry:
"""Role-to-capability resolution.
* In-memory, rebuilt on each install / resume.
* Merges manifest's role_defs with sensible defaults.
* Wildcard matching via fnmatch.
* room.owner short-circuits to True.
"""
def register(self, broker_id: str, role_defs: dict) -> None
def check(self, broker_id: str, role: str, capability: str) -> bool
def list_roles(self, broker_id: str) -> list[str]
def list_caps(self, broker_id: str, role: str) -> list[str]检查是 O(1) dict lookup + fnmatch pass。PermissionRegistry 同步、无副作用。
8. 安全边界
| 边界 | 当前状态 |
|---|---|
| Sandbox 内的权限强制 | ✅ 已落地（AST guard + worker 限制） |
| Bridge API 的权限强制 | 🔶 待办（manifest.permissions 还没在 bridge 路由服务端强制） |
| 跨集群权限传递 | 🔶 钩子已留 |
参考源码
- 能力注册表：
src/broker/capability_registry.py - 权限 registry：
src/broker/permissions.py - 能力授予：
src/broker/capability_grants/repos.py - 成员能力：
src/broker/member_caps.py - REST：
src/bridge/routes/broker_workshop.py