CLI 全量命令参考

main.py 是 Familiars bridge 的命令行入口，包装了 47 个路由文件 暴露的全部 REST 端点（WebSocket-only 的数字人/电话流除外）。

40 个命令组、200+ 子命令。本文档是完整参考。

---

0. 启动前提

CLI 不启动 bridge。它驱动一个已运行的 bridge 实例。

# 先确保 bridge 运行
.venv/Scripts/python -m src.bridge.run

# 另开终端
python main.py --help

认证

每个请求携带 X-Bridge-Token 头。CLI 按以下优先级获取 token：

1. --token <value> 命令行参数
2. BRIDGE_TOKEN 环境变量
3. BRIDGE_TOKEN_PATH 环境变量指向的文件
4. --token-file <path> 参数指定的文件
5. 默认：workspace/.bridge_token

Bridge URL

1. --base-url <url> 命令行参数
2. BRIDGE_URL 环境变量
3. workspace/.bridges.json（Electron spawn 时写入，含 PID + port）
4. workspace/.bridge.port（bridge 写入的端口文件）
5. 默认：https://127.0.0.1:18711

全局选项

选项	说明
--pretty	JSON 输出美化（2 空格缩进）
--verbose / -v	将请求信息输出到 stderr
--base-url	覆盖 bridge URL
--token	覆盖 bridge token
--token-file	指定 token 文件路径
--timeout	HTTP 超时秒数（默认 60）

Body 控制

所有 POST/PUT/PATCH 子命令都支持：

选项	说明
--field KEY=VALUE	逐个设置 body 字段（可重复，值自动 JSON 解析）
--body-json JSON	完整 JSON body（覆盖 --field）
--body-file PATH	从文件读取 JSON body（覆盖 --body-json）
--query KEY=VALUE	额外 query 参数（可重复）

文件上传

支持 multipart/form-data 的子命令：

选项	说明
--file PATH	上传文件路径（必填）
--form KEY=VALUE	附加表单字段（可重复）

---

1. 命令组总览

#	组名	说明	子命令数
1	auth	本地身份注册/登录	2
2	broker	交换所作者工具 + 市场安装 + 联邦/CRL/信任管理	20
3	recipe	Recipe 作者工具：pack/sign/verify/publish + relay 审核	8
4	flow	Flow 模板作者工具：pack/sign/verify/publish + relay 审核	8
5	agents	Agent 生命周期 + 资产	16
6	chat	对话：发送/流式/翻译/模型列表	5
7	dialogues	对话列表管理	5
8	tree	对话树结构操作	7
9	todos	待办 CRUD	6
10	schedules	日程 CRUD	5
11	cron	定时任务管理	6
12	reminders	提醒：最近/SSE 流/贪睡/忽略	4
13	settings	运行时设置（全局/agent/dialogue/LLM）	8
14	user	用户资料/头像	5
15	background	后台模式 + autorun	4
16	status	运行时状态	3
17	usage	LLM token 用量	1
18	memory	记忆 writer 诊断	1
19	learn	框架文档	2
20	feedback	主动消息评分	2
21	quick-inputs	快捷输入模板	4
22	quick-ask	快捷键临时对话	2
23	draft	文本自动分类为日程/待办	3
24	reports	报告 + manager 元评审	6
25	responses	OpenAI Responses API 代理	2
26	dev	开发/演示端点	2
27	gift	礼物 v2	4
28	feishu	飞书 webhook	2
29	monitor	社交监听器	7
30	skills	技能列表/运行/SSE	10
31	skill-forge	技能锻造	6
32	skill-workshop	技能影棚（视频流水线）	14
33	cg	CG 过场动画	5
34	asr	ASR 语音识别 + 预热	7
35	digital-human	数字人 REST	4
36	phone-call	电话通话 REST	1
37	recipes-library	Recipe 市场库	3
38	recipes	Recipe CRUD/绑定/干跑/评估	16
39	agent-workshop	外部 agent 导入	6
40	agent-assets	Agent 资产 staging/替换	9
41	comm	通信中心（消息/审批/中断）	7
42	flows	Flow 实例管理	4

---

2. auth — 本地身份

# 注册新本地身份
python main.py auth register --nickname "Alice"

# 登录（当前设备指纹）
python main.py auth login

子命令	HTTP	路径	参数
register	POST	/api/auth/register	--nickname
login	POST	/api/auth/login	无

---

3. broker — 交换所

