@shgroup/dsh-serenity-hooks 1.72.0 → 1.73.0

package/lib/im/feishu-account.d.ts

@@ -0,0 +1,92 @@
+/**
+ * im/feishu-account.ts — 飞书账号实现（P3，2026-10-19）
+ *
+ * ## 它凭什么这么短
+ *
+ * 这是本件最有价值的一点：**P3 只写了这一个文件**。路由 ／ 会话 ／ 提问 ／ 回复 ／ 记账 ／
+ * 媒体落盘全都在中立层（`im/inbound-event.ts`，B1）—— 飞书只提供三样：
+ *   ① 怎么建连接并收消息 ② 一条飞书消息长什么样 ③ 怎么把文本发回去。
+ *
+ * owner 那句「和微信一样，只不过是 account 方实现不同」在这里是**代码事实**。
+ *
+ * ## 三条官方约束（照抄会坏，必须各自处理）
+ *
+ * 1. 🔴 **回调须 3 秒内返回**（官方：超时触发重推）⇒ 回调里**只入队**，处理全异步。
+ * 2. 🔴 **超时会重推** ⇒ 必须按 `message_id` **去重**，否则同一句话答两遍。
+ * 3. 🔴 **建连成功 ≠ 能收消息** ⇒ 这两件事分开取证（`getConnectionStatus` 只证明前者）。
+ *
+ * ## 边界（R↓）
+ *
+ * - ⛔ 不做路由判断、不做会话管理 —— 那是中立层的。
+ * - ⛔ 不解析富文本/图片/文件（本期）：只取 `message_type === 'text'` 的正文；
+ *   其它类型当作"有消息但没文本"交给中立层（它会静默或降级，**不会静默丢连接**）。
+ */
+import type { ImAccountImpl } from './accounts.js';
+import type { ImInboundEvent } from './inbound-event.js';
+/**
+ * 飞书 SDK 的最小面（**注入**，不是硬 import）。
+ *
+ * 🔴 为什么注入（两条理由，一条设计、一条实测）：
+ *  ① **设计**：与微信同款（`installWeixinAccountImpl` 注入 `getUpdates` 等）。
+ *     飞书 SDK 是重依赖（protobufjs 等）⇒ 不该成为模块求值时的硬依赖，只在真要起账号时加载。
+ *  ② **实测**：`vi.mock` 拦不住它 —— 本模块用 `await import('@larksuiteoapi/node-sdk')`，
+ *     而该包在 pnpm 下是**外置依赖**，vitest 的动态 import 不被 mock 拦截。实测证据：
+ *     测试里跑出了真 SDK 自己的日志 `[error]: ['[ws]', 'invalid appId: cli_x']`
+ *     ⇒ 若坚持 mock，测的就是"能不能骗过测试装置"，不是被测对象。
+ *     ⇒ 注入后，测试直接给替身，**没有魔法**。
+ */
+export interface FeishuSdk {
+    Client: new (p: {
+        appId: string;
+        appSecret: string;
+    }) => {
+        im?: {
+            v1?: {
+                message?: {
+                    create?: (p: unknown) => Promise<unknown>;
+                };
+            };
+        };
+    };
+    EventDispatcher: new (p?: unknown) => {
+        register: (h: Record<string, (d: never) => unknown>) => unknown;
+    };
+    WSClient: new (p: {
+        appId: string;
+        appSecret: string;
+    }) => {
+        start: (p: {
+            eventDispatcher: unknown;
+        }) => Promise<void>;
+        close: (p?: {
+            force?: boolean;
+        }) => void;
+    };
+}
+/**
+ * 接入 SDK 加载器（`bridge.ts` 在模块求值时注入真加载器；测试注入替身）。
+ * 缺省 = 动态 import 真包 —— 这样生产路径不需要 `bridge.ts` 也能独立跑。
+ */
+export declare function installFeishuSdk(loader: () => Promise<FeishuSdk>): void;
+/** 测试辅助：关掉并清空全部长连接（生产零调用） */
+export declare function __closeAllFeishuConnectionsForTest(): void;
+/** 测试辅助：清空去重表（生产零调用） */
+export declare function __resetFeishuSeenForTest(): void;
+/**
+ * 从飞书 `im.message.receive_v1` 事件里取出**中立入站事件**。
+ *
+ * 🔴 这是 P3 唯一的"形状翻译"处，与 `bridge.ts` 里 iLink 的那一处对称。
+ * ⚠️ 用户标识用 **open_id**（不是 chat_id）：路由表是"人 → 轨迹"，
+ *    而 chat_id 在群里会变、在单聊里也与人不是一一对应。
+ * @returns 无可用发送者/消息体 ⇒ `null`（调用方丢弃并**出声**，不静默）
+ */
+export declare function feishuEventToInbound(data: Record<string, unknown>): ImInboundEvent | null;
+/** 飞书账号实现（登记名 = `feishu`；与配置里的 `channel` 取值一致） */
+export declare const feishuAccountImpl: ImAccountImpl;
+/**
+ * 注册飞书实现（`bridge.ts` 在**模块求值时**调用）。
+ *
+ * ⚠️ 与微信同款教训（续 220 实测 12 例红）：注册必须在**模块求值**时发生，
+ * 不能等 `apply` —— 测试与面板会**直接**调 `syncCccBridge` / `syncHumanChannel`。
+ */
+export declare function installFeishuAccountImpl(): void;

