pi-proactive 0.0.0-stage → 0.2.0-beta.3

package/build/src/dedupe.js

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isKnownOnDiskVersion, onDiskVersionOf, proactiveDir, reportForeignVersion, resolveAgentDir, writeAtomicFile, } from "./config.js";
+import { agentSegment } from "./envelope.js";
+/** seen 集合保留窗口（plan §5.5：保留最近 N=512 个 id）。 */
+export const DEFAULT_SEEN_LIMIT = 512;
+/**
+ * **窗口容量估算**（偏差 P-D10：窗口多大必须能被估算，而不是拍脑袋）。
+ *
+ * 估算口径 = 「一个 agent 会话一天产生多少条消息 id」= 本插件**处理过的对端消息**条数
+ * （每条进/出的 A2A 信封各占一个 id）。
+ * 样本：本机真实会话日志 `~/.pi/agent/sessions/` 下的 `*.jsonl`（2026-10-23 ~ 2026-10-26）里
+ * 带 `proactive:peer` 来源标记的注入消息（即本插件处理过的对端消息）：
+ * - 有 peer 消息的会话：63 个；
+ * - 每会话 peer 消息总数：min 1 / **p50 2** / **p90 13** / max 24 / 均值 5.1；
+ * - 全机每日：60 / 183 / 69 / 8 条，分布在 23 / 24 / 14 / 2 个会话上
+ *   → **每会话每日 2.6 ~ 7.6 条**。
+ *
+ * 结论：单个 agent 的 seen 集合增速 ≈ **3 ~ 8 条/天**（p90 ≈ 13 条/天，最坏观测会话 24 条/其整个生命周期）
+ * → 512 条窗口 ≈ 覆盖 **≥ 3 周**（最坏 512/24 ≈ 21 天），典型会话 ≈ **≥ 100 天**。
+ * 超窗后的行为是「旧 id 不再去重 → 再次到达被**重新处理**」（重复处理，**不丢消息**），
+ * 因此窗口偏小只会造成重复处理，不会造成消息丢失。
+ *
+ * 可调：`PI_PROACTIVE_SEEN_LIMIT=<正整数>`（见 `resolveSeenLimit`）—— 该入口是**进程级环境变量**，
+ * **不持久化**（持久化需改 `src/config.ts` 的配置面，不在本卡白名单内 → 台账 P-D10 的残余限制）。
+ */
+export const SEEN_LIMIT_CAPACITY = {
+    /** 每会话每日的消息 id 条数（实测 p50 / p90 / 最坏单会话）。 */
+    perSessionPerDay: { p50: 3, p90: 13, worst: 24 },
+    /** 512 条窗口按上述速率可覆盖的天数。 */
+    coverageDays: { p50: 170, p90: 39, worst: 21 },
+};
+/**
+ * 保留窗口的**可调入口**（偏差 P-D10：窗口此前是写死的常量 → 不可调、不可估算）。
+ *
+ * `PI_PROACTIVE_SEEN_LIMIT=<正整数>` 生效；非法值 → 回落缺省 512（不猜、不报错）。
+ * 契约（规范「去重窗口必须是显式契约」）：
+ * - 多大：本值（缺省 512 条 id）；
+ * - 依据什么淘汰：按 `at`（首次记录时刻）**升序**淘汰最早的；
+ * - 超窗后的行为：旧 id **不再去重** → 再次到达会被**重新处理**（重复处理，不是丢消息）。
+ */
+export function resolveSeenLimit() {
+    const raw = process.env.PI_PROACTIVE_SEEN_LIMIT;
+    if (raw === undefined)
+        return DEFAULT_SEEN_LIMIT;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SEEN_LIMIT;
+}
+/**
+ * 接收侧按消息 id 去重（至少一次投递 + 接收侧去重 = 不丢且不重复执行）。
+ *
+ * 落盘位置：`<agentDir>/proactive/processed/<agentId>/seen.json`（原子写 tmp+rename）。
+ * 约定：
+ * - `seen(id)` → 该 id 是否**已处理过**；同一 id 再次到达时调用方**必须跳过**；
+ * - `mark(id)` → 记录（保留最近 N 个 id，超出后按时间淘汰最早的）；
+ * - 文件缺失 → 空集合；文件坏 → 备份为 `.corrupt-<ts>` 并以空集合启动，**绝不抛出**。
+ */
+export class SeenSet {
+    agentDir;
+    agentId;
+    now;
+    limit;
+    /** 当前文件带**不认识的版本** → 拒绝按已知格式解析，且不得覆盖原文件（规范 V3）。 */
+    foreignVersion = null;
+    /** 已提示过（同一进程内不重复刷屏）。 */
+    notifiedForeign = false;
+    constructor(opts) {
+        this.agentDir = opts.agentDir ?? resolveAgentDir();
+        this.agentId = opts.agentId;
+        this.now = opts.now ?? Date.now;
+        this.limit = opts.limit ?? resolveSeenLimit();
+    }
+    /** seen 集合文件绝对路径。 */
+    get filePath() {
+        return path.join(proactiveDir(this.agentDir), "processed", agentSegment(this.agentId), "seen.json");
+    }
+    /** 该 id 是否已处理过（true ⇒ 调用方必须跳过）。 */
+    seen(mid) {
+        return this.read().some((e) => e.id === mid);
+    }
+    /** 记录一个已处理的 id（重复 mark 不产生重复条目）。 */
+    mark(mid) {
+        const entries = this.read();
+        if (entries.some((e) => e.id === mid))
+            return;
+        entries.push({ id: mid, at: this.now() });
+        // 超窗后按时间淘汰最早的
+        if (entries.length > this.limit) {
+            entries.sort((a, b) => a.at - b.at);
+            entries.splice(0, entries.length - this.limit);
+        }
+        this.write(entries);
+    }
+    /** 当前 seen 文件的**未知版本**（无则 null）—— 供宿主观测。 */
+    get foreignVersionText() {
+        return this.foreignVersion;
+    }
+    /** 当前集合大小（便于测试与观测）。 */
+    size() {
+        return this.read().length;
+    }
+    // ---- 内部实现 ----
+    /** 读盘：文件缺失 → 空集合；坏文件 → 备份 + 空集合（绝不抛出）。 */
+    read() {
+        const file = this.filePath;
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return [];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.backupCorrupt(file);
+            return [];
+        }
+        // 未知版本 → **拒绝按已知格式解析**（规范 V3）：按空集合处理，
+        // 且**不备份、不覆盖**原文件（备份 = 移动原文件，也算破坏「原文件保留」）。
+        const version = onDiskVersionOf(parsed);
+        if (!isKnownOnDiskVersion(version)) {
+            this.foreignVersion = typeof version === "string" ? version : (JSON.stringify(version) ?? "缺失");
+            return [];
+        }
+        if (!isSeenFile(parsed)) {
+            this.backupCorrupt(file);
+            return [];
+        }
+        return parsed.entries;
+    }
+    /**
+     * 原子写（tmp **独占** + 同目录 rename + 0600，**不 fsync**）。
+     *
+     * **持久化分层（P-D4）**：本面属于「**可重建的中间态**」→ **不 durable**。
+     * - 分层规则：① **承诺数据**（用户可感知、不可重建、丢了=用户受损：任务表 / 配置 /
+     *   待投递信封）→ `durable: true`（fsync 文件 + fsync 父目录）；② **可重建中间态**
+     *   （seen / 注册表条目 / 重试 sidecar / 线程事件 / 归档目录）→ 不 durable。
+     * - 为什么 seen 不 durable：
+     *   - **丢了不丢消息**：seen 只是去重账本 → 丢了最多让窗口内的消息被**重复处理**
+     *     （规范 §1.4：seen「可部分重建」——由 `processed/<seg>/*.json` 的文件名反推）；
+     *     而消息本体在 `processed/` 归档里，不会消失；
+     *   - **代价可量化**：seen 是**最热**的写点（每处理一条消息写一次，完整重写整个 512 条集合）。
+     *     在这条路径上每次都 fsync，等于把一次同步落盘（实测毫秒级）加到**每条消息**上；
+     *     而重复处理在语义上是幂等的（处理方本来就该容忍「至少一次投递」）。
+     * - **解除条件**：若产品要求「绝不重复处理」（幂等键语义升级为强保证），
+     *   或某部署的单会话消息速率显著高于实测（见 `DEFAULT_SEEN_LIMIT` 的容量估算注释），
+     *   把本行改为 `{ durable: true }` 即可（**一行**改动，无需改其它面）。
+     * - 其它面的分层理由见 `src/config.ts` 的 `writeAtomicFile` 注释与台账 `deviations.json` 的 P-D4 条目。
+     *
+     * 未知版本 → **拒绝写入**（不得覆盖原文件，规范 V3②）。
+     */
+    write(entries) {
+        if (this.foreignVersion !== null) {
+            if (!this.notifiedForeign) {
+                this.notifiedForeign = true;
+                reportForeignVersion("seen.json", this.filePath, this.foreignVersion);
+            }
+            return;
+        }
+        const file = this.filePath;
+        writeAtomicFile(file, `${JSON.stringify({ entries }, null, 2)}\n`);
+    }
+    /** 坏文件 → 备份改名（备份失败也绝不抛出）。 */
+    backupCorrupt(file) {
+        try {
+            fs.renameSync(file, `${file}.corrupt-${this.now()}`);
+        }
+        catch {
+            // 备份失败也绝不抛出（宁可当成空集合）
+        }
+    }
+}
+/** seen 文件形状校验。 */
+function isSeenFile(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (!Array.isArray(v.entries))
+        return false;
+    return v.entries.every((e) => typeof e === "object" &&
+        e !== null &&
+        typeof e.id === "string" &&
+        typeof e.at === "number");
+}

