pi-proactive 0.2.0-beta.2 → 0.2.0-beta.3

package/build/src/daemon.js

@@ -25,12 +25,26 @@ import fs from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { proactiveDir, resolveAgentDir } from "./config.js";
+// G12 四件套（**主动联系**能力 —— 代码侧声明）：
+// @capability: daemon-contact
+// @observable: pi-proactive/src/daemon.ts:writeHeartbeat
+// @attribution: pi-proactive/src/daemon-contact.ts:decideContact
+// @outcome: pi-proactive/src/daemon-config.ts:appendContactEntry
+// @checked: test:pi-proactive/tests/daemon-contact.test.ts#目标判定
+import { proactiveDir, resolveAgentDir, ensureDir, writeAtomicFile } from "./config.js";
 import { Scheduler } from "./scheduler.js";
 import { TaskStore } from "./task-store.js";
 import { Lineage } from "./lineage.js";
-import { buildHandoverSummary, classifyAction, dayKey, estimateTokenUnits, loadDaemonConfig, loadDaemonState, MAX_ACTION_LOG, saveDaemonState, writeHandoverSummary, } from "./daemon-config.js";
+import { appendContactAudit, appendContactEntry, buildHandoverSummary, classifyAction, dayKey, estimateTokenUnits, heartbeatPath, loadDaemonConfig, loadDaemonState, MAX_ACTION_LOG, formatContactList, readContactEntries, saveDaemonState, writeHandoverSummary, } from "./daemon-config.js";
+import { decideContact } from "./daemon-contact.js";
+import { detectHost } from "./daemon-host.js";
+import { buildContactPayload, selectNotifyChannels } from "./notify.js";
+import { Registry } from "./registry.js";
+import { createEnvelope } from "./envelope.js";
+import { deliverCrossProcess } from "./socket.js";
 const HOUR_MS = 3_600_000;
+/** 心跳间隔（ms）：外部验证「它还活着」的刷新周期。 */
+const HEARTBEAT_INTERVAL_MS = 5_000;
 /** 动作标题的最大长度（截断后的标题进流水与交班摘要）。 */
 const MAX_TITLE_LEN = 60;
 /** 创建干跑执行器。 */
