@yuanchilin/dsh-mailbox 0.0.1

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,89 @@
+# @yuanchilin/dsh-mailbox
+
+DeepSeek Harness 跨会话文件信箱插件：让多个 DSH 会话 / agent 通过共享文件系统异步通信——**发消息即投递，收消息自动唤醒**，对方离线也不丢信。
+
+## 能力一览
+
+| 面 | 内容 |
+|---|---|
+| **工具** | `mailbox_send` / `mailbox_recv` / `mailbox_status` / `mailbox_sessions` / `mailbox_alias` / `mailbox_clean` |
+| **命令** | `/mailbox <目标|别名|all> <消息>`（输入框直发）；`/mailbox` 空回车列会话目录；`/mailbox recv` 收信；输入 `/mailbox` 弹出**补全选择器** |
+| **内建 watcher** | 新消息 → 为目标会话 agent 创建完成 job → DSH 自动唤醒；随插件启动，**重启自动复活**，无需挂 CLI job |
+| **CLI** | 零依赖 node CLI（`bin/mailbox.mjs`）+ pwsh 双实现（`skill/mailbox.ps1/.psm1`），同协议互通 |
+| **Skill** | `skill/SKILL.md`，复制到 `~/.dsh/skills/mailbox/` 供所有会话加载 |
+
+## 核心机制
+
+- **文件协议**：每人一个目录 `<root>/<identity>/`，各写各的、互读对方的；消息即 `msg_<id>.json`，定向/广播路由，seen 去重，TTL 清理。
+- **身份自动派生**：默认 `<工作区名>-<会话短id>`（如 `dsh-mailbox-17cbcfa0`），同一工作区多会话互不冲突；配置显式 `identity` 优先。
+- **发现**：`mailbox_sessions` 会话目录（在线/别名/工作区/标题）；发送目标未登记时**错误即地址簿**（附完整目录）；`to` 支持 identity / 别名 / 完整 sessionId / 工作区路径 / `all`。
+- **默认信箱位置**：`$DSH_HOME/mailbox`（通常 `~/.dsh/mailbox`），无 DSH_HOME 回退 `~/.dsh/mailbox`——可移植，不写死盘符。
+
+## 安装（DSH 插件）
+
+```sh
+# 本地源码（开发, 符号链接: 已装包=源码, 改完重启即生效）
+dsh plugin --profile web add link:<本仓库>/packages/mailbox
+
+# 或 npm 发布版
+dsh plugin --profile web add @yuanchilin/dsh-mailbox
+
+# 然后重启 dsh web
+```
+
+配置（可选, 均有默认值）：profile 的 `cordis.patch.yml` 覆盖 `root`/`identity` 等：
+
+```yaml
+- id: mailbox
+  config:
+    root: D:/somewhere/shared-mailbox   # 默认 ~/.dsh/mailbox
+    # identity 留空 → 自动按会话派生; watcher: false 可关闭内建唤醒
+```
+
+## 使用
+
+```
+mailbox_send     { to: "hub" | "dsh-mailbox-17cbcfa0" | "<sessionId>" | "all",
+                   type: "notify|request|response|reply", topic: "hello",
+                   payload: {...}, replyTo: "<msg-id>" }
+mailbox_recv     {}        → 新消息列表 (自动 seen 去重)
+mailbox_status   {}        → 身份/目录/会话目录/在线
+mailbox_sessions {}        → 会话目录: 找"要对话的会话"
+mailbox_alias    { alias: "hub" }  → 给本会话设唯一别名
+mailbox_clean    { ttlHours: 24, dryRun: false }
+```
+
+CLI：
+
+```sh
+node packages/mailbox/bin/mailbox.mjs send --identity me --to hub --topic hello --payload '{"text":"hi"}'
+node packages/mailbox/bin/mailbox.mjs recv --identity me
+node packages/mailbox/bin/mailbox.mjs sessions --identity me
+```
+
+## 开发
+
+```sh
+npm install        # 仓库根 (npm workspace)
+npm test           # node:test, 30 用例
+npm run build      # 重建浏览器 bundle lib/client.js (提交入库)
+npm run watch:client  # bundle 监视重建
+```
+
+结构：
+
+```
+lib/           核心逻辑 (纯 JS): core/command/watcher/directory-parse + index(插件) + types
+src/client/    浏览器插件源码 → lib/client.js (/mailbox 补全弹窗)
+bin/           node CLI
+skill/         SKILL.md + pwsh 双实现 + 示例
+test/          node:test 用例
+```
+
+## CI
+
+`.github/workflows/ci.yml`：Node 22/24，`npm ci` → 测试 → 构建 → 校验 `lib/client.js` 与源码同步。
+
+## License
+
+MIT