3.1 本地作者工具（不需要 bridge）

# 生成 Ed25519 签名密钥
python main.py broker keygen --name mykey
python main.py broker keygen --name mykey --overwrite   # 覆盖旧密钥

# 列出已有密钥
python main.py broker keys-list

# 打包 broker 目录
python main.py broker pack workspace/manager/brokers/starter_broker
python main.py broker pack workspace/manager/brokers/starter_broker --output custom.broker.zip

# 签名
python main.py broker sign starter_broker.broker.zip --author-key mykey

# 校验
python main.py broker verify starter_broker.broker.zip --pretty

# 一键发布到 relay
python main.py broker publish workspace/manager/brokers/starter_broker \
  --author-key mykey --relay https://api.familiars.cn \
  --author-name "My Broker" --categories "tools,chat"

# 一键发布到本地 host 目录
python main.py broker publish workspace/manager/brokers/starter_broker \
  --author-key mykey --host-dir ./host --download-url-base https://brokers.example.com/

3.2 市场安装（需要 bridge）

python main.py broker install --url https://example.com/x.broker.zip \
  --sha256 <64位hex> --pubkey <base64>

# 查看市场 index
python main.py broker marketplace-index

3.3 联邦管理

python main.py broker federation-status

3.4 Relay 信任管理（operator-only）

python main.py broker relay-trust-add --pubkey <b64> --operator-key mykey \
  --relay https://api.familiars.cn --name "Trusted Author" --notes "vouched"

python main.py broker relay-trust-list --relay https://api.familiars.cn

python main.py broker relay-trust-remove --pubkey <b64> --operator-key mykey \
  --relay https://api.familiars.cn

3.5 Relay 审核

# 查看待审核队列
python main.py broker relay-review-pending --operator-key mykey --relay https://api.familiars.cn

# 审批
python main.py broker relay-review-approve --broker-id starter_broker --version 1.0.0 \
  --operator-key mykey --relay https://api.familiars.cn --note "LGTM"

# 拒绝
python main.py broker relay-review-reject --broker-id starter_broker --version 1.0.0 \
  --note "Missing manifest" --operator-key mykey --relay https://api.familiars.cn

# 查看提交状态
python main.py broker relay-review-status --broker-id starter_broker --version 1.0.0 \
  --author-key mykey --relay https://api.familiars.cn

# 交互式逐条审核
python main.py broker relay-review --operator-key mykey --relay https://api.familiars.cn

3.6 集群 CRL + 信任管理

# CRL 吊销
python main.py broker crl-revoke --pubkey <b64> --operator-key mykey --reason "compromised"

# CRL 列表
python main.py broker crl-list

# CRL 取消吊销
python main.py broker crl-unrevoke --pubkey <b64> --operator-key mykey

# 集群信任添加/列表/移除
python main.py broker trust-add --pubkey <b64> --operator-key mykey
python main.py broker trust-list
python main.py broker trust-remove --pubkey <b64> --operator-key mykey

完整子命令表

子命令	类型	说明	关键参数
keygen	本地	生成 Ed25519 签名密钥	--name --overwrite
keys-list	本地	列出已有密钥	-
pack	本地	打包 broker 目录为 .broker.zip	source_dir --output
sign	本地	签名 .broker.zip	zip_path --author-key
verify	本地	校验签名 + manifest	zip_path
publish	本地	一键 pack+sign+发布	source_dir --author-key --relay/--host-dir+--download-url-base --author-name --categories
install	bridge	从市场 URL 安装	--url --sha256 --pubkey
marketplace-index	bridge	查看市场 index	-
federation-status	bridge	联邦状态	-
relay-trust-add	本地→relay	添加信任	--pubkey --operator-key --relay
relay-trust-list	本地→relay	列出信任	--relay
relay-trust-remove	本地→relay	移除信任	--pubkey --operator-key --relay
relay-review-pending	本地→relay	待审核列表	--operator-key --relay
relay-review-approve	本地→relay	审批	--broker-id --version --operator-key --relay
relay-review-reject	本地→relay	拒绝	--broker-id --version --note --operator-key --relay
relay-review-status	本地→relay	状态查询	--broker-id --version --author-key --relay
relay-review	本地→relay	交互式审核	--operator-key --relay
crl-revoke	本地→bridge	CRL 吊销	--pubkey --operator-key --reason
crl-list	本地→bridge	CRL 列表	-
crl-unrevoke	本地→bridge	CRL 取消吊销	--pubkey --operator-key
trust-add	本地→bridge	集群信任添加	--pubkey --operator-key
trust-list	本地→bridge	集群信任列表	-
trust-remove	本地→bridge	集群信任移除	--pubkey --operator-key