@@ -71,9 +85,15 @@ export class Daemon {
     scheduler;
     state;
     timer;
+    /** 心跳定时器（独立于 tick 周期 → 「它还活着」的证据始终新鲜）。 */
+    heartbeatTimer;
     lastSweepAt = 0;
     lastHandoverDay = "";
     stopped = false;
+    /** 常驻宿主（herdr / launchd / systemd）—— 写进心跳，外部可查。 */
+    hostKind;
+    /** 设备通知通道（注入点；缺省 → 自动挑）。 */
+    notifyChannels;
     constructor(opts) {
         this.agentId = opts.config.agentId;
         this.agentDir = opts.agentDir;
@@ -85,6 +105,8 @@ export class Daemon {
         this.lineage =
             opts.lineage ?? new Lineage({ agentDir: this.agentDir, agentId: this.agentId, now: this.now });
         this.state = loadDaemonState(this.agentDir, this.now());
+        this.hostKind = opts.hostKind ?? detectHost().hostKind;
+        this.notifyChannels = opts.notifyChannels;
         this.scheduler = new Scheduler({
             store: this.store,
             trigger: { deliverToModel: (msg, intent, o) => this.handleDelivery(msg, intent, o) },
@@ -112,6 +134,14 @@ export class Daemon {
         this.timer = setInterval(() => {
             void this.tick();
         }, this.config.tickIntervalMs);
+        // 心跳独立于 tick（tick 可能 30 秒一次 → 外部验证「还活着」不该等那么久）。
+        this.heartbeatTimer = setInterval(() => {
+            this.writeHeartbeat();
+        }, HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer.unref?.();
+        // 立刻写一次心跳：**监督器靠心跳判活**（等 5s 才有心跳 → 接管会慢 5s；更糟的是
+        // 两个监督器可能同时判定「没有心跳」→ 双开值班进程）。
+        this.writeHeartbeat();
         this.log(`值班循环已启动（agent=${this.agentId} · tick=${this.config.tickIntervalMs}ms · enabled=${this.config.enabled} · dryRun=${this.config.dryRun}）`);
     }
     /** 停值班循环（幂等）：停循环 → 写交班摘要 → 落盘。 */
@@ -120,6 +150,10 @@ export class Daemon {
             clearInterval(this.timer);
             this.timer = undefined;
         }
+        if (this.heartbeatTimer !== undefined) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
         this.scheduler.stop();
         if (this.stopped)
             return;
@@ -145,6 +179,148 @@ export class Daemon {
         catch (err) {
             this.log(`维护失败（已隔离）：${errText(err)}`);
         }
+        // 心跳（**外部可验证「它还活着」**：文件里的 ts 随 tick 前进）。
+        this.writeHeartbeat(now);
+        // 主动联系（7×24 助理的硬需求：它**主动找我**）。
+        try {
+            await this.maybeContact(now);
+        }
+        catch (err) {
+            this.log(`主动联系失败（已隔离）：${errText(err)}`);
+        }
+    }
+    /**
+     * 写心跳文件（`<agentDir>/proactive/daemon/heartbeat.json`）。
+     *
+     * 为什么单独一个文件：安装脚本要**外部可验证**「它真的起来了」——
+     * 进程在 + 心跳在更新 + 单元已加载，三条证据缺一不可。
+     */
+    writeHeartbeat(now = this.now()) {
+        const file = heartbeatPath(this.agentDir);
+        const body = {
+            ts: now,
+            pid: process.pid,
+            agentId: this.agentId,
+            host: this.hostKind,
+            runMode: this.config.dryRun ? "dry-run" : "live",
+            enabled: this.config.enabled,
+            contactEnabled: this.config.contact.enabled,
+        };
+        try {
+            ensureDir(path.dirname(file));
+            writeAtomicFile(file, `${JSON.stringify(body, null, 2)}\n`, { durable: true });
+        }
+        catch {
+            // 心跳写失败不影响值班（它只是可观测证据，不是业务数据）
+        }
+        return file;
+    }
+    /**
+     * 主动联系（**它主动找我**）。
+     *
+     * 顺序固定：总开关 → 预算硬上限 → 决策（目标 / 频次 / 每日上限）→ 会话投递 →
+     * 设备级通知（去重策略）→ 记账 → 落清单。
+     *
+     * 不变量：**只联系已登记会话**；找不到目标 → **不联系**（只留可查记录）。
+     */
+    async maybeContact(now = this.now()) {
+        if (!this.config.enabled)
+            return;
+        const cfg = this.config.contact;
+        if (!cfg.enabled)
+            return;
+        const budget = this.budgetStatus(now);
+        if (budget.exhausted) {
+            this.log(`主动联系被预算挡住：${budget.reason}`);
+            return;
+        }
+        const registry = new Registry({ agentDir: this.agentDir, now: this.now });
+        const decision = decideContact({
+            config: cfg,
+            entries: registry.listAll(),
+            recent: readContactEntries(this.agentDir),
+            now,
+            selfAgentId: this.agentId,
+        });
+        if (decision.action !== "contact" || decision.target === undefined) {
+            // **可查记录**：不联系也要留下「为什么没联系」（用户能查）。
+            appendContactAudit(this.agentDir, { ts: now, reason: decision.reason });
+            this.log(`主动联系跳过：${decision.reason}`);
+            return;
+        }
+        const target = decision.target;
+        const eventId = decision.eventId ?? `c-${now}-${target.agentId}`;
+        const payload = buildContactPayload({ ...cfg.payload, why: this.contactWhy() });
+        const channels = [];
+        // ① 会话投递（**只投给已登记会话**）。
+        let sessionStatus = "failed";
+        try {
+            const envelope = createEnvelope({
+                from: this.agentId,
+                to: target.agentId,
+                kind: "notify",
+                intent: "notify",
+                body: payload.body ?? "",
+                subject: payload.title,
+            });
+            const ack = await deliverCrossProcess({
+                targetAgentId: target.agentId,
+                envelope,
+                agentDir: this.agentDir,
+            });
+            sessionStatus = ack.status;
+            if (ack.status === "accepted" || ack.status === "duplicate")
+                channels.push("session");
+        }
+        catch (err) {
+            sessionStatus = `error: ${errText(err)}`;
+        }
+        // ② 设备级通知（`fallback` = 会话没送达才发 → **双通道去重**，用户不被打扰两次）。
+        if (cfg.deviceNotify === "always" || !channels.includes("session")) {
+            const deviceChannels = this.notifyChannels ?? selectNotifyChannels({ channels: ["herdr", "osx", "linux"] });
+            for (const channel of deviceChannels) {
+                const res = await channel.send(payload);
+                if (res.ok) {
+                    channels.push("device");
+                    break;
+                }
+            }
+        }
+        // ③ 记账（**联系也算一次动作** → 预算硬上限不被绕过）。
+        this.countAction("limited", payload.body ?? "", channels.includes("session") ? "delivered" : "notified");
+        this.pushAction({
+            ts: now,
+            title: `主动联系 ${target.agentId}`,
+            tier: "limited",
+            outcome: channels.length > 0 ? "executed" : "failed",
+            reason: `${decision.reason} · 通道=${channels.join("+") || "无"} · 会话投递=${sessionStatus}`,
+            tokenUnits: 0,
+        });
+        // ④ 落清单（**同一事件只一条**：两条通道用同一个 eventId）。
+        appendContactEntry(this.agentDir, {
+            eventId,
+            ts: now,
+            outcome: channels.includes("session")
+                ? channels.includes("device")
+                    ? "both"
+                    : "session"
+                : channels.includes("device")
+                    ? "device"
+                    : "failed",
+            channels,
+            targetAgentId: target.agentId,
+            payload,
+            reason: `会话投递=${sessionStatus}`,
+        });
+        this.saveState();
+        this.log(`已主动联系 ${target.agentId}（通道：${channels.join("+") || "无"}）`);
+    }
+    /** 「为什么找你」的现实理由（有排队动作就说实话；否则用配置里的模板）。 */
+    contactWhy() {
+        const queued = this.state.queue.length;
+        if (queued > 0)
+            return `有 ${queued} 个动作在等你确认`;
+        return this.config.contact.payload.why;
     }
     /**
      * 崩溃恢复（**幂等**）：死 socket、过期任务认领、半成品执行、临时文件。
@@ -657,6 +833,8 @@ if (isMainModule()) {
     let once = false;
     let handoverOnly = false;
     let enable = false;
+    let contactOnce = false;
+    let listContacts = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--agent-dir") {
@@ -669,6 +847,10 @@ if (isMainModule()) {
             handoverOnly = true;
         else if (arg === "--enable")
             enable = true;
+        else if (arg === "--contact-once")
+            contactOnce = true;
+        else if (arg === "--list-contacts")
+            listContacts = true;
     }
     if (!agentDir)
         agentDir = resolveAgentDir();
@@ -684,7 +866,15 @@ if (isMainModule()) {
         config,
         executor: createDryRunExecutor(),
     });
-    if (handoverOnly) {
+    if (listContacts) {
+        console.log(formatContactList(readContactEntries(agentDir)));
+    }
+    else if (contactOnce) {
+        // 主动联系一次（**手动触发**；决策与投递路径与值班循环完全一致）。
+        await daemon.maybeContact();
+        console.log(`联系记录：\n${formatContactList(readContactEntries(agentDir))}`);
+    }
+    else if (handoverOnly) {
         console.log(daemon.writeHandover());
     }
     else if (once) {

package/build/src/health.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultConfig, proactiveDir } from "./config.js";
+import { ContentStore } from "./content.js";
 import { OFFLINE_ENTRY_MIN_RETENTION_MS, OFFLINE_HEARTBEAT_FACTOR, } from "./registry.js";
 import { socketPathFor } from "./socket.js";
 import { readLatestHandover } from "./daemon-config.js";
@@ -338,6 +339,68 @@ function readConfig(configFile) {
     }
     return sample;
 }
+/**
+ * 外置内容引用采样（只读）—— CFG1：`promptRef` / `agentRef` 的引用数与悬空数。
+ *
+ * 口径与**运行期同一把尺子**：复用 `content.ts` 的 `ContentStore.resolveEntry()`
+ * → 悬空 / 空文件 / 格式错 / 越界路径的判定与 `loadConfig()` 完全一致（不在这里重写一套规则）。
+ *
+ * 「内联优先」（规范 §4）：同层仍有内联 `prompt` 时，`promptRef` **不生效** →
+ * 运行期不会因它失败 → 计入 `shadowed`（不计入悬空），避免体检报一个假故障。
+ */
+function readExternalContent(root) {
+    const out = { refs: 0, dangling: 0, shadowed: 0, issues: [] };
+    const raw = readJsonSafe(path.join(root, "config.json"));
+    if (!isPlainObject(raw))
+        return out;
+    const refs = [];
+    const idleTrigger = isPlainObject(raw.idleTrigger) ? raw.idleTrigger : {};
+    if (typeof idleTrigger.promptRef === "string" && idleTrigger.promptRef.trim() !== "") {
+        const inline = typeof idleTrigger.prompt === "string" ? idleTrigger.prompt : "";
+        refs.push({
+            category: "prompts",
+            ref: idleTrigger.promptRef.trim(),
+            where: "idleTrigger.promptRef",
+            shadowed: inline !== "",
+        });
+    }
+    const contentRefs = isPlainObject(raw.contentRefs) ? raw.contentRefs : {};
+    for (const [name, value] of Object.entries(contentRefs)) {
+        if (!isPlainObject(value))
+            continue;
+        if (typeof value.promptRef === "string" && value.promptRef.trim() !== "") {
+            refs.push({
+                category: "prompts",
+                ref: value.promptRef.trim(),
+                where: `contentRefs.${name}.promptRef`,
+                shadowed: false,
+            });
+        }
+        if (typeof value.agentRef === "string" && value.agentRef.trim() !== "") {
+            refs.push({
+                category: "agents",
+                ref: value.agentRef.trim(),
+                where: `contentRefs.${name}.agentRef`,
+                shadowed: false,
+            });
+        }
+    }
+    for (const item of refs) {
+        out.refs += 1;
+        if (item.shadowed) {
+            out.shadowed += 1;
+            continue;
+        }
+        try {
+            new ContentStore(root, item.category).resolveEntry(item.ref, item.category);
+        }
+        catch (e) {
+            out.dangling += 1;
+            out.issues.push(`${item.where}=${item.ref} → ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return out;
+}
 // ---------------------------------------------------------------- 主入口
 /**
  * 采集插件面健康快照（**纯读**）。
@@ -372,6 +435,7 @@ export function collectHealth(agentDir, opts) {
     const events = installed ? readEvents(path.join(root, "lineage"), now) : { exists: false, lastEventAgeMs: null, streams: 0, deliveredThisHour: 0, lastDeliveredAt: null };
     const tasks = installed ? readTasks(path.join(root, "tasks.json")) : { count: 0, totalFireCount: 0 };
     const config = readConfig(path.join(root, "config.json"));
+    const external = readExternalContent(root);
     const handoverFile = readLatestHandover(agentDir);
     const handover = {
         exists: handoverFile !== undefined,
@@ -423,6 +487,7 @@ export function collectHealth(agentDir, opts) {
             maxPerHour: config.maxPerHour,
             issues: config.issues,
         },
+        external,
         handover,
         findings: [],
         overall: "ok",
@@ -607,6 +672,25 @@ function buildFindings(report, ctx) {
                 : "无需处置。",
         alertKind: cfg.issues.length > 0 ? "CONFIG_INVALID" : undefined,
     });
+    // ---- 外置内容引用（CFG1）
+    const ext = report.external;
+    out.push({
+        id: "external.content",
+        label: "外置内容引用",
+        status: ext.dangling > 0 ? "fail" : "ok",
+        value: `引用 ${ext.refs} 个` +
+            (ext.shadowed > 0 ? `（其中 ${ext.shadowed} 个被内联值覆盖、未生效）` : "") +
+            ` · 悬空 ${ext.dangling} 个` +
+            (ext.issues.length > 0 ? `：${ext.issues.join("；")}` : ""),
+        criterion: "配置里的每个 promptRef / agentRef 都必须能解析到 <配置目录>/prompts|agents/<ref>.md" +
+            "（悬空 / 空文件 / 格式错 / 越界路径 均判红）",
+        thresholdSource: "实现口径：src/content.ts 的 ContentStore.resolveEntry()（CFG1 规范 §9 冻结的契约；失败语义 = 抛错并指名 ref 与路径）",
+        advice: ext.dangling > 0
+            ? "改 <agent-dir>/proactive/config.json 里的引用，或补上对应的 prompts/<ref>.md / agents/<ref>.md；" +
+                "不得靠静默回退默认值掩盖（规范 §8）。"
+            : "无需处置。",
+        alertKind: ext.dangling > 0 ? "EXTERNAL_CONTENT_BROKEN" : undefined,
+    });
     return out;
 }
 /** 毫秒 → 人可读时长。 */

package/build/src/lineage.js

@@ -42,10 +42,10 @@ function isLineageEvent(value) {
         return false;
     if (typeof e.type !== "string")
         return false;
-    if (e.type !== "triggered" && e.type !== "delivered" && e.type !== "answered" && e.type !== "outcome" && e.type !== "dropped" && e.type !== "decision") {
+    if (e.type !== "triggered" && e.type !== "delivered" && e.type !== "answered" && e.type !== "outcome" && e.type !== "dropped" && e.type !== "decision" && e.type !== "trust") {
         return false;
     }
-    if (e.cause !== "idle" && e.cause !== "schedule" && e.cause !== "peer-request" && e.cause !== "manual")
+    if (e.cause !== "idle" && e.cause !== "schedule" && e.cause !== "peer-request" && e.cause !== "manual" && e.cause !== "trust")
         return false;
     return true;
 }
@@ -212,6 +212,29 @@ export class Lineage {
             decision: info.decision,
         });
     }
+    /**
+     * 记一次**信任层事件**（托付四段 / 目标归因）。
+     *
+     * 落什么：阶段 + 托付/目标 id + 归因步数 + 通道 + 守候时长 + 原因。
+     * 为什么落在事件流里（而不是另一个文件）：托付闭环率、回应率、守候时长
+     * **必须能靠账本复算**（`src/trust-metrics.ts` 只读事件流，不读登记册）→
+     * 单一事件流 = 单一真源。
+     */
+    noteTrust(info) {
+        return this.append({
+            type: "trust",
+            cause: "trust",
+            trust: {
+                stage: info.stage,
+                ...(info.entrustmentId !== undefined ? { entrustmentId: info.entrustmentId } : {}),
+                ...(info.goalId !== undefined ? { goalId: info.goalId } : {}),
+                ...(info.progressDelta !== undefined ? { progressDelta: info.progressDelta } : {}),
+                ...(info.channel !== undefined ? { channel: info.channel } : {}),
+                ...(info.waitedMs !== undefined ? { waitedMs: info.waitedMs } : {}),
+                ...(info.reason !== undefined ? { reason: info.reason } : {}),
+            },
+        });
+    }
     /**
      * 记一次「回应」（窗口内的事实）。
      *
@@ -420,6 +443,22 @@ export function formatLineageHistory(events) {
             if (e.durationMs !== undefined)
                 detail.push(`耗时=${formatShortDuration(e.durationMs)}`);
         }
+        if (e.type === "trust" && e.trust !== undefined) {
+            const t = e.trust;
+            detail.push(`阶段=${t.stage}`);
+            if (t.entrustmentId !== undefined)
+                detail.push(`托付=${t.entrustmentId.slice(0, 8)}`);
+            if (t.goalId !== undefined)
+                detail.push(`目标=${t.goalId.slice(0, 8)}`);
+            if (t.progressDelta !== undefined)
+                detail.push(`推进=${t.progressDelta}`);
+            if (t.channel !== undefined)
+                detail.push(`通道=${t.channel}`);
+            if (t.waitedMs !== undefined)
+                detail.push(`守候=${formatShortDuration(t.waitedMs)}`);
+            if (t.reason !== undefined)
+                detail.push(`原因=${t.reason}`);
+        }
         lines.push(`${formatEventTime(e.ts)}  ${e.type.padEnd(9)}  ${e.cause.padEnd(12)}  ${ids.join(" ")}  ${detail.join(" ")}`.trimEnd());
     }
     return lines.join("\n");

package/build/src/notify.js

@@ -0,0 +1,183 @@
+/**
+ * 设备级通知（形态 A · N1）与「会话内联系」**共用同一份载荷**。
+ *
+ * 为什么要单独一个文件（而不是塞进 daemon.ts）：
+ * - 载荷只构造一次 → 会话投递与设备通知**措辞必然一致**（两份各写一遍必然漂移）；
+ * - 通道**可插拔**（接口 + 三个实现）→ 加新通道（Slack/邮件/托盘）不改调用方；
+ * - 命令执行器**可注入** → 测试零真实通知（不在开发者机器上弹窗）。
+ *
+ * 载荷四段（用户只面对三件事里的「它会做什么 / 怎么回应」）：
+ *   ① 为什么找你　② 需要你做什么　③ 不做的后果　④ 怎么关掉我
+ *
+ * 纪律：**不造新的动作语义** —— 这里只搬运既有语义（通知 + 设备级提示），
+ * 不新增「主动行为」（主动能力登记见 `src/daemon.ts` 的四件套声明）。
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter } from "node:path";
+/** 通知标题的缺省文案。 */
+export const DEFAULT_CONTACT_TITLE = "助理找你有事";
+/**
+ * 构造载荷（**唯一**入口）。
+ *
+ * 正文格式固定为四行（顺序固定）——人读得懂，机器也能按行取。
+ */
+export function buildContactPayload(input) {
+    const title = input.title ?? DEFAULT_CONTACT_TITLE;
+    return {
+        why: input.why,
+        ask: input.ask,
+        consequence: input.consequence,
+        howToDisable: input.howToDisable,
+        title,
+        body: contactBody(input),
+    };
+}
+/** 载荷正文（四行；**顺序固定**）—— 会话投递与设备通道都用它 → 措辞不可能漂移。 */
+export function contactBody(input) {
+    return [
+        `为什么找你：${input.why}`,
+        `需要你做什么：${input.ask}`,
+        `不做的后果：${input.consequence}`,
+        `怎么关掉我：${input.howToDisable}`,
+    ].join("\n");
+}
+/** 默认执行器：同步执行、5 秒超时、继承环境但**不继承 stdin**。 */
+export const defaultExec = (cmd, args) => {
+    const res = spawnSync(cmd, args, { timeout: 5000, stdio: ["ignore", "pipe", "pipe"] });
+    const stderr = res.stderr ? res.stderr.toString("utf8").slice(0, 300) : "";
+    return {
+        ok: res.status === 0 && !res.error,
+        code: res.status ?? 1,
+        ...(stderr !== "" ? { stderr } : {}),
+    };
+};
+/** macOS 通知中心（`osascript display notification`）。 */
+export function createMacChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => process.platform === "darwin" && commandExists("osascript"));
+    return {
+        id: "osx",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "osascript 不可用" };
+            // 参数化传递（正文含换行/引号 → 绝不能拼进 AppleScript 源码）。
+            const res = exec("osascript", [
+                "-e",
+                "on run argv",
+                "-e",
+                "display notification (item 1 of argv) with title (item 2 of argv)",
+                "-e",
+                "end run",
+                payload.body ?? contactBody(payload),
+                payload.title ?? DEFAULT_CONTACT_TITLE,
+            ]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `osascript 退出码 ${res.code}` };
+        },
+    };
+}
+/** Linux 桌面通知（`notify-send`）。 */
+export function createLinuxChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => process.platform === "linux" && commandExists("notify-send"));
+    return {
+        id: "linux",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "notify-send 不可用" };
+            const res = exec("notify-send", [payload.title ?? DEFAULT_CONTACT_TITLE, payload.body ?? contactBody(payload)]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `notify-send 退出码 ${res.code}` };
+        },
+    };
+}
+/** herdr 通知（`herdr notification show`）—— herdr 宿主下的现成通道。 */
+export function createHerdrChannel(opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const available = opts.available ?? (() => commandExists("herdr"));
+    return {
+        id: "herdr",
+        isAvailable: available,
+        async send(payload) {
+            if (!available())
+                return { ok: false, detail: "herdr 不可用" };
+            const res = exec("herdr", [
+                "notification",
+                "show",
+                payload.title ?? DEFAULT_CONTACT_TITLE,
+                "--body",
+                payload.body ?? contactBody(payload),
+            ]);
+            return res.ok ? { ok: true } : { ok: false, detail: res.stderr ?? `herdr 退出码 ${res.code}` };
+        },
+    };
+}
+/** 空通道（永远不可用 → 选通道时必被跳过；用于「本机没有设备通知」的情形）。 */
+export function createNullChannel() {
+    return {
+        id: "none",
+        isAvailable: () => false,
+        async send() {
+            return { ok: false, detail: "无设备通知通道" };
+        },
+    };
+}
+/** 内置工厂表。 */
+export function defaultChannelFactories() {
+    return {
+        herdr: () => createHerdrChannel(),
+        osx: () => createMacChannel(),
+        linux: () => createLinuxChannel(),
+    };
+}
+/**
+ * 按可用性挑选通道（**不可用的自动跳过** → 回落是自动的）。
+ *
+ * 返回顺序 = 入参顺序（调用方按顺序发 → 第一个成功的即可停）。
+ */
+export function selectNotifyChannels(opts) {
+    const factories = opts.factories ?? defaultChannelFactories();
+    const out = [];
+    for (const id of opts.channels) {
+        const make = factories[id];
+        if (make === undefined)
+            continue;
+        let ch;
+        try {
+            ch = make();
+        }
+        catch {
+            continue;
+        }
+        try {
+            if (!ch.isAvailable())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push(ch);
+    }
+    return out;
+}
+/** 命令是否存在（**只看 PATH**，不执行）。 */
+function commandExists(cmd) {
+    const pathEnv = process.env["PATH"] ?? "";
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir === "")
+            continue;
+        try {
+            if (existsSync(joinPath(dir, cmd)))
+                return true;
+        }
+        catch {
+            // 忽略（权限等异常 → 当作不可用）
+        }
+    }
+    return false;
+}
+/** 拼路径（避免为一个函数引入 path 模块 → 保持本文件零副作用）。 */
+function joinPath(dir, cmd) {
+    return dir.endsWith("/") ? `${dir}${cmd}` : `${dir}/${cmd}`;
+}