package/lib/im/inbound-event.d.ts

@@ -0,0 +1,162 @@
+/**
+ * im/inbound-event.ts — **中立入站事件层**（B1，2026-10-19）
+ *
+ * ## 这一层解决的是什么
+ *
+ * `handleIncoming` 原先吃的 `msg` 是 **iLink 形状**（`from_user_id` / `context_token` /
+ * `item_list` / `message_type`）。飞书的消息形状与它**没有一处相同**，所以接第二家 IM
+ * 的真正工作量不在"建连接"，而在**把各家消息归一成同一个东西**。
+ *
+ * 本文件就是那个"同一个东西"，以及消费它的**通道中立主流程**。
+ *
+ * ## 切法（为什么这样切，而不是改 `handleIncoming` 的签名）
+ *
+ * 🔴 实测爆炸半径：全仓 **约 50 处**测试直接驱动 `handleIncoming` 的 iLink 形状。
+ * 直接改签名 ⇒ 那 50 处同时要改 ⇒ 而 B1 的验收判据恰恰是「**微信行为逐字不变**」
+ * （用例数守恒 ＋ 真机一条微信）。判据自己会失去可复算性。
+ *
+ * ⇒ 切法是**适配器**：
+ *   - 本文件 `handleInboundEvent()` = 真正的主流程，**零 iLink 概念**；
+ *   - `bridge.ts` 的 `handleIncoming()` 退化成**薄适配器**：iLink 消息 → 中立事件 + iLink 的 io；
+ *   - 飞书实现自己造中立事件 + 飞书的 io，调到**同一个** `handleInboundEvent`。
+ *
+ * 收益：微信侧调用点与测试**逐字不动**；第二条、第三条 IM 只是**新增一个适配器**。
+ *
+ * ## 边界（R↓：这层刻意**不**管什么）
+ *
+ * - ⛔ **不管连接怎么建**（长轮询 vs WebSocket 回调）—— 那是各账号实现自己的事。
+ * - ⛔ **不管凭据怎么取** —— `io` 与事件都由实现处构造好再交进来。
+ * - ✅ 只负责：「一条已到达的消息，该投到哪条认知轨迹、怎么答、怎么记账」。
+ */
+import type { Context } from 'cordis';
+import { type SkiffProfile } from '../trajectory/policy/profile.js';
+/**
+ * 一条**已到达**的入站消息（归一后）。
+ *
+ * 刻意只留**主流程真正用到的**字段 —— 每多留一个通道特定的字段，这一层就多一处
+ * 需要为两家分别解释的东西（E↓）。
+ */
+export interface ImInboundEvent {
+    /** 发送者在**该通道内**的稳定标识（微信 = from_user_id；飞书 = open_id） */
+    userId: string;
+    /** 正文（含语音转写）。无文本 ⇒ `null` */
+    text: string | null;
+    /** 媒体项（图片/文件）。顺序即到达顺序 */
+    media: ImMediaItem[];
+    /** 有语音但**没有转写文本**（触发降级告知；与 `text` 同时为空时才有意义） */
+    hasVoice: boolean;
+    /**
+     * 回复锚点。微信 = `context_token`（回复必须带上它）；飞书**没有这个概念**
+     * ⇒ 可选。⛔ 不要在消费侧假设它一定在。
+     */
+    replyRef?: string;
+}
+/**
+ * 一个媒体项：**取字节的动作由通道自己提供**。
+ *
+ * 为什么把下载放进事件里，而不是让主流程拿着 `item` 去调 `downloadMedia`：
+ * 后者是 iLink 的 CDN 协议，飞书是 `im.v1.messageResource.get` —— 两者除了
+ * "返回一堆字节"之外没有任何共同点。⇒ 中立层只约定**取字节这个动作**。
+ */
+export interface ImMediaItem {
+    kind: 'image' | 'file';
+    /** 原始文件名（file 才有；**未净化**，净化在落盘侧做） */
+    fileName?: string;
+    /** 取字节；失败/不可得 ⇒ `null`（主流程**降级告知**，不静默） */
+    fetch(): Promise<{
+        data: Buffer;
+        fileName?: string;
+    } | null>;
+}
+/**
+ * 账号的**动作面**（发消息 / 打字态）。
+ *
+ * 与 `ImInboundEvent` 成对：进来的是事件，出去的是动作。两者都不含通道协议细节。
+ */
+export interface ImAccountIo {
+    /** 发纯文本（实现内部做各自的长度分片与格式转换） */
+    sendText(input: {
+        toUserId: string;
+        text: string;
+        replyRef?: string;
+    }): Promise<void>;
+    /** "正在输入"起始（可实现不了；飞书就没有这个能力） */
+    typingStart?(input: {
+        toUserId: string;
+        replyRef?: string;
+    }): Promise<void>;
+    /** "正在输入"结束（异常路径也会调 ⇒ 实现须自行容忍未开始的情形） */
+    typingStop?(input: {
+        toUserId: string;
+    }): Promise<void>;
+}
+/**
+ * 路由解析结果：目标根 ＋ **轨迹编码** ＋ **该轨迹的 skiff 约束面**。
+ * `null` 从本函数出去 ⇒ **不投递**（未命中已留痕 ／ 目标不存在已响亮出声）。
+ */
+export interface ResolvedInboundTarget {
+    root: string;
+    /** 目标认知轨迹编码（= 新模型里的"身份"；旧模型的角色名已退役） */
+    trajectory: string;
+    /**
+     * 该轨迹的 skiff 约束面。
+     * ⚠️ **可能为 `null`**：轨迹存在但没有 `skiff.json` ⇒ 它是一条**普通轨迹**，
+     * IM 桥照样可以往里投，只是不施加 skiff 约束。
+     */
+    profile: SkiffProfile | null;
+}
+/**
+ * **入站路由的单一解析处**（P0-3）：机器级订阅表优先 → CCC 级回退；三档语义都在这里落地。
+ *
+ * 🔴 为什么抽成一个函数而不是写两遍：**两种模式（CCC 起桥 ／ 机器级起 poller）走的是同一套
+ * 判据**，差别只有一格 —— **有没有 CCC 级回退**（`cccFallback`）。写两遍必然分叉。
+ *
+ * 三档（方案 §3.1，**刻意分档**）：
+ *  - **未命中** ⇒ 不投递 ＋ **留痕**（静默档：这是"表里没有你"，不是错误）
+ *  - **表残缺** ⇒ **响亮出声**（且**独立于是否命中**）
+ *  - **目标不存在**（CCC ／ **轨迹**）⇒ **响亮报错**（不静默丢弃）
+ */
+export declare function resolveInboundTarget(ctx: Context, input: {
+    account: string;
+    user: string;
+    cccFallback: {
+        root: string;
+        trajectory: string;
+    } | null;
+}): Promise<ResolvedInboundTarget | null>;
+/**
+ * **一条入站消息的主流程**（通道中立）。
+ *
+ * 职责：路由 → 固定会话 id 创建/延续 → 提问 → 回复（或被闸门拦下后兜底）。
+ * 语料（媒体）由事件自带 `fetch()`；出站走的 `io`。
+ *
+ * 🔴 **本函数没有任何 iLink 概念** —— 这是 B1 的判据。任何 `context_token` /
+ * `item_list` / `message_type` 出现在这里，就说明抽缝没抽干净。
+ *
+ * @param preset 机器级模式：目标已解析好 ⇒ **不再自行路由**，且**不看本 CCC 的 `enabled`**
+ */
+export declare function handleInboundEvent(ctx: Context, root: string, accountId: string, io: ImAccountIo, event: ImInboundEvent, preset?: {
+    target: ResolvedInboundTarget;
+}): Promise<void>;
+/**
+ * 手动输出模式的**机制标记**（v1.30.10 引入；v1.30.16 按「ACC 管机制、CCC 管措辞」重构）。
+ *
+ * 边界（R↓）：ACC 只提供**机制与数据**——"桥不转发最终文本"这个事实 + 三个已填好的参数值。
+ * **纪律措辞归 CCC**：怎么写、必须怎么做、后果是什么，全部写在轨迹的 `PROMPT.md` 里。
+ */
+export declare function manualOutputMarker(accountId: string, userId: string): string;
+/**
+ * 手动输出模式的**兜底判定**（纯函数，v1.30.17——把决策矩阵从装配里抽出来，可独立测试）。
+ *
+ * 四个条件同时成立才兜底：
+ * ① CCC 显式开启 `fallbackOnNoSend`（缺省 false = 严格静默）
+ * ② 机械闸门**已装配**（未装配时无法判定"是否发送过" → 宁可静默也不冒重复发送风险）
+ * ③ 本轮**没有**成功发送（agent 自己发过 → 输出权归 agent，桥不插话）
+ * ④ 有最终文本可转发（空文本无意义）
+ */
+export declare function manualOutputFallbackNeeded(input: {
+    fallbackOnNoSend?: boolean;
+    guardActive: boolean;
+    sentThisTurn: boolean;
+    answer: string;
+}): boolean;

