@shgroup/dsh-serenity-hooks 1.50.0 → 1.51.0

package/lib/human-channel.d.ts

@@ -18,9 +18,15 @@
  * `ccc:<root>|<accountId>`（那时身份里带了 root ⇒ 跨 CCC 不可能撞车，也就不会误判成"同一账号"）。
  *
  * ## 边界
- * 本模块**只做归属判定**（谁能起、谁被谁占着），**不碰**：轮询循环、凭据解析、路由投递。
- * 那些留在 `weixin-bridge.ts`（渠道实现）—— 归属是机制，实现是渠道。
+ * 本模块做三件事（**都属机制**，与"哪个渠道"无关）：
+ *  ① **归属判定**（P0-2：谁能起 poller、谁被谁占着）—— 见下 §归属判定
+ *  ② **订阅表查询 ＋ 入站路由决策**（P0-3：`(账号, 用户) → (CCC, 角色)`）—— 见 §订阅表
+ *  ③ **机器级留痕**（P0-3：未投递 ／ 目标不存在 ／ 表残缺）—— 见 §留痕。
+ *     🔴 为什么这些必须机器级：它们**没有目标 CCC** ⇒ 落进任何 CCC 都是"编一个"目标。
+ * **不碰**：轮询循环、凭据解析、会话投递 —— 那些是**渠道实现**，留在 `weixin-bridge.ts`。
+ * ⇒ 本模块**零 DSH 依赖**（只有 `node:crypto` ／ `node:fs`），可独立单测。
  */
