@yuanchilin/dsh-mailbox 0.0.1

package/lib/index.js

@@ -0,0 +1,319 @@
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — DeepSeek Harness cordis 插件
+//
+//  注册 6 个模型面向工具 + 1 个宿主命令:
+//    mailbox_send     发送消息 (to=identity / 别名 / sessionId / all)
+//    mailbox_recv     读取新消息 (自动 seen 去重)
+//    mailbox_status   身份/目录/消息数 + 会话目录与在线状态
+//    mailbox_sessions 会话目录: 找"要对话的会话" (身份/别名/在线/未读)
+//    mailbox_alias    给本会话设置唯一别名 (便于他人定向发送)
+//    mailbox_clean    按 TTL 清理自己发过的旧消息
+//    /mailbox         宿主命令: /mailbox <目标|别名|all> <消息> (聊天框直发)
+//
+//  身份模型 (v1.1):
+//    - 默认按 <工作区名>-<会话短id> 自动派生, 同一工作区多个会话互不冲突,
+//      工具执行时从 exec.agent.session 取 id / header.cwd / 标题。
+//    - 显式 config.identity 仍是最高优先级 (固定身份 / 旧配置兼容)。
+//    - 每次工具调用写注册表心跳 (<root>/_sessions/<sessionId>.json),
+//      供 mailbox_sessions / status 展示在线状态与未读数。
+//
+//  配置 (cordis.patch.yml 的 mailbox 行 config, 或 profile patch 覆盖):
+//    identity(可选,留空自动), root(必填,共享目录), layout(root|dirs),
+//    dirs, participants, intervalSec, timeoutSec, seenFile, patchRoot,
+//    presenceWindowSec(在线判定窗口,默认 300)
+//
+//  长驻场景 (mailbox_wait 事件唤醒 / mailbox_poll 常驻轮询) 不适合做成工具,
+//  请用包内 CLI: npx mailbox wait|poll (或 pwsh 版 mailbox.ps1), CLI 会写心跳。
+// ============================================================================
+
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import * as core from "./core.js";
+import { registerMailboxCommand } from "./command.js";
+import { startMailboxWatcher } from "./watcher.js";
+
+const name = "mailbox";
+const inject = ["tools", "commands"];
+
+/** schemastery 配置模式 (全部带默认值, 激活零配置; 收发前需配置 root) */
+const Config = z.object({
+  identity: z.string().default(""),
+  layout: z.string().default("root"),
+  root: z.string().default(""),
+  dirs: z.dict(z.string()).default({}),
+  participants: z.array(z.string()).default([]),
+  intervalSec: z.number().default(2),
+  timeoutSec: z.number().default(0),
+  seenFile: z.string().default(""),
+  patchRoot: z.string().default(""),
+  presenceWindowSec: z.number().default(300),
+  watcher: z.boolean().default(true),
+});
+
+const text = (s) => [{ type: "text", text: s }];
+
+/** 会话上下文: 每个工具调用都先解析身份 + 写心跳, 然后带着有效身份执行。 */
+function withSession(cfg, exec, fn) {
+  const session = exec?.agent?.session;
+  const eff = core.effectiveConfig(cfg, session);
+  core.touchRegistry(cfg, session);
+  return fn(eff, session);
+}
+
+function apply(ctx, config) {
+  const cfg = core.resolveConfig(config ?? {});
+
+  // 宿主命令: /mailbox <目标|别名|all> <消息> (聊天输入框直接使用)
+  registerMailboxCommand(ctx, cfg);
+
+  // 内建 watcher: 新消息 → 为对应会话 agent 创建完成 job → DSH 唤醒。
+  // 随插件启动, dsh 重启自动复活 (根治 CLI wait job 重启即死的痛点)。
+  startMailboxWatcher(ctx, cfg);
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_send",
+    description: "通过共享文件系统信箱向其他会话/agent 发送一条异步消息。to=参与者 identity / 别名 / 完整 sessionId 定向发送，或 all 广播；消息类型 request/response/notify/reply；对方不在线也不丢消息（对方之后 recv 或 CLI wait/poll 即可收到）。可用 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" },
+      topic: { type: "string", description: "消息主题，用于路由/归类（如 hello、patch_xxx）" },
+      payload: { type: "object", additionalProperties: true, description: "任意 JSON 负载" },
+      replyTo: { type: "string", description: "应答目标消息 id（请求-响应模式）" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          ok: { type: "boolean", required: true },
+          id: { type: "string", required: true },
+          from: { type: "string", required: true },
+          to: { type: "string", required: true },
+          toAlias: { type: "string" },
+          targetOnline: { oneOf: [{ type: "boolean" }, { type: "null" }] },
+          sessionsHint: { type: "string" },
+        },
+      },
+      render: (_args, value) => {
+        const alias = value.toAlias ? ` (alias=${value.toAlias})` : "";
+        const online = value.targetOnline === null ? "" : value.targetOnline ? " 目标在线" : " 目标离线";
+        const hint = value.sessionsHint ? `\n\n${value.sessionsHint}` : "";
+        return text(`已发送 ${value.id}  (${value.from} → ${value.to}${alias})${online}${hint}`);
+      },
+    },
+    execute: async (args, exec) => withSession(cfg, exec, (eff) => {
+      const target = core.resolveTarget(eff, args.to);
+      const id = core.sendMessage(eff, {
+        to: args.to,
+        type: args.type ?? "notify",
+        topic: args.topic ?? "",
+        payload: args.payload ?? {},
+        replyTo: args.replyTo ?? "",
+      });
+      const rec = core.listSessions(eff).find((s) => s.identity === target);
+      const known = core.isKnownTarget(eff, target);
+      return {
+        ok: true,
+        id,
+        from: eff.identity,
+        to: target,
+        toAlias: args.to !== target ? args.to : "",
+        targetOnline: rec ? core.isOnline(rec, eff.presenceWindowSec) : null,
+        sessionsHint: known ? "" : core.unknownTargetHint(eff, target),
+      };
+    }),
+    presentCall: (args) => ({
+      card: "generic",
+      title: `mailbox → ${args.to}`,
+      kind: "other",
+      rawInput: args,
+    }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_recv",
+    description: "读取信箱中发给本会话的新消息（自动记录 seen，重复调用不会重复返回）。返回消息列表：from/to/type/topic/payload/reply_to。无新消息时返回空列表。长驻等待请用 CLI：npx mailbox wait。",
+    parameters: {
+      format: { type: "string", enum: ["table", "json"], description: "输出格式，默认 table" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          count: { type: "integer", required: true },
+          messages: {
+            type: "array",
+            required: true,
+            items: {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                id: { type: "string" },
+                from: { type: "string" },
+                to: { type: "string" },
+                type: { type: "string" },
+                topic: { type: "string" },
+                ts: { type: "integer" },
+                reply_to: { type: "string" },
+                payload: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        if (value.count === 0) return text("(无新消息)");
+        const lines = value.messages.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 text(`新消息 ${value.count} 条:\n${lines.join("\n")}`);
+      },
+    },
+    execute: async (args, exec) => withSession(cfg, exec, (eff) => {
+      const messages = core.recvNew(eff, true);
+      return { count: messages.length, messages };
+    }),
+    presentCall: () => ({ card: "generic", title: "mailbox recv", kind: "other" }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_status",
+    description: "查看信箱配置与状态：本会话身份、写入目录、已发送消息数、seen 记录数、各对方信箱的消息数与未读，以及会话目录（各已注册会话的身份/别名/在线状态）。用于确认信箱是否配置好、对方是否在线。",
+    parameters: {},
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          identity: { type: "string" },
+          layout: { type: "string" },
+          outDir: { type: "string" },
+          outCount: { type: "integer" },
+          seen: { type: "integer" },
+          inboxes: { type: "array", items: { type: "object", additionalProperties: true } },
+          sessions: { type: "array", items: { type: "object", additionalProperties: true } },
+        },
+      },
+      render: (_args, value) => {
+        const lines = [
+          `身份: ${value.identity}  layout=${value.layout}`,
+          `写:   ${value.outDir}  (消息 ${value.outCount})`,
+          `seen: ${value.seen} 条`,
+          ...value.inboxes.map((i) => `读:   ${i.name || i.dir}  (消息 ${i.msgCount}, 未读 ${i.unread ?? 0})`),
+        ];
+        const sessions = value.sessions || [];
+        if (sessions.length > 0) {
+          lines.push("会话目录:");
+          for (const s of sessions) {
+            const on = s.online ? "●在线" : "○离线";
+            lines.push(`  ${on} ${s.identity}${s.alias ? ` (${s.alias})` : ""}  ${s.workspace || "?"}${s.title ? `  «${s.title}»` : ""}${s.unread ? `  未读${s.unread}` : ""}`);
+          }
+        } else {
+          lines.push("会话目录: (暂无注册会话, 各会话调用一次 mailbox 工具即登记)");
+        }
+        return text(lines.join("\n"));
+      },
+    },
+    execute: async (_args, exec) => withSession(cfg, exec, (eff) => core.statusOf(eff)),
+    presentCall: () => ({ card: "generic", title: "mailbox status", kind: "other" }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_sessions",
+    description: "会话目录：列出所有已注册会话（identity/别名/工作区/标题/在线状态/发给我未读条数），按最近活跃排序。用于快速找到要对话的会话：先看目录确定对方的 identity 或别名，再 mailbox_send 定向发送。",
+    parameters: {},
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          count: { type: "integer", required: true },
+          sessions: {
+            type: "array",
+            required: true,
+            items: { type: "object", additionalProperties: true },
+          },
+        },
+      },
+      render: (_args, value) => {
+        if (value.count === 0) return text("(暂无注册会话: 各会话调用一次 mailbox 工具即自动登记)");
+        const lines = value.sessions.map((s) => {
+          const on = s.online ? "●在线" : "○离线";
+          return `${on} ${s.identity}${s.alias ? ` (alias=${s.alias})` : ""}  ${s.workspace || "?"}${s.title ? `  «${s.title}»` : ""}${s.unread ? `  发给我的未读:${s.unread}` : ""}`;
+        });
+        return text(`会话 ${value.count} 个:\n${lines.join("\n")}`);
+      },
+    },
+    execute: async (_args, exec) => withSession(cfg, exec, (eff) => {
+      const sessions = core.listSessions(eff).map((s) => ({
+        ...s,
+        online: core.isOnline(s, eff.presenceWindowSec),
+        unread: core.unreadFrom(eff, s.identity),
+      }));
+      return { count: sessions.length, sessions };
+    }),
+    presentCall: () => ({ card: "generic", title: "mailbox sessions", kind: "other" }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_alias",
+    description: "给本会话设置一个简短唯一别名（全库检查，已被其他会话占用会拒绝），便于其他会话用 alias 定向发消息，而不是记长 identity。alias 仅允许字母数字 . _ -（≤32 字符）。",
+    parameters: {
+      alias: { type: "string", required: true, description: "别名，例如 rp / mcp / builder（全库唯一）" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          alias: { type: "string", required: true },
+          identity: { type: "string", required: true },
+        },
+      },
+      render: (_args, value) => text(`别名已设置: ${value.identity} → "${value.alias}"`),
+    },
+    execute: async (args, exec) => withSession(cfg, exec, (eff, session) => {
+      const rec = core.setAlias(eff, session, args.alias);
+      return { alias: rec.alias, identity: rec.identity };
+    }),
+    presentCall: (args) => ({
+      card: "generic",
+      title: `mailbox alias → ${args.alias}`,
+      kind: "other",
+      rawInput: args,
+    }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "mailbox_clean",
+    description: "按 TTL 清理本会话自己发过的旧消息（对方应已读过）。dryRun 只统计不删除。",
+    parameters: {
+      ttlHours: { type: "integer", description: "保留时长（小时），默认 24" },
+      dryRun: { type: "boolean", description: "只统计不删除，默认 false" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          removed: { type: "integer", required: true },
+          dryRun: { type: "boolean", required: true },
+        },
+      },
+      render: (_args, value) =>
+        text(`clean: ${value.dryRun ? "dry-run" : "已删除"} ${value.removed} 条过期消息`),
+    },
+    execute: async (args, exec) => withSession(cfg, exec, (eff) => {
+      const removed = core.cleanTTL(eff, {
+        ttlHours: args.ttlHours ?? 24,
+        dryRun: args.dryRun ?? false,
+      });
+      return { removed, dryRun: args.dryRun ?? false };
+    }),
+    presentCall: () => ({ card: "generic", title: "mailbox clean", kind: "other" }),
+  }));
+}
+
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,123 @@
+// 最小类型声明 (core / command / watcher / directory-parse 导出的形状)
+export interface MailboxConfig {
+  identity: string;
+  layout: "root" | "dirs";
+  root: string;
+  dirs: Record<string, string>;
+  participants: string[];
+  intervalSec: number;
+  timeoutSec: number;
+  seenFile: string;
+  patchRoot: string;
+  presenceWindowSec: number;
+  watcher: boolean;
+}
+
+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 MailboxInbox {
+  dir: string;
+  name: string;
+  msgCount: number;
+  unread: number;
+}
+
+export interface MailboxSession {
+  sessionId: string;
+  identity: string;
+  alias: string;
+  workspace: string;
+  title: string;
+  firstSeen: number;
+  lastSeen: number;
+  online?: boolean;
+  unread?: number;
+}
+
+export interface MailboxStatus {
+  identity: string;
+  layout: string;
+  outDir: string;
+  outCount: number;
+  seen: number;
+  inboxes: MailboxInbox[];
+  sessions: MailboxSession[];
+}
+
+/** DSH Session 对象的最小形状 (工具执行时 exec.agent.session)。 */
+export interface DshSessionLike {
+  id: string;
+  header?: { cwd?: string };
+  events?: Array<{ type?: string; data?: { title?: string } }>;
+}
+
+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;
+
+// ---- 会话身份 + 注册表 ----
+export function sessionCtx(session?: DshSessionLike | null): { sessionId: string; workspace: string; title: string } | undefined;
+export function deriveIdentity(ctx?: { sessionId: string; workspace: string; title: string }): string;
+export function effectiveIdentity(cfg: MailboxConfig, session?: DshSessionLike | null): string;
+export function effectiveConfig(cfg: MailboxConfig, session?: DshSessionLike | null): MailboxConfig;
+export function registryDir(cfg: MailboxConfig): string;
+export function touchRegistry(cfg: MailboxConfig, session?: DshSessionLike | null, opts?: { alias?: string }): MailboxSession | undefined;
+export function touchRegistryCli(cfg: MailboxConfig, opts?: { workspace?: string }): MailboxSession | undefined;
+export function listSessions(cfg: MailboxConfig): MailboxSession[];
+export function isOnline(rec?: MailboxSession | null, windowSec?: number): boolean;
+export function setAlias(cfg: MailboxConfig, session: DshSessionLike, alias: string): MailboxSession;
+export function resolveTarget(cfg: MailboxConfig, to: string): string;
+export function isKnownTarget(cfg: MailboxConfig, target: string): boolean;
+export function sessionDirectoryText(cfg: MailboxConfig): string;
+export function unknownTargetHint(cfg: MailboxConfig, target: string): string;
+export function unreadInDir(cfg: MailboxConfig, dir: string): number;
+export function unreadFrom(cfg: MailboxConfig, identity: string): number;
+
+// ---- 宿主 /mailbox 命令 ----
+export interface MailboxCommandResult {
+  kind: "success" | "error";
+  text: string;
+}
+export interface MailboxInvocation {
+  agent?: { session?: DshSessionLike };
+  rawInput: string;
+}
+export const MAILBOX_USAGE: string;
+export function parseMailboxCommand(rawInput: string):
+  | { kind: "usage" }
+  | { kind: "list" }
+  | { kind: "recv" }
+  | { kind: "no-message"; to: string }
+  | { kind: "send"; to: string; message: string };
+export function renderDirectory(cfg: MailboxConfig): string;
+export function executeMailboxCommand(ctx: unknown, cfg: MailboxConfig, invocation: MailboxInvocation): MailboxCommandResult;
+export function registerMailboxCommand(ctx: { commands: { register(definition: unknown): unknown } }, cfg: MailboxConfig): void;
+
+// ---- 内建 watcher ----
+export function scanMailboxRoot(root: string, known: Set<string>, live: Map<string, unknown>): Map<string, MailboxMessage[]>;
+export function startMailboxWatcher(ctx: unknown, cfg: MailboxConfig): (() => void) | undefined;
+
+// ---- 目录文本解析 (客户端补全) ----
+export interface DirectoryOption {
+  id: string;
+  label: string;
+  detail: string;
+}
+export function parseDirectory(text: string): DirectoryOption[];