---

4. recipe — Recipe 作者工具

python main.py recipe pack workspace/agent_recipes/my_recipe
python main.py recipe sign my_recipe.recipe.zip --author-key mykey
python main.py recipe verify my_recipe.recipe.zip
python main.py recipe publish workspace/agent_recipes/my_recipe \
  --author-key mykey --relay https://api.familiars.cn

子命令	类型	说明	关键参数
pack	本地	打包为 .recipe.zip	source_dir --output
sign	本地	签名	zip_path --author-key
verify	本地	校验	zip_path
publish	本地→relay	打包+签名+上传	source_dir --author-key --relay --author-name --categories
relay-review-pending	本地→relay	待审核列表	--operator-key --relay
relay-review-approve	本地→relay	审批	--artifact-id --version --operator-key --relay
relay-review-reject	本地→relay	拒绝	--artifact-id --version --note --operator-key --relay
relay-review-status	本地→relay	状态查询	--artifact-id --version --author-key --relay
relay-review	本地→relay	交互式审核	--operator-key --relay

---

5. flow — Flow 模板作者工具

与 recipe 同构，只是打包对象是 flow template 目录。

子命令	类型	说明	关键参数
pack	本地	打包为 .flow.zip	source_dir --output
sign	本地	签名	zip_path --author-key
verify	本地	校验	zip_path
publish	本地→relay	打包+签名+上传	source_dir --author-key --relay
relay-review-pending	本地→relay	待审核列表	--operator-key --relay
relay-review-approve	本地→relay	审批	--artifact-id --version --operator-key --relay
relay-review-reject	本地→relay	拒绝	--artifact-id --version --note --operator-key --relay
relay-review-status	本地→relay	状态查询	--artifact-id --version --author-key --relay
relay-review	本地→relay	交互式审核	--operator-key --relay

---

6. agents — Agent 生命周期

python main.py agents list --pretty
python main.py agents create --agent-id 5
python main.py agents create-stream --name "小助手" --identity "温柔体贴" --personality "幽默"
python main.py agents delete 5
python main.py agents avatar 1 --output avatar.png
python main.py agents portrait 1 --output portrait.png
python main.py agents figure-rgba 1 --output figure.png
python main.py agents bust-loop 1 --output bust.webp
python main.py agents diagnose-dirs

子命令	HTTP	路径	关键参数
list	GET	/api/agents	-
create	POST	/api/agents	--agent-id
create-stream	SSE	GET /api/agents/create/stream	--name --identity --personality --appearance --voice --need-figure --need-audio --figure-staging-id --voice-staging-id --voice-transcript
delete	DELETE	/api/agents/{agent_id}	agent_id
greeting-played	POST	/api/agents/{agent_id}/greeting/played	agent_id
greeting-video	GET	/api/agents/{agent_id}/greeting	agent_id --output
diagnose-dirs	GET	/api/agents/diagnose-dirs	-
avatar	GET	/api/agents/{agent_id}/avatar	agent_id --output
portrait	GET	/api/agents/{agent_id}/portrait	agent_id --output
figure-rgba	GET	/api/agents/{agent_id}/figure_rgba	agent_id --output
bust-loop	GET	/api/agents/{agent_id}/bust_loop	agent_id --output
bust-meta	GET	/api/agents/{agent_id}/bust_meta	agent_id
theme-element	GET	/api/agents/{agent_id}/theme/{element}	agent_id element --output
theme-meta	GET	/api/agents/{agent_id}/theme/meta	agent_id
skill-cg	GET	/api/agents/{agent_id}/skills/{skill_id}/cg	agent_id skill_id --output
manager-entry-image	GET	/api/manager/entry-image/{key}	key --output

---

7. chat — 对话

# 发送消息，获取完整 JSON 回复
python main.py chat send --prompt "你好" --agent-id 1

# SSE 流式输出
python main.py chat stream --prompt "今天有什么待办？" --agent-id 1

# 翻译
python main.py chat translate --text "Hello World" --target zh

# 列出可用模型
python main.py chat models

