@yuanchilin/dsh-mailbox 0.0.1 → 0.0.2

package/lib/index.js

@@ -1,13 +1,14 @@
 // ============================================================================
 //  @yuanchilin/dsh-mailbox — DeepSeek Harness cordis 插件
 //
-//  注册 6 个模型面向工具 + 1 个宿主命令:
+//  注册 7 个模型面向工具 + 1 个宿主命令:
 //    mailbox_send     发送消息 (to=identity / 别名 / sessionId / all)
 //    mailbox_recv     读取新消息 (自动 seen 去重)
-//    mailbox_status   身份/目录/消息数 + 会话目录与在线状态
+//    mailbox_status   身份/目录/消息数 + 会话目录与在线状态, 输出末尾附命令一览
 //    mailbox_sessions 会话目录: 找"要对话的会话" (身份/别名/在线/未读)
 //    mailbox_alias    给本会话设置唯一别名 (便于他人定向发送)
 //    mailbox_clean    按 TTL 清理自己发过的旧消息
+//    mailbox_reset    清空整个信箱根目录 (消息+seen+注册表, 需 confirm=true, 不可恢复)
 //    /mailbox         宿主命令: /mailbox <目标|别名|all> <消息> (聊天框直发)
 //
 //  身份模型 (v1.1):
@@ -48,6 +49,7 @@ const Config = z.object({
   patchRoot: z.string().default(""),
   presenceWindowSec: z.number().default(300),
   watcher: z.boolean().default(true),
+  wakeRetrySec: z.number().default(300),
 });
 
 const text = (s) => [{ type: "text", text: s }];
@@ -72,7 +74,7 @@ function apply(ctx, config) {
 
   ctx.tools.register(defineTool({
     name: "mailbox_send",
-    description: "通过共享文件系统信箱向其他会话/agent 发送一条异步消息。to=参与者 identity / 别名 / 完整 sessionId 定向发送，或 all 广播；消息类型 request/response/notify/reply；对方不在线也不丢消息（对方之后 recv 或 CLI wait/poll 即可收到）。可用 mailbox_sessions 查看有哪些会话及其身份/别名。",
+    description: "通过共享文件系统信箱向其他会话/agent 发送一条异步消息。to=参与者 identity / 别名 / 完整 sessionId 定向发送，或 all 广播；消息类型 request/response/notify/reply；对方不在线也不丢消息（对方之后 recv 或 CLI wait/poll 即可收到）。request 型消息对方收取时会自动回执 delivered，处理完会回 done/error（本端下次 mailbox_recv 可读到该 reply）；需要对方确认后再执行的任务请用 request 型。可用 mailbox_sessions 查看有哪些会话及其身份/别名。",
     parameters: {
       to: { type: "string", required: true, description: "接收方：identity（如 dsh-mailbox-17cbcfa0）/ 别名（如 rp）/ 完整 sessionId / all 广播" },
       type: { type: "string", enum: ["request", "response", "notify", "reply"], description: "消息类型，默认 notify" },
@@ -132,7 +134,7 @@ function apply(ctx, config) {
 
   ctx.tools.register(defineTool({
     name: "mailbox_recv",
-    description: "读取信箱中发给本会话的新消息（自动记录 seen，重复调用不会重复返回）。返回消息列表：from/to/type/topic/payload/reply_to。无新消息时返回空列表。长驻等待请用 CLI：npx mailbox wait。",
+    description: "读取信箱中发给本会话的新消息（自动记录 seen，重复调用不会重复返回）。request 型消息会向发送方自动回执 delivered（收到确认），收到此类消息请先确认意图，涉及执行/计划类任务先回复确认方案并等待发送方确认后再动手，处理完成后回执 done/error（mailbox_send to=发送方 type=reply replyTo=消息id payload={status:\"done\"}）。返回消息列表：from/to/type/topic/payload/reply_to。无新消息时返回空列表。长驻等待请用 CLI：npx mailbox wait。",
     parameters: {
       format: { type: "string", enum: ["table", "json"], description: "输出格式，默认 table" },
     },
@@ -160,6 +162,7 @@ function apply(ctx, config) {
               },
             },
           },
+          ackHint: { type: "string" },
         },
       },
       render: (_args, value) => {
@@ -168,12 +171,23 @@ function apply(ctx, config) {
           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")}`);
+        const hint = value.ackHint ? `\n${value.ackHint}` : "";
+        return text(`新消息 ${value.count} 条:\n${lines.join("\n")}${hint}`);
       },
     },
     execute: async (args, exec) => withSession(cfg, exec, (eff) => {
       const messages = core.recvNew(eff, true);
-      return { count: messages.length, messages };
+      let acked = 0;
+      for (const m of messages) {
+        if (m.type === "request" && core.sendAck(eff, m, "delivered")) acked++;
+      }
+      return {
+        count: messages.length,
+        messages,
+        ackHint: acked > 0
+          ? `已自动回执 delivered 给 ${acked} 条 request 的发送方 ✓\n处理完成后请回报: mailbox_send to=<发送方> type=reply replyTo=<消息id> payload={status:"done"|"error"}`
+          : "",
+      };
     }),
     presentCall: () => ({ card: "generic", title: "mailbox recv", kind: "other" }),
   }));
@@ -213,6 +227,8 @@ function apply(ctx, config) {
         } else {
           lines.push("会话目录: (暂无注册会话, 各会话调用一次 mailbox 工具即登记)");
         }
+        lines.push("");
+        lines.push("可用命令: mailbox_send 发送 / mailbox_recv 收信 / mailbox_sessions 会话目录 / mailbox_alias 别名 / mailbox_clean 清理 / mailbox_reset ⚠️清空整个信箱(需 confirm=true, 不可恢复) / /mailbox <目标> <消息> 聊天框直发");
         return text(lines.join("\n"));
       },
     },
