@shgroup/dsh-serenity-hooks 1.70.0 → 1.72.0

package/lib/invariant.js

@@ -1,8 +1,8 @@
 import { dirname, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
-//#region src/invariant.ts
+//#region src/kernel/invariant.ts
 /**
-* invariant.ts — 包级不变量伴生（dsh-my-rsi creating-a-plugin 规范）
+* kernel/invariant.ts — 包级不变量伴生（dsh-my-rsi creating-a-plugin 规范）
 *
 * 检查：dsh.plugin.json 的 contributes.tools 与代码实际注册的工具一致。
 * 挂载时 plugin-local 会校验清单；本不变量让仓库内 `verify-package-invariants`

package/lib/{ccc-roots.d.ts → kernel/ccc-roots.d.ts}

@@ -1,5 +1,5 @@
 /**
- * ccc-roots.ts — CCC 根解析的**唯一判断层**（L1 单根解析 + L2 全量枚举）
+ * kernel/ccc-roots.ts — CCC 根解析的**唯一判断层**（L1 单根解析 + L2 全量枚举）
  *
  * 为什么存在（C2「CCC 发现面归一」，S142 2026-09-15 Q5 裁决）：
  * 「这个会话/路径属于哪个 CCC 根」（L1）与「本机有哪些 CCC」（L2）这两层判断此前被
@@ -8,11 +8,11 @@
  * 调用方只问本模块，不再各写各的上溯 + 兜底。
  *
  * 分层（唯一真相源边界，**不要**把下层搬进本模块）：
- *  - **L0 原语** `findSerenityRoot(cwd)`（`ccc.ts:16`）——**仍是唯一** L0 实现，本模块从它 import。
+ *  - **L0 原语** `findSerenityRoot(cwd)`（`kernel/ccc.ts:16`）——**仍是唯一** L0 实现，本模块从它 import。
  *  - **L1 单根解析** —— 本模块：{@link agentCwdFor}（agent/exec → cwd）与
  *    {@link cccRootForCwd}/{@link cccRootForExec}（cwd → 根）。
  *  - **L2 全量枚举** —— 本模块：{@link listCccs}。
- *  - **L3 CCC 名解析** `readCccName`（`ccc.ts`）——不在本模块，也不与 `skills-discovery` 的
+ *  - **L3 CCC 名解析** `readCccName`（`kernel/ccc.ts`）——不在本模块，也不与 `skills-discovery` 的
  *    第二份实现合并（那是另一条开放项）。
  *
  * 不新增持久状态（Q5 裁决：**不新增"本机 CCC 名单"**、不扫盘、不写路径假设）——
@@ -21,7 +21,7 @@
  * ── 🔴 2026-09-25 I2 收敛（约束文档 §2.7 违反清单，L1 违反之一）────────────────
  * **本模块的 `ctx` 参数类型从 `Context` 改为 `unknown`** —— 消除本文件唯一的 `W2` 接触。
  *
- * **判据（与 `live-sessions.ts` 同款，但本文件要多过一道）：** 约束文档 §2.7 原记本处
+ * **判据（与 `trajectory/live.ts` 同款，但本文件要多过一道）：** 约束文档 §2.7 原记本处
  * `Context` 是"**实测真被用到**"（因它调 `hostService(ctx,…)`／`hostSessions(ctx)`）。
  * 🔴 **该判断把"透传"与"解引用"混为一谈了** —— 实测本文件 `ctx` 的**唯一**去向是
  * **原样透传**给两个 L0 取数口（签名均为 `ctx: unknown`），**零处** `ctx.xxx` 属性访问。
@@ -58,14 +58,14 @@ export interface ExecOrAgent {
  */
 export declare function agentCwdFor(execOrAgent: ExecOrAgent): string;
 /**
- * cwd → CCC 根（L0 原语的唯一调用形态；`ccc.ts` 之外不要再各写一遍）。
+ * cwd → CCC 根（L0 原语的唯一调用形态；`kernel/ccc.ts` 之外不要再各写一遍）。
  * @param cwd 起始路径（目录或文件；文件会靠 `dirname` 上溯）
  * @returns CCC 根绝对路径；不在任何 CCC 内 → `null`
  */
 export declare function cccRootForCwd(cwd: string): string | null;
 /**
  * 工具/缝入口的根解析（L1 标准形态）：`agentCwdFor(...)` 再上溯。
- * @returns CCC 根；解析不到 → `null`（**不**回落假根——"回落进程 cwd 当根"是 `rebuild.ts`
+ * @returns CCC 根；解析不到 → `null`（**不**回落假根——"回落进程 cwd 当根"是 `trajectory/rebuild.ts`
  *   独有的另一条语义，见该处注释）
  */
 export declare function cccRootForExec(execOrAgent: ExecOrAgent): string | null;
@@ -83,9 +83,9 @@ export interface CccEntry {
     /** 目录名（展示用） */
     name: string;
     /**
-     * 该 CCC 的 skiff 角色名列表。
-     * ⚠️ **仅 `withRoles: true` 时非空**；缺省 `false` ⇒ 恒为 `[]` 且**不读任何
-     * `serenity.json`**（唤醒调度器每 tick 都要枚举，不该为角色付 IO；见 listCccs 说明）。
+     * 该 CCC 的 skiff 列表（**轨迹编码**；新模型里编码即身份）。
+     * ⚠️ **仅 `withRoles: true` 时非空**；缺省 `false` ⇒ 恒为 `[]` 且**不扫
+     * `AGENT_SESSIONS/`**（唤醒调度器每 tick 都要枚举，不该为 skiff 付 IO）。
      */
     roles: string[];
 }
@@ -95,7 +95,7 @@ export interface ListCccsOptions {
      * 传 `undefined`/`''` 表示没有默认根。
      */
     defaultRoot?: string;
-    /** 是否实时读取各 CCC 的 `skiff.roles`（缺省 false）。 */
+    /** 是否实时扫各 CCC 的 skiff 轨迹（缺省 false）。 */
     withRoles?: boolean;
 }
 /**

package/lib/{ccc.d.ts → kernel/ccc.d.ts}

@@ -1,5 +1,5 @@
 /**
- * ccc.ts — CCC 纯逻辑层（零 DSH 依赖，可独立单测）
+ * kernel/ccc.ts — CCC 纯逻辑层（零 DSH 依赖，可独立单测）
  *
  * 职责：CCC 根检测（P1）、git 检测（P2）、serenity.json 配置读取（.opencode 规范位置，.dsh 回退）、
  * 路径守卫（P3 语义）、安全模式黑名单匹配。
@@ -86,11 +86,16 @@ interface SerenityConfig {
         /** 重启自动恢复最近激活的宁静号会话（session-start 时，根会话且无自身标记 → 回退最近 use 的标记） */
         autoRestoreSession?: boolean;
     };