package/lib/im/route.d.ts

@@ -78,6 +78,19 @@ export declare function readWeixinCredential(root: string, accountId: string): W
 export declare function writeWeixinCredential(root: string, accountId: string, cred: WeixinAccountCredential): void;
 /** 清除账号凭据（移除账号时） */
 export declare function clearWeixinCredential(root: string, accountId: string): void;
+/** 飞书账号凭据（appSecret 缺 ⇒ 账号未绑定） */
+export interface FeishuAccountCredential {
+    /** 应用 appId（自建应用「凭证与基础信息」页） */
+    appId: string;
+    /** 应用 appSecret（**凭据**，只在 localstore） */
+    appSecret: string;
+}
+/** 读取飞书账号凭据（appId 或 appSecret 缺失 → null——账号未绑定） */
+export declare function readFeishuCredential(root: string, accountId: string): FeishuAccountCredential | null;
+/** 写入飞书账号凭据（面板保存后；两者都必写——只写一半等于没绑） */
+export declare function writeFeishuCredential(root: string, accountId: string, cred: FeishuAccountCredential): void;
+/** 清除飞书账号凭据（移除账号时） */
+export declare function clearFeishuCredential(root: string, accountId: string): void;
 /**
  * 路由匹配：exact user 优先，通配 `*` 兜底。
  * @returns 命中的**轨迹编码**；未命中 → null（无路由 → 消息不回复/忽略）

package/lib/index.d.ts

@@ -164,10 +164,6 @@ export interface Config {
     gatewayEnabled?: Volatile<boolean | undefined>;
     /** F2 触发阈值（K token；面板层；部署层同义键 = `rebuild.thresholdK`） */
     rebuildThresholdK?: Volatile<number | undefined>;
