@shgroup/dsh-serenity-hooks 1.27.1 → 1.27.4

package/lib/skiff-core.d.ts

@@ -31,10 +31,19 @@ export interface SkiffAgentRef {
     handle: AgentHandle;
     agent: Agent;
     sessionId: string;
+    /** true = 从持久化恢复既有会话（历史延续，非新对话）；false = 新建（首次/无持久化） */
+    resumed: boolean;
 }
 /**
  * 创建 Skiff agent：标准 DSH agent + cwd=CCC root + 角色模型 +
  * standard preset（平台工具面）+ scoped 系统提示词（基础提示词 + CCC 定义段，全替换 ACC 默认注入）。
+ *
+ * **固定 sessionId 的 resume-or-create（v1.27.2，微信桥 id collision 修复）**：
+ * 指定 sessionId 且磁盘已有持久化 log → `ctx.agents.resume`（DSH 持久化语义：
+ * sessionId 即身份，已持久化会话必须 resume——历史 + turn 续号延续，同用户长期记忆保留）；
+ * 无 log（首次）/持久化未配置 → `ctx.agents.create`（新建）。不指定 sessionId →
+ * 随机 id 恒 create（ACP/调试页默认路径）。
+ *
  * @param sessionId 指定会话 id（可选；微信桥等外部面用固定 id 实现用户↔会话长期映射——
  *   不传则随机生成 skiff-<role>-<uuid>，ACP/调试页默认路径）
  */

package/lib/{skiff-debug-ZVbIqttn.js → skiff-debug-BRlc17GU.js}

@@ -251,6 +251,13 @@ const SKIFF_PRESET = "standard";
 /**
 * 创建 Skiff agent：标准 DSH agent + cwd=CCC root + 角色模型 +
 * standard preset（平台工具面）+ scoped 系统提示词（基础提示词 + CCC 定义段，全替换 ACC 默认注入）。
+*
+* **固定 sessionId 的 resume-or-create（v1.27.2，微信桥 id collision 修复）**：
+* 指定 sessionId 且磁盘已有持久化 log → `ctx.agents.resume`（DSH 持久化语义：
+* sessionId 即身份，已持久化会话必须 resume——历史 + turn 续号延续，同用户长期记忆保留）；
+* 无 log（首次）/持久化未配置 → `ctx.agents.create`（新建）。不指定 sessionId →
+* 随机 id 恒 create（ACP/调试页默认路径）。
+*
 * @param sessionId 指定会话 id（可选；微信桥等外部面用固定 id 实现用户↔会话长期映射——
 *   不传则随机生成 skiff-<role>-<uuid>，ACP/调试页默认路径）
 */