子命令	HTTP	路径	关键参数
send	POST	/api/chat/send	--prompt --agent-id --dialogue-id --parent-id --type --call-mode
stream	SSE	GET /api/chat/stream	--prompt --agent-id --dialogue-id --parent-id --type --model --regen-q --resume-a --call-mode
generate-stream	SSE	GET /api/chat/generate/stream	--prompt --agent-id
translate	POST	/api/translate	--text --target
models	GET	/api/models	-

---

8. dialogues — 对话列表

python main.py dialogues list 1
python main.py dialogues create 1 --topic "新对话"
python main.py dialogues rename 1 3 --topic "重命名"
python main.py dialogues mark-read 1 3
python main.py dialogues delete 1 3

子命令	HTTP	路径	关键参数
list	GET	/api/dialogues/{agent_id}	agent_id
create	POST	/api/dialogues/{agent_id}	agent_id --topic
rename	PATCH	/api/dialogues/{agent_id}/{dialogue_id}	agent_id dialogue_id --topic
mark-read	POST	/api/dialogues/{agent_id}/{dialogue_id}/read	agent_id dialogue_id
delete	DELETE	/api/dialogues/{agent_id}/{dialogue_id}	agent_id dialogue_id

---

9. tree — 对话树

python main.py tree get 1 1
python main.py tree query 1 1 --text "报销流程" --k 5
python main.py tree node 1 1 42
python main.py tree path 1 1 42
python main.py tree delete 1 1 42
python main.py tree move 1 1 --node-id 42 --new-parent-id 10
python main.py tree edit 1 1 42 --content "修改后的内容"

子命令	HTTP	路径	关键参数
get	GET	/api/tree/{agent_id}/{dialogue_id}	agent_id dialogue_id
query	GET	/api/tree/{agent_id}/{dialogue_id}/query	agent_id dialogue_id --text --k
node	GET	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id
path	GET	/api/tree/{agent_id}/{dialogue_id}/path/{node_id}	agent_id dialogue_id node_id
delete	DELETE	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id
move	POST	/api/tree/{agent_id}/{dialogue_id}/move	agent_id dialogue_id --node-id --new-parent-id
edit	PATCH	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id --content

---

10. todos — 待办

python main.py todos list
python main.py todos create --title "买牛奶" --deadline 2026-07-05T18:00
python main.py todos patch 3 --title "买全脂牛奶"
python main.py todos complete 3
python main.py todos uncomplete 3
python main.py todos delete 3

子命令	HTTP	路径	关键参数
list	GET	/api/todos	--open-only
create	POST	/api/todos	--title --content --deadline --emergency-level --needs-reminder --remind-at --frequency
patch	PATCH	/api/todos/{todo_id}	todo_id --title --content --deadline --emergency-level
complete	POST	/api/todos/{todo_id}/complete	todo_id
uncomplete	POST	/api/todos/{todo_id}/uncomplete	todo_id
delete	DELETE	/api/todos/{todo_id}	todo_id

---

11. schedules — 日程

python main.py schedules list --agent-id 1
python main.py schedules create --title "会议" --scheduled-time 2026-08-30T14:00:00
python main.py schedules complete 5
python main.py schedules uncomplete 5
python main.py schedules delete 5

子命令	HTTP	路径	关键参数
list	GET	/api/schedules	--agent-id
create	POST	/api/schedules	--title --content --scheduled-time --emergency-level --frequency --kind --needs-reminder --remind-at
complete	POST	/api/schedules/{schedule_id}/complete	schedule_id
uncomplete	POST	/api/schedules/{schedule_id}/uncomplete	schedule_id
delete	DELETE	/api/schedules/{schedule_id}	schedule_id

---

12. cron — 定时任务

python main.py cron list --agent-id 1
python main.py cron create --name "morning_report" --cron "0 9 * * *" --task "生成每日报告" --agent-id 1
python main.py cron patch morning_report --cron "30 9 * * *"
python main.py cron runs morning_report --limit 10
python main.py cron run-now morning_report
python main.py cron delete morning_report

子命令	HTTP	路径	关键参数
list	GET	/api/cron-jobs	--agent-id --include-system
create	POST	/api/cron-jobs	--name --cron --task --agent-id --action --recurring
patch	PATCH	/api/cron-jobs/{name}	name --new-name --cron --task --action --recurring --agent-id
delete	DELETE	/api/cron-jobs/{name}	name
runs	GET	/api/cron-jobs/{name}/runs	name --limit
run-now	POST	/api/cron-jobs/{name}/run-now	name

