Broker 开发速成（给贡献者）

如果时间是首要约束，读这篇够开始。来源：BROKER_DEVELOPMENT_GUIDE.md（官方为贡献者写的速成），加内存中的实操沉淀。

---

10 分钟上手

# 1. 生成作者密钥（一次性）
python main.py broker keygen --name alice       # 输出 ~/.familiars/authors/alice.key

# 2. 从模板造一个 broker
cp -r workspace/manager/brokers/starter_broker /tmp/my_broker
# 编辑 manifest.json（broker_id / name / version / description / author_pubkey）

# 3. 打包 + 校验，本地安装（bridge 需在跑）
python main.py broker pack --source-dir workspace/manager/brokers/starter_broker
python main.py broker verify starter_broker.broker.zip --pretty
python main.py broker install --url file:///D:/path/to/starter_broker.broker.zip \
  --sha256 <64位hex> --pubkey <base64公钥>

注：install 走 install_from_url，需要远端 URL + sha256 + 作者公钥三要素。想本地快验，用 broker verify 就够，不必装。

之后在交换所里：python main.py broker marketplace-index 刷新本地 index 即可看到。

关键字段（manifest.json）

字段	说明
broker_id	全局唯一，== 目录名 == zip 内 id
author_pubkey	你的公钥（要写对，否则发布/安装校验失败）
capabilities_required	声明的能力
ui.entry	iframe UI 入口

三步校验缺一不可

1. sha256 一致；
2. SIGNATURE 用 pubkey 验 manifest.json 哈希；
3. pubkey 与 index 里的一致。

发布到市场：把 zip + index 条目传到 relay（走 publish 进审核队列 → approve 后对用户可见）。

调试要点

• audit.log 有 broker 每个动作（谁、何时、幂等 key）；
• 本地不装成功不进 index；装成功又消失 → 检查 capabilities_required 是否被审批拦截；
• iframe UI 用浏览器 DevTools 看 window.familiars API。

---

更多

• 完整来源：仓库根 BROKER_DEVELOPMENT_GUIDE.md
• 配套视频：Broker 教学视频（待录制）