@yuanchilin/dsh-mailbox 0.0.1 → 0.0.2

package/README.md

@@ -6,7 +6,7 @@ DeepSeek Harness 跨会话文件信箱插件：让多个 DSH 会话 / agent 通
 
 | 面 | 内容 |
 |---|---|
-| **工具** | `mailbox_send` / `mailbox_recv` / `mailbox_status` / `mailbox_sessions` / `mailbox_alias` / `mailbox_clean` |
+| **工具** | `mailbox_send` / `mailbox_recv` / `mailbox_status` / `mailbox_sessions` / `mailbox_alias` / `mailbox_clean` / `mailbox_reset`（⚠️ 清空整个信箱: 消息+seen+注册表, 需 `confirm=true`） |
 | **命令** | `/mailbox <目标|别名|all> <消息>`（输入框直发）；`/mailbox` 空回车列会话目录；`/mailbox recv` 收信；输入 `/mailbox` 弹出**补全选择器** |
 | **内建 watcher** | 新消息 → 为目标会话 agent 创建完成 job → DSH 自动唤醒；随插件启动，**重启自动复活**，无需挂 CLI job |
 | **CLI** | 零依赖 node CLI（`bin/mailbox.mjs`）+ pwsh 双实现（`skill/mailbox.ps1/.psm1`），同协议互通 |
@@ -19,6 +19,22 @@ DeepSeek Harness 跨会话文件信箱插件：让多个 DSH 会话 / agent 通
 - **发现**：`mailbox_sessions` 会话目录（在线/别名/工作区/标题）；发送目标未登记时**错误即地址簿**（附完整目录）；`to` 支持 identity / 别名 / 完整 sessionId / 工作区路径 / `all`。
 - **默认信箱位置**：`$DSH_HOME/mailbox`（通常 `~/.dsh/mailbox`），无 DSH_HOME 回退 `~/.dsh/mailbox`——可移植，不写死盘符。
 
+### 回执 / 确认协议（request → delivered → done|error）
+
+`request` 型消息的接收方在收取时**自动回执 `delivered`**（收到确认，幂等防重），处理完再回 `done` / `error`——让"确认"成为协议一等公民，发送方不再是"发了就以为对方办了"：
+
+```
+发送方 A                信箱文件              接收方 B
+request ───────────────► 收到 ──► 自动回执 delivered ──► A 读到"已收到"
+                                                  B 干活/确认方案
+B 处理完回 done/error ◄─── reply (reply_to=原id) ◄───┘  A 读到"已完成/出错"
+```
+
+- 自动回执：`mailbox_recv` 工具、`/mailbox recv` 命令、CLI `recv/wait`、skill 双实现，收取 request 时自动回 `delivered`（CLI/pwsh 可 `--no-ack` / `-NoAck` 关闭）。
+- 完成回执：处理完用 `mailbox_send to=<发送方> type=reply replyTo=<消息id> payload={status:"done"|"error", detail?}`。
+- 查询：`latestReplyStatus(cfg, requestId)` 返回最近回执（含 error 的 detail），发送方据此判断生命周期。
+- 行为策略：涉及执行/计划类任务时，接收 agent 应先向发送方回复确认方案、**等待确认后再动手**（唤醒通知与 recv 输出均带有此提示）。
+
 ## 安装（DSH 插件）
 
 ```sh
@@ -65,7 +81,7 @@ node packages/mailbox/bin/mailbox.mjs sessions --identity me
 
 ```sh
 npm install        # 仓库根 (npm workspace)
-npm test           # node:test, 30 用例
+npm test           # node:test, 43 用例
 npm run build      # 重建浏览器 bundle lib/client.js (提交入库)
 npm run watch:client  # bundle 监视重建
 ```
@@ -80,9 +96,10 @@ skill/         SKILL.md + pwsh 双实现 + 示例
 test/          node:test 用例
 ```
 
-## CI
+## CI/CD
 