---

13. reminders — 提醒

python main.py reminders recent --since-ts 1725000000 --limit 20
python main.py reminders stream --start-ts 1725000000
python main.py reminders snooze todo 3 --minutes 15
python main.py reminders dismiss schedule 5

子命令	HTTP	路径	关键参数
recent	GET	/api/reminders/recent	--since-ts --limit
stream	SSE	GET /api/reminders/stream	--start-ts
snooze	POST	/api/reminders/{kind}/{subject_id}/snooze	kind(schedule/todo) subject_id --minutes
dismiss	POST	/api/reminders/{kind}/{subject_id}/dismiss	kind subject_id

---

14. settings — 运行时设置

python main.py settings get
python main.py settings put --body-json '{"color":"red"}'
python main.py settings get-agent 1
python main.py settings put-agent 1 --body-json '{"need_initiative":false}'
python main.py settings get-llm
python main.py settings put-llm --base-url https://api.openai.com/v1 --api-key sk-xxx

子命令	HTTP	路径	关键参数
get	GET	/api/settings	-
put	PUT	/api/settings	JSON body
get-agent	GET	/api/agents/{agent_id}/settings	agent_id
put-agent	PUT	/api/agents/{agent_id}/settings	agent_id JSON body
get-dialogue	GET	/api/dialogues/{agent_id}/{dialogue_id}/settings	agent_id dialogue_id
put-dialogue	PUT	/api/dialogues/{agent_id}/{dialogue_id}/settings	agent_id dialogue_id JSON body
get-llm	GET	/api/settings/llm	-
put-llm	PUT	/api/settings/llm	--base-url --api-key --default-model --transport-mode --auto-fallback

---

15. user — 用户资料

python main.py user profile-get
python main.py user profile-put --body-json '{"nickname":"Alice"}'
python main.py user avatar-get --output my_avatar.png
python main.py user avatar-upload --file avatar.png
python main.py user intro --text "我是一名开发者"

子命令	HTTP	路径	关键参数
profile-get	GET	/api/user/profile	-
profile-put	PUT	/api/user/profile	JSON body
avatar-get	GET	/api/user/avatar	--output
avatar-upload	POST	/api/user/avatar	--file
intro	POST	/api/user/intro	--text

---

16. background — 后台模式

子命令	HTTP	路径
state	GET	/api/background/state
enable	POST	/api/background/enable
disable	POST	/api/background/disable
quit	POST	/api/background/quit

---

17. status — 运行时状态

子命令	HTTP	路径	关键参数
get	GET	/api/status	-
stream	SSE	GET /api/status/stream	-
debug	POST	/api/status/debug	--key --label --detail --level --clear

---

18. usage — LLM 用量

python main.py usage summary --model gpt-4o

子命令	HTTP	路径	关键参数
summary	GET	/api/usage/summary	--model

---

19. memory — 记忆诊断

python main.py memory writer-status --recent 30 --agent-id 1

子命令	HTTP	路径	关键参数
writer-status	GET	/api/memory/writer-status	--recent --agent-id

---

20. learn — 框架文档

子命令	HTTP	路径	关键参数
docs	GET	/api/learn/docs	-
doc	GET	/api/learn/docs/{doc_key}	doc_key

---

21. feedback — 主动消息评分

子命令	HTTP	路径	关键参数
proactive	POST	/api/feedback/proactive	--agent-id --rating(0/1) --decision-id --fired-at --signal-summary --action-category --act-score
stats	GET	/api/feedback/proactive/stats	--agent-id

---

22. quick-inputs — 快捷输入

子命令	HTTP	路径	关键参数
list	GET	/api/quick-inputs	-
add	POST	/api/quick-inputs	--text
use	POST	/api/quick-inputs/{qid}/use	qid
delete	DELETE	/api/quick-inputs/{qid}	qid

---

23. quick-ask — 快捷问答

子命令	HTTP	路径	关键参数
create	POST	/api/quick_ask/dialogue	--quoted-text
archive	POST	/api/quick_ask/dialogue/{dialogue_id}/archive	dialogue_id

---

24. draft — 文本分类草稿

子命令	HTTP	路径	关键参数
auto	POST	/api/draft/from_text	--text --agent-id
schedule	POST	/api/draft/schedule_from_text	--text --agent-id
todo	POST	/api/draft/todo_from_text	--text --agent-id

---

25. reports — 报告

