@shgroup/dsh-serenity-hooks 1.30.17 → 1.31.0

package/lib/index.js

@@ -3,14 +3,14 @@ import { a as findSerenityRoot, c as matchBlacklist, d as readCccName$2, f as re
 import { a as readSkiffRoles, d as systemPromptSource, i as isSkiffSessionId, l as roleToolWhitelist, o as resolveRoleSystemPrompt } from "./skiff-role-BYvNnwv1.js";
 import { A as skiffRoleFor, C as listActiveHandymen, D as splitModel, E as requireWhitelistedModel, O as writeFailedStatus, S as handymanProgressPaths, T as readProgress, _ as unregisterSkiffSession, a as startSkiffDebugServer, b as HANDYMAN_GUIDE, c as askSkiff, d as ensureWorkspacePromptSection, f as getSkiffAgent, g as skiffTrajectoryEnabled, h as skiffSessionSnapshot, k as writeProgress, l as createSkiffAgent, m as skiffSessionInfo, n as jscSafeJsonText, o as stopSkiffDebugServer, p as skiffMsmGate, r as renderSkiffMarkdown, s as stripThink, t as discoverCccs, u as ensureSkiffSession, v as workspaceTrajectoryLine, w as newStopToken, x as buildRoundPrompt, y as waitAgentIdle } from "./skiff-debug-C5ulZKCa.js";
 import { i as hostSessions, n as hostInjected, o as hostWeb, r as hostService, s as hostWebServer, t as hostAgents } from "./access-dU_vG1q8.js";
-import { a as readWeixinCredential, c as weixinInboundDir, d as LOCALSTORE_SCOPES, f as checkLocalstoreGitCompliance, h as runLocalStore, i as matchWeixinRoute, l as weixinSessionIdFor, m as readGitTrack, n as extractWeixinText, o as readWeixinSettings, p as localstorePath, r as hasVoiceItem, s as sanitizeFileName$1, t as extractWeixinMedia } from "./weixin-route-DIaUYipW.js";
+import { a as readWeixinCredential, c as weixinInboundDir, d as LOCALSTORE_SCOPES, f as checkLocalstoreGitCompliance, g as runLocalStore, h as readStore, i as matchWeixinRoute, l as weixinSessionIdFor, m as readGitTrack, n as extractWeixinText, o as readWeixinSettings, p as localstorePath, r as hasVoiceItem, s as sanitizeFileName$1, t as extractWeixinMedia } from "./weixin-route-wWk4AIwV.js";
 import { C as useSession, S as summarize, _ as resolveSessionByTitle, a as archiveSessions, b as setActiveSessionInfo, c as createSession, d as getActiveSessionInfo, f as healthCheck, g as readActiveSessionMd, h as qaCheck, i as SESSION_ACTIONS, l as extractSessionMdPathFromText, m as parseSessionContextFromEvents, n as readLastBound, o as clearActiveSessionInfo, p as listSessions, r as DEFAULT_SESSION_SCOPE, s as closeSession, t as appendBound, u as findSession, v as sessionEvents, x as showSession, y as sessionsRoot } from "./session-bound-BpTayaIS.js";
 import { n as registerSettingsSection, t as readSimpleSettings } from "./settings-section-CP4uMJf_.js";
-import { a as markdownToPlainText, c as sniffImageExt, i as getUpdates, n as downloadMedia, o as sendTextMessage, r as getConfig, s as sendTyping, t as TypingStatus } from "./weixin-api-BMpljodH.js";
+import { a as markdownToPlainText, c as sendTyping, i as getUpdates, l as sniffImageExt, n as downloadMedia, o as sendFileMessage, r as getConfig, s as sendTextMessage, t as TypingStatus } from "./weixin-api-PjEhmjlZ.js";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { homedir, platform } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -421,10 +421,10 @@ function runCcFs(root, args) {
 * 进程内注册（取代 v0.1 的 bash spawn runner）：zod/schemastery 参数校验、
 * 规范 JSON 输出、纯 render 投影。逻辑在 fs-ops.ts（可单测）。
 */
-function agentCwd$9(exec) {
+function agentCwd$10(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$12(value) {
+function renderText$13(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -496,10 +496,10 @@ const ccFsTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$12(value)
+		render: (args, value) => renderText$13(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$9(exec));
+		const root = findSerenityRoot(agentCwd$10(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		return runCcFs(root, args);
 	}
@@ -520,6 +520,208 @@ const ACC_VERSION = (() => {
 	}
 })();
 //#endregion
+//#region src/im-bridge.ts
+/**
+* im-bridge.ts — IM 发送能力层（v1.31.0，S142 用户洞察）
+*
+* 用户原话：「既然微信桥是我们 ACC 提供的，那么 weixin-send 应该是我们 ACC 提供的能力，
+* 当用户配置了微信桥则可用，不配置则不可见」＋「设定一个复杂的多层工具，叫 im-bridge，
+* 里面有微信，然后保留后续可能兼容别的 im 的空间」。
+*
+* 分层（E↑）：
+*   `tools/im-bridge.ts`（工具面：参数 → 结果渲染）
+*     → **本模块**（通道注册表 + 可见性判据 + 动作分发 + 错误码翻译）
+*       → 通道实现（`im-weixin.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` 移除，而非调用时报错）。
+* @param root 本会话 CCC 根（由调用方解析）
+*/
+function hasEnabledImChannel(root) {
+	for (const channel of channels.values()) try {
+		if (channel.isEnabled(root)) return true;
+	} catch {}
+	return false;
+}
+/** 错误码 → 可行动提示（模型视角：说清怎么改） */
+function remediationFor(code) {
+	switch (code) {
+		case "CHANNEL_UNKNOWN": return "Use a registered channel id (see the tool description)";
+		case "CHANNEL_NOT_CONFIGURED": return "This CCC has not configured that channel — enable it in .opencode/serenity.json (weixin.enabled) 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})`);
+	if (action === "users") return {
+		ok: true,
+		channel: channelId,
+		action,
+		detail: { users: channel.listUsers(root) }
+	};
+	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
 //#region src/seams/guards.ts
 /**
 * guards.ts — 拦截缝：安全模式 + 路径守卫（P3 语义的机械层）
@@ -712,6 +914,55 @@ function syncSafeModeRestriction(agent, root) {
 	}
 	writeRestrictDiag(root);
 }
+/** 条件可见的 IM 工具名（与 tools/im-bridge.ts 的注册名一致） */
+const IM_BRIDGE_TOOL_NAME = "im-bridge";
+/** agent key → restrict disposer（im-bridge 隐藏状态；key 同安全模式 = 会话 id） */
+const imBridgeRestrictions = /* @__PURE__ */ new Map();
+/**
+* 同步 im-bridge 可见性（v1.31.0，S142 用户拍板 Q3「未配置则不可见」）。
+*
+* 判据 = 本会话 CCC 是否启用了**任一** IM 通道（`hasEnabledImChannel`，当前只有 weixin）：
+* - 未启用 → `agent.ctx.tools.restrict({ deny: ['im-bridge'] })`：**从 schema 移除**
+*   （模型看不到，而不是看得到但调用被拒——用户原话"不配置则不可见"）
+* - 启用 → 解除隐藏（CCC 配置热更新即时生效）
+*
+* 与 `syncSafeModeRestriction` 同点调用（pre-step 每步 + 会话就绪），失败不阻断
+* （守卫仍兜底；restrict 不可用时最坏是"看得到但通道未配置 → 返回 CHANNEL_NOT_CONFIGURED"）。
+*/
+function syncImBridgeVisibility(agent, root) {
+	const key = agent.session.id ?? "global";
+	let enabled = false;
+	try {
+		enabled = hasEnabledImChannel(root);
+	} catch (e) {
+		console.error(`[serenity-hooks] im-bridge 可见性判据失败 (key=${key}):`, e.message);
+		return;
+	}
+	const existing = imBridgeRestrictions.get(key);
+	if (!enabled && !existing) try {
+		const dispose = agent.ctx.tools.restrict({ deny: [IM_BRIDGE_TOOL_NAME] });
+		imBridgeRestrictions.set(key, dispose);
+	} catch (e) {
+		console.error(`[serenity-hooks] im-bridge 隐藏失败 (key=${key}):`, e.message);
+	}
+	else if (enabled && existing) {
+		try {
+			existing();
+		} catch (e) {
+			console.error(`[serenity-hooks] im-bridge 解除隐藏失败 (key=${key}):`, e.message);
+		}
+		imBridgeRestrictions.delete(key);
+	}
+}
+/** 会话销毁清理（lifecycle 调用；防 per-会话 Map 无界增长——review F-08 同族） */
+function forgetImBridgeVisibility(sessionId) {
+	const existing = imBridgeRestrictions.get(sessionId);
+	if (!existing) return;
+	try {
+		existing();
+	} catch {}
+	imBridgeRestrictions.delete(sessionId);
+}
 /**
 * 从 exec 参数中提取常见路径字段（write/edit 工具）；宽松读取。
 * container_fs 复合工具：path（单路径）/ paths（数组）/ src / dst——取第一个命中（越界检查
@@ -1316,10 +1567,10 @@ async function runKit(root, args, hostCtx) {
 /**
 * kit.ts — dashboard 真实 DSH 工具定义（defineTool）（v1.30：acc_kit → dashboard）
 */
-function agentCwd$8(exec) {
+function agentCwd$9(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$11(value) {
+function renderText$12(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -1347,10 +1598,10 @@ function createKitTool(ctx) {
 		},
 		output: {
 			schema: { type: "json" },
-			render: (args, value) => renderText$11(value)
+			render: (args, value) => renderText$12(value)
 		},
 		async execute(args, exec) {
-			return await runKit(findSerenityRoot(agentCwd$8(exec)), args, ctx);
+			return await runKit(findSerenityRoot(agentCwd$9(exec)), args, ctx);
 		}
 	});
 }
@@ -1539,10 +1790,10 @@ function runGit(root, args) {
 /**
 * git.ts — container_git 真实 DSH 工具定义（defineTool）（v1.30：cc_git → container_git）
 */
-function agentCwd$7(exec) {
+function agentCwd$8(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$10(value) {
+function renderText$11(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -1581,10 +1832,10 @@ const gitTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$10(value)
+		render: (args, value) => renderText$11(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$7(exec));
+		const root = findSerenityRoot(agentCwd$8(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		return runGit(root, args);
 	}
@@ -1844,26 +2095,33 @@ CCC 级微信个人号接入（iLink 协议）：dsh 一进程多 CCC，每 CCC
 （扫码绑定后自动写入，永不进 git 明文面）。
 路由 user → role：exact 优先，* 通配兜底；role 必须 ∈ 该 CCC skiff.roles。
 面板（WebUI 设置 → 微信桥）可扫码绑定/移除账号/编辑路由；msm("weixin-doctor", ["status"|"diag"|"verify"|"guide"]) 排查 + 大而全指南。凭据主动查看：localstore get WEIXIN_<ACCOUNT>_TOKEN。
-  ▸ 主动发送（v1.30.9）：CCC 用 msm("weixin-send", ["send", "--ccc", "<CCC>", "--user", "<别名|id>", "<文本>"])
-    给用户发消息——经 dsp 主动发送入口（**只绑 127.0.0.1**，plugin 全局配置 ~/.dsh/serenity-hooks.json
-    的 weixinApi.port，默认 3082；公网不可达故无密钥）→ weixin-bridge.sendProactiveText →
-    成功后触发 outgoing hook（source="proactive"）。send-file 仍由 MSM 直连 iLink 上传并自行补记。
+  ▸ 主动发送（v1.31.0：**ACC 工具 im-bridge**）：调
+    im-bridge({channel:"weixin", action:"send", user:"<别名|id>", text:"<文本>"}) 给用户发消息——
+    **工具只能操作本会话 CCC**（无 ccc 参数，防误发他容器）→ weixin-bridge.sendProactiveText →
+    成功后触发 outgoing hook（source="proactive"）。文件用 action:"send-file" + file:"<CCC 内路径>"
+    （逃逸/缺失/超 20MB 拒绝）+ 可选 caption。**可见性**：本 CCC 配置了 IM 通道
+    （weixin.enabled=true）才出现在模型工具清单里；未配置 → 由 guards 逐 agent
+    tools.restrict({deny:['im-bridge']}) 移除（不是"看得到但被拒"）。skiff 角色另需在
+    roles.<role>.tools 白名单列出 im-bridge。
+    历史（v1.30.9~v1.30.x）：CCC 侧 MSM weixin-send（走 loopback HTTP 入口 3082）——
+    v1.31.0 已退役（脚本删除 + 注册表注销）；3082 入口保留给**非 agent 调用者**。
 
   ▸ weixin.autoReplyWithLastMessage（v1.30.10，关闭桥的自动输出）：
     缺省 true = 现状：桥在 agent 一轮结束后把**最终 assistant 文本**自动回发用户（source="reply"）。
     显式 false = 关闭：桥**不再转发最终文本**，输出权交给 agent——每轮在用户消息**末尾**追加
-    **机制标记** [serenity:weixin-manual-output] + 一行已填好参数的 weixin-send 命令
-    （CCC 根/账号/用户 id），agent 自己决定发什么、发几条（全部记 source="proactive"）。
+    **机制标记** [serenity:weixin-manual-output] + 一行已填好参数的 im-bridge 调用
+    （账号/用户 id），agent 自己决定发什么、发几条（全部记 source="proactive"）。
     **ACC 只给机制与数据，纪律措辞归 CCC**（v1.30.16）：怎么写/必须怎么做/后果是什么写在
     CCC 角色提示词文件里（如 .opencode/skiff/<role>.md），可热改（v1.30.15 起角色提示词热重载）。
-    机械闸门（v1.30.16）：本轮 turn 结束仍未成功调用 weixin-send → agent 被打回（≤2 次，
-    提示 = 标记 + 事实）；达上限放弃并响亮告警。失败调用不算已送达。
+    机械闸门（v1.30.16）：本轮 turn 结束仍未成功调用 im-bridge（send / send-file；兼容旧
+    msm("weixin-send") 形态）→ agent 被打回（≤2 次，提示 = 标记 + 事实）；达上限放弃并响亮告警。
+    失败调用不算已送达。
     语义边界（用户拍板）：只关最终文本；系统类消息（新对话通知 / 语音无法解析提示）保留；
     typing 指示与 incoming hook 不受影响。
 
   ▸ weixin.fallbackOnNoSend（v1.30.17，手动模式的**兜底**；缺省 false）：
     仅在 autoReplyWithLastMessage=false 时生效。true → 一轮结束时若 agent **一次都没成功**
-    调用 weixin-send（闸门打回用尽），桥把该轮最终文本转发给用户（记录 source="reply-fallback"，
+    调用输出工具（闸门打回用尽），桥把该轮最终文本转发给用户（记录 source="reply-fallback"，
     日志留响亮告警）——保证"不丢消息"。agent 自己发过 → 不兜底（输出权仍在 agent）。
     为什么需要（实证）：v1.30.16 闸门会打回 ≤2 次，但实测某模型在**寒暄类消息**上连续 4 轮、
     跨 3 版 CCC 提示词仍不调工具 → 打回用尽后用户什么都收不到；提示词与闸门均已排除。
@@ -1890,7 +2148,7 @@ CCC 级微信个人号接入（iLink 协议）：dsh 一进程多 CCC，每 CCC
     incoming  = 用户 → bot：路由命中后、媒体落盘后触发（文本含语音转写；媒体带落盘 relPath）
     outgoing  = bot → 用户：发送成功后触发（reply = 用户实际收到的纯文本，已剥离 think）
       · source="reply"（缺省）= 回复用户消息；source="proactive"（v1.30.9）= bot 主动发起
-        （CCC 经 weixin-send MSM → dsp 主动发送入口 → sendProactiveText）；
+        （CCC 经 im-bridge 工具（v1.31.0；旧 weixin-send MSM 已退役）→ sendProactiveText）；
         source="reply-fallback"（v1.30.17）= 手动模式下 agent 本轮未发送 → 桥兜底转发最终文本
       · file（仅 send-file 补记）：{ "name": "报告.pdf", "size": 12345, "caption": "可选" }
 
@@ -2327,13 +2585,13 @@ async function runMsmAsync(root, args) {
 * 管理面（register/deregister/check/guide/catalog/ccc-config）已移入 container_admin。
 * 底层 runMsmAsync/prepareExec 全复用；未命中候选为新增 findSuggestions。
 */
-function agentCwd$6(exec) {
+function agentCwd$7(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
 function agentSessionId$1(exec) {
 	return exec.agent?.session?.id ?? "";
 }
-function renderText$9(value) {
+function renderText$10(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2383,10 +2641,10 @@ const msmTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$9(value)
+		render: (args, value) => renderText$10(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$6(exec));
+		const root = findSerenityRoot(agentCwd$7(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		const sessionId = agentSessionId$1(exec);
 		const name = args.name;
@@ -2444,7 +2702,7 @@ CCC (home-serenity etc.) encodes cognitive content as skills/SESSIONs/design doc
 
 ## Reference
 https://github.com/tellmewhattodo/theory-eap`;
-function renderText$8(value) {
+function renderText$9(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2464,7 +2722,7 @@ defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$8(value)
+		render: (_args, value) => renderText$9(value)
 	},
 	async execute(args) {
 		if (args.section === "variables") return EAP_CONTENT.split("## Pre-Output Self-Check Checklist")[0];
@@ -2505,7 +2763,7 @@ Requirements → Scope → Solution → Interface → Implementation
 2. Wait for confirmation or correction (small step)
 3. After confirmation, record the decision (into session SESSION.md or a design doc)
 4. Move to the next decision point`;
-function renderText$7(value) {
+function renderText$8(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2521,7 +2779,7 @@ defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$7(value)
+		render: (_args, value) => renderText$8(value)
 	},
 	async execute(args) {
 		if (args.section === "rules") return NEAT_CONTENT.match(/## Four Iron Rules[\s\S]*?(?=## )/)?.[0] ?? NEAT_CONTENT;
@@ -2584,7 +2842,7 @@ CCE answers "how structured knowledge should keep evolving across time without l
 ## Relationship with Serenity
 Serenity's session system, session tracking, and entropy management mechanisms (SQC quality loop) are all engineering implementations of CCE;
 the behavioral constraints embedded in CCC system prompts come from CCE.`;
-function renderText$6(value) {
+function renderText$7(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2605,7 +2863,7 @@ defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$6(value)
+		render: (_args, value) => renderText$7(value)
 	},
 	async execute(args) {
 		const section = args.section;
@@ -2651,7 +2909,7 @@ const PRAXIS_INDEX = `praxis — 可实践理论注入（认知框架，按需
           praxis cce（认知连续性工程——容器 5 行为约束 + H_op 操作熵）
 无参返回本目录；详情以对应框架原文为准（单一真相源）。
 `;
-function renderText$5(value) {
+function renderText$6(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2671,7 +2929,7 @@ const praxisTool = defineTool({
 	} },
 	output: {
 		schema: { type: "string" },
-		render: (_args, value) => renderText$5(value)
+		render: (_args, value) => renderText$6(value)
 	},
 	async execute(args) {
 		if (args.section === "eap") return EAP_CONTENT;
@@ -2725,10 +2983,10 @@ function handymanPresetInheritance(parentCtx) {
 * preset 继承 + 工具收窄：setup 钩子里对子 agent 执行 agentPresets.composeFrom（对齐
 * subagent 先例）+ tools.restrict deny handyman（worker 内部看不到 handyman 工具）。
 */
-function agentCwd$5(exec) {
+function agentCwd$6(exec) {
 	return (exec.agent?.session)?.header?.cwd ?? process.cwd();
 }
-function renderText$4(value) {
+function renderText$5(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -2931,11 +3189,11 @@ function createHandymanTool(ctx) {
 		},
 		output: {
 			schema: { type: "json" },
-			render: (_args, value) => renderText$4(value)
+			render: (_args, value) => renderText$5(value)
 		},
 		async execute(args, exec) {
 			if (args.guide) return { guide: HANDYMAN_GUIDE };
-			const root = findSerenityRoot(agentCwd$5(exec));
+			const root = findSerenityRoot(agentCwd$6(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const hc = readHandymanConfig(root, DEFAULT_SERENITY_CONFIG_PATHS);
 			if (hc === null) throw new Error("handyman requires a model whitelist: configure .opencode/serenity.json \"handyman.models\" (e.g. {\"handyman\": {\"models\": [\"minimax-cn-coding-plan/MiniMax-M3\"], \"defaultModel\": \"minimax-cn-coding-plan/MiniMax-M3\"}})");
@@ -2996,7 +3254,7 @@ function createHandymanTool(ctx) {
 * 同步把当前 dsh 会话重命名为该 SESSION 目录名**（sessionTitle.rename，user source
 * pin 住标题）。非创建时预命名。
 */
-function agentCwd$4(exec) {
+function agentCwd$5(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
 /** 当前 dsh 会话 id（use/close 按会话隔离的 scope） */
@@ -3112,7 +3370,7 @@ function renameDshSessionForActive(ctx, exec, info, summary) {
 		console.warn(`[serenity-hooks] dsh 会话重命名异常: ${String(err?.message ?? err)}`);
 	}
 }
-function renderText$3(value) {
+function renderText$4(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -3258,10 +3516,10 @@ function createSessionTool(ctx) {
 		},
 		output: {
 			schema: { type: "json" },
-			render: (args, value) => renderText$3(value)
+			render: (args, value) => renderText$4(value)
 		},
 		async execute(args, exec) {
-			const root = findSerenityRoot(agentCwd$4(exec));
+			const root = findSerenityRoot(agentCwd$5(exec));
 			if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 			const entries = loadMsmEntries(root);
 			const hasSessionTool = entries.some((e) => e.name === "session-tool");
@@ -3367,7 +3625,7 @@ function createSessionTool(ctx) {
 						root,
 						note: args.note,
 						summary: args.summary,
-						agentCwd: agentCwd$4(exec),
+						agentCwd: agentCwd$5(exec),
 						dshSessionId
 					});
 					return {
@@ -3392,7 +3650,7 @@ function createSessionTool(ctx) {
 * 进程内注册，零 DSH 依赖逻辑在 localstore-ops.ts（可单测）。
 * doc 子命令输出存储规范，agent 可直接用 fs 工具（read/write）自己读写。
 */
-const ACTIONS = [
+const ACTIONS$1 = [
 	"list",
 	"get",
 	"set",
@@ -3400,10 +3658,10 @@ const ACTIONS = [
 	"show",
 	"doc"
 ];
-function agentCwd$3(exec) {
+function agentCwd$4(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText$2(value) {
+function renderText$3(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -3415,7 +3673,7 @@ const localstoreTool = defineTool({
 	parameters: {
 		action: {
 			type: "string",
-			enum: [...ACTIONS],
+			enum: [...ACTIONS$1],
 			required: true,
 			description: "Subcommand: list/get/set/unset/show/doc"
 		},
@@ -3435,10 +3693,10 @@ const localstoreTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$2(value)
+		render: (args, value) => renderText$3(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$3(exec));
+		const root = findSerenityRoot(agentCwd$4(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		return runLocalStore(root, args);
 	}
@@ -3594,13 +3852,13 @@ function applySkiffConfig(root) {
 *
 * 参数极简（LLM 直觉）：domain（管理域）+ action（该域子命令）+ 少量业务参数。
 */
-function agentCwd$2(exec) {
+function agentCwd$3(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
 function agentSessionId(exec) {
 	return exec.agent?.session?.id ?? "";
 }
-function renderText$1(value) {
+function renderText$2(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -3655,10 +3913,10 @@ const containerAdminTool = defineTool({
 	},
 	output: {
 		schema: { type: "json" },
-		render: (args, value) => renderText$1(value)
+		render: (args, value) => renderText$2(value)
 	},
 	async execute(args, exec) {
-		const root = findSerenityRoot(agentCwd$2(exec));
+		const root = findSerenityRoot(agentCwd$3(exec));
 		if (!root) throw new Error("No CCC found: no .serenity file from agent cwd");
 		const sessionId = agentSessionId(exec);
 		const domain = args.domain;
@@ -4363,10 +4621,10 @@ const AUTOPILOT_ACTIONS = [
 	"guide",
 	"diag-live"
 ];
-function agentCwd$1(exec) {
+function agentCwd$2(exec) {
 	return exec.agent?.session?.header?.cwd ?? process.cwd();
 }
-function renderText(value) {
+function renderText$1(value) {
 	return [{
 		type: "text",
 		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
@@ -4405,11 +4663,11 @@ function createAutopilotTool(ctx) {
 		} },
 		output: {
 			schema: { type: "json" },
-			render: (_args, value) => renderText(value)
+			render: (_args, value) => renderText$1(value)
 		},
 		async execute(args, exec) {
 			if (args.action === "diag-live") return { output: renderDiagLive(diagLive(ctx)) };
-			const root = findSerenityRoot(agentCwd$1(exec));
+			const root = findSerenityRoot(agentCwd$2(exec));
 			const result = {};
 			if (!EXP_SCRIPT) {
 				result.error = "autopilot-trajectory 脚本未随安装分发（npm 包缺 experiments/autopilot-trajectory/）——请检查包完整性";
@@ -5889,7 +6147,7 @@ function codeModeAdaptationLine(ctx, scope) {
 *  无 agent → undefined（不注入）；有 agent 但无 header.cwd（workflow subagent 等）
 *  回退 process.cwd()——对齐 context.ts，否则这些 agent 系统提示词注入为空
 *  （v1.18.6：workflow subagent 无宁静号上下文 bug） */
-function agentCwd(context) {
+function agentCwd$1(context) {
 	const agent = context.agent;
 	if (!agent) return void 0;
 	return agent.session?.header?.cwd ?? process.cwd();
@@ -5909,7 +6167,7 @@ function registerEntrySkillSectionGlobal(ctx) {
 			name: "serenity-entry",
 			order: -50,
 			text: (context) => {
-				const cwd = agentCwd(context);
+				const cwd = agentCwd$1(context);
 				if (!cwd) return "";
 				const root = findSerenityRoot(cwd);
 				if (!root) return "";
@@ -6116,6 +6374,9 @@ function registerContext(ctx, opts = {}) {
 		injected.add(key);
 		agent.inject(accMessage(root, configPaths, entrySkillMaxChars));
 		syncSafeModeRestriction(agent, root);
+		try {
+			syncImBridgeVisibility(agent, root);
+		} catch {}
 	};
 	if (opts.seedOnStart ?? true) ctx.on("agent/session-start", (payload) => {
 		try {
@@ -6133,6 +6394,9 @@ function registerContext(ctx, opts = {}) {
 			try {
 				syncSafeModeRestriction(agent, root);
 			} catch {}
+			try {
+				syncImBridgeVisibility(agent, root);
+			} catch {}
 			registerEntrySkillSection(agent, root);
 		}
 		if (!root || injected.has(key) || downstream.kind !== "enter") return downstream;
@@ -6621,11 +6885,11 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$2(res, 400, { error: chk.error });
 						return;
 					}
-					const { readWeixinSettings } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { readWeixinSettings } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const { weixinBridgeStatus } = await Promise.resolve().then(() => weixin_bridge_exports);
 					const settings = readWeixinSettings(chk.root);
 					const bridge = weixinBridgeStatus().find((b) => b.ccc === chk.root);
-					const { readWeixinCredential } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { readWeixinCredential } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const accounts = (settings.accounts ?? []).map((a) => ({
 						accountId: a.accountId,
 						name: a.name ?? void 0,
@@ -6654,10 +6918,10 @@ function registerStatusApi(ctx, opts = {}) {
 				}
 				const root = chk.root;
 				if (body.action === "login-start") {
-					const { fetchQRCode } = await import("./weixin-api-BMpljodH.js").then((n) => n.l);
+					const { fetchQRCode } = await import("./weixin-api-PjEhmjlZ.js").then((n) => n.u);
 					const { randomUUID } = await import("node:crypto");
 					for (const [key, v] of weixinLogins) if (Date.now() - v.startedAt > WEIXIN_LOGIN_TTL_MS) weixinLogins.delete(key);
-					const { readWeixinSettings } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { readWeixinSettings } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const qr = await fetchQRCode({ botType: readWeixinSettings(root).botType ?? void 0 });
 					const loginKey = randomUUID();
 					weixinLogins.set(loginKey, {
@@ -6678,7 +6942,7 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$2(res, 400, { error: "missing accountId" });
 						return;
 					}
-					const { removeWeixinAccount } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { removeWeixinAccount } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 					removeWeixinAccount(root, body.accountId);
 					syncCccBridge(ctx, root);
@@ -6691,7 +6955,7 @@ function registerStatusApi(ctx, opts = {}) {
 						sendJson$2(res, 400, { error: "invalid routes (expected [{user, role}, ...])" });
 						return;
 					}
-					const { saveWeixinRoutes } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { saveWeixinRoutes } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const { readSkiffRoles } = await import("./skiff-role-BYvNnwv1.js").then((n) => n.u);
 					const roles = readSkiffRoles(root);
 					for (const r of routes) if (!roles.has(r.role)) {
@@ -6704,7 +6968,7 @@ function registerStatusApi(ctx, opts = {}) {
 				}
 				if (body.action === "set-enabled") {
 					const enabled = body.enabled === true;
-					const { readWeixinSettings, setWeixinEnabled } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+					const { readWeixinSettings, setWeixinEnabled } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 					const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 					const settings = readWeixinSettings(root);
 					if (enabled && (settings.accounts ?? []).length === 0) {
@@ -6750,8 +7014,8 @@ function registerStatusApi(ctx, opts = {}) {
 					sendJson$2(res, 200, { status: "expired" });
 					return;
 				}
-				const { pollQRStatus } = await import("./weixin-api-BMpljodH.js").then((n) => n.l);
-				const { readWeixinSettings } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+				const { pollQRStatus } = await import("./weixin-api-PjEhmjlZ.js").then((n) => n.u);
+				const { readWeixinSettings } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 				const settings = readWeixinSettings(login.root);
 				const status = await pollQRStatus({
 					baseUrl: void 0,
@@ -6766,7 +7030,7 @@ function registerStatusApi(ctx, opts = {}) {
 							});
 							return;
 						}
-						const { upsertWeixinAccount, writeWeixinCredential, nextWeixinAccountId } = await import("./weixin-route-DIaUYipW.js").then((n) => n.u);
+						const { upsertWeixinAccount, writeWeixinCredential, nextWeixinAccountId } = await import("./weixin-route-wWk4AIwV.js").then((n) => n.u);
 						const { syncCccBridge } = await Promise.resolve().then(() => weixin_bridge_exports);
 						const accountId = nextWeixinAccountId(settings);
 						upsertWeixinAccount(login.root, {
@@ -9239,19 +9503,31 @@ function sessionIdOf$1(value) {
 	const id = v?.session?.id ?? v?.id;
 	return typeof id === "string" && id !== "" ? id : null;
 }
-/** 工具调用是否为「成功的 weixin-send」 */
+/**
+* 工具调用是否为「成功的微信发送」。
+*
+* v1.31.0 起有两种合法形态（标记与闸门同时认，迁移期并存）：
+* - `im-bridge({channel:"weixin", action:"send"|"send-file", …})` —— ACC 工具（推荐）
+* - `msm("weixin-send", ["send"|"send-file", …])` —— CCC MSM（v1.30.x 通道，逐步退役）
+*/
 function isSuccessfulWeixinSend(exec, result) {
 	const e = exec;
-	if (e?.name !== "msm") return false;
-	if (e.arguments?.name !== "weixin-send") return false;
-	return result?.isError !== true;
+	if (result?.isError === true) return false;
+	const args = e?.arguments;
+	if (e?.name === "im-bridge") {
+		if ((typeof args?.channel === "string" ? args.channel : "") !== "weixin") return false;
+		const action = typeof args?.action === "string" ? args.action : "";
+		return action === "send" || action === "send-file";
+	}
+	if (e?.name === "msm") return args?.name === "weixin-send";
+	return false;
 }
 /** 打回消息（机制事实 + 标记；怎么做由 CCC 角色提示词定义） */
 function buildManualOutputRebuke(session) {
 	return [
 		"[serenity:weixin-manual-output] no send detected in this turn — the user has received NOTHING.",
 		`ccc=${session.root} account=${session.accountId} user=${session.userId}`,
-		`msm("weixin-send", ["send", "--ccc", "${session.root}", "--account", "${session.accountId}", "--user", "${session.userId}", "<回复>"])`
+		`im-bridge({channel:"weixin", action:"send", account:"${session.accountId}", user:"${session.userId}", text:"<回复>"})`
 	].join("\n");
 }
 /**
@@ -9358,7 +9634,8 @@ function buildOutgoingHookEvent(input) {
 		sessionId: input.sessionId,
 		role: input.role,
 		reply: input.reply,
-		...input.source && input.source !== "reply" ? { source: input.source } : {}
+		...input.source && input.source !== "reply" ? { source: input.source } : {},
+		...input.file ? { file: input.file } : {}
 	};
 }
 /**
@@ -9474,6 +9751,7 @@ var weixin_bridge_exports = /* @__PURE__ */ __exportAll({
 	handleIncoming: () => handleIncoming,
 	manualOutputFallbackNeeded: () => manualOutputFallbackNeeded,
 	registerWeixinBridge: () => registerWeixinBridge,
+	resolveWeixinAccount: () => resolveWeixinAccount,
 	sendProactiveText: () => sendProactiveText,
 	stopAllBridges: () => stopAllBridges,
 	stopCccBridge: () => stopCccBridge,
@@ -9571,14 +9849,14 @@ async function runAccountLoop(ctx, root, accountId, cred, loop) {
 * "约束不够，LLM 不听"——且措辞迭代要动插件代码 + 发版 + 重启；把措辞放 CCC 才能快速迭代，
 * 也符合"ACC 管机制、CCC 管内容"的归属二分。
 *
-* 标记格式（稳定，供 CCC 提示词引用）：
+* 标记格式（稳定，供 CCC 提示词引用；v1.31.0 起为 ACC 工具形态）：
 * ```
 * [serenity:weixin-manual-output]
-* msm("weixin-send", ["send", "--ccc", "<root>", "--account", "<account>", "--user", "<user>", "<回复>"])
+* im-bridge({channel:"weixin", action:"send", account:"<account>", user:"<user>", text:"<回复>"})
 * ```
 */
 function weixinManualOutputMarker(root, accountId, userId) {
-	return ["[serenity:weixin-manual-output]", `msm("weixin-send", ["send", "--ccc", "${root}", "--account", "${accountId}", "--user", "${userId}", "<回复>"])`].join("\n");
+	return ["[serenity:weixin-manual-output]", `im-bridge({channel:"weixin", action:"send", account:"${accountId}", user:"${userId}", text:"<回复>"})`].join("\n");
 }
 /**
 * 手动输出模式的**兜底判定**（纯函数，v1.30.17——把决策矩阵从装配里抽出来，可独立测试）。
@@ -9840,22 +10118,12 @@ function stopAllBridges() {
 	bridges.clear();
 }
 /**
-* 以 bot 身份主动给指定用户发文本（**不经用户消息触发**）。
-*
-* 为什么放在桥里而不是让 CCC 自己直连 iLink（用户拍板 A 方案）：
-* ① **记录归桥**——发送成功后触发既有 outgoing hook，`_weixin-logs/*.jsonl` 与对话回复
-*    同源同格式（事件多一个 `source: 'proactive'` 标记）；② 协议/账号/凭据解析单一真相源，
-*    CCC 侧不必重复实现 sendmessage；③ 多账号可选。
-*
-* 记录一致性：`sessionId` 取 `weixinSessionIdFor(toUserId)`——与该用户平时对话**同一条轨迹**，
-* 记录里能直接按会话串联；`role` 取该 CCC 路由命中角色（未命中 → 空串）。
-*
-* 主动消息不带 context_token（iLink 接受 bot 主动发起；带 token 的路径见 handleIncoming 回复）。
-* @param input CCC 根 + 目标用户 + 文本 +（可选）账号
-* @returns 成功含 accountId/userId/sessionId/role；失败含稳定 code 与可行动提示（不抛错）
+* 解析该 CCC 的发送账号 + 凭据（v1.31.0：文本与文件发送的**单一账号选择真相源**）。
+* 顺序：桥启用 → 有启用账号 → 指定账号存在 → 凭据已绑定（扫码）。
+* @param root CCC 根
+* @param accountId 指定账号（缺省 = 第一个启用账号）
 */
-async function sendProactiveText(input) {
-	const { root, toUserId } = input;
+function resolveWeixinAccount(root, accountId) {
 	const settings = readWeixinSettings(root);
 	if (!settings.enabled) return {
 		ok: false,
@@ -9870,20 +10138,32 @@ async function sendProactiveText(input) {
 		error: "微信桥未配置任何启用账号",
 		remediation: "在设置面板「微信桥」扫码绑定账号"
 	};
-	const accountId = input.accountId ?? accounts[0].accountId;
-	if (!accounts.some((a) => a.accountId === accountId)) return {
+	const id = accountId ?? accounts[0].accountId;
+	if (!accounts.some((a) => a.accountId === id)) return {
 		ok: false,
 		code: "ACCOUNT_NOT_FOUND",
-		error: `账号不存在或未启用: ${accountId}`,
+		error: `账号不存在或未启用: ${id}`,
 		remediation: `可用账号: ${accounts.map((a) => a.accountId).join(", ")}`
 	};
-	const cred = readWeixinCredential(root, accountId);
+	const cred = readWeixinCredential(root, id);
 	if (!cred) return {
 		ok: false,
 		code: "ACCOUNT_NOT_BOUND",
-		error: `账号未绑定（无凭据）: ${accountId}`,
+		error: `账号未绑定（无凭据）: ${id}`,
 		remediation: "在设置面板重新扫码绑定"
 	};
+	return {
+		ok: true,
+		accountId: id,
+		cred
+	};
+}
+async function sendProactiveText(input) {
+	const { root, toUserId } = input;
+	const settings = readWeixinSettings(root);
+	const account = resolveWeixinAccount(root, input.accountId);
+	if (!account.ok) return account;
+	const { accountId, cred } = account;
 	const sessionId = weixinSessionIdFor(toUserId);
 	const role = matchWeixinRoute(settings.routes ?? [], toUserId) ?? "";
 	try {
@@ -9959,7 +10239,9 @@ function registerWeixinBridge(ctx) {
 * 而 3081 的登录态属于"家庭账号"——一旦挂上去，任何已登录的外部用户都能冒充 bot 发消息。
 * 独立 loopback 监听器则**不经网关、公网不可达**，因此不做共享密钥；仍校验来源地址。
 *
-* 调用者 = CCC 自己的 MSM（`msm weixin-send ...`）：ACC **不新增工具**，只多一个本机 HTTP 面。
+* 调用者 = **非 agent 的调用者**（外部脚本/集成/运维）。**agent 侧已不走这里**：v1.31.0 起
+* agent 统一调 `im-bridge` 工具（进程内直调 `sendProactiveText`，无 HTTP 一跳），旧 CCC MSM
+* `weixin-send` 已退役。本入口保留 = 给容器外的进程一个稳定的本机发送面。
 * 发送与记录都经 `weixin-bridge.sendProactiveText` → 复用既有 outgoing hook（`source: 'proactive'`）。
 *
 * 契约：
@@ -10325,6 +10607,9 @@ function cleanupSessionState(sessionId) {
 	try {
 		forgetManualOutputSession(sessionId);
 	} catch {}
+	try {
+		forgetImBridgeVisibility(sessionId);
+	} catch {}
 }
 /**
 * 装配生命周期订阅与资源拆卸。
@@ -10548,6 +10833,243 @@ async function registerWebFetchProvider(ctx) {
 	}
 }
 //#endregion
+//#region src/im-weixin.ts
+/**
+* im-weixin.ts — 微信通道实现（`im-bridge` 的通道之一，v1.31.0）
+*
+* 能力归 ACC（S142 用户洞察）：本文件吸收原 CCC MSM `.opencode/skills/home-serenity/scripts/
+* weixin-send.ts` 的 `send` / `send-file` / `users` 语义——协议、凭据、账号选择、别名解析、
+* 记录全部落在 ACC 侧；CCC 只保留「何时发 / 发什么 / 怎么写」。
+*
+* 通道内部契约：
+* - `isEnabled(root)` = 该 CCC 的 `weixin.enabled`（可见性判据，im-bridge 用它决定工具是否可见）
+* - `send` 复用 `sendProactiveText`（唯一文本发送实现 + 唯一记录点）
+* - `sendFile` 走 iLink 上传（`weixin-api.sendFileMessage`）+ 同一 outgoing hook（带 `file` 元数据）
+*/
+/**
+* 别名 → CCC localstore 凭据键（与 v1.30.9 CCC MSM 逐字一致，迁移零认知成本）。
+* 别名解析属"数据填值"，归 ACC（D23）。
+*/
+const WEIXIN_ALIAS_MAP = {
+	yh: "WEIXIN_USER_YH",
+	danica: "WEIXIN_USER_DANICA",
+	xiaowang: "WEIXIN_USER_DANICA"
+};
+/** 读该 CCC 的一个凭据值（空/缺失 → null） */
+function credentialValue(root, key) {
+	try {
+		const value = readStore(root, "credential")[key];
+		return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+	} catch {
+		return null;
+	}
+}
+/** 把通道层的失败码转成一句可读错误（工具面统一映射为 SEND_FAILED） */
+function channelError(code, error, remediation) {
+	return /* @__PURE__ */ new Error(`${code}: ${error}${remediation ? ` — ${remediation}` : ""}`);
+}
+const weixinChannel = {
+	id: "weixin",
+	isEnabled(root) {
+		return readWeixinSettings(root).enabled === true;
+	},
+	resolveUser(root, input) {
+		const raw = input.trim();
+		if (raw === "") return null;
+		const alias = raw.toLowerCase();
+		const key = WEIXIN_ALIAS_MAP[alias];
+		if (key) {
+			const id = credentialValue(root, key);
+			return id ? {
+				alias,
+				id
+			} : null;
+		}
+		if (raw.includes("@")) return {
+			alias: raw,
+			id: raw
+		};
+		return null;
+	},
+	listUsers(root) {
+		const out = [];
+		for (const [alias, key] of Object.entries(WEIXIN_ALIAS_MAP)) {
+			const id = credentialValue(root, key);
+			if (id) out.push({
+				alias,
+				id
+			});
+		}
+		return out;
+	},
+	async send(input) {
+		const result = await sendProactiveText({
+			root: input.root,
+			toUserId: input.userId,
+			text: input.text,
+			...input.accountId ? { accountId: input.accountId } : {}
+		});
+		if (!result.ok) throw channelError(result.code, result.error, result.remediation);
+		return {
+			accountId: result.accountId,
+			userId: result.userId,
+			sessionId: result.sessionId,
+			role: result.role
+		};
+	},
+	async sendFile(input) {
+		const settings = readWeixinSettings(input.root);
+		if (!settings.enabled) throw channelError("BRIDGE_DISABLED", `微信桥未启用（ccc=${input.root}）`);
+		const account = resolveWeixinAccount(input.root, input.accountId);
+		if (!account.ok) throw channelError(account.code, account.error, account.remediation);
+		const sent = await sendFileMessage({
+			baseUrl: account.cred.baseUrl,
+			token: account.cred.token,
+			toUserId: input.userId,
+			data: input.data,
+			fileName: input.fileName
+		});
+		if (input.caption) await sendTextMessage({
+			baseUrl: account.cred.baseUrl,
+			token: account.cred.token,
+			toUserId: input.userId,
+			text: input.caption
+		});
+		if (settings.hook) {
+			const role = matchWeixinRoute(settings.routes ?? [], input.userId) ?? "";
+			invokeWeixinHook(input.root, settings.hook, buildOutgoingHookEvent({
+				cccRoot: input.root,
+				accountId: account.accountId,
+				userId: input.userId,
+				sessionId: weixinSessionIdFor(input.userId),
+				role,
+				reply: input.caption ? `[文件] ${sent.fileName} — ${input.caption}` : `[文件] ${sent.fileName}`,
+				source: "proactive",
+				file: {
+					name: sent.fileName,
+					size: sent.size,
+					...input.caption ? { caption: input.caption } : {}
+				}
+			})).catch((err) => {
+				console.log(`[serenity-hooks] weixin hook outgoing(file) error: ${err instanceof Error ? err.message : String(err)}`);
+			});
+		}
+		return sent;
+	},
+	/**
+	* 通道健康快照（`status` 动作）。
+	*
+	* 显式映射为 JSON 安全形状（而非把内部结构直接返回）：内部类型含 `undefined`
+	* 可选字段与 interface（无隐式索引签名）→ 直接返回既过不了 `ImJson` 类型门，
+	* 也会让工具返回值出现不可序列化字段。缺省用条件展开去掉 undefined。
+	*/
+	status(root) {
+		const settings = readWeixinSettings(root);
+		const accounts = weixinBridgeStatus().filter((entry) => entry.ccc === root).flatMap((entry) => entry.accounts.map((account) => ({
+			accountId: account.accountId,
+			lastPollAt: account.lastPollAt,
+			...account.lastError ? { lastError: account.lastError } : {}
+		})));
+		const routes = (settings.routes ?? []).map((route) => ({
+			user: route.user,
+			role: route.role
+		}));
+		return {
+			enabled: settings.enabled === true,
+			autoReplyWithLastMessage: settings.autoReplyWithLastMessage !== false,
+			fallbackOnNoSend: settings.fallbackOnNoSend === true,
+			routes,
+			accounts
+		};
+	}
+};
+//#endregion
+//#region src/tools/im-bridge.ts
+/**
+* im-bridge.ts（工具面）— IM 消息发送工具（v1.31.0）
+*
+* 用户洞察（S142）：微信桥是 ACC 提供的 → **发送能力也应是 ACC 的工具**；
+* 「当用户配置了微信桥则可用，不配置则不可见」。
+*
+* 本文件只做工具面三件事：① 从 agent 会话解析**本会话 CCC**（R4：不接受目标 CCC）
+* ② 把参数交给 `im-bridge.ts`（能力层）分发 ③ 渲染结果/错误。
+*
+* 可见性不在这里判定：`seams/context.ts` 在会话就绪时按 CCC 配置
+* `agent.ctx.tools.restrict({ deny: ['im-bridge'] })` 把本工具从**未配置通道**的
+* agent 工具清单中移除（未配置 = 模型看不到，而非"看得到但被拒"）。
+*/
+const ACTIONS = [
+	"send",
+	"send-file",
+	"users",
+	"status"
+];
+function agentCwd(exec) {
+	return exec.agent?.session?.header?.cwd ?? process.cwd();
+}
+function renderText(value) {
+	return [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}];
+}
+/**
+* IM 发送工具（`im-bridge`）。通道维度为将来其他 IM 预留（R3）——
+* 新增通道只注册实现，不改工具名与参数形状。
+*/
+function createImBridgeTool() {
+	return defineTool({
+		name: "im-bridge",
+		description: `Send messages to family members through an IM channel configured for THIS container (currently: weixin / 微信). Every successful send is recorded in the container log automatically; this tool only acts on the current container (no target container parameter). It is hidden entirely when this container has no IM channel configured. Channels: ${imChannelIds().join(", ") || "(none registered)"}. Actions: send (text) / send-file (a file inside this container) / users (list configured recipients) / status (channel health). user accepts a configured alias (e.g. yh, danica) or a raw channel user id. Failures return a stable code plus a remediation hint.`,
+		parameters: {
+			channel: {
+				type: "string",
+				description: `IM channel id (e.g. "weixin"); available: ${imChannelIds().join(", ") || "(none)"}`,
+				required: true
+			},
+			action: {
+				type: "string",
+				enum: [...ACTIONS],
+				required: true,
+				description: "send / send-file / users / status"
+			},
+			user: {
+				type: "string",
+				description: "Recipient: configured alias (yh, danica) or raw channel user id (send / send-file)"
+			},
+			text: {
+				type: "string",
+				description: "Message text, plain text only (send)"
+			},
+			file: {
+				type: "string",
+				description: "File path inside this container, relative to the container root (send-file)"
+			},
+			caption: {
+				type: "string",
+				description: "Optional caption sent as a separate message (send-file)"
+			},
+			account: {
+				type: "string",
+				description: "Channel account id (default: the first enabled, bound account)"
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: (_args, value) => renderText(value)
+		},
+		async execute(args, exec) {
+			const root = findSerenityRoot(agentCwd(exec));
+			if (!root) return {
+				ok: false,
+				code: "CCC_UNRESOLVED",
+				error: "this session is not inside a Serenity container (no .serenity marker found from the session cwd)"
+			};
+			return runImBridge(root, args);
+		}
+	});
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-serenity-hooks";
 /** 主动调用的服务；其余（agent 事件）随 harness 装配必然存在
@@ -10597,6 +11119,7 @@ function apply(ctx, config) {
 		const report = probeHostContract(ctx, readDshVersion());
 		if (report.issues.length > 0) console.warn(`[serenity-hooks] ${summarizeHostContract(report)}`);
 	} catch {}
+	registerImChannel(weixinChannel);
 	if (config.tools) {
 		ctx.tools.register(ccFsTool);
 		ctx.tools.register(createSessionTool(ctx));
@@ -10608,6 +11131,7 @@ function apply(ctx, config) {
 		ctx.tools.register(localstoreTool);
 		ctx.tools.register(containerAdminTool);
 		ctx.tools.register(createAutopilotTool(ctx));
+		ctx.tools.register(createImBridgeTool());
 	}
 	if (config.guards) registerGuards(ctx, { configPaths: config.serenityConfigPaths });
 	if (config.keeper) registerKeeper(ctx, {