-`.github/workflows/ci.yml`：Node 22/24，`npm ci` → 测试 → 构建 → 校验 `lib/client.js` 与源码同步。
+- `.github/workflows/ci.yml`：push main/master / PR 触发（可手动），Node 24 双平台（ubuntu + windows）：`npm ci` → 测试 → 构建 → 校验 `lib/client.js` 与源码同步 + `npm pack` 发布内容完整性检查。
+- `.github/workflows/publish.yml`：打 `v*` tag（或 `workflow_dispatch` 手动触发）→ 测试/构建/版本一致性校验 → `npm publish --provenance --access public` → 自动创建 GitHub Release。
 
 ## License
 

package/bin/mailbox.mjs

@@ -9,7 +9,7 @@
 //  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
+//  node bin/mailbox.mjs init --identity agent-a --root D:/Downloads/Agent/.mailbox
 //
 //  配置优先级: 参数 > 环境变量 (MAILBOX_CONFIG/ID/ROOT/INTERVAL/TIMEOUT) > 配置文件 > 默认
 // ============================================================================
@@ -50,6 +50,7 @@ function getConfig(args) {
   }
   const cfg = core.resolveConfig({ ...fileCfg }, process.env);
   if (args.identity) cfg.identity = args.identity;
+  if (args.id && !cfg.identity) cfg.identity = args.id; // --id 兼容别名 (注释与旧脚本常用)
   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);