@@ -258,19 +265,12 @@ async function createSkiffAgent(ctx, root, roleName, role, defaultModel, session
 	if (!ctx.agents) throw new Error("skiff: ctx.agents unavailable");
 	const model = role.model?.trim() || defaultModel || "";
 	const id = sessionId ?? `skiff-${roleName}-${randomUUID()}`;
-	const handle = await ctx.agents.create({
-		sessionId: id,
-		meta: {
-			cwd: root,
-			agentPreset: SKIFF_PRESET
-		},
-		setup: async (agentCtx) => {
-			try {
-				await agentCtx.get("agentPresets")?.mount?.(agentCtx, SKIFF_PRESET);
-			} catch {}
-		},
-		...model ? { agentOptions: splitModel(model) } : {}
-	});
+	const setup = async (agentCtx) => {
+		try {
+			await agentCtx.get("agentPresets")?.mount?.(agentCtx, SKIFF_PRESET);
+		} catch {}
+	};
+	const handle = await createOrResumeAgent(ctx, id, root, model, setup, sessionId !== void 0);
 	const agent = handle.agent;
 	let cccPrompt = "";
 	try {
@@ -291,8 +291,94 @@ async function createSkiffAgent(ctx, root, roleName, role, defaultModel, session
 	return {
 		handle,
 		agent,
-		sessionId: id
+		sessionId: id,
+		resumed: handle.resumed
+	};
+}
+/** 取 live agent（DSH 文档：`ctx.agents.get(id)` 返回 bare Agent；会话 live 时 resume/create 均不可用） */
+function getLiveAgent(ctx, id) {
+	try {
+		return ctx.agents?.get?.(id);
+	} catch {
+		return;
+	}
+}
+/** live 复用返回（resumed:true 历史延续；dispose 空操作——live agent 不归本模块所有，不能拆） */
+function liveReuseRef(live, setup) {
+	return setup(live.ctx).catch(() => {}).then(() => ({
+		agent: live,
+		dispose: async () => {},
+		resumed: true
+	}));
+}
+/**
+* resume-or-create 分派：固定 id → 优先 resume（持久化历史延续），失败降级 create；
+* 随机 id（无固定 sessionId）→ 恒 create。返回 handle + resumed 标志。
+*
+* **v1.27.3 修复（微信桥"重启后不响应"根因）：live 会话优先复用**——重启后 DSH 把
+* 关闭时仍 live 的持久化会话恢复为 live（crash/restart 恢复语义）。此时 resume 报
+* "cannot prepare session X while it is live"（session-persistence coordinator 显式
+* 拒绝 live 会话）、create 报 "session X already exists"（磁盘有持久化 log 必拒）→
+* 微信桥 catch 吞错 → 用户消息无回复。唯一可行路径 = `ctx.agents.get(id)` 取 live
+* agent 直接续用（resumed:true；角色提示词重挂与内存注册表登记由 createSkiffAgent 统一做）。
+*/
+async function createOrResumeAgent(ctx, id, root, model, setup, fixedId) {
+	if (!fixedId) return {
+		...await ctx.agents.create({
+			sessionId: id,
+			meta: {
+				cwd: root,
+				agentPreset: SKIFF_PRESET
+			},
+			setup,
+			...model ? { agentOptions: splitModel(model) } : {}
+		}),
+		resumed: false
+	};
+	const liveAgent = getLiveAgent(ctx, id);
+	if (liveAgent) return liveReuseRef(liveAgent, setup);
+	const agentsWithResume = ctx.agents;
+	if (typeof agentsWithResume.resume !== "function") return {
+		...await ctx.agents.create({
+			sessionId: id,
+			meta: {
+				cwd: root,
+				agentPreset: SKIFF_PRESET
+			},
+			setup,
+			...model ? { agentOptions: splitModel(model) } : {}
+		}),
+		resumed: false
 	};
+	try {
+		return {
+			...await agentsWithResume.resume({
+				resumeSessionId: id,
+				setup,
+				...model ? { agentOptions: splitModel(model) } : {}
+			}),
+			resumed: true
+		};
+	} catch (err) {
+		const liveNow = getLiveAgent(ctx, id);
+		if (liveNow) return liveReuseRef(liveNow, setup);
+		const msg = err instanceof Error ? err.message : String(err);
+		const stack = err instanceof Error ? err.stack ?? "" : "";
+		console.log(`[serenity-hooks] skiff resume 失败降级 create (id=${id}): ${msg}`);
+		if (stack) console.log(`[serenity-hooks] skiff resume stack:\n${stack.slice(0, 1200)}`);
+		return {
+			...await ctx.agents.create({
+				sessionId: id,
+				meta: {
+					cwd: root,
+					agentPreset: SKIFF_PRESET
+				},
+				setup,
+				...model ? { agentOptions: splitModel(model) } : {}
+			}),
+			resumed: false
+		};
+	}
 }
 /** 等待 agent 空闲（agent/status → idle）；无超时（agent 工作多久等多久，handyman 同款） */
 function waitIdle(ctx, agent) {

package/lib/tools/{autotrajectory-exp.d.ts → autopilot-trajectory.d.ts}

@@ -1,8 +1,9 @@
 /**
- * autotrajectory-exp.ts — 自主轨迹实验一站式管理工具（v1.26.12 实验提案，默认关）
+ * autopilot-trajectory.ts — Autopilot Trajectory 一站式管理工具（v1.26.12 实验
+ * autotrajectory-exp → v1.27.4 正式化改名）
  *
- * 定位：dsp **只提供工具与知识**，不向 CCC 自动安装任何东西（实验可能失败，不污染 CCC）——
- * 实验是 CCC 的自选动作：agent 调本工具（doc/全报告）即懂实验，init/random/check 辅助，
+ * 定位：dsp **只提供工具与知识**，不向 CCC 自动安装任何东西（机制是 CCC 的自选动作）——
+ * agent 调本工具（doc/全报告）即懂机制，init/random/check 辅助，
  * 实际执行（写配置/写偏见脚本/标记会话）由 CCC 自己决定、自己用现有工具完成。
  *
  * 实现：薄封装——exec 包内静态脚本（npm files 含 experiments/），脚本是单一真相源。
@@ -13,12 +14,12 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import type { Context } from 'cordis';
 /**
- * 定位包内实验脚本（npm files 分发 experiments/autotrajectory/）。
+ * 定位包内脚本（npm files 分发 experiments/autopilot-trajectory/）。
  * 布局差异：tsdown bundle 后 import.meta.url 指向 lib/index.js（lib → 包根 1 层）；
  * vitest 源码直跑时指向 src/tools/x.ts（src/tools → 包根 2 层）——逐级上溯查找，
- * 两种布局都稳（找到 experiments/autotrajectory/scripts/autotrajectory-exp.ts 即止）。
+ * 两种布局都稳（找到 experiments/autopilot-trajectory/scripts/autopilot-trajectory.ts 即止）。
  */
 export declare function findExpScript(startDir: string): string | null;
-export declare const AUTO_TRAJECTORY_EXP_ACTIONS: readonly ["all", "init", "random", "diag", "doc", "check", "status", "guide", "diag-live"];
-/** 创建 autotrajectory-exp 工具（闭包捕获 ctx → diag-live 进程内诊断；v1.26.14） */
-export declare function createAutoTrajectoryExpTool(ctx: Context): ReturnType<typeof defineTool>;
+export declare const AUTOPILOT_ACTIONS: readonly ["all", "init", "random", "diag", "doc", "check", "status", "guide", "diag-live"];
+/** 创建 autopilot-trajectory 工具（闭包捕获 ctx → diag-live 进程内诊断；v1.26.14 + v1.27.4 改名） */
+export declare function createAutopilotTool(ctx: Context): ReturnType<typeof defineTool>;

package/lib/{weixin-api-b8HLmcPE.js → weixin-api-DAugVJ-f.js}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { randomBytes } from "node:crypto";
+import { createDecipheriv, randomBytes } from "node:crypto";
 //#region src/weixin-api.ts
 /**
 * weixin-api.ts — 微信个人号 iLink Bot API 客户端（F4c-3，v1.27.0 实验性）
@@ -23,15 +23,25 @@ var weixin_api_exports = /* @__PURE__ */ __exportAll({
 	MessageItemType: () => MessageItemType,
 	MessageState: () => MessageState,
 	MessageType: () => MessageType,
+	TypingStatus: () => TypingStatus,
+	aes128EcbDecrypt: () => aes128EcbDecrypt,
 	buildClientVersion: () => buildClientVersion,
+	buildMediaDownloadUrl: () => buildMediaDownloadUrl,
+	downloadMedia: () => downloadMedia,
 	fetchQRCode: () => fetchQRCode,
+	getConfig: () => getConfig,
 	getUpdates: () => getUpdates,
 	markdownToPlainText: () => markdownToPlainText,
+	parseMediaAesKey: () => parseMediaAesKey,
 	pollQRStatus: () => pollQRStatus,
-	sendTextMessage: () => sendTextMessage
+	sendTextMessage: () => sendTextMessage,
+	sendTyping: () => sendTyping,
+	sniffImageExt: () => sniffImageExt
 });
 /** iLink API Base URL（腾讯官方） */
 const ILINK_DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+/** CDN Base（媒体上传/下载；P3 媒体期用） */
+const ILINK_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
 /** iLink-App-Id（openclaw-weixin 同款） */
 const ILINK_APP_ID = "bot";
 /** 通道版本（对齐 openclaw-weixin 2.1.1；buildClientVersion 编码） */
@@ -193,6 +203,119 @@ async function sendTextMessage(params) {
 		timeoutMs: params.timeoutMs ?? 15e3
 	});
 }
+/** sendtyping status：1=TYPING（开始）0=CANCEL（结束）。
+*  ⚠️ 对齐**官方 openclaw-weixin 参考实现**（index.ts onReplyStart → status 1 /
+*  onCleanup → status 0）——早期协议注释"2=CANCEL"为误记，以参考实现为准。 */
+const TypingStatus = {
+	TYPING: 1,
+	CANCEL: 0
+};
+/** 取对话配置（typing_ticket：sendtyping 的前置——先 getconfig 拿 ticket 再发状态） */
+async function getConfig(params) {
+	const rawText = await apiPost({
+		baseUrl: params.baseUrl,
+		endpoint: "ilink/bot/getconfig",
+		body: JSON.stringify({
+			ilink_user_id: params.ilinkUserId,
+			context_token: params.contextToken
+		}),
+		token: params.token,
+		timeoutMs: params.timeoutMs ?? 1e4
+	});
+	return JSON.parse(rawText);
+}
+/** 发送"正在输入"状态（status: 1=开始 0=结束；ticket 来自 getConfig） */
+async function sendTyping(params) {
+	await apiPost({
+		baseUrl: params.baseUrl,
+		endpoint: "ilink/bot/sendtyping",
+		body: JSON.stringify({
+			ilink_user_id: params.ilinkUserId,
+			typing_ticket: params.typingTicket,
+			status: params.status
+		}),
+		token: params.token,
+		timeoutMs: params.timeoutMs ?? 1e4
+	});
+}
+/** 构造 CDN 下载 URL（full_url 优先；否则 encrypted_query_param 拼 download 端点；都无 → null） */
+function buildMediaDownloadUrl(media) {
+	if (media.full_url) return media.full_url;
+	if (media.encrypt_query_param) return `${ILINK_CDN_BASE_URL}/download?encrypted_query_param=${encodeURIComponent(media.encrypt_query_param)}`;
+	return null;
+}
+/**
+* 解析媒体 AES key（兼容三种编码，对齐参考实现）：
+* ① 32+ hex 字符 → hex Buffer(16)  ② base64 解码 = 16 字节直接用
+* ③ base64 解码 = 32 字节 → ascii 是 hex 串 → 再 hex → Buffer(16)；其他 → null
+*/
+function parseMediaAesKey(keyText) {
+	if (!keyText) return null;
+	if (/^[0-9a-fA-F]{32,}$/.test(keyText)) {
+		const buf = Buffer.from(keyText, "hex");
+		return buf.length === 16 ? buf : null;
+	}
+	try {
+		const decoded = Buffer.from(keyText, "base64");
+		if (decoded.length === 16) return decoded;
+		if (decoded.length === 32) {
+			const hexStr = decoded.toString("ascii");
+			if (/^[0-9a-fA-F]{32}$/.test(hexStr)) return Buffer.from(hexStr, "hex");
+		}
+	} catch {}
+	return null;
+}
+/** AES-128-ECB 解密（无 IV；node:crypto 内置） */
+function aes128EcbDecrypt(data, key) {
+	const decipher = createDecipheriv("aes-128-ecb", key, null);
+	return Buffer.concat([decipher.update(data), decipher.final()]);
+}
+/** 图片 magic-byte 嗅探（vlm-describe 支持 jpg/png/gif/webp/bmp——比固定 .jpg 可靠） */
+function sniffImageExt(data) {
+	if (data.length >= 3 && data[0] === 255 && data[1] === 216 && data[2] === 255) return "jpg";
+	if (data.length >= 8 && data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) return "png";
+	if (data.length >= 3 && data[0] === 71 && data[1] === 73 && data[2] === 70) return "gif";
+	if (data.length >= 12 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP") return "webp";
+	if (data.length >= 2 && data[0] === 66 && data[1] === 77) return "bmp";
+	return "bin";
+}
+/**
+* 下载 + 解密一条媒体（图片/文件）。失败/超时/无 URL → null（不抛——调用方降级）。
+* key 提取：item.aeskey || item.media.aes_key（对齐参考实现）。
+*/
+async function downloadMedia(params) {
+	const mediaItem = params.item[params.mediaType];
+	if (!mediaItem) return null;
+	const media = mediaItem.media;
+	const url = buildMediaDownloadUrl(media ?? {});
+	if (!url) return null;
+	const itemKey = mediaItem.aeskey;
+	const fileName = mediaItem.file_name;
+	const key = parseMediaAesKey(itemKey ?? media?.aes_key);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 3e4);
+	try {
+		const res = await currentFetch(url, { signal: controller.signal });
+		if (!res.ok) return null;
+		const buf = Buffer.from(await res.arrayBuffer());
+		if (key) try {
+			return {
+				data: aes128EcbDecrypt(buf, key),
+				fileName
+			};
+		} catch {
+			return null;
+		}
+		return {
+			data: buf,
+			fileName
+		};
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
 /** Markdown → 纯文本（代码块/图片/链接/表格/标题/粗斜体/删除线 7 类） */
 function markdownToPlainText(text) {
 	let result = text;
@@ -208,4 +331,4 @@ function markdownToPlainText(text) {
 	return result.trim();
 }
 //#endregion
-export { sendTextMessage as n, weixin_api_exports as r, getUpdates as t };
+export { sendTextMessage as a, weixin_api_exports as c, getUpdates as i, downloadMedia as n, sendTyping as o, getConfig as r, sniffImageExt as s, TypingStatus as t };

package/lib/weixin-api.d.ts

@@ -47,16 +47,50 @@ export declare function pollQRStatus(params: {
     qrcode: string;
     timeoutMs?: number;
 }): Promise<QrStatusResult>;
+/** CDN 媒体元数据（下载侧；协议见 docs/weixin-bot-api.md §6） */
+export interface CDNMedia {
+    encrypt_query_param?: string;
+    aes_key?: string;
+    encrypt_type?: number;
+    full_url?: string;
+}
+/** 媒体项引用（extractWeixinMedia 产物：kind + **完整消息项**——downloadMedia 用 item[mediaType] 提取） */
+export interface WeixinMediaRef {
+    kind: 'image' | 'file';
+    fileName?: string;
+    item: WeixinMessageItem;
+}
 export interface WeixinMessageItem {
     type?: number;
     msg_id?: string;
     text_item?: {
         text?: string;
     };
-    image_item?: Record<string, unknown>;
-    voice_item?: Record<string, unknown>;
-    file_item?: Record<string, unknown>;
-    video_item?: Record<string, unknown>;
+    image_item?: {
+        media?: CDNMedia;
+        thumb_media?: CDNMedia;
+        aeskey?: string;
+        url?: string;
+        mid_size?: number;
+        thumb_size?: number;
+    };
+    /** 语音项：**text = 微信服务端自带语音转写**（官方 openclaw-weixin 直接读该字段，无需下载/ASR） */
+    voice_item?: {
+        text?: string;
+        media?: CDNMedia;
+        playtime?: number;
+    };
+    file_item?: {
+        media?: CDNMedia;
+        file_name?: string;
+        md5?: string;
+        len?: string;
+    };
+    video_item?: {
+        media?: CDNMedia;
+        video_size?: number;
+        thumb_media?: CDNMedia;
+    };
 }
 export interface WeixinMessage {
     seq?: number;
@@ -115,5 +149,58 @@ export declare function sendTextMessage(params: {
     clientId?: string;
     timeoutMs?: number;
 }): Promise<void>;
+/** sendtyping status：1=TYPING（开始）0=CANCEL（结束）。
+ *  ⚠️ 对齐**官方 openclaw-weixin 参考实现**（index.ts onReplyStart → status 1 /
+ *  onCleanup → status 0）——早期协议注释"2=CANCEL"为误记，以参考实现为准。 */
+export declare const TypingStatus: {
+    readonly TYPING: 1;
+    readonly CANCEL: 0;
+};
+export interface GetConfigResp {
+    ret?: number;
+    errmsg?: string;
+    typing_ticket?: string;
+}
+/** 取对话配置（typing_ticket：sendtyping 的前置——先 getconfig 拿 ticket 再发状态） */
+export declare function getConfig(params: {
+    baseUrl: string;
+    token: string;
+    ilinkUserId: string;
+    contextToken: string;
+    timeoutMs?: number;
+}): Promise<GetConfigResp>;
+/** 发送"正在输入"状态（status: 1=开始 0=结束；ticket 来自 getConfig） */
+export declare function sendTyping(params: {
+    baseUrl: string;
+    token: string;
+    ilinkUserId: string;
+    typingTicket: string;
+    status: number;
+    timeoutMs?: number;
+}): Promise<void>;
+/** 构造 CDN 下载 URL（full_url 优先；否则 encrypted_query_param 拼 download 端点；都无 → null） */
+export declare function buildMediaDownloadUrl(media: CDNMedia): string | null;
+/**
+ * 解析媒体 AES key（兼容三种编码，对齐参考实现）：
+ * ① 32+ hex 字符 → hex Buffer(16)  ② base64 解码 = 16 字节直接用
+ * ③ base64 解码 = 32 字节 → ascii 是 hex 串 → 再 hex → Buffer(16)；其他 → null
+ */
+export declare function parseMediaAesKey(keyText?: string): Buffer | null;
+/** AES-128-ECB 解密（无 IV；node:crypto 内置） */
+export declare function aes128EcbDecrypt(data: Buffer, key: Buffer): Buffer;
+/** 图片 magic-byte 嗅探（vlm-describe 支持 jpg/png/gif/webp/bmp——比固定 .jpg 可靠） */
+export declare function sniffImageExt(data: Buffer): 'jpg' | 'png' | 'gif' | 'webp' | 'bmp' | 'bin';
+/**
+ * 下载 + 解密一条媒体（图片/文件）。失败/超时/无 URL → null（不抛——调用方降级）。
+ * key 提取：item.aeskey || item.media.aes_key（对齐参考实现）。
+ */
+export declare function downloadMedia(params: {
+    item: WeixinMessageItem;
+    mediaType: 'image_item' | 'file_item';
+    timeoutMs?: number;
+}): Promise<{
+    data: Buffer;
+    fileName?: string;
+} | null>;
 /** Markdown → 纯文本（代码块/图片/链接/表格/标题/粗斜体/删除线 7 类） */
 export declare function markdownToPlainText(text: string): string;

package/lib/weixin-bridge.d.ts

@@ -14,23 +14,28 @@
  */
 import type { Context } from 'cordis';
 import { type WeixinAccountCredential } from './weixin-route.js';
+import { type WeixinMessage } from './weixin-api.js';
+/** 测试辅助：清空 typing_ticket 缓存（生产零调用） */
+export declare function resetWeixinTypingCache(): void;
 /**
  * 处理单条微信消息：路由 → skiff 会话（固定 id 创建/延续）→ 提问 → 回复回写。
  *
  * 会话语义：`weixinSessionIdFor(fromUserId)` 固定可重建——同用户长期同一会话；
  * 进程内已有（getSkiffAgent 命中）→ 延续；无（首次/进程重启）→ createSkiffAgent
- * 以固定 id 新建（角色不变，记忆从新开始——重启后自动重建，与 3100 问答页同语义）。
+ * 固定 id resume-or-create（v1.27.2）：磁盘已有持久化 log → resume（历史延续，
+ * 重启后记忆保留——真正的"同用户长期延续"）；无 log（首次）→ create。
+ * "新的对话已开始"通知仅真正首次（create）时发送；resume/进程内延续不发。
+ *
+ * 完善（v1.27.3）：
+ * - **语音支持**：`voice_item.text` = 微信服务端自带语音转写 → 与文本同路径进对话
+ *   （无需下载/ASR）；语音无转写 → 降级提示"暂时无法解析"
+ * - **正在输入**：处理前 sendtyping 1（微信显示"正在输入..."），处理后（含异常）0
+ * - **媒体接收（图片/文件）**：桥侧 CDN 下载 + AES 解密 → 落盘 CCC 根
+ *   `_tmp/weixin-inbound/<userhash>/` → question 注入「存在性 + 路径」（ACC 层只保证
+ *   可达性——"让会话知道文件的存在并可以拿到"；识别/解析归角色 LLM 决策，不编排）。
+ *   降级不静默：下载失败 / 超 20MB → 注入说明进对话；typing 窗口覆盖下载（M7）。
  */
-export declare function handleIncoming(ctx: Context, root: string, _accountId: string, cred: WeixinAccountCredential, msg: {
-    from_user_id?: string;
-    context_token?: string;
-    item_list?: Array<{
-        type?: number;
-        text_item?: {
-            text?: string;
-        };
-    }>;
-}): Promise<void>;
+export declare function handleIncoming(ctx: Context, root: string, accountId: string, cred: WeixinAccountCredential, msg: Pick<WeixinMessage, 'from_user_id' | 'context_token' | 'item_list'>): Promise<void>;
 /**
  * 启动/重建某 CCC 的桥：读配置 → 对每个 enabled + 有凭据的账号启动轮询循环。
  * 已存在（配置变化热重建）→ 先停旧循环再启动新的。

package/lib/{weixin-route-CDdlFn1E.js → weixin-route-EVu56Ytp.js}

@@ -282,7 +282,8 @@ function runLocalStore(root, args) {
 * 职责（零 DSH 依赖，可独立单测）：
 * - 读取 CCC 的 weixin 配置（.opencode/serenity.json weixin 段——结构/路由/开关）
 * - 读取/写入 CCC localstore 的账号凭据（weixin.accounts.<accountId>.token/.baseUrl/.userId）
-* - 微信用户 → skiff 会话 id 映射（固定可重建：skiff-weixin-<sha256(userid)>.slice(16)）
+* - 微信用户 → skiff 会话 id 映射（固定可重建：skiff-weixin-<sha256(userid)>.slice(1, 17)；
+*   v1.27.3 错位一位避开损坏 log）
 * - 路由匹配（exact user → 通配 * 兜底）
 *
 * 配置归属（S142 用户拍板）：**CCC 级**——serenity.json 结构 + localstore 凭据分离；
@@ -291,15 +292,19 @@ function runLocalStore(root, args) {
 var weixin_route_exports = /* @__PURE__ */ __exportAll({
 	WEIXIN_SESSION_PREFIX: () => WEIXIN_SESSION_PREFIX,
 	clearWeixinCredential: () => clearWeixinCredential,
+	extractWeixinMedia: () => extractWeixinMedia,
 	extractWeixinText: () => extractWeixinText,
+	hasVoiceItem: () => hasVoiceItem,
 	matchWeixinRoute: () => matchWeixinRoute,
 	nextWeixinAccountId: () => nextWeixinAccountId,
 	readWeixinCredential: () => readWeixinCredential,
 	readWeixinSettings: () => readWeixinSettings,
 	removeWeixinAccount: () => removeWeixinAccount,
+	sanitizeFileName: () => sanitizeFileName,
 	saveWeixinRoutes: () => saveWeixinRoutes,
 	setWeixinEnabled: () => setWeixinEnabled,
 	upsertWeixinAccount: () => upsertWeixinAccount,
+	weixinInboundDir: () => weixinInboundDir,
 	weixinSessionIdFor: () => weixinSessionIdFor,
 	writeWeixinCredential: () => writeWeixinCredential
 });
@@ -312,9 +317,12 @@ function accountKeyPart(accountId) {
 }
 /** 微信桥 skiff 会话 id 前缀（seams 旁路判定；对外面纯净——守卫识别外部面） */
 const WEIXIN_SESSION_PREFIX = "skiff-weixin-";
-/** 微信用户 → 固定会话 id（同用户长期同一会话，记忆延续；多用户天然隔离） */
+/** 微信用户 → 固定会话 id（同用户长期同一会话，记忆延续；多用户天然隔离）。
+*  **v1.27.2 错位一位（用户拍板）**：`.slice(0, 16)` → `.slice(1, 17)`——旧规则生成的
+*  固定 id 已与磁盘损坏的持久化 log 绑定（dsh 不可硬删，create 同 id 必撞）→
+*  新规则下同用户生成**全新 id**，避开损坏 log；固定可重建语义不变（同用户恒同 id）。 */
 function weixinSessionIdFor(fromUserId) {
-	const digest = createHash("sha256").update(fromUserId).digest("hex").slice(0, 16);
+	const digest = createHash("sha256").update(fromUserId).digest("hex").slice(1, 17);
 	return `${WEIXIN_SESSION_PREFIX}${digest}`;
 }
 /**
@@ -386,18 +394,59 @@ function matchWeixinRoute(routes, fromUserId) {
 	return null;
 }
 /**
-* 提取消息文本（item_list 首条 text_item；非文本消息 → null——P1 只处理文本）。
+* 提取消息文本（文本项 + **语音项的服务端转写**）：
+* - type 1 TEXT → `text_item.text`
+* - type 3 VOICE → `voice_item.text`——**微信服务端自带语音转写**（官方 openclaw-weixin
+*   直接读该字段并入对话文本，无需下载/ASR；对齐参考实现 index.ts voiceTexts）。
 * @returns 纯文本；无文本 → null
 */
 function extractWeixinText(msg) {
 	const items = msg.item_list;
 	if (!Array.isArray(items) || items.length === 0) return null;
-	for (const item of items) if (item.type === 1 && typeof item.text_item?.text === "string") {
-		const text = item.text_item.text.trim();
-		return text === "" ? null : text;
+	for (const item of items) {
+		if (item.type === 1 && typeof item.text_item?.text === "string") {
+			const text = item.text_item.text.trim();
+			if (text !== "") return text;
+		}
+		if (item.type === 3 && typeof item.voice_item?.text === "string") {
+			const text = item.voice_item.text.trim();
+			if (text !== "") return text;
+		}
 	}
 	return null;
 }
+/** 是否包含语音项（无转写文本时的降级提示判定——bridge 用） */
+function hasVoiceItem(msg) {
+	return (msg.item_list ?? []).some((item) => item.type === 3 && item.voice_item != null);
+}
+/**
+* 提取消息媒体项（图片 type 2 / 文件 type 4）：
+* 只收集**带 media 元数据**的项（下载前置条件）；返回 kind + **完整消息项**（downloadMedia 用
+* `item[mediaType]` 取 image_item/file_item）。纯 ACC 层可达性——不做内容处理（v0.2 用户拍板）。
+*/
+function extractWeixinMedia(msg) {
+	const out = [];
+	for (const item of msg.item_list ?? []) if (item.type === 2 && item.image_item?.media) out.push({
+		kind: "image",
+		fileName: void 0,
+		item
+	});
+	else if (item.type === 4 && item.file_item?.media) out.push({
+		kind: "file",
+		fileName: item.file_item.file_name,
+		item
+	});
+	return out;
+}
+/** 文件名净化：basename + 去控制字符 + 截断 128（防路径穿越——落盘安全） */
+function sanitizeFileName(name) {
+	return (name.split(/[\\/]/).pop() ?? "").replace(/[\x00-\x1f\x7f]/g, "").trim().slice(0, 128);
+}
+/** 落盘目录：`<CCC 根>/_tmp/weixin-inbound/<userhash>/`（gitignored ✓；agent read 边界内 ✓；按用户分目录） */
+function weixinInboundDir(root, fromUserId) {
+	const userHash = createHash("sha256").update(fromUserId).digest("hex").slice(0, 12);
+	return join(root, "_tmp", "weixin-inbound", userHash);
+}
 /**
 * 读取 serenity.json 文件（原始；不存在 → 空对象）。
 * 注意：loadSerenityConfig 返回解析对象但无法写回——此处直接文件读写。
@@ -482,4 +531,4 @@ function setWeixinEnabled(root, enabled) {
 	return next;
 }
 //#endregion
-export { weixinSessionIdFor as a, checkLocalstoreGitCompliance as c, runLocalStore as d, readWeixinSettings as i, localstorePath as l, matchWeixinRoute as n, weixin_route_exports as o, readWeixinCredential as r, LOCALSTORE_SCOPES as s, extractWeixinText as t, readGitTrack as u };
+export { readWeixinCredential as a, weixinInboundDir as c, LOCALSTORE_SCOPES as d, checkLocalstoreGitCompliance as f, runLocalStore as h, matchWeixinRoute as i, weixinSessionIdFor as l, readGitTrack as m, extractWeixinText as n, readWeixinSettings as o, localstorePath as p, hasVoiceItem as r, sanitizeFileName as s, extractWeixinMedia as t, weixin_route_exports as u };