@next-open-ai/openclawx 0.8.17 → 0.8.22

package/dist/core/memory/compaction-extension.js

@@ -1,23 +1,15 @@
-import { addMemory } from "./index.js";
 /**
- * 创建用于在 session_compact 事件时把 compaction summary 写入向量库的 extension factory。
- * 在 AgentSession 发生 compaction（自动或手动）后触发，无需等到关闭会话。
+ * 创建用于在 session_compact 事件时更新「当前 session 最新 compaction」的 extension factory。
+ * 发生 compaction 时只回调 onUpdateLatestCompaction(summary)，由调用方保存；
+ * 向量库写入推迟到 SessionAgent 关闭时由 AgentManager 统一执行。
  */
-export function createCompactionMemoryExtensionFactory(sessionId) {
+export function createCompactionMemoryExtensionFactory(_sessionId, onUpdateLatestCompaction) {
     return (pi) => {
-        pi.on("session_compact", async (event) => {
+        pi.on("session_compact", (event) => {
             const summary = event.compactionEntry?.summary?.trim();
             if (!summary)
                 return;
-            try {
-                await addMemory(summary, {
-                    infotype: "compaction",
-                    sessionId,
-                });
-            }
-            catch (_) {
-                // 写入失败不打断会话
-            }
+            onUpdateLatestCompaction(summary);
         });
     };
 }

package/dist/core/memory/embedding-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Embedding 抽象：便于后续切换不同实现（在线 OpenAPI、node-llama-cpp GGUF 等）。
+ * 调用方仅依赖 embed(text) => Promise<number[] | null>。
+ */
+export interface IEmbeddingProvider {
+    /** 单条文本向量化，不可用时返回 null */
+    embed(text: string): Promise<number[] | null>;
+    /** 提供方名称，用于日志 */
+    readonly name: string;
+}

package/dist/core/memory/embedding-types.js

@@ -0,0 +1,5 @@
+/**
+ * Embedding 抽象：便于后续切换不同实现（在线 OpenAPI、node-llama-cpp GGUF 等）。
+ * 调用方仅依赖 embed(text) => Promise<number[] | null>。
+ */
+export {};

package/dist/core/memory/embedding.d.ts

@@ -1,4 +1,5 @@
 /**
- * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ * 对单条文本做 embedding。
+ * 未配置在线或在线连接失败时使用本地 embedding；均不可用时返回 null（仅首次打日志）。
  */
 export declare function embed(text: string): Promise<number[] | null>;

package/dist/core/memory/embedding.js

@@ -1,15 +1,47 @@
 /**
- * 文本 embedding：使用 config.json 中配置的远端 RAG embedding 模型。
- * 未配置时返回 null，调用方（长记忆）空转。
+ * 文本 embedding 统一入口（供 memory 向量库等使用）。
+ *
+ * 使用逻辑：
+ * - 未配置在线 embedding：直接使用本地 embedding（GGUF）。
+ * - 已配置在线 embedding：先尝试在线；若请求失败（无法连接、超时、返回错误等），则回退到本地 embedding。
+ * - 本地也不可用时返回 null，长记忆空转。
  */
 import { getRagEmbeddingConfigSync } from "../config/desktop-config.js";
 import { embedRemote } from "./remote-embedding.js";
+import { getLocalEmbeddingProvider, getLocalEmbeddingUnavailableReason } from "./local-embedding.js";
+let fallbackLogged = false;
+let unavailableLogged = false;
 /**
- * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ * 对单条文本做 embedding。
+ * 未配置在线或在线连接失败时使用本地 embedding；均不可用时返回 null（仅首次打日志）。
  */
 export async function embed(text) {
     const config = getRagEmbeddingConfigSync();
-    if (!config)
-        return null;
-    return embedRemote(text, config);
+    if (config) {
+        try {
+            const vec = await embedRemote(text, config);
+            if (Array.isArray(vec) && vec.length > 0)
+                return vec;
+        }
+        catch {
+            // 配置了在线但请求失败（无法连接等），下面使用本地
+        }
+        if (!fallbackLogged) {
+            fallbackLogged = true;
+            console.warn("[RAG embedding] 在线模型不可用，已切换至本地模型（GGUF）");
+        }
+    }
+    const local = await getLocalEmbeddingProvider();
+    if (local) {
+        const vec = await local.embed(text);
+        if (Array.isArray(vec) && vec.length > 0)
+            return vec;
+    }
+    if (!unavailableLogged) {
+        unavailableLogged = true;
+        const reason = getLocalEmbeddingUnavailableReason();
+        const reasonSuffix = reason ? ` 原因: ${reason}` : "（若为首次加载，请先执行 npm run build 后重启桌面端以查看具体原因）";
+        console.warn("[RAG embedding] 本地模型也不可用，长记忆将空转。" + reasonSuffix);
+    }
+    return null;
 }

package/dist/core/memory/index.js

@@ -26,6 +26,9 @@ export async function addMemory(text, metadata) {
         createdAt: new Date().toISOString(),
     };
     await addToStore(id, vec, text, meta);
+    if (metadata.infotype === "experience") {
+        console.log(`[Memory] 经验已写入向量库 sessionId=${metadata.sessionId} id=${id}`);
+    }
     return id;
 }
 /**

package/dist/core/memory/local-embedding-llama.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 本地 embedding（Electron 主进程）：node-llama-cpp + GGUF。
+ * 需在安装依赖后对 Electron 的 Node ABI 执行 electron-rebuild（见 apps/desktop 的 rebuild:native）。
+ * 加载前会注册 ESM 钩子，将 "typescript" 解析为桩模块，避免依赖链加载 typescript.js（含 with 语句，ESM 下报错）。
+ */
+import type { IEmbeddingProvider } from "./embedding-types.js";
+export declare function getLocalEmbeddingLlamaUnavailableReason(): string | null;
+/**
+ * 获取基于 node-llama-cpp + GGUF 的本地 embedding 提供方。
+ * 仅在可解析到 node-llama-cpp 且模型可加载时返回，否则返回 null。
+ * @param modelPath 配置的 GGUF 路径或 hf: URI，为空时使用 DEFAULT_GGUF_MODEL
+ */
+export declare function getLocalEmbeddingLlamaProvider(modelPath: string | null): Promise<IEmbeddingProvider | null>;

package/dist/core/memory/local-embedding-llama.js

@@ -0,0 +1,76 @@
+import { join } from "path";
+import { homedir } from "os";
+let cached = null;
+let initError = null;
+let lastQueryError = null;
+export function getLocalEmbeddingLlamaUnavailableReason() {
+    return initError?.message ?? lastQueryError ?? null;
+}
+function L2Normalize(vec) {
+    let sum = 0;
+    for (let i = 0; i < vec.length; i++)
+        sum += vec[i] * vec[i];
+    const norm = Math.sqrt(sum) || 1;
+    return vec.map((x) => x / norm);
+}
+/** 默认 GGUF embedding 模型（与 moltbot 一致），首次使用会按 node-llama-cpp 规则下载到缓存 */
+const DEFAULT_GGUF_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+/**
+ * 获取基于 node-llama-cpp + GGUF 的本地 embedding 提供方。
+ * 仅在可解析到 node-llama-cpp 且模型可加载时返回，否则返回 null。
+ * @param modelPath 配置的 GGUF 路径或 hf: URI，为空时使用 DEFAULT_GGUF_MODEL
+ */
+export async function getLocalEmbeddingLlamaProvider(modelPath) {
+    if (cached)
+        return cached;
+    if (initError)
+        return null;
+    const effectivePath = (modelPath?.trim() || DEFAULT_GGUF_MODEL).trim();
+    try {
+        // Node 20.10+ 才提供 node:module 的 register；Electron 内置 Node 较旧时无此导出，跳过钩子
+        const nodeModule = await import("node:module");
+        if (typeof nodeModule.register === "function") {
+            const loaderUrl = new URL("../../../scripts/ts-stub-loader.mjs", import.meta.url).href;
+            await Promise.resolve(nodeModule.register(loaderUrl, import.meta.url));
+        }
+        const { getLlama, resolveModelFile, LlamaLogLevel } = await import("node-llama-cpp");
+        const llama = await getLlama({ logLevel: LlamaLogLevel.error });
+        const cacheDir = join(homedir(), ".cache", "llama");
+        const resolved = await resolveModelFile(effectivePath, cacheDir);
+        const model = await llama.loadModel({ modelPath: resolved });
+        const embeddingCtx = await model.createEmbeddingContext();
+        const provider = {
+            name: "llama-gguf",
+            async embed(text) {
+                try {
+                    const embedding = await embeddingCtx.getEmbeddingFor(text);
+                    const vec = Array.from(embedding.vector);
+                    if (vec.length === 0) {
+                        lastQueryError = "getEmbeddingFor 返回空向量";
+                        return null;
+                    }
+                    return L2Normalize(vec);
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    lastQueryError = `llama embed 失败: ${err.message}`;
+                    console.warn("[RAG embedding] node-llama-cpp embed 失败:", err.message);
+                    return null;
+                }
+            },
+        };
+        cached = provider;
+        return provider;
+    }
+    catch (e) {
+        initError = e instanceof Error ? e : new Error(String(e));
+        console.warn("[RAG embedding] node-llama-cpp (GGUF) 不可用，原因:", initError.message);
+        if (initError.stack) {
+            console.warn("[RAG embedding] GGUF 加载失败堆栈:\n", initError.stack);
+        }
+        if (initError.message.includes("Unexpected token 'with'")) {
+            console.warn("[RAG embedding] 提示: 依赖链中某包在 ESM 下使用了禁止的 with 语句（如 typescript.js）。可配置在线 RAG 或升级 Electron 至 Node 22+。");
+        }
+        return null;
+    }
+}

package/dist/core/memory/local-embedding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 本地 embedding：仅 node-llama-cpp (GGUF)。不可用时返回 null，由上层决定是否使用在线 RAG。
+ */
+import type { IEmbeddingProvider } from "./embedding-types.js";
+export declare function getLocalEmbeddingUnavailableReason(): string | null;
+/**
+ * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
+ * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ */
+export declare function getLocalEmbeddingProvider(): Promise<IEmbeddingProvider | null>;

package/dist/core/memory/local-embedding.js

@@ -0,0 +1,29 @@
+import { getRagLocalModelPathSync } from "../config/desktop-config.js";
+import { getLocalEmbeddingLlamaProvider, getLocalEmbeddingLlamaUnavailableReason, } from "./local-embedding-llama.js";
+let cached = null;
+let envLogged = false;
+export function getLocalEmbeddingUnavailableReason() {
+    return getLocalEmbeddingLlamaUnavailableReason();
+}
+/**
+ * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
+ * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ */
+export async function getLocalEmbeddingProvider() {
+    if (cached)
+        return cached;
+    const provider = await getLocalEmbeddingLlamaProvider(getRagLocalModelPathSync());
+    if (provider) {
+        cached = provider;
+        if (!envLogged) {
+            envLogged = true;
+            console.warn("[RAG embedding] 本地模型使用 node-llama-cpp (GGUF)");
+        }
+        return cached;
+    }
+    if (!envLogged) {
+        envLogged = true;
+        console.warn("[RAG embedding] 本地模型不可用，长记忆将空转。可配置 RAG 在线模型或检查 GGUF 报错。");
+    }
+    return null;
+}

package/dist/core/memory/persist-compaction-on-close.d.ts

@@ -0,0 +1,14 @@
+export type AddMemoryCompaction = (text: string, meta: {
+    infotype: "compaction";
+    sessionId: string;
+}) => Promise<unknown>;
+/**
+ * 将 map 中指定 compositeKey 的 summary 写入 addMemory 并从 map 删除；用于 Session 关闭前。
+ * 写入采用 fire-and-forget，不阻塞调用方，避免 agent.chat 等请求被 addMemory/embed 拖住导致无回复。
+ */
+export declare function persistStoredCompactionForSession(sessionLatestCompactionSummary: Map<string, string>, compositeKey: string, addMemory: AddMemoryCompaction): Promise<void>;
+/**
+ * 将 map 中所有给定 keys（需以 sessionId + "::" 为前缀）的 summary 依次写入 addMemory 并删除；用于按业务 sessionId 关闭时。
+ * 写入采用 fire-and-forget，不阻塞调用方。
+ */
+export declare function persistStoredCompactionForBusinessSession(sessionLatestCompactionSummary: Map<string, string>, keysToProcess: string[], sessionId: string, addMemory: AddMemoryCompaction): Promise<void>;

package/dist/core/memory/persist-compaction-on-close.js

@@ -0,0 +1,32 @@
+/**
+ * 会话关闭时将内存中缓存的 compaction summary 写入向量库的纯逻辑，便于单测且与 AgentManager 解耦。
+ */
+const COMPOSITE_KEY_SEP = "::";
+/**
+ * 将 map 中指定 compositeKey 的 summary 写入 addMemory 并从 map 删除；用于 Session 关闭前。
+ * 写入采用 fire-and-forget，不阻塞调用方，避免 agent.chat 等请求被 addMemory/embed 拖住导致无回复。
+ */
+export async function persistStoredCompactionForSession(sessionLatestCompactionSummary, compositeKey, addMemory) {
+    const summary = sessionLatestCompactionSummary.get(compositeKey);
+    sessionLatestCompactionSummary.delete(compositeKey);
+    if (summary?.trim()) {
+        const sessionId = compositeKey.split(COMPOSITE_KEY_SEP)[0];
+        void addMemory(summary.trim(), { infotype: "compaction", sessionId }).catch(() => { });
+    }
+}
+/**
+ * 将 map 中所有给定 keys（需以 sessionId + "::" 为前缀）的 summary 依次写入 addMemory 并删除；用于按业务 sessionId 关闭时。
+ * 写入采用 fire-and-forget，不阻塞调用方。
+ */
+export async function persistStoredCompactionForBusinessSession(sessionLatestCompactionSummary, keysToProcess, sessionId, addMemory) {
+    const prefix = sessionId + COMPOSITE_KEY_SEP;
+    for (const key of keysToProcess) {
+        if (!key.startsWith(prefix))
+            continue;
+        const summary = sessionLatestCompactionSummary.get(key);
+        sessionLatestCompactionSummary.delete(key);
+        if (summary?.trim()) {
+            void addMemory(summary.trim(), { infotype: "compaction", sessionId }).catch(() => { });
+        }
+    }
+}

package/dist/core/tools/bookmark-tool.d.ts

@@ -1,4 +1,8 @@
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/**
+ * 新增一个收藏标签。当 get_bookmark_tags 返回的列表中缺少用户想要的标签时，可先调用本工具创建该标签，再使用 save_bookmark 保存收藏。
+ */
+export declare function createAddBookmarkTagTool(): ToolDefinition;
 /**
  * 获取当前系统中已维护的标签列表，供保存 URL 时选择匹配的标签。
  */

package/dist/core/tools/bookmark-tool.js

@@ -1,11 +1,14 @@
 import { Type } from "@sinclair/typebox";
 import { getBackendBaseUrl } from "../../gateway/backend-url.js";
 const GetBookmarkTagsSchema = Type.Object({});
+const AddBookmarkTagSchema = Type.Object({
+    tagName: Type.String({ description: "要新增的标签名称，如「技术」「待读」「美女」等" }),
+});
 const SaveBookmarkSchema = Type.Object({
     url: Type.String({ description: "要收藏的 URL" }),
     title: Type.Optional(Type.String({ description: "可选标题" })),
     tagNames: Type.Optional(Type.Array(Type.String(), {
-        description: "标签名称列表，须与系统中已维护的标签一致。保存前应先用 get_bookmark_tags 获取可用标签。",
+        description: "标签名称列表，须与系统中已维护的标签一致。保存前应先用 get_bookmark_tags 获取可用标签；若缺标签可先用 add_bookmark_tag 新增。",
     })),
 });
 async function apiGet(path) {
@@ -39,6 +42,59 @@ async function apiPost(path, body) {
     }
     return res.json();
 }
+/**
+ * 新增一个收藏标签。当 get_bookmark_tags 返回的列表中缺少用户想要的标签时，可先调用本工具创建该标签，再使用 save_bookmark 保存收藏。
+ */
+export function createAddBookmarkTagTool() {
+    return {
+        name: "add_bookmark_tag",
+        label: "Add Bookmark Tag",
+        description: "在系统中新增一个收藏标签。当用户要保存链接到某个尚不存在的标签（如「美女」「技术」「待读」）时，先调用本工具创建该标签，再调用 get_bookmark_tags 获取最新列表并用 save_bookmark 保存。若标签已存在会提示无需重复创建。",
+        parameters: AddBookmarkTagSchema,
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            const tagName = (params.tagName ?? "").trim();
+            if (!tagName) {
+                return {
+                    content: [{ type: "text", text: "请提供要新增的标签名称。" }],
+                    details: undefined,
+                };
+            }
+            try {
+                const json = await apiPost("/tags", {
+                    name: tagName,
+                });
+                const data = json.data;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `已新增标签「${data?.name ?? tagName}」，可直接用于 save_bookmark 的 tagNames。`,
+                        },
+                    ],
+                    details: data,
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("409") || msg.includes("已存在") || msg.includes("Conflict")) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `标签「${tagName}」已存在，无需重复创建。可直接在 save_bookmark 的 tagNames 中使用该名称。`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `新增标签失败: ${msg}` }],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}
 /**
  * 获取当前系统中已维护的标签列表，供保存 URL 时选择匹配的标签。
  */