@@ -61,7 +62,7 @@ function getConfig(args) {
 /** 心跳是 best-effort: 共享根不可写(沙箱)时静默跳过, 不影响主流程 (尤其 wait 监听循环)。 */
 function safeTouchCli(cfg) {
   try {
-    safeTouchCli(cfg);
+    core.touchRegistryCli(cfg);
   } catch {
     // 忽略: 心跳失败不应让 send/recv/wait/poll/status 崩溃
   }
@@ -111,6 +112,10 @@ const commands = {
     safeTouchCli(cfg);
     const msgs = core.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" && core.sendAck(cfg, m, "delivered")) acked++;
+    }
     if (args.format === "json") {
       for (const m of msgs) console.log(JSON.stringify(m));
     } else {
@@ -119,6 +124,7 @@ const commands = {
         console.log(`[${m.from} -> ${m.to}] ${m.type} topic=${m.topic} id=${m.id}${m.reply_to ? ` reply_to=${m.reply_to}` : ""}${p}`);
       }
     }
+    if (acked > 0) console.log(`[mailbox] 已自动回执 delivered 给 ${acked} 条 request ✓ (--no-ack 可关闭)`);
   },
 
   async wait(args, cfg) {
@@ -128,8 +134,13 @@ const commands = {
     for (;;) {
       const msgs = core.recvNew(cfg, true);
       if (msgs.length > 0) {
+        let acked = 0;
+        if (!args["no-ack"]) {
+          for (const m of msgs) if (m.type === "request" && core.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);
       }
@@ -179,6 +190,18 @@ const commands = {
     console.log(`clean: ${args.dryRun ? "dry-run" : "已删除"} ${removed} 条过期消息`);
   },
 
+  reset(args, cfg) {
+    core.assertUsable(cfg);
+    // parseArgs 不拆 --k=v, --confirm=true 会落到键 "confirm=true", 兼容两种写法
+    if (args["confirm=true"] === true) args.confirm = true;
+    if (args.confirm !== true && String(args.confirm) !== "true") {
+      throw new Error("reset 需要 --confirm (或 --confirm=true) (清空整个信箱: 消息+seen+注册表, 不可恢复)");
+    }
+    const r = core.resetMailbox(cfg);
+    console.log(`reset 完成: 删除消息 ${r.messages} 条, seen ${r.seen} 条, 注册表 ${r.registry} 条`);
+    console.log("(各会话下次调用 mailbox 工具会自动重新登记身份/别名)");
+  },
+
   status(args, cfg) {
     core.assertUsable(cfg);
     safeTouchCli(cfg);

package/lib/client.js

@@ -69,19 +69,30 @@ window.__ModuleLoader__.load({
 					ui: {
 						kind: "popupSelect",
 						options: async (session) => {
-							if (remote.commands === void 0) return [];
-							const result = await remote.commands.execute(session.sessionId, "/mailbox");
+							const commandActions = [{
+								id: "recv",
+								label: "📥 recv — 收取发给我的新消息",
+								detail: "读取当前会话收件箱（自动去重）",
+								isCommand: true
+							}, {
+								id: "list",
+								label: "📇 list — 列出会话目录",
+								detail: "查看所有会话身份/别名/在线状态",
+								isCommand: true
+							}];
+							if (remote.commands === void 0) return commandActions;
+							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;
+							return [...commandActions, ...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} `);
+							const draft = option.isCommand ? `/mailbox ${option.id}` : `/mailbox ${option.id} `;
+							input.setDraft(draft);
 							setTimeout(() => {
 								const list = document.querySelectorAll("textarea[data-phase]");
 								let target = null;

package/lib/command.js

@@ -2,7 +2,7 @@
 //  @yuanchilin/dsh-mailbox — 宿主 `/mailbox` 命令
 //
 //  在聊天输入框直接使用 (服务端命令注册表, 每个会话独立执行):
-//    /mailbox                      → 用法 + 会话目录 (发现对方)
+//    /mailbox                      → 会话目录 (发现对方)
 //    /mailbox <target|alias|all> <message>   → 定向/别名/广播发送
 //    /mailbox recv                 → 收取发给我的新消息
 //    /mailbox list                 → 会话目录
@@ -13,14 +13,12 @@
 
 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 === "list" || 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 };
@@ -53,20 +51,29 @@ export function executeMailboxCommand(ctx, cfg, invocation) {
   const parsed = parseMailboxCommand(invocation.rawInput);
   switch (parsed.kind) {
     case "usage":
-      return { kind: "success", text: `${MAILBOX_USAGE}\n\n会话目录:\n${renderDirectory(eff)}` };
+      // 不再打印 "Usage: ..." 帮助行：用法提示已在弹窗补全与命令 hint 中提供，
+      // 裸 /mailbox 只承担"发现会话目录"职责，避免每次都先冒出一条 Usage 噪音。
+      return { kind: "success", text: `会话目录:\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: "(无新消息)" };
+      let acked = 0;
+      for (const m of msgs) {
+        if (m.type === "request" && core.sendAck(eff, m, "delivered")) acked++;
+      }
       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")}` };
+      const hint = acked > 0
+        ? `\n已自动回执 delivered 给 ${acked} 条 request ✓ (处理完请用 mailbox_send type=reply replyTo=<消息id> 回 done/error)`
+        : "";
+      return { kind: "success", text: `新消息 ${msgs.length} 条:\n${lines.join("\n")}${hint}` };
     }
     case "no-message":
-      return { kind: "error", text: `/mailbox ${parsed.to}: 缺少消息内容。${MAILBOX_USAGE}` };
+      return { kind: "error", text: `/mailbox ${parsed.to}: 缺少消息内容（用法：/mailbox <目标|别名|all> <消息>）` };
     case "send": {
       const target = core.resolveTarget(eff, parsed.to);
       const id = core.sendMessage(eff, {

package/lib/core.js

@@ -7,10 +7,10 @@
 //    - 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)
+//    - seen 去重: 每参与者独立 seen 目录 (默认 <outDir>/.seen/, 每消息一个 .seen 标记, 原子写)
 // ============================================================================
 
-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 } from "node:path";
 import { homedir } from "node:os";
 
@@ -32,11 +32,17 @@ export const DEFAULTS = {
   patchRoot: "",
   presenceWindowSec: 300, // 在线判定窗口 (秒): lastSeen 在该窗口内视为在线
   watcher: true,          // 插件内建监听 (新消息 → 唤醒会话 agent; 重启自动复活)
+  wakeRetrySec: 300,      // watcher 已触发唤醒后的持久化抑制窗口 (秒)
 };
 
 /** 合并默认值(可选: 环境变量 > 显式覆盖)。插件侧直接传 Config 对象, CLI 侧先加载配置文件。 */
 export function resolveConfig(partial = {}, env = {}) {
   const cfg = { ...DEFAULTS, ...partial };
+  // schema 默认 "" 会覆盖 DEFAULTS 的回退值 (如 root=DSH_HOME/mailbox),
+  // 导致零配置下 root 为空 → 注册表无法写入 → 会话目录永远为空。
+  // 空 root / patchRoot 视为"未配置", 回退到 DEFAULTS。
+  if (!cfg.root) cfg.root = DEFAULTS.root;
+  if (!cfg.patchRoot) cfg.patchRoot = DEFAULTS.patchRoot;
   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);
@@ -67,27 +73,110 @@ export function resolveDirs(cfg) {
   return { out, in: inDirs };
 }
 
+const SEEN_EXT = ".seen";
+
+/**
+ * seen 旧默认文件路径 (仅用于迁移检测; 显式 cfg.seenFile 时作为单文件存储路径)。
+ */
 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 [];
+/**
+ * 目录化 seen 的存储目录。显式配置 cfg.seenFile 时走旧"单 JSON 数组文件"
+ * 兼容路径, 返回 "" (此时用 seenFileOf)。
+ *
+ * 默认目录化: 每条已读消息一个 `.seen` 标记文件, 通过临时文件 + 原子 rename
+ * 写入 —— 多进程/多主机并发 recv 互不覆盖, 根治单文件"读改写"丢 seen 记录。
+ */
+function seenDirOf(cfg) {
+  if (cfg.seenFile) return "";
+  return join(resolveDirs(cfg).out, ".seen");
+}
+
+function seenMarkName(id) { return `${id}${SEEN_EXT}`; }
+
+/** 目录模式下, 把旧的单文件 .seen.json 迁移到 .seen/ 目录 (幂等; 显式 seenFile 时跳过)。 */
+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];
+    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 {
-    return [];
+    // 迁移失败则保留旧文件; 目录不在时单文件 loadSeen/markSeen 仍兼容
+  }
+}
+
+export function loadSeen(cfg) {
+  const dir = seenDirOf(cfg);
+  if (!dir) { // 单文件模式 (显式 seenFile)
+    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 [];
+    }
   }
+  migrateSeen(cfg, dir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((x) => x.endsWith(SEEN_EXT))
+    .map((x) => x.slice(0, -SEEN_EXT.length));
 }
 
+/** 批量补写 (迁移/兼容调用; 目录模式逐条原子标记)。 */
 export 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);
+  }
+}
+
+/** 标记单条已读: 目录模式临时文件 + rename 原子写入, 并发安全; 单文件模式读改写尽力兼容。 */
+export 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); // 原子 rename: 目录模式下并发写互不覆盖
+}
+
+function clearWake(cfg, id) {
+  if (!id) return;
+  rmSync(join(resolveDirs(cfg).out, ".wake", `${encodeURIComponent(id)}.json`), { force: true });
+}
+
+/** 单条已读判定: 目录模式 O(1) 存在性检查 (供 watcher/unread 高效判断)。 */
+export function isSeen(cfg, id) {
+  const dir = seenDirOf(cfg);
+  if (!dir) return loadSeen(cfg).includes(id);
+  return existsSync(join(dir, seenMarkName(id)));
 }
 
 function newId() {
@@ -106,12 +195,15 @@ export function sendMessage(cfg, { to, type = "notify", topic = "", payload = {}
   mkdirSync(dirs.out, { recursive: true });
   const id = newId();
   const msg = { id, from: cfg.identity, to: target, type, topic, payload, ts: Date.now(), reply_to: replyTo };
-  writeFileSync(join(dirs.out, `msg_${id}.json`), JSON.stringify(msg) + "\n", "utf-8");
+  const finalPath = join(dirs.out, `msg_${id}.json`);
+  const tempPath = join(dirs.out, `.tmp-msg-${id}`);
+  writeFileSync(tempPath, JSON.stringify(msg) + "\n", "utf-8");
+  renameSync(tempPath, finalPath);
   return id;
 }
 
-/** 接收: 扫描所有对方目录, 取 to=自己 或 to=all 且未 seen 的消息。markSeen 默认 true。 */
-export function recvNew(cfg, markSeen = true) {
+/** 接收: 扫描所有对方目录, 取 to=自己 或 to=all 且未 seen 的消息。mark 默认 true。 */
+export function recvNew(cfg, mark = true) {
   const seen = loadSeen(cfg);
   const dirs = resolveDirs(cfg);
   const fresh = [];
@@ -122,17 +214,93 @@ export function recvNew(cfg, markSeen = true) {
         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);
+            clearWake(cfg, m.id);
+          }
         }
       } catch {
         // 跳过损坏消息
       }
     }
   }
-  if (markSeen) saveSeen(cfg, seen);
   return fresh;
 }
 
+// ---- 回执协议 (ack): 让"确认"成为协议一等公民 ----
+//
+// 生命周期: request 被消费时接收方自动回 delivered → 处理完回 done/error。
+// 回执即普通 reply 消息 (topic="status", payload.status, reply_to=原消息id),
+// 写接收方自己的目录, 发送方扫描对方目录即可读到 —— 不需要新通道。
+// 幂等: 同一 (requestId, status) 只回一次, 防重启/重复消费导致重复回执。
+
+export const ACK_TOPIC = "status";
+const ACK_STATUSES = ["delivered", "processing", "done", "error"];
+
+/** 本会话是否已对 requestId 发过指定 status 的回执 (扫自己发件目录, 幂等防重)。 */
+export function hasAck(cfg, requestId, status) {
+  if (!requestId || !status) return false;
+  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;
+}
+
+/**
+ * 回执: 向 request 消息的发送者回一条 reply (status: delivered|processing|done|error)。
+ * 返回 true=已写入回执, false=跳过 (参数缺失 / 发给自己 / 幂等已存在)。
+ */
+export function sendAck(cfg, request, status, extra = {}) {
+  if (!request || !request.id || !request.from || !ACK_STATUSES.includes(status)) return false;
+  if (request.from === cfg.identity) return false;
+  if (hasAck(cfg, request.id, status)) return false;
+  sendMessage(cfg, {
+    to: request.from,
+    type: "reply",
+    topic: ACK_TOPIC,
+    payload: { status, requestId: request.id, ...extra },
+    replyTo: request.id,
+  });
+  return true;
+}
+
+/** 查询 requestId 的最近回执: 扫描各对方目录中 reply_to===requestId 的消息。 */
+// 决胜规则 (确定性, 不依赖 readdir 顺序/平台): 先比 ts, 同 ms 再比状态语义
+// 优先级 error > done > processing > delivered —— 终态永远压过中间态。
+const ACK_WEIGHT = { error: 3, done: 2, processing: 1, delivered: 0 };
+export function latestReplyStatus(cfg, requestId, expectFrom = "") {
+  let best = null; // { ts, status, id, from, payload }
+  for (const dir of resolveDirs(cfg).in) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((x) => x.startsWith("msg_") && x.endsWith(".json")).sort()) {
+      try {
+        const m = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        if (m.reply_to !== requestId) continue;
+        if (expectFrom && m.from !== expectFrom) continue;
+        if (m.payload?.status) {
+          const ts = m.ts ?? 0;
+          const w = ACK_WEIGHT[m.payload.status] ?? 0;
+          const bw = best ? (ACK_WEIGHT[best.status] ?? 0) : -1;
+          if (!best || ts > best.ts || (ts === best.ts && w > bw)) {
+            best = { ts, status: m.payload.status, id: m.id, from: m.from, payload: m.payload };
+          }
+        }
+      } catch {
+        // 跳过损坏消息
+      }
+    }
+  }
+  return best;
+}
+
 /** 按 id 删除消息: inbox=true 删对方目录(已处理), 否则删自己的目录(已发送)。 */
 export function removeMessage(cfg, id, inbox = false) {
   const dirs = resolveDirs(cfg);
@@ -155,6 +323,54 @@ export function removeMessage(cfg, id, inbox = false) {
   return false;
 }
 
+/**
+ * 重置信箱: 清空所有参与者目录的消息 (msg_*.json)、已读标记 (.seen/ 与旧 .seen.json)、
+ * 唤醒标记 (.wake/) 以及会话注册表 (_sessions/, 含别名)。保留根目录本身 (可能是挂载点/配置根)。
+ * 返回各类删除计数; 各会话下次调用 mailbox 工具会自动重新登记身份。
+ * ⚠️ 破坏性: 全会话共享数据, 不可恢复。调用方负责确认 (工具层要求 confirm=true)。
+ */
+export function resetMailbox(cfg) {
+  const dirs = resolveDirs(cfg);
+  const targets = new Set([dirs.out, ...dirs.in]);
+  const removed = { messages: 0, seen: 0, registry: 0 };
+  const reg = registryDir(cfg);
+  if (existsSync(reg)) {
+    try {
+      removed.registry = readdirSync(reg).length;
+      rmSync(reg, { recursive: true, force: true });
+    } catch {
+      removed.registry = 0;
+    }
+  }
+  for (const dir of targets) {
+    if (!dir || !existsSync(dir)) continue;
+    for (const f of readdirSync(dir)) {
+      const p = join(dir, f);
+      try {
+        const st = statSync(p);
+        if (st.isDirectory()) {
+          if (f === ".seen" || f === ".wake") {
+            // .wake 唤醒标记与 .seen 同属点目录状态文件, 一并计入 seen 计数
+            removed.seen += readdirSync(p).length;
+            rmSync(p, { recursive: true, force: true });
+          }
+          continue;
+        }
+        if (f.startsWith("msg_") && f.endsWith(".json")) {
+          removed.messages++;
+          rmSync(p, { force: true });
+        } else if (f === ".seen.json") {
+          removed.seen++;
+          rmSync(p, { force: true });
+        }
+      } catch {
+        // 单个文件处理失败跳过
+      }
+    }
+  }
+  return removed;
+}
+
 /** TTL 清理: 删除自己 OutDir 中超过 ttlHours 的已发送消息 (收方应已读过)。返回删除数。 */
 export function cleanTTL(cfg, { ttlHours = 24, dryRun = false } = {}) {
   const dirs = resolveDirs(cfg);
@@ -166,6 +382,8 @@ export function cleanTTL(cfg, { ttlHours = 24, dryRun = false } = {}) {
     const p = join(dirs.out, f);
     try {
       if (statSync(p).mtimeMs < cutoff) {
+        const message = JSON.parse(readFileSync(p, "utf-8"));
+        if (message.type === "request" && !latestReplyStatus(cfg, message.id)) continue;
         if (!dryRun) rmSync(p, { force: true });
         removed++;
       }
@@ -274,6 +492,14 @@ function registryFileOf(cfg, key) {
   return dir ? join(dir, `${key}.json`) : "";
 }
 
+function writeRegistry(cfg, key, value) {
+  const file = registryFileOf(cfg, key);
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(temp, JSON.stringify(value, null, 2) + "\n", "utf-8");
+  rmSync(file, { force: true });
+  renameSync(temp, file);
+}
+
 function readRegistry(cfg, key) {
   const f = registryFileOf(cfg, key);
   if (!f || !existsSync(f)) return undefined;
@@ -302,7 +528,7 @@ export function touchRegistry(cfg, session, { alias } = {}) {
     lastSeen: now,
   };
   mkdirSync(dir, { recursive: true });
-  writeFileSync(registryFileOf(cfg, key), JSON.stringify(rec, null, 2) + "\n", "utf-8");
+  writeRegistry(cfg, key, rec);
   return rec;
 }
 
@@ -323,7 +549,7 @@ export function touchRegistryCli(cfg, { workspace = "" } = {}) {
     lastSeen: now,
   };
   mkdirSync(dir, { recursive: true });
-  writeFileSync(registryFileOf(cfg, key), JSON.stringify(rec, null, 2) + "\n", "utf-8");
+  writeRegistry(cfg, key, rec);
   return rec;
 }
 
@@ -384,11 +610,15 @@ export function resolveTarget(cfg, to) {
   // 按工作区匹配: 完整路径 (正反斜杠归一) 或目录名 (如 D:/.../dsh-mailbox 或 dsh-mailbox)
   const norm = (p) => String(p || "").replace(/\\/g, "/").replace(/\/+$/, "");
   const targetNorm = norm(to);
-  const byWorkspace = sessions.find((s) => {
+  const workspaceMatches = sessions.filter((s) => {
     const ws = norm(s.workspace);
     return ws === targetNorm || ws.split("/").pop() === targetNorm;
   });
-  if (byWorkspace) return byWorkspace.identity || to;
+  if (workspaceMatches.length > 1) {
+    const identities = workspaceMatches.map((s) => s.identity).filter(Boolean).join(", ");
+    throw new Error(`workspace '${to}' 对应多个会话 (${identities})，请使用 identity、alias 或完整 sessionId`);
+  }
+  if (workspaceMatches.length === 1) return workspaceMatches[0].identity || to;
   return to;
 }