子命令	HTTP	路径	关键参数
list	GET	/api/manager/reports	-
by-agent	GET	/api/manager/reports/by-agent	-
meta	GET	/api/manager/reports/meta	-
content	GET	/api/manager/reports/content	--path
roll-up	POST	/api/manager/reports/roll-up	-
run-legacy	POST	/api/manager/report	--period

---

26. responses — OpenAI Responses API 代理

子命令	HTTP	路径	关键参数
proxy	POST	/v1/responses	JSON body (--body-file/--body-json)
proxy-stream	SSE	POST /v1/responses	JSON body (streaming)

---

27. dev — 开发端点

子命令	HTTP	路径
fake-gift	POST	/api/dev/fake_gift
gift-demo	POST	/api/dev/gift_demo

---

28. gift — 礼物 v2

子命令	HTTP	路径	关键参数
video	GET	/api/gift/video/{decision_id}	decision_id --output
swap	POST	/api/gift/swap	--agent-id --dialogue-id --node-id --candidate-index --keyword
open	POST	/api/gift/open	--agent-id --dialogue-id --node-id
purchase	POST	/api/gift/purchase	--agent-id --dialogue-id --node-id

---

29. feishu — 飞书

子命令	HTTP	路径	关键参数
test-webhook	POST	/api/feishu/test_webhook	--webhook-url --title --content
webhook	POST	/api/feishu/webhook	JSON body

---

30. monitor — 消息监听

python main.py monitor list
python main.py monitor diag
python main.py monitor start wechat
python main.py monitor stop wechat
python main.py monitor settings-get
python main.py monitor file-roots
python main.py monitor file-roots-refresh --source wechat

子命令	HTTP	路径	关键参数
list	GET	/api/monitor	-
settings-get	GET	/api/monitor/settings	-
settings-put	PUT	/api/monitor/settings	JSON body
file-roots	GET	/api/monitor/file-roots	-
file-roots-refresh	POST	/api/monitor/file-roots/refresh	--source(wechat/qq) --allow-ui-probe
diag	GET	/api/monitor/_diag	-
start	POST	/api/monitor/{monitor_id}/start	monitor_id
stop	POST	/api/monitor/{monitor_id}/stop	monitor_id

---

31. skills — 技能

python main.py skills list
python main.py skills run 1 my_skill
python main.py skills stream run_abc123
python main.py skills agent-list 1
python main.py skills run-in-dialogue 1 my_skill --dialogue-id 3
python main.py skills doc my_skill
python main.py skills cancel-run run_abc123

子命令	HTTP	路径	关键参数
list	GET	/api/skills	-
cancel-run	POST	/api/skills/runs/{run_id}/cancel	run_id
unschedule	POST	/api/agents/{agent_id}/skills/{skill_id}/unschedule	agent_id skill_id
active	GET	/api/skills/runs/active	-
stream	SSE	GET /api/skills/runs/{run_id}/stream	run_id
agent-list	GET	/api/agents/{agent_id}/skills	agent_id
doc	GET	/api/skills/{skill_id}/doc	skill_id
kb	GET	/api/agents/{agent_id}/knowledge-bases	agent_id
run	POST	/api/agents/{agent_id}/skills/{skill_id}/run	agent_id skill_id
run-in-dialogue	POST	/api/agents/{agent_id}/skills/{skill_id}/run_in_dialogue	agent_id skill_id --dialogue-id --parent-id

---

32. skill-forge — 技能锻造

子命令	HTTP	路径	关键参数
propose	POST	/api/skills/forge/from-dialogue/propose	JSON body
repropose	POST	/api/skills/forge/from-dialogue/repropose	JSON body
summary	POST	/api/skills/forge/summary	JSON body
preview	POST	/api/skills/forge/preview	JSON body
revise	POST	/api/skills/forge/revise	--skill-md --user-guidance --skill-id
commit	POST	/api/skills/forge/commit	--skill-id --skill-md --scope(global/agent) --agent-id --overwrite

---

33. skill-workshop — 技能影棚

