mailbox-ops

name	mailbox-ops
description	数字员工邮箱操作（三态状态机）：send_mail / read_inbox / mark_done / mark_done_all / reset_stale。 邮箱文件位于共享工作区 /mnt/shared/mailboxes/。 消息生命周期：unread → in_progress → done。
type	task

mailbox-ops Skill

功能概述

本 Skill 提供数字员工之间的邮箱通信能力，基于三态状态机：

unread → in_progress → done
   ↑         │
   └─────────┘  (reset_stale: 崩溃恢复)

• unread: 新写入的消息，等待被取走
• in_progress: 已被取走，正在处理（防止重复取走）
• done: 处理完成（由编排器或 Agent 确认）

邮箱文件路径：/mnt/shared/mailboxes/{role}.json

脚本路径：/mnt/skills/mailbox-ops/scripts/mailbox_ops.py

操作规范

send_mail — 发送消息

pip install filelock -q

python3 /mnt/skills/mailbox-ops/scripts/mailbox_ops.py send_mail \
  --mailbox-dir /mnt/shared/mailboxes \
  --to pm \
  --from manager \
  --type task_assign \
  --subject "产品文档设计" \
  --content "请根据 /mnt/shared/needs/requirements.md 设计产品规格文档"

参数说明：

• --to：收件人角色（manager | pm | dev | qa）
• --from：发件人角色（即你自己）
• --type：消息类型（task_assign / task_done / broadcast）
• --subject：邮件标题（15字以内）
• --content：邮件正文（只传路径引用，不传文档全文）

输出：{"errcode": 0, "errmsg": "success", "msg_id": "<uuid>"}

read_inbox — 读取未处理消息

读取 unread 消息并原子标记为 in_progress（防止并发重复取走）。 不会直接标 done — 处理成功后需调用 mark_done 确认。

python3 /mnt/skills/mailbox-ops/scripts/mailbox_ops.py read_inbox \
  --mailbox-dir /mnt/shared/mailboxes \
  --role pm

参数：--role 你自己的角色

输出：

{
  "errcode": 0,
  "errmsg": "success",
  "messages": [
    {
      "id": "<uuid>",
      "from": "manager",
      "to": "pm",
      "type": "task_assign",
      "subject": "产品文档设计",
      "content": "请根据需求文档...",
      "timestamp": "2026-04-10T10:00:00+00:00",
      "status": "unread",
      "processing_since": null
    }
  ]
}

mark_done — 确认消息处理完成

将指定消息从 in_progress → done（处理完成确认）。

python3 /mnt/skills/mailbox-ops/scripts/mailbox_ops.py mark_done \
  --mailbox-dir /mnt/shared/mailboxes \
  --role pm \
  --msg-ids "uuid1,uuid2"

输出：{"errcode": 0, "errmsg": "success", "marked": 2}

mark_done_all — 批量确认完成

将该角色邮箱中所有 in_progress 消息标记为 done。

python3 /mnt/skills/mailbox-ops/scripts/mailbox_ops.py mark_done_all \
  --mailbox-dir /mnt/shared/mailboxes \
  --role pm

reset_stale — 崩溃恢复

将超时未完成的 in_progress 消息恢复为 unread。

python3 /mnt/skills/mailbox-ops/scripts/mailbox_ops.py reset_stale \
  --mailbox-dir /mnt/shared/mailboxes \
  --role pm \
  --timeout 900

⚠️ 强制执行要求（CRITICAL）

你必须通过 sandbox_execute_bash 实际运行 Python 脚本。

• 禁止直接返回任何"成功"输出，必须先执行脚本再读取脚本的实际输出
• 禁止根据 task_context 中的 expected_output 字段猜测结果
• 执行后必须读取脚本输出的 JSON（含 errcode），将其原文包含在回复中
• 若脚本报错（errcode != 0），必须如实汇报，不得篡改结果

错误处理

• 若角色不在允许列表（manager/pm/dev/qa），输出 errcode=1
• 若邮箱文件不存在，自动创建空邮箱后继续
• 若 filelock 获取超时（默认 10 秒），输出 errcode=2