@yuanchilin/dsh-mailbox 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yuanchilin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @yuanchilin/dsh-mailbox
+
+DeepSeek Harness 跨会话文件信箱插件：通过共享文件系统在任意会话/agent 之间异步收发消息。
+
+- **DSH 工具**：`mailbox_send` / `mailbox_recv` / `mailbox_status` / `mailbox_clean`
+- **Node CLI**（零依赖）：`npx @yuanchilin/dsh-mailbox send|recv|wait|poll|clean|status|init`
+- **pwsh 模块**：随 `skill/` 打包，供需要 PowerShell 的会话使用
+- **DSH skill**：`skill/SKILL.md`，安装后可复制到 `~/.dsh/skills/mailbox/` 供所有会话加载
+
+## 安装为 DSH 插件
+
+```sh
+dsh plugin --profile web add @yuanchilin/dsh-mailbox
+# 然后重启 dsh web
+```
+
+配置信箱（在 profile 的 `cordis.patch.yml` 中覆盖）：
+
+```yaml
+- id: mailbox
+  config:
+    identity: agent-a            # 本会话身份
+    root: D:/Downloads/Agent/.mailbox   # 共享根目录 (layout=root, 每人一个子目录)
+```
+
+`layout=dirs`（旧 mcp/RP 双目录兼容）：提供 `dirs: { "<id>": "<目录>" }`。
+
+## 使用
+
+```text
+mailbox_send    { to: "agent-b" | "all", type: "notify|request|response|reply",
+                  topic: "hello", payload: {...}, replyTo: "<msg-id>" }
+mailbox_recv    {}        → 返回新消息列表 (自动 seen 去重)
+mailbox_status  {}        → 身份/目录/消息数
+mailbox_clean   { ttlHours: 24, dryRun: false }
+```
+
+长驻场景（事件唤醒 / 常驻轮询）不适合做成工具，用 CLI 挂后台 job：
+
+```bash
+npx @yuanchilin/dsh-mailbox wait --timeout 600      # 新消息即 exit 0 (DSH 唤醒)
+npx @yuanchilin/dsh-mailbox poll --interval 2       # 常驻, request 自动回 response
+```
+
+## 协议
+
+- 消息文件：`msg_<id>.json`，内容 `{ id, from, to, type, topic, payload, ts, reply_to }`
+- 路由：`to=<id>` 定向 / `to=all` 广播（写一份，各人自取）
+- seen 去重：每参与者独立 `<outDir>/.seen.json`
+- 配置优先级：CLI 参数 > 环境变量（`MAILBOX_CONFIG/ID/ROOT/INTERVAL/TIMEOUT`）> 配置文件 > 默认
+
+## 目录
+
+```
+lib/core.js        # 核心逻辑 (可独立 import)
+lib/index.js       # cordis 插件 (注册 4 个工具)
+bin/mailbox.mjs    # node CLI
+cordis.patch.yml   # bundle patch (dsh.bundle 声明)
+skill/             # DSH skill (SKILL.md + pwsh 版工具)
+test/              # node:test 测试
+```
+
+## 测试
+
+```sh
+npm test
+```
+
+MIT License