-    /** Skiff（F4，v1.25.0 实验性）认知子集角色配置——角色归 CCC 定义（S142 用户拍板） */
-    skiff?: {
-        /** 角色定义（名 → 角色配置）；缺省/空 = Skiff 未启用（零影响） */
-        roles?: Record<string, SkiffRoleConfig>;
-    };
+    /**
+     * 🔴 **`skiff` 段已于 2026-10-19 退役**（owner 重做令）。
+     *
+     * skiff 不再是 `serenity.json` 里的一组角色定义，而是**带 `skiff.json` 的认知轨迹**
+     * （约束面住在轨迹目录里）。⇒ 本段**不再被读取**：存量配置里残留的 `skiff.roles` ⇒
+     * **静默忽略**（schemastery 非 strict，不报错；也不会被误当成"没有 skiff"）。
+     *
+     * 迁移路径 = 把 `skiff.roles.<name>` 的内容原样搬进对应轨迹目录的 `skiff.json`
+     * （判据与步骤见 `role/skiff/profile.ts` 头注释与 `docs/skiff-as-trajectory-redesign.md` §5）。
+     */
     /**
      * 认知轨迹族配置（D58，S142 2026-09-13；2026-10-18 更名 `cognitiveTrajectory`）。
      *
@@ -131,6 +136,12 @@ interface SerenityConfig {
      * 未配置或 enabled=false → 该 CCC 桥完全不启动（零资源占用）。
      */
     weixin?: WeixinSettings;