+import type { HumanChannelSubscriptionSettings } from './settings-section.js';
 /** 一个"想为该账号起 poller"的请求（来自某 CCC） */
 export interface PollerRequest {
     /** 发起方 CCC 根（绝对路径） */
@@ -87,3 +93,126 @@ export declare function releasePollersOf(root: string): number;
 export declare function releaseAllPollers(): void;
 /** 测试专用：复位进程级归属表（生产零调用） */
 export declare function __resetPollersForTest(): void;
+/** 订阅表里**完好**的一行（四个字段全部非空） */
+export interface SubscriptionHit {
+    account: string;
+    user: string;
+    ccc: string;
+    role: string;
+}
+/**
+ * 订阅表里的**残缺行**（缺字段）。
+ * 🔴 它**不是**"未命中"（见上）；且**与是否命中无关** —— 表里只要有残缺行就要出声，
+ * 否则"命中了一条完好的"会让人以为整张表是干净的。
+ */
+export interface SubscriptionDefect {
+    /** 行序（0 基）—— 报错要指得出是**哪一行** */
+    index: number;
+    /** 缺哪些字段（`account` ／ `user` ／ `ccc` ／ `role`） */
+    missing: string[];
+    /** 行里**已有**的字段（残缺行的可见部分：让人认得出是哪一行） */
+    present: Record<string, string>;
+}
+export interface SubscriptionLookup {
+    /** 命中的行（未命中 ⇒ `null`） */
+    hit: SubscriptionHit | null;
+    /** 表里残缺的行（**与是否命中无关**，一律要出声） */
+    defects: SubscriptionDefect[];
+    /** 表里**完好**的行数（供调用方区分"表是空的"与"表里没有你"） */
+    usable: number;
+}
+/**
+ * 订阅表查询（**纯函数**）。
+ *
+ * 匹配两段式（**刻意对齐**旧 `matchWeixinRoute` 的 exact → `*` 兜底）：
+ *  ① `account` **精确** ∧ `user` **精确**
+ *  ② `account` **精确** ∧ `user === '*'`（通配兜底）
+ * 🔴 `account` **不设通配**：它是机器级账号的**显式身份**（表里写的就是账号 id）；
+ *   给账号也开 `*` 会让"这条订阅到底覆盖哪个 bot"变得不可读。
+ * 🔴 `user` 保留 `*`：这是**有意的**——存量 CCC 级 `routes` 用的就是 `{user:'*'}`，
+ *   迁移（P0-4）要能**逐字平移**它，否则"迁移"会悄悄改变行为。
+ *
+ * @param subscriptions 机器级订阅表（`readSimpleSettings().humanChannel.subscriptions`）
+ * @param account 收到的**账号 id**（poller 身份；不是 token）
+ * @param user 发信人 id
+ */
+export declare function lookupSubscription(subscriptions: readonly HumanChannelSubscriptionSettings[], account: string, user: string): SubscriptionLookup;
+/** 入站投递目标**从哪来**（判据用；也是"这条消息为什么被投到这里"的可重建依据） */
+export type InboundRouteSource = 'machine' | 'ccc-fallback';
+/** 未投递的原因（两档，措辞刻意不同 —— 见 `planInboundRoute`） */
+export type InboundSkipReason = 'no-subscription' | 'no-match';
+export interface InboundRoutePlan {
+    /** 投递目标（`null` ⇒ **不投递**） */
+    target: {
+        ccc: string;
+        role: string;
+    } | null;
+    /** 目标出处（`null` ⇔ `target === null`） */
+    source: InboundRouteSource | null;
+    /** 未投递的原因（`target !== null` ⇒ `null`） */
+    skipReason: InboundSkipReason | null;
+    /** 订阅表里残缺的行（**与是否命中无关**，一律要出声） */
+    defects: SubscriptionDefect[];
+}
+/**
+ * 入站路由决策（**纯函数**）。
+ *
+ * 顺序：**机器级订阅表优先** → 未命中时用 CCC 级回退。
+ *
+ * 🔴 **回退是过渡期的"不打断在用的微信"**（方案 §11.3 **Q5**）：机器级账号表为空时，
+ * 桥仍按 CCC 起、路由也仍认 CCC 级 `routes`。机器级一旦配起来，回退传 `null`
+ * ⇒ **未命中 = 不投递**（不是"投给默认角色"——那正是方案 §3.1 明令禁止的）。
+ * @param input.subscriptions 机器级订阅表
+ * @param input.account 收到的账号 id
+ * @param input.user 发信人 id
+ * @param input.fallback CCC 级回退目标（`{ccc, role}`）；无 ⇒ `null` ／ 省略
+ */
+export declare function planInboundRoute(input: {
+    subscriptions: readonly HumanChannelSubscriptionSettings[];
+    account: string;
+    user: string;
+    fallback?: {
+        ccc: string;
+        role: string;
+    } | null;
+}): InboundRoutePlan;
+/**
+ * 留痕落点：`$DSH_HOME/human-channel-audit.jsonl`（缺省 `~/.dsh/human-channel-audit.jsonl`）。
+ *
+ * 🔴 **为什么是机器级而不是某个 CCC 的 `_weixin-logs/`**：本文件记的事件（未投递 ／
+ * 目标不存在 ／ 表残缺）**恰恰是"没有目标 CCC"的那些** —— 落进任何一个 CCC 都是**编一个**目标。
+ * （投递成功的入站事件仍落**被路由到的那个 CCC** 的 `_weixin-logs/`，方案 §3.6 不变。）
+ * env `SERENITY_HUMAN_CHANNEL_AUDIT` 覆盖（测试注入；与 `SERENITY_HOOKS_CONFIG` 同款推导）。
+ */
+export declare function humanChannelAuditPath(): string;
+/**
+ * 留痕事件。
+ * 🔴 **刻意不记消息正文**：方案 §3.1 要的是"**谁**发的、**为什么**没投" —— 正文既不必要，
+ * 又会把人说的话抄进一个机器级文件（本该只落在他自己 CCC 的日志里）。
+ */
+export type HumanChannelAuditEvent = {
+    kind: 'inbound-unrouted';
+    account: string;
+    user: string;
+    reason: InboundSkipReason;
+    detail: string;
+} | {
+    kind: 'inbound-target-missing';
+    account: string;
+    user: string;
+    ccc: string;
+    role: string;
+    detail: string;
+} | {
+    kind: 'subscription-defect';
+    account: string;
+    index: number;
+    missing: string[];
+    present: Record<string, string>;
+};
+/**
+ * 追加一条留痕。**永不抛** ——
+ * 留痕失败绝不能反过来打断投递（它是**旁路**，与 `invokeWeixinHook` 的"旁路容忍"同款）。
+ * 🔴 **不静默的是它记的那件事**，不是它自己：所以调用方仍要**另行 `console` 出声**。
+ */
+export declare function appendHumanChannelAudit(event: HumanChannelAuditEvent): void;

package/lib/index.d.ts

@@ -156,6 +156,13 @@ export interface Config {
     visionPatch?: {
         enabled?: boolean;
     };
+    /**
+     * diagram 工具（实验性 demo；2026-09-29 owner 具名令 **D104**）：标签格式源码 → 进程内
+     * 光栅化成 PNG（**不借浏览器**）。缺省关；部署层同义键 = 面板层 `diagramEnabled`。
+     */
+    diagram?: {
+        enabled?: boolean;
+    };
     /** human-channel（人机信道；**机器级**；2026-09-26 owner 定案）—— 见 `HumanChannelConfig` */
     humanChannel?: HumanChannelConfig;
     /** F1 双端口网关总开关（面板层；部署层同义键 = `gateway.enabled`） */
@@ -176,6 +183,8 @@ export interface Config {
     croEnabled?: Volatile<boolean | undefined>;
     /** 无人值守代理回复总闸（面板层；无部署层同义键；缺省关） */
     unattendedEnabled?: Volatile<boolean | undefined>;
+    /** **diagram 工具总闸**（面板层；部署层同义键 = `diagram.enabled`；缺省关；D104） */
+    diagramEnabled?: Volatile<boolean | undefined>;
 }
 /** schemastery 的 schema 类型（别名只为可读；**名字取自全局命名空间**，见上方 TS2742 说明） */
 type SchemaOf<S, T = S> = Schemastery<S, T>;
@@ -234,6 +243,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    diagram: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
     humanChannel: z<Schemastery.ObjectS<NoInfer<{
         accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
         subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
@@ -270,6 +284,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     publicAskEnabled: z<boolean, boolean, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     unattendedEnabled: z<boolean, boolean, "volatile">;
+    diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, Schemastery.ObjectT<NoInfer<{
     serenityConfigPaths: z<string[], string[], "defined">;
     tools: z<boolean, boolean, "defined">;
@@ -321,6 +336,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    diagram: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
     humanChannel: z<Schemastery.ObjectS<NoInfer<{
         accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
         subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
@@ -357,6 +377,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     publicAskEnabled: z<boolean, boolean, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     unattendedEnabled: z<boolean, boolean, "volatile">;
+    diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, "plain">;
 export declare function apply(ctx: Context, config: Config): void;
 export {};