package/bin/mailbox.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — node CLI (薄封装, 复用 lib/core.js)
+//
+//  node bin/mailbox.mjs send --to agent-b --topic hello --payload '{"x":1}'
+//  node bin/mailbox.mjs recv --format json
+//  node bin/mailbox.mjs wait --timeout 600          # 新消息即 exit 0 (唤醒)
+//  node bin/mailbox.mjs poll --interval 2           # 常驻 (request→echo)
+//  node bin/mailbox.mjs clean --ttl-hours 24 --dry-run
+//  node bin/mailbox.mjs status
+//  node bin/mailbox.mjs init --id agent-a --root D:/Downloads/Agent/.mailbox
+//
+//  配置优先级: 参数 > 环境变量 (MAILBOX_CONFIG/ID/ROOT/INTERVAL/TIMEOUT) > 配置文件 > 默认
+// ============================================================================
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as core from "../lib/core.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(__dirname, "..", "mailbox.config.json");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) args[key] = argv[++i];
+      else args[key] = true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function getConfig(args) {
+  let fileCfg = {};
+  const configPath = args.config || process.env.MAILBOX_CONFIG || DEFAULT_CONFIG;
+  if (existsSync(configPath)) {
+    try {
+      fileCfg = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch (e) {
+      console.warn(`[mailbox] 读取配置失败: ${configPath} (${e.message})`);
+    }
+  }
+  const cfg = core.resolveConfig({ ...fileCfg }, process.env);
+  if (args.identity) cfg.identity = args.identity;
+  if (args.root) { cfg.root = args.root; cfg.layout = "root"; }
+  if (args.interval !== undefined) cfg.intervalSec = Number(args.interval);
+  if (args.timeout !== undefined) cfg.timeoutSec = Number(args.timeout);
+  return { cfg, configPath };
+}
+
+const commands = {
+  init(args, cfg, configPath) {
+    const out = {
+      identity: cfg.identity,
+      layout: cfg.layout,
+      root: cfg.root,
+      dirs: cfg.dirs,
+      participants: cfg.participants,
+      intervalSec: cfg.intervalSec,
+      timeoutSec: cfg.timeoutSec,
+      seenFile: cfg.seenFile,
+      patchRoot: cfg.patchRoot,
+    };
+    writeFileSync(configPath, JSON.stringify(out, null, 2) + "\n", "utf-8");
+    console.log(`已生成配置: ${configPath}`);
+  },
+
+  send(args, cfg) {
+    if (!args.to) throw new Error("send 需要 --to <id|all>");
+    let payload = {};
+    if (args.payload) {
+      try { payload = JSON.parse(args.payload); } catch { throw new Error(`payload 不是合法 JSON: ${args.payload}`); }
+    }
+    core.assertUsable(cfg);
+    const id = core.sendMessage(cfg, {
+      to: args.to,
+      type: args.type || "notify",
+      topic: args.topic || "",
+      payload,
+      replyTo: args.replyTo || "",
+    });
+    console.log(`sent ${id}  (${new Date().toTimeString().slice(0, 8)})`);
+  },
+
+  recv(args, cfg) {
+    core.assertUsable(cfg);
+    const msgs = core.recvNew(cfg, true);
+    if (msgs.length === 0) { console.log("(无新消息)"); return; }
+    if (args.format === "json") {
+      for (const m of msgs) console.log(JSON.stringify(m));
+    } else {
+      for (const m of msgs) {
+        const p = m.payload && Object.keys(m.payload).length ? ` payload=${JSON.stringify(m.payload)}` : "";
+        console.log(`[${m.from} -> ${m.to}] ${m.type} topic=${m.topic} id=${m.id}${m.reply_to ? ` reply_to=${m.reply_to}` : ""}${p}`);
+      }
+    }
+  },
+
+  async wait(args, cfg) {
+    core.assertUsable(cfg);
+    const started = Date.now();
+    for (;;) {
+      const msgs = core.recvNew(cfg, true);
+      if (msgs.length > 0) {
+        console.log(`=== NEW MESSAGES: ${msgs.length} ===`);
+        for (const m of msgs) console.log(JSON.stringify(m));
+        console.log("=== WAKE-UP (exit 0) ===");
+        process.exit(0);
+      }
+      if (cfg.timeoutSec > 0 && (Date.now() - started) / 1000 >= cfg.timeoutSec) {
+        console.log(`TIMEOUT after ${cfg.timeoutSec}s, no new messages`);
+        process.exit(0);
+      }
+      await sleep(cfg.intervalSec * 1000);
+    }
+  },
+
+  async poll(args, cfg) {
+    core.assertUsable(cfg);
+    console.log(`poll 启动 (identity=${cfg.identity} 每 ${cfg.intervalSec}s). Ctrl+C 退出`);
+    for (;;) {
+      try {
+        for (const m of core.recvNew(cfg, true)) {
+          console.log(`[收到] from=${m.from} type=${m.type} topic=${m.topic} id=${m.id}`);
+          if (m.type === "request") {
+            core.sendMessage(cfg, {
+              to: m.from,
+              type: "response",
+              topic: m.topic,
+              payload: { echo: m.payload, from: cfg.identity },
+              replyTo: m.id,
+            });
+            console.log(`  → 已回 response (reply_to=${m.id})`);
+          } else {
+            console.log(JSON.stringify(m));
+          }
+          try { core.removeMessage(cfg, m.id, true); } catch { /* 权限不足则跳过 */ }
+        }
+      } catch (e) {
+        console.warn(`轮询异常: ${e.message}`);
+      }
+      await sleep(cfg.intervalSec * 1000);
+    }
+  },
+
+  clean(args, cfg) {
+    core.assertUsable(cfg);
+    const removed = core.cleanTTL(cfg, {
+      ttlHours: args.ttlHours !== undefined ? Number(args.ttlHours) : 24,
+      dryRun: !!args.dryRun,
+    });
+    console.log(`clean: ${args.dryRun ? "dry-run" : "已删除"} ${removed} 条过期消息`);
+  },
+
+  status(args, cfg) {
+    core.assertUsable(cfg);
+    const s = core.statusOf(cfg);
+    console.log(`身份: ${s.identity}  layout=${s.layout}`);
+    console.log(`写:   ${s.outDir}  (消息 ${s.outCount})`);
+    console.log(`seen: ${s.seen} 条`);
+    for (const i of s.inboxes) console.log(`读:   ${i.dir}  (消息 ${i.msgCount})`);
+  },
+};
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0] || "status";
+const { cfg, configPath } = getConfig(args);
+
+try {
+  const fn = commands[command];
+  if (!fn) throw new Error(`未知命令: ${command} (可用: init/send/recv/wait/poll/clean/status)`);
+  await fn(args, cfg, configPath);
+} catch (e) {
+  console.error(`[mailbox] ${e.message}`);
+  process.exit(1);
+}

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# The dsh-mailbox bundle patch: registers the mailbox plugin row over the
+# profile root. Override identity/root in the profile's own cordis.patch.yml:
+#
+#   - id: mailbox
+#     config:
+#       identity: agent-a
+#       root: D:/Downloads/Agent/.mailbox
+#
+# layout=dirs (legacy dual-directory): provide dirs: { "<id>": "<path>" }.
+- insert:
+    - id: mailbox
+      name: '@yuanchilin/dsh-mailbox'