-    /** F4 Skiff 调试服务总开关（面板层；部署层同义键 = `skiff.enabled`） */
-    skiffEnabled?: Volatile<boolean | undefined>;
-    /** F4 Skiff 调试端口（面板层；部署层同义键 = `skiff.debugPort`） */
-    skiffDebugPort?: Volatile<number | undefined>;
     /** CRO（轨迹自编程唤起）总闸（面板层；无部署层同义键；缺省开） */
     croEnabled?: Volatile<boolean | undefined>;
     /** **diagram 工具总闸**（面板层；部署层同义键 = `diagram.enabled`；缺省关；D104） */
@@ -201,13 +197,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         thresholdK: z<number, number, "defined">;
     }>>, "plain">;
-    skiff: z<Schemastery.ObjectS<NoInfer<{
-        enabled: z<boolean, boolean, "defined">;
-        debugPort: z<number, number, "defined">;
-    }>>, Schemastery.ObjectT<NoInfer<{
-        enabled: z<boolean, boolean, "defined">;
-        debugPort: z<number, number, "defined">;
-    }>>, "plain">;
     webFetch: z<Schemastery.ObjectS<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
@@ -257,8 +246,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, "plain">;
     gatewayEnabled: z<boolean, boolean, "volatile">;
     rebuildThresholdK: z<number, number, "volatile">;
-    skiffEnabled: z<boolean, boolean, "volatile">;
-    skiffDebugPort: z<number, number, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, Schemastery.ObjectT<NoInfer<{
@@ -283,13 +270,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         thresholdK: z<number, number, "defined">;
     }>>, "plain">;
-    skiff: z<Schemastery.ObjectS<NoInfer<{
-        enabled: z<boolean, boolean, "defined">;
-        debugPort: z<number, number, "defined">;
-    }>>, Schemastery.ObjectT<NoInfer<{
-        enabled: z<boolean, boolean, "defined">;
-        debugPort: z<number, number, "defined">;
-    }>>, "plain">;
     webFetch: z<Schemastery.ObjectS<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
@@ -339,8 +319,6 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, "plain">;
     gatewayEnabled: z<boolean, boolean, "volatile">;
     rebuildThresholdK: z<number, number, "volatile">;
-    skiffEnabled: z<boolean, boolean, "volatile">;
-    skiffDebugPort: z<number, number, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, "plain">;