+    /**
+     * 🔴 **统一 IM 配置（2026-10-19，owner 定向）**：微信与飞书**只是账号实现不同**，
+     * 配置整合到这一段。存在且 `accounts` 是数组 ⇒ 优先于旧 `weixin` 段。
+     * 见 `ImSettings` 的注释（含"为什么判据不是'段存在'"的坑）。
+     */
+    im?: ImSettings;
     /**
      * 专属工具声明（v1.33，S142 §32.11）：**ACC 注册但默认对所有 CCC 隐藏**的工具，
      * 只有在自己这里声明的 CCC 可见（例：`["acc-diag"]` = ACC 负责人的运行态诊断）。
@@ -140,6 +151,73 @@ interface SerenityConfig {
      */
     exclusiveTools?: string[];
 }
+/**
+ * 🔴 **统一 IM 配置（2026-10-19 owner 定向：「飞书和微信一样，只不过是 account 方实现不同。
+ * 要整合到统一的配置中」）。**
+ *
+ * ## 为什么是"账号"这一层，不是"通道"这一层
+ *
+ * 微信与飞书的差别**只在账号侧**：怎么连、怎么收、怎么发。而它们的**身份、路由、会话**
+ * 从来就是通道无关的（`routes: user → 轨迹编码`；会话 id 由轨迹编码派生）。
+ * ⇒ 抽象点是 `account.channel`（这个字段本来就有，装配处也早写着"等第二个实现"），
+ * 不是新造一个平行的"通道接口"。
+ *
+ * ## 与旧 `weixin` 段的关系（向后兼容是硬要求）
+ *
+ * - `im` 段**存在且 `accounts` 是数组** ⇒ 用它；
+ * - 否则 ⇒ **回退读旧 `weixin` 段**（存量 CCC 零迁移，行为逐字不变）。
+ * - 旧段**不删不改**：回滚 = 删掉 `im` 段即可。
+ *
+ * 🔴 **为什么判据是「`accounts` 是数组」而不是「有没有 im 段」**：
+ * 本 CCC 的配置里**曾经**有过一个 `im` 段（退役的 ACP：`{channel:"acp", acp:{…}}`）。
+ * 若只判"段存在"，那份残留会被当成新配置读 ⇒ **读到一个没有 accounts 的对象** ⇒
+ * 表现为"配置没生效"且**不报错**。⇒ 形状判据必须能区分这两种 `im`。
+ */
+export interface ImSettings {
+    /** 总开关（缺省 false——未开零资源占用） */
+    enabled?: boolean;
+    /** 账号表：**每条账号自带 `channel`**（`weixin` / `feishu`），凭据在 localstore */
+    accounts?: ImAccountConfig[];
+    /** 消息路由：**通道用户 id → 认知轨迹编码**（通道无关；`*` 通配兜底） */
+    routes?: ImRouteConfig[];
+    /** 用户别名表：`{ "<别名>": "<localstore 凭据键>" }` */
+    aliases?: Record<string, string>;
+    /** 消息记录 hook（相对 CCC 根的脚本路径） */
+    hook?: string;
+    /** 桥是否自动回发 agent 的最终文本（缺省 true；微信侧语义见旧注释） */
+    autoReplyWithLastMessage?: boolean;
+    /** 手动输出模式的兜底（缺省 false = 严格静默） */
+    fallbackOnNoSend?: boolean;
+    /** iLink 专属：bot_type 取码参数（飞书账号忽略它） */
+    botType?: string;
+}
+/** 统一账号配置：**`channel` 决定用哪个实现**；其余字段各实现自查 */
+export interface ImAccountConfig {
+    /** 本地唯一键（如 wechat-1 / feishu-1） */
+    accountId: string;
+    /**
+     * 账号实现（缺省 `weixin`——旧配置平移到 `im` 段时不必补这个字段）。
+     * 未实现的 channel ⇒ **出声但不静默跳过**（装配处已有该分支）。
+     */
+    channel?: string;
+    /** 展示名（可选） */
+    name?: string;
+    /** 该账号开关（缺省 true） */
+    enabled?: boolean;
+}
+/**
+ * 统一路由配置：**通道用户 id → 认知轨迹编码**。
+ *
+ * 与旧 `WeixinRouteConfig` 语义完全相同（那是它的超集形态）；保留别名仅为读侧兼容。
+ */
+export interface ImRouteConfig {
+    /** 通道用户 id（微信 `xxx@im.wechat` / 飞书 `open_id`）；`*` = 通配兜底 */
+    user: string;
+    /** 目标认知轨迹编码 */
+    trajectory: string;
+    /** @deprecated 过渡别名（语义等同 `trajectory`） */
+    role?: string;
+}
 /**
  * 微信桥配置（CCC 级；S142 用户拍板）：
  * - 结构/路由/开关在 .opencode/serenity.json（git 管可重建）
@@ -147,6 +225,9 @@ interface SerenityConfig {
  *   扫码登录后插件自动写入（面板只显示"已绑定"），永不进 git 明文面
  * - 路由 user → role：exact 匹配优先，通配 `*` 兜底；role 必须是该 CCC skiff.roles 之一
  * - 多账号：accounts[] 每项 { accountId, name?, enabled }（本地唯一键，如 wechat-1）
+ *
+ * 🔴 2026-10-19：**本段已被统一 `im` 段取代**（见上方 `ImSettings`）。此处保留是因为
+ * 存量 CCC 的配置里写的就是它——读侧继续认，**不强制迁移**。
  */
 export interface WeixinSettings {
     /** 总开关（缺省 false——默认关，未开零资源占用） */
@@ -213,50 +294,39 @@ export interface WeixinAccountConfig {
     /** 该账号轮询开关（缺省 true） */
     enabled?: boolean;
 }
-/** 微信桥路由配置：微信用户 → CCC 的 skiff role */
+/**
+ * 微信桥路由配置：微信用户 → 该 CCC 的**认知轨迹编码**
+ *
+ * 🔴 2026-10-19（owner 重做令）：「微信桥的路由表修改为 **user → 认知轨迹的映射**」。
+ * 旧形态指向 `skiff.roles` 里的**角色名**；新形态直接指向**轨迹编码**
+ * （= 目录名固定位置那一段；该轨迹目录里有 `skiff.json` 时它就是 skiff）。
+ */
 export interface WeixinRouteConfig {
     /** 微信用户标识（from_user_id，形如 userA@im.wechat）；`*` = 通配兜底 */
     user: string;
-    /** 目标 skiff role 名（必须 ∈ 该 CCC skiff.roles；ACC 不绑定——用户自选） */
-    role: string;
-}
-/**
- * Skiff 角色配置（CCC 定义：全知全能轨迹的一个子集）：
- * 能力面 = tools（非 MSM 工具白名单）+ msms（MSM 白名单）双白名单，白名单外全隐藏；
- * 轨迹纪律面 = trajectory 子集（session/keeper/rebuild 参与项，默认全关）。
- * 实验性质：未配置任何角色时 Skiff 完全零影响（无监听、无 agent 创建）。
- */
-export interface SkiffRoleConfig {
-    /** 角色模型（provider/model；CCC 直接指定，无白名单校验——用户拍板） */
-    model?: string;
     /**
-     * 角色类型（v1.30.15，S142 用户拍板"skiff 应该区分的类型是临时和长期"）：
-     * - `temporary`：临时 skiff——不绑定 trajectory（无 SESSION.md 工作台），
-     *   提示词按创建时快照注入（"注入发生一次"）。
-     * - `persistent`：长期 skiff——绑定 trajectory（自动建/恢复 SESSION.md 工作台），
-     *   提示词**每轮动态重读文件**（改 `systemPromptFile` 即生效，无需重启）。
-     * 缺省（未写）= 隐式推断：调用方传入稳定 sessionId → persistent，否则 temporary。
+     * 目标**认知轨迹编码**（必须是该 CCC 内一条活跃轨迹的编码；ACC 不绑定——用户自选）。
+     * ⚠️ 存量配置里的 `role` 字段仍被读取作**过渡别名**（读侧 `routeTarget` 统一解析），
+     * 但**新写法是 `trajectory`**，且两者都给时 `trajectory` 优先。
      */
-    kind?: 'temporary' | 'persistent';
-    /** MSM 白名单（独立）：该角色可 exec 的 MSM 名列表；缺省空 = 无 MSM 通道 */
-    msms?: string[];
-    /** 非 MSM 工具白名单（独立）：平台/ACC 工具名列表；缺省空 = 仅 MSM 通道 */
-    tools?: string[];
-    /** 认知轨迹纪律子集（缺省全 false = 完全独立，不参与 keeper/session/rebuild）
-     *  🔴 2026-10-18 更名：`trajectory` → **`cognitiveTrajectory`**（与顶层同名同义）。
-     *  ⚠️ CCC 侧必须同批改（owner 令「CCC 自行处理」），否则该角色静默退化为全 false。 */
-    cognitiveTrajectory?: {
-        session?: boolean;
-        keeper?: boolean;
-        rebuild?: boolean;
-    };
-    /** 角色系统提示词（CCC 完整定义：人格/认知边界/回答风格） */
-    systemPrompt?: string;
-    /** 角色系统提示词文件（推荐：相对 CCC 根引用 md 文件——超长提示词在 JSON 内嵌不可读；
-     *  优先于 systemPrompt；文件缺失/逃逸 → resolveRoleSystemPrompt 抛错。
-     *  persistent 型每轮重读（mtime 缓存），改文件即生效） */
-    systemPromptFile?: string;
+    trajectory: string;
+    /** @deprecated 过渡别名：语义已等同于 `trajectory`（见上）。新配置不要写它。 */
+    role?: string;
 }
+/**
+ * 🔴 **`SkiffRoleConfig` 已于 2026-10-19 退役**（owner 重做令）。
+ *
+ * 它的语义整体搬进**轨迹目录下的 `skiff.json`**，类型现在是
+ * `role/skiff/profile.ts` 的 `SkiffProfile`（在那里还多了 `code`/`dirName`/`path`
+ * 三个与轨迹身份相关的字段）。
+ *
+ * 退役理由（一句话）：skiff 的约束面是**某一条轨迹的属性**，不是容器级配置表里的一个 entry。
+ * 放进 `serenity.json` 会让"这条轨迹是不是 skiff"分散在**两个文件**里，而 owner 要的是
+ * 一条判据（「目录下拥有 `skiff.json` 的认知轨迹自动是一个 skiff」）。
+ *
+ * ⚠️ 旧字段里 `kind: temporary|persistent` **整件无对应物**：它区分"有没有工作台"，
+ * 而新模型里 skiff 恒等于一条轨迹 ⇒ 恒有 SESSION.md ⇒ 该区分没有指称对象（静默忽略）。
+ */
 /**
  * 解析 cheap-worker 配置。
  *

package/lib/{config-ops.d.ts → kernel/config.d.ts}

@@ -1,5 +1,5 @@
 /**
- * config-ops.ts — plugin 全局配置读写（结构化，`~/.dsh/serenity-hooks.json`）
+ * kernel/config.ts — plugin 全局配置读写（结构化，`~/.dsh/serenity-hooks.json`）
  *
  * 归属原则（S142 用户拍板，v1.22）：**plugin 是全局的，CCC 是具体的**——
  * 账号密码/gateway 监听配置是 plugin 级能力，归 plugin 全局文件；
@@ -57,7 +57,7 @@ interface PersonaSettings {
 /**
  * 高级设定全量（~/.dsh/serenity-hooks.json 持久化形态；passHash 含 hash）。
  * review P2-3：**rebuild 已从高级配置删除**——rebuild 开关/阈值归"简单配置"
- * （settings.yaml 原生面板，见 settings-section.ts），运行时只读 readSimpleSettings()；
+ * （settings.yaml 原生面板，见 surface/settings.ts），运行时只读 readSimpleSettings()；
  * 旧高级 rebuild 字段是死双胞胎（/serenity/config PUT 回显但运行时从不读它）——
  * 删除防误导（用户在高级面板改了却无效）。历史残留字段被 mergeWithDefaults 忽略（幂等安全）。
  */

package/lib/kernel/constants.d.ts

@@ -0,0 +1,20 @@
+/** 常量（纯模块，零 DSH 依赖） */
+/**
+ * 包根 = 含**本包** `package.json` 的目录。
+ *
+ * 🔴 为什么不写 `join(here, '..')`：本模块自身的位置**随目录重构变化**
+ * （曾 `src/`，现 `src/kernel/`），而发布态是从打包入口 `lib/index.js` 反推 ——
+ * 两种布局的深度不同，写死层数**必然在其中一个布局下静默错位**。
+ * 实测代价：`src/` → `src/kernel/` 之后，`join(here,'..')` 指到 `src/`（无 package.json）
+ * ⇒ `ACC_VERSION` 落进 catch 分支变 `0.0.0`，**没有任何门禁报警**。
+ *
+ * ⇒ 判据改成**内容**（找带本包名的 package.json）而不是**层数**。
+ *
+ * @param start 起点目录（缺省 = 本模块所在目录；测试可注入）
+ */
+export declare function findPackageRoot(start?: string): string | null;
+/**
+ * ACC 版本：自动从 package.json 读取（单一真相源，消除与 CHANGELOG 的漂移）。
+ * 发布时只需改 package.json 的 version。
+ */
+export declare const ACC_VERSION: string;

package/lib/{invariant.d.ts → kernel/invariant.d.ts}

@@ -1,5 +1,5 @@
 /**
- * invariant.ts — 包级不变量伴生（dsh-my-rsi creating-a-plugin 规范）
+ * kernel/invariant.ts — 包级不变量伴生（dsh-my-rsi creating-a-plugin 规范）
  *
  * 检查：dsh.plugin.json 的 contributes.tools 与代码实际注册的工具一致。
  * 挂载时 plugin-local 会校验清单；本不变量让仓库内 `verify-package-invariants`

package/lib/{json.d.ts → kernel/json.d.ts}

@@ -1,5 +1,5 @@
 /**
- * json.ts — 本地 JsonValue 类型（与 DSH 的 JsonValue 同构）
+ * kernel/json.ts — 本地 JsonValue 类型（与 DSH 的 JsonValue 同构）
  *
  * 纯层（fs-ops/cognitive-trajectory-ops）保持零 DSH 运行时依赖：仅用本地类型标注，
  * 工具层（defineTool）要求 execute 返回 DSH JsonValue，二者结构等价。

package/lib/{message-source.d.ts → kernel/message-source.d.ts}

@@ -1,5 +1,5 @@
 /**
- * message-source.ts — ACC 注入消息的来源标识（**单一真相源**，v1.47.0 / DSH 0.1.7-rc.1 适配）
+ * kernel/message-source.ts — ACC 注入消息的来源标识（**单一真相源**，v1.47.0 / DSH 0.1.7-rc.1 适配）
  *
  * **为什么有这个文件**：DSH 0.1.7-rc.1（session format v3→v4）把消息来源从
  * 「`kind: 'plugin'` ＋ `plugin` 字段」改成**每个生产者声明自己的 kind** ——

package/lib/{ports.d.ts → kernel/ports.d.ts}

@@ -1,5 +1,5 @@
 /**
- * ports.ts — ACC 对外面的**集中端口表**（C4 块 B，S142 2026-09-15）
+ * kernel/ports.ts — ACC 对外面的**集中端口表**（C4 块 B，S142 2026-09-15）
  *
  * 为什么存在（现状取证：`AGENT_SESSIONS/…/acc-c4c5-current-state.md` §③ 3.2-8）：
  * 端口此前**散在 4 处默认值**（`config-ops.defaultAdvancedSettings` / `settings-section` schema

package/lib/{time.d.ts → kernel/time.d.ts}

@@ -1,5 +1,5 @@
 /**
- * time.ts — ACC **时间呈现的单一真相源**（S142 2026-09-17，所有者令：「统一 ACC 所有使用时间的地方使用当地时区」）
+ * kernel/time.ts — ACC **时间呈现的单一真相源**（S142 2026-09-17，所有者令：「统一 ACC 所有使用时间的地方使用当地时区」）
  *
  * ── 存在的理由：**把"时刻"与"呈现"分开**（R↓）
  *