@yuanchilin/dsh-mailbox 1.0.0

package/lib/types/index.d.ts

@@ -0,0 +1,44 @@
+// 最小类型声明 (core 与插件导出的形状)
+export interface MailboxConfig {
+  identity: string;
+  layout: "root" | "dirs";
+  root: string;
+  dirs: Record<string, string>;
+  participants: string[];
+  intervalSec: number;
+  timeoutSec: number;
+  seenFile: string;
+  patchRoot: string;
+}
+
+export interface MailboxMessage {
+  id: string;
+  from: string;
+  to: string;
+  type: "request" | "response" | "notify" | "reply";
+  topic: string;
+  payload: unknown;
+  ts: number;
+  reply_to: string;
+}
+
+export interface MailboxStatus {
+  identity: string;
+  layout: string;
+  outDir: string;
+  outCount: number;
+  seen: number;
+  inboxes: Array<{ dir: string; msgCount: number }>;
+}
+
+export function resolveConfig(partial?: Partial<MailboxConfig>, env?: NodeJS.ProcessEnv): MailboxConfig;
+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 sendMessage(cfg: MailboxConfig, msg: Partial<Pick<MailboxMessage, "to" | "type" | "topic" | "payload" | "reply_to">>): string;
+export function recvNew(cfg: MailboxConfig, markSeen?: boolean): MailboxMessage[];
+export function removeMessage(cfg: MailboxConfig, id: string, inbox?: boolean): boolean;
+export function cleanTTL(cfg: MailboxConfig, opts?: { ttlHours?: number; dryRun?: boolean }): number;
+export function statusOf(cfg: MailboxConfig): MailboxStatus;
+export function assertUsable(cfg: MailboxConfig): void;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@yuanchilin/dsh-mailbox",
+  "version": "1.0.0",
+  "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), plus a zero-dependency node CLI and a packaged DSH skill.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./core": {
+      "default": "./lib/core.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./skill/SKILL.md": "./skill/SKILL.md",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mailbox": "bin/mailbox.mjs"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/core.js",
+    "lib/types/index.d.ts",
+    "bin/mailbox.mjs",
+    "cordis.patch.yml",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "mailbox",
+    "cross-session",
+    "messaging",
+    "plugin"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skill/README.md

@@ -0,0 +1,117 @@
+# mailbox — 通用跨会话文件信箱 v1
+
+文件信箱，用于 **N 个会话/agent 之间的异步通信**。泛化自 mcp/RP 联调工具，零依赖、配置驱动、双实现（pwsh + Node）可互换混用。
+
+## 核心模型
+
+- 每个参与者有唯一身份 `id`，各写各的信箱目录，互读对方的
+- **layout=root（标准）**：共享根目录 `<root>/<id>/` 每人一个子目录
+- **layout=dirs（兼容旧双目录）**：`dirs: { id -> 目录 }` 显式映射，旧 mcp/RP 信箱免迁移接入
+- 消息格式：`{ id, from, to, type, topic, payload, ts, reply_to }`，文件 `msg_<id>.json`
+- 路由：`to=<id>` 定向 / `to=all` 广播（只写一份，各人自取）
+- seen 去重：每参与者独立 seen 文件（默认 `<outDir>/.seen.json`），重启不重复处理
+
+## 快速开始
+
+```powershell
+# 1. 初始化（每个参与者同一 root 下各一个目录）
+.\mailbox.ps1 init -Id agent-a -Root D:/Downloads/Agent/.mailbox
+.\mailbox.ps1 init -Id agent-b -Root D:/Downloads/Agent/.mailbox
+
+# 2. A 发消息
+.\mailbox.ps1 send -To agent-b -Topic hello -Payload '{"x":1}'
+
+# 3. B 收消息（一次性）
+.\mailbox.ps1 recv -Format table
+
+# 4. B 事件监听（新消息 → 打印 → exit 0，DSH 后台 job 完成即唤醒 agent）
+.\mailbox.ps1 wait -Timeout 600
+
+# 5. B 常驻轮询（request 自动回 response，可挂 handlers）
+.\mailbox.ps1 poll -Interval 2 -Handlers .\examples\handlers.patch.ps1
+```
+
+Node 版命令完全一致：
+
+```bash
+node mailbox.mjs send --to agent-b --topic hello --payload '{"x":1}'
+node mailbox.mjs recv --format table
+node mailbox.mjs wait --timeout 600
+```
+
+## 命令
+
+| 命令 | pwsh | node | 说明 |
+|---|---|---|---|
+| init | `init -Id x -Root y` | `init --id x --root y` | 生成配置文件 |
+| send | `send -To <id\|all> -Type <t> -Topic <t> -Payload <json> -ReplyTo <id>` | 同左 `--to/--type/--topic/--payload/--reply-to` | 发消息 |
+| recv | `recv [-Format table\|json]` | `recv [--format table\|json]` | 读新消息（更新 seen） |
+| wait | `wait [-Timeout sec] [-Interval sec]` | `wait [--timeout sec]` | 新消息即 exit 0（唤醒） |
+| poll | `poll [-Interval sec] [-Handlers <ps1>]` | `poll [--interval sec] [--handlers <mjs>]` | 常驻轮询 |
+| clean | `clean [-TtlHours n] [-DryRun]` | `clean [--ttl-hours n] [--dry-run]` | TTL 清理自己的已发送消息 |
+| status | `status` | `status` | 身份/目录/消息数 |
+
+## 配置
+
+配置文件默认 `mailbox.config.json`（与工具同目录），可用 `-Config` / `--config` 或环境变量 `MAILBOX_CONFIG` 指定。
+
+```json
+{
+  "identity": "agent-a",
+  "layout": "root",
+  "root": "D:/Downloads/Agent/.mailbox",
+  "dirs": {},
+  "participants": [],
+  "intervalSec": 2,
+  "timeoutSec": 0,
+  "seenFile": "",
+  "patchRoot": ""
+}
+```
+
+优先级：**CLI 参数 > 环境变量（`MAILBOX_CONFIG`/`MAILBOX_ID`/`MAILBOX_ROOT`/`MAILBOX_INTERVAL`/`MAILBOX_TIMEOUT`）> 配置文件 > 默认**。
+
+- `participants` 留空时自动扫描 `<root>/` 下的子目录作为参与者
+- `seenFile` 留空默认 `<outDir>/.seen.json`
+- `patchRoot` 供示例补丁 handler 使用
+
+## 消息类型与默认处理
+
+| type | 默认处理（poll） |
+|---|---|
+| request | 自动回 `response`（echo payload） |
+| response / notify / reply | 打印 |
+
+**可插拔 handler**：
+- pwsh：`-Handlers <ps1>`，dot-source 后定义 `function Handle-Message($Msg, $Ctx)`，返回 `$false` 回退默认逻辑
+- node：`--handlers <mjs>`，导出 `export async function handle(msg, ctx)`，返回 `false` 回退默认逻辑
+
+示例：`examples/handlers.patch.ps1` 补丁自动应用（备份→替换→`node --check`→失败回滚→写 `patches/history.jsonl`→回 response），协议：
+
+```json
+{ "type": "request", "topic": "patch_<任意>", "payload": {
+    "patch_id": "p1", "note": "说明",
+    "edits": [ { "file": "build/x.js", "old": "...", "new": "..." },
+               { "file": "build/y.js", "whole": "完整内容" },
+               { "file": "build/z.js", "old": "...", "new": "...", "replace_all": true } ] } }
+```
+
+## 旧布局兼容（mcp/RP）
+
+`legacy-mcp.config.json` 用 `layout:"dirs"` 映射原 mcp/RP 双目录，原轮询/监听脚本改为薄封装：
+
+```powershell
+.\mailbox_poll_mcp.ps1   # → mailbox.ps1 poll -Config legacy-mcp.config.json -Handlers examples/handlers.patch.ps1
+.\mailbox_wait_mcp.ps1   # → mailbox.ps1 wait -Config legacy-mcp.config.json
+```
+
+## 自测
+
+```powershell
+.\self-test.ps1   # 覆盖: 往返/广播/wait 唤醒/TTL/双实现互通/旧布局/去重
+```
+
+## 二期路线（未实现）
+
+- HTTP relay（跨机器，CLI 加 `transport` 开关）+ X25519 加密 / Ed25519 签名
+- 独立 npm/pwsh 包发布

package/skill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: mailbox
+description: 跨会话异步通信的文件信箱。通过共享文件系统在任意会话/agent 之间收发消息，支持 N 参与者、定向/广播、seen 去重、TTL 清理、事件唤醒。当需要与其他会话、后台 agent 或未来会话交换消息、任务结果或指示（而对方不一定在线）时使用。提供 pwsh 与 node 双实现的 CLI（send/recv/wait/poll/clean/status/init）。
+whenToUse: 需要跨会话/跨进程异步传递消息时，例如向另一个会话发起请求、等待对方响应、投递任务结果、广播通知；或需要把当前会话状态交接给后续会话。
+---
+
+# mailbox — 跨会话文件信箱
+
+基于文件系统的异步消息机制：**每个参与者各写各的信箱目录，互读对方的**。消息是文件，所以只要双方共享同一文件系统（同机或网络盘），就能在任意会话/进程/时间点通信，对方不在线也不丢消息。
+
+## 脚本位置
+
+- **本技能目录**（随技能打包，任何项目可用）：`$env:USERPROFILE\.dsh\skills\mailbox\`
+- **项目内开发副本**（如存在，优先用项目内的）：`<workspace>/tools/mailbox/`
+- 两个实现完全同协议，可互换混用：
+  - pwsh：`mailbox.ps1`（模块 `mailbox.psm1`）
+  - node：`mailbox.mjs`（零依赖）
+
+## 快速开始
+
+```powershell
+$mb = "$env:USERPROFILE\.dsh\skills\mailbox"   # 或项目内 tools/mailbox
+
+# 1. 初始化身份（同一 root 下每个参与者各初始化一次；root 需双方共享）
+& "$mb\mailbox.ps1" init -Id agent-a -Root D:/Downloads/Agent/.mailbox
+
+# 2. 发消息（to=all 广播 / to=<id> 定向）
+& "$mb\mailbox.ps1" send -To agent-b -Topic hello -Payload '{"x":1}'
+
+# 3. 收消息（一次性，自动更新 seen）
+& "$mb\mailbox.ps1" recv -Format table
+
+# 4. 事件唤醒：新消息到达即打印并 exit 0（后台 job 完成 → agent 被唤醒）
+& "$mb\mailbox.ps1" wait -Timeout 600
+```
+
+node 版命令一致：`node "$mb\mailbox.mjs" send --to agent-b --topic hello --payload '{"x":1}'`
+
+## 命令
+
+| 命令 | pwsh | node | 说明 |
+|---|---|---|---|
+| init | `init -Id <id> -Root <dir>` | `init --id <id> --root <dir>` | 生成配置 |
+| send | `send -To <id\|all> [-Type request\|response\|notify\|reply] [-Topic <t>] [-Payload <json>] [-ReplyTo <id>]` | `--to/--type/--topic/--payload/--reply-to` | 发消息 |
+| recv | `recv [-Format table\|json]` | `recv [--format ...]` | 读新消息（更新 seen） |
+| wait | `wait [-Timeout <sec>]` | `wait [--timeout <sec>]` | 新消息即 exit 0（唤醒） |
+| poll | `poll [-Interval <sec>] [-Handlers <ps1>]` | `poll [--interval <sec>] [--handlers <mjs>]` | 常驻轮询（request 自动回 response） |
+| clean | `clean [-TtlHours <n>] [-DryRun]` | `clean [--ttl-hours <n>] [--dry-run]` | TTL 清理自己发过的旧消息 |
+| status | `status` | `status` | 身份/目录/消息数 |
+
+## 配置
+
+默认读取工具同目录 `mailbox.config.json`，可用 `-Config` / `--config` 或环境变量 `MAILBOX_CONFIG` 指定。优先级：**CLI 参数 > 环境变量（`MAILBOX_ID`/`MAILBOX_ROOT`/`MAILBOX_CONFIG`/`MAILBOX_INTERVAL`/`MAILBOX_TIMEOUT`）> 配置文件 > 默认**。
+
+```json
+{ "identity": "agent-a", "layout": "root", "root": "D:/Downloads/Agent/.mailbox",
+  "participants": [], "intervalSec": 2, "timeoutSec": 0, "seenFile": "", "patchRoot": "" }
+```
+
+- `layout=root`（标准）：`<root>/<id>/` 每人一子目录；`participants` 留空自动扫描
+- `layout=dirs`（旧双目录兼容）：`dirs: { "<id>": "<目录>" }` 显式映射
+- `seenFile` 留空默认 `<outDir>/.seen.json`（每参与者独立去重）
+
+## 协议
+
+- 消息文件：`msg_<id>.json`，内容 `{ id, from, to, type, topic, payload, ts, reply_to }`
+- 路由：`to=<id>` 定向 / `to=all` 广播（写一份，各人自取）
+- 消息类型：`request` / `response` / `notify` / `reply`
+- **请求-响应模式**：发 `request` 带 `reply_to`，对方处理完回 `response` 指向原 id；`wait`/`recv` 可按 `reply_to` 关联
+- 已处理消息建议删除（`Remove-MailboxMsg` / 由 poll 自动清理），seen 文件兜底去重
+
+## 典型用法
+
+1. **跨会话交接**：完成任务后 `send -To <对方> -Type notify -Topic handoff_ready -Payload @{...}`，把上下文文件路径放进 payload
+2. **请求-响应**：`send -To rp -Type request -Topic patch_bug2 -Payload @{edits=...}` → 对方 poll 自动处理并回 `patch_result`
+3. **等待对方**：`wait -Timeout 600` 挂后台 job，新消息到达 job 完成即被唤醒（DSH 机制）
+4. **补丁自动应用**（示例）：`poll -Handlers examples/handlers.patch.ps1`（需配置 `patchRoot`），收到 `topic=patch_*` 消息自动备份→替换→node --check→回滚→回 response
+
+## 注意事项
+
+- 双方必须共享同一文件系统（同机目录或网络盘）；广域网需二期 HTTP relay（未实现）
+- `wait` 与 `poll` 共用 seen 文件，同一身份不要同时跑两个
+- 消息明文存储；需要保密时不要写入敏感 payload（二期支持加密）

package/skill/examples/handlers.patch.ps1

@@ -0,0 +1,154 @@
+# ============================================================================
+#  handlers.patch.ps1 — 示例 handler: 补丁自动应用
+#  (泛化自旧 mailbox_poll_mcp.ps1 的 Invoke-MailboxPatch)
+#
+#  用法:
+#    .\mailbox.ps1 poll -Handlers .\examples\handlers.patch.ps1
+#  要求:
+#    配置文件里 patchRoot 指向补丁目标工作区 (如 D:/work/myproject)
+#  协议 (对端发来的消息):
+#    { type:"request", topic:"patch_<任意>", payload:{
+#        patch_id:"<标识>", note:"<说明>",
+#        edits:[
+#          { file:"build/x.js", old:"...", new:"..." },              # 片段替换
+#          { file:"build/y.js", whole:"完整新内容" },                 # 整文件替换
+#          { file:"build/z.js", old:"...", new:"...", replace_all:true } # 全部替换
+#        ] } }
+#  行为: 备份 → 替换 → node --check 语法检查 → 失败回滚 →
+#        写 <patchRoot>/patches/history.jsonl → 回 response (topic: patch_result)
+#
+#  返回值: $true=已处理; $false=非补丁消息, 交给默认逻辑 (request→echo)
+# ============================================================================
+
+function Handle-Message {
+    param($Msg, $Ctx)
+
+    if ("$($Msg.topic)" -notlike "patch_*") { return $false }
+
+    $cfg = $Ctx.Cfg
+    $workRoot = [string]$cfg.patchRoot
+    if (-not $workRoot -or -not (Test-Path -LiteralPath $workRoot)) {
+        Write-Host "  [补丁] patchRoot 未配置或不存在, 跳过 (config.patchRoot=$workRoot)"
+        return $true
+    }
+
+    $payload = $Msg.payload
+    $patchId = if ($payload.patch_id) { [string]$payload.patch_id } else { [string]$Msg.id }
+    $edits = @($payload.edits)
+    $results = @()
+    $changed = @{}          # full path -> backup path
+    $ok = $true
+
+    New-Item -ItemType Directory -Force -Path (Join-Path $workRoot "patches") | Out-Null
+    $bakDir = Join-Path $workRoot "patches\backup"
+    New-Item -ItemType Directory -Force -Path $bakDir | Out-Null
+
+    Write-Host "`n[补丁应用] patch_id=$patchId edits=$($edits.Count) note=$($payload.note) root=$workRoot"
+
+    try {
+        foreach ($e in $edits) {
+            $rel = [string]$e.file
+            $full = Join-Path $workRoot $rel
+
+            # 路径安全: 必须落在 patchRoot 内
+            if (-not $full.StartsWith($workRoot, [System.StringComparison]::OrdinalIgnoreCase)) {
+                $results += "SKIP  $rel  (路径越界, 拒绝)"
+                $ok = $false
+                continue
+            }
+            if (-not (Test-Path -LiteralPath $full)) {
+                $results += "FAIL  $rel  (文件不存在)"
+                $ok = $false
+                continue
+            }
+
+            # 首次接触该文件时备份
+            if (-not $changed.ContainsKey($full)) {
+                $bak = Join-Path $bakDir ((Split-Path $rel -Leaf) + ".$patchId.bak")
+                Copy-Item -LiteralPath $full -Destination $bak -Force
+                $changed[$full] = $bak
+            }
+
+            $content = Get-Content -LiteralPath $full -Raw
+
+            if ($null -ne $e.whole -and [string]$e.whole -ne "") {
+                Set-Content -LiteralPath $full -Value ([string]$e.whole) -Encoding UTF8 -NoNewline
+                $results += "OK    $rel  (整文件替换)"
+                continue
+            }
+
+            $old = [string]$e.old
+            $new = [string]$e.new
+            if ($old -eq "") {
+                $results += "FAIL  $rel  (old 为空)"
+                $ok = $false
+                continue
+            }
+
+            $count = ([regex]::Matches($content, [regex]::Escape($old))).Count
+            if ($count -eq 0) {
+                $results += "FAIL  $rel  (old 片段未找到)"
+                $ok = $false
+                continue
+            }
+            if ($count -gt 1 -and -not $e.replace_all) {
+                $results += "FAIL  $rel  (old 出现 $count 次, 需 replace_all=true)"
+                $ok = $false
+                continue
+            }
+
+            if ($e.replace_all) {
+                $newContent = $content.Replace($old, $new)
+            } else {
+                $idx = $content.IndexOf($old, [System.StringComparison]::Ordinal)
+                $newContent = $content.Substring(0, $idx) + $new + $content.Substring($idx + $old.Length)
+            }
+            Set-Content -LiteralPath $full -Value $newContent -Encoding UTF8 -NoNewline
+            $results += "OK    $rel  (替换 x$count)"
+        }
+
+        # --- JS 语法检查 (node --check), 失败回滚 ---
+        if ($changed.Count -gt 0) {
+            $syntaxFail = $false
+            foreach ($full in @($changed.Keys)) {
+                if ($full -like "*.js") {
+                    $out = & node --check $full 2>&1
+                    if ($LASTEXITCODE -ne 0) {
+                        $syntaxFail = $true
+                        $results += "SYNTAX-FAIL $full : $out"
+                    }
+                }
+            }
+            if ($syntaxFail) {
+                foreach ($full in @($changed.Keys)) {
+                    Copy-Item -LiteralPath $changed[$full] -Destination $full -Force
+                    $results += "ROLLED-BACK $full"
+                }
+                $ok = $false
+            }
+        }
+    } catch {
+        $ok = $false
+        $results += "EXCEPTION: $($_.Exception.Message)"
+        foreach ($full in @($changed.Keys)) {
+            Copy-Item -LiteralPath $changed[$full] -Destination $full -Force
+            $results += "ROLLED-BACK $full"
+        }
+    }
+
+    # --- 历史记录 ---
+    $rec = [ordered]@{
+        ts = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+        patch_id = $patchId; from = $Msg.from; ok = $ok
+        edits = $edits.Count; results = $results
+    }
+    ($rec | ConvertTo-Json -Depth 5) | Add-Content (Join-Path $workRoot "patches\history.jsonl") -Encoding UTF8
+
+    # --- 回 response ---
+    Send-Mailbox -Cfg $cfg -To $Msg.from -Type "response" -Topic "patch_result" `
+        -ReplyTo $Msg.id -Payload @{ patch_id = $patchId; ok = $ok; results = $results }
+
+    $results | ForEach-Object { Write-Host "  $_" }
+    Write-Host "  → 补丁结果: $(if ($ok) {'成功'} else {'失败(已回滚)'}) (response 已回 $($Msg.from))"
+    return $true
+}

package/skill/legacy-mcp.config.json

@@ -0,0 +1,14 @@
+{
+  "identity": "mcp",
+  "layout": "dirs",
+  "root": "",
+  "dirs": {
+    "mcp": "D:/Downloads/Agent/Soc/tools/mcp-serial/mailbox",
+    "rp": "D:/Downloads/Agent/RP/tools/mailbox"
+  },
+  "participants": [],
+  "intervalSec": 2,
+  "timeoutSec": 0,
+  "seenFile": "D:/Downloads/Agent/Soc/tools/mcp-serial/tools/.seen_mcp.json",
+  "patchRoot": "D:/Downloads/Agent/Soc/tools/mcp-serial"
+}

package/skill/mailbox.config.json

@@ -0,0 +1,11 @@
+{
+  "identity": "agent-a",
+  "layout": "root",
+  "root": "D:/Downloads/Agent/.mailbox",
+  "dirs": {},
+  "participants": [],
+  "intervalSec": 2,
+  "timeoutSec": 0,
+  "seenFile": "",
+  "patchRoot": ""
+}