package/bin/mailbox.mjs

@@ -0,0 +1,225 @@
+#!/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 sessions                    # 会话目录 (注册表: 在线/别名/工作区)
+//  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);
+  // 配置文件里 root 为空串时回退到源码默认 (DSH_HOME/mailbox 或 ~/.dsh/mailbox)
+  if (!cfg.root && cfg.layout === "root") cfg.root = core.defaultMailboxRoot();
+  return { cfg, configPath };
+}
+
+/** 心跳是 best-effort: 共享根不可写(沙箱)时静默跳过, 不影响主流程 (尤其 wait 监听循环)。 */
+function safeTouchCli(cfg) {
+  try {
+    safeTouchCli(cfg);
+  } catch {
+    // 忽略: 心跳失败不应让 send/recv/wait/poll/status 崩溃
+  }
+}
+
+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|alias|all>");
+    let payload = {};
+    if (args.payload) {
+      try { payload = JSON.parse(args.payload); } catch { throw new Error(`payload 不是合法 JSON: ${args.payload}`); }
+    }
+    core.assertUsable(cfg);
+    safeTouchCli(cfg);
+    const target = core.resolveTarget(cfg, args.to);
+    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)})`);
+    if (!core.isKnownTarget(cfg, target)) {
+      console.log(core.unknownTargetHint(cfg, target));
+    }
+  },
+
+  recv(args, cfg) {
+    core.assertUsable(cfg);
+    safeTouchCli(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);
+    safeTouchCli(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);
+    safeTouchCli(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);
+    safeTouchCli(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.name || i.dir}  (消息 ${i.msgCount}, 未读 ${i.unread ?? 0})`);
+    if (s.sessions.length > 0) {
+      console.log("会话目录:");
+      const now = Date.now();
+      for (const r of s.sessions) {
+        const on = r.online ? "●在线" : "○离线";
+        const ago = r.lastSeen ? `${Math.max(0, Math.round((now - r.lastSeen) / 1000))}s前` : "-";
+        console.log(`  ${on} ${r.identity}${r.alias ? ` (${r.alias})` : ""}  ${r.workspace || "?"}${r.title ? `  «${r.title}»` : ""}  last=${ago}`);
+      }
+    }
+  },
+
+  sessions(args, cfg) {
+    core.assertUsable(cfg);
+    const list = core.listSessions(cfg);
+    if (list.length === 0) { console.log("(暂无注册会话: 各会话调用一次 mailbox 工具即自动登记)"); return; }
+    const now = Date.now();
+    for (const r of list) {
+      const on = core.isOnline(r, cfg.presenceWindowSec) ? "●在线" : "○离线";
+      const ago = r.lastSeen ? `${Math.max(0, Math.round((now - r.lastSeen) / 1000))}s前` : "-";
+      console.log(`${on} ${r.identity}${r.alias ? ` (alias=${r.alias})` : ""}  ${r.workspace || "?"}${r.title ? `  «${r.title}»` : ""}  last=${ago}`);
+    }
+  },
+};
+
+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/sessions)`);
+  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/client.js

@@ -0,0 +1,110 @@
+window.__ModuleLoader__.load({
+	id: "@yuanchilin/dsh-mailbox",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region lib/directory-parse.js
+		const DIRECTORY_LINE = /^\s{2}([●○])(在线|离线)\s+(\S+)(?:\s+\(([^()]*)\))?\s+(.*)$/;
+		/**
+		* 从 /mailbox 目录输出文本解析会话行。
+		* @returns { id, label, detail }[] (popupSelect SelectOption 形状)
+		*/
+		function parseDirectory(text) {
+			const rows = [];
+			if (typeof text !== "string") return rows;
+			for (const raw of text.split(/\r?\n/)) {
+				const m = DIRECTORY_LINE.exec(raw);
+				if (!m) continue;
+				const identity = m[3];
+				const alias = m[4] ?? "";
+				const rest = (m[5] ?? "").trim();
+				rows.push({
+					id: identity,
+					label: alias ? `${identity} (${alias})` : identity,
+					detail: `${m[1] === "●" ? "●在线" : "○离线"}  ${rest || "?"}`
+				});
+			}
+			return rows;
+		}
+		//#endregion
+		//#region src/client/index.ts
+		/**
+		* Browser client plugin for the mailbox: decorates the HOST `/mailbox`
+		* command with a popupSelect — typing `/mailbox` pops the session directory
+		* as selectable options, picking one fills the composer with
+		* `/mailbox <identity> ` so the user types the message and Enter executes
+		* the host command.
+		*
+		* 低风险设计 (教训沉淀):
+		*   - 不用自定义 Remote 命名空间 (无挂载/注入死锁)。选项数据走成熟的
+		*     `remote.commands` 通道: 执行 `/mailbox` 拿目录文本, 解析成选项。
+		*   - 根级只注入 ui-commands 自己也在用的成熟服务
+		*     (commandUi / remote / remote.commands / sessions)。
+		*   - `conversation.input` 不是服务键, 在 onSelect 里经 ctx.conversation
+		*     懒取, 取不到静默跳过。
+		*
+		* @module @yuanchilin/dsh-mailbox/client
+		*/
+		const name = "mailbox-client";
+		const inject = [
+			"commandUi",
+			"remote",
+			"remote.commands",
+			"sessions"
+		];
+		function apply(ctx) {
+			ctx.inject([
+				"commandUi",
+				"remote",
+				"remote.commands",
+				"sessions"
+			], (scope) => {
+				const command = scope.get("commandUi");
+				const sessions = scope.get("sessions");
+				const remote = scope.get("remote");
+				scope.effect(() => command.decorate({
+					name: "mailbox",
+					available: () => true,
+					ui: {
+						kind: "popupSelect",
+						options: async (session) => {
+							if (remote.commands === void 0) return [];
+							const result = await remote.commands.execute(session.sessionId, "/mailbox");
+							if (!result.ok || result.value === void 0) throw new Error(`mailbox 目录获取失败: ${result.error?.message ?? result.error?.code ?? "unknown"}`);
+							const rows = parseDirectory(result.value.result?.text ?? "");
+							if (rows.length === 0) throw new Error("mailbox 目录为空 (暂无注册会话)");
+							return rows;
+						},
+						onSelect: async (option, session) => {
+							const actx = sessions.scope(session.sessionId);
+							if (actx === void 0) return;
+							const input = scope.get("conversation")?.input?.for(actx);
+							if (input === void 0) return;
+							input.setDraft(`/mailbox ${option.id} `);
+							setTimeout(() => {
+								const list = document.querySelectorAll("textarea[data-phase]");
+								let target = null;
+								for (const el of list) if (el.offsetParent !== null) {
+									target = el;
+									break;
+								}
+								target ??= list[0] ?? null;
+								if (target === null) return;
+								target.focus();
+								target.setSelectionRange(target.value.length, target.value.length);
+							}, 0);
+						}
+					}
+				}), "mailbox: /mailbox popup decoration");
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/command.js

@@ -0,0 +1,98 @@
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — 宿主 `/mailbox` 命令
+//
+//  在聊天输入框直接使用 (服务端命令注册表, 每个会话独立执行):
+//    /mailbox                      → 用法 + 会话目录 (发现对方)
+//    /mailbox <target|alias|all> <message>   → 定向/别名/广播发送
+//    /mailbox recv                 → 收取发给我的新消息
+//    /mailbox list                 → 会话目录
+//
+//  执行时带会话上下文 (invocation.agent.session): 身份自动派生 + 心跳登记,
+//  与 mailbox_send 等工具完全同协议。
+// ============================================================================
+
+import * as core from "./core.js";
+
+export const MAILBOX_USAGE = "Usage: /mailbox <target|alias|all> <message>   |   /mailbox [list|recv]";
+
+/** 解析命令输入 (首 token 为目标, 其余为消息)。 */
+export function parseMailboxCommand(rawInput) {
+  const input = String(rawInput ?? "").trim();
+  if (input.length === 0) return { kind: "usage" };
+  const lower = input.toLowerCase();
+  if (lower === "list" || lower === "sessions" || lower === "help" || lower === "?") return { kind: "list" };
+  if (lower === "recv") return { kind: "recv" };
+  const sp = input.search(/\s/);
+  if (sp === -1) return { kind: "no-message", to: input };
+  const to = input.slice(0, sp).trim();
+  const message = input.slice(sp + 1).trim();
+  if (!message) return { kind: "no-message", to };
+  return { kind: "send", to, message };
+}
+
+/** 渲染会话目录 (身份/别名/在线/工作区/标题/未读)。 */
+export function renderDirectory(eff) {
+  const sessions = core.listSessions(eff);
+  if (sessions.length === 0) return "(暂无注册会话: 各会话调用一次 mailbox 工具/命令即自动登记)";
+  return sessions
+    .map((s) => {
+      const on = core.isOnline(s, eff.presenceWindowSec) ? "●在线" : "○离线";
+      const alias = s.alias ? ` (${s.alias})` : "";
+      const title = s.title ? `  «${s.title}»` : "";
+      const unread = core.unreadFrom(eff, s.identity) ? `  未读${core.unreadFrom(eff, s.identity)}` : "";
+      return `  ${on} ${s.identity}${alias}  ${s.workspace || "?"}${title}${unread}`;
+    })
+    .join("\n");
+}
+
+/** 执行一次解析后的 /mailbox 命令, 返回 CommandResult ({ kind, text })。 */
+export function executeMailboxCommand(ctx, cfg, invocation) {
+  const session = invocation.agent?.session;
+  const eff = core.effectiveConfig(cfg, session);
+  core.touchRegistry(cfg, session);
+  const parsed = parseMailboxCommand(invocation.rawInput);
+  switch (parsed.kind) {
+    case "usage":
+      return { kind: "success", text: `${MAILBOX_USAGE}\n\n会话目录:\n${renderDirectory(eff)}` };
+    case "list":
+      return { kind: "success", text: `会话目录:\n${renderDirectory(eff)}` };
+    case "recv": {
+      const msgs = core.recvNew(eff, true);
+      if (msgs.length === 0) return { kind: "success", text: "(无新消息)" };
+      const lines = msgs.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 { kind: "success", text: `新消息 ${msgs.length} 条:\n${lines.join("\n")}` };
+    }
+    case "no-message":
+      return { kind: "error", text: `/mailbox ${parsed.to}: 缺少消息内容。${MAILBOX_USAGE}` };
+    case "send": {
+      const target = core.resolveTarget(eff, parsed.to);
+      const id = core.sendMessage(eff, {
+        to: parsed.to,
+        type: "notify",
+        topic: "message",
+        payload: { text: parsed.message },
+      });
+      const rec = core.listSessions(eff).find((s) => s.identity === target);
+      const status = rec
+        ? core.isOnline(rec, eff.presenceWindowSec) ? "目标在线" : "目标离线"
+        : parsed.to === "all" ? "" : core.unknownTargetHint(eff, target);
+      return {
+        kind: "success",
+        text: `已发送 ${id}  (${eff.identity} → ${target})  ${status}\n内容: ${parsed.message}`,
+      };
+    }
+  }
+}
+
+/** 向宿主命令注册表注册 /mailbox。 */
+export function registerMailboxCommand(ctx, cfg) {
+  ctx.commands.register({
+    name: "mailbox",
+    description: "跨会话发消息: /mailbox <目标|别名|all> <消息>; 单独 /mailbox 查看会话目录; /mailbox recv 收消息",
+    input: { hint: "<target|alias|all> <message>" },
+    handler: (invocation) => executeMailboxCommand(ctx, cfg, invocation),
+  });
+}