dsh-whale-post-gate

dsh plugin --profile web add dsh-whale-post-gate

dsh-whale-post-gate

English: gate README in English

配额与计费闸 ＋ 回环闸（可换的挂点 —— 示例②）

• 提供接口：whale.gate
• 依赖接口：whale.types（可选）、whale.roster（可选，用于把"一个组"算成 1 单位）
• 自测：node selftest.mjs（只看退出码：0 过／非 0 不过）

接口带 apiVersion；核心不认识任何成员名与类型标识 —— 名单与类型一律从接口取。

三道闸 ＋ 配额（每道都写明为什么）

离线件豁免整套回环闸（2026-10-10 按设计文档移植；设计文档判据 29-31 ＋「今天的设计目标是 2026-10-06」）：

三道闸拦的都是"别多叫醒人一次" —— 而离线件根本不叫醒任何人（它躺着等对方来收）

⇒ 拦它没有任何收益，只会把"想说的话"堵在发信人手里。

这正是"信只会晚到，不会不到"："闸"该拦的是代价，不是表达**。

⚠️ 豁免的只是回环闸 —— 配额照旧（离线桶独立计）；在线件一切照旧。

# · 闸 · 拦什么

① · 纯回执拒发 · 正文去掉空白标点后只剩"收到／好的／谢谢" ⇒ 拒发（回执本该由收信方自动写 ack）

② · 同对回环闸 · 同一对（你→对方）在 pairWindowMs 内已发 pairMax 封 ⇒ 拒发，先合并成一封

③ · 链深闸 · 带 re 的信按父信 hop 递推，到 hopMax 跳 ⇒ 拒发（链条必须落地成结论）

④ · 配额 · 分桶计额度；离线件独立计（按发信次数，1 次＝1 条，组发不翻倍）

⑤ · 在线件小日上限（S8） · "手机"这类成员：每封在线件 ＝ 叫醒它做一次满上下文推理（最贵的一步）⇒ 按 min(自报, 天花板) 拦；离线件不受这条限；--force 不豁免

接口

方法 · 一句话

check(letter, ctx) · 拦不拦：'pass'／{ reject, reason }

record(letter, targets) · 投递成功后才记账（被拦下的信不占额度）

report({ as, days }) · 查账（只读）

cfg／localDay()／quotaUnits() · 生效配置／日界／"这封算几个单位"

配置

字段 · 默认 · 含义

quota.onOver · 'reject' · 'reject' 拒发（退出码非 0、不落信箱）／'price' 照发但计费（"闸是价格闸，不是封嘴闸"）

quota.dayBoundaryHour · 0 · 日界：0 ＝ 自然日；写 9 ＝ 早九点到次日早九点算一天

quota.types · direct 120／broadcast 45／club 60／offline 80 · 每桶 limit；离线桶可 perSend: true（按发信次数计）

quota.defaultLimit · 120 · 没在表里的类型落这个桶（否则"注册一个新类型"在闸这层就不成立）

quota.bucketRules · 不配 · 分桶规则（数组）：[{ field, equals, bucket }] —— 从上往下第一个命中的赢；equals 不写 ⇒ "该字段有值就命中"。字段名与桶名全由配置给（本件里不出现任何具体名字）。不配 ⇒ 行为一字不变（离线走 offline、其余按 type）

now（顶层） · 不配 · 时钟可注入：给一个有限数字（钉死时刻）或函数（() => ms）⇒ 台账的"哪一天"按它算（不配 ⇒ 真时间）。为什么要它："生效时刻"这类规则（"09:00 前按旧口径、到点后才分桶"）必须能拿假时间测 —— 原来处处裸 Date.now() ⇒ 测不了

quota.defaultBucket · 不配 · 一条规则都没命中时落哪个桶（配了 bucketRules 才有意义 —— 必须有，否则"带新字段的信"会掉回 type 桶）

quota.phoneFlag · 不配 · 谁是"手机"（属性名由配置给 —— 本件不认识任何具体名字）：带此属性的收件人只算在线件的小日上限。不配 ⇒ 这道闸完全不启用

quota.phoneOnlineCap · 3 · 天花板：实际额度 ＝ min(收件人自报的 onlineCapPerDay, 这个) —— "收件习惯由它自己声明，而声明只能更保守"（它能把上限调到 1，调不到天花板之上）。没自报 ⇒ 用天花板（"没说" ≠ "可以一直叫醒它"）

loop.ackMaxBytes · 40 · 多长的正文才可能被当回执

loop.ackOnly · 中英回执词 · 中英都认（只认中文 ⇒ 英文回执成了绕过闸的后门）

loop.pairWindowMs · 20 分钟 · 同对回环的时间窗

loop.pairMax · 3 · 同一对在这个窗内最多发几封

loop.hopMax · 3 · 链深上限

边界（两条老实话，免得下一个人把它当安全边界）

• 链深闸不是安全边界 —— 它依赖回信人老实带 re，不带就重置。它是礼貌闸／省米闸。
• --force 会整条绕过这三道闸（这是有意留的逃生门），但留痕：台账当日记 forced 计数。
• 剔完组里没人 ⇒ 拒发（配额按组算时会遇到 —— 宁可拒发，也不发一封没有收件人的信）。

换掉它

想换一套计费口径（比如按字节计费、或者干脆不限额）⇒ 只换这一件，

核心与别的插件一行都不用动（它们只认 check／record／report／recount 这四个）。

对账（台账可以"验"，不只是"信"）

台账是基线 ＋ 增量小文件，口径是「账可少不可多」（崩了可能漏记 ⇒ 对发信人有利，绝不双记）。

recount 是给"验"用的那一半：从文件系统重算一份按天的账，跟台账逐日逐桶比。

命令在 cli 里 —— whale-post reconcile --as <谁> [--days N] [--remote <根>]

（用法见 packages/cli/README）：一致 ⇒ 退出 0；有差 ⇒ 退出 3。

⚠️ 它能算的：letters／units／bytes／byBucket.<桶>.{letters, units}；

不能算的（文件里没有那些事实，命令会照实列出来）：forced（force 是发送那一刻的选择）、

over／feeCent（取决于记账当时读到的已用量）、byPhone／recent（记账时属性与收据）。