package/lib/watcher.js

@@ -0,0 +1,129 @@
+// ============================================================================
+//  @yuanchilin/dsh-mailbox — 插件内建 watcher (根治"重启杀监听")
+//
+//  背景: 用 CLI `wait` 挂后台 job 的监听属于会话进程, dsh 一重启就死。
+//  方案: 监听做进插件本身 —— 插件每次启动 apply() 都会自动重启 watcher,
+//        不依赖会话进程。轮询 <root>/ 各参与者目录, 发现发给"在线会话身份"
+//        的新消息, 为该会话的 agent 创建一个立即完成的后台 job —— DSH 的
+//        后台 job 完成通知会唤醒该 agent (与 CLI wait 完成唤醒同机制)。
+//
+//  去重: 收件人 seen 文件里已有的消息不重复唤醒 (已处理不打扰);
+//        本进程内 known 集合保证同一文件只唤醒一次。
+//
+//  安全: jobs/agents 服务缺失时静默降级 (不影响其他 profile 启动);
+//        任何轮询异常吞掉下轮重试, 绝不抛向启动流程。
+// ============================================================================
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import * as core from "./core.js";
+
+/**
+ * 纯检测逻辑: 扫描 root 下参与者目录 (跳过 _/. 前缀), 找出 live 身份未 seen
+ * 的新消息。known (Set<绝对路径>) 就地更新; 返回 Map<identity, msg[]>。
+ */
+export function scanMailboxRoot(root, known, live) {
+  const fresh = new Map();
+  if (!existsSync(root)) return fresh;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    const dirPath = join(root, entry.name);
+    let files;
+    try {
+      files = readdirSync(dirPath);
+    } catch {
+      continue;
+    }
+    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; // 损坏消息跳过
+      }
+      for (const identity of live.keys()) {
+        if (m.to !== identity && m.to !== "all") continue;
+        // 自收消息 (from=自己): recv 只扫别人目录, 永远读不到 → 不唤醒 (否则每次重启重复响铃)
+        if (m.from === identity) continue;
+        // 收件人已处理 (seen 含该 id) 则不重复唤醒
+        const seenPath = join(root, identity, ".seen.json");
+        if (existsSync(seenPath)) {
+          try {
+            const v = JSON.parse(readFileSync(seenPath, "utf-8"));
+            const seen = Array.isArray(v) ? v : [v];
+            if (seen.includes(m.id)) continue;
+          } catch {
+            // seen 损坏则视为未处理, 照常唤醒
+          }
+        }
+        if (!fresh.has(identity)) fresh.set(identity, []);
+        fresh.get(identity).push(m);
+      }
+    }
+  }
+  return fresh;
+}
+
+/**
+ * 启动内建 watcher。返回停止函数 (或 undefined = 未启用/环境不支持)。
+ * jobs/agents 为惰性获取: 缺失即静默不启用 (web 面两者都存在)。
+ */
+export function startMailboxWatcher(ctx, cfg) {
+  if (cfg.watcher === false || cfg.layout !== "root" || !cfg.root) return undefined;
+  const jobs = ctx.get("jobs");
+  const agents = ctx.get("agents");
+  if (!jobs || typeof jobs.start !== "function") return undefined;
+  if (!agents || typeof agents.list !== "function") return undefined;
+
+  const known = new Set();
+
+  const tick = () => {
+    try {
+      const live = new Map(); // identity → agent
+      for (const agent of agents.list()) {
+        try {
+          const identity = core.effectiveIdentity(cfg, agent.session);
+          if (identity) live.set(identity, agent);
+        } catch {
+          // 该 agent 无会话/身份, 跳过
+        }
+      }
+      if (live.size === 0) return;
+      const fresh = scanMailboxRoot(cfg.root, known, live);
+      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 读取处理。`,
+                }),
+              }),
+            });
+          } catch {
+            // 单个唤醒失败不影响其他 (如 kind 不被 jobs 实现接受)
+          }
+        }
+      }
+    } catch {
+      // 轮询异常静默, 下轮重试
+    }
+  };
+
+  tick(); // 启动即扫一遍 (重启后立刻发现遗留未读)
+  const handle = setInterval(tick, (cfg.intervalSec || 2) * 1000);
+  const stop = () => clearInterval(handle);
+  if (typeof ctx.effect === "function") ctx.effect(() => stop);
+  return stop;
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@yuanchilin/dsh-mailbox",
+  "version": "0.0.1",
+  "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",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mailbox": "bin/mailbox.mjs"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/core.js",
+    "lib/command.js",
+    "lib/watcher.js",
+    "lib/directory-parse.js",
+    "lib/client.js",
+    "lib/types/index.d.ts",
+    "bin/",
+    "cordis.patch.yml",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "watch:client": "tsdown --watch",
+    "test": "node --test --test-isolation=none \"test/*.test.js\""
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "mailbox",
+    "cross-session",
+    "messaging",
+    "plugin",
+    "client"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-commands",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  },
+  "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": ">=22.0.0"
+  }
+}