palz-connector 1.6.6 → 1.6.7

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "palz-connector",
   "name": "Palz Connector Channel",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "description": "Palz IM 接入 OpenClaw",
   "channels": [
     "palz-connector"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palz-connector",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "type": "module",
   "main": "index.js",
   "description": "Palz IM 接入 OpenClaw — 模块化架构，基于 OpenClaw Runtime 消息管道",

package/palz-connector.config.json

@@ -5,7 +5,8 @@
   "clawGatewayUrl": "http://claw-gateway:8080",
   "activityReportEnabled": false,
   "sessionTimeout": 1800000,
-  "controlPort": 8008,
   "groupContextCache": false,
-  "showProcess": true
+  "showProcess": true,
+  "kbEngineUrl": "http://127.0.0.1:8070",
+  "controlPort": 8008
 }

package/palz-connector.dev.config.json

@@ -5,7 +5,8 @@
   "clawGatewayUrl": "http://claw-gateway:8080",
   "activityReportEnabled": true,
   "sessionTimeout": 1800000,
-  "controlPort": 8008,
   "groupContextCache": false,
-  "showProcess": true
+  "showProcess": true,
+  "kbEngineUrl": "http://uniclaw-kb-engine:8070",
+  "controlPort": 8008
 }

package/palz-connector.prod.config.json

@@ -5,7 +5,8 @@
   "clawGatewayUrl": "http://claw-gateway:8080",
   "activityReportEnabled": true,
   "sessionTimeout": 1800000,
-  "controlPort": 8008,
   "groupContextCache": false,
-  "showProcess": true
+  "showProcess": true,
+  "kbEngineUrl": "http://uniclaw-kb-engine:8070",
+  "controlPort": 8008
 }

package/palz-connector.staging.config.json

@@ -5,7 +5,8 @@
   "clawGatewayUrl": "http://claw-gateway:8080",
   "activityReportEnabled": true,
   "sessionTimeout": 1800000,
-  "controlPort": 8008,
   "groupContextCache": false,
-  "showProcess": true
+  "showProcess": true,
+  "kbEngineUrl": "http://uniclaw-kb-engine:8070",
+  "controlPort": 8008
 }

package/src/activity.js

@@ -1,10 +1,9 @@
 /**
- * Palz IM WebSocket 连接成功后的 claw-gateway 活动上报。
+ * Palz IM 收到消息后的 claw-gateway 活动上报。
  */
 const ACTIVITY_REPORT_TIMEOUT_MS = 2000;
 const ACTIVITY_REPORT_PATH_PREFIX = "/openclaw-gateway/be/deployments";
 const warnedMissingConfig = new Set();
