@yuanchilin/dsh-mailbox 1.0.0

package/skill/mailbox.psm1

@@ -0,0 +1,270 @@
+# ============================================================================
+#  mailbox.psm1 — 通用跨会话文件信箱 v1 (泛化自 mcp/RP 联调工具)
+#
+#  模型: N 个对等参与者, 每人一个信箱目录, 各写各的, 互读对方的。
+#    - layout=root (标准): 共享根目录 <root>/<id>/ 每人一个子目录
+#    - layout=dirs (兼容旧双目录): 显式 dirs 映射 { id -> 目录 }
+#    - 消息格式: { id, from, to, type, topic, payload, ts, reply_to }
+#    - 路由: to=<id> 定向 / to=all 广播 (写一份, 各人自取)
+#    - seen 去重: 每参与者独立 seen 文件 (默认 <outDir>/.seen.json)
+#
+#  用法:
+#    Import-Module <dir>/mailbox.psm1
+#    $cfg = Get-MailboxConfig                       # 配置解析 (env > 文件 > 默认)
+#    Send-Mailbox -Cfg $cfg -To "agent-b" -Topic "hello" -Payload @{x=1}
+#    $msgs = Recv-Mailbox -Cfg $cfg                 # 读取新消息 (自动更新 seen)
+#    Remove-MailboxMsg -Cfg $cfg -Id $msg.id -InInbox
+# ============================================================================
+
+Set-StrictMode -Version Latest
+
+# ---------------------------------------------------------------------------
+# 配置解析: 默认值 < 环境变量 < 配置文件 (CLI 参数由调用方覆盖)
+# ---------------------------------------------------------------------------
+function Get-MailboxConfig {
+    param([string]$ConfigPath = "")
+
+    $cfg = @{
+        identity     = ""
+        layout       = "root"        # root | dirs
+        root         = ""
+        dirs         = @{}           # layout=dirs: { id -> 目录 }
+        participants = @()           # layout=root 可选的显式参与者列表 (默认自动扫描)
+        intervalSec  = 2
+        timeoutSec   = 0
+        seenFile     = ""            # 默认 <outDir>/.seen.json
+        patchRoot    = ""            # 供示例补丁 handler 使用
+    }
+
+    if ($ConfigPath -eq "") { $ConfigPath = $env:MAILBOX_CONFIG }
+    if ($ConfigPath -eq "") { $ConfigPath = Join-Path $PSScriptRoot "mailbox.config.json" }
+    if (Test-Path -LiteralPath $ConfigPath) {
+        try {
+            $file = Get-Content -LiteralPath $ConfigPath -Raw | ConvertFrom-Json
+            foreach ($k in @($cfg.Keys)) {
+                if ($null -ne $file.$k) { $cfg[$k] = $file.$k }
+            }
+        } catch {
+            Write-Warning "读取配置失败: $ConfigPath ($($_.Exception.Message))"
+        }
+    }
+
+    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 = [int]$env:MAILBOX_INTERVAL }
+    if ($env:MAILBOX_TIMEOUT)  { $cfg.timeoutSec = [int]$env:MAILBOX_TIMEOUT }
+
+    # 规范化: JSON 解析出的 dirs 是 PSCustomObject, participants 可能是 $null/空数组
+    if ($cfg.dirs -and $cfg.dirs -isnot [System.Collections.IDictionary]) {
+        $h = @{}
+        foreach ($p in $cfg.dirs.PSObject.Properties) { $h[$p.Name] = [string]$p.Value }
+        $cfg.dirs = $h
+    }
+    if ($null -eq $cfg.dirs) { $cfg.dirs = @{} }
+    $cfg.participants = @(@($cfg.participants) | Where-Object { $_ })
+
+    return $cfg
+}
+
+# ---------------------------------------------------------------------------
+# 目录解析: 返回 @{ Out = <自己的目录>; In = @(<对方目录...>) }
+# ---------------------------------------------------------------------------
+function Resolve-MailboxDirs {
+    param($Cfg)
+
+    if ($Cfg.layout -eq "dirs") {
+        # dirs 可能是程序构造的 hashtable 或配置文件解析出的 PSCustomObject, 统一为 hashtable
+        $dirMap = @{}
+        if ($Cfg.dirs -is [System.Collections.IDictionary]) {
+            $dirMap = $Cfg.dirs
+        } elseif ($Cfg.dirs) {
+            foreach ($p in $Cfg.dirs.PSObject.Properties) { $dirMap[$p.Name] = [string]$p.Value }
+        }
+        if (-not $dirMap.ContainsKey($Cfg.identity)) {
+            throw "layout=dirs 但配置缺少 identity '$($Cfg.identity)' 的目录映射"
+        }
+        $out = $dirMap[$Cfg.identity]
+        $in = @()
+        foreach ($k in @($dirMap.Keys)) {
+            if ($k -ne $Cfg.identity) { $in += $dirMap[$k] }
+        }
+        return @{ Out = $out; In = @($in | Select-Object -Unique) }
+    }
+
+    # layout=root
+    if (-not $Cfg.root) { throw "layout=root 需要配置 root" }
+    $out = Join-Path $Cfg.root $Cfg.identity
+    $in = @()
+    $participants = @(@($Cfg.participants) | Where-Object { $_ })
+    if ($participants.Count -eq 0) {
+        $participants = @(Get-ChildItem -LiteralPath $Cfg.root -Directory -ErrorAction SilentlyContinue |
+            Select-Object -ExpandProperty Name)
+    }
+    foreach ($p in $participants) {
+        if ($p -ne $Cfg.identity -and $p -ne "") { $in += (Join-Path $Cfg.root $p) }
+    }
+    return @{ Out = $out; In = @($in | Select-Object -Unique) }
+}
+
+# ---------------------------------------------------------------------------
+# seen 读写
+# ---------------------------------------------------------------------------
+function Get-MailboxSeenFile {
+    param($Cfg)
+    if ($Cfg.seenFile -ne "") { return $Cfg.seenFile }
+    return Join-Path (Resolve-MailboxDirs $Cfg).Out ".seen.json"
+}
+
+function Get-MailboxSeen {
+    param($Cfg)
+    $f = Get-MailboxSeenFile $Cfg
+    $seen = @()
+    if (Test-Path -LiteralPath $f) {
+        try { $seen = @((Get-Content -LiteralPath $f -Raw | ConvertFrom-Json)) } catch { $seen = @() }
+    }
+    # 逗号运算符: 防止单元素数组在函数输出边界被解包成裸字符串 (PowerShell 经典坑)
+    return ,$seen
+}
+
+function Save-MailboxSeen {
+    param($Cfg, [string[]]$Seen)
+    $f = Get-MailboxSeenFile $Cfg
+    $dir = Split-Path $f -Parent
+    if ($dir -and -not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
+    # 参数形式 (-InputObject) 保证单元素也输出数组 JSON ["a"], 避免管道解包成 "a"
+    $unique = @($Seen | Select-Object -Unique)
+    ConvertTo-Json -InputObject $unique | Set-Content -LiteralPath $f -Encoding UTF8
+}
+
+# ---------------------------------------------------------------------------
+# 发送: 写到自己的目录 (对方读你的目录)
+# ---------------------------------------------------------------------------
+function Send-Mailbox {
+    param(
+        [Parameter(Mandatory)][string]$To,                     # 参与者 id 或 "all"
+        [ValidateSet("request","response","notify","reply")][string]$Type = "notify",
+        [string]$Topic = "",
+        $Payload = @{},
+        [string]$ReplyTo = "",
+        $Cfg
+    )
+
+    $dirs = Resolve-MailboxDirs $Cfg
+    if (-not (Test-Path -LiteralPath $dirs.Out)) { New-Item -ItemType Directory -Force -Path $dirs.Out | Out-Null }
+
+    $id = "$(Get-Date -Format 'yyyyMMddHHmmss')-$(Get-Random -Minimum 1000 -Maximum 9999)-$([guid]::NewGuid().ToString('N').Substring(0,4))"
+    $msg = [ordered]@{
+        id = $id
+        from = $Cfg.identity
+        to = $To
+        type = $Type
+        topic = $Topic
+        payload = $Payload
+        ts = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+        reply_to = $ReplyTo
+    }
+    $file = Join-Path $dirs.Out "msg_$id.json"
+    $msg | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $file -Encoding UTF8
+    return $id
+}
+
+# ---------------------------------------------------------------------------
+# 接收: 扫描所有对方目录, 取 to=自己 或 to=all 且未 seen 的消息
+# ---------------------------------------------------------------------------
+function Recv-Mailbox {
+    param(
+        $Cfg,
+        [switch]$KeepSeen   # 置位时只读不更新 seen (wait 场景由调用方决定)
+    )
+
+    # Get-MailboxSeen 已用逗号保证返回扁平数组, 这里不要再 @() 包装 (会变成嵌套数组)
+    $seen = Get-MailboxSeen $Cfg
+    $new = @()
+    foreach ($dir in (Resolve-MailboxDirs $Cfg).In) {
+        if (-not (Test-Path -LiteralPath $dir)) { continue }
+        Get-ChildItem -LiteralPath $dir -Filter "msg_*.json" -ErrorAction SilentlyContinue |
+            Sort-Object Name |
+            ForEach-Object {
+                try {
+                    $m = Get-Content -LiteralPath $_.FullName -Raw | ConvertFrom-Json
+                    if (($m.to -eq $Cfg.identity -or $m.to -eq "all") -and ($seen -notcontains $m.id)) {
+                        $new += $m
+                        if (-not $KeepSeen) { $seen += $m.id }
+                    }
+                } catch { }
+            }
+    }
+    if (-not $KeepSeen) { Save-MailboxSeen $Cfg $seen }
+    return $new
+}
+
+# ---------------------------------------------------------------------------
+# 删除消息: -InInbox 删对方目录(已处理), 默认删自己的目录(已发送)
+# ---------------------------------------------------------------------------
+function Remove-MailboxMsg {
+    param(
+        [Parameter(Mandatory)][string]$Id,
+        $Cfg,
+        [switch]$InInbox
+    )
+
+    $dirs = Resolve-MailboxDirs $Cfg
+    $dirsToScan = if ($InInbox) { $dirs.In } else { @($dirs.Out) }
+    foreach ($dir in $dirsToScan) {
+        if (-not (Test-Path -LiteralPath $dir)) { continue }
+        Get-ChildItem -LiteralPath $dir -Filter "msg_*.json" -ErrorAction SilentlyContinue |
+            ForEach-Object {
+                try {
+                    $m = Get-Content -LiteralPath $_.FullName -Raw | ConvertFrom-Json
+                    if ($m.id -eq $Id) { Remove-Item -LiteralPath $_.FullName -Force; return }
+                } catch { }
+            }
+    }
+}
+
+# ---------------------------------------------------------------------------
+# TTL 清理: 删除自己 OutDir 中超过 TtlHours 的已发送消息 (收方应已读过)
+# ---------------------------------------------------------------------------
+function Clear-MailboxTTL {
+    param($Cfg, [int]$TtlHours = 24, [switch]$DryRun)
+
+    $dirs = Resolve-MailboxDirs $Cfg
+    if (-not (Test-Path -LiteralPath $dirs.Out)) { return 0 }
+    $cutoff = (Get-Date).AddHours(-$TtlHours)
+    $removed = 0
+    Get-ChildItem -LiteralPath $dirs.Out -Filter "msg_*.json" -ErrorAction SilentlyContinue |
+        ForEach-Object {
+            if ($_.LastWriteTime -lt $cutoff) {
+                if (-not $DryRun) { Remove-Item -LiteralPath $_.FullName -Force }
+                $removed++
+            }
+        }
+    return $removed
+}
+
+# ---------------------------------------------------------------------------
+# 状态: 身份/目录/各参与者消息数/未读数
+# ---------------------------------------------------------------------------
+function Get-MailboxStatus {
+    param($Cfg)
+
+    $dirs = Resolve-MailboxDirs $Cfg
+    $seen = Get-MailboxSeen $Cfg
+    $inInfo = @()
+    foreach ($dir in $dirs.In) {
+        $count = if (Test-Path -LiteralPath $dir) {
+            @(Get-ChildItem -LiteralPath $dir -Filter "msg_*.json" -ErrorAction SilentlyContinue).Count
+        } else { 0 }
+        $inInfo += [pscustomobject]@{ Dir = $dir; MsgCount = $count }
+    }
+    return [pscustomobject]@{
+        identity = $Cfg.identity
+        layout   = $Cfg.layout
+        outDir   = $dirs.Out
+        outCount = @(Get-ChildItem -LiteralPath $dirs.Out -Filter "msg_*.json" -ErrorAction SilentlyContinue).Count
+        seen     = @($seen).Count
+        inboxes  = $inInfo
+    }
+}
+
+Export-ModuleMember -Function Get-MailboxConfig, Resolve-MailboxDirs, Send-Mailbox, Recv-Mailbox, Remove-MailboxMsg, Clear-MailboxTTL, Get-MailboxStatus

package/skill/self-test.ps1

@@ -0,0 +1,105 @@
+# ============================================================================
+#  self-test.ps1 — mailbox 泛化工具自测
+#  覆盖: 往返 / 广播 / wait 唤醒 / TTL 清理 / pwsh↔node 互通 / 旧 dirs 布局 / seen 去重
+#  用法: .\self-test.ps1   (全部通过 exit 0)
+# ============================================================================
+$ErrorActionPreference = "Stop"
+
+$toolDir = $PSScriptRoot
+$testRoot = Join-Path $toolDir ".selftest"
+if (Test-Path -LiteralPath $testRoot) { Remove-Item -Recurse -Force -LiteralPath $testRoot }
+New-Item -ItemType Directory -Force -Path $testRoot | Out-Null
+
+$pass = 0; $fail = 0
+function Check($name, $cond) {
+    if ($cond) { Write-Host "PASS  $name"; $script:pass++ }
+    else       { Write-Host "FAIL  $name"; $script:fail++ }
+}
+
+Import-Module (Join-Path $toolDir "mailbox.psm1") -Force
+
+# ---- 配置: root 布局, 三参与者 agent-a / agent-b / rp ----
+$cfgA = Get-MailboxConfig; $cfgA.identity = "agent-a"; $cfgA.root = $testRoot; $cfgA.layout = "root"
+$cfgB = Get-MailboxConfig; $cfgB.identity = "agent-b"; $cfgB.root = $testRoot; $cfgB.layout = "root"
+$cfgR = Get-MailboxConfig; $cfgR.identity = "rp";     $cfgR.root = $testRoot; $cfgR.layout = "root"
+New-Item -ItemType Directory -Force -Path (Join-Path $testRoot "rp") | Out-Null   # 让自动扫描包含 rp
+
+# 供 CLI 使用的配置文件
+$cfgAFile = Join-Path $testRoot "agent-a.config.json"
+$cfgBFile = Join-Path $testRoot "agent-b.config.json"
+@{ identity="agent-a"; layout="root"; root=$testRoot; dirs=@{}; participants=@(); intervalSec=1; timeoutSec=0; seenFile=""; patchRoot="" } | ConvertTo-Json | Set-Content $cfgAFile -Encoding UTF8
+@{ identity="agent-b"; layout="root"; root=$testRoot; dirs=@{}; participants=@(); intervalSec=1; timeoutSec=0; seenFile=""; patchRoot="" } | ConvertTo-Json | Set-Content $cfgBFile -Encoding UTF8
+
+$ps1 = Join-Path $toolDir "mailbox.ps1"
+$mjs = Join-Path $toolDir "mailbox.mjs"
+
+# ================= 1. 模块级: 往返 + seen 去重 =================
+$id1 = Send-Mailbox -Cfg $cfgA -To "agent-b" -Topic "hello" -Payload @{ x = 1 }
+$msgs = @(Recv-Mailbox -Cfg $cfgB)
+Check "往返: B 收到 A 的消息" ($msgs.Count -eq 1 -and $msgs[0].from -eq "agent-a" -and $msgs[0].topic -eq "hello")
+Check "往返: payload 正确" ($msgs[0].payload.x -eq 1)
+$msgs2 = @(Recv-Mailbox -Cfg $cfgB)
+Check "seen 去重: 第二次 recv 无新消息" ($msgs2.Count -eq 0)
+
+# ================= 2. 广播 to=all =================
+Send-Mailbox -Cfg $cfgR -To "all" -Topic "broadcast" -Payload @{ n = 42 } | Out-Null
+$b1 = @(Recv-Mailbox -Cfg $cfgA)
+$b2 = @(Recv-Mailbox -Cfg $cfgB)
+Check "广播: A 和 B 都收到 to=all" ($b1.Count -eq 1 -and $b2.Count -eq 1 -and $b1[0].topic -eq "broadcast")
+
+# ================= 3. wait 唤醒 (pwsh CLI) =================
+Send-Mailbox -Cfg $cfgA -To "agent-b" -Topic "wake" | Out-Null
+$waitOut = & $ps1 wait -Config $cfgBFile -Timeout 5 6>&1 2>&1 | Out-String
+Check "wait: 有新消息时输出唤醒标记" ($waitOut -match "WAKE-UP")
+
+# ================= 4. TTL 清理 =================
+$idOld = Send-Mailbox -Cfg $cfgA -To "agent-b" -Topic "old" | Out-Null
+$oldFile = Get-ChildItem -LiteralPath (Join-Path $testRoot "agent-a") -Filter "msg_*.json" | Sort-Object LastWriteTime | Select-Object -Last 1
+$oldFile.LastWriteTime = (Get-Date).AddDays(-2)
+$dry = Clear-MailboxTTL -Cfg $cfgA -TtlHours 24 -DryRun
+Check "TTL dry-run: 计数 1" ($dry -eq 1)
+$real = Clear-MailboxTTL -Cfg $cfgA -TtlHours 24
+Check "TTL: 实际删除 1" ($real -eq 1)
+Check "TTL: 文件已消失" (-not (Test-Path -LiteralPath $oldFile.FullName))
+
+# ================= 5. pwsh ↔ node 互通 =================
+& node $mjs send --config $cfgBFile --to agent-a --topic from-node --payload '{"n":2}' 2>&1 | Out-Null
+$recvA = @(Recv-Mailbox -Cfg $cfgA)
+Check "node 发 → pwsh 收" ($recvA.Count -eq 1 -and $recvA[0].from -eq "agent-b" -and $recvA[0].topic -eq "from-node" -and $recvA[0].payload.n -eq 2)
+
+Send-Mailbox -Cfg $cfgA -To "agent-b" -Topic "to-node" -Payload @{ k = "v" } | Out-Null
+$nodeRecv = & node $mjs recv --config $cfgBFile --format json 2>&1 | Out-String
+Check "pwsh 发 → node 收" ($nodeRecv -match "to-node")
+
+$nodeStatus = & node $mjs status --config $cfgAFile 2>&1 | Out-String
+Check "node status 正常" ($nodeStatus -match "agent-a")
+
+# ================= 6. 旧 dirs 布局兼容 (CLI) =================
+$legacyRoot = Join-Path $testRoot "legacy"
+New-Item -ItemType Directory -Force -Path (Join-Path $legacyRoot "mcp") | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $legacyRoot "rp")  | Out-Null
+$legacyCfgM = Join-Path $testRoot "legacy-mcp.config.json"
+$legacyCfgR = Join-Path $testRoot "legacy-rp.config.json"
+@{ identity="mcp"; layout="dirs"; root=""; dirs=@{ mcp=(Join-Path $legacyRoot "mcp"); rp=(Join-Path $legacyRoot "rp") }; participants=@(); intervalSec=1; timeoutSec=0; seenFile=""; patchRoot="" } | ConvertTo-Json | Set-Content $legacyCfgM -Encoding UTF8
+@{ identity="rp";  layout="dirs"; root=""; dirs=@{ mcp=(Join-Path $legacyRoot "mcp"); rp=(Join-Path $legacyRoot "rp") }; participants=@(); intervalSec=1; timeoutSec=0; seenFile=""; patchRoot="" } | ConvertTo-Json | Set-Content $legacyCfgR -Encoding UTF8
+& $ps1 send -Config $legacyCfgM -To "rp" -Topic "legacy-test" -Payload '{"L":1}' 2>&1 | Out-Null
+$legacyRecv = & node $mjs recv --config $legacyCfgR --format json 2>&1 | Out-String
+Check "旧 dirs 布局: mcp 发 → rp (node) 收" ($legacyRecv -match "legacy-test")
+Check "旧 dirs 布局: 不创建幽灵目录" (-not (Test-Path -LiteralPath (Join-Path $testRoot "legacy\mcp\.seen.json")))
+
+# ================= 7. CLI status / recv 空 =================
+$st = & $ps1 status -Config $cfgAFile 6>&1 2>&1 | Out-String
+Check "pwsh status 正常" ($st -match "agent-a")
+$empty = & $ps1 recv -Config $cfgBFile 6>&1 2>&1 | Out-String
+Check "recv 无新消息提示" ($empty -match "无新消息")
+
+# ================= 8. 泛化代码无硬编码路径 =================
+$hardcoded = Select-String -Path (Join-Path $toolDir "mailbox.psm1"),(Join-Path $toolDir "mailbox.ps1"),(Join-Path $toolDir "mailbox.mjs") -Pattern 'D:\\Downloads|Agent\\Soc|Agent\\RP' -ErrorAction SilentlyContinue
+Check "泛化代码无硬编码路径 (Soc/RP)" ($null -eq $hardcoded)
+
+# ================= 清理 =================
+Remove-Item -Recurse -Force -LiteralPath $testRoot
+Write-Host ""
+Write-Host "结果: PASS=$pass FAIL=$fail"
+if ($fail -gt 0) { exit 1 }
+exit 0