/notify_human

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