Operator 收件箱

你与 Operator 之间的一条“低频通道”。并非每个事件都值得立即通知。收件箱会捕获真正重要的信息，并在 Operator 准备查看时以优雅的方式呈现。

初始化设置

首次使用时，收件箱文件将自动创建于 {workspace}/inbox/messages.json。

何时向收件箱写入内容

当某件事值得关注（Operator 应该知晓），但又不紧急到需要打断其当前工作时，应写入一条收件箱条目。

建议写入的场景：

• 需人工决策 —— 仅人类可处理的事项（如付款、审批、策略确认）
• 异常情况 —— 错误、失败、非预期行为模式、安全事件
• 值得关注的动态 —— 显著用户互动、媒体提及、关键里程碑、潜在机会
• 仅作知悉（FYI） —— 当前无需操作，但后续可能具有参考价值的上下文信息

请勿写入的场景：

• 常规成功状态（例如 “cron 任务执行正常”、“心跳检测正常”）
• 已在聊天中同步过的内容
• 无实际影响或长期意义的琐碎事件
• 与收件箱中已有条目重复的内容

优先级等级：

• urgent —— 需在数小时内关注（标题前加前缀 [URGENT]）
• important —— 建议当天查阅（标题前加前缀 [IMPORTANT]）
• normal —— Operator 在任意时间检查收件箱时查阅（无需前缀）

撰写优质条目的建议：

• 标题： 简洁、易扫读；明确包含主体（WHO）或事件（WHAT）。例如："@bigaccount (500K) mentioned us"，而非 "Social media event"
• 正文： 1–3 句话。说明发生了什么、为何重要、以及是否需要采取行动（如有）。相关时请附上链接或社交账号句柄（handles）。

CLI 使用方式

# 添加条目
node {skill}/scripts/inbox.js add "Title" "Description of what happened"

# 指定优先级添加条目
node {skill}/scripts/inbox.js add "[URGENT] Server disk 95%" "Only 2GB remaining on /dev/sda1"

# 列出未读条目
node {skill}/scripts/inbox.js list

# 列出全部条目（含已读）
node {skill}/scripts/inbox.js list all

# 列出已归档条目
node {skill}/scripts/inbox.js list archived

# 将指定 ID 条目标记为已读
node {skill}/scripts/inbox.js read 

# 将所有条目标记为已读
node {skill}/scripts/inbox.js read-all

# 归档指定 ID 条目
node {skill}/scripts/inbox.js archive 

# 归档所有已读条目
node {skill}/scripts/inbox.js archive-read

# 渲染为聊天适配格式（自动识别渠道）
node {skill}/scripts/inbox.js render [unread|all|archived]

# 强制渲染为 HTML 格式
node {skill}/scripts/inbox.js render --html

# 强制渲染为 Markdown 格式
node {skill}/scripts/inbox.js render --md

# 强制渲染为纯文本格式
node {skill}/scripts/inbox.js render --text

收件箱展示方式

当 Operator 请求查看收件箱（或说出 “inbox”、“messages”、“check inbox” 等关键词）时，请运行：

node {skill}/scripts/inbox.js render [unread|all|archived] [--html|--md|--text]

请根据通信渠道选择输出格式：

• Telegram、Webchat → 使用 --html
• Discord、Slack → 使用 --md
• SMS、纯文本环境 → 使用 --text

将命令输出直接作为你的回复发送。除非 Operator 主动要求，否则请勿额外添加解释性文字。

心跳集成

在执行 heartbeat 期间，应检查是否存在未读的 urgent/important 条目：

node {skill}/scripts/inbox.js list unread --json

若存在 urgent 条目，则需主动提示；否则保持静默。

存储机制

所有消息均存储于 {workspace}/inbox/messages.json。该文件为单写者（仅 agent 写入），因此无需加锁。写入操作采用原子重命名方式（先写入 .tmp 文件，再重命名为目标文件），以防止数据损坏。