@@ -314,6 +330,45 @@ function apply(ctx, config) {
     }),
     presentCall: () => ({ card: "generic", title: "mailbox clean", kind: "other" }),
   }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_reset",
+    description: "清空整个信箱根目录：所有会话的消息文件 (msg_*.json)、已读标记 (.seen/ 与旧 .seen.json)、会话注册表 (_sessions/ 含别名)。⚠️ 破坏性且不可恢复（全会话共享数据），confirm 必须为 true 才执行；各会话下次调用 mailbox 工具会自动重新登记身份。用于彻底清理（如回执风暴残留）或重建干净信箱。",
+    parameters: {
+      confirm: { type: "boolean", required: true, description: "必须为 true 才会真正执行" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          confirm: { type: "boolean", required: true },
+          removed: {
+            type: "object",
+            required: true,
+            additionalProperties: true,
+            properties: {
+              messages: { type: "integer" },
+              seen: { type: "integer" },
+              registry: { type: "integer" },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        if (!value.confirm) return text("(未执行：需要 confirm=true，防止误清全会话共享数据)");
+        const r = value.removed;
+        return text(`已清空信箱: 消息 ${r.messages} 条, seen ${r.seen} 条, 注册表 ${r.registry} 条\n(各会话下次调用 mailbox 工具会自动重新登记身份/别名)`);
+      },
+    },
+    execute: async (args, exec) => withSession(cfg, exec, (eff) => {
+      if (args.confirm !== true) {
+        return { confirm: false, removed: { messages: 0, seen: 0, registry: 0 } };
+      }
+      return { confirm: true, removed: core.resetMailbox(eff) };
+    }),
+    presentCall: (args) => ({ card: "generic", title: "mailbox reset", kind: "danger", rawInput: args }),
+  }));
 }
 
 export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -11,6 +11,7 @@ export interface MailboxConfig {
   patchRoot: string;
   presenceWindowSec: number;
   watcher: boolean;
+  wakeRetrySec: number;
 }
 
 export interface MailboxMessage {
@@ -65,10 +66,21 @@ export function resolveDirs(cfg: MailboxConfig): { out: string; in: string[] };
 export function seenFileOf(cfg: MailboxConfig): string;
 export function loadSeen(cfg: MailboxConfig): string[];
 export function saveSeen(cfg: MailboxConfig, seen: string[]): void;
+export function markSeen(cfg: MailboxConfig, id: string): void;
+export function isSeen(cfg: MailboxConfig, id: string): boolean;
+
+// ---- 回执协议 (ack) ----
+export const ACK_TOPIC: "status";
+export function hasAck(cfg: MailboxConfig, requestId: string, status: string): boolean;
+export function sendAck(cfg: MailboxConfig, request: MailboxMessage, status: string, extra?: Record<string, unknown>): boolean;
+export interface MailboxReplyStatus { ts: number; status: string; id: string; from: string; payload?: Record<string, unknown>; }
+export function latestReplyStatus(cfg: MailboxConfig, requestId: string, expectFrom?: string): MailboxReplyStatus | null;
 export function sendMessage(cfg: MailboxConfig, msg: Partial<Pick<MailboxMessage, "to" | "type" | "topic" | "payload" | "reply_to">>): string;
-export function recvNew(cfg: MailboxConfig, markSeen?: boolean): MailboxMessage[];
+export function recvNew(cfg: MailboxConfig, mark?: boolean): MailboxMessage[];
 export function removeMessage(cfg: MailboxConfig, id: string, inbox?: boolean): boolean;
 export function cleanTTL(cfg: MailboxConfig, opts?: { ttlHours?: number; dryRun?: boolean }): number;
+export interface MailboxResetResult { messages: number; seen: number; registry: number; }
+export function resetMailbox(cfg: MailboxConfig): MailboxResetResult;
 export function statusOf(cfg: MailboxConfig): MailboxStatus;
 export function assertUsable(cfg: MailboxConfig): void;
 

package/lib/watcher.js

@@ -14,15 +14,42 @@
 //        任何轮询异常吞掉下轮重试, 绝不抛向启动流程。
 // ============================================================================
 
-import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, statSync, rmSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import * as core from "./core.js";
 
 /**
  * 纯检测逻辑: 扫描 root 下参与者目录 (跳过 _/. 前缀), 找出 live 身份未 seen
- * 的新消息。known (Set<绝对路径>) 就地更新; 返回 Map<identity, msg[]>。
+ * 的新消息。known (Set<绝对路径+收件人>) 就地更新; 返回 Map<identity, msg[]>。
  */
-export function scanMailboxRoot(root, known, live) {
+function wakeMarkerPath(root, identity, messageId) {
+  return join(root, identity, ".wake", `${encodeURIComponent(messageId)}.json`);
+}
+
+function recentlyWoken(root, identity, messageId, retrySec) {
+  if (!(retrySec > 0)) return false;
+  try {
+    return Date.now() - statSync(wakeMarkerPath(root, identity, messageId)).mtimeMs < retrySec * 1000;
+  } catch {
+    return false;
+  }
+}
+
+function markWoken(root, identity, messageId) {
+  const dir = join(root, identity, ".wake");
+  mkdirSync(dir, { recursive: true });
+  const file = wakeMarkerPath(root, identity, messageId);
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(temp, JSON.stringify({ id: messageId, ts: Date.now() }) + "\n", "utf-8");
+  rmSync(file, { force: true });
+  renameSync(temp, file);
+}
+
+function messagePath(root, message) {
+  return join(root, message.from, `msg_${message.id}.json`);
+}
+
+export function scanMailboxRoot(root, known, live, { wakeRetrySec = 0 } = {}) {
   const fresh = new Map();
   if (!existsSync(root)) return fresh;
   for (const entry of readdirSync(root, { withFileTypes: true })) {
@@ -37,31 +64,37 @@ export function scanMailboxRoot(root, known, live) {
     for (const f of files) {
       if (!f.startsWith("msg_") || !f.endsWith(".json")) continue;
       const filePath = join(dirPath, f);
-      if (known.has(filePath)) continue;
-      known.add(filePath);
       let m;
       try {
         m = JSON.parse(readFileSync(filePath, "utf-8"));
       } catch {
-        continue; // 损坏消息跳过
+        continue; // 半写消息留待下轮重试
       }
       for (const identity of live.keys()) {
+        const knownKey = `${filePath}\0${identity}`;
+        if (known.has(knownKey) || known.has(filePath)) continue;
         if (m.to !== identity && m.to !== "all") continue;
+        if (recentlyWoken(root, identity, m.id, wakeRetrySec)) {
+          known.add(knownKey);
+          continue;
+        }
         // 自收消息 (from=自己): recv 只扫别人目录, 永远读不到 → 不唤醒 (否则每次重启重复响铃)
         if (m.from === identity) continue;
         // 收件人已处理 (seen 含该 id) 则不重复唤醒
-        const seenPath = join(root, identity, ".seen.json");
-        if (existsSync(seenPath)) {
+        // seen 目录化: <identity>/.seen/<id>.seen (原子写); 兼容旧单文件 .seen.json
+        if (existsSync(join(root, identity, ".seen", `${m.id}.seen`))) continue;
+        const legacySeen = join(root, identity, ".seen.json");
+        if (existsSync(legacySeen)) {
           try {
-            const v = JSON.parse(readFileSync(seenPath, "utf-8"));
-            const seen = Array.isArray(v) ? v : [v];
-            if (seen.includes(m.id)) continue;
+            const v = JSON.parse(readFileSync(legacySeen, "utf-8"));
+            if ((Array.isArray(v) ? v : [v]).includes(m.id)) continue;
           } catch {
             // seen 损坏则视为未处理, 照常唤醒
           }
         }
         if (!fresh.has(identity)) fresh.set(identity, []);
         fresh.get(identity).push(m);
+        known.add(knownKey);
       }
     }
   }
@@ -93,28 +126,54 @@ export function startMailboxWatcher(ctx, cfg) {
         }
       }
       if (live.size === 0) return;
-      const fresh = scanMailboxRoot(cfg.root, known, live);
+      const fresh = scanMailboxRoot(cfg.root, known, live, { wakeRetrySec: cfg.wakeRetrySec });
       for (const [identity, messages] of fresh) {
         const agent = live.get(identity);
-        for (const m of messages) {
-          try {
-            jobs.start({
-              kind: "mailbox",
-              label: `mailbox 新消息: [${m.from} -> ${m.to}] ${m.topic || "(无主题)"}`,
-              owner: agent,
-              run: () => ({
-                cancel: () => {},
-                done: Promise.resolve({
-                  status: "completed",
-                  detail: `[${m.from} -> ${m.to}] ${m.topic || ""}`,
-                  output: `收到新消息 id=${m.id} from=${m.from} topic=${m.topic || ""}\n调用 mailbox_recv 读取处理。`,
-                }),
+        // 投递回执 (watcher 层): 系统识别到"发往在线会话的新消息"即视为已投递,
+        // 代接收方立刻回 delivered —— 不依赖对方 agent 是否来 recv/是否回应。
+        // delivered 语义 = "系统已转交到对方会话"; 对方读没读/办没办由后续
+        // done/error 或人工跟进确认。幂等: sendAck 内部 hasAck 防重复回执。
+        const recvCfg = { ...cfg, identity };
+        let started = false;
+        try {
+          const isRequest = messages.some((m) => m.type === "request");
+          const ids = messages.map((m) => m.id).join(",");
+          const policy = isRequest
+            ? `其中包含 request 型消息: 请 mailbox_recv 读取 (已回执 delivered)。涉及执行/计划类任务, 先向消息发送方回复确认方案并等待确认后再动手; 完成后回执 done/error。`
+            : `请调用 mailbox_recv 读取并处理这些消息。`;
+          jobs.start({
+            kind: "mailbox",
+            label: `mailbox 新消息: ${messages.length} 条 -> ${identity}`,
+            owner: agent,
+            run: () => ({
+              cancel: () => {},
+              done: Promise.resolve({
+                status: "completed",
+                detail: `[${identity}] ${messages.length} 条 mailbox 消息`,
+                output: `收到 ${messages.length} 条 mailbox 消息 ids=${ids}\n${policy}`,
               }),
-            });
-          } catch {
-            // 单个唤醒失败不影响其他 (如 kind 不被 jobs 实现接受)
+            }),
+          });
+          started = true;
+          for (const m of messages) {
+            const knownKey = `${messagePath(cfg.root, m)}\0${identity}`;
+            known.add(knownKey);
+            // 回执迷走防御: 回执自身不再代回 delivered, 防止无限互回。
+            if (m.type === "reply" || m.topic === "status") continue;
+            try {
+              core.sendAck(recvCfg, m, "delivered");
+            } catch {
+              // 回执失败不影响唤醒
+            }
+          }
+          for (const m of messages) {
+            try { markWoken(cfg.root, identity, m.id); } catch { /* 标记失败不影响本次唤醒 */ }
           }
+        } catch {
+          // job 创建失败时撤销精确 key, 允许下一轮重试
+          for (const m of messages) known.delete(`${messagePath(cfg.root, m)}\0${identity}`);
         }
+        if (!started) continue;
       }
     } catch {
       // 轮询异常静默, 下轮重试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuanchilin/dsh-mailbox",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "DeepSeek Harness cross-session file mailbox: send/recv/status tools over a shared filesystem mailbox (N participants, directed & broadcast routing, seen dedup, TTL cleanup, session directory & presence), a /mailbox slash command with popup completion, a plugin-native wake watcher, a zero-dependency node CLI and a packaged DSH skill.",
   "type": "module",
   "main": "lib/index.js",

package/skill/README.md

@@ -51,6 +51,22 @@ node mailbox.mjs wait --timeout 600
 | clean | `clean [-TtlHours n] [-DryRun]` | `clean [--ttl-hours n] [--dry-run]` | TTL 清理自己的已发送消息 |
 | status | `status` | `status` | 身份/目录/消息数 |
 
+## DSH 插件工具（agent 会话内直接调用）
+
+上面是 CLI；**DSH 会话内还自带 7 个同名工具**，零配置、身份自动派生——不需要跑 CLI 就能收发。`mailbox_status` 的输出末尾会附完整命令一览，忘记有哪些功能时先调它：
+
+| 工具 | 作用 |
+|---|---|
+| `mailbox_send` | 发消息：`to`=identity/别名/完整 sessionId/`all`；`type`=notify/request/response/reply；可带 `topic`/`payload`/`replyTo` |
+| `mailbox_recv` | 读新消息（自动 seen 去重；request 自动回执 delivered） |
+| `mailbox_status` | 身份/写入目录/seen/各信箱未读 + 会话目录（**输出末尾附全部可用命令**） |
+| `mailbox_sessions` | 会话目录：找"要对话的会话"（identity/别名/工作区/在线/未读） |
+| `mailbox_alias` | 给本会话设唯一别名（如 `hub`/`rp`），便于他人定向发送；全库查重 |
+| `mailbox_clean` | 按 TTL 清理自己发过的旧消息（`dryRun` 只统计不删） |
+| `mailbox_reset` | ⚠️ **清空整个信箱根目录**：消息+seen+注册表 _sessions/（含别名），不可恢复；`confirm=true` 才执行；各会话下次调用自动重新登记（彻底清理/重建干净信箱用） |
+
+另有宿主命令 `/mailbox <目标|别名|all> <消息>`（聊天框直发，输入 `/mailbox` 有补全）。CLI 侧 `reset` 用 `--confirm` 确认：`reset --confirm`。
+
 ## 配置
 
 配置文件默认 `mailbox.config.json`（与工具同目录），可用 `-Config` / `--config` 或环境变量 `MAILBOX_CONFIG` 指定。

package/skill/SKILL.md

@@ -73,6 +73,22 @@ node 版命令一致：`node "$mb\mailbox.mjs" send --to agent-b --topic hello -
 
 CLI 侧（无会话上下文）继续用显式 `--identity`；`send` 的 `--to` 同样支持别名（经注册表解析）。
 
+### DSH 插件工具一览（会话内直接调用，无需 CLI）
+
+DSH 会话内自带以下 7 个 mailbox 工具，**告诉你的用户"用 `mailbox_status` 就能看到全部命令"**。平时最常用的是前四个：
+
+| 工具 | 用途 |
+|---|---|
+| `mailbox_send` | 发消息：`to`=identity/别名/完整 sessionId/`all`；`type`=notify/request/response/reply；可带 `topic`/`payload`/`replyTo` |
+| `mailbox_recv` | 读新消息（自动 seen 去重；request 自动回执 delivered） |
+| `mailbox_status` | 本会话身份/写入目录/seen/各信箱未读 + 会话目录与在线状态（**输出末尾附全部可用命令**） |
+| `mailbox_sessions` | 会话目录：找"要对话的会话"（identity/别名/工作区/在线/未读） |
+| `mailbox_alias` | 给本会话设唯一别名（如 `hub`/`rp`），便于他人定向发送；全库查重 |
+| `mailbox_clean` | 按 TTL 清理自己发过的旧消息（`dryRun` 只统计不删） |
+| `mailbox_reset` | ⚠️ **清空整个信箱根目录**：所有消息 (msg_*.json) + seen + 注册表 _sessions/（含别名），不可恢复；`confirm=true` 才执行；各会话下次调用工具自动重新登记（用于彻底清理/重建干净信箱） |
+
+另有宿主命令 `/mailbox <目标|别名|all> <消息>`（聊天框直发，`/mailbox` 空回车列会话目录、`/mailbox recv` 收信、输入有补全选择器）。CLI 侧（无会话上下文）用 `npx mailbox help` 查看：`send/recv/wait/poll/clean/status/sessions/reset`。
+
 ## 协议
 
 - 消息文件：`msg_<id>.json`，内容 `{ id, from, to, type, topic, payload, ts, reply_to }`

package/skill/mailbox.mjs

@@ -15,7 +15,7 @@
 //  消息格式: { id, from, to, type, topic, payload, ts, reply_to }
 // ============================================================================
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, rmSync, renameSync } from "node:fs";
 import { join, dirname, basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -98,25 +98,74 @@ function resolveDirs(cfg) {
   return { out, in: inDirs };
 }
 
+const SEEN_EXT = ".seen";
+
 function seenFileOf(cfg) {
   if (cfg.seenFile) return cfg.seenFile;
   return join(resolveDirs(cfg).out, ".seen.json");
 }
 
-function loadSeen(cfg) {
-  const f = seenFileOf(cfg);
-  if (!existsSync(f)) return [];
+function seenDirOf(cfg) {
+  if (cfg.seenFile) return "";
+  return join(resolveDirs(cfg).out, ".seen");
+}
+function seenMarkName(id) { return `${id}${SEEN_EXT}`; }
+
+function migrateSeen(cfg, dir) {
+  const legacy = seenFileOf(cfg);
+  if (cfg.seenFile || !existsSync(legacy) || existsSync(dir)) return;
   try {
-    // pwsh 旧版本可能把单元素 seen 写成裸字符串 "id", 归一化为数组
-    const v = JSON.parse(readFileSync(f, "utf-8"));
-    return Array.isArray(v) ? v : [v];
-  } catch { return []; }
+    const v = JSON.parse(readFileSync(legacy, "utf-8"));
+    const arr = Array.isArray(v) ? v : [v];
+    mkdirSync(dir, { recursive: true });
+    for (const id of arr) if (id) writeFileSync(join(dir, seenMarkName(id)), "", "utf-8");
+    rmSync(legacy, { force: true });
+  } catch { /* 迁移失败则保留旧文件 */ }
+}
+
+function loadSeen(cfg) {
+  const dir = seenDirOf(cfg);
+  if (!dir) {
+    const f = seenFileOf(cfg);
+    if (!existsSync(f)) return [];
+    try {
+      const v = JSON.parse(readFileSync(f, "utf-8"));
+      return Array.isArray(v) ? v : [v];
+    } catch { return []; }
+  }
+  migrateSeen(cfg, dir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((x) => x.endsWith(SEEN_EXT)).map((x) => x.slice(0, -SEEN_EXT.length));
 }
 
 function saveSeen(cfg, seen) {
-  const f = seenFileOf(cfg);
-  mkdirSync(dirname(f), { recursive: true });
-  writeFileSync(f, JSON.stringify([...new Set(seen)]));
+  const dir = seenDirOf(cfg);
+  if (!dir) {
+    const f = seenFileOf(cfg);
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, JSON.stringify([...new Set(seen)]));
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  for (const id of new Set(seen)) if (id) markSeen(cfg, id);
+}
+
+// 目录化 seen: 每条已读消息一个 `.seen` 标记文件, 临时文件 + 原子 rename 写入 (并发安全)
+function markSeen(cfg, id) {
+  if (!id) return;
+  const dir = seenDirOf(cfg);
+  if (!dir) {
+    const cur = loadSeen(cfg);
+    if (!cur.includes(id)) saveSeen(cfg, [...cur, id]);
+    return;
+  }
+  migrateSeen(cfg, dir);
+  mkdirSync(dir, { recursive: true });
+  const mark = join(dir, seenMarkName(id));
+  if (existsSync(mark)) return;
+  const tmp = join(dir, `.tmp-${id}`);
+  writeFileSync(tmp, "", "utf-8");
+  renameSync(tmp, mark);
 }
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -165,6 +214,10 @@ function cmdSend(cfg, args) {
 function cmdRecv(cfg, args) {
   const msgs = recvNew(cfg, true);
   if (msgs.length === 0) { console.log("(无新消息)"); return; }
+  let acked = 0;
+  if (!args["no-ack"]) {
+    for (const m of msgs) if (m.type === "request" && sendAck(cfg, m, "delivered")) acked++;
+  }
   if (args.format === "json") {
     for (const m of msgs) console.log(JSON.stringify(m));
   } else {
@@ -175,9 +228,10 @@ function cmdRecv(cfg, args) {
       if (p) console.log(`   payload: ${p}`);
     }
   }
+  if (acked > 0) console.log(`[mailbox] 已自动回执 delivered 给 ${acked} 条 request ✓ (--no-ack 可关闭)`);
 }
 
-function recvNew(cfg, markSeen) {
+function recvNew(cfg, mark) {
   const seen = loadSeen(cfg);
   const dirs = resolveDirs(cfg);
   const fresh = [];
@@ -188,23 +242,61 @@ function recvNew(cfg, markSeen) {
         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);
+          if (mark) markSeen(cfg, m.id);
         }
       } catch { /* 跳过损坏消息 */ }
     }
   }
-  if (markSeen) saveSeen(cfg, seen);
   return fresh;
 }
 
+// ---- 回执协议 (ack): request 被消费自动回 delivered; 处理完回 done/error ----
+function hasAck(cfg, requestId, status) {
+  const dirs = resolveDirs(cfg);
+  if (!existsSync(dirs.out)) return false;
+  for (const f of readdirSync(dirs.out)) {
+    if (!f.startsWith("msg_") || !f.endsWith(".json")) continue;
+    try {
+      const m = JSON.parse(readFileSync(join(dirs.out, f), "utf-8"));
+      if (m.reply_to === requestId && m.payload?.status === status) return true;
+    } catch { /* 跳过损坏消息 */ }
+  }
+  return false;
+}
+
+function sendAck(cfg, request, status, extra = {}) {
+  if (!request || !request.id || !request.from) return false;
+  if (request.from === cfg.identity) return false;
+  if (!["delivered", "processing", "done", "error"].includes(status)) return false;
+  if (hasAck(cfg, request.id, status)) return false;
+  const dirs = resolveDirs(cfg);
+  mkdirSync(dirs.out, { recursive: true });
+  const id = `${ts()}${rand4()}-${rand4()}`;
+  const msg = {
+    id, from: cfg.identity, to: request.from,
+    type: "reply",
+    topic: "status",
+    payload: { status, requestId: request.id, ...extra },
+    ts: Date.now(),
+    reply_to: request.id,
+  };
+  writeFileSync(join(dirs.out, `msg_${id}.json`), JSON.stringify(msg) + "\n", "utf-8");
+  return true;
+}
+
 async function cmdWait(cfg, args) {
   const timeoutSec = cfg.timeoutSec;
   const started = Date.now();
   for (;;) {
     const msgs = recvNew(cfg, true);
     if (msgs.length > 0) {
+      let acked = 0;
+      if (!args["no-ack"]) {
+        for (const m of msgs) if (m.type === "request" && sendAck(cfg, m, "delivered")) acked++;
+      }
       console.log(`=== NEW MESSAGES: ${msgs.length} ===`);
       for (const m of msgs) console.log(JSON.stringify(m));
+      if (acked > 0) console.log(`[mailbox] 已自动回执 delivered 给 ${acked} 条 request ✓ (--no-ack 可关闭)`);
       console.log("=== WAKE-UP (exit 0) ===");
       process.exit(0);
     }