Broker 开发速成（给贡献者）

10 分钟上手 Broker 开发。如果时间紧，读这篇即可开始；细节参考 Broker 开发教程 和 Broker 架构。

---

1. 10 分钟上手

1.1 生成作者密钥（一次性）

python main.py broker keygen --name alice
# 输出: pub_key_b64 = <base64 公钥>
# 密钥写到: ~/.familiars/authors/alice.key

1.2 从模板造一个 broker

# Windows
xcopy /E /I workspace\manager\brokers\starter_broker workspace\manager\brokers\my_broker

# Linux/macOS
cp -r workspace/manager/brokers/starter_broker workspace/manager/brokers/my_broker

编辑 workspace/manager/brokers/my_broker/manifest.json：

• 改 broker_id（必须 == 目录名）
• 改 name / description
• 填 author_pubkey（你的公钥）

1.3 本地开发迭代

# 打包
python main.py broker pack workspace/manager/brokers/my_broker \
    --output ./my_broker-0.1.0.broker.zip

# 校验（看输出）
python main.py broker verify ./my_broker-0.1.0.broker.zip --pretty
# → 输出 pub_key_b64、manifest_sha256、zip_sha256

本地开发不需要走 install（built_in / user_created 来源的包直接在 workshop 可见）。bridge 启动时自动扫描 workspace/manager/brokers/ 下的目录。

1.4 发布

到公共 relay（推荐）

python main.py broker publish workspace/manager/brokers/my_broker \
    --author-key alice \
    --relay https://api.familiars.cn

包进审核队列（pending）→ 运营 approve → 公开可见。

到自己的静态站

python main.py broker publish workspace/manager/brokers/my_broker \
    --author-key alice \
    --host-dir workspace/marketplace_host \
    --download-url-base https://your-marketplace.example.com

然后让用户 export FAMILIARS_MARKETPLACE_URL=https://your-marketplace.example.com。

1.5 用户端安装

# CLI
python main.py broker marketplace-index                       # 查索引
python main.py broker install \
    --url https://api.familiars.cn/marketplace/download/<broker_id>/<version> \
    --sha256 <zip_sha256> \
    --pubkey <pub_key_b64>

# UI：Workshop → 🏬 市场 → 点 my_broker → 安装

---

2. 关键文件（manifest.json）

{
  "broker_id": "my_broker",
  "name": "My Broker",
  "version": "0.1.0",
  "schema_version": 1,
  "author_pubkey": "<你的公钥>",
  "description": "...",

  "capabilities_required": ["guild", "ledger"],

  "role_defs": {
    "owner": {"caps": ["*"]},
    "member": {"caps": ["message.post", "room.read"]}
  },

  "ui": {
    "entry": "index.html"
  },

  "permissions": {
    "network": false,
    "extra_modules": []
  }
}

字段	说明
broker_id	全局唯一，== 目录名 == zip 内 id
author_pubkey	你的公钥（要写对，否则发布/安装校验失败）
capabilities_required	向集群声明要哪些本地 API
ui.entry	iframe UI 入口（相对 ui/ 的 .html）
role_defs	role → capability 集合
permissions	plugin 沙箱权限

---

3. 写 UI（最小例子）

ui/index.html：

<!DOCTYPE html>
<html>
<head><script src="../sdk.js"></script></head>
<body>
  <h1 id="title"></h1>
  <button onclick="load()">Load rooms</button>
  <pre id="out"></pre>
  <script>
    const api = window.familiars;
    document.getElementById('title').textContent = 'Hello, ' + api.broker_id;
    async function load() {
      const res = await api.rooms.list();
      document.getElementById('out').textContent = JSON.stringify(res, null, 2);
    }
  </script>
</body>
</html>

../sdk.js 由 bridge 的 /api/broker_app/<id>/sdk.js 提供，把 window.familiars 注入 iframe。

完整 SDK API：workspace/manager/brokers/SDK.md。

---

4. 写 Plugin（最小例子）

plugins/greeter.py：

from broker_sdk import store

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

triggers.json：

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

关键点：

• plugin 函数只接收单个 payload dict 参数；
• facade（store / rooms / ledger）从 broker_sdk 导入；
• 不要加 sdk 参数（旧版已废弃）。

---

5. 三条强制校验（缺一不可）

install_from_url 依次校验：

1. sha256：下载内容哈希与 index 记录严格一致
2. SIGNATURE：zip 内 <pubkey>\n<sig>\n，用 pubkey 验 sha256(manifest.json) 签名
3. author_pubkey：签名里的 pubkey 必须与 index 声明一致

任何一个不匹配 → 拒绝安装并报错具体原因。

---

6. 调试要点

症状	排查
broker 装不成功	audit.log 看具体动作；capabilities_required 是否被审批拦截
装成功又消失	检查 capabilities_required 是否被用户拒绝
iframe UI 不出来	浏览器 DevTools 看 window.familiars 是否存在；../sdk.js 是否加载
plugin 不触发	triggers.json 字段名拼对了吗？action_ref 格式是 plugins.<module>:<fn>
改 manifest 后签名失效	必须 broker sign 重签

调试命令：

# 看已装 broker
python main.py broker workshop list

# 看 audit 日志
tail -f workspace/.bridge.audit.log

# 看 marketplace 索引
python main.py broker marketplace-index

---

7. 学习路径

1. 抄 starter_broker：装本地 → 看 iframe UI 怎么被托管
2. 读 hello_broker：看 plugin + triggers 的最小例子
3. 读 example_broker：Vue/Vite 工程 + dist/ 构建产物
4. 读 ventaris：完整业务级参考实现（任务+勋章+房间六区域）

---

8. CLI 命令速查

命令	说明
python main.py broker keygen --name <name>	生成作者密钥
python main.py broker keys-list	列出本地密钥
python main.py broker pack --source-dir <dir>	打包为 .broker.zip
python main.py broker sign <zip> --author-key <name>	签名
python main.py broker verify <zip> --pretty	校验 + 输出三要素
python main.py broker install --url <url> --sha256 <hex> --pubkey <b64>	从 URL 安装
python main.py broker marketplace-index	查市场索引
python main.py broker publish <dir> --author-key <name> --relay <url>	发布到 relay
python main.py broker relay-review --relay <url> --operator-key <key>	运营审核

---

参考

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