@yuanchilin/dsh-mailbox 1.0.0

package/skill/mailbox.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+// ============================================================================
+//  mailbox.mjs — 通用跨会话文件信箱 CLI v1 (Node 版, 零依赖)
+//
+//  与 pwsh 版 (mailbox.ps1) 同协议、同配置、同命令, 可互换混用:
+//    node mailbox.mjs init  --id agent-a --root D:/Downloads/Agent/.mailbox
+//    node mailbox.mjs send  --to agent-b --topic hello --payload '{"x":1}'
+//    node mailbox.mjs recv  --format table
+//    node mailbox.mjs wait  --timeout 60
+//    node mailbox.mjs poll  --interval 2 --handlers ./handlers.mjs
+//    node mailbox.mjs clean --ttl-hours 24
+//    node mailbox.mjs status
+//
+//  配置优先级: 参数 > 环境变量 (MAILBOX_CONFIG/ID/ROOT/INTERVAL/TIMEOUT) > 配置文件 > 默认
+//  消息格式: { id, from, to, type, topic, payload, ts, reply_to }
+// ============================================================================
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join, dirname, basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(__dirname, "mailbox.config.json");
+
+// ---------------------------------------------------------------------------
+// 参数解析: --key value / --flag
+// ---------------------------------------------------------------------------
+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) {
+  const cfg = {
+    identity: "",
+    layout: "root",
+    root: "",
+    dirs: {},
+    participants: [],
+    intervalSec: 2,
+    timeoutSec: 0,
+    seenFile: "",
+    patchRoot: "",
+  };
+  let configPath = args.config || process.env.MAILBOX_CONFIG || DEFAULT_CONFIG;
+  if (existsSync(configPath)) {
+    try {
+      Object.assign(cfg, JSON.parse(readFileSync(configPath, "utf-8")));
+    } catch (e) {
+      console.warn(`[mailbox] 读取配置失败: ${configPath} (${e.message})`);
+    }
+  }
+  if (process.env.MAILBOX_ID) cfg.identity = process.env.MAILBOX_ID;
+  if (process.env.MAILBOX_ROOT) { cfg.root = process.env.MAILBOX_ROOT; cfg.layout = "root"; }
+  if (process.env.MAILBOX_INTERVAL) cfg.intervalSec = Number(process.env.MAILBOX_INTERVAL);
+  if (process.env.MAILBOX_TIMEOUT) cfg.timeoutSec = Number(process.env.MAILBOX_TIMEOUT);
+  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 };
+}
+
+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 = Array.isArray(cfg.participants) && cfg.participants.length > 0 ? cfg.participants : [];
+  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 };
+}
+
+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 [];
+  try {
+    // pwsh 旧版本可能把单元素 seen 写成裸字符串 "id", 归一化为数组
+    const v = JSON.parse(readFileSync(f, "utf-8"));
+    return Array.isArray(v) ? v : [v];
+  } catch { return []; }
+}
+
+function saveSeen(cfg, seen) {
+  const f = seenFileOf(cfg);
+  mkdirSync(dirname(f), { recursive: true });
+  writeFileSync(f, JSON.stringify([...new Set(seen)]));
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------------------
+// 命令实现
+// ---------------------------------------------------------------------------
+function cmdInit(cfg, configPath, args) {
+  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}`);
+  console.log(JSON.stringify(out, null, 2));
+}
+
+function cmdSend(cfg, args) {
+  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}`); }
+  }
+  const dirs = resolveDirs(cfg);
+  mkdirSync(dirs.out, { recursive: true });
+  const id = `${ts()}${rand4()}-${rand4()}`;
+  const msg = {
+    id, from: cfg.identity, to: args.to,
+    type: args.type || "notify",
+    topic: args.topic || "",
+    payload,
+    ts: Date.now(),
+    reply_to: args.replyTo || "",
+  };
+  writeFileSync(join(dirs.out, `msg_${id}.json`), JSON.stringify(msg) + "\n", "utf-8");
+  console.log(`sent ${id}  (${new Date().toTimeString().slice(0, 8)})`);
+}
+
+function cmdRecv(cfg, args) {
+  const msgs = 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 ? JSON.stringify(m.payload) : "";
+      console.log(`[${m.from} -> ${m.to}] ${m.type} topic=${m.topic} id=${m.id}`);
+      if (m.reply_to) console.log(`   reply_to=${m.reply_to} ts=${m.ts}`);
+      if (p) console.log(`   payload: ${p}`);
+    }
+  }
+}
+
+function recvNew(cfg, markSeen) {
+  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;
+}
+
+async function cmdWait(cfg, args) {
+  const timeoutSec = cfg.timeoutSec;
+  const started = Date.now();
+  for (;;) {
+    const msgs = 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 (timeoutSec > 0 && (Date.now() - started) / 1000 >= timeoutSec) {
+      console.log(`TIMEOUT after ${timeoutSec}s, no new messages`);
+      process.exit(0);
+    }
+    await sleep(cfg.intervalSec * 1000);
+  }
+}
+
+async function cmdPoll(cfg, args) {
+  let handler = null;
+  if (args.handlers) {
+    const p = resolve(args.handlers);
+    handler = await import("file://" + p.replace(/\\/g, "/"));
+    console.log(`已加载 handlers: ${p}`);
+  }
+  console.log(`poll 启动 (identity=${cfg.identity} 每 ${cfg.intervalSec}s). Ctrl+C 退出`);
+  for (;;) {
+    try {
+      for (const m of recvNew(cfg, true)) {
+        console.log(`[收到] from=${m.from} type=${m.type} topic=${m.topic} id=${m.id}`);
+        let handled = false;
+        if (handler && typeof handler.handle === "function") {
+          handled = await handler.handle(m, { cfg, send: (o) => sendFrom(cfg, { ...o, from: cfg.identity }) });
+        }
+        if (!handled) {
+          if (m.type === "request") {
+            sendFrom(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 { removeMsg(cfg, m.id, true); } catch { /* 权限不足则跳过 */ }
+      }
+    } catch (e) {
+      console.warn(`轮询异常: ${e.message}`);
+    }
+    await sleep(cfg.intervalSec * 1000);
+  }
+}
+
+function sendFrom(cfg, { to, type = "notify", topic = "", payload = {}, replyTo = "" }) {
+  const dirs = resolveDirs(cfg);
+  mkdirSync(dirs.out, { recursive: true });
+  const id = `${ts()}${rand4()}-${rand4()}`;
+  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;
+}
+
+function removeMsg(cfg, id, inbox) {
+  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; }
+      } catch { /* 跳过 */ }
+    }
+  }
+}
+
+function cmdClean(cfg, args) {
+  const ttlHours = args.ttlHours !== undefined ? Number(args.ttlHours) : 24;
+  const dryRun = !!args.dryRun;
+  const dirs = resolveDirs(cfg);
+  if (!existsSync(dirs.out)) { console.log(`clean: 0 条 (目录不存在)`); return; }
+  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 { /* 跳过 */ }
+  }
+  console.log(`clean: ${dryRun ? "dry-run" : "已删除"} ${removed} 条过期消息 (TtlHours=${ttlHours})`);
+}
+
+function cmdStatus(cfg) {
+  const dirs = resolveDirs(cfg);
+  const seen = loadSeen(cfg).length;
+  const outCount = existsSync(dirs.out) ? readdirSync(dirs.out).filter((f) => f.startsWith("msg_")).length : 0;
+  console.log(`身份: ${cfg.identity}  layout=${cfg.layout}`);
+  console.log(`写:   ${dirs.out}  (消息 ${outCount})`);
+  console.log(`seen: ${seen} 条`);
+  for (const d of dirs.in) {
+    const n = existsSync(d) ? readdirSync(d).filter((f) => f.startsWith("msg_")).length : 0;
+    console.log(`读:   ${d}  (消息 ${n})`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 工具
+// ---------------------------------------------------------------------------
+function ts() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+function rand4() {
+  return Math.random().toString(16).slice(2, 6).padEnd(4, "0");
+}
+
+// ---------------------------------------------------------------------------
+// 入口
+// ---------------------------------------------------------------------------
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0] || "status";
+const { cfg, configPath } = getConfig(args);
+
+try {
+  switch (command) {
+    case "init": cmdInit(cfg, configPath, args); break;
+    case "send": cmdSend(cfg, args); break;
+    case "recv": cmdRecv(cfg, args); break;
+    case "wait": await cmdWait(cfg, args); break;
+    case "poll": await cmdPoll(cfg, args); break;
+    case "clean": cmdClean(cfg, args); break;
+    case "status": cmdStatus(cfg); break;
+    default:
+      console.error(`未知命令: ${command} (可用: init/send/recv/wait/poll/clean/status)`);
+      process.exit(1);
+  }
+} catch (e) {
+  console.error(`[mailbox] ${e.message}`);
+  process.exit(1);
+}

package/skill/mailbox.ps1

@@ -0,0 +1,172 @@
+# ============================================================================
+#  mailbox.ps1 — 通用跨会话文件信箱 CLI v1
+#
+#  用法示例:
+#    .\mailbox.ps1 init -Id agent-a -Root D:/Downloads/Agent/.mailbox
+#    .\mailbox.ps1 send -To agent-b -Topic hello -Payload '{"x":1}'
+#    .\mailbox.ps1 recv -Format table
+#    .\mailbox.ps1 wait -Timeout 60                  # 新消息即退出 (exit 0, 唤醒 agent)
+#    .\mailbox.ps1 poll -Interval 2 -Handlers .\examples\handlers.patch.ps1
+#    .\mailbox.ps1 clean -TtlHours 24
+#    .\mailbox.ps1 status
+#
+#  配置优先级: 参数 > 环境变量 (MAILBOX_CONFIG/ID/ROOT/INTERVAL/TIMEOUT) > 配置文件 > 默认
+# ============================================================================
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet("init","send","recv","wait","poll","clean","status")]
+    [string]$Command = "status",
+
+    [string]$Config = "",
+    [string]$Identity = "",
+    [string]$Root = "",
+
+    # send
+    [string]$To = "",
+    [ValidateSet("request","response","notify","reply")]
+    [string]$Type = "notify",
+    [string]$Topic = "",
+    [string]$Payload = "",
+    [string]$ReplyTo = "",
+
+    # recv
+    [ValidateSet("table","json")]
+    [string]$Format = "table",
+
+    # wait / poll
+    [int]$Timeout = -1,
+    [int]$Interval = -1,
+    [string]$Handlers = "",
+
+    # clean
+    [int]$TtlHours = 24,
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+Import-Module (Join-Path $PSScriptRoot "mailbox.psm1") -Force
+
+$cfg = Get-MailboxConfig -ConfigPath $Config
+if ($Identity) { $cfg.identity = $Identity }
+if ($Root)     { $cfg.root = $Root; $cfg.layout = "root" }
+if (-not $cfg.identity) { throw "未指定身份: 请用 -Identity / MAILBOX_ID / 配置文件 identity" }
+if ($Interval -ge 0)    { $cfg.intervalSec = $Interval }
+if ($Timeout -ge 0)     { $cfg.timeoutSec = $Timeout }
+
+switch ($Command) {
+    "init" {
+        $out = [ordered]@{
+            identity = $cfg.identity
+            layout   = "root"
+            root     = $cfg.root
+            dirs     = $cfg.dirs
+            participants = @()
+            intervalSec  = $cfg.intervalSec
+            timeoutSec   = $cfg.timeoutSec
+            seenFile     = $cfg.seenFile
+            patchRoot    = $cfg.patchRoot
+        }
+        $cfgPath = if ($Config) { $Config } else { Join-Path $PSScriptRoot "mailbox.config.json" }
+        $out | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $cfgPath -Encoding UTF8
+        Write-Host "已生成配置: $cfgPath"
+        Write-Host ($out | ConvertTo-Json -Depth 6)
+    }
+
+    "send" {
+        if (-not $To) { throw "send 需要 -To <id|all>" }
+        $payloadObj = @{}
+        if ($Payload) {
+            try { $payloadObj = $Payload | ConvertFrom-Json } catch { throw "payload 不是合法 JSON: $Payload" }
+        }
+        $id = Send-Mailbox -Cfg $cfg -To $To -Type $Type -Topic $Topic -Payload $payloadObj -ReplyTo $ReplyTo
+        Write-Output "sent $id  ($(Get-Date -Format 'HH:mm:ss'))"
+    }
+
+    "recv" {
+        $msgs = @(Recv-Mailbox -Cfg $cfg)
+        if ($msgs.Count -eq 0) { Write-Output "(无新消息)"; break }
+        if ($Format -eq "json") {
+            $msgs | ForEach-Object { Write-Output ($_ | ConvertTo-Json -Depth 8 -Compress) }
+        } else {
+            $msgs | ForEach-Object {
+                $p = if ($_.payload) { ($_ | ConvertTo-Json -Depth 3 -Compress) } else { "" }
+                Write-Host "[$($_.from) -> $($_.to)] $($_.type) topic=$($_.topic) id=$($_.id)"
+                Write-Host "   reply_to=$($_.reply_to) ts=$($_.ts)"
+                if ($p) { Write-Host "   payload: $p" }
+            }
+        }
+    }
+
+    "wait" {
+        # 事件唤醒: 检测到新消息 → 打印 → exit 0 (DSH 后台 job 完成即通知 agent)
+        $started = Get-Date
+        while ($true) {
+            $msgs = @(Recv-Mailbox -Cfg $cfg)
+            if ($msgs.Count -gt 0) {
+                Write-Host "=== NEW MESSAGES: $($msgs.Count) ==="
+                $msgs | ForEach-Object { Write-Host ($_ | ConvertTo-Json -Depth 8 -Compress) }
+                Write-Host "=== WAKE-UP (exit 0) ==="
+                exit 0
+            }
+            if ($cfg.timeoutSec -gt 0 -and ((Get-Date) - $started).TotalSeconds -ge $cfg.timeoutSec) {
+                Write-Host "TIMEOUT after $($cfg.timeoutSec)s, no new messages"
+                exit 0
+            }
+            Start-Sleep -Seconds $cfg.intervalSec
+        }
+    }
+
+    "poll" {
+        # 常驻轮询: 默认 request→echo response, notify/reply→打印
+        # -Handlers <ps1>: dot-source 后若定义 Handle-Message($Msg, $Ctx) 则调用
+        if ($Handlers) {
+            $handlersPath = if (Test-Path -LiteralPath $Handlers) { (Resolve-Path $Handlers).Path } else { $Handlers }
+            . $handlersPath
+            Write-Host "已加载 handlers: $handlersPath"
+        }
+        Write-Host "poll 启动 (identity=$($cfg.identity) 每 $($cfg.intervalSec)s). Ctrl+C 退出"
+        while ($true) {
+            try {
+                $msgs = @(Recv-Mailbox -Cfg $cfg)
+                foreach ($m in $msgs) {
+                    Write-Host "[收到] from=$($m.from) type=$($m.type) topic=$($m.topic) id=$($m.id)"
+                    $handled = $false
+                    if ($Handlers -and (Get-Command Handle-Message -ErrorAction SilentlyContinue)) {
+                        $handled = Handle-Message -Msg $m -Ctx @{ Cfg = $cfg }
+                    }
+                    if (-not $handled) {
+                        if ($m.type -eq "request") {
+                            # 默认: 自动回 response (echo)
+                            Send-Mailbox -Cfg $cfg -To $m.from -Type "response" -Topic $m.topic -ReplyTo $m.id `
+                                -Payload @{ echo = $m.payload; from = $cfg.identity }
+                            Write-Host "  → 已回 response (reply_to=$($m.id))"
+                        } else {
+                            Write-Host ($m | ConvertTo-Json -Depth 6 -Compress)
+                        }
+                    }
+                    try { Remove-MailboxMsg -Cfg $cfg -Id $m.id -InInbox } catch { }
+                }
+            } catch {
+                Write-Host "轮询异常: $($_.Exception.Message)" -ForegroundColor Yellow
+            }
+            Start-Sleep -Seconds $cfg.intervalSec
+        }
+    }
+
+    "clean" {
+        $removed = Clear-MailboxTTL -Cfg $cfg -TtlHours $TtlHours -DryRun:$DryRun
+        $mode = if ($DryRun) { "dry-run" } else { "已删除" }
+        Write-Output "clean: $mode $removed 条过期消息 (TtlHours=$TtlHours, outDir=$((Resolve-MailboxDirs $cfg).Out))"
+    }
+
+    "status" {
+        $s = Get-MailboxStatus $cfg
+        Write-Host "身份: $($s.identity)  layout=$($s.layout)"
+        Write-Host "写:   $($s.outDir)  (消息 $($s.outCount))"
+        Write-Host "seen: $($s.seen) 条"
+        foreach ($i in $s.inboxes) {
+            Write-Host "读:   $($i.Dir)  (消息 $($i.MsgCount))"
+        }
+    }
+}