子命令	HTTP	路径	关键参数
list	GET	/api/skill_workshop/skills	-
upload	POST	/api/skill_workshop/upload	--file
asset-get	GET	/api/skill_workshop/asset	--output
rewrite	POST	/api/skill_workshop/rewrite	JSON body
run	POST	/api/skill_workshop/run	JSON body
status	GET	/api/skill_workshop/run/{run_id}/status	run_id
images	GET	/api/skill_workshop/run/{run_id}/images	run_id
regen-image	POST	/api/skill_workshop/run/{run_id}/regenerate_image	run_id JSON body
approve-images	POST	/api/skill_workshop/run/{run_id}/approve_images	run_id JSON body
clips	GET	/api/skill_workshop/run/{run_id}/clips	run_id
clip-gen	POST	/api/skill_workshop/run/{run_id}/clips/{idx}/generate	run_id idx JSON body
concat-final	POST	/api/skill_workshop/run/{run_id}/concat_final	run_id JSON body
history	GET	/api/skill_workshop/history/{skill_id}	skill_id
history-run	GET	/api/skill_workshop/history/{skill_id}/{run_id}	skill_id run_id

---

34. cg — CG 过场

子命令	HTTP	路径	关键参数
list	GET	/api/agents/manager/cg/list	-
run	POST	/api/agents/manager/cg/run	--target-agent-id --target-skill-id --prompt
delete	DELETE	/api/agents/{agent_id}/skills/{skill_id}/cg	agent_id skill_id
skill-state	GET	/api/skill_state	-
preview	POST	/api/agents/{agent_id}/skills/{skill_id}/cg/preview	agent_id skill_id --seconds

---

35. asr — 语音识别

子命令	HTTP	路径	关键参数
transcribe	POST	/api/asr/transcribe	--file --language
prewarm	POST	/api/asr/prewarm	-
call-prewarm	POST	/api/call/prewarm	--agent-id
dialog-prewarm	POST	/api/dialog/prewarm	-
focus	POST	/api/focus/{mode}	mode(dialog/call/idle) --agent-id --dialogue-id
gpu-tier	GET	/api/gpu_tier	-
model-choice	POST	/api/model_choice	--model-id --choice(download/skip/never_prompt)

---

36. digital-human — 数字人

子命令	HTTP	路径	关键参数
status	GET	/api/digital_human/{agent_id}/status	agent_id
prewarm	POST	/api/digital_human/{agent_id}/prewarm	agent_id
unload	POST	/api/digital_human/{agent_id}/unload	agent_id
regen-voice	POST	/api/digital_human/{agent_id}/regenerate_voice	agent_id

---

37. phone-call — 电话通话

子命令	HTTP	路径	关键参数
status	GET	/api/phone_call/{agent_id}/status	agent_id

---

38. recipes-library — Recipe 市场库

子命令	HTTP	路径	关键参数
list	GET	/api/recipes/library	-
install	POST	/api/recipes/library/install	--library-id --overwrite
publish	POST	/api/recipes/library/publish	--recipe-id --channel --author --version

---

39. recipes — Recipe CRUD

python main.py recipes list
python main.py recipes get my_recipe
python main.py recipes catalog
python main.py recipes create --body-file manifest.json
python main.py recipes bind my_recipe 1
python main.py recipes validate my_recipe --body-json '{"section":"manifest"}'
python main.py recipes dry-run my_recipe --prompt "你好" --mock-response "模拟回复"
python main.py recipes eval my_recipe --agent-id 1 --timeout 120
python main.py recipes export-zip my_recipe --output my_recipe.zip
python main.py recipes import-zip --file my_recipe.zip

子命令	HTTP	路径	关键参数
catalog	GET	/api/recipes/catalog	-
protocol	GET	/api/recipes/_meta/protocol	-
list	GET	/api/recipes	-
get	GET	/api/recipes/{recipe_id}	recipe_id
export-zip	GET	/api/recipes/{recipe_id}/export_zip	recipe_id --output
import-zip	POST	/api/recipes/import_zip	--file
import-folder	POST	/api/recipes/import_folder	JSON body
create	POST	/api/recipes	JSON body
update	PUT	/api/recipes/{recipe_id}	recipe_id JSON body
delete	DELETE	/api/recipes/{recipe_id}	recipe_id
bind	POST	/api/recipes/{recipe_id}/bind/{agent_id}	recipe_id agent_id
unbind	POST	/api/recipes/{recipe_id}/unbind/{agent_id}	recipe_id agent_id
validate	POST	/api/recipes/{recipe_id}/validate	recipe_id JSON body
chain-source	GET	/api/recipes/chain_source/{slot}	slot
dry-run	POST	/api/recipes/{recipe_id}/dry-run	recipe_id --prompt --mock-response
eval	POST	/api/recipes/{recipe_id}/eval	recipe_id --agent-id --suite --max-cases --timeout --parallelism --save-baseline

