@shgroup/dsh-serenity-hooks 1.70.0 → 1.72.0

package/lib/settings-lt1i3OZv.js

@@ -0,0 +1,403 @@
+import { f as hostSettings } from "./ccc-roots-jZYR2GVE.js";
+import { _ as resolveInside, g as readUtf8 } from "./ccc-Dkoa2oW3.js";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/kernel/constants.ts
+/** 常量（纯模块，零 DSH 依赖） */
+/** 本包名 —— 上溯定位包根时的**身份核对**（同名目录家的邻居不会误命中） */
+const PACKAGE_NAME = "@shgroup/dsh-serenity-hooks";
+/** 上溯层数上限（源码态最深 `src/<域>/<子域>/` ／ 发布态 `lib/` ⇒ 8 层足够，且**保证有界**） */
+const MAX_ROOT_ASCENT = 8;
+/**
+* 包根 = 含**本包** `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 起点目录（缺省 = 本模块所在目录；测试可注入）
+*/
+function findPackageRoot(start) {
+	let dir = start ?? dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < MAX_ROOT_ASCENT; i += 1) {
+		try {
+			if (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).name === PACKAGE_NAME) return dir;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* ACC 版本：自动从 package.json 读取（单一真相源，消除与 CHANGELOG 的漂移）。
+* 发布时只需改 package.json 的 version。
+*/
+const ACC_VERSION = (() => {
+	try {
+		const root = findPackageRoot();
+		if (root === null) return "0.0.0";
+		return JSON.parse(readFileSync(join(root, "package.json"), "utf-8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+})();
+//#endregion
+//#region src/role/skiff/config.ts
+/**
+* role/skiff/config.ts — skiff 约束面的**纯逻辑助手**（零 DSH 依赖，可独立单测）
+*
+* ## 2026-10-19 重做后的职责边界（R↓，别再混起来）
+*
+* | 模块 | 管什么 |
+* |---|---|
+* | `./profile.ts` | **判据 + 读盘**（"这是不是 skiff"、"约束面是什么"） |
+* | `./config.ts`（本文件） | **从约束面派生出的纯函数**（白名单集合、提示词读取器、基础提示词文本） |
+* | `./core.ts` | 会话创建/复用、提问、守门查询 |
+*
+* ⇒ 本文件**不再读 `serenity.json`**：`skiff.roles` 整段已退役（owner 2026-10-19 重做）。
+* 它只接收一个已解析好的 `SkiffProfile`，因此**不涉及任何 IO**（除提示词文件，那是刻意懒读的）。
+*/
+/** 白名单推导 ────────────────────────────────────────────────────────────── */
+/** 提示词来源提示串（`apply` 回执与面板共用；避免两处措辞漂） */
+const SKIFF_PROFILE_HINT = "systemPromptFile hot-reloads by mtime; the rest of skiff.json is re-read every turn";
+/**
+* 该 skiff 会话**可见**的工具面（tools ∪ `msm`）。
+*
+* 🔴 `msm` 为什么自动加入：`msms` 非空意味着这个 skiff **有 MSM 通道**，
+* 而 MSM 的唯一合法调用入口是 `msm` 工具（单入口纪律）——不给它 `msm` 就等于
+* 声明了一堆调不动的能力。⚠️ 这是**并集**，不是覆盖：`tools` 里显式写的照旧生效。
+*/
+function profileToolWhitelist(profile) {
+	const out = /* @__PURE__ */ new Set();
+	for (const t of profile?.tools ?? []) out.add(t);
+	if ((profile?.msms?.length ?? 0) > 0) out.add("msm");
+	return out;
+}
+/** 该 skiff 会话可 exec 的 MSM 白名单（`msm` 工具内部再过滤；独立于工具白名单） */
+function profileMsmWhitelist(profile) {
+	return new Set(profile?.msms ?? []);
+}
+/** 轨迹纪律参与项（`profile` 缺省已在 `readSkiffProfileAt` 归一为全 true） */
+function profileCognitiveTrajectory(profile) {
+	return {
+		session: profile?.cognitiveTrajectory.session === true,
+		keeper: profile?.cognitiveTrajectory.keeper === true,
+		rebuild: profile?.cognitiveTrajectory.rebuild === true
+	};
+}
+/**
+* 解析约束面声明的**系统提示词全文**（一次性读取；`create` / `validate` / `list` 用）。
+*
+* 顺序：`systemPromptFile`（**推荐**：超长提示词在 JSON 里内嵌不可读）→ 内嵌 `systemPrompt` → 空串。
+* 文件缺失/逃逸 ⇒ **抛错**（调用方 catch 降级；`validate` 据此报 issue）。
+*
+* ⚠️ 热路径**不用**它（那会用每次工具调用去读盘）——热路径用 `createProfilePromptReader`。
+*/
+function resolveProfileSystemPrompt(root, profile) {
+	if (!profile) return "";
+	const file = profile.systemPromptFile?.trim();
+	if (file) {
+		const abs = resolveInside(root, file);
+		if (!existsSync(abs)) throw new Error(`skiff "${profile.code}": systemPromptFile "${file}" not found (resolved: ${abs})`);
+		return readUtf8(abs).trim();
+	}
+	return profile.systemPrompt ?? "";
+}
+/** 提示词来源（`list`/`validate` 展示用） */
+function profileSystemPromptSource(profile) {
+	if (profile?.systemPromptFile?.trim()) return "file";
+	if (profile?.systemPrompt?.trim()) return "inline";
+	return "none";
+}
+/**
+* 提示词**读取器**（长期热更新；改文件即生效，无需重启）。
+*
+* 为什么返回函数而不是字符串（R↓，实证代价）：旧实现在创建时把提示词**快照**进系统提示词段闭包
+* ⇒ CCC 改了提示词文件必须重启 dsh web 才生效（实测：改完 18KB 提示词，live agent 仍用旧文本）。
+* 现形态由系统提示词段的 `text()` **每轮调用**本读取器：
+*   - `systemPromptFile`：按 **mtime + size** 缓存重读（命中缓存零 IO；未变不解析）
+*   - 内嵌 `systemPrompt`：静态（改 JSON 仍需重载配置，这与文件热更的差别是**必然**的 —— 文件有 mtime，JSON 没有）
+*   - 读取失败：返回**上次成功内容**（⛔ 绝不返回空——空提示词会让角色失去人格与纪律），并按标签去重告警一次
+*
+* @param root CCC 根
+* @param profile 约束面
+*/
+function createProfilePromptReader(root, profile) {
+	const file = profile?.systemPromptFile?.trim();
+	if (!file) {
+		const inline = profile?.systemPrompt ?? "";
+		return () => inline;
+	}
+	let abs = null;
+	try {
+		abs = resolveInside(root, file);
+	} catch (err) {
+		console.warn(`[serenity-hooks] ✗ skiff 提示词路径非法（${file}）: ${String(err?.message ?? err)}`);
+	}
+	if (abs === null) return () => "";
+	const absPath = abs;
+	let cachedMtime = -1;
+	let cachedSize = -1;
+	let cachedText = "";
+	let warned = false;
+	return () => {
+		try {
+			const st = statSync(absPath);
+			if (st.mtimeMs === cachedMtime && st.size === cachedSize) return cachedText;
+			const text = readUtf8(absPath).trim();
+			const isReload = cachedMtime !== -1;
+			cachedMtime = st.mtimeMs;
+			cachedSize = st.size;
+			cachedText = text;
+			warned = false;
+			if (isReload) console.info(`[serenity-hooks] ↻ skiff 提示词已热重载（${file}，${text.length} 字符）`);
+			return text;
+		} catch (err) {
+			if (!warned) {
+				warned = true;
+				console.warn(`[serenity-hooks] ✗ skiff 提示词读取失败（${file}）——沿用上次成功内容: ${String(err?.message ?? err)}`);
+			}
+			return cachedText;
+		}
+	};
+}
+/**
+* skiff 基础提示词（dsp 只给这部分；CCC 的 `systemPrompt` 段由调用方拼接）。
+*
+* ## 🔴 为什么**不再枚举**清单（owner 2026-10-19 令）
+*
+* 旧版在这里抄了两份清单（`MSMs: a, b, c` / `Tools: read, grep, …`）。那是**第二真相源**，
+* 而真相源本来就在模型自己手里：
+*   · **工具清单** = 这一轮实际注册给它的 tool schema —— 模型已经看得见，抄一遍只会漂
+*   · **MSM 清单** = `msm()` 无参调用返回的目录 —— 已按白名单过滤，且**每次实时读配置**
+*
+* ⚠️ **漂移不是理论风险，是已发生的缺陷**（2026-10-19）：角色配置早就长到 8 个工具，
+* 而这个函数是从**创建时冻结的快照**求值的 ⇒ 提示词里一直写着旧的 4 个
+* ⇒ 模型照着提示词办事，**它自己以为没有的能力就不去调** ⇒ 症状是"工具用不了"，
+* 而守卫那边（每调用实时读配置）其实是放行的。两个真相源打架，输的总是提示词。
+*
+* ⇒ 现在只声明**边界与发现路径**，不抄内容：清单在哪，怎么取，越界会怎样。
+*
+* @param code 轨迹编码（skiff 的身份 —— 不是"角色名"，那个概念已退役）
+*/
+function buildSkiffBasePrompt(code) {
+	return [
+		"=== Serenity Skiff ===",
+		`Cognitive trajectory: ${code} (this is the trajectory you ARE, not a role you play)`,
+		"Your capability boundary is enforced mechanically by this CCC — anything outside it is rejected at the call site, not by your judgment.",
+		"Discover your surface, do not memorize it (both are generated from the live config on every turn):",
+		"  · Your tools are exactly the tool schemas you see in this session — if a tool is not in your schema, it is not available.",
+		"  · Your MSMs are listed by calling msm() with no arguments — that directory is already filtered to this trajectory.",
+		"  · Usage for any MSM: msm(\"<name>\", [], inspect=true) or pass \"--help\" as the first argument.",
+		"Do not infer unavailability from anything you remember or from an earlier list: this surface changes when the CCC configuration changes, and it takes effect without restarting.",
+		"",
+		"---",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/kernel/ports.ts
+/**
+* 集中端口表。
+* A=宿主主面（插件不监听）/ B=网关（可配，默认关）/ C=微信发送（默认开，仅 loopback）
+* / D=Skiff 调试（默认关）。
+*/
+const FACE_PORTS = {
+	main: {
+		port: 3080,
+		host: null,
+		defaultEnabled: true,
+		meaning: "宿主 DSH 主 WebUI + 插件 /serenity/* 路由面（**插件不起此 listener**，端口自宿主读）"
+	},
+	gateway: {
+		port: 3081,
+		host: "0.0.0.0",
+		defaultEnabled: false,
+		meaning: "双端口网关（外部登录 + 全量反代宿主主面；host/port 走 plugin 全局配置）"
+	},
+	weixinSend: {
+		port: 3082,
+		host: "127.0.0.1",
+		defaultEnabled: true,
+		meaning: "微信主动发送面（容器外进程 → POST /send；与 3080 显式解耦，不经网关）"
+	},
+	skiffDebug: {
+		port: 3099,
+		host: "127.0.0.1",
+		defaultEnabled: false,
+		meaning: "Skiff 调试问答面（人工调试子角色；无认证，仅靠 loopback）"
+	}
+};
+/** 宿主主 WebUI 端口（面 A：插件**不监听**，只读取；`readWebPort` 的回退值） */
+const MAIN_WEB_PORT = FACE_PORTS.main.port;
+/** 网关端口默认值（面 B） */
+const GATEWAY_PORT = FACE_PORTS.gateway.port;
+/** 微信主动发送端口默认值（面 C） */
+const WEIXIN_SEND_PORT = FACE_PORTS.weixinSend.port;
+/** Skiff 调试页端口默认值（面 D） */
+const SKIFF_DEBUG_PORT = FACE_PORTS.skiffDebug.port;
+/**
+* **机制端口**词表（output-guard 用：agent 在**用户可见输出**里提及内部端口即打回）。
+*
+* 由 {@link FACE_PORTS} 机械派生 ⇒ 与面清单**永不漂移**。
+* ⚠️ 修复记录（C4 块 B，2026-09-15）：旧常量硬写 `['3080','3081','3099','3100']`
+* ——**漏 3082**（微信发送面，默认开）⇒ 守卫拦不住"3082"这类提及。现由表派生，四面齐全。
+* ⚠️ 面变更记录（2026-10-15）：**面 E（3100 ACP/问答）已整体退役**（owner 裁「砍掉外部问答」）
+* ⇒ 本词表随之少一项，**无需另改**（这正是"派生而非手抄"的收益）。
+*/
+const MECHANISM_PORTS = Object.keys(FACE_PORTS).map((id) => String(FACE_PORTS[id].port));
+//#endregion
+//#region src/surface/settings.ts
+/**
+* 设置面板命名空间 = **profile 条目 id**（v0.1.7 起；与旧 `settings.yaml` 段名逐字相同）。
+*/
+const SERENITY_SETTINGS_NS = "serenity-hooks";
+/** 进程级默认（无 Config 可读时的兜底；与 Config 各字段的缺省一致） */
+function defaultSimpleSettings() {
+	return {
+		gatewayEnabled: false,
+		rebuildThresholdK: 400,
+		skiffEnabled: false,
+		skiffDebugPort: SKIFF_DEBUG_PORT,
+		croEnabled: true,
+		diagramEnabled: false,
+		humanChannel: defaultHumanChannelSettings()
+	};
+}
+/**
+* volatile 字段的**结构化解包**（v1.47.2；本文件读取语义的第一道）。
+*
+* ## 为什么必须有它（两个事实的合成，缺一即错）
+* ① **0.1.7 的面板层字段必须标 `.volatile()`** —— 否则本插件命名空间整个不进宿主的
+*    `settings.describe()`（`volatileForm()` 只认 `meta.volatile`）⇒ **设置面板那一节消失**。
+* ② **标了之后，运行期拿到的是引用包装，不是裸值** —— schemastery 的 `Schema.resolve()` 对
+*    `meta.volatile` **无条件**包 `createVolatile(value)`，且该分支排在"缺省值回退"那一段
+*    **之前** ⇒ **"用户没设过"的字段也是恒真对象**（`.get()` 返回 `undefined`），**不是 `undefined`**。
+*
+* ⇒ 若这里不解包，下面十行的 `??` 链会**短路在这层包装上** ⇒ 网关 / Skiff 会被
+* **无意打开**（比"面板不显示"更坏：静默改变对外暴露面）。
+*
+* ## 为什么用结构判定
+* 可观察形状就是"有 `get()`"（cosmokit 的 `isVolatile` 也这么判）；本模块不引它的运行时依赖。
+*
+* @param value - volatile 引用 ｜ 裸值 ｜ undefined
+* @returns 解包后的裸值（引用 ⇒ `.get()`；裸值原样；缺省 ⇒ `undefined`）
+*/
+function unwrapVolatile(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value.get === "function") return value.get();
+	return value;
+}
+/** human-channel 的内建缺省（与 `Config` 的 schema 缺省**同源**：这里是读取面，那里是解析面） */
+function defaultHumanChannelSettings() {
+	return {
+		accounts: [],
+		subscriptions: [],
+		relayCcc: null,
+		sendingAllow: ["*"]
+	};
+}
+/** 取"有内容的字符串"（首尾空白剥掉；空白串 ⇒ `undefined`）—— 面板空文本框会写 `''`，那是"没填"不是"填了个空名" */
+function nonEmptyText(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/**
+* `humanChannel` 片段 → 运行时归一形态。**优先级：显式值 > 内建缺省**（与 `simpleSettingsFromConfig` 同族）。
+*
+* 🔴 三处"缺省 vs 显式"的语义差别，别写反：
+*  ① `sending.allow: []` ⇒ **`[]`**（"谁都不许"），**不是**回退到 `['*']` —— 故用 `??`
+*     （只对 `undefined`/`null` 回退）。⚠️ **别拿 `??`→`||` 当变异探针**：空数组在 JS 里是
+*     **真值** ⇒ 两种写法在这个输入上**恰好同效**，那是**非变异**（会得出"测试不承重"的假结论）。
+*  ② `relay.ccc` 空白 ⇒ `null`（"没填"与"没这一项"同义），**不是**把空白当 CCC 名；
+*  ③ 账号 `enabled` 缺省 **true**（老账号表里 `enabled` 不写就是开）。
+*
+* 🔴 **旧 CCC 侧 `weixin.*` 不在这里、也不该在这里**：机器级面**只**认 `humanChannel`
+*   （硬切无别名，同 D61 先例）⇒ 传进来的旧键**一律不进结构**（回归钉见
+*   `tests/human-channel-config.test.ts`；CCC 侧旧读取面的退役在 P0-2~P0-4）。
+* @param fragment - `Config.humanChannel`（可能整个不存在 —— 那是**合法**初始态）
+* @returns 归一形态（永不 `undefined`）
+*/
+function humanChannelSettingsFromConfig(fragment) {
+	const d = defaultHumanChannelSettings();
+	if (!fragment) return d;
+	return {
+		accounts: (fragment.accounts ?? []).map((a) => ({
+			id: nonEmptyText(a?.id),
+			channel: nonEmptyText(a?.channel),
+			enabled: a?.enabled !== false,
+			token: a?.token,
+			userId: a?.userId
+		})),
+		subscriptions: (fragment.subscriptions ?? []).map((s) => ({
+			account: nonEmptyText(s?.account),
+			user: nonEmptyText(s?.user),
+			ccc: nonEmptyText(s?.ccc),
+			role: nonEmptyText(s?.role)
+		})),
+		relayCcc: nonEmptyText(fragment.relay?.ccc) ?? d.relayCcc,
+		sendingAllow: fragment.sending?.allow ?? d.sendingAllow
+	};
+}
+/**
+* Config（宿主 Loader 校验后的解析值）→ 扁平简单配置。**本文件唯一的读取语义**。
+*
+* 优先级：**面板层（扁平键）> 部署层（嵌套段）> 内建缺省**。
+* @param config - 插件 Config（`fiber.config` 或 apply 收到的 config）
+* @returns 扁平开关集合
+*/
+function simpleSettingsFromConfig(config) {
+	const d = defaultSimpleSettings();
+	return {
+		gatewayEnabled: unwrapVolatile(config.gatewayEnabled) ?? config.gateway?.enabled ?? d.gatewayEnabled,
+		rebuildThresholdK: unwrapVolatile(config.rebuildThresholdK) ?? config.rebuild?.thresholdK ?? d.rebuildThresholdK,
+		skiffEnabled: unwrapVolatile(config.skiffEnabled) ?? config.skiff?.enabled ?? d.skiffEnabled,
+		skiffDebugPort: unwrapVolatile(config.skiffDebugPort) ?? config.skiff?.debugPort ?? d.skiffDebugPort,
+		croEnabled: unwrapVolatile(config.croEnabled) ?? d.croEnabled,
+		diagramEnabled: unwrapVolatile(config.diagramEnabled) ?? config.diagram?.enabled ?? d.diagramEnabled,
+		humanChannel: humanChannelSettingsFromConfig(config.humanChannel)
+	};
+}
+/** 运行时源（`registerSettingsSection` 装配：读本插件 fiber 的**当前** Config） */
+let simpleSource = null;
+/**
+* 读取当前简单配置（各功能 gateway/rebuild/skiff/… 的启动与运行时判断都经此）。
+*
+* 源 = 本插件 fiber 的 `config`（宿主在配置变更时走 `fiber.update()` ⇒ `config` 始终最新，
+* **不必**依赖 apply 重跑，也不必缓存）。
+* @returns 扁平开关集合
+*/
+function readSimpleSettings() {
+	return simpleSource ? simpleSource() : defaultSimpleSettings();
+}
+/**
+* 装配简单配置读取面（v1.21 分层；**v0.1.7 起不再注册任何 section**）。
+*
+* 两件事：
+*  1. 把"本插件自己的 Config"接成简单配置源 —— 读 `ctx.fiber.config`（宿主 `fiber.update()`
+*     保证最新），拿不到 fiber 时退回 apply 收到的 `config`。
+*  2. 关掉宿主按 Config schema **自动生成**的通用页（`settings.configure({ auto: false })`）——
+*     门面是我们的自定义页 `client/SettingsSection.tsx`（同一个命名空间，同一份数据）。
+*
+* ⚠️ 两个失败都不阻断插件装载（面板是附属能力，绝不能成为启动单点）。
+* @param ctx - 插件上下文
+* @param config - apply 收到的 Config（fiber.config 不可用时的兜底）
+*/
+function registerSettingsSection(ctx, config) {
+	const fiber = ctx.fiber;
+	const readConfig = () => fiber?.config ?? config;
+	simpleSource = () => simpleSettingsFromConfig(readConfig());
+	const settings = hostSettings(ctx);
+	try {
+		settings?.configure?.({ auto: false }, fiber);
+	} catch {}
+}
+//#endregion
+export { resolveProfileSystemPrompt as _, GATEWAY_PORT as a, SKIFF_DEBUG_PORT as c, buildSkiffBasePrompt as d, createProfilePromptReader as f, profileToolWhitelist as g, profileSystemPromptSource as h, FACE_PORTS as i, WEIXIN_SEND_PORT as l, profileMsmWhitelist as m, readSimpleSettings as n, MAIN_WEB_PORT as o, profileCognitiveTrajectory as p, registerSettingsSection as r, MECHANISM_PORTS as s, SERENITY_SETTINGS_NS as t, SKIFF_PROFILE_HINT as u, ACC_VERSION as v, findPackageRoot as y };

package/lib/{skills-discovery.d.ts → skills/discovery.d.ts}

@@ -1,5 +1,5 @@
 /**
- * skills-discovery.ts — CCC 入口 skill 自动发现（纯逻辑，零 DSH 依赖）
+ * skills/discovery.ts — CCC 入口 skill 自动发现（纯逻辑，零 DSH 依赖）
  *
  * 发现全部入口技能（原文全量，不截断）—— **现行三个来源**（原为四个，**来源 3 已于 2026-09-21 删除**）：
  *   0. **`.serenity` 记号文件内容 = 顶层入口 skill 名**（CCC 记号文件的权威语义）—— 最高优先

package/lib/skills/resource-index.d.ts

@@ -14,7 +14,7 @@
  * 六条硬性规则（逐条对应设计 §4.2，改这里先改那里）：
  *   ① **只枚举，不注入正文** —— 索引里**绝不**出现任何参考文件的正文；
  *   ② **确定性排序** = 相对路径的 **UTF-8 字节序**（🔴 **不用 mtime**：mtime 随检出漂移，
- *      会让每请求的注入文本抖动；对照 `src/cro.ts:101` 那份**落盘快照**用 {name,bytes,mtime} ——
+ *      会让每请求的注入文本抖动；对照 `src/wake/cro.ts:101` 那份**落盘快照**用 {name,bytes,mtime} ——
  *      **同一件事两处的取舍相反，那个差异是判据不是巧合**）；
  *   ③ **有界 ＋ 响亮** —— 条数/字符各有上限，超出**必须显式写出还剩多少项**，**绝不静默截断**；
  *   ④ **摘要可复现** —— 取该文件首个 `#` 标题（剥 markdown 记号）；取不到 ⇒ 留空，**不编**；
@@ -30,7 +30,7 @@
  *
  * 🔴 **两个面，两个入口**（2026-10-12 增；owner 裁决 O2）—— 同源、但成本形态不同：
  *    · **载入面** `buildResourceIndex()` —— 完整索引（名字 ＋ 首标题 ＋ 字节），带 `.md` 文件头读取；
- *      在三条路径上各附一次：入口段（`system-prompt.ts` order −50）／轨迹段（`cognitive-trajectory-skills.ts`
+ *      在三条路径上各附一次：入口段（`system-prompt.ts` order −50）／轨迹段（`trajectory/skills.ts`
  *      order −45）／目录 provider 的 `get()`（`opencode-skills.ts`）。
  *    · **目录面** `buildResourceNameSuffix()` —— **只有名字**，**不读任何正文**；只挂一处：
  *      目录 provider 的 `list()`（`available_skills` 的 `SkillSummary.description`）。

package/lib/{face-host.d.ts → surface/faces.d.ts}

@@ -1,5 +1,5 @@
 /**
- * face-host.ts — **面宿主**：插件自起 HTTP listener 的唯一生命周期处（C4 块 A，S142 2026-09-15）
+ * surface/faces.ts — **面宿主**：插件自起 HTTP listener 的唯一生命周期处（C4 块 A，S142 2026-09-15）
  *
  * ## 现状 → 本模块要收掉什么（取证：`…/acc-c4c5-current-state.md` §①/§③ 3.1）
  *
@@ -8,7 +8,7 @@
  * ⇒ 仍保有面 B/C/D 三个；本段保留"当年是四个"的记述，因为下方"两套拆卸"的病史由它解释。
  * 此前四处各写一份同款样板：`createServer` + `server.once('error')` +
  * `listen(port, host)` + 模块级 `active` 变量 + `close()`；拆卸也分裂成**两套**——
- * `seams/lifecycle.ts` 有一个聚合 disposer，而 `gateway.ts` 与 `weixin-send-api.ts`
+ * `seams/lifecycle.ts` 有一个聚合 disposer，而 `gateway/server.ts` 与 `im/send.ts`
  * **各自另注册**一个（D/E 干脆没有自己的 disposer）。
  *
  * 本模块把"listener 生命周期"收成一处：**active 表 + 统一 listen/close + 统一错误与端口占用
@@ -17,7 +17,7 @@
  * ## 🔴 共享的是「生命周期与样板」，**绝不是**「路由 / 监听器 / 鉴权」
  *
  * 每个面**保留自己的 listener、自己的路由、自己的鉴权**（`handler` 内部原样不动）：
- *   · **A ↔ C 解耦**（`weixin-send-api.ts:4-7`）：3080 会被 3081 原样反代（连请求头），
+ *   · **A ↔ C 解耦**（`im/send.ts:4-7`）：3080 会被 3081 原样反代（连请求头），
  *     把 3082 的端点挂到 3080 上 = 已登录的外部家庭账号即可冒充 bot 发消息
  *     ⇒ 本模块**不提供**"把面挂到别的面"的能力，也不共享路由表；
  *   · （原 **E ↔ D** 共用会话核心但各自独立 listener 一条，**随 E 退役删除**）；
@@ -64,7 +64,7 @@ export interface FaceSpec {
      *
      * 面 C（微信发送，`FACE_PORTS.weixinSend.defaultEnabled = true`）必须传 `true`：宿主若以
      * **一次性命令**方式跑（`dsh <cmd>` 用完即退），未 unref 的 listener 会拖着进程不退出。
-     * 这是 C4 之前 `weixin-send-api.ts` 的原语义（C4 归一到面宿主时丢失），现逐字恢复。
+     * 这是 C4 之前 `im/send.ts` 的原语义（C4 归一到面宿主时丢失），现逐字恢复。
      */
     unref?: boolean;
 }

package/lib/{api.d.ts → surface/http.d.ts}

@@ -1,5 +1,5 @@
 /**
- * api.ts — HTTP 状态接口（WebUI 停靠栏数据源/开关通道 + 图片落盘）
+ * surface/http.ts — HTTP 状态接口（WebUI 停靠栏数据源/开关通道 + 图片落盘）
  *
  * 路由：
  *   GET  /serenity/status            ?workspace=<路径>  → 状态（root/accVersion/safeModeOn/...）
@@ -43,7 +43,7 @@ interface StatusApiRegistration {
  * 它就会**静默返回另一个 CCC 的路径**，于是面板把**别人的轨迹/技能/安全模式**当成你的显示出来。
  * 这比"显示未激活"危险得多 —— 用户会据此做判断（以为自己的 safe-mode 开着、以为那是自己的轨迹）。
  *
- * 修法与既有先例一致（`rebuild.ts` 对"跨轨迹猜测"的裁决：**响亮失败优于静默接错**）：
+ * 修法与既有先例一致（`trajectory/rebuild.ts` 对"跨轨迹猜测"的裁决：**响亮失败优于静默接错**）：
  * **多个候选 ⇒ 不猜**。只有当 live sessions 里的 CCC 根**唯一**时才采用它
  * （那正是 v1.22.2 要救的场景：单 CCC 部署 + 远程访问缺 sessionId）；
  * 一旦出现**两个及以上**不同 CCC 根，就退回进程 cwd（→ 面板显示"未激活"），绝不挑一个顶替。

package/lib/{container-status.d.ts → surface/observation.d.ts}

@@ -1,5 +1,5 @@
 /**
- * container-status.ts — 容器状态模型的**取数层唯一出口**（C5「观察面归一」，S142 2026-09-15）
+ * surface/observation.ts — 容器状态模型的**取数层唯一出口**（C5「观察面归一」，S142 2026-09-15）
  *
  * 为什么存在（R↓）：ACC 有多个观察面（`dashboard health` / `acc-diag` / WebUI 面板 /
  * 系统提示词注入），它们读的是同一批宿主事实。此前"这些事实怎么取"写在**每个消费方各自的
@@ -17,19 +17,19 @@
  * 依赖分层（为什么本模块"重"而 `kit-ops` / `status` 保持"轻"）：
  *  {@link containerClocks} 必须读 `wake-scheduler` 的进程内快照，而该模块带 **@deepseek-ai 值依赖**
  *  （`dsh-llm` 的 `createUserMessage`）。故本模块**只能**被本就重型或异步的消费方使用：
- *  `diag-ops`（静态 import）、`api.ts` / `kit-ops`（`await import(...)`，与 `api.ts` 既有的
+ *  `diag-ops`（静态 import）、`surface/http.ts` / `kit-ops`（`await import(...)`，与 `surface/http.ts` 既有的
  *  "保持静态链纯净"约定一致）。**轻链模块不得静态 import 本模块**。
  *
  * 已有的单一真相源继续指向原处（**不复制**）：
- *  L0 根解析 `ccc.ts findSerenityRoot`｜L1/L2 根与枚举 `ccc-roots.ts`｜宿主契约 `host/contract.ts`
- *  ｜CCC 配置 `ccc.ts loadSerenityConfig`｜注册表 `msm-ops.ts`｜时钟 `wake-scheduler.ts`
- *  ｜唤醒注册表 `wake-registry.ts`。
+ *  L0 根解析 `kernel/ccc.ts findSerenityRoot`｜L1/L2 根与枚举 `kernel/ccc-roots.ts`｜宿主契约 `host/contract.ts`
+ *  ｜CCC 配置 `kernel/ccc.ts loadSerenityConfig`｜注册表 `tools/msm/service.ts`｜时钟 `wake/scheduler.ts`
+ *  ｜唤醒注册表 `wake/registry.ts`。
  */
-import { type HostContractReport } from './host/contract.js';
-import { checkRegistryQuality, type RegistryQualityReport } from './msm-ops.js';
-import { type WakeEntry } from './wake-registry.js';
-import { wakeSchedulerState } from './wake-scheduler.js';
-import type { JsonValue } from './json.js';
+import { type HostContractReport } from '../host/contract.js';
+import { checkRegistryQuality, type RegistryQualityReport } from '../tools/msm/service.js';
+import { type WakeEntry } from '../wake/registry.js';
+import { wakeSchedulerState } from '../wake/scheduler.js';
+import type { JsonValue } from '../kernel/json.js';
 export interface ContainerIdentity {
     /** CCC 根（调用方给定；null = 不在任何 CCC 内） */
     root: string | null;
@@ -58,7 +58,7 @@ export interface ContainerPrinciples {
 }
 /**
  * 三原则取数。
- * ⚠️ 与 `ccc.ts` 的 P1/P2 原语是**同一实现**（`existsSync(.serenity)` / `findGitRoot`），
+ * ⚠️ 与 `kernel/ccc.ts` 的 P1/P2 原语是**同一实现**（`existsSync(.serenity)` / `findGitRoot`），
  * 本函数只把它们组装成"一次检查"的形状；判定语义未变（P1 要求文件非空、P2 要求 `.git` 存在）。
  */
 export declare function containerPrinciples(root: string | null): ContainerPrinciples;
@@ -71,7 +71,7 @@ export interface RegistryStructureReport {
     issues: string[];
 }
 /**
- * **判据 A —— 注册表「结构完整性」**（原 `kit-ops.ts checkRegistryHealth`，C5 迁入本模块）。
+ * **判据 A —— 注册表「结构完整性」**（原 `tools/kit/service.ts checkRegistryHealth`，C5 迁入本模块）。
  *
  * 回答的问题：**这张表坏没坏**——文件能不能被安全解析（JSON 合法 / 顶层形状 / entry 字段类型 /
  * name 全局唯一 / path 在根内且脚本存在）。
@@ -90,7 +90,7 @@ export interface RegistryStructureReport {
  */
 export declare function checkRegistryHealth(root: string): RegistryStructureReport;
 /**
- * **判据 B —— 注册表「质量契约」**（DC-M1~M4；实现在 `msm-ops.ts checkRegistryQuality`，
+ * **判据 B —— 注册表「质量契约」**（DC-M1~M4；实现在 `tools/msm/service.ts checkRegistryQuality`，
  * 执行面 `container_admin msm check` 亦走它）。
  *
  * 与判据 A 的关系见 {@link checkRegistryHealth} 的对照注释——**两条判据、两个名字、两份结论**。
@@ -99,7 +99,7 @@ export declare function checkRegistryHealth(root: string): RegistryStructureRepo
 export { checkRegistryQuality, type RegistryQualityReport };
 /**
  * 进程内时钟快照类型。
- * ⚠️ 形状由**时钟模块自身**定义（`wake-scheduler.ts` 未导出的 `WakeSchedulerRuntime`）——故此处
+ * ⚠️ 形状由**时钟模块自身**定义（`wake/scheduler.ts` 未导出的 `WakeSchedulerRuntime`）——故此处
  * 直接取其返回类型。2026-09-15：原为「唤醒调度器 ∪ autopilot」联合（两者诊断字段同规格但类型
  * 不同）；autopilot 时钟随 ACC 侧 autopilot 退场删除后，**只剩一座钟**（唤醒调度器）。
  */
@@ -112,7 +112,7 @@ export interface ContainerClocks {
  * 时钟的进程内状态（"为什么这轮没被唤起"的第一手判据）。
  *
  * 🔴 **只读快照，不重算**（设计红线）：`armed`/`ticks`/`lastTickAt`/`lastSkipReason` 只存在于
- * 调度器自己的模块级运行时对象里（`wake-scheduler.ts schedulerRuntime`）。任何"从配置或文件
+ * 调度器自己的模块级运行时对象里（`wake/scheduler.ts schedulerRuntime`）。任何"从配置或文件
  * 重新推导"得到的值都会与真实调度器的状态不一致——那比没有可观测量更糟（会给出假的"一切正常"）。
  */
 export declare function containerClocks(): ContainerClocks;
@@ -146,7 +146,7 @@ export interface ContainerStatus {
          */
         quality: RegistryQualityReport | null;
     };
-    /** CCC 配置（`ccc.ts loadSerenityConfig`；无根 → null） */
+    /** CCC 配置（`kernel/ccc.ts loadSerenityConfig`；无根 → null） */
     config: JsonValue | null;
     /** 宿主契约（进程内唯一来源，见 `host/contract.ts hostContractReport`） */
     hostContract: HostContractReport | null;

package/lib/{settings-section.d.ts → surface/settings.d.ts}

@@ -1,5 +1,5 @@
 /**
- * settings-section.ts — 简单配置读取（dsh 原生设置面板；v1.21 分层，**v1.47 A 案移植到 0.1.7 表单模型**）
+ * surface/settings.ts — 简单配置读取（dsh 原生设置面板；v1.21 分层，**v1.47 A 案移植到 0.1.7 表单模型**）
  *
  * 分层决策（S142）：**简单配置（开关/阈值）→ dsh 原生设置面板**；
  * **复杂配置（账号列表）→ 宁静号高级面板**（localstore + /serenity/config）。

package/lib/{status.d.ts → surface/status.d.ts}

@@ -1,10 +1,10 @@
 /**
- * status.ts — 状态与安全模式操作（纯逻辑，零 DSH 依赖，可独立单测）
+ * surface/status.ts — 状态与安全模式操作（纯逻辑，零 DSH 依赖，可独立单测）
  *
  * WebUI 停靠栏的数据源：ACC 版本 / CCC 根 / safe-mode 状态 / 黑名单 / keeper 阈值 / cheap-worker 模型。
  * setSafeMode 直接读写 .serenity-safe-on 标记（守卫实时读取，写即生效）。
  */
-import { type TrajectorySummary } from './cognitive-trajectory-ops.js';
+import { type TrajectorySummary } from '../trajectory/core.js';
 /**
  * 🔴 **布局无关档**：从**正在跑的那个入口脚本**反推宿主包根，读它的 `version`。
  *

package/lib/{usage-stats.d.ts → surface/usage.d.ts}

@@ -1,5 +1,5 @@
 /**
- * usage-stats.ts — ACC 用量统计（**skill 加载次数** ＋ **MSM 执行次数**；落该 CCC 的 `_tmp`）
+ * surface/usage.ts — ACC 用量统计（**skill 加载次数** ＋ **MSM 执行次数**；落该 CCC 的 `_tmp`）
  *
  * ## 所有者令（本模块的存在理由）
  *
@@ -15,7 +15,7 @@
  * ⇒ 本模块让每个 CCC 留下一份**纯计数**账本：**用了哪个、多少次、第一次和最近一次是什么时候**。
  * 用途 = 清理/精简的**依据**（没有人用的东西与天天在用的东西，不再靠猜）。
  *
- * ## 🔴 铁律（与 `cro-log.ts` 同族）
+ * ## 🔴 铁律（与 `wake/cro-log.ts` 同族）
  *
  * **本模块每个导出函数都不抛错**：读盘 / 解析 / 写盘失败一律返回结构化失败，
  * 由调用方只记一行日志（或什么都不做）⇒ **统计的问题绝不影响工具执行与既有链路**。
@@ -30,8 +30,8 @@
  * ## 🔴 重启后必须续算（所有者令）
  *
  * 宿主会被重启（本容器实测 24h 内 3 次）⇒ 计数**不能只活在内存里**：
- * 每次写盘 = **读旧文件 → 在旧值上自增 → 原子写**（`tmp + rename`，与 `wake-registry.ts` /
- * `cro-log.ts` 同款形态）⇒ **进程重启后计数自然延续**，无需额外的 flush/落盘时机。
+ * 每次写盘 = **读旧文件 → 在旧值上自增 → 原子写**（`tmp + rename`，与 `wake/registry.ts` /
+ * `wake/cro-log.ts` 同款形态）⇒ **进程重启后计数自然延续**，无需额外的 flush/落盘时机。
  *
  * ## 口径（两个字段，勿合并）
  *

package/lib/{voyage-page.d.ts → surface/voyage/page.d.ts}

@@ -1,5 +1,5 @@
 /**
- * voyage-page.ts — `/serenity/voyage`：宁静号航行动画（**ACC 层静态资产**）
+ * surface/voyage/page.ts — `/serenity/voyage`：宁静号航行动画（**ACC 层静态资产**）
  *
  * 作用：把「宁静号航行动画」作为 **ACC 的一部分**随包分发，并用一条 HTTP 路由把它
  * 交给 WebUI。当前唯一消费者 = 会话头部状态胶囊展开卡片（`SafeModePanel` 的 `sp-pop`）
@@ -39,7 +39,7 @@ export declare function resetVoyageCache(): void;
 /**
  * 注册 `/serenity/voyage`（GET）。
  * @param opts.assetPath 覆盖资产路径（测试用；生产不传）
- * @param opts.resolveRoot 解析本次请求所属 CCC 根（生产由 api.ts 的 resolveWorkspace 提供）。
+ * @param opts.resolveRoot 解析本次请求所属 CCC 根（生产由 surface/http.ts 的 resolveWorkspace 提供）。
  *   🔴 **2026-10-18 新增**：词表按请求所属 CCC **运行时注入**（owner 报「在别的 CCC 点开
  *   显示的还是 home-serenity 的信息」）。不传 ⇒ 不注入（保持资产原样 = 旧行为）。
  */

package/lib/{voyage-vocab.d.ts → surface/voyage/vocab.d.ts}

@@ -1,5 +1,5 @@
 /**
- * voyage-vocab.ts — 航行页词表改为**按当前 CCC 运行时注入**（纯逻辑，零 DSH 依赖）
+ * surface/voyage/vocab.ts — 航行页词表改为**按当前 CCC 运行时注入**（纯逻辑，零 DSH 依赖）
  *
  * ## 为什么需要它（owner 2026-10-18 报的缺陷）
  * 资产 `assets/serenity-voyage.html` 的词表是**构建期扫描容器写死的常量**：