@shgroup/dsh-serenity-hooks 1.90.0 → 1.91.0

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.90.0",
+  "version": "1.91.0",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——14 个工具（container_fs/cognitive_trajectory/dashboard/container_git/msm/praxis/ontology/serenity-skill-creator/cheap-worker/localstore/container_admin；另三个 im-bridge/acc-diag/diagram 按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 认知轨迹日志与原地重建 + 网页登录入口/IM 桥/认知轨迹唤醒注册表。轨迹声明 = 轨迹目录下的 trajectory.json（约束面 + 旧标识 uid + CRO 机器绑定 cro.host；旧名 trajectory-constraint.json / skiff.json 仍在读取族里）；轨迹提示词 = 轨迹目录下的 PROMPT.md（一条轨迹「是谁、按什么章程工作」，所有轨迹通用，追加在容器层与质量层之后，不替换它们）。适配 DSH 0.1.7-rc.1 / 0.2.0-rc.1 / 0.2.1-rc.1（三档，deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/channels-CuCsUfcY.js

@@ -0,0 +1,602 @@
+import { f as hostSettings } from "./ccc-roots-WfktvbN8.js";
+import { c as readWeixinSettings, o as readImSettings } from "./route-DxIKWeN9.js";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+//#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,
+		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`**。
+*
+* ⇒ 若这里不解包，下面十行的 `??` 链会**短路在这层包装上** ⇒ 网关 / 轨迹约束 会被
+* **无意打开**（比"面板不显示"更坏：静默改变对外暴露面）。
+*
+* ## 为什么用结构判定
+* 可观察形状就是"有 `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,
+		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/轨迹约束/… 的启动与运行时判断都经此）。
+*
+* 源 = 本插件 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
+//#region src/im/log-scan.ts
+/**
+* im/log-scan.ts — 读聊天记录落盘，汇总出「与谁有过往来」（`contacts` 的数据源）
+*
+* ## 这个文件解决什么
+*
+* owner 2026-10-22：「配路由需要的是**账户到轨迹**，轨迹 CCC 知道，**账户 CCC 不知道**，
+* 需要有个能力让 CCC 查询用户配好的账户」。这里的"账户"= **通道用户**（对方是谁），
+* 不是 IM 账号（我们自己登录的身份，`status` 早就能查）。
+*
+* 那个 id（微信 `xxx@im.wechat` / 飞书 `ou_…`）不在任何配置文件里 ——
+* 它**只在聊天记录里出现过**。⇒ 本文件把记录读成联系人表。
+*
+* ## 🔴 两条硬边界
+*
+* 1. **只读**：本文件不写任何东西。真相源仍是那些 jsonl（append-only 事件流），
+*    本文件只是它的一次投影 —— ⛔ 不产生第二真相源。
+* 2. **不猜渠道**：事件的 `channel` 字段为准；缺它（存量事件）⇒ 按
+*    `accountId → im.accounts[].channel` 回填，仍取不到才落 `weixin`
+*    （那是该字段存在之前唯一的渠道）。⛔ **绝不按 userId 的形状猜**
+*    （`ou_` 前缀 / `@im.wechat` 后缀都是命名习惯，不是判据 —— D167 认族不认名）。
+*/
+/** 日志根目录族（**新旧两代并存**：`_im-logs/<channel>/` 与存量 `_weixin-logs/`） */
+const IM_LOG_DIR_NEW = "_im-logs";
+const IM_LOG_DIR_LEGACY = "_weixin-logs";
+/** 某 CCC 下**存在**的日志目录（相对根），新代在前 */
+function imLogRoots(root) {
+	const out = [];
+	const newBase = join(root, "AGENT_SESSIONS", IM_LOG_DIR_NEW);
+	const legacy = join(root, "AGENT_SESSIONS", IM_LOG_DIR_LEGACY);
+	if (existsSync(newBase)) out.push(join("AGENT_SESSIONS", IM_LOG_DIR_NEW));
+	if (existsSync(legacy)) out.push(join("AGENT_SESSIONS", IM_LOG_DIR_LEGACY));
+	return out;
+}
+/** 收集某个日志根下所有 `*.jsonl`（含 `_im-logs/<channel>/` 一层；按文件名排序） */
+function jsonlFilesIn(root, rel) {
+	const abs = join(root, rel);
+	const out = [];
+	let entries = [];
+	try {
+		entries = readdirSync(abs, { withFileTypes: true }).map((d) => d.name);
+	} catch {
+		return out;
+	}
+	for (const name of entries.sort()) {
+		if (name.startsWith(".")) continue;
+		if (name.endsWith(".jsonl")) {
+			out.push(join(rel, name));
+			continue;
+		}
+		if (rel === join("AGENT_SESSIONS", "_im-logs")) {
+			const sub = join(rel, name);
+			try {
+				for (const child of readdirSync(join(root, sub)).sort()) if (child.endsWith(".jsonl")) out.push(join(sub, child));
+			} catch {}
+		}
+	}
+	return out;
+}
+/** 从文件名 / 所在目录猜渠道（**只作为回填的最后一级**，不是判据） */
+function channelFromPath(rel) {
+	const parts = rel.split("/");
+	const idx = parts.indexOf(IM_LOG_DIR_NEW);
+	const candidate = idx >= 0 && parts.length > idx + 2 ? parts[idx + 1] : void 0;
+	return candidate !== void 0 && candidate !== "" ? candidate : null;
+}
+/**
+* 扫描本 CCC 的全部聊天记录，按 `(channel, userId)` 汇总。
+*
+* @param root CCC 根
+* @param accountChannel 存量事件缺 `channel` 时的回填表（`accountId → channel`）
+* @returns 汇总结果 ＋ **扫描域** ＋ 读取错误（三者都不可省）
+*/
+function scanImContacts(root, accountChannel = {}) {
+	const byKey = /* @__PURE__ */ new Map();
+	const sources = [];
+	const errors = [];
+	for (const rel of imLogRoots(root)) for (const fileRel of jsonlFilesIn(root, rel)) {
+		sources.push(fileRel);
+		let text = "";
+		try {
+			text = readFileSync(join(root, fileRel), "utf8");
+		} catch (err) {
+			errors.push(`${fileRel}: ${err instanceof Error ? err.message : String(err)}`);
+			continue;
+		}
+		const pathChannel = channelFromPath(fileRel);
+		for (const line of text.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed === "") continue;
+			let ev;
+			try {
+				ev = JSON.parse(trimmed);
+			} catch {
+				errors.push(`${fileRel}: 有 1 行不是合法 JSON（已跳过）`);
+				continue;
+			}
+			const userId = typeof ev.userId === "string" ? ev.userId.trim() : "";
+			if (userId === "") continue;
+			const accountId = typeof ev.accountId === "string" ? ev.accountId.trim() : "";
+			const channel = (typeof ev.channel === "string" && ev.channel.trim() !== "" ? ev.channel.trim() : null) ?? pathChannel ?? (accountId !== "" ? accountChannel[accountId] ?? null : null) ?? "weixin";
+			const key = `${channel}\u0000${userId}`;
+			let entry = byKey.get(key);
+			if (!entry) {
+				entry = {
+					channel,
+					userId,
+					accountIds: [],
+					roleAtEvent: null,
+					firstSeen: null,
+					lastSeen: null,
+					messages: 0
+				};
+				byKey.set(key, entry);
+			}
+			if (accountId !== "" && !entry.accountIds.includes(accountId)) entry.accountIds.push(accountId);
+			if (typeof ev.role === "string" && ev.role.trim() !== "") entry.roleAtEvent = ev.role.trim();
+			const ts = typeof ev.ts === "number" && Number.isFinite(ev.ts) ? ev.ts : null;
+			if (ts !== null) {
+				if (entry.firstSeen === null || ts < entry.firstSeen) entry.firstSeen = ts;
+				if (entry.lastSeen === null || ts > entry.lastSeen) entry.lastSeen = ts;
+			}
+			entry.messages += 1;
+		}
+	}
+	return {
+		contacts: [...byKey.values()].sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0)),
+		sources,
+		errors
+	};
+}
+//#endregion
+//#region src/im/channels.ts
+/**
+* im/channels.ts — IM 发送能力层（v1.31.0，S142 用户洞察）
+*
+* 用户原话：「既然微信桥是我们 ACC 提供的，那么 weixin-send 应该是我们 ACC 提供的能力，
+* 当用户配置了微信桥则可用，不配置则不可见」＋「设定一个复杂的多层工具，叫 im-bridge，
+* 里面有微信，然后保留后续可能兼容别的 im 的空间」。
+*
+* 分层（E↑）：
+*   `tools/im/channels.ts`（工具面：参数 → 结果渲染）
+*     → **本模块**（通道注册表 + 可见性判据 + 动作分发 + 错误码翻译）
+*       → 通道实现（`im/weixin-channel.ts`：协议/凭据/账号/记录）
+*
+* 边界（R↓）：
+* - **本模块零宿主依赖**（不 import cordis/agent）——可见性判定与分发都是纯逻辑，可独立单测。
+* - **通道只提供机制**：本模块不认识"微信"；新增 IM 只需注册一个通道实现（R3 家族式扩展）。
+* - **只能操作本会话 CCC**（R4）：`root` 由调用方（工具面）从 agent cwd 解析后传入，
+*   本模块不接受"目标 CCC"参数——跨 CCC 发送不在能力面。
+* - **记录归通道**（R5）：通道实现负责让每次发送都落既有 hook。
+*/
+/** 文本长度上限（微信侧单条实践上限；超限拒绝而非静默截断——与 HTTP 入口同值） */
+const IM_SEND_MAX_TEXT = 4e3;
+/** 文件大小上限（20MB，与媒体接收上限一致） */
+const IM_FILE_MAX_BYTES = 20971520;
+const channels = /* @__PURE__ */ new Map();
+/** 注册通道（index.ts apply 调用；重复 id 覆盖——测试与热重载友好） */
+function registerImChannel(channel) {
+	channels.set(channel.id, channel);
+}
+/** 已注册通道 id（工具 `channel` 参数枚举） */
+function imChannelIds() {
+	return [...channels.keys()];
+}
+/**
+* 可见性判据：本 CCC 是否**有任何可用的 IM 账号**。
+* 未启用 → 工具面对该 agent **不可见**（`tools.restrict` 移除，而非调用时报错）。
+*
+* ## 🔴 2026-10-22 判据修正（owner 令：「把开关升级为有任意账号即可，而不是盯着微信」）
+*
+* **旧判据** = 遍历已注册通道、任一 `channel.isEnabled(root)` 为真即可见。
+* **旧判据的缺陷**（实测于一个只配飞书的 CCC）：`feishuChannel.isEnabled()` 首行是
+* `if (settings.enabled !== true) return false` —— 总开关一关，**后面的账号判断根本不执行**
+* ⇒ 账号明明配了、`enabled:true`，却因为一个**渠道无关的总开关**被永久判成"未启用"
+* ⇒ `im-bridge` 在模型清单里彻底消失，而配置面看上去是对的（`accounts[]` 里躺着一条 feishu）。
+* 这正是 D179 的形态：**配置说它有，行为说它没有**，且零报错。
+*
+* **新判据** = **账号即事实**：`readImSettings(root).accounts` 里存在
+* 「`enabled !== false` 的账号」即视为可见。理由三条：
+* ① **可见性问的是"这个 CCC 有没有 IM 能力"**，而能力的载体是**账号**，不是总开关；
+* ② 总开关的语义是"**要不要让桥跑起来**"，把它当成可见性上限，会让"配好了但暂时不想让它跑"
+*    这种合法状态变成"工具凭空消失"；
+* ③ 判**按账号判**后，微信与飞书不再各有一套"总开关 + 账号"的双重判据 ⇒ 消除同族漂移。
+*
+* ⚠️ **不放宽的部分**：没有账号 ⇒ 仍然不可见（`accounts` 为空即 false）。
+* ⚠️ 单个通道自己的 `isEnabled` 仍是**发送/启停**判据（那是通道自己的事），
+*    只是**不再兼任**工具可见性判据 —— 两件事被这次修正分开了。
+*
+* @param root 本会话 CCC 根（由调用方解析）
+*/
+function hasEnabledImChannel(root) {
+	let settings;
+	try {
+		settings = readImSettings(root);
+	} catch {
+		return false;
+	}
+	return (settings.accounts ?? []).some((a) => a.enabled !== false);
+}
+/**
+* 可见性判据（**轨迹级**，2026-10-23 owner 令）：
+* 这个 dsh 会话所属的认知轨迹，是否**被 IM 路由表点名**（= 它才是那个"接线人"）。
+*
+* ## 它解决的问题（owner 原话的**去标识改写**，原文含私有角色名，按 D145 不入仓库）
+*
+* > 「很多轨迹发消息给我，但是我没空回，它们就会等待我，其实并不是，我希望他们继续工作；
+* >  所以只有 IM 桥绑定了任意账户的认知轨迹才拥有 `im-bridge` 这个 tool，
+* >  这样可以确保只有一个接线角色和我联系，其它轨迹和它联系即可，它会自行回复它们的」
+*
+* ⇒ 旧判据是 **CCC 级**（{@link hasEnabledImChannel}：本 CCC 有任一启用账号 ⇒ 全体可见）。
+* 它的后果不是"少一个工具"，而是**一条错误的工作流**：每条轨迹都以为自己该直接对 owner 说话，
+* 于是发完就**停下来等人回**——而 owner 根本没空逐条回。**工具在，就把等待也带上了。**
+*
+* ## 判据（两条，缺一不可）
+*
+* 1. 本 CCC 有可用账号（{@link hasEnabledImChannel}）—— 没有账号时路由表也没有意义；
+* 2. 本会话**绑定的轨迹编码**出现在 `routes[].trajectory` 里。
+*
+* ⚠️ **为什么不看 `routes[].user`**：那是"对端是谁"（owner 的通道 id），
+*    判"这条轨迹能不能说话"只跟**轨迹**有关，与哪个对端无关。
+*
+* ⚠️ **`*` 通配也算点名**：`{ user:"*", trajectory:"<某轨迹>" }` 这条路由的含义就是
+*    "**没人认领的消息都归那条轨迹**" ⇒ 它确实是一条被授权的接线轨迹，必须算可见。
+*    这与 `matchWeixinRoute` 的通配兜底语义**同源**，不另立规则。
+*
+* ## 拿不到轨迹编码时怎么办（fail-closed，与 `exclusive` 同向）
+*
+* 会话 → 轨迹编码要读绑定。**取不到就判不可见**：
+* - 与 `exclusive`（未声明 ⇒ 隐藏）同向；
+* - 反向（取不到就放行）会让"绑定坏了"表现成"工具还在"，
+*   而那正是本判据要防的形态（D179：配置说它有、行为说它没有，且零报错）。
+* ⚠️ 代价明示：绑定读取若短暂失败，该轮会少一个工具；下一轮绑定恢复即回。
+*    这比"误给一条轨迹发消息的权限"便宜 —— 后者会让它**停下来等 owner**。
+*
+* @param root CCC 根
+* @param trajectoryCode 本会话所属认知轨迹的编码（**由调用方解析**，见 `trajectory/policy/profile.ts`）
+* @returns true = 该轨迹接线，`im-bridge` 可见
+*/
+function isImWiredTrajectory(root, trajectoryCode) {
+	if (typeof trajectoryCode !== "string" || trajectoryCode.trim() === "") return false;
+	if (!hasEnabledImChannel(root)) return false;
+	let settings;
+	try {
+		settings = readImSettings(root);
+	} catch {
+		return false;
+	}
+	const wanted = trajectoryCode.trim();
+	for (const route of settings.routes ?? []) {
+		const target = typeof route.trajectory === "string" ? route.trajectory.trim() : "";
+		if (target !== "" && target === wanted) return true;
+	}
+	return false;
+}
+/**
+* 错误码 → 可行动提示（模型视角：说清怎么改）。
+*
+* 🔴 `CHANNEL_NOT_CONFIGURED` 的提示**不能写死某一个渠道的字段名**（2026-10-20 Q4 真机验收踩到）：
+* 首版逐字写「enable it in … (weixin.enabled)」，而接第二个渠道后，**飞书能不能用不取决于
+* 这个开关**（它取决于有没有一条启用中的飞书账号）⇒ 按那句提示去改 `weixin.enabled`
+* **不会生效**，而错误码又指向"没配置" ⇒ 用户据此改完还是同一句报错。
+* ⇒ 提示按**渠道是否带自己的启用判据**分岔：带 `channelHint` 的就用它自己的说法。
+*/
+function remediationFor(code, channelHint) {
+	switch (code) {
+		case "CHANNEL_UNKNOWN": return "Use a registered channel id (see the tool description)";
+		case "CHANNEL_NOT_CONFIGURED": return channelHint ?? "This CCC has not configured that channel — check .opencode/serenity.json (the channel's own enabled flag / accounts) or the settings panel";
+		case "ACTION_UNKNOWN": return "Use send / send-file / users / status";
+		case "ACTION_UNSUPPORTED": return "This channel does not support that action";
+		case "ALIAS_UNKNOWN": return "Use a configured alias (see action=users) or a raw channel user id";
+		case "TEXT_REQUIRED": return "Provide text";
+		case "TEXT_TOO_LONG": return `Shorten the text to <= ${IM_SEND_MAX_TEXT} characters`;
+		case "USER_REQUIRED": return "Provide user";
+		case "FILE_REQUIRED": return "Provide file (a path inside this CCC)";
+		case "FILE_ESCAPE": return "Use a path inside this CCC";
+		case "FILE_NOT_FOUND": return "Check the path exists inside this CCC";
+		case "FILE_TOO_LARGE": return `Use a file <= ${Math.round(IM_FILE_MAX_BYTES / 1048576)} MB`;
+		default: return;
+	}
+}
+function fail(code, error, remediation) {
+	return {
+		ok: false,
+		code,
+		error,
+		...remediation ?? remediationFor(code) ? { remediation: remediation ?? remediationFor(code) } : {}
+	};
+}
+/** CCC 内文件读取（路径逃逸/缺失/超限一律拒绝，返回稳定码） */
+function readCccFile(root, relOrAbs) {
+	const abs = isAbsolute(relOrAbs) ? resolve(relOrAbs) : resolve(root, relOrAbs);
+	const rel = relative(resolve(root), abs);
+	if (rel.startsWith("..") || isAbsolute(rel)) return {
+		ok: false,
+		code: "FILE_ESCAPE",
+		error: `file escapes the CCC root: ${relOrAbs}`
+	};
+	if (!existsSync(abs)) return {
+		ok: false,
+		code: "FILE_NOT_FOUND",
+		error: `file not found: ${relOrAbs}`
+	};
+	let size = 0;
+	try {
+		size = statSync(abs).size;
+	} catch (err) {
+		return {
+			ok: false,
+			code: "FILE_NOT_FOUND",
+			error: `cannot stat file: ${relOrAbs} (${err instanceof Error ? err.message : String(err)})`
+		};
+	}
+	if (size > 20971520) return {
+		ok: false,
+		code: "FILE_TOO_LARGE",
+		error: `file is ${size} bytes (> ${IM_FILE_MAX_BYTES})`
+	};
+	try {
+		return {
+			ok: true,
+			data: readFileSync(abs),
+			fileName: abs.split("/").pop() ?? "file"
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			code: "FILE_NOT_FOUND",
+			error: `cannot read file: ${relOrAbs} (${err instanceof Error ? err.message : String(err)})`
+		};
+	}
+}
+/**
+* 执行一次 IM 动作（工具面唯一入口）。
+*
+* 顺序：通道解析 → 动作校验 → 用户解析（别名 → id）→ 输入校验 → 调用通道实现。
+* 任何一步失败都返回**稳定错误码 + 可行动提示**（不抛错——工具面统一渲染）。
+*
+* @param root 本会话 CCC 根（调用方从 agent cwd 解析；本函数不接受目标 CCC）
+* @param req 工具参数
+*/
+async function runImBridge(root, req) {
+	const channelId = (req.channel ?? "").trim();
+	const action = (req.action ?? "").trim();
+	if (channelId === "") return fail("CHANNEL_REQUIRED", "channel is required", "Provide channel (e.g. \"weixin\")");
+	const channel = channels.get(channelId);
+	if (!channel) return fail("CHANNEL_UNKNOWN", `unknown channel "${channelId}" (registered: ${imChannelIds().join(", ") || "(none)"})`);
+	if (!channel.isEnabled(root)) return fail("CHANNEL_NOT_CONFIGURED", `channel "${channelId}" is not configured for this CCC (${root})`, channel.notEnabledReason?.(root));
+	if (action === "users") return {
+		ok: true,
+		channel: channelId,
+		action,
+		detail: { users: channel.listUsers(root) }
+	};
+	if (action === "contacts") {
+		if (!channel.listContacts) return fail("ACTION_UNSUPPORTED", `channel "${channelId}" has no record source for contacts`);
+		const settings = readWeixinSettings(root);
+		const accountChannel = {};
+		for (const account of settings.accounts ?? []) if (typeof account.accountId === "string" && account.accountId !== "") accountChannel[account.accountId] = typeof account.channel === "string" && account.channel !== "" ? account.channel : "weixin";
+		const scanned = scanImContacts(root, accountChannel);
+		const mine = scanned.contacts.filter((c) => c.channel === channelId);
+		/** 当前路由表（`user → trajectory`）；同一 user 多条时后者覆盖 */
+		const routeMap = /* @__PURE__ */ new Map();
+		for (const route of settings.routes ?? []) if (typeof route.user === "string" && route.user !== "") routeMap.set(route.user, typeof route.trajectory === "string" ? route.trajectory : "");
+		const contacts = mine.map((c) => ({
+			channel: c.channel,
+			userId: c.userId,
+			accountIds: c.accountIds,
+			route: routeMap.get(c.userId) ?? null,
+			firstSeen: c.firstSeen === null ? null : new Date(c.firstSeen).toISOString(),
+			lastSeen: c.lastSeen === null ? null : new Date(c.lastSeen).toISOString(),
+			messages: c.messages
+		}));
+		const seenUsers = new Set(mine.map((c) => c.userId));
+		return {
+			ok: true,
+			channel: channelId,
+			action,
+			detail: {
+				contacts,
+				unrouted: mine.filter((c) => !routeMap.has(c.userId)).map((c) => c.userId),
+				orphanRoutes: [...routeMap.keys()].filter((user) => !seenUsers.has(user)),
+				sources: scanned.sources,
+				...scanned.errors.length > 0 ? { errors: scanned.errors } : {}
+			}
+		};
+	}
+	if (action === "status") return {
+		ok: true,
+		channel: channelId,
+		action,
+		detail: channel.status(root)
+	};
+	if (action === "send") {
+		const rawUser = (req.user ?? "").trim();
+		if (rawUser === "") return fail("USER_REQUIRED", "user is required");
+		const text = req.text ?? "";
+		if (text === "") return fail("TEXT_REQUIRED", "text is required");
+		if (text.length > 4e3) return fail("TEXT_TOO_LONG", `text is ${text.length} characters (> ${IM_SEND_MAX_TEXT})`);
+		const resolved = channel.resolveUser(root, rawUser);
+		if (!resolved) return fail("ALIAS_UNKNOWN", `unknown user "${rawUser}"`);
+		try {
+			return {
+				ok: true,
+				channel: channelId,
+				action,
+				detail: {
+					...await channel.send({
+						root,
+						userId: resolved.id,
+						text,
+						accountId: req.account
+					}),
+					user: resolved.alias ?? resolved.id
+				}
+			};
+		} catch (err) {
+			return fail("SEND_FAILED", err instanceof Error ? err.message : String(err));
+		}
+	}
+	if (action === "send-file") {
+		if (!channel.sendFile) return fail("ACTION_UNSUPPORTED", `channel "${channelId}" does not support send-file`);
+		const rawUser = (req.user ?? "").trim();
+		if (rawUser === "") return fail("USER_REQUIRED", "user is required");
+		const fileArg = (req.file ?? "").trim();
+		if (fileArg === "") return fail("FILE_REQUIRED", "file is required");
+		const resolved = channel.resolveUser(root, rawUser);
+		if (!resolved) return fail("ALIAS_UNKNOWN", `unknown user "${rawUser}"`);
+		const file = readCccFile(root, fileArg);
+		if (!file.ok) return fail(file.code, file.error);
+		try {
+			return {
+				ok: true,
+				channel: channelId,
+				action,
+				detail: {
+					...await channel.sendFile({
+						root,
+						userId: resolved.id,
+						data: file.data,
+						fileName: file.fileName,
+						caption: req.caption,
+						accountId: req.account
+					}),
+					user: resolved.alias ?? resolved.id
+				}
+			};
+		} catch (err) {
+			return fail("SEND_FAILED", err instanceof Error ? err.message : String(err));
+		}
+	}
+	return fail("ACTION_UNKNOWN", `unknown action "${action}"`);
+}
+//#endregion
+export { SERENITY_SETTINGS_NS as a, runImBridge as i, isImWiredTrajectory as n, readSimpleSettings as o, registerImChannel as r, registerSettingsSection as s, imChannelIds as t };

