示例与模板

已随仓库发布的 Broker 样例导航。这些是最佳学习材料 —— 每个样例都对应一种开发阶段。

---

1. 随仓库的模板

1.1 starter_broker —— 从零开始的空模板

字段	值
路径	workspace/manager/brokers/starter_broker/
类型	最小骨架，纯 UI demo
学习点	iframe UI 托管 + SDK 调用

starter_broker/
├── manifest.json        # broker_id, name, version, schema_version, ui.entry
├── README.md            # 指向 BROKER_DEVELOPMENT.md
└── ui/
    └── index.html       # ★ 单 HTML + ../sdk.js 最小例子

manifest.json 关键：

{
  "broker_id": "starter_broker",
  "name": "Starter Broker",
  "version": "0.1.0",
  "schema_version": 1,
  "author_pubkey": "",
  "description": "最小 broker 模板，配合 BROKER_DEVELOPMENT.md 从零开始讲解。",
  "ui": {"entry": "index.html"},
  "permissions": {}
}

ui/index.html 核心片段：

<script src="../sdk.js"></script>
<script>
  const api = window.familiars;
  async function loadRooms() {
    const res = await api.rooms.list();
    document.getElementById('out').textContent = JSON.stringify(res, null, 2);
  }
</script>

学习路径：从这里起步，改 broker_id + name + description，跑 broker pack + broker verify，在 workshop 看 iframe 怎么被托管。

---

1.2 hello_broker —— 最小 plugin + trigger

字段	值
路径	workspace/manager/brokers/hello_broker/
类型	Plugin + Trigger 最小参考
学习点	plugin_fn 触发路径 + SDK facade 调用

hello_broker/
├── manifest.json         # capabilities: ["rooms.read", "rooms.write"]
├── plugins/
│   └── greeter.py        # on_message_posted + on_approval_decided
├── triggers.json         # event → action_ref 分发
└── ui/
    └── index.html

plugins/greeter.py：

from broker_sdk import store

def on_message_posted(payload: dict) -> None:
    store.upsert(
        f"seen/{payload['message_id']}",
        title="seen",
        meta={"cluster_id": payload.get("cluster_id")}
    )

def on_approval_decided(payload: dict) -> None:
    msg_id = payload.get("approval_id") or payload.get("id") or ""
    store.upsert(f"decided/{msg_id}", ...)

triggers.json：

[
  {
    "event": "message.posted",
    "action_kind": "plugin_fn",
    "action_ref": "plugins.greeter:on_message_posted"
  },
  {
    "event": "approval.decided",
    "action_kind": "plugin_fn",
    "action_ref": "plugins.greeter:on_approval_decided"
  }
]

学习路径：抄 starter_broker 后加 plugins/ 和 triggers.json，验证 plugin 怎么被触发。

---

1.3 example_broker —— Vue/Vite 工程

字段	值
路径	workspace/manager/brokers/example_broker/
类型	Vue/Vite 完整工程
学习点	构建产物 dist/ 打包 + 高级能力

example_broker/
├── manifest.json         # ui_mode: "vue", entry: "./dist/index.html"
├── package.json          # @familiars/broker-ui 依赖
├── vite.config.ts
├── src/                  # Vue 源码
│   ├── App.vue
│   └── ...
├── assets/               # 静态资源
├── index.html            # Vite 入口
└── ui/                   # 构建产物 dist/ 会打进去

manifest.json 关键：

{
  "broker_id": "example_broker",
  "schema_version": "2",
  "name": "example_broker",
  "display_name": "Example Broker",
  "version": "1.0.0",
  "ui_mode": "vue",
  "entry": "./dist/index.html",
  "capabilities": [
    "graph-editor", "theme",
    "rooms.read", "rooms.write",
    "guild.tasks.read", "guild.tasks.write"
  ],
  "permissions": {"network": false, "storage": true}
}

学习路径：读 ui/ 里的 Vue 工程，看如何组织组件 + 调用 window.familiars。发布前 npm run build 生成 dist/。

---

1.4 ventaris —— 业务级参考实现

字段	值
路径	workspace/manager/brokers/ventaris/
类型	完整业务应用
学习点	任务 + 勋章 + 房间六区域 + 5 角色 + 信誉维度 + Recipe 协作

ventaris/
├── manifest.json         # 151 行，完整 role_defs + reputation_dimensions + guild + medal_catalog
├── cover.png             # 市场封面
├── README.md             # 业务说明
├── VENTARIS_TEST_PLAN.md # ★ 真实测试用例（436 行）
├── plugins/
│   ├── bootstrap.py      # 安装时初始化
│   ├── matcher.py        # 任务匹配
│   └── medals.py         # 勋章颁发
├── recipes/              # 自带 recipe（guild_recipe 自动起草 profile/contract）
├── triggers.json         # 51 行，完整事件分发
└── ui/
    ├── index.html        # iframe 入口
    ├── assets/           # 静态资源
    ├── views/            # 页面视图（4 个 tab）
    └── subtask-graph/    # 子任务图可视化（独立 iframe）

manifest.json 关键片段：

