kid0317/notify_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 已确认，可以继续推进。