-const SERVICE_NAME = process.env.OPENCLAW_WORKSPACE_POOL_SERVICE_NAME ?? "";
 function formatDateTimeWithOffset(date) {
     const pad = (n, width = 2) => String(n).padStart(width, "0");
     const offsetMinutes = -date.getTimezoneOffset();
@@ -24,7 +23,7 @@ function resolveActivityUrl(baseUrl, releaseName) {
     return `${normalizedBase}${ACTIVITY_REPORT_PATH_PREFIX}/${encodeURIComponent(releaseName)}/activity`;
 }
 export async function reportPalzActivity(params) {
-    const { config, connectedAt, runtime, accountId } = params;
+    const { config, msg, receivedAt, runtime, accountId } = params;
     const log = typeof runtime?.log === "function" ? runtime.log : console.log;
     const error = typeof runtime?.error === "function" ? runtime.error : console.error;
     const tag = `palz[${accountId ?? config.botId ?? "default"}]`;
@@ -42,17 +41,22 @@ export async function reportPalzActivity(params) {
     }
     const payload = {
         source: "palz-connector",
-        eventType: "ws_connected",
-        releaseName,
-        serviceName: SERVICE_NAME,
-        connectedAt: formatDateTimeWithOffset(connectedAt),
+        eventType: "im_message_received",
+        messageId: msg.msg_id,
+        conversationId: msg.conversation_id,
+        conversationType: msg.conversation_type || "direct",
+        userId: msg.owner_id ?? "",
+        senderId: msg.sender_id,
+        receivedAt: formatDateTimeWithOffset(receivedAt),
     };
+    if (msg.traceparent) {
+        payload.traceId = msg.traceparent;
+    }
     const url = resolveActivityUrl(baseUrl, releaseName);
     const body = JSON.stringify(payload);
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ACTIVITY_REPORT_TIMEOUT_MS);
     const startMs = Date.now();
-    log(`${tag}: [ACTIVITY_REPORT] reporting eventType=ws_connected url=${url} body=${body}`);
     try {
         const response = await fetch(url, {
             method: "POST",
@@ -63,15 +67,15 @@ export async function reportPalzActivity(params) {
         const elapsedMs = Date.now() - startMs;
         const responseText = await response.text().catch(() => "");
         if (!response.ok) {
-            error(`${tag}: [ACTIVITY_REPORT] failed status=${response.status} elapsed=${elapsedMs}ms response=${responseText.slice(0, 300)}`);
+            error(`${tag}: [ACTIVITY_REPORT] failed status=${response.status} elapsed=${elapsedMs}ms msg_id=${msg.msg_id} response=${responseText.slice(0, 300)}`);
             return;
         }
-        log(`${tag}: [ACTIVITY_REPORT] ok status=${response.status} elapsed=${elapsedMs}ms eventType=ws_connected`);
+        log(`${tag}: [ACTIVITY_REPORT] ok status=${response.status} elapsed=${elapsedMs}ms msg_id=${msg.msg_id}`);
     }
     catch (err) {
         const elapsedMs = Date.now() - startMs;
         const reason = err?.name === "AbortError" ? `timeout ${ACTIVITY_REPORT_TIMEOUT_MS}ms` : (err?.message ?? String(err));
-        error(`${tag}: [ACTIVITY_REPORT] error elapsed=${elapsedMs}ms reason=${reason}`);
+        error(`${tag}: [ACTIVITY_REPORT] error elapsed=${elapsedMs}ms msg_id=${msg.msg_id} reason=${reason}`);
     }
     finally {
         clearTimeout(timeout);

package/src/bot.js

@@ -9,11 +9,14 @@
  * - 通过 OpenClaw Runtime 的 dispatchReplyFromConfig 完成 AI 对话
  * - Session 管理交由 OpenClaw Runtime（resolveAgentRoute）
  */
+import { hostname as getHostname } from "node:os";
 import { getPalzRuntime } from "./runtime.js";
 import { resolvePalzAccount } from "./config.js";
 import { tryClaimMessage } from "./dedup.js";
 import { createPalzReplyDispatcher } from "./reply-dispatcher.js";
 import { resolvePalzMediaList, resolveMediaLocalRoots } from "./media.js";
+import { extractFileUrls, ingestFilesToKbEngine } from "./kb-ingest.js";
+import { consumeKbTaskContext, extractKbTaskCallbackContent, extractKbTaskId, resolveKbTaskContext, } from "./kb-task-callback.js";
 import { sendToPalzIM } from "./send.js";
 import { buildPassthroughFromMsg } from "./message-utils.js";
 import { tracer, trace, context, SpanStatusCode } from "./tracing.js";
@@ -206,10 +209,6 @@ function buildMediaPayload(mediaList) {
         MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
     };
 }
-function shellSingleQuote(value) {
-    const raw = String(value ?? "");
-    return `'${raw.replace(/'/g, "'\"'\"'")}'`;
-}
 function buildFileSharingSystemPrompt() {
     return [
         "## File Sharing",
@@ -223,29 +222,40 @@ function buildFileSharingSystemPrompt() {
         "Multiple files: one MEDIA: line per file.",
     ].join("\n");
 }
-function buildKnowledgeRecallSystemPrompt(params) {
-    const directCommand = "python3 skills/knowledge-mgmt/recall/kb-recall.py topics '<用户问题>' --group-id 'default'";
-    const hasGroupContext = Boolean(params.groupId && params.ownerId && params.groupOwnerId);
-    const groupCommand = hasGroupContext
-        ? [
-            "python3 skills/knowledge-mgmt/recall/kb-recall.py topics '<用户问题>'",
-            `--group-id ${shellSingleQuote(params.groupId)}`,
-            "--conversation-type 'group'",
-            `--owner-id ${shellSingleQuote(params.ownerId)}`,
-            `--group-owner-id ${shellSingleQuote(params.groupOwnerId)}`,
-            `--user-id ${shellSingleQuote(params.ownerId)}`,
-        ].join(" ")
-        : "python3 skills/knowledge-mgmt/recall/kb-recall.py topics '<用户问题>' --group-id '<group_id>' --conversation-type 'group' --owner-id '<owner_id>' --group-owner-id '<group_owner_id>' --user-id '<owner_id>'";
+function buildKbIngestNoticeMessage(results) {
+    const lines = results.map((result, index) => {
+        const details = [
+            `task_id=${result.taskId ?? "(unknown)"}`,
+            `state=${result.state ?? "(unknown)"}`,
+            result.kind ? `kind=${result.kind}` : "",
+        ].filter(Boolean);
+        return `${index + 1}. ${details.join(", ")}`;
+    });
     return [
-        "## Knowledge Recall Routing",
-        "This Palz system prompt is the stable entrypoint for Knowledge Recall, even when workspace startup files were not read.",
-        "For knowledge, explanatory, advisory, or consultation-style user questions, Recall is default-on. Only skip Recall for clear greetings, casual chat, weather, pure operation requests, ingest-trigger messages, or questions obviously unrelated to stored knowledge.",
-        "When Recall is triggered, the first tool call for the user question MUST be `kb-recall.py topics`. Do not call `web_search` or `memory_search` before `topics` returns no_match or an unavailable/error state that permits fallback.",
-        params.isGroup ? `Current Palz recall command: ${groupCommand}` : `Current Palz recall command: ${directCommand}`,
-        "Replace `<用户问题>` with the current user's actual question text. Follow the runner JSON `next_step`, `repair`, and `answer_contract`; do not manually read wiki/index files or invent citation links.",
-        "Fallback to web/general knowledge is allowed only after `no_match`, `local_not_found`, `remote_unavailable`, or `remote_error`. In group chat, missing owner/group-owner context must not fallback to direct/default.",
+        "[Knowledge Ingest Status]",
+        "The current message includes file(s) that have just been submitted for knowledge-base ingestion.",
+        "This status is informational only. You may refer to it if relevant, but continue handling the user's current request normally. Do not wait for ingestion to finish, and do not change your own intended actions solely because of this status.",
+        "Created ingest task(s):",
+        ...lines,
     ].join("\n");
 }
+function resolveWorkspacePoolServiceName() {
+    const explicit = process.env.OPENCLAW_WORKSPACE_POOL_SERVICE_NAME?.trim();
+    if (explicit)
+        return explicit;
+    const currentHostname = getHostname().trim();
+    const parts = currentHostname.split("-").filter(Boolean);
+    if (parts.length >= 3)
+        return parts.slice(0, 3).join("-");
+    return currentHostname || "127.0.0.1";
+}
+function resolveKbIngestCallbackUrl(config) {
+    if (typeof config.controlPort === "number" && config.controlPort > 0) {
+        const host = resolveWorkspacePoolServiceName();
+        return `http://${host}:${config.controlPort}/admin/kb-ingest/callback`;
+    }
+    return undefined;
+}
 export async function handlePalzMessage(params) {
     const { msg } = params;
     // 在当前 trace context（由 monitor.ts ws_recv span 建立）下创建子 span
@@ -268,7 +278,7 @@ export async function handlePalzMessage(params) {
     });
 }
 async function _handlePalzMessageInner(params) {
-    const { cfg, msg, runtime, accountId, agentId } = params;
+    const { cfg, msg, runtime, accountId, agentId, suppressAck } = params;
     const log = typeof runtime?.log === "function" ? runtime.log : console.log;
     const error = typeof runtime?.error === "function" ? runtime.error : console.error;
     const tag = `palz[${accountId}]`;
@@ -352,25 +362,27 @@ async function _handlePalzMessageInner(params) {
     }
     // 立即发送确认消息（在入队之前，不受队列阻塞影响）
     const groupId = isGroup ? msg.conversation_id : undefined;
-    try {
-        log(`${tag}: [ACK] 发送确认消息 conv=${msg.conversation_id} sender=${msg.sender_id}`);
-        await sendToPalzIM({
-            config: account.config,
-            conversationId: msg.conversation_id,
-            content: "收到，正在思考中…",
-            conversationType: msg.conversation_type || "direct",
-            msgId: msg.msg_id,
-            senderId: msg.sender_id,
-            msgType: msg.msg_type,
-            groupId,
-            lobsterId: msg.lobster_id,
-            palzMsgType: "thinking",
-            passthrough: buildPassthroughFromMsg(msg),
-        });
-        log(`${tag}: [ACK] 确认消息发送成功`);
-    }
-    catch (err) {
-        log(`${tag}: [ACK] 确认消息发送失败(不影响主流程): ${String(err)}`);
+    if (!suppressAck) {
+        try {
+            log(`${tag}: [ACK] 发送确认消息 conv=${msg.conversation_id} sender=${msg.sender_id}`);
+            await sendToPalzIM({
+                config: account.config,
+                conversationId: msg.conversation_id,
+                content: "收到，正在思考中…",
+                conversationType: msg.conversation_type || "direct",
+                msgId: msg.msg_id,
+                senderId: msg.sender_id,
+                msgType: msg.msg_type,
+                groupId,
+                lobsterId: msg.lobster_id,
+                palzMsgType: "thinking",
+                passthrough: buildPassthroughFromMsg(msg),
+            });
+            log(`${tag}: [ACK] 确认消息发送成功`);
+        }
+        catch (err) {
+            log(`${tag}: [ACK] 确认消息发送失败(不影响主流程): ${String(err)}`);
+        }
     }
     // 入队（按 agentId 隔离，不同 agent 并行处理）
     const queueKey = isGroup
@@ -455,9 +467,37 @@ async function _dispatchPalzMessageInner(params) {
     span?.addEvent(step4Input);
     const mediaList = await resolvePalzMediaList(msg.content, log);
     let mediaPayload = buildMediaPayload(mediaList);
-    const step4Output = `[STEP 4 输出] mediaList=${JSON.stringify(mediaList.map((m) => ({ path: m.path, contentType: m.contentType })))} mediaPayload=${JSON.stringify(mediaPayload)}`;
+    const fileMd5ByUrl = new Map(mediaList
+        .filter((m) => m.sourceUrl && m.md5)
+        .map((m) => [m.sourceUrl, m.md5]));
+    const step4Output = `[STEP 4 输出] mediaList=${JSON.stringify(mediaList.map((m) => ({ path: m.path, contentType: m.contentType, sourceUrl: m.sourceUrl, md5: m.md5 })))} mediaPayload=${JSON.stringify(mediaPayload)}`;
     log(`${tag}: ${step4Output}`);
     span?.addEvent(step4Output);
+    // STEP 4b: 同步提交知识库入库；单次请求内部 3s 超时，超时只打日志并继续后续流程
+    let kbIngestNoticeBody = "";
+    const kbEngineUrl = config.kbEngineUrl;
+    if (kbEngineUrl) {
+        const kbFileUrls = extractFileUrls(msg.content);
+        if (kbFileUrls.length > 0) {
+            log(`${tag}: [STEP 4b kb-ingest] 触发入库 files=${kbFileUrls.length} md5=${fileMd5ByUrl.size}/${kbFileUrls.length} engine=${kbEngineUrl}`);
+            const ingestResults = await ingestFilesToKbEngine({
+                kbEngineUrl,
+                msg,
+                fileUrls: kbFileUrls,
+                fileMd5ByUrl,
+                accountId,
+                agentId,
+                callbackUrl: resolveKbIngestCallbackUrl(config),
+                log,
+            });
+            const createdTasks = ingestResults.filter((result) => result.taskCreated === true);
+            log(`${tag}: [STEP 4b kb-ingest] 完成 results=${ingestResults.length} task_created=${createdTasks.length}`);
+            if (createdTasks.length > 0) {
+                kbIngestNoticeBody = buildKbIngestNoticeMessage(createdTasks);
+                span?.addEvent(`[STEP 4b kb-ingest] 插入消息提示 task_created=${createdTasks.length}`);
+            }
+        }
+    }
     // STEP 5: 解析路由
     const peerKind = isGroup ? "group" : "direct";
     const routeInput = { cfg: "(cfg)", channel: "palz-connector", accountId, peer: { kind: peerKind, id: peerId } };
@@ -500,6 +540,15 @@ async function _dispatchPalzMessageInner(params) {
     const step6aOutput = `[STEP 6a 输出] envelope body (len=${body.length}): "${body.slice(0, 200)}"`;
     log(`${tag}: ${step6aOutput}`);
     span?.addEvent(step6aOutput);
+    const kbIngestNoticeEnvelope = kbIngestNoticeBody
+        ? core.channel.reply.formatAgentEnvelope({
+            channel: "Palz",
+            from: "kb-engine",
+            timestamp: new Date(),
+            body: kbIngestNoticeBody,
+            envelope: envelopeOptions,
+        })
+        : "";
     // STEP 6b: 构建 inbound context
     const palzFrom = `palz:${msg.sender_id}:${msg.conversation_id}`;
     // 新格式: {conversationType}:{senderId}:{lobsterId}:{conversationId}
@@ -520,12 +569,12 @@ async function _dispatchPalzMessageInner(params) {
     // 群聊历史：将积攒的未@消息拼入 Body 上下文（仅 groupContextCache=true 时生效）
     const groupContextCacheEnabled = account.config.groupContextCache !== false;
     const historyKey = isGroup && groupContextCacheEnabled ? `${effectiveAgentId}:${msg.conversation_id}` : undefined;
-    let combinedBody = body;
+    let combinedBody = kbIngestNoticeEnvelope ? `${kbIngestNoticeEnvelope}\n\n${body}` : body;
     if (isGroup && historyKey && groupContextCacheEnabled) {
         log(`${tag}: [STEP 6b 群聊历史] 开始构建, historyKey=${historyKey} bodyLen=${body.length}`);
         combinedBody = buildGroupHistoryContext({
             historyKey,
-            currentMessage: body,
+            currentMessage: combinedBody,
             formatEntry: (entry) => core.channel.reply.formatAgentEnvelope({
                 channel: "Palz",
                 from: entry.sender,
@@ -606,16 +655,7 @@ async function _dispatchPalzMessageInner(params) {
     log(`${tag}: ${step6bCtx}`);
     span?.addEvent(step6bCtx);
     const showProcess = config.showProcess === true;
-    const groupSystemPromptParts = [buildFileSharingSystemPrompt()];
-    if (effectiveAgentId === "main") {
-        groupSystemPromptParts.unshift(buildKnowledgeRecallSystemPrompt({
-            isGroup,
-            groupId,
-            ownerId: typeof msg.owner_id === "string" ? msg.owner_id : undefined,
-            groupOwnerId: typeof msg.group_owner_id === "string" ? msg.group_owner_id : undefined,
-        }));
-    }
-    const groupSystemPrompt = groupSystemPromptParts.join("\n\n");
+    const groupSystemPrompt = buildFileSharingSystemPrompt();
     const ctx = core.channel.reply.finalizeInboundContext({
         Body: combinedBody,
         BodyForAgent: messageBody,
@@ -872,3 +912,51 @@ export function cleanupAgentCaches(agentIdToClean) {
     }
     reasoningScannedAgents.delete(agentIdToClean);
 }
+export async function handleKbTaskCallback(params) {
+    const log = params.log ?? (typeof params.runtime?.log === "function" ? params.runtime.log : console.log);
+    const error = params.error ?? (typeof params.runtime?.error === "function" ? params.runtime.error : console.error);
+    const taskId = extractKbTaskId(params.body);
+    if (!taskId) {
+        return { handled: false, reason: "missing task_id" };
+    }
+    const taskContext = resolveKbTaskContext(taskId);
+    if (!taskContext) {
+        log(`palz-kb-callback: task_id=${taskId} ignored, context not found`);
+        return { handled: false, taskId, reason: "task context not found" };
+    }
+    const content = extractKbTaskCallbackContent(params.body);
+    if (!content) {
+        log(`palz-kb-callback: task_id=${taskId} ignored, callback content missing`);
+        return { handled: false, taskId, reason: "missing callback content" };
+    }
+    const original = taskContext.msg;
+    const callbackMsg = {
+        ...original,
+        event: "message",
+        content,
+        msg_id: `kb_callback_${taskId}_${Date.now()}`,
+        timestamp: Date.now(),
+        stream: false,
+        mentioned_bot: true,
+        agent_id: taskContext.agentId,
+        sender_id: original.sender_id || "kb-engine",
+        sender_name: "Knowledge Base Engine",
+    };
+    log(`palz-kb-callback: dispatching task_id=${taskId} agent=${taskContext.agentId} conv=${callbackMsg.conversation_id}`);
+    try {
+        consumeKbTaskContext(taskId);
+        await handlePalzMessage({
+            cfg: params.cfg,
+            runtime: params.runtime,
+            msg: callbackMsg,
+            accountId: taskContext.accountId,
+            agentId: taskContext.agentId,
+            suppressAck: true,
+        });
+        return { handled: true, taskId };
+    }
+    catch (err) {
+        error(`palz-kb-callback: dispatch failed task_id=${taskId}: ${String(err)}`);
+        throw err;
+    }
+}

package/src/channel.js

@@ -108,7 +108,8 @@ export const palzPlugin = {
                 log: logInfo,
                 error,
             });
-            // 停止服务：断开所有 WS 且不再重连。幂等，可被 HTTP 控制接口或框架层 abort 多次调用。
+            // Stop service: disconnect all WS connections and prevent scanner-triggered reconnects.
+            // Idempotent because it may be called from the HTTP control port or framework abort.
             let stopped = false;
             const doStop = () => {
                 if (stopped)
@@ -118,8 +119,8 @@ export const palzPlugin = {
                 scanner.stop();
                 manager.shutdown();
             };
-            // 可选启动 HTTP 控制服务（仅当配置了 controlPort）。停止服务时保留该 HTTP 服务，
-            // 仅在框架层 abort 时才关闭。
+            // Optional HTTP control service. /admin/stop keeps this server alive so callers can
+            // inspect /admin/health afterwards; framework abort closes it.
             let controlServer = null;
             const controlPort = baseConfig.controlPort;
             if (typeof controlPort === "number" && controlPort > 0) {
@@ -130,6 +131,8 @@ export const palzPlugin = {
                         const activeUsers = manager.getActiveUsers();
                         return { stopped, activeConnections: activeUsers.length, activeUsers };
                     },
+                    cfg: ctx.cfg,
+                    runtime: ctx.runtime,
                     log: logInfo,
                     error,
                 });

package/src/config.js

@@ -67,6 +67,7 @@ export function resolvePalzConfig(_cfg, botId) {
         sessionTimeout: file.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT,
         groupContextCache: file.groupContextCache !== false,
         showProcess: file.showProcess === true,
+        kbEngineUrl: file.kbEngineUrl || "",
         controlPort: file.controlPort,
     };
     if (!_configLoggedOnce) {

package/src/control-server.js

@@ -1,28 +1,47 @@
 /**
- * Palz Connector HTTP 控制服务
+ * Palz Connector HTTP control service.
  *
- * 提供一个独立的 HTTP 端口，供外部主动控制插件：
- *   - POST /admin/stop   断开所有 WS 连接且不再重连（停止服务），幂等
- *   - GET  /admin/health 查询当前状态（是否已停止 / 活跃连接数）
- *
- * 与 WS 连接 / 消息处理 / reconcile 完全隔离：只持有 onStop / getStatus 回调，
- * 不碰任何业务数据；只有配置了端口才启动；启动错误只记日志不影响插件主流程。
- *
- * 统一响应结构：{ code, err_message, data }，code=0 表示成功，非 0 为错误码。
- * HTTP status 一律 200，业务结果由 code 表达。
+ * Exposes an optional admin port for stopping all WS connections without
+ * affecting the normal channel/message code paths.
  */
 import http from "node:http";
+import { handleKbTaskCallback } from "./bot.js";
+import { getKbTaskRegistryStatus } from "./kb-task-callback.js";
 function sendJson(res, body) {
     const payload = JSON.stringify(body);
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(payload);
 }
+async function readRequestBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function parseCallbackBody(req, raw) {
+    const contentType = String(req.headers["content-type"] || "").toLowerCase();
+    if (!raw.trim())
+        return {};
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+        const form = new URLSearchParams(raw);
+        const payload = form.get("payload");
+        if (payload)
+            return JSON.parse(payload);
+        return Object.fromEntries(form.entries());
+    }
+    if (contentType.includes("multipart/form-data")) {
+        const match = raw.match(/name="payload"(?:\r?\n[^\r\n]*)?\r?\n\r?\n([\s\S]*?)\r?\n--/);
+        if (match?.[1])
+            return JSON.parse(match[1].trim());
+    }
+    return JSON.parse(raw);
+}
 export function startControlServer(opts) {
     const log = opts.log ?? console.log;
     const error = opts.error ?? console.error;
-    const server = http.createServer((req, res) => {
+    const server = http.createServer(async (req, res) => {
         const method = (req.method || "GET").toUpperCase();
-        // 去掉查询串，只取 path
         const path = (req.url || "/").split("?")[0].replace(/\/+$/, "") || "/";
         try {
             if (path === "/admin/stop") {
@@ -47,7 +66,36 @@ export function startControlServer(opts) {
                     return;
                 }
                 const status = opts.getStatus();
-                sendJson(res, { code: 0, err_message: "", data: { ...status } });
+                sendJson(res, {
+                    code: 0,
+                    err_message: "",
+                    data: { ...status, kbTasks: getKbTaskRegistryStatus() },
+                });
+                return;
+            }
+            if (path === "/admin/kb-ingest/callback") {
+                if (method !== "POST") {
+                    sendJson(res, { code: 405, err_message: "method not allowed", data: {} });
+                    return;
+                }
+                if (!opts.runtime) {
+                    sendJson(res, { code: 503, err_message: "runtime not available", data: {} });
+                    return;
+                }
+                const rawBody = await readRequestBody(req);
+                const body = parseCallbackBody(req, rawBody);
+                const result = await handleKbTaskCallback({
+                    cfg: opts.cfg,
+                    runtime: opts.runtime,
+                    body,
+                    log,
+                    error,
+                });
+                sendJson(res, {
+                    code: result.handled ? 0 : 404,
+                    err_message: result.handled ? "" : (result.reason ?? "not handled"),
+                    data: result,
+                });
                 return;
             }
             sendJson(res, { code: 404, err_message: "not found", data: {} });
@@ -60,7 +108,6 @@ export function startControlServer(opts) {
             catch { }
         }
     });
-    // 端口占用等错误只记日志，不让插件崩溃。
     server.on("error", (err) => {
         error(`control-server: server error on port ${opts.port}: ${err?.message ?? err}`);
     });

package/src/kb-ingest.js

@@ -0,0 +1,227 @@
+/**
+ * Palz Connector → uniclaw-kb-engine 知识库入库
+ *
+ * 当 IM 消息携带文件时，调用 engine 的 ingest API
+ * (POST /uniclaw-kb-engine/api/v1/ingest-tasks)，把原始 file_url 直接交给 engine 入库。
+ * engine 自行做文件类型路由 / 去重 / 跳过，本模块不过滤文件类型。
+ *
+ * 本模块的所有调用都不阻塞、不抛出，失败只打日志，绝不影响 AI 对话流程。
+ */
+import { registerKbTaskContext } from "./kb-task-callback.js";
+/** 调用 engine ingest API 的超时时间（毫秒）。
+ *  ingest 为异步受理（暂存+入队即返回），但走 file_url 时 engine 需从 URL
+ *  拉取文件再上传到自己的 OSS；超时只记录日志并继续后续 AI 流程。 */
+const INGEST_TIMEOUT_MS = 3000;
+const KB_ENGINE_API_PREFIX = "/uniclaw-kb-engine/api/v1";
+const LEGACY_KB_ENGINE_API_PREFIX = "/api/v1";
+const KB_ENGINE_INGEST_ENDPOINT = "ingest-tasks";
+/**
+ * 从消息 content 中提取所有 type:"file" 的 file_url。
+ * 取值逻辑与 media.ts 的 resolvePalzMediaList 保持一致。
+ */
+export function extractFileUrls(content) {
+    if (typeof content === "string" || !Array.isArray(content))
+        return [];
+    const urls = [];
+    for (const part of content) {
+        if (part.type === "file") {
+            const filePart = part;
+            const url = filePart.file_url?.url;
+            if (url)
+                urls.push(url);
+        }
+    }
+    return urls;
+}
+function resolveKbEngineIngestUrl(kbEngineUrl) {
+    const normalizedBase = kbEngineUrl.trim().replace(/\/+$/, "");
+    if (normalizedBase.endsWith(KB_ENGINE_API_PREFIX)) {
+        return `${normalizedBase}/${KB_ENGINE_INGEST_ENDPOINT}`;
+    }
+    if (normalizedBase.endsWith(LEGACY_KB_ENGINE_API_PREFIX)) {
+        const hostBase = normalizedBase.slice(0, -LEGACY_KB_ENGINE_API_PREFIX.length).replace(/\/+$/, "");
+        return `${hostBase}${KB_ENGINE_API_PREFIX}/${KB_ENGINE_INGEST_ENDPOINT}`;
+    }
+    return `${normalizedBase}${KB_ENGINE_API_PREFIX}/${KB_ENGINE_INGEST_ENDPOINT}`;
+}
+/** 构造单个 file_url 的 ingest payload；缺少 engine 必填字段时返回 null（跳过）。 */
+function buildPayload(msg, fileUrl, fileMd5, callbackUrl, log) {
+    const ownerId = (msg.owner_id || "").trim();
+    const conversationId = (msg.conversation_id || "").trim();
+    const senderId = (msg.sender_id || "").trim();
+    const lobsterId = (msg.lobster_id || "").trim();
+    const msgId = (msg.msg_id || "").trim();
+    const lobsterType = (msg.lobster_type || "").trim();
+    const missing = [];
+    if (!ownerId)
+        missing.push("owner_id");
+    if (!conversationId)
+        missing.push("conversation_id");
+    if (!senderId)
+        missing.push("sender_id");
+    if (!lobsterId)
+        missing.push("lobster_id");
+    if (!msgId)
+        missing.push("msg_id");
+    if (!lobsterType)
+        missing.push("lobster_type");
+    if (missing.length > 0) {
+        log?.(`palz-kb-ingest: [skip] msg_id=${msgId || "(none)"} 缺少必填字段: ${missing.join(",")}`);
+        return null;
+    }
+    const isGroup = (msg.conversation_type || "").toLowerCase() === "group";
+    const payload = {
+        owner_id: ownerId,
+        conversation_id: conversationId,
+        sender_id: senderId,
+        lobster_id: lobsterId,
+        msg_id: msgId,
+        lobster_type: lobsterType,
+        conversation_type: (msg.conversation_type || "direct").trim(),
+        file_url: fileUrl,
+    };
+    if (fileMd5)
+        payload.file_md5 = fileMd5;
+    if (callbackUrl)
+        payload.callback_url = callbackUrl;
+    if (msg.sender_name)
+        payload.sender_name = msg.sender_name;
+    if (msg.sender_account_type)
+        payload.sender_account_type = msg.sender_account_type;
+    if (msg.lobster_name)
+        payload.lobster_name = msg.lobster_name;
+    if (msg.group_name)
+        payload.group_name = msg.group_name;
+    if (isGroup) {
+        const groupId = (msg.group_id || msg.conversation_id || "").trim();
+        const groupOwnerId = (msg.group_owner_id || "").trim();
+        const groupMembersList = (msg.group_members_list || "").trim();
+        const groupMissing = [];
+        if (!groupOwnerId)
+            groupMissing.push("group_owner_id");
+        if (!groupMembersList)
+            groupMissing.push("group_members_list");
+        if (groupMissing.length > 0) {
+            log?.(`palz-kb-ingest: [skip] msg_id=${msgId} 群聊缺少必填字段: ${groupMissing.join(",")}`);
+            return null;
+        }
+        payload.group_id = groupId;
+        payload.group_owner_id = groupOwnerId;
+        payload.group_members_list = groupMembersList;
+    }
+    return payload;
+}
+/** 发送单个 ingest 请求，带 3s 超时；失败只打日志，绝不抛出。 */
+async function postIngest(kbEngineUrl, payload, log) {
+    const baseResult = {
+        fileUrl: payload.file_url,
+        fileMd5: payload.file_md5,
+        submitted: false,
+        taskCreated: false,
+    };
+    const url = resolveKbEngineIngestUrl(kbEngineUrl);
+    const payloadJson = JSON.stringify(payload);
+    const form = new FormData();
+    form.append("payload", payloadJson);
+    // 完整请求体日志，便于排查字段映射 / engine 拒绝原因
+    log?.(`palz-kb-ingest: [request] POST ${url} payload=${payloadJson}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), INGEST_TIMEOUT_MS);
+    try {
+        const resp = await fetch(url, { method: "POST", body: form, signal: controller.signal });
+        const rawBody = await resp.text();
+        // 完整响应体日志（含 HTTP 状态码与原始 body，无论 JSON 与否）
+        log?.(`palz-kb-ingest: [response] msg_id=${payload.msg_id} http=${resp.status} body=${rawBody}`);
+        let body = null;
+        try {
+            body = JSON.parse(rawBody);
+        }
+        catch {
+            /* 非 JSON 响应，已在 [response] 中打出原始 body */
+        }
+        if (!resp.ok) {
+            log?.(`palz-kb-ingest: [warn] HTTP ${resp.status} msg_id=${payload.msg_id} url=${payload.file_url}`);
+            return { ...baseResult, error: `HTTP ${resp.status}` };
+        }
+        if (!body || typeof body.code !== "number") {
+            log?.(`palz-kb-ingest: [warn] engine 响应格式异常 msg_id=${payload.msg_id}`);
+            return { ...baseResult, error: "invalid engine response" };
+        }
+        const engineBody = body;
+        if (engineBody.code !== 0) {
+            const errMessage = engineBody.err_message || `engine code ${engineBody.code}`;
+            log?.(`palz-kb-ingest: [warn] engine 拒绝 msg_id=${payload.msg_id} code=${engineBody.code} err=${engineBody.err_message}`);
+            return { ...baseResult, error: errMessage };
+        }
+        const data = engineBody.data ?? {};
+        const taskId = data.task_id;
+        const state = data.state;
+        const taskCreated = data.task_created === true;
+        const dup = data.duplicate_submit === true ? " duplicate_submit=true" : "";
+        const skipped = data.skipped === true ? ` skipped=true reason=${data.reason ?? "(none)"}` : "";
+        log?.(`palz-kb-ingest: [ok] msg_id=${payload.msg_id} task_id=${taskId ?? "(none)"} state=${state ?? "(none)"} task_created=${taskCreated}${dup}${skipped}`);
+        return {
+            ...baseResult,
+            submitted: true,
+            taskCreated,
+            taskId,
+            state,
+            kind: data.kind,
+            duplicateSubmit: data.duplicate_submit === true,
+            skipped: data.skipped === true,
+            skipReason: data.reason,
+            error: data.error,
+        };
+    }
+    catch (err) {
+        const reason = err?.name === "AbortError" ? `超时(${INGEST_TIMEOUT_MS}ms)` : err?.message;
+        log?.(`palz-kb-ingest: [error] msg_id=${payload.msg_id} url=${payload.file_url} error=${reason}`);
+        return {
+            ...baseResult,
+            timedOut: err?.name === "AbortError",
+            error: reason || "unknown error",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 把消息中的文件送入 kb-engine 知识库。
+ * 内部吞掉所有错误，仅打日志并返回非创建结果，绝不抛出。
+ */
+export async function ingestFilesToKbEngine(params) {
+    const { kbEngineUrl, msg, fileUrls, fileMd5ByUrl, accountId, agentId, callbackUrl, log } = params;
+    if (!kbEngineUrl || fileUrls.length === 0)
+        return [];
+    log?.(`palz-kb-ingest: [start] msg_id=${msg.msg_id} files=${fileUrls.length} engine=${kbEngineUrl}`);
+    const results = [];
+    for (const fileUrl of fileUrls) {
+        const fileMd5 = fileMd5ByUrl?.get(fileUrl);
+        const payload = buildPayload(msg, fileUrl, fileMd5, callbackUrl, log);
+        if (!payload) {
+            results.push({
+                fileUrl,
+                fileMd5,
+                submitted: false,
+                taskCreated: false,
+                error: "payload skipped",
+            });
+            continue;
+        }
+        const result = await postIngest(kbEngineUrl, payload, log);
+        results.push(result);
+        if (result.taskCreated && result.taskId && accountId && agentId) {
+            registerKbTaskContext({
+                taskId: result.taskId,
+                accountId,
+                agentId,
+                msg,
+                fileUrl,
+                fileMd5,
+                log,
+            });
+        }
+    }
+    return results;
+}

package/src/kb-task-callback.js

@@ -0,0 +1,53 @@
+const DEFAULT_TASK_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_TASK_CONTEXTS = 5000;
+const taskContexts = new Map();
+function cleanupExpired(now = Date.now()) {
+    for (const [taskId, context] of taskContexts) {
+        if (context.expiresAt <= now)
+            taskContexts.delete(taskId);
+    }
+    while (taskContexts.size > MAX_TASK_CONTEXTS) {
+        const oldest = taskContexts.keys().next().value;
+        if (oldest === undefined)
+            break;
+        taskContexts.delete(oldest);
+    }
+}
+export function registerKbTaskContext(params) {
+    const taskId = params.taskId.trim();
+    if (!taskId)
+        return;
+    const now = Date.now();
+    cleanupExpired(now);
+    taskContexts.set(taskId, {
+        taskId,
+        accountId: params.accountId,
+        agentId: params.agentId,
+        msg: { ...params.msg },
+        fileUrl: params.fileUrl,
+        fileMd5: params.fileMd5,
+        createdAt: now,
+        expiresAt: now + (params.ttlMs ?? DEFAULT_TASK_TTL_MS),
+    });
+    params.log?.(`palz-kb-callback: registered task_id=${taskId} agent=${params.agentId} conv=${params.msg.conversation_id}`);
+}
+export function resolveKbTaskContext(taskId) {
+    cleanupExpired();
+    return taskContexts.get(taskId.trim());
+}
+export function consumeKbTaskContext(taskId) {
+    const context = resolveKbTaskContext(taskId);
+    if (context)
+        taskContexts.delete(context.taskId);
+    return context;
+}
+export function getKbTaskRegistryStatus() {
+    cleanupExpired();
+    return { trackedTasks: taskContexts.size };
+}
+export function extractKbTaskId(body) {
+    return typeof body.task_id === "string" ? body.task_id.trim() : "";
+}
+export function extractKbTaskCallbackContent(body) {
+    return typeof body.content === "string" ? body.content.trim() : "";
+}

package/src/media.js

@@ -8,6 +8,7 @@
 import fs from "fs";
 import path from "path";
 import os from "os";
+import crypto from "crypto";
 import { uploadFileToOss, uploadBufferToOss } from "./oss.js";
 /** OpenClaw 允许访问的媒体目录 */
 const MEDIA_DIR = path.join(os.homedir(), ".openclaw", "media");
@@ -62,7 +63,7 @@ function sanitizeFileName(name) {
     const trimmedStem = cleaned.slice(0, MAX - ext.length);
     return trimmedStem + ext;
 }
-function saveBufferToMediaDir(buffer, contentType, ext, log, originalName) {
+function saveBufferToMediaDir(buffer, contentType, ext, log, originalName, sourceUrl) {
     try {
         fs.mkdirSync(MEDIA_DIR, { recursive: true });
         let fileName;
@@ -76,8 +77,9 @@ function saveBufferToMediaDir(buffer, contentType, ext, log, originalName) {
         const filePath = path.join(MEDIA_DIR, fileName);
         fs.writeFileSync(filePath, buffer);
         const placeholder = isImageMime(contentType) ? "<media:image>" : `<media:file:${ext}>`;
-        log?.(`palz-media: [saveToMediaDir] 成功: path=${filePath} size=${buffer.length}bytes mime=${contentType}${originalName ? ` originalName=${originalName}` : ""}`);
-        return { path: filePath, contentType, placeholder };
+        const md5 = crypto.createHash("md5").update(buffer).digest("hex");
+        log?.(`palz-media: [saveToMediaDir] 成功: path=${filePath} size=${buffer.length}bytes mime=${contentType} md5=${md5}${originalName ? ` originalName=${originalName}` : ""}`);
+        return { path: filePath, contentType, placeholder, sourceUrl, md5 };
     }
     catch (err) {
         log?.(`palz-media: [saveToMediaDir] 失败: error=${err.message}`);
@@ -224,7 +226,7 @@ export async function resolvePalzMediaList(content, log) {
         log?.(`palz-media: [resolve] 处理第 ${i + 1}/${mediaUrls.length} 个媒体, urlType=${urlType} urlLen=${url.length}`);
         const fetched = await fetchUrlToBuffer(url, log);
         if (fetched) {
-            const info = saveBufferToMediaDir(fetched.buffer, fetched.contentType, fetched.ext, log, fetched.originalName);
+            const info = saveBufferToMediaDir(fetched.buffer, fetched.contentType, fetched.ext, log, fetched.originalName, url);
             if (info) {
                 results.push(info);
                 log?.(`palz-media: [resolve] 第 ${i + 1} 完成: ${JSON.stringify(info)}`);

package/src/monitor.js

@@ -167,14 +167,6 @@ export async function monitorPalzProvider(params) {
                 lastPongAt = connectedAt;
                 consecutive4002 = 0;
                 log(`palz[${accountId}]: WebSocket connected, bot_id=${config.botId}`);
-                reportPalzActivity({
-                    config,
-                    connectedAt: new Date(connectedAt),
-                    runtime,
-                    accountId,
-                }).catch((err) => {
-                    error(`palz[${accountId}]: [ACTIVITY_REPORT] unhandled error: ${err.message ?? err}`);
-                });
                 pingInterval = setInterval(() => {
                     if (ws.readyState === WebSocket.OPEN) {
                         const timeSinceLastPong = Date.now() - lastPongAt;
@@ -203,6 +195,7 @@ export async function monitorPalzProvider(params) {
                 }
             });
             ws.on("message", (data) => {
+                const receivedAt = new Date();
                 const raw = data.toString();
                 try {
                     const msg = JSON.parse(raw);
@@ -215,7 +208,16 @@ export async function monitorPalzProvider(params) {
                     tracer.startActiveSpan("palz.ws_recv", {}, parentCtx, (span) => {
                         try {
                             span.setAttribute("raw_message", raw);
-                            log(`palz[${accountId}]: [WS_RECV] #${messageCount} full_message=${raw.slice(0, 1000)} traceId=${span.spanContext().traceId}`);
+                            log(`palz[${accountId}]: [WS_RECV] #${messageCount} full_message=${raw} traceId=${span.spanContext().traceId}`);
+                            reportPalzActivity({
+                                config,
+                                msg,
+                                receivedAt,
+                                runtime,
+                                accountId,
+                            }).catch((err) => {
+                                error(`palz[${accountId}]: [ACTIVITY_REPORT] unhandled error: ${err.message ?? err}`);
+                            });
                             // agent_id：从消息中取，缺失/空时默认为 {userId}-main
                             let messageAgentId = typeof msg.agent_id === "string" ? msg.agent_id.trim() : "";
                             if (!messageAgentId) {