{
  "broker_id": "ventaris.local_ffexwwm5uptt",
  "name": "Ventaris 协作公会（测试版）",
  "version": "1.0.0",
  "author_pubkey": "8xp0BDrcm/zGKzRdzJVS+KzRdzJVS+...",
  "capabilities_required": ["guild", "ledger", "recipe_call", "scheduler"],
  "reputation_dimensions": [
    {"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}
  ],
  "role_defs": {
    "owner":   {"caps": ["*"]},
    "approver": {"caps": ["task.approve", "task.verdict", "settle.trigger", ...]},
    "issuer":  {"caps": ["task.publish", "task.propose", ...]},
    "developer": {"caps": ["task.accept", "task.deliver", ...]},
    "audience": {"caps": ["task.read", "message.read"]}
  },
  "guild": {
    "default_token_symbol": "VTP",
    "default_settlement_cron": "0 3 1 */3 *",
    "medal_catalog": [
      {"key": "rookie", "label": "新手冒险者", "criteria": {"auto_on_registration": true}},
      {"key": "task_1", "label": "初出茅庐", "criteria": {"tasks_completed": 1}},
      ...
    ]
  }
}

VENTARIS_TEST_PLAN.md（436 行）覆盖了：

• 注册流程 + 勋章自动颁发
• 任务发布 / 承包 / 交付 / 审批
• 驳回 → 重做的循环
• 跨角色跳转
• 季度结算 cron
• 子任务图可视化

学习路径：

1. 读 manifest.json 看完整 role_defs + reputation_dimensions + medal_catalog
2. 读 VENTARIS_TEST_PLAN.md 看真实测试用例怎么写
3. 读 triggers.json 看复杂事件分发
4. 读 plugins/matcher.py 看 plugin 怎么写撮合逻辑

---

1.5 market_test_broker —— 市场集成测试

字段	值
路径	workspace/manager/brokers/market_test_broker/
类型	测试用
学习点	marketplace 端到端校验

{
  "broker_id": "market_test_broker",
  "schema_version": 1,
  "name": "Market Test Broker",
  "version": "0.1.0",
  "description": "Used by marketplace integration tests",
  "author_pubkey": ""
}

主要用于 bridge 启动时测试 marketplace 索引 / 安装 / 校验流程。一般开发者不必参考。

---

2. 生产 relay 上的已发布

2.1 Ventaris

• Broker ID: ventaris.local_ffexwwm5uptt
• 发布日期: 2026-08-13
• 状态: 已上架 api.familiars.cn
• 安装: 任何用户打开 Workshop → 🏬 市场 → 点 Ventaris → 安装

3. 学习路径总览

3.1 推荐顺序

顺序	样例	学什么	复杂度
1	starter_broker	包结构 + iframe UI 托管	⭐
2	hello_broker	plugin + trigger 链路	⭐⭐
3	example_broker	Vue/Vite 工程 + 高级能力	⭐⭐⭐
4	ventaris	完整业务实现 + 测试计划	⭐⭐⭐⭐⭐

3.2 详细步骤

Level 1：starter_broker

1. 抄 starter_broker → 改 broker_id + name → 装本地 → 看 iframe UI 怎么被托管
2. 试调 SDK 方法：api.rooms.list() / api.broker_id / ...

Level 2：hello_broker

1. 读 plugins/greeter.py 看 plugin 怎么写
2. 读 triggers.json 看事件怎么绑
3. 自己加一个 on_approval_created 触发器

Level 3：example_broker

1. 看 ui/ 目录的 Vue 工程怎么组织
2. 看 manifest.json 里的 ui_mode: "vue" 与 entry: "./dist/index.html"
3. 在 ui/ 里跑 npm install && npm run build，验证构建产物

Level 4：ventaris

1. 读 manifest.json（151 行）—— 看完整 role_defs / reputation_dimensions / medal_catalog
2. 读 VENTARIS_TEST_PLAN.md（436 行）—— 看真实测试用例怎么写
3. 读 plugins/matcher.py —— 看撮合逻辑
4. 跑 python scripts/test_flow_e2e.py ventaris（如果有对应脚本）验证流程

---

4. 模板文件对照

文件	starter	hello	example	ventaris
manifest.json	✅	✅	✅	✅（151 行）
ui/index.html	✅（最小）	✅	-	✅
ui/ Vue 工程	-	-	✅	-
ui/ 复杂视图	-	-	-	✅（views/, subtask-graph/）
plugins/*.py	-	✅（1 个）	-	✅（3 个）
triggers.json	-	✅（2 条）	-	✅（51 行）
recipes/	-	-	-	✅
cover.png	-	-	-	✅
README.md	✅	-	-	✅
测试计划	-	-	-	✅（436 行）

---

5. 配套视频

Broker 开发教学视频将带你把 starter_broker 变成一个真 App（待录制）。

---

参考

• Broker 开发教程 / Broker 架构 / Broker 能力参考 / Broker 速成
• 完整开发手册：BROKER_DEVELOPMENT.md（仓库根）
• SDK 文档：workspace/manager/brokers/SDK.md