package/lib/im/bridge.d.ts

@@ -26,8 +26,8 @@
 import type { Context } from 'cordis';
 import { type WeixinAccountCredential } from './route.js';
 import { type WeixinMessage } from './ilink.js';
-import { resolveInboundTarget, manualOutputFallbackNeeded, type ResolvedInboundTarget } from './inbound-event.js';
-export { manualOutputFallbackNeeded, resolveInboundTarget };
+import { resolveInboundTarget, type ResolvedInboundTarget } from './inbound-event.js';
+export { resolveInboundTarget };
 export type { ResolvedInboundTarget };
 /** 记下最近一次入站带来的 `context_token`（**只存非空**；空串会把好票覆盖成坏票） */
 export declare function rememberContextToken(accountId: string, userId: string, token: string | undefined): void;

package/lib/im/guard.d.ts

@@ -1,6 +1,12 @@
 /**
  * im/guard.ts — 手动输出模式的**机械闸门**（v1.30.16，S142 用户"LLM 不听"）
  *
+ * 🔴 **2026-10-24（D238）后本模块从"边缘"变成"主路径"**：`autoReplyWithLastMessage` 那条开关
+ * 已整条退役 ⇒ **所有会话都是手动输出**（桥永不自动回发）⇒ 本闸门**每轮恒生效**。
+ * 由此得到一条必配件判据（D234）：打回前**必须**先确认 `im-bridge` 对该轨迹可见 ——
+ * 否则"该轨迹没有发送权"会被无解地打回成"忘了发"。见 `isImWiredTrajectory` 的使用处。
+ * 下面第 4 行起的"问题（实证）"是**当时**的缘起叙述，其中提到的开关现已不存在。
+ *
  * 问题（实证）：`weixin.autoReplyWithLastMessage: false` 时桥不回发最终文本，输出权归 agent
  * （必须自己调 `im-bridge` 工具，v1.30.x 为 `msm("weixin-send", …)`）。提示词层面已说明，
  * 但用户实测 **LLM 仍经常不发**——结果用户什么都收不到（静默）。这类"提示词软约束失效"正是 ACC
@@ -92,7 +98,7 @@ export declare function isWeixinOutputGuardActive(): boolean;
  * 🔴 **原名为 `isSuccessfulWeixinSend`，2026-10-20 改名**（Q4 出站飞书）：
  * 它曾硬比 `channel !== 'weixin' ⇒ false`。接第二个渠道后，那条判据的含义变成
  * **"只有微信算发出去了"** —— 而实际后果是：飞书会话里 agent 真的发成功了，
- * 闸门仍判"未发送" ⇒ 打回 ≤2 次，若 CCC 开了 `fallbackOnNoSend` 还会再兜底转发一遍
+ * 闸门仍判"未发送" ⇒ 打回 ≤2 次，且当时的 `fallbackOnNoSend` 还会再兜底转发一遍
  * ⇒ **重复投递**。⇒ 判据从"是不是微信"改成"是不是**这个会话所在的那条渠道**"，
  * 函数名随之更正（**名字要能对着行为读**，D151/D179 同族）。
  *