package/build/src/envelope.js

@@ -0,0 +1,283 @@
+/** 合法 `kind`（契约 §1：消息语义 —— 对方要不要回我）。 */
+export const DELIVER_KINDS = ["notify", "ask", "task", "reply", "broadcast"];
+/**
+ * **人类发起标记**（`customType` 取值空间的一个具名取值）。
+ *
+ * 语义：这条信封由**人类操作者**在本会话里直接下达（`/proactive tell`），
+ * **不是**模型转达、也不是模型自己发起的协作消息。
+ *
+ * **它不豁免任何校验**：`from` 仍必须逐字命中收信侧注册表 + 主机一致（P1 `strict` 口径不变）。
+ * 收信侧只有在发送方属于「受信人类发起方」集合时，才把它当成**已验证**的人类指令；
+ * 否则只当「对端的**声称**」（如实标注，不给特权）—— 语义见 `docs/a2a-protocol.md`。
+ *
+ * 为什么复用 `customType` 而不是新增信封字段：信封字段集是**封闭**的
+ * （`docs/a2a/envelope.schema.json` 的 `additionalProperties:false`）→ 新增字段会让
+ * 本实现比 schema 松（严格按 schema 实现的第三方对端会拒收）→ 复用既有「投递来源标记」
+ * 字段是唯一不破线格式契约的做法。
+ */
+export const HUMAN_ORIGIN_CUSTOM_TYPE = "proactive:human";
+/** 合法 `intent`（契约 §1：投递意图 —— 怎么投给对方）。 */
+export const INTENTS = ["wake", "interrupt", "queue", "notify"];
+/** 默认最大转手次数（防 A→B→A 环路）。 */
+export const DEFAULT_MAX_HOPS = 3;
+/**
+ * agentId → 文件系统片段（**跨模块唯一真源**）：原样保留 `#`（agentId 形如 `name#host#pid`），
+ * 只把路径分隔符与空白换成 `_`（防目录穿越 / 非法路径）。
+ *
+ * 写入端（`outbox.ts` 落盘）与读取端（`mailbox.ts` 收件、`dedupe.ts` seen 集合、
+ * `registry.ts` 条目）**必须用这一个函数** —— 两边各写一份必然漂移（写进去读不到）。
+ */
+export function agentSegment(agentId) {
+    return agentId.replace(/[/\\\s]/g, "_") || "unknown";
+}
+/** 默认 TTL：1 小时。 */
+export const DEFAULT_TTL_MS = 3_600_000;
+/**
+ * 单个信封的**体积上限（字节）** —— 收信侧硬上限（本地 IPC 攻击面：超大 body 打爆对端）。
+ *
+ * 取 256 KiB：远大于正常协作消息（KB 级），又足够小到「一个信封不可能把内存/磁盘打爆」。
+ * 超限 → **拒收并隔离**（邮箱路径 → `corrupt/`；socket 路径 → 回执 `rejected`），
+ * **不**先读进内存再判断（读之前先看文件大小 / 帧长度）。
+ */
+export const MAX_ENVELOPE_BYTES = 256 * 1024;
+/** `agentId` / 信封 id 的**长度上限（字符）**：超过即视为畸形（防超长串放大攻击面）。 */
+export const MAX_ID_CHARS = 200;
+/**
+ * 标识（`from` / 信封 `id`）的**结构性合法性**检查（与「是否注册」无关）。
+ *
+ * 拒绝：空串、超长、含控制字符、含路径分隔符（`/ \`）、含 `..`（路径穿越形状）。
+ * 注意：这**不是**鉴权（不证明发送方存在）—— 它只保证「后续拿它拼路径/查注册表」是安全的。
+ */
+export function isWellFormedId(from) {
+    if (typeof from !== "string")
+        return false;
+    if (from.length === 0 || from.length > MAX_ID_CHARS)
+        return false;
+    if (from.includes("/") || from.includes("\\"))
+        return false;
+    if (from.includes(".."))
+        return false;
+    // 控制字符（\u0000-\u001f\u3001\u007f）—— 会污染日志/文件名。
+    return !/[\u0000-\u001f\u007f]/.test(from);
+}
+let idCounter = 0;
+/** 生成消息 id：可读前缀 `m-` + 时间基 36 进制 + 计数 + 随机后缀（进程内唯一 + 跨进程高熵）。 */
+function generateId(now) {
+    idCounter = (idCounter + 1) % 1_679_616;
+    const t = now.toString(36);
+    const c = idCounter.toString(36).padStart(4, "0");
+    const r = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+    return `m-${t}-${c}${r}`;
+}
+/**
+ * 构造消息信封（契约 §2 `Envelope`）。
+ * 非法输入（枚举值越界、ttlMs<=0、maxHops<1）→ 抛带明确信息的 Error。
+ */
+export function createEnvelope(input) {
+    if (!DELIVER_KINDS.includes(input.kind)) {
+        throw new Error(`createEnvelope：kind 非法「${String(input.kind)}」（允许 ${DELIVER_KINDS.join("|")}）`);
+    }
+    if (!INTENTS.includes(input.intent)) {
+        throw new Error(`createEnvelope：intent 非法「${String(input.intent)}」（允许 ${INTENTS.join("|")}）`);
+    }
+    const maxHops = input.maxHops ?? DEFAULT_MAX_HOPS;
+    if (!Number.isInteger(maxHops) || maxHops < 1) {
+        throw new Error(`createEnvelope：maxHops 非法「${String(input.maxHops)}」（必须为 >=1 的整数）`);
+    }
+    const ttlMs = input.ttlMs ?? DEFAULT_TTL_MS;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new Error(`createEnvelope：ttlMs 非法「${String(input.ttlMs)}」（必须 > 0）`);
+    }
+    if (!input.from || !input.to) {
+        throw new Error("createEnvelope：from/to 不能为空");
+    }
+    const createdAt = input.createdAt ?? Date.now();
+    const envelope = {
+        id: input.id ?? generateId(createdAt),
+        from: input.from,
+        to: input.to,
+        kind: input.kind,
+        intent: input.intent,
+        body: input.body,
+        hop: 0,
+        maxHops,
+        ttlMs,
+        priority: input.priority ?? "normal",
+        createdAt,
+    };
+    if (input.subject !== undefined)
+        envelope.subject = input.subject;
+    if (input.threadId !== undefined)
+        envelope.threadId = input.threadId;
+    if (input.correlationId !== undefined) {
+        envelope.correlationId = input.correlationId;
+    }
+    else if (envelope.kind === "reply") {
+        // reply 必须**自带** correlationId（落盘后要能追回它回答的是哪条 ask）：
+        // 调用方没给就用 threadId 兜底（ask↔reply 同线程），再退到信封自身 id（仍可追溯）。
+        envelope.correlationId = input.threadId ?? envelope.id;
+    }
+    if (input.replyTo !== undefined)
+        envelope.replyTo = input.replyTo;
+    if (input.customType !== undefined)
+        envelope.customType = input.customType;
+    return envelope;
+}
+/**
+ * 信封的**封闭字段集**（= `docs/a2a/envelope.schema.json` 的 properties）。
+ *
+ * 写端（`createEnvelope`）与读端（`validateEnvelopeStrict`）必须用**这一个**清单 ——
+ * 两边各写一份必然漂移（写进去读不到 / 读得进写不出）。
+ */
+export const ENVELOPE_FIELDS = [
+    "id",
+    "from",
+    "to",
+    "kind",
+    "intent",
+    "subject",
+    "body",
+    "threadId",
+    "correlationId",
+    "replyTo",
+    "hop",
+    "maxHops",
+    "ttlMs",
+    "priority",
+    "createdAt",
+    "customType",
+];
+/** schema 的 5 个**可选**字段（给了就必须是字符串；见 `validateEnvelopeStrict`）。 */
+export const OPTIONAL_ENVELOPE_FIELDS = [
+    "subject",
+    "threadId",
+    "correlationId",
+    "replyTo",
+    "customType",
+];
+/**
+ * 校验信封：必填字段、类型、枚举值、`ttlMs>0`、`hop<=maxHops`。
+ * 合法 → `{ ok: true, envelope }`；非法 → `{ ok: false, error }`（**不抛裸异常**）。
+ *
+ * **口径分层（重要）**：
+ * - 本函数 = **结构校验**（TS 形状 + 枚举 + 跨字段约束 `hop<=maxHops`）。
+ *   它是 `tests/a2a-conformance-cases/*.json` 台账登记的判定口径（附录 B.1 偏差
+ *   B-3/B-5/B-6 描述的就是它），**不得**在此改口径（台账是协调者资产）。
+ * - **信任边界**（socket 入站帧 / 邮箱入站文件 / 出站自检）一律改用
+ *   {@link validateEnvelopeStrict} —— 它 = 本函数 + JSON Schema 的封闭字段集、
+ *   可选字段类型、`kind=reply` 必带 `correlationId` 三条约束。
+ */
+export function validateEnvelope(msg) {
+    if (typeof msg !== "object" || msg === null || Array.isArray(msg)) {
+        return { ok: false, error: "信封必须是对象" };
+    }
+    const m = msg;
+    const required = [
+        "id",
+        "from",
+        "to",
+        "kind",
+        "intent",
+        "body",
+        "hop",
+        "maxHops",
+        "ttlMs",
+        "priority",
+        "createdAt",
+    ];
+    for (const field of required) {
+        if (m[field] === undefined || m[field] === null) {
+            return { ok: false, error: `信封缺少必填字段：${String(field)}` };
+        }
+    }
+    for (const field of ["id", "from", "to", "body"]) {
+        if (typeof m[field] !== "string" || m[field].length === 0) {
+            return { ok: false, error: `信封字段类型错误：${field} 必须是非空字符串` };
+        }
+    }
+    if (!DELIVER_KINDS.includes(m.kind)) {
+        return { ok: false, error: `信封 kind 非法：${String(m.kind)}（允许 ${DELIVER_KINDS.join("|")}）` };
+    }
+    if (!INTENTS.includes(m.intent)) {
+        return { ok: false, error: `信封 intent 非法：${String(m.intent)}（允许 ${INTENTS.join("|")}）` };
+    }
+    if (typeof m.hop !== "number" || !Number.isInteger(m.hop) || m.hop < 0) {
+        return { ok: false, error: `信封 hop 非法：${String(m.hop)}（必须为 >=0 的整数）` };
+    }
+    if (typeof m.maxHops !== "number" || !Number.isInteger(m.maxHops) || m.maxHops < 1) {
+        return { ok: false, error: `信封 maxHops 非法：${String(m.maxHops)}（必须为 >=1 的整数）` };
+    }
+    if (m.hop > m.maxHops) {
+        return { ok: false, error: `信封 hop(${m.hop}) 超过 maxHops(${m.maxHops})` };
+    }
+    if (typeof m.ttlMs !== "number" || !Number.isFinite(m.ttlMs) || m.ttlMs <= 0) {
+        return { ok: false, error: `信封 ttlMs 非法：${String(m.ttlMs)}（必须 > 0）` };
+    }
+    if (m.priority !== "normal" && m.priority !== "high") {
+        return { ok: false, error: `信封 priority 非法：${String(m.priority)}（允许 normal|high）` };
+    }
+    if (typeof m.createdAt !== "number" || !Number.isFinite(m.createdAt)) {
+        return { ok: false, error: `信封 createdAt 非法：${String(m.createdAt)}（必须为数字）` };
+    }
+    return { ok: true, envelope: msg };
+}
+/**
+ * **契约校验**（严格）：= `validateEnvelope`（结构校验）+ JSON Schema 的三条额外约束。
+ *
+ * 1. **封闭字段集**（schema `additionalProperties:false`）—— 未知字段一律拒绝（D2 / 偏差 B-3）；
+ * 2. **可选字段类型**（schema `type:string`）—— 非字符串一律拒绝（D3 / 偏差 B-5）；
+ *    其中 `correlationId` / `replyTo` 还要求**非空**（schema `minLength:1`）；
+ * 3. **`kind:"reply"` 必带 `correlationId`**（schema `if/then`）—— 缺失一律拒绝（D4 / 偏差 B-6）。
+ *
+ * **为什么信任边界用它**：第三方对端按 JSON Schema 实现（附录 B.1 明示「本规范以 schema 为准」），
+ * 主实现比 schema 松 → 同一条边界样例两侧判定不同 → 对端拿到的字段类型不可信、reply 配不上对。
+ * 收紧后主实现与严格对端**逐条一致**。
+ *
+ * 非法 → `{ ok: false, error }`（**不抛裸异常**）。
+ */
+export function validateEnvelopeStrict(msg) {
+    const base = validateEnvelope(msg);
+    if (!base.ok)
+        return base;
+    const m = msg;
+    const allowed = new Set(ENVELOPE_FIELDS);
+    const unknown = Object.keys(m).filter((k) => !allowed.has(k));
+    if (unknown.length > 0) {
+        return { ok: false, error: `信封含未知字段：${unknown.join(",")}（schema 为封闭字段集）` };
+    }
+    for (const field of OPTIONAL_ENVELOPE_FIELDS) {
+        const value = m[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            return { ok: false, error: `信封字段类型错误：${field} 必须是字符串` };
+        }
+        if ((field === "correlationId" || field === "replyTo") && value.length === 0) {
+            return { ok: false, error: `信封字段 ${field} 不得为空串` };
+        }
+    }
+    if (m.kind === "reply" && (typeof m.correlationId !== "string" || m.correlationId.length === 0)) {
+        return { ok: false, error: "信封 kind=reply 必须带 correlationId（schema if/then）" };
+    }
+    return base;
+}
+/**
+ * TTL 判定：年龄 **>= ttlMs** 即过期（恰好等于 TTL 视为过期）。
+ */
+export function isExpired(msg, now = Date.now()) {
+    return now - msg.createdAt >= msg.ttlMs;
+}
+/**
+ * 转发：hop+1。
+ * 超过 `maxHops` → **拒绝**（防 A→B→A 环路），返回 `{ ok:false, error }`；原信封不被修改。
+ */
+export function nextHop(msg) {
+    const hop = msg.hop + 1;
+    if (hop > msg.maxHops) {
+        return {
+            ok: false,
+            error: `hop 超限：next hop=${hop} 超过 maxHops=${msg.maxHops}（拒绝转发，防环路）`,
+        };
+    }
+    return { ok: true, envelope: { ...msg, hop } };
+}