@@ -55,7 +111,7 @@ export function createGetBookmarkTagsTool() {
                 const names = data.map((t) => t.name);
                 const text = names.length > 0
                     ? `当前可用标签：${names.join("、")}。请根据用户意图选择匹配的标签名用于 save_bookmark。`
-                    : "当前暂无标签。请在设置中先添加标签，或使用 save_bookmark 时不传 tagNames。";
+                    : "当前暂无标签。可使用 add_bookmark_tag 新增标签，或 save_bookmark 时不传 tagNames。";
                 return {
                     content: [{ type: "text", text }],
                     details: { tags: data },
@@ -78,7 +134,7 @@ export function createSaveBookmarkTool() {
     return {
         name: "save_bookmark",
         label: "Save Bookmark",
-        description: "将用户提供的 URL 保存到收藏库，并可关联一个或多个标签。标签名必须使用 get_bookmark_tags 返回的已有标签；若用户未指定标签，可根据上下文推断或留空。",
+        description: "将用户提供的 URL 保存到收藏库，并可关联一个或多个标签。标签名须为系统已有标签（get_bookmark_tags 返回）；若缺少某标签可先用 add_bookmark_tag 新增。",
         parameters: SaveBookmarkSchema,
         execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
             const url = (params.url ?? "").trim();

package/dist/core/tools/index.d.ts

@@ -1,7 +1,8 @@
 export { createBrowserTool, closeBrowser } from "./browser-tool.js";
 export { createSaveExperienceTool } from "./save-experience-tool.js";
+export { createMemoryRecallTool } from "./memory-recall-tool.js";
 export { createInstallSkillTool } from "./install-skill-tool.js";
 export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
-export { createGetBookmarkTagsTool, createSaveBookmarkTool } from "./bookmark-tool.js";
+export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";

package/dist/core/tools/index.js

@@ -1,7 +1,8 @@
 export { createBrowserTool, closeBrowser } from "./browser-tool.js";
 export { createSaveExperienceTool } from "./save-experience-tool.js";
+export { createMemoryRecallTool } from "./memory-recall-tool.js";
 export { createInstallSkillTool } from "./install-skill-tool.js";
 export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
-export { createGetBookmarkTagsTool, createSaveBookmarkTool } from "./bookmark-tool.js";
+export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";

package/dist/core/tools/memory-recall-tool.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/**
+ * 创建 memory_recall 工具：按需从向量库检索经验与对话摘要，供回答「过往工作、决定、日期、人、偏好、待办、复杂任务、定时任务、历史经验」等问题时使用。
+ * @param useLongMemory 当前智能体是否启用长记忆；为 false 时执行空转（不检索，直接返回未启用提示）。
+ */
+export declare function createMemoryRecallTool(useLongMemory: boolean): ToolDefinition;

package/dist/core/tools/memory-recall-tool.js

@@ -0,0 +1,77 @@
+import { Type } from "@sinclair/typebox";
+import { searchMemory } from "../memory/index.js";
+const MemoryRecallSchema = Type.Object({
+    query: Type.String({
+        description: "语义检索查询，例如：过往决定、用户偏好、某日讨论、待办、历史经验、任务总结等",
+    }),
+    topK: Type.Optional(Type.Number({
+        description: "返回条数，默认 6",
+        minimum: 1,
+        maximum: 20,
+    })),
+});
+/**
+ * 创建 memory_recall 工具：按需从向量库检索经验与对话摘要，供回答「过往工作、决定、日期、人、偏好、待办、复杂任务、定时任务、历史经验」等问题时使用。
+ * @param useLongMemory 当前智能体是否启用长记忆；为 false 时执行空转（不检索，直接返回未启用提示）。
+ */
+export function createMemoryRecallTool(useLongMemory) {
+    return {
+        name: "memory_recall",
+        label: "Memory Recall",
+        description: "从长期记忆中语义检索与查询相关的经验总结和对话摘要。在回答与过往工作、决定、日期、人、偏好、待办、复杂任务、定时任务或需要历史经验相关的问题前，应先调用本工具获取相关记忆再作答。",
+        parameters: MemoryRecallSchema,
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            if (!useLongMemory) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "当前智能体未启用长记忆（经验），无法检索。",
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            const query = (params.query ?? "").trim();
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "请提供检索查询（query）。" }],
+                    details: undefined,
+                };
+            }
+            const topK = Math.min(20, Math.max(1, params.topK ?? 6));
+            try {
+                const results = await searchMemory(query, topK);
+                if (results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "未找到与查询相关的记忆。",
+                            },
+                        ],
+                        details: { results: [], query, topK },
+                    };
+                }
+                const lines = results.map((r, i) => `${i + 1}. [${r.metadata?.infotype ?? "memory"}]\n${(r.document ?? "").trim()}`);
+                const text = "以下为检索到的相关记忆：\n\n" + lines.join("\n\n");
+                return {
+                    content: [{ type: "text", text }],
+                    details: { results: results.length, query, topK },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `记忆检索失败: ${msg}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}

package/dist/gateway/channel/adapters/wechat.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 微信通道适配器：使用 Wechaty（Web/UOS 协议）接收消息，say() 发送回复。
+ * 不支持流式（微信无法编辑已发消息），回复在 agent_end 后一次性发送。
+ * 扫码：scan 事件产生二维码 URL，经 qrcode 库生成 base64 供前端展示。
+ */
+import type { IChannel } from "../types.js";
+export interface WechatChannelConfig {
+    /** Puppet 名称，缺省使用 Wechaty 自带 puppet */
+    puppet?: string;
+    /** 默认绑定的 agentId */
+    defaultAgentId?: string;
+}
+type WechatLoginStatus = "scanning" | "logged_in" | "logged_out";
+/** 供 Gateway API 查询当前二维码（base64 Data URL 或 null） */
+export declare function getWechatQrCode(): string | null;
+/** 供 Gateway API 查询登录状态 */
+export declare function getWechatStatus(): {
+    status: WechatLoginStatus;
+    userName: string | null;
+};
+/** 重启 Wechaty 以刷新二维码（二维码过期后调用） */
+export declare function refreshWechatQrCode(): Promise<void>;
+export declare function createWechatChannel(config: WechatChannelConfig): IChannel;
+export {};