---

40. agent-workshop — 外部 Agent 导入

子命令	HTTP	路径	关键参数
kinds	GET	/api/agent_workshop/kinds	-
scan	GET	/api/agent_workshop/scan/{kind}	kind
import-start	POST	/api/agent_workshop/import/{kind}/start	kind --need-digital-human --display-name --model
import-cancel	POST	/api/agent_workshop/import/cancel	--session-id
import-stream	SSE	GET /api/agent_workshop/import/{kind}/stream	kind --session-id --approved-steps
custom	POST	/api/agent_workshop/custom	--display-name --repo-url --cli-command --description --need-digital-human

---

41. agent-assets — Agent 资产管理

子命令	HTTP	路径	关键参数
upload-staging	POST	/api/agents/upload_staging	--file --kind(figure/voice)
figure-job-start	POST	/api/agents/{agent_id}/asset_job/figure	agent_id --file
job-status	GET	/api/agents/{agent_id}/asset_job	agent_id
job-stream	SSE	GET /api/agents/{agent_id}/asset_job/stream	agent_id
job-retry	POST	/api/agents/{agent_id}/asset_job/retry	agent_id --stage
job-dismiss	DELETE	/api/agents/{agent_id}/asset_job	agent_id
job-upload-stage	POST	/api/agents/{agent_id}/asset_job/upload_stage	agent_id --file --stage
voice-replace	POST	/api/agents/{agent_id}/voice/replace	agent_id --file --transcript
greeting-regen	POST	/api/agents/{agent_id}/greeting/regenerate	agent_id

---

42. comm — 通信中心

python main.py comm messages --agent-id 1
python main.py comm post --body-json '{"agent_id":1,"content":"你好"}'
python main.py comm approvals-pending --agent-id 1
python main.py comm approval-respond --request-id req_abc --approved true --scope always
python main.py comm interrupt --agent-id 1 --reason "停！"

子命令	HTTP	路径	关键参数
messages	GET	/api/communication/messages	--agent-id --since --direction(agent_to_user/user_to_agent)
post	POST	/api/communication/messages	JSON body
send	POST	/api/communication/send	JSON body
approvals-pending	GET	/api/communication/approvals/pending	--agent-id
approval-request	POST	/api/communication/approvals/request	JSON body
approval-respond	POST	/api/communication/approvals/respond	--request-id --approved --reason --scope
approval-status	GET	/api/communication/approvals/{request_id}	request_id
interrupt	POST	/api/communication/interrupt	--agent-id --reason

---

43. flows — Flow 实例

python main.py flows list --status running
python main.py flows get flow_abc123 --trace-tail 50
python main.py flows trace flow_abc123 --tail 100
python main.py flows cancel flow_abc123

子命令	HTTP	路径	关键参数
list	GET	/api/flows	--status --template-id --limit
get	GET	/api/flows/{instance_id}	instance_id --trace-tail
trace	GET	/api/flows/{instance_id}/trace	instance_id --tail
cancel	POST	/api/flows/{instance_id}/cancel	instance_id

---

44. 输出格式

• JSON 响应：默认单行 JSON。加 --pretty 美化输出。
• SSE 流：每行一个 JSON 事件。[DONE] 表示流结束。
• 文件下载：--output <path> 指定保存路径，默认输出 {ok, path, bytes} JSON。
• 错误：HTTP ≥ 400 在 stderr 输出 ! HTTP <status>。

---

45. 典型用法

# 完整工作流：创建 agent → 绑定 recipe → 开始对话
python main.py agents create --agent-id 5
python main.py recipes bind medical_triage 5
python main.py chat stream --prompt "分析这个病例" --agent-id 5

# 监控管理
python main.py monitor list
python main.py monitor start wechat
python main.py monitor start qq

# 技能开发
python main.py skill-forge propose --body-file proposal.json
python main.py skill-forge preview --body-file draft.json
python main.py skill-forge commit --skill-id my_skill --skill-md "$(cat SKILL.md)" --scope global

# Broker 开发完整流程
python main.py broker keygen --name mykey
python main.py broker pack workspace/manager/brokers/my_broker
python main.py broker sign my_broker.broker.zip --author-key mykey
python main.py broker verify my_broker.broker.zip --pretty
python main.py broker publish workspace/manager/brokers/my_broker \
  --author-key mykey --relay https://api.familiars.cn