snail-mail

慢速通道收件箱，用于向操作员留下重要消息。当发生值得注意的、异常的或需要决策的事情并且操作员应该看到它时使用，但又不够紧急而无法中断。当操作员要求查看其收件箱、将消息标记为已读或存档项目时也可使用。

# Operator Inbox

A "slow channel" between you and your operator. Not every event deserves a ping. The inbox captures what matters and presents it beautifully when they're ready to look.

## Setup

On first use, the inbox file is created automatically at `{workspace}/inbox/messages.json`.

Requires: `node` (Node.js runtime).

## When to Write to the Inbox

Write an inbox entry when something is **notable enough that your operator would want to know, but not urgent enough to interrupt them.**

### Write when:
- **Needs decision** — something only a human can resolve (payment, approval, policy)
- **Abnormal** — errors, failures, unexpected patterns, security events
- **Interesting** — notable engagement, media mentions, milestones, opportunities
- **FYI** — context that might matter later but needs no action now

### Do NOT write when:
- Routine success ("cron ran fine", "heartbeat OK")
- Something you already told them in chat
- Trivial events with no lasting significance
- Duplicate of something already in the inbox

### Priority levels:
- `urgent` — needs attention within hours (prefix title with `[URGENT]`)
- `important` — should see today (prefix title with `[IMPORTANT]`)
- `normal` — whenever they check (no prefix)

### Writing good entries:
- **Title:** Short, scannable. Include the WHO or WHAT. ("@bigaccount (500K) mentioned us", not "Social media event")
- **Message:** 1-3 sentences. What happened, why it matters, what (if anything) needs doing. Include links/handles when relevant.

## CLI Usage

```bash
# Add entry
node {skill}/scripts/inbox.js add "Title" "Description of what happened"

# Add with priority
node {skill}/scripts/inbox.js add "[URGENT] Server disk 95%" "Only 2GB remaining on /dev/sda1"

# List unread
node {skill}/scripts/inbox.js list

# List all (including read)
node {skill}/scripts/inbox.js list all

# List archived
node {skill}/scripts/inbox.js list archived

# Mark one read
node {skill}/scripts/inbox.js read <id>

# Mark all read
node {skill}/scripts/inbox.js read-all

# Archive one
node {skill}/scripts/inbox.js archive <id>

# Archive all read
node {skill}/scripts/inbox.js archive-read

# Render for chat (auto-detects channel via OPENCLAW_CHANNEL)
node {skill}/scripts/inbox.js render [unread|all|archived]

# Render as HTML (force)
node {skill}/scripts/inbox.js render --html

# Render as markdown (force)
node {skill}/scripts/inbox.js render --md

# Render as plain text (force)
node {skill}/scripts/inbox.js render --text
```

## Presenting the Inbox

When the operator asks to see their inbox (or says "inbox", "messages", "check inbox"), run:

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

Choose format based on channel:
- **Telegram, webchat** → `--html`
- **Discord, Slack** → `--md`
- **SMS, plain** → `--text`

Send the output as your reply. Do not add commentary unless they ask.

## Heartbeat Integration

During heartbeats, check for unread urgent/important items:

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

If urgent items exist, surface them proactively. Otherwise stay quiet.

## Storage

Messages stored in `{workspace}/inbox/messages.json`. Single-writer (the agent), so no locking needed. Writes use atomic rename (write .tmp → rename) to prevent corruption.

Environment variables:
- `OPENCLAW_WORKSPACE` — base directory for inbox storage (defaults to `$HOME`)
- `OPENCLAW_CHANNEL` — used by `render` auto-format detection (telegram/discord/slack/webchat)

---

## 中文说明

# Operator Inbox

你与操作员之间的“慢速通道”。并非每个事件都值得提醒。收件箱捕获重要的内容，并在操作员准备好查看时以美观的方式呈现。

## 设置

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

需要：`node`（Node.js 运行时）。

## 何时写入收件箱

当某事**值得让操作员知道，但又不足以紧急到打断他们**时，写入一条收件箱条目。

### 何时写入：
- **需要决策** — 只有人类才能解决的事（付款、审批、策略）
- **异常** — 错误、失败、意外模式、安全事件
- **有趣** — 值得注意的互动、媒体提及、里程碑、机会
- **供参考** — 以后可能相关但当下无需操作的上下文

### 何时不要写入：
- 例行成功（“cron 运行正常”、“心跳 OK”）
- 你已在聊天中告知他们的事
- 无持久意义的琐碎事件
- 收件箱中已有内容的重复

### 优先级别：
- `urgent` — 需要在数小时内处理（标题以 `[URGENT]` 为前缀）
- `important` — 当天应查看（标题以 `[IMPORTANT]` 为前缀）
- `normal` — 他们查看时再看（无前缀）

### 写好条目：
- **标题：** 简短、易扫读。包含谁或什么。（“@bigaccount (500K) mentioned us”，而非“Social media event”）
- **消息：** 1-3 句。发生了什么、为何重要、（如有）需要做什么。相关时附上链接/账号。

## CLI 用法

```bash
# Add entry
node {skill}/scripts/inbox.js add "Title" "Description of what happened"

# Add with priority
node {skill}/scripts/inbox.js add "[URGENT] Server disk 95%" "Only 2GB remaining on /dev/sda1"

# List unread
node {skill}/scripts/inbox.js list

# List all (including read)
node {skill}/scripts/inbox.js list all

# List archived
node {skill}/scripts/inbox.js list archived

# Mark one read
node {skill}/scripts/inbox.js read <id>

# Mark all read
node {skill}/scripts/inbox.js read-all

# Archive one
node {skill}/scripts/inbox.js archive <id>

# Archive all read
node {skill}/scripts/inbox.js archive-read

# Render for chat (auto-detects channel via OPENCLAW_CHANNEL)
node {skill}/scripts/inbox.js render [unread|all|archived]

# Render as HTML (force)
node {skill}/scripts/inbox.js render --html

# Render as markdown (force)
node {skill}/scripts/inbox.js render --md

# Render as plain text (force)
node {skill}/scripts/inbox.js render --text
```

## 呈现收件箱

当操作员要求查看收件箱（或说“inbox”、“messages”、“check inbox”）时，运行：

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

根据渠道选择格式：
- **Telegram、webchat** → `--html`
- **Discord、Slack** → `--md`
- **SMS、纯文本** → `--text`

将输出作为你的回复发送。除非他们要求，否则不要添加评论。

## 心跳集成

在心跳期间，检查未读的紧急/重要项：

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

如存在紧急项，主动呈现。否则保持安静。

## 存储

消息存储在 `{workspace}/inbox/messages.json`。单写入者（代理），因此无需加锁。写入使用原子重命名（写入 .tmp → 重命名）以防止损坏。

环境变量：
- `OPENCLAW_WORKSPACE` — 收件箱存储的基础目录（默认为 `$HOME`）
- `OPENCLAW_CHANNEL` — 供 `render` 自动格式检测使用（telegram/discord/slack/webchat）