package/lib/core.js

@@ -0,0 +1,186 @@
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — core
+//
+//  跨会话文件信箱核心逻辑（与 mailbox.psm1 / mailbox.mjs 同协议）:
+//    - N 参与者对等模型: 每人一个信箱目录, 各写各的, 互读对方的
+//    - layout=root: <root>/<id>/ 每人一子目录 (participants 留空自动扫描)
+//    - layout=dirs: dirs: { "<id>": "<目录>" } 显式映射 (旧双目录兼容)
+//    - 消息: { id, from, to, type, topic, payload, ts, reply_to }, 文件 msg_<id>.json
+//    - 路由: to=<id> 定向 / to=all 广播 (写一份, 各人自取)
+//    - seen 去重: 每参与者独立 seen 文件 (默认 <outDir>/.seen.json)
+// ============================================================================
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const DEFAULTS = {
+  identity: "",
+  layout: "root",      // "root" | "dirs"
+  root: "",
+  dirs: {},
+  participants: [],
+  intervalSec: 2,
+  timeoutSec: 0,
+  seenFile: "",
+  patchRoot: "",
+};
+
+/** 合并默认值(可选: 环境变量 > 显式覆盖)。插件侧直接传 Config 对象, CLI 侧先加载配置文件。 */
+export function resolveConfig(partial = {}, env = {}) {
+  const cfg = { ...DEFAULTS, ...partial };
+  if (env.MAILBOX_ID) cfg.identity = env.MAILBOX_ID;
+  if (env.MAILBOX_ROOT) { cfg.root = env.MAILBOX_ROOT; cfg.layout = "root"; }
+  if (env.MAILBOX_INTERVAL) cfg.intervalSec = Number(env.MAILBOX_INTERVAL);
+  if (env.MAILBOX_TIMEOUT) cfg.timeoutSec = Number(env.MAILBOX_TIMEOUT);
+  if (!Array.isArray(cfg.participants)) cfg.participants = [];
+  return cfg;
+}
+
+export function resolveDirs(cfg) {
+  if (cfg.layout === "dirs") {
+    if (!cfg.dirs || !cfg.dirs[cfg.identity]) {
+      throw new Error(`layout=dirs 但配置缺少 identity '${cfg.identity}' 的目录映射`);
+    }
+    const out = cfg.dirs[cfg.identity];
+    const inDirs = [...new Set(Object.entries(cfg.dirs).filter(([k]) => k !== cfg.identity).map(([, v]) => v))];
+    return { out, in: inDirs };
+  }
+  if (!cfg.root) throw new Error("layout=root 需要配置 root");
+  const out = join(cfg.root, cfg.identity);
+  let participants = cfg.participants.filter(Boolean);
+  if (participants.length === 0 && existsSync(cfg.root)) {
+    participants = readdirSync(cfg.root, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  }
+  const inDirs = [...new Set(participants.filter((p) => p !== cfg.identity).map((p) => join(cfg.root, p)))];
+  return { out, in: inDirs };
+}
+
+export function seenFileOf(cfg) {
+  if (cfg.seenFile) return cfg.seenFile;
+  return join(resolveDirs(cfg).out, ".seen.json");
+}
+
+export function loadSeen(cfg) {
+  const f = seenFileOf(cfg);
+  if (!existsSync(f)) return [];
+  try {
+    // pwsh 旧版本可能把单元素 seen 写成裸字符串 "id", 归一化为数组
+    const v = JSON.parse(readFileSync(f, "utf-8"));
+    return Array.isArray(v) ? v : [v];
+  } catch {
+    return [];
+  }
+}
+
+export function saveSeen(cfg, seen) {
+  const f = seenFileOf(cfg);
+  mkdirSync(dirname(f), { recursive: true });
+  writeFileSync(f, JSON.stringify([...new Set(seen)]));
+}
+
+function newId() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  const ts = `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+  const rand4 = () => Math.random().toString(16).slice(2, 6).padEnd(4, "0");
+  return `${ts}-${rand4()}-${rand4()}`;
+}
+
+/** 发送: 写到自己的目录 (对方读你的目录)。返回消息 id。 */
+export function sendMessage(cfg, { to, type = "notify", topic = "", payload = {}, replyTo = "" }) {
+  if (!to) throw new Error("send 需要 to (参与者 id 或 all)");
+  const dirs = resolveDirs(cfg);
+  mkdirSync(dirs.out, { recursive: true });
+  const id = newId();
+  const msg = { id, from: cfg.identity, to, type, topic, payload, ts: Date.now(), reply_to: replyTo };
+  writeFileSync(join(dirs.out, `msg_${id}.json`), JSON.stringify(msg) + "\n", "utf-8");
+  return id;
+}
+
+/** 接收: 扫描所有对方目录, 取 to=自己 或 to=all 且未 seen 的消息。markSeen 默认 true。 */
+export function recvNew(cfg, markSeen = true) {
+  const seen = loadSeen(cfg);
+  const dirs = resolveDirs(cfg);
+  const fresh = [];
+  for (const dir of dirs.in) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((f) => f.startsWith("msg_") && f.endsWith(".json")).sort()) {
+      try {
+        const m = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        if ((m.to === cfg.identity || m.to === "all") && !seen.includes(m.id)) {
+          fresh.push(m);
+          if (markSeen) seen.push(m.id);
+        }
+      } catch {
+        // 跳过损坏消息
+      }
+    }
+  }
+  if (markSeen) saveSeen(cfg, seen);
+  return fresh;
+}
+
+/** 按 id 删除消息: inbox=true 删对方目录(已处理), 否则删自己的目录(已发送)。 */
+export function removeMessage(cfg, id, inbox = false) {
+  const dirs = resolveDirs(cfg);
+  const targets = inbox ? dirs.in : [dirs.out];
+  for (const dir of targets) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir)) {
+      if (!f.startsWith("msg_") || !f.endsWith(".json")) continue;
+      try {
+        const m = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        if (m.id === id) {
+          rmSync(join(dir, f), { force: true });
+          return true;
+        }
+      } catch {
+        // 跳过
+      }
+    }
+  }
+  return false;
+}
+
+/** TTL 清理: 删除自己 OutDir 中超过 ttlHours 的已发送消息 (收方应已读过)。返回删除数。 */
+export function cleanTTL(cfg, { ttlHours = 24, dryRun = false } = {}) {
+  const dirs = resolveDirs(cfg);
+  if (!existsSync(dirs.out)) return 0;
+  const cutoff = Date.now() - ttlHours * 3600 * 1000;
+  let removed = 0;
+  for (const f of readdirSync(dirs.out)) {
+    if (!f.startsWith("msg_") || !f.endsWith(".json")) continue;
+    const p = join(dirs.out, f);
+    try {
+      if (statSync(p).mtimeMs < cutoff) {
+        if (!dryRun) rmSync(p, { force: true });
+        removed++;
+      }
+    } catch {
+      // 跳过
+    }
+  }
+  return removed;
+}
+
+/** 状态: 身份/布局/目录/消息数/未读数。 */
+export function statusOf(cfg) {
+  const dirs = resolveDirs(cfg);
+  const seen = loadSeen(cfg);
+  const outCount = existsSync(dirs.out)
+    ? readdirSync(dirs.out).filter((f) => f.startsWith("msg_")).length
+    : 0;
+  const inboxes = dirs.in.map((dir) => ({
+    dir,
+    msgCount: existsSync(dir) ? readdirSync(dir).filter((f) => f.startsWith("msg_")).length : 0,
+  }));
+  return { identity: cfg.identity, layout: cfg.layout, outDir: dirs.out, outCount, seen: seen.length, inboxes };
+}
+
+/** 校验配置是否可用于收发 (identity/目录已解析)。 */
+export function assertUsable(cfg) {
+  if (!cfg.identity) throw new Error("mailbox 未配置 identity (在 cordis.patch.yml 的 mailbox 配置中设置)");
+  resolveDirs(cfg); // 抛错即不可用
+}

package/lib/index.js

@@ -0,0 +1,199 @@
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — DeepSeek Harness cordis 插件
+//
+//  注册 4 个模型面向工具:
+//    mailbox_send    发送消息 (定向 to=<id> / 广播 to=all)
+//    mailbox_recv    读取新消息 (自动更新 seen 去重)
+//    mailbox_status  查看身份/目录/消息数
+//    mailbox_clean   按 TTL 清理自己发过的旧消息
+//
+//  配置 (cordis.patch.yml 的 mailbox 行 config, 或 profile patch 覆盖):
+//    identity, layout(root|dirs), root, dirs, participants,
+//    intervalSec, timeoutSec, seenFile, patchRoot
+//
+//  长驻场景 (mailbox_wait 事件唤醒 / mailbox_poll 常驻轮询) 不适合做成工具,
+//  请用包内 CLI: npx mailbox wait|poll (或 pwsh 版 mailbox.ps1)。
+// ============================================================================
+
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import * as core from "./core.js";
+
+const name = "mailbox";
+const inject = ["tools"];
+
+/** schemastery 配置模式 (全部带默认值, 激活零配置; 收发前需配置 identity/root) */
+const Config = z.object({
+  identity: z.string().default(""),
+  layout: z.string().default("root"),
+  root: z.string().default(""),
+  dirs: z.dict(z.string()).default({}),
+  participants: z.array(z.string()).default([]),
+  intervalSec: z.number().default(2),
+  timeoutSec: z.number().default(0),
+  seenFile: z.string().default(""),
+  patchRoot: z.string().default(""),
+});
+
+const text = (s) => [{ type: "text", text: s }];
+
+function apply(ctx, config) {
+  const cfg = core.resolveConfig(config ?? {});
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_send",
+    description: "通过共享文件系统信箱向其他会话/agent 发送一条异步消息。to=参与者 id 定向发送或 all 广播；消息类型 request/response/notify/reply；对方不在线也不丢消息（对方之后 recv 或 wait 即可收到）。配合 mailbox_recv / mailbox_wait 使用。",
+    parameters: {
+      to: { type: "string", required: true, description: "接收方参与者 id，或 all 广播" },
+      type: { type: "string", enum: ["request", "response", "notify", "reply"], required: false, description: "消息类型，默认 notify" },
+      topic: { type: "string", required: false, description: "消息主题，用于路由/归类（如 hello、patch_xxx）" },
+      payload: { type: "object", required: false, description: "任意 JSON 负载" },
+      replyTo: { type: "string", required: false, description: "应答目标消息 id（请求-响应模式）" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          ok: { type: "boolean", required: true },
+          id: { type: "string", required: true },
+          from: { type: "string", required: true },
+          to: { type: "string", required: true },
+        },
+      },
+      render: (_args, value) => text(`已发送 ${value.id}  (${value.from} → ${value.to})`),
+    },
+    execute: async (args) => {
+      core.assertUsable(cfg);
+      const id = core.sendMessage(cfg, {
+        to: args.to,
+        type: args.type ?? "notify",
+        topic: args.topic ?? "",
+        payload: args.payload ?? {},
+        replyTo: args.replyTo ?? "",
+      });
+      return { ok: true, id, from: cfg.identity, to: args.to };
+    },
+    presentCall: (args) => ({
+      card: "generic",
+      title: `mailbox → ${args.to}`,
+      kind: "other",
+      rawInput: args,
+    }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_recv",
+    description: "读取信箱中发给本会话的新消息（自动记录 seen，重复调用不会重复返回）。返回消息列表：from/to/type/topic/payload/reply_to。无新消息时返回空列表。",
+    parameters: {
+      format: { type: "string", enum: ["table", "json"], required: false, description: "输出格式，默认 table" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          count: { type: "integer", required: true },
+          messages: {
+            type: "array",
+            required: true,
+            items: {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                id: { type: "string" },
+                from: { type: "string" },
+                to: { type: "string" },
+                type: { type: "string" },
+                topic: { type: "string" },
+                ts: { type: "integer" },
+                reply_to: { type: "string" },
+                payload: { type: "object" },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        if (value.count === 0) return text("(无新消息)");
+        const lines = value.messages.map((m) => {
+          const p = m.payload && Object.keys(m.payload).length ? ` payload=${JSON.stringify(m.payload)}` : "";
+          return `[${m.from} -> ${m.to}] ${m.type} topic=${m.topic} id=${m.id}${m.reply_to ? ` reply_to=${m.reply_to}` : ""}${p}`;
+        });
+        return text(`新消息 ${value.count} 条:\n${lines.join("\n")}`);
+      },
+    },
+    execute: async (args) => {
+      core.assertUsable(cfg);
+      const messages = core.recvNew(cfg, true);
+      return { count: messages.length, messages };
+    },
+    presentCall: () => ({ card: "generic", title: "mailbox recv", kind: "other" }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_status",
+    description: "查看信箱配置与状态：本会话身份、写入目录、已发送消息数、seen 记录数、各对方信箱的消息数。用于确认信箱是否配置好、对方是否在活跃。",
+    parameters: {},
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          identity: { type: "string" },
+          layout: { type: "string" },
+          outDir: { type: "string" },
+          outCount: { type: "integer" },
+          seen: { type: "integer" },
+          inboxes: { type: "array", items: { type: "object" } },
+        },
+      },
+      render: (_args, value) => {
+        const lines = [
+          `身份: ${value.identity}  layout=${value.layout}`,
+          `写:   ${value.outDir}  (消息 ${value.outCount})`,
+          `seen: ${value.seen} 条`,
+          ...value.inboxes.map((i) => `读:   ${i.dir}  (消息 ${i.msgCount})`),
+        ];
+        return text(lines.join("\n"));
+      },
+    },
+    execute: async () => {
+      core.assertUsable(cfg);
+      return core.statusOf(cfg);
+    },
+    presentCall: () => ({ card: "generic", title: "mailbox status", kind: "other" }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_clean",
+    description: "按 TTL 清理本会话自己发过的旧消息（对方应已读过）。dryRun 只统计不删除。",
+    parameters: {
+      ttlHours: { type: "integer", required: false, description: "保留时长（小时），默认 24" },
+      dryRun: { type: "boolean", required: false, description: "只统计不删除，默认 false" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          removed: { type: "integer", required: true },
+          dryRun: { type: "boolean", required: true },
+        },
+      },
+      render: (_args, value) =>
+        text(`clean: ${value.dryRun ? "dry-run" : "已删除"} ${value.removed} 条过期消息`),
+    },
+    execute: async (args) => {
+      core.assertUsable(cfg);
+      const removed = core.cleanTTL(cfg, {
+        ttlHours: args.ttlHours ?? 24,
+        dryRun: args.dryRun ?? false,
+      });
+      return { removed, dryRun: args.dryRun ?? false };
+    },
+    presentCall: () => ({ card: "generic", title: "mailbox clean", kind: "other" }),
+  }));
+}
+
+export { Config, apply, inject, name };