Bridge REST API 全量参考

Familiars 后端是单进程 FastAPI bridge，默认监听 127.0.0.1:18711（HTTPS + HTTP/2）。60+ 路由文件，500+ 端点。本文档按路由文件组织，每个端点列出 HTTP 方法、路径、说明、请求体、响应体。

来源：src/bridge/routes/ + src/api/v1/endpoints/communication.py。

---

0. 传输与认证

传输

• 默认：HTTPS + HTTP/2（hypercorn + 自签证书 workspace/.bridge.crt）
• 回退：FAMILIARS_HTTP_INSECURE=1 → 纯 HTTP + uvicorn
• 端口：默认 18711。被占用时 Electron 自动选空闲端口，写入 workspace/.bridge.port

认证

• 所有非 /health、/api/auth/*、/api/broker_app/*、/api/demo/*、/api/chat/* 端点需要 X-Bridge-Token 头
• Token 也支持 ?token=... query 参数（SSE / WebSocket / <img src> 场景）
• BridgeTokenMiddleware 全局校验

SSE

• 对话流、状态流、提醒流、资产任务流等返回 text/event-stream
• HTTP/2 多路复用避免 Chromium 6-socket HTTP/1.1 限制

curl 示例

# 获取 token
TOKEN=$(cat workspace/.bridge_token)

# 列出 agent
curl -k -H "X-Bridge-Token: $TOKEN" https://127.0.0.1:18711/api/agents

# SSE 流式对话
curl -k -N -H "X-Bridge-Token: $TOKEN" \
  "https://127.0.0.1:18711/api/chat/stream?prompt=你好&agent_id=1"

# 创建待办
curl -k -X POST -H "X-Bridge-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"买牛奶","deadline":"2026-07-05T18:00"}' \
  https://127.0.0.1:18711/api/todos

---

1. chat.py — 对话

前缀：/api

方法	路径	说明	请求	响应
GET	/chat/inflight	获取当前正在进行的流	-	{slots: [{agent_id, dialogue_id, fingerprint}]}
POST	/chat/send	发送消息，同步获取完整回复	{prompt, dialogue_id?, parent_id?, type?, agent_id?}	{type, content, node_id, metadata}
GET	/chat/stream	SSE 流式回复	query: prompt, dialogue_id, parent_id, agent_id, type, model, regen_q, resume_a, call_mode	SSE: progress / result / error 事件
GET	/chat/recipe_dialogue_id	查询 recipe 对话映射	query: recipe_id	{dialogue_id}
POST	/translate	翻译文本（保留代码/URL）	{text, target?}	{translated}
GET	/models	列出 @-picker 可用模型	-	[{id, name, ...}]
GET	/chat/generate/stream	遗留生成 SSE（Generation.generate）	query: prompt, agent_id	SSE 流

---

2. agents.py — Agent 生命周期

前缀：/api

方法	路径	说明	请求	响应
GET	/agents	列出所有 agent（含 manager）	-	[{id, name, color, avatar_url, portrait_url, ...}]
GET	/agents/{agent_id}/dialogue_tree	获取 agent 的对话树	-	树结构 JSON
POST	/agents	注册已有 agent id	query: agent_id	{ok, agent_id}
POST	/agents/temporary	创建临时 agent	JSON body	{agent_id}
GET	/agents/create/stream	Agent 创建向导 SSE	query: name, identity, personality, appearance, voice, need_figure, need_audio, ...	SSE 进度事件
DELETE	/agents/{agent_id}	删除 agent	-	{ok}
POST	/agents/{agent_id}/release-memory	释放 agent 内存	-	{ok}
GET	/agents/{agent_id}/greeting	下载问候视频	-	视频文件
POST	/agents/{agent_id}/greeting/played	标记问候已播放	-	{ok}
GET	/agents/{agent_id}/pending_cg	待处理 CG	-	CG 状态
GET	/agents/diagnose-dirs	诊断孤立/重复 agent 目录	-	{orphan_dirs, duplicates}
GET	/agents/{agent_id}/avatar	获取头像	-	PNG 图片
GET	/agents/{agent_id}/portrait	获取立绘	-	图片/视频
GET	/agents/{agent_id}/client_portraits/{client_name}	客户端定制立绘	-	图片
GET	/agents/{agent_id}/figure_rgba	透明背景全身立绘	-	PNG
GET	/agents/{agent_id}/bg	获取背景图	-	图片
GET	/agents/{agent_id}/bust_loop	半身循环动画	-	WebM/WebP
GET	/agents/{agent_id}/bust_meta	半身动画元数据	-	{duration, fps, ...}
GET	/agents/{agent_id}/theme/{element}	主题元素资源	element: bubble/chat_bg/dock_bg/selected	PNG
GET	/agents/{agent_id}/theme/meta	主题元数据	-	{text_color_hint, bubble_text_color_hint, ...}
GET	/agents/{agent_id}/skills/{skill_id}/cg	技能 CG 资源	-	图片
GET	/manager/entry-image/{key}	Manager 入口图	key	图片

---

3. tree.py — 对话树

前缀：/api

方法	路径	说明	请求	响应
GET	/tree/{agent_id}/{dialogue_id}	序列化整棵树	-	{roots, nodes}
GET	/tree/{agent_id}/{dialogue_id}/query	语义搜索节点	query: text, k?	[{node, score}]
GET	/tree/{agent_id}/{dialogue_id}/node/{node_id}	获取单节点	-	{id, title, content, node_type, parent, children, metadata, ...}
GET	/tree/{agent_id}/{dialogue_id}/path/{node_id}	根到节点的路径	-	[{id, content, node_type, ...}]
DELETE	/tree/{agent_id}/{dialogue_id}/node/{node_id}	删除子树	-	{ok, removed, roots, nodes}
POST	/tree/{agent_id}/{dialogue_id}/move	移动子树	{node_id, new_parent_id?}	{ok}
PATCH	/tree/{agent_id}/{dialogue_id}/node/{node_id}	编辑节点文本	{content}	{ok}

---

4. todo.py — 待办

前缀：/api

方法	路径	说明	请求	响应
GET	/todos	列出待办	query: open_only?	[{id, title, content, deadline, completed, ...}]
POST	/todos	创建待办	{title, content?, deadline?, emergency_level?, needs_reminder?, remind_at?, frequency?}	{id, ...}
DELETE	/todos/{todo_id}	删除待办	-	{ok}
PATCH	/todos/{todo_id}	修改待办	{title?, content?, deadline?, emergency_level?}	{ok}
POST	/todos/{todo_id}/complete	完成待办	-	{ok}
POST	/todos/{todo_id}/uncomplete	重新打开	-	{ok}

---

5. schedule.py — 日程

前缀：/api

方法	路径	说明	请求	响应
GET	/schedules	列出日程	query: agent_id?	[{id, title, scheduled_time, ...}]
POST	/schedules	创建日程	{title, content?, scheduled_time, emergency_level?, frequency?, kind?, needs_reminder?, remind_at?}	{id, ...}
DELETE	/schedules/{schedule_id}	删除日程	-	{ok}
POST	/schedules/{schedule_id}/complete	完成	-	{ok}
POST	/schedules/{schedule_id}/uncomplete	重新打开	-	{ok}

---

6. cron.py — 定时任务

前缀：/api

方法	路径	说明	请求	响应
GET	/cron-jobs	列出定时任务	query: agent_id?, include_system?	[{name, cron, task, agent_id, ...}]
POST	/cron-jobs	创建定时任务	{name, cron, task, agent_id, action?, recurring?}	{name, ...}
PATCH	/cron-jobs/{name}	修改	{name?, cron?, task?, action?, recurring?, agent_id?}	{ok}
DELETE	/cron-jobs/{name}	删除	-	{ok}
GET	/cron-jobs/{name}/runs	近期运行记录	query: limit?	[{ts, status, output}]
POST	/cron-jobs/{name}/run-now	立即执行	-	{ok}
GET	/cron-jobs/{name}/diagnostics	诊断信息	-	诊断 JSON
GET	/cron/scripts/preview	脚本预览	-	脚本列表

---

7. reminders.py — 提醒

前缀：/api

方法	路径	说明	请求	响应
GET	/reminders/recent	近期提醒事件	query: since_ts?, limit?	[{kind, subject_id, ts, ...}]
GET	/reminders/stream	SSE 提醒流	query: start_ts?	SSE 事件流
POST	/reminders/{kind}/{subject_id}/snooze	贪睡	{minutes?}	{ok}
POST	/reminders/{kind}/{subject_id}/dismiss	忽略	-	{ok}

---

8. settings.py — 设置

前缀：/api

方法	路径	说明	请求	响应
GET	/settings	获取全局设置	-	设置 JSON
PUT	/settings	修改全局设置	部分设置 JSON	{ok}
GET	/agents/{agent_id}/settings	Agent 设置	-	设置 JSON
PUT	/agents/{agent_id}/settings	修改 Agent 设置	部分设置 JSON	{ok}
GET	/dialogues/{agent_id}/{dialogue_id}/settings	对话设置	-	设置 JSON
PUT	/dialogues/{agent_id}/{dialogue_id}/settings	修改对话设置	部分设置 JSON	{ok}
GET	/settings/llm	LLM 连接信息（密钥掩码）	-	{base_url, api_key: "***", default_model, ...}
GET	/settings/update-config	更新配置	-	配置 JSON
PUT	/settings/llm	修改 LLM 连接	{base_url?, api_key?, default_model?, transport_mode?, auto_fallback?}	{ok}
GET	/settings/models	列出已保存模型	-	[{name, url, ...}]
POST	/settings/models	添加模型	{name, url, api_key?, ...}	{ok}
DELETE	/settings/models/{name}	删除模型	-	{ok}
POST	/settings/models/{name}/ping	测试模型连通性	-	{ok, latency_ms}

---

9. auth.py — 认证

前缀：/api

方法	路径	说明	请求	响应
POST	/auth/register	注册本地身份	{nickname?}	{token, ...}
POST	/auth/login	登录（设备指纹）	-	{token, ...}

---

10. user.py — 用户资料

前缀：/api/user

方法	路径	说明	请求	响应
GET	/profile	获取资料	-	{nickname, ...}
PUT	/profile	修改资料	部分 profile JSON	{ok}
GET	/avatar	获取头像	-	图片文件
POST	/avatar	上传头像	multipart: file	{ok, url}
POST	/intro	自我介绍合并到 USER.md	{text}	{ok}

---

11. background.py — 后台模式

前缀：/api/background

方法	路径	说明	请求	响应
GET	/state	后台状态	-	{enabled, autorun_installed}
POST	/enable	启用后台 + 安装 autorun	-	{ok}
POST	/disable	禁用后台 + 卸载 autorun	-	{ok}
POST	/quit	优雅停止 bridge	-	{ok}

---

12. status.py — 运行时状态

前缀：/api

方法	路径	说明	请求	响应
GET	/status	状态快照	-	{states: {...}}
GET	/status/stream	SSE 状态增量流	-	SSE
POST	/status/debug	手动设置状态键	{key, label, detail?, level?, clear?}	{ok}

---

13. usage.py — LLM 用量

前缀：/api

方法	路径	说明	请求	响应
GET	/usage/summary	聚合用量	query: model?	{total_tokens, cost, per_model: {...}}

---

14. memory.py / memory_status.py — 记忆

前缀：/api

方法	路径	说明	请求	响应
GET	/memory	内存/VRAM 观测	-	{rss_gb, vram_gb, dialogues_loaded, ...}
GET	/memory/writer-status	Memory writer 诊断	query: recent?, agent_id?	{status, records: [...]}

---

15. monitor.py — 消息监听

前缀：/api/monitor

方法	路径	说明	请求	响应
GET	/	列出监听器状态	-	[{id, status, ...}]
GET	/settings	监听设置	-	设置 JSON
PUT	/settings	修改监听设置	设置 JSON	{ok}
GET	/file-roots	文件根解析快照	-	{wechat: [...], qq: [...]}
POST	/file-roots/refresh	强制重解析	{source, allow_ui_probe?}	{ok}
GET	/_diag	诊断快照	-	{preflight, vram_residents}
POST	/{monitor_id}/start	启动监听器	-	{ok}
POST	/{monitor_id}/stop	停止监听器	-	{ok}

---

16. skills.py — 技能

前缀：/api

方法	路径	说明	请求	响应
GET	/skills	全局技能列表	-	[{id, name, ...}]
GET	/skills/{skill_id}/source	获取 SKILL.md 源码	-	{source}
PUT	/skills/{skill_id}/source	修改 SKILL.md	{source}	{ok}
POST	/skills/{skill_id}/validate	校验 SKILL.md	-	{ok, errors?}
PATCH	/skills/{skill_id}/meta	修改技能元数据	{name?, description?, ...}	{ok}
DELETE	/skills/{skill_id}	删除技能	-	{ok}
POST	/skills/runs/{run_id}/cancel	取消运行	-	{ok}
POST	/agents/{agent_id}/skills/{skill_id}/unschedule	取消调度	-	{ok}
GET	/skills/runs/active	活跃运行列表	-	[{run_id, skill_id, ...}]
GET	/skills/runs/{run_id}/stream	SSE 运行进度	-	SSE
GET	/agents/{agent_id}/skills	Agent 可用技能	-	[{id, name, ...}]
GET	/recipes/{recipe_id}/skills	Recipe 关联技能	-	[{id, ...}]
GET	/recipe_skills/all	所有 recipe 技能	-	[{...}]
GET	/skills/{skill_id}/doc	原始 SKILL.md	-	文本
GET	/agents/{agent_id}/knowledge-bases	Agent 知识库	-	[{id, name, ...}]
POST	/agents/{agent_id}/knowledge-bases	创建知识库	{name, ...}	{id}
POST	/agents/{agent_id}/knowledge-bases/upload	上传 KB 文件	multipart	{ok}
DELETE	/agents/{agent_id}/knowledge-bases/{kb_id}	删除知识库	-	{ok}
GET	/agents/{agent_id}/skills/{skill_id}/cg_meta	CG 元数据	-	{...}
POST	/agents/{agent_id}/skills/{skill_id}/run	运行技能（后台）	-	{run_id}
POST	/agents/{agent_id}/skills/{skill_id}/run_in_dialogue	在对话中运行	{dialogue_id, parent_id?, initial_inputs?}	{run_id}
POST	/skills/import/folder	从文件夹导入	JSON body	{ok}
POST	/skills/import/zip	从 zip 导入	multipart	{ok}
POST	/skills/import/text	从文本导入	{text, skill_id?}	{ok}

---

17. skill_forge.py — 技能锻造

前缀：/api/skills/forge

方法	路径	说明	请求	响应
POST	/from-dialogue/derive_io	从对话推导 I/O	JSON body	{inputs, outputs}
POST	/from-dialogue/propose	从对话提议技能	JSON body（重）	{skill_md, ...}
POST	/from-dialogue/repropose	带锁定 I/O 重新提议	JSON body	{skill_md, ...}
POST	/summary	技能摘要	JSON body	{summary}
POST	/from-dialogue/build_and_preview	构建并预览	JSON body	{skill_md}
POST	/preview	预览 SKILL.md	JSON body	{skill_md}
GET	/revise/terminal/{skill_id}	修订终端状态	-	{status}
GET	/revise/inflight	进行中的修订	-	{...}
POST	/revise	应用用户指导修订	{skill_md, user_guidance, skill_id}	{skill_md}
POST	/commit	提交到注册表	{skill_id, skill_md, scope, agent_id?, overwrite?}	{ok}

---

18. skill_proposals.py — 技能提议审批

前缀：/api/skill_proposals

方法	路径	说明	请求	响应
GET	/	列出提议	-	[{id, ...}]
GET	/count	待审批数量	-	{count}
GET	/{pid}	提议详情	-	{...}
POST	/{pid}/approve	审批通过	-	{ok}
POST	/{pid}/reject	审批拒绝	{reason?}	{ok}

---

19. skill_workshop.py — 技能影棚

前缀：/api/skill_workshop

方法	路径	说明	请求	响应
GET	/skills	列出注册技能	-	[{id, name, ...}]
POST	/upload	上传资产	multipart: file	{asset_id, url}
GET	/asset	获取资产	query: asset_id	文件流
POST	/rewrite	重写分镜	JSON body	{storyboard}
POST	/run	启动运行	JSON body	{run_id}
GET	/run/{run_id}/status	运行状态	-	{status, progress, ...}
GET	/run/{run_id}/images	生成图片	-	[{idx, url, ...}]
POST	/run/{run_id}/regenerate_image	重新生成图片	JSON body	{ok}
POST	/run/{run_id}/approve_images	批准图片	JSON body	{ok}
GET	/run/{run_id}/clips	片段列表	-	[{idx, ...}]
POST	/run/{run_id}/clips/{idx}/generate	生成片段	JSON body	{ok}
POST	/run/{run_id}/concat_final	拼接最终视频	JSON body	{video_url}
GET	/draft	获取草稿	-	{...}
POST	/draft	保存草稿	JSON body	{ok}
GET	/history/{skill_id}	运行历史	-	[{run_id, ts, ...}]
GET	/history/{skill_id}/{run_id}	历史运行详情	-	{...}

---

20. asr.py — 语音识别

前缀：/api

方法	路径	说明	请求	响应
POST	/asr/transcribe	上传音频并识别	multipart: audio, form: language?	{text, segments}
POST	/asr/prewarm	预热 ASR 模型	-	{ok}
POST	/call/prewarm	预热通话模式全部模型	query: agent_id?	{ok}
POST	/focus/{mode}	用户注意力信号	mode: dialog/call/idle, query: agent_id?, dialogue_id?	{ok}
POST	/dialog/prewarm	预热对话模式模型	-	{ok}
GET	/gpu_tier	GPU 分级 + 功能	-	{tier, features: {...}}
POST	/model_choice	持久化缺失模型决策	query: model_id, choice	{ok}

---

21. digital_human.py — 数字人

前缀：/api/digital_human

方法	路径	说明	请求	响应
GET	/{agent_id}/status	资产清单 + 后端推荐	-	{assets, backend, ...}
POST	/{agent_id}/prewarm	后台预加载	-	{ok}
POST	/{agent_id}/unload	释放缓存会话	-	{ok}
POST	/{agent_id}/regenerate_voice	重新生成 voice.wav	-	{ok}

---

22. agent_workshop.py — 外部 Agent 导入

前缀：/api/agent_workshop

方法	路径	说明	请求	响应
GET	/kinds	可导入 agent 类型	-	["openclaw", "hermes", ...]
GET	/scan/{kind}	扫描安装状态	-	{installed, ...}
POST	/import/{kind}/start	启动导入会话	{need_digital_human?, display_name?, model?}	{session_id}
POST	/import/cancel	取消导入	{session_id}	{ok}
GET	/import/{kind}/stream	SSE 导入进度	query: session_id, approved_steps?	SSE
POST	/custom	自定义 agent	{display_name, repo_url?, cli_command, description?, need_digital_human?}	{agent_id}

---

23. agent_assets.py — Agent 资产管理

前缀：/api

方法	路径	说明	请求	响应
POST	/agents/upload_staging	staging 暂存	multipart: file, form: kind(figure/voice)	{staging_id}
POST	/agents/{agent_id}/asset_job/figure	启动立绘替换任务	multipart: file	{job_id}
GET	/agents/{agent_id}/asset_job	任务状态	-	{status, stage, ...}
GET	/agents/{agent_id}/asset_job/stream	SSE 任务流	-	SSE
POST	/agents/{agent_id}/asset_job/retry	重试单阶段	{stage}	{ok}
DELETE	/agents/{agent_id}/asset_job	丢弃任务	-	{ok}
POST	/agents/{agent_id}/asset_job/upload_stage	侧载阶段交付	multipart: file, form: stage	{ok}
POST	/agents/{agent_id}/voice/replace	替换语音	multipart: file, form: transcript?	{ok}
POST	/agents/{agent_id}/theme/{element}/replace	替换主题元素	multipart: file	{ok}
POST	/agents/{agent_id}/greeting/regenerate	重新渲染问候视频	-	{ok}

---

24. agent_activity.py — Agent 活动

前缀：/api

方法	路径	说明	请求	响应
GET	/agents/activity	Agent 活动列表	-	[{agent_id, activity, ts}]
GET	/agents/activity/stream	SSE 活动流	-	SSE

---

25. agent_recipes.py — Recipe CRUD

前缀：/api/recipes

这是最大的路由文件，56 个端点。以下列出核心端点。

方法	路径	说明
GET	/catalog	可接线模块目录
GET	/_meta/protocol	文件夹协议规范
GET	/{recipe_id}/docs	Recipe 文档列表
GET	/{recipe_id}/docs/{name}	获取文档
PUT	/{recipe_id}/docs/{name}	修改文档
DELETE	/{recipe_id}/docs/{name}	删除文档
GET	/{recipe_id}/utils	工具文件列表
GET	/{recipe_id}/utils/{name}	获取工具文件
PUT	/{recipe_id}/utils/{name}	修改工具文件
DELETE	/{recipe_id}/utils/{name}	删除工具文件
POST	/{recipe_id}/utils/upload	上传工具文件
GET	/	列出全部 recipe
GET	/{recipe_id}	获取 recipe 详情
POST	/{recipe_id}/duplicate	复制 recipe
GET	/{recipe_id}/renderers	自定义渲染器列表
GET	/{recipe_id}/renderers/{name}	获取渲染器源码
GET	/{recipe_id}/export_zip	导出 zip
POST	/import_zip	从 zip 导入
POST	/preview_zip	预览 zip 内容
POST	/import_folder	从文件夹导入
POST	/install	安装 recipe
POST	/{recipe_id}/create_agent	从 recipe 创建 agent
POST	/	创建 recipe
PUT	/{recipe_id}	更新 recipe
POST	/_meta/validate_chain_steps	验证 chain 步骤
DELETE	/{recipe_id}	删除 recipe
POST	/{recipe_id}/unbind_all_and_delete	解绑全部 agent 后删除
GET	/_state/default	获取默认 recipe 状态
DELETE	/_state/default	清除默认
POST	/{recipe_id}/set_default	设为默认
POST	/{recipe_id}/bind/{agent_id}	绑定到 agent
POST	/{recipe_id}/unbind/{agent_id}	从 agent 解绑
POST	/{recipe_id}/validate	验证 recipe
GET	/chain_source/{slot}	chain slot 实现枚举
GET	/_meta/reasoning_templates	推理模板列表
GET	/{recipe_id}/resolved_tools	已解析工具
GET	/{recipe_id}/tool_catalog	工具目录
GET	/{recipe_id}/skill_status	技能状态
GET	/{recipe_id}/knowledge_file	知识文件
GET	/{recipe_id}/digital_human_slots	数字人插槽
GET	/{recipe_id}/asset_file	资产文件
GET	/library	市场库列表
POST	/library/install	从市场库安装
POST	/library/publish	发布到市场库
GET	/{recipe_id}/capabilities/status/{agent_id}	能力审批状态
POST	/{recipe_id}/capabilities/approve/{agent_id}	批准能力
DELETE	/{recipe_id}/capabilities/approve/{agent_id}	撤销批准
POST	/eval/compare	评估对比
POST	/{recipe_id}/eval	运行评估
GET	/{recipe_id}/graph	获取图定义
PUT	/{recipe_id}/graph	更新图定义
DELETE	/{recipe_id}/graph	删除图
POST	/{recipe_id}/graph/test	测试图

---

26. recipe_dev.py — Recipe 开发工具

前缀：/api/recipe_dev

方法	路径	说明	请求	响应
POST	/compile	编译 recipe	JSON body	{ok, errors?}
POST	/dryrun	干跑	JSON body	{outcome, units}
POST	/e2e_test	端到端测试	JSON body	{pass, details}
POST	/publish_relay	发布到 relay	JSON body	{ok}
GET	/review_status	审核状态	-	{status}

---

27. flow_templates.py — Flow 模板

前缀：/api/flow-templates

方法	路径	说明	请求	响应
GET	/	列出模板	-	[{id, name, ...}]
POST	/	创建模板	JSON body	{id}
GET	/{template_id}	获取模板	-	{id, template, layout, ...}
PUT	/{template_id}	更新模板	JSON body	{ok}
DELETE	/{template_id}	删除模板	-	{ok}
POST	/{template_id}/validate	校验模板	-	{ok, errors?}
POST	/{template_id}/duplicate	复制模板	-	{new_id}
GET	/{template_id}/docs	文档列表	-	[{name}]
GET	/{template_id}/docs/{name}	获取文档	-	{content}
PUT	/{template_id}/docs/{name}	修改文档	{content}	{ok}
DELETE	/{template_id}/docs/{name}	删除文档	-	{ok}
GET	/{template_id}/export	导出	-	JSON
POST	/import	导入	JSON body	{id}
POST	/preview_bundle	预览 bundle	JSON body	{preview}
POST	/import_bundle	导入 bundle	multipart	{id}
GET	/{template_id}/export_bundle	导出 bundle	-	zip 文件
GET	/{template_id}/renderers	自定义字段渲染器列表	-	[{name}]
GET	/{template_id}/renderers/{name}	获取渲染器	-	{source}
POST	/{template_id}/renderers/{name}	创建/更新渲染器	{source}	{ok}
DELETE	/{template_id}/renderers/{name}	删除渲染器	-	{ok}

---

28. flows.py — Flow 实例

前缀：/api/flows

方法	路径	说明	请求	响应
GET	/	列出实例	query: status?, template_id?, limit?	[{instance_id, template_id, status, ...}]
GET	/{instance_id}	获取实例	query: trace_tail?	{instance_id, status, trace_tail: [...]}
GET	/{instance_id}/trace	完整 trace	query: limit?	[{ts, event, ...}]
POST	/{instance_id}/cancel	强制停止	-	{ok}

---

29. flow_dev.py — Flow 开发工具

前缀：/api/flow_dev

方法	路径	说明	请求	响应
POST	/publish_relay	发布到 relay	JSON body	{ok}
GET	/review_status	审核状态	-	{status}

---

30. comm (communication.py) — 通信中心

前缀：/api/communication

方法	路径	说明	请求	响应
GET	/messages	消息列表	query: agent_id?, since?, direction?	[{id, agent_id, content, ts, direction}]
POST	/messages	用户发消息给 agent	JSON body	{id}
POST	/send	Agent 推送给用户	JSON body	{ok}
GET	/approvals/pending	待审批列表	query: agent_id?	[{request_id, tool, args, ...}]
POST	/approvals/request	创建审批请求	JSON body	{request_id}
POST	/approvals/respond	响应审批	{request_id, approved, reason?, scope?, choices?}	{ok}
GET	/approvals/{request_id}	审批状态	-	{request_id, status, ...}
POST	/interrupt	中断 agent	{agent_id, reason?}	{ok}

---

31. broker.py — 交换所核心

前缀：/api/broker

方法	路径	说明
GET	/brokers	列出 broker
POST	/brokers/{broker_id}/register	注册 broker
POST	/brokers/{broker_id}/deregister	注销 broker
POST	/brokers/{broker_id}/scopes	设置 scope
GET	/brokers/{broker_id}/card	获取 card
POST	/brokers/{broker_id}/actions/{action}	执行操作
POST	/brokers/{broker_id}/deals/{deal_id}/transition	交易状态转换
GET	/brokers/{broker_id}/deals	交易列表
GET	/brokers/{broker_id}/ledger	账本
POST	/federation/receive	联邦接收
GET	/federation/status	联邦状态
POST	/federation/rooms/{broker_id}/{room_id}/federate	联邦房间
POST	/federation/threads/{broker_id}/{thread_id}/federate	联邦线程
POST	/federation/tasks/{broker_id}/{task_id}/federate	联邦任务
GET	/federation/rooms/{broker_id}	联邦房间列表

---

32. broker_workshop.py — 交换所工坊

前缀：/api/broker_workshop

最大的路由文件，90+ 端点。涵盖：实例管理、市场 index、封面、同意、能力审批、CRL/信任、房间/线程/消息/权限/声誉/触发器/审批。

核心端点：

方法	路径	说明
GET	/instances	列出已安装实例
GET	/instances/{broker_id}	实例详情
POST	/instances/install_from_url	从 URL 安装
GET	/marketplace/index	市场 index
GET	/marketplace/recipes/index	Recipe 市场 index
GET	/marketplace/flows/index	Flow 市场 index
POST	/marketplace/{kind}/like	点赞
POST	/marketplace/{kind}/coin	投币
GET	/marketplace/coin/balance	币余额
POST	/marketplace/coin/claim	领币
POST	/marketplace/{kind}/view	标记已查看
POST	/marketplace/report	举报
POST	/marketplace/ban	封禁
POST	/marketplace/unban	解封禁
POST/GET	/marketplace/moderators/*	版主管理
POST	/marketplace/cover/upload	上传封面
POST	/marketplace/cover/generate	AI 生成封面
GET	/instances/{broker_id}/rooms	房间列表
POST	/instances/{broker_id}/rooms	创建房间
GET/PATCH/DELETE	/instances/{broker_id}/rooms/{room_id}	房间 CRUD
GET	/instances/{broker_id}/rooms/{room_id}/threads	线程列表
POST	/instances/{broker_id}/rooms/{room_id}/threads	创建线程
POST/GET	/instances/{broker_id}/messages*	消息 CRUD + 反应 + 搜索
GET	/instances/{broker_id}/reputation/{cluster_id}	声誉
POST	/instances/{broker_id}/reputation/rate	评分
GET/POST/DELETE	/instances/{broker_id}/triggers*	触发器管理
GET/POST/DELETE	/instances/{broker_id}/capabilities/*	能力管理
POST/GET	/instances/{broker_id}/approvals*	投票审批
POST/GET	/instances/crl/*	CRL 管理
POST/GET	/instances/trust/*	信任管理
GET/POST	/instances/{broker_id}/permissions/*	权限管理
GET/POST	/instances/{broker_id}/member_caps*	成员能力

---

33. broker_app.py — Broker 应用静态资源

前缀：/api/broker_app

方法	路径	说明
GET	/{broker_id}/ui/{rel:path}	UI 静态资源（script/link/img）
GET	/{broker_id}/cover	封面图
GET	/{broker_id}/sdk.js	Broker SDK
GET	/_meta/sdk.js	SDK 元数据

---

34. broker_assets.py — Broker 资产

前缀：/api/broker_workshop

方法	路径	说明
POST	/instances/{broker_id}/assets	上传资产
GET	/instances/{broker_id}/assets/{asset_id}	获取资产
GET	/instances/{broker_id}/assets	资产列表
DELETE	/instances/{broker_id}/assets/{asset_id}	删除资产
GET	/instances/{broker_id}/capabilities	能力列表
POST	/instances/{broker_id}/capabilities/grant	授予能力
POST	/instances/{broker_id}/capabilities/revoke	撤销能力

---

35. guild.py — 公会系统（Ventaris）

前缀：/api/guild

Ventaris 公会子系统。任务/钱包/勋章/收件箱/配方运行。80+ 端点。

核心端点：

方法	路径	说明
GET/PUT	/instances/{broker_id}/rooms/{room_id}/config	房间配置
POST	/instances/{broker_id}/tasks	创建任务
GET	/instances/{broker_id}/tasks	任务列表
GET	/instances/{broker_id}/tasks/calendar	任务日历
GET/PUT	/instances/{broker_id}/tasks/{task_id}	任务 CRUD
POST	/instances/{broker_id}/tasks/{task_id}/reassign	重新分配
POST	/instances/{broker_id}/tasks/{task_id}/publish	发布任务
POST	/instances/{broker_id}/tasks/{task_id}/accept	接受任务
POST	/instances/{broker_id}/tasks/{task_id}/contract/*	合约管理
POST	/instances/{broker_id}/tasks/{task_id}/start	开始任务
POST	/instances/{broker_id}/tasks/{task_id}/complete	完成任务
POST	/instances/{broker_id}/tasks/{task_id}/cancel	取消任务
POST	/instances/{broker_id}/tasks/{task_id}/deliveries	提交交付
POST	/instances/{broker_id}/deliveries/{delivery_id}/verdict	交付裁定
POST/GET	/instances/{broker_id}/tasks/{task_id}/subtasks*	子任务
POST/GET	/instances/{broker_id}/tasks/{task_id}/merge_requests*	合并请求
GET	/instances/{broker_id}/wallets	钱包列表
GET	/instances/{broker_id}/balance/{cluster_id}	余额
POST	/instances/{broker_id}/tokens/move	转账
GET	/instances/{broker_id}/ledger	账本
POST/GET	/instances/{broker_id}/medals*	勋章管理
GET	/instances/{broker_id}/archive	归档
GET	/instances/{broker_id}/inbox	收件箱
POST	/instances/{broker_id}/inbox/*	收件箱操作
POST	/instances/{broker_id}/recipe/run	运行 recipe
POST/GET	/instances/{broker_id}/tasks/{task_id}/modifications*	修改请求

---

36. xun_da.py — 寻达（社交协作）

前缀：/api/xun_da

社交协作子系统。标签/recipe/房间/线程/支付/相册/声誉/勋章/用户资料。80+ 端点。

核心端点：

方法	路径	说明
GET	/tags	标签列表
POST	/recipe/rebuild	重建 recipe
GET	/recipe/me	我的 recipe
POST/GET	/rooms/*	房间管理（创建/发现/加入/关闭/邀请）
POST/GET	/threads/*	线程管理（创建/加入/离开/消息/附件/支付/结算/相册）
GET	/reputation/me/pending	待处理声誉
GET	/badges/me	我的勋章
POST	/cron/tick	定时 tick
GET/PUT	/user_profile/me	我的资料
POST	/user_profile/me/avatar	上传头像

---

37. cg.py — CG 过场

前缀：/api

方法	路径	说明
GET	/agents/manager/cg/list	CG 状态列表
POST	/agents/manager/cg/run	渲染 CG
GET	/agents/manager/cg/reference/{agent_id}	CG 参考
DELETE	/agents/{agent_id}/skills/{skill_id}/cg	删除 CG
GET	/skill_state	当前活跃技能
POST	/agents/{agent_id}/skills/{skill_id}/cg/preview	CG 预览
GET	/agents/manager/cg/steps	CG 步骤
POST	/agents/manager/cg/step_image	步骤图片
POST	/agents/manager/cg/step_image/upload	上传步骤图片
POST	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/dh_compose	数字人合成
DELETE	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/image	删除步骤图片
GET	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/image	获取步骤图片

---

38. gift.py — 礼物

前缀：/api/gift

方法	路径	说明	请求	响应
GET	/video/{decision_id}	礼物视频	-	视频文件
POST	/swap	换候选/重搜索	{agent_id, dialogue_id, node_id, candidate_index?, keyword?}	{ok}
POST	/open	标记已打开	{agent_id, dialogue_id, node_id}	{ok}
POST	/purchase	确认购买	{agent_id, dialogue_id, node_id}	{ok}

---

39. reports.py — 报告

前缀：/api

方法	路径	说明
GET	/manager/reports	报告平铺列表
GET	/manager/reports/by-agent	按 agent 分组
GET	/manager/reports/meta	Manager 元报告
GET	/manager/reports/content	报告原始 markdown（query: path）
POST	/manager/reports/roll-up	触发 manager_meta_review
POST	/manager/report	遗留 stub

---

40. feedback.py — 反馈

前缀：/api/feedback

方法	路径	说明	请求	响应
POST	/proactive	主动消息评分	{agent_id, rating(0/1), decision_id?, fired_at?, signal_summary?, action_category?, act_score?}	{ok}
GET	/proactive/stats	反馈统计	query: agent_id?	{stats}

---

41. draft.py — 草稿

前缀：/api/draft

方法	路径	说明	请求	响应
POST	/from_text	自动分类	{text, agent_id?}	{kind, draft}
POST	/schedule_from_text	提取日程	{text, agent_id?}	{draft}
POST	/todo_from_text	提取待办	{text, agent_id?}	{draft}
POST	/cron_from_text	提取定时任务	{text, agent_id?}	{draft}

---

42. quick_inputs.py — 快捷输入

前缀：/api

方法	路径	说明	请求	响应
GET	/quick-inputs	列出快捷输入	-	[{qid, text, ...}]
POST	/quick-inputs	添加	{text}	{qid}
POST	/quick-inputs/{qid}/use	标记已用	-	{ok}
DELETE	/quick-inputs/{qid}	删除	-	{ok}

---

43. quick_ask.py — 快捷问答

前缀：/api/quick_ask

方法	路径	说明	请求	响应
POST	/dialogue	创建临时对话	{quoted_text?}	{dialogue_id}
POST	/dialogue/{dialogue_id}/archive	归档	-	{ok}

---

44. responses.py — OpenAI Responses API 代理

路径：/v1/responses

方法	路径	说明	请求	响应
POST	/v1/responses	代理 Responses API	OpenAI Responses API body	OpenAI Responses API 响应（支持流式）

---

45. learn.py — 框架文档

前缀：/api/learn

方法	路径	说明
GET	/docs	文档 key 列表
GET	/docs/{doc_key}	获取文档（纯文本 markdown）

---

46. feishu.py — 飞书

前缀：/api/feishu

方法	路径	说明	请求	响应
POST	/webhook	飞书事件投递	飞书 Event JSON	{ok}

---

47. phone_call.py — 电话通话

路径：/api/phone_call

方法	路径	说明
GET	/api/phone_call/{agent_id}/status	虚拟线缆检测 + 音频设备

---

48. broadcast.py — 广播

前缀：/api

方法	路径	说明
GET	/broadcast/stream	SSE 广播流

---

49. demo.py — 演示

前缀：/api/demo

方法	路径	说明
GET	/status	演示状态
POST	/token	获取演示 token
POST	/feedback	演示反馈

---

50. desktop_notify.py — 桌面通知

前缀：/api

方法	路径	说明	请求	响应
POST	/desktop-notify/native	发送原生桌面通知	{title, body, urgency?}	{ok}

---

51. dev.py — 开发端点

前缀：/api/dev

方法	路径	说明
GET	/framework-docs	框架文档列表
GET	/framework-docs/{name}	获取框架文档
GET	/llm_gates	LLM gate 状态
POST	/fake_gift	伪造礼物
POST	/gift_demo	礼物演示
GET	/pools	连接池状态
POST	/thread_dump	线程转储

---

52. setup.py — 初始化向导

前缀：/api/setup

方法	路径	说明
GET	/seethrough	透视渲染状态
POST	/seethrough/backend	设置透视后端
POST	/seethrough/check-login	检查透视登录
GET	/status	初始化状态
GET	/llm_presets	LLM 预设列表
POST	/chrome	安装 Chrome
GET	/chrome/install/stream	Chrome 安装 SSE
GET	/tutorial_media/{step_id}/{filename}	教程媒体资源
GET	/extensions	扩展列表
POST	/extensions/select	选择扩展
POST	/complete	完成初始化
GET	/deps/install/stream	依赖安装 SSE
GET	/deps/install/stream/{mirror}	镜像依赖安装 SSE
GET	/models/offer	模型推荐
POST	/models/download	下载模型

---

53. onboarding.py — 引导

前缀：/api/onboarding

方法	路径	说明
POST	/probe_media	探测媒体能力
GET	/media	媒体能力列表
POST	/media/{capability}	启用能力
DELETE	/media/{capability}	禁用能力
GET	/probe_env	环境探测
GET	/state	引导状态
PUT	/state	设置引导状态
GET	/tutorial_state	教程状态
PUT	/tutorial_state	设置教程状态

---

54. user_profile.py — Broker 用户资料

前缀：/api/broker_user

方法	路径	说明
GET	/profile	当前用户资料
PUT	/profile	修改资料
GET	/profile/{cluster_id}	其他用户资料
GET	/profile/search	搜索用户
POST	/profile/import_from_agent	从 agent 导入
POST	/profile/import_from_user	从 desktop user 导入
POST	/profile/ai_infer	AI 推断
POST	/assets	上传资产
GET	/assets/{asset_id}	获取资产

---

55. tool_skills.py — 工具级技能

前缀：/api

方法	路径	说明
POST	/tool_skills/import/folder	从文件夹导入
POST	/tool_skills/import/zip	从 zip 导入
POST	/tool_skills/import/text	从文本导入
GET	/tool_skills	列表
DELETE	/tool_skills/{skill_id}	删除
GET	/tool_skills/_meta/clients	客户端元数据

---

56. tools_catalog.py / tools_source.py — 工具目录

前缀：/api/tools

方法	路径	说明
GET	/catalog	工具目录
GET	/{name}	工具详情
GET	/{name}/source	工具源码

---

57. marketplace_artifacts.py — 市场制品

前缀：/api

方法	路径	说明
GET	/marketplace/artifact_updates	制品更新
POST	/marketplace/artifacts/install	安装制品

---

58. vram.py — VRAM

前缀：/api/vram

方法	路径	说明
POST	/yield	释放 VRAM

---

59. broker_dev.py — Broker 开发工具

前缀：/api/broker_dev

方法	路径	说明
GET	/guide	开发指南
GET	/keys	密钥列表
POST	/keys	生成密钥
POST	/pack	打包
POST	/sign	签名
POST	/verify	校验
POST	/publish	发布
POST	/publish_relay	发布到 relay
GET	/review_status	审核状态

---

内省工具：src/models/RAG/bridge_api_reflected.py 自动比对「手动目录 vs FastAPI 实际路由」，确保路由增删时文档保持诚实。CLI 覆盖除 WebSocket 流外的全部 REST 端点。