package/build/src/guard.js

@@ -0,0 +1,74 @@
+const HOUR_MS = 3_600_000;
+/**
+ * 触发护栏。
+ *
+ * 计数作用域 = **每 agent**（一个 agent 一个 Guard 实例）：N 个 agent ⇒ N × 单 agent 上限，
+ * 不是全局上界（见 implementation-spec.md §5「多进程放大护栏计数」）。
+ *
+ * check() 是纯判断，不修改状态；只有 record() 才写入。
+ */
+export class Guard {
+    config;
+    state = { fireLog: [] };
+    constructor(config) {
+        this.config = config;
+    }
+    /** 判断此刻是否允许触发："allow" | "defer"（稍后再说）| "drop"（本小时丢弃）。 */
+    check(now = Date.now()) {
+        const { minGapMs, maxPerHour, quietHours } = this.config.limits;
+        // 冷却期未过 → defer
+        const last = this.state.lastFireAt;
+        if (last !== undefined && now - last < minGapMs)
+            return "defer";
+        // 本小时触发数已达上限 → drop
+        if (this.countInWindow(now) >= maxPerHour)
+            return "drop";
+        // 静默时段 → defer
+        if (quietHours && this.isInQuietHours(quietHours, now))
+            return "defer";
+        return "allow";
+    }
+    /** 记录一次触发（调用方在真正投递之后调用）。 */
+    record(now = Date.now()) {
+        this.state.lastFireAt = now;
+        this.state.fireLog.push(now);
+        this.prune(now);
+    }
+    /** 本小时还剩多少次触发额度。 */
+    remainingThisHour(now = Date.now()) {
+        return Math.max(0, this.config.limits.maxPerHour - this.countInWindow(now));
+    }
+    countInWindow(now) {
+        const from = now - HOUR_MS;
+        return this.state.fireLog.filter((t) => t > from && t <= now).length;
+    }
+    prune(now) {
+        const from = now - HOUR_MS;
+        this.state.fireLog = this.state.fireLog.filter((t) => t > from && t <= now);
+    }
+    /** 静默时段判定；from > to 表示跨零点（如 22:00 → 07:00）。 */
+    isInQuietHours(q, now) {
+        const from = parseHHMM(q.from);
+        const to = parseHHMM(q.to);
+        if (from === null || to === null)
+            return false;
+        if (from === to)
+            return false; // 零长度窗口 = 不静默
+        const d = new Date(now);
+        const minutes = d.getHours() * 60 + d.getMinutes();
+        return from < to
+            ? minutes >= from && minutes < to
+            : minutes >= from || minutes < to;
+    }
+}
+/** "HH:MM" → 当日分钟数；格式非法返回 null（静默降级为不静默）。 */
+function parseHHMM(value) {
+    const m = /^(\d{1,2}):(\d{2})$/.exec(value);
+    if (!m)
+        return null;
+    const h = Number(m[1]);
+    const min = Number(m[2]);
+    if (h > 23 || min > 59)
+        return null;
+    return h * 60 + min;
+}