| name | notify_human |
| type | reference |
| description | 通知 Human 在关键节点介入确认。规定何时通知、何时不通知、通知类型和内容格式。 |
通知 Human
当需要 Human 介入时(需求确认、SOP 审阅、设计审核、异常上报),通知 Human。
重要约束:单一接口原则
只有 Manager 可以向 human.json 发消息。
- PM 不能直接联系 Human
- 所有 Human 交互必须经过 Manager 中转
mailbox_cli.py 会强制校验:--to human --from pm 会返回 errcode=1
通知类型
| type | 触发时机 | 说明 |
|---|
needs_confirm | 需求文档写好后 | 请 Human 确认需求是否准确 |
sop_draft_confirm | SOP 草稿完成后 | 请 Human 审阅 SOP 设计 |
sop_confirm | SOP 选择完成后 | 请 Human 确认选定的 SOP |
checkpoint_request | 关键交付物完成后 | 请 Human 审阅产品文档等 |
error_alert | 遇到超出权限的异常 | 上报异常,不可自行处理 |
何时通知 Human(必须通知)
- 需求文档完成后(等待 Human 确认方向)
- SOP 选择完成后(等待 Human 确认流程)
- 重要交付物完成时(如产品文档,SOP 规定了 checkpoint)
- 遇到无法自行解决的异常时
何时不需要通知 Human(禁止打扰)
- 团队内部任务分配和协调(Manager ↔ PM 邮件往来)
- 常规进度推进(不需要决策的步骤)
- Agent 自己能解决的技术问题
通知发送方式
python3 /workspace/skills/mailbox/scripts/mailbox_cli.py send \
--mailboxes-dir /mnt/shared/mailboxes \
--from manager \
--to human \
--type {type} \
--subject "{简洁的主题}" \
--content "{关键路径 + 1-2句说明}"
消息内容规范
Human 的时间宝贵。消息要简洁:
- 主题:直接说明需要确认什么(不超过 15 字)
- 内容:文件路径 + 1-2 句说明,不要长篇大论
# 好的通知 ✅
主题:需求文档(第1轮)待确认
内容:需求文档路径:/mnt/shared/needs/requirements.md
# 差的通知 ❌
主题:请您抽空查看并审阅我们精心整理的需求文档
内容:[把需求文档全文复制进来...]
发送后
不要等待 Human 回复。发完消息,完成当前能做的事,结束本轮。
Human 会在自己方便的时候通过 human_cli.py 确认。
下次运行 main.py 时,Manager 检查 human.json 的 read 字段判断是否已确认。
检查 Human 是否已确认
python3 /workspace/skills/mailbox/scripts/mailbox_cli.py check-human \
--mailboxes-dir /mnt/shared/mailboxes \
--type needs_confirm
返回 confirmed: true 表示 Human 已确认,可以继续推进。