palz-connector 1.3.2 → 1.3.4

package/openclaw.plugin.json

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

package/package.json

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

package/palz-connector.config.json

@@ -1,7 +1,8 @@
 {
   "enabled": true,
-  "streamUrl": "ws://14.103.148.99:9090/ws/bot",
-  "apiBaseUrl": "http://14.103.148.99:9090/api",
+  "streamUrl": "ws://14.103.148.99:8090/ws/bot",
+  "apiBaseUrl": "http://14.103.148.99:8090/api",
   "sessionTimeout": 1800000,
-  "groupContextCache": true
+  "groupContextCache": true,
+  "showProcess": true
 }

package/palz-connector.dev.config.json

@@ -3,5 +3,6 @@
   "streamUrl": "wss://claw-server.csaiagent.com/ws/bot",
   "apiBaseUrl": "https://claw-server.csaiagent.com/api",
   "sessionTimeout": 1800000,
-  "groupContextCache": true
+  "groupContextCache": true,
+  "showProcess": true
 }

package/palz-connector.prod.config.json

@@ -3,5 +3,6 @@
   "streamUrl": "wss://claw-server.csagentai.com/ws/bot",
   "apiBaseUrl": "https://claw-server.csagentai.com/api",
   "sessionTimeout": 1800000,
-  "groupContextCache": true
+  "groupContextCache": true,
+  "showProcess": true
 }

package/palz-connector.staging.config.json

@@ -3,5 +3,6 @@
   "streamUrl": "wss://claw-server.csjkagent.com/ws/bot",
   "apiBaseUrl": "https://claw-server.csjkagent.com/api",
   "sessionTimeout": 1800000,
-  "groupContextCache": true
+  "groupContextCache": true,
+  "showProcess": true
 }

package/src/bot.ts

@@ -43,6 +43,37 @@ function extractPlainText(content: OpenAIContent): string {
   return "";
 }
 
+// ============ reasoning 激活状态缓存（内存） ============
+
+/** 已激活 reasoning stream 的 session key 集合，避免每次请求重复发送 /reasoning stream */
+const reasoningActivated = new Set<string>();
+
+/** 已扫描过 session store 的 agent 集合，每个 agent 只扫描一次 */
+const reasoningScannedAgents = new Set<string>();
+
+/**
+ * 从 session store 中预填已激活 reasoning stream 的 session key。
+ * 每个 agentId 只扫描一次，在首次处理该 agent 的请求时调用。
+ */
+function prefillReasoningActivated(core: any, agentId: string, log: (...args: any[]) => void): void {
+  if (reasoningScannedAgents.has(agentId)) return;
+  reasoningScannedAgents.add(agentId);
+  try {
+    const storePath = core.agent.session.resolveStorePath(undefined, { agentId });
+    const store = core.agent.session.loadSessionStore(storePath, { skipCache: true });
+    let count = 0;
+    for (const [key, entry] of Object.entries(store)) {
+      if ((entry as any)?.reasoningLevel === "stream") {
+        reasoningActivated.add(key);
+        count++;
+      }
+    }
+    log(`[REASONING PREFILL] agentId=${agentId} scanned, found ${count} session(s) with reasoning=stream`);
+  } catch (err) {
+    log(`[REASONING PREFILL] agentId=${agentId} 扫描失败: ${String(err)}`);
+  }
+}
+
 // ============ 聊天队列（同一会话串行处理） ============
 
 function createChatQueue() {
@@ -511,6 +542,8 @@ async function _dispatchPalzMessageInner(params: HandlePalzMessageParams): Promi
   log(`${tag}: ${step6bCtx}`);
   span?.addEvent(step6bCtx);
 
+  const showProcess = !isGroup && config.showProcess === true;
+
   const ctx = core.channel.reply.finalizeInboundContext({
     Body: combinedBody,
     BodyForAgent: messageBody,
@@ -552,9 +585,90 @@ async function _dispatchPalzMessageInner(params: HandlePalzMessageParams): Promi
   span?.addEvent(step6bOutput);
   ctx.metadata = {
     ...ctx.metadata,
-    traceId: msg.msg_id, 
+    traceId: msg.msg_id,
     source: "palz-connector"
   };
+
+  // 当 showProcess 开启时，确保 session 的 reasoningLevel 为 "stream"
+  // 通过模拟发送一条 directive-only 的 "/reasoning stream" 消息来激活，
+  // OpenClaw 的 handleDirectiveOnly 会通过 updateSessionStore（锁内 read-modify-write）
+  // 安全地持久化 reasoningLevel，完全避免并发覆盖问题。
+  // 使用内存 Set 记录已激活的 session，避免每次请求重复发送。
+
+  // 首次处理该 agent 时，从 session store 预填已激活的 session key
+  if (showProcess) {
+    prefillReasoningActivated(core, route.agentId, log);
+  }
+
+  if (showProcess && !reasoningActivated.has(route.sessionKey)) {
+    try {
+      log(`${tag}: [REASONING ACTIVATE] 开始激活 reasoning stream, sessionKey=${route.sessionKey}`);
+      // 构造 directive-only 的 context，Body 仅包含 /reasoning stream
+      const reasoningCtx = core.channel.reply.finalizeInboundContext({
+        Body: "/reasoning stream",
+        RawBody: "/reasoning stream",
+        CommandBody: "/reasoning stream",
+        From: palzFrom,
+        To: palzTo,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: chatType,
+        SenderId: msg.sender_id,
+        SenderName: senderName,
+        Provider: "palz-connector",
+        Surface: "palz-connector",
+        MessageSid: `${msg.msg_id}_reasoning_activate`,
+        Timestamp: Date.now(),
+        WasMentioned: true,
+        CommandAuthorized: true,
+        OriginatingChannel: "palz-connector",
+        OriginatingTo: palzTo,
+      });
+
+      // 创建静默 dispatcher，消费 ack 回复但不发送给 IM
+      // 通过 ack 内容判断是否真正激活成功
+      let activateSuccess = false;
+      const { dispatcher: silentDispatcher, replyOptions: silentReplyOptions, markDispatchIdle: silentMarkIdle } =
+        core.channel.reply.createReplyDispatcherWithTyping({
+          deliver: async (payload: any, info: any) => {
+            const text = payload.text ?? "";
+            log(`${tag}: [REASONING ACTIVATE] 收到 ack: "${text.slice(0, 200)}" kind=${info?.kind}`);
+            // handleDirectiveOnly 成功时返回含 "reasoning" 的 ack 文本（如 "Reasoning stream enabled."）
+            if (/reasoning/i.test(text)) {
+              activateSuccess = true;
+            }
+          },
+          onError: async (err: unknown) => {
+            log(`${tag}: [REASONING ACTIVATE] 错误: ${String(err)}`);
+          },
+          onIdle: async () => {
+            log(`${tag}: [REASONING ACTIVATE] dispatcher idle`);
+          },
+        });
+
+      await core.channel.reply.withReplyDispatcher({
+        dispatcher: silentDispatcher,
+        onSettled: () => silentMarkIdle(),
+        run: () =>
+          core.channel.reply.dispatchReplyFromConfig({
+            ctx: reasoningCtx,
+            cfg,
+            dispatcher: silentDispatcher,
+            replyOptions: silentReplyOptions,
+          }),
+      });
+
+      if (activateSuccess) {
+        reasoningActivated.add(route.sessionKey);
+        log(`${tag}: [REASONING ACTIVATE] 激活成功, sessionKey=${route.sessionKey}`);
+      } else {
+        log(`${tag}: [REASONING ACTIVATE] 未收到确认 ack, 下次请求将重试, sessionKey=${route.sessionKey}`);
+      }
+    } catch (err) {
+      log(`${tag}: [REASONING ACTIVATE] 激活失败: ${String(err)}`);
+    }
+  }
+
   // STEP 6c: 创建回复分发器
   const dispatcherParams = {
     accountId,
@@ -581,6 +695,8 @@ async function _dispatchPalzMessageInner(params: HandlePalzMessageParams): Promi
     msgType: msg.msg_type,
     groupId,
     mediaLocalRoots: resolveMediaLocalRoots(effectiveAgentId),
+    showProcess,
+    sessionKey: route.sessionKey,
   });
 
   // STEP 6d: 分发消息给 AI

package/src/config.ts

@@ -73,6 +73,7 @@ export function resolvePalzConfig(_cfg?: any): PalzConfig {
     apiBaseUrl: file.apiBaseUrl || "",
     sessionTimeout: file.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT,
     groupContextCache: file.groupContextCache !== false,
+    showProcess: file.showProcess === true,
   };
   if (!_configLoggedOnce) {
     _configLoggedOnce = true;

package/src/reply-dispatcher.ts

@@ -11,6 +11,7 @@
 import { getPalzRuntime } from "./runtime.js";
 import { loadMediaAsOssUrl } from "./media.js";
 import { sendToPalzIM } from "./send.js";
+import { resolveToolDisplay, formatToolStartText, formatToolResultText, formatResultSummary } from "./tool-display.js";
 import type { PalzConfig, StreamChunkOpts, ContentPart, OpenAIContent } from "./types.js";
 
 const STREAM_THROTTLE_MS = 200;
@@ -44,6 +45,8 @@ export interface CreatePalzReplyDispatcherParams {
   msgType?: string;
   groupId?: string;
   mediaLocalRoots?: readonly string[];
+  showProcess?: boolean;
+  sessionKey?: string;
 }
 
 export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParams) {
@@ -61,6 +64,7 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
     msgType,
     groupId,
     mediaLocalRoots,
+    showProcess,
   } = params;
 
   const log = typeof runtime?.log === "function" ? runtime.log : console.log;
@@ -68,11 +72,27 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
   const streamState = enableStreaming ? createStreamingState() : null;
   const tag = `palz[${accountId}]`;
 
+  // 会话级串行队列：保证同一会话内 IM 消息按入队顺序到达
+  // (不同 dispatcher 实例对应不同会话，天然隔离)
+  let imSendQueue: Promise<unknown> = Promise.resolve();
+  const enqueueIMSend = (
+    content: OpenAIContent,
+    streamOpts: StreamChunkOpts | undefined,
+    palzMsgType: string | undefined,
+    label: string,
+  ): Promise<unknown> => {
+    const next = imSendQueue.then(() => sendToIM(content, streamOpts, palzMsgType)).catch((err: any) => {
+      error(`${tag}: [IM_QUEUE] ${label} 发送失败: ${err?.message ?? String(err)}`);
+    });
+    imSendQueue = next;
+    return next;
+  };
+
   log(
     `${tag}: [DISPATCHER 创建] conv=${conversationId} sender=${senderId} streaming=${enableStreaming}${streamState ? ` streamId=${streamState.streamId}` : ""}`,
   );
 
-  const sendToIM = async (content: OpenAIContent, streamOpts?: StreamChunkOpts) => {
+  const sendToIM = async (content: OpenAIContent, streamOpts?: StreamChunkOpts, palzMsgType?: string, toolContent?: Record<string, unknown>) => {
     const contentPreview = typeof content === "string" ? content.slice(0, 120) : JSON.stringify(content).slice(0, 120);
     const sendInput = {
       conversationId,
@@ -80,6 +100,7 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
       conversationType,
       senderId,
       stream: streamOpts ? { streamId: streamOpts.streamId, seq: streamOpts.seq, isFinal: streamOpts.isFinal, deltaLen: streamOpts.delta?.length } : undefined,
+      palzMsgType,
     };
     log(`${tag}: [DISPATCHER→sendToIM] 输入: ${JSON.stringify(sendInput)}`);
     const result = await sendToPalzIM({
@@ -92,11 +113,58 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
       stream: streamOpts,
       msgType,
       groupId,
+      palzMsgType,
+      toolContent,
     });
     log(`${tag}: [DISPATCHER←sendToIM] 输出: ${JSON.stringify(result)}`);
     return result;
   };
 
+  // ============ 工具调用 & 思考过程中间过程监听 ============
+  let unsubscribeToolEvents: (() => void) | undefined;
+  let accumulatedThinking = "";
+
+  // 生成 runId，传给 dispatch 并用于事件过滤
+  // 这样可以精确关联当前 dispatcher 产生的工具事件，避免多用户并发串消息
+  const toolRunId = showProcess
+    ? `palz_run_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`
+    : undefined;
+
+  if (showProcess) {
+    log(`${tag}: [TOOL_EVENTS] 开启工具调用中间过程监听 runId=${toolRunId}`);
+    try {
+      unsubscribeToolEvents = core.events.onAgentEvent((evt: any) => {
+        // 按 runId 精确过滤，避免并发消息串事件
+        if (evt.runId !== toolRunId) return;
+
+        // ---- 工具事件 ----
+        if (evt.stream === "tool") {
+          const data = evt.data ?? {};
+          const phase = data.phase;
+          const toolName = data.name ?? data.toolName;
+
+          if (phase === "start") {
+            const display = resolveToolDisplay(toolName, data.args);
+            const text = formatToolStartText(toolName, data.args);
+            log(`${tag}: [TOOL_EVENTS] tool_start name=${toolName} detail=${display.detail ?? "(none)"}`);
+            enqueueIMSend(text, undefined, "tool_start", "tool_start");
+          }
+
+          if (phase === "result") {
+            const isError = data.isError === true;
+            const meta = typeof data.meta === "string" ? data.meta : undefined;
+            const text = formatToolResultText(toolName, data.result, isError, meta);
+            const resultSummary = isError ? "Error" : formatResultSummary(data.result);
+            log(`${tag}: [TOOL_EVENTS] tool_result name=${toolName} is_error=${isError} summary=${resultSummary}`);
+            enqueueIMSend(text, undefined, "tool_result", "tool_result");
+          }
+        }
+      });
+    } catch (err) {
+      error(`${tag}: [TOOL_EVENTS] 注册监听失败: ${String(err)}`);
+    }
+  }
+
   const { dispatcher, replyOptions, markDispatchIdle } =
     core.channel.reply.createReplyDispatcherWithTyping({
       deliver: async (payload: any, info: any) => {
@@ -145,18 +213,24 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
 
         if (streamState && kind === "final" && typeof content === "string") {
           const delta = content.slice(streamState.lastSentLength);
+          const seq = streamState.seq++;
           log(
-            `${tag}: [DELIVER 流式最终] seq=${streamState.seq} totalLen=${content.length} deltaLen=${delta.length} delta="${delta.slice(0, 120)}"`,
+            `${tag}: [DELIVER 流式最终] seq=${seq} totalLen=${content.length} deltaLen=${delta.length} delta="${delta.slice(0, 120)}"`,
+          );
+          await enqueueIMSend(
+            content,
+            {
+              streamId: streamState.streamId,
+              seq,
+              isFinal: true,
+              delta,
+            },
+            undefined,
+            `final seq=${seq}`,
           );
-          await sendToIM(content, {
-            streamId: streamState.streamId,
-            seq: streamState.seq++,
-            isFinal: true,
-            delta,
-          });
         } else {
           log(`${tag}: [DELIVER 非流式] contentType=${typeof content === "string" ? "string" : "array"}`);
-          await sendToIM(content);
+          await enqueueIMSend(content, undefined, undefined, "deliver");
         }
 
         log(`${tag}: [DELIVER 完成] kind=${kind}`);
@@ -169,11 +243,18 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
       },
       onIdle: async () => {
         log(`${tag}: [DISPATCHER idle]`);
+        if (unsubscribeToolEvents) {
+          log(`${tag}: [TOOL_EVENTS] 清理监听器`);
+          unsubscribeToolEvents();
+          unsubscribeToolEvents = undefined;
+        }
       },
     });
 
   const palzReplyOptions = {
     ...replyOptions,
+    // 传入 runId 让 OpenClaw agent execution 使用，与 onAgentEvent 的 evt.runId 对应
+    ...(toolRunId ? { runId: toolRunId } : {}),
     onPartialReply: enableStreaming
       ? (payload: any) => {
           const text = payload.text ?? "";
@@ -197,14 +278,37 @@ export function createPalzReplyDispatcher(params: CreatePalzReplyDispatcherParam
             `${tag}: [PARTIAL 输出] seq=${seq} totalLen=${text.length} deltaLen=${delta.length} delta="${delta.slice(0, 120)}" elapsed=${elapsed}ms`,
           );
 
-          sendToIM(text, {
-            streamId: streamState.streamId,
-            seq,
-            isFinal: false,
-            delta,
-          }).catch((err: any) => {
-            error(`${tag}: [PARTIAL 发送失败] seq=${seq} error=${err.message}`);
-          });
+          enqueueIMSend(
+            text,
+            {
+              streamId: streamState.streamId,
+              seq,
+              isFinal: false,
+              delta,
+            },
+            undefined,
+            `partial seq=${seq}`,
+          );
+        }
+      : undefined,
+    onReasoningStream: showProcess
+      ? (payload: any) => {
+          const text = payload.text ?? "";
+          if (text.trim()) {
+            accumulatedThinking = text;
+          }
+        }
+      : undefined,
+    onReasoningEnd: showProcess
+      ? () => {
+          if (!accumulatedThinking.trim()) return;
+          // 格式化思考文本：去掉 "Reasoning:\n" 前缀和 "_" 斜体标记
+          let text = accumulatedThinking;
+          accumulatedThinking = "";
+          text = text.replace(/^Reasoning:\n/, "");
+          text = text.replace(/^_|_$/gm, "");
+          log(`${tag}: [THINKING] 思考完成, len=${text.length}`);
+          enqueueIMSend(text, undefined, "thinking", "thinking");
         }
       : undefined,
   };

package/src/send.ts

@@ -29,7 +29,7 @@ export async function sendToPalzIM(params: SendToIMParams): Promise<any> {
 }
 
 async function _sendToPalzIMInner(params: SendToIMParams): Promise<any> {
-  const { config, conversationId, content, conversationType, msgId, senderId, stream, msgType, groupId } = params;
+  const { config, conversationId, content, conversationType, msgId, senderId, stream, msgType, groupId, palzMsgType, toolContent } = params;
   const url = `${config.apiBaseUrl}/bot/send`;
   const resolvedMsgId = msgId || nextMsgId();
   const span = trace.getActiveSpan();
@@ -61,6 +61,14 @@ async function _sendToPalzIMInner(params: SendToIMParams): Promise<any> {
     reqBody.delta = stream.delta;
   }
 
+  if (palzMsgType) {
+    reqBody.palz_msg_type = palzMsgType;
+  }
+
+  if (toolContent) {
+    reqBody.tool_content = toolContent;
+  }
+
   const reqBodyStr = JSON.stringify(reqBody);
   const reqLog = `[HTTP_REQ] POST ${url} body_length=${reqBodyStr.length}\n  request_body=${reqBodyStr}`;
   console.log(`palz-send: ${reqLog}`);

package/src/tool-display.ts

@@ -0,0 +1,273 @@
+/**
+ * 工具调用显示辅助模块
+ *
+ * 提供工具名到 emoji/title/detailKeys 的映射，以及生成纯文本摘要和结构化内容的辅助函数。
+ * 参考 OpenClaw 的 tool-display-overrides.json 和 ui/tool-display.ts。
+ */
+
+// ============ 工具映射表 ============
+
+interface ToolDisplaySpec {
+  emoji: string;
+  title: string;
+  detailKeys?: string[];
+}
+
+const TOOL_DISPLAY_MAP: Record<string, ToolDisplaySpec> = {
+  web_search: { emoji: "🔎", title: "Web Search", detailKeys: ["query", "count"] },
+  web_fetch: { emoji: "📄", title: "Web Fetch", detailKeys: ["url", "extractMode", "maxChars"] },
+  exec: { emoji: "🛠️", title: "Exec", detailKeys: ["command"] },
+  bash: { emoji: "🛠️", title: "Bash", detailKeys: ["command"] },
+  read: { emoji: "📖", title: "Read", detailKeys: ["path", "file_path"] },
+  write: { emoji: "✍️", title: "Write", detailKeys: ["path", "file_path"] },
+  edit: { emoji: "✍️", title: "Edit", detailKeys: ["path", "file_path"] },
+  glob: { emoji: "📂", title: "Glob", detailKeys: ["pattern"] },
+  grep: { emoji: "🔍", title: "Grep", detailKeys: ["pattern", "path"] },
+  memory_search: { emoji: "🧠", title: "Memory Search", detailKeys: ["query"] },
+  memory_get: { emoji: "📓", title: "Memory Get", detailKeys: ["path"] },
+  sessions_spawn: { emoji: "🧑‍🔧", title: "Sub-agent", detailKeys: ["label", "task"] },
+  sessions_send: { emoji: "📨", title: "Session Send", detailKeys: ["label", "sessionKey"] },
+  message: { emoji: "✉️", title: "Message", detailKeys: ["action", "to"] },
+  apply_patch: { emoji: "🩹", title: "Apply Patch", detailKeys: [] },
+  cron: { emoji: "⏰", title: "Cron", detailKeys: ["action", "cron"] },
+};
+
+const FALLBACK_EMOJI = "🔧";
+
+// ============ 工具名处理 ============
+
+function normalizeToolName(name?: string): string {
+  return (name ?? "tool").trim();
+}
+
+function defaultTitle(name: string): string {
+  const cleaned = name.replace(/_/g, " ").trim();
+  if (!cleaned) return "Tool";
+  return cleaned
+    .split(/\s+/)
+    .map((part) =>
+      part.length <= 2 && part.toUpperCase() === part
+        ? part
+        : `${part.charAt(0).toUpperCase()}${part.slice(1)}`,
+    )
+    .join(" ");
+}
+
+// ============ 文本截断 ============
+
+export function truncateText(text: string, headLen = 80, tailLen = 40): string {
+  if (!text) return text;
+  const maxLen = headLen + tailLen + 3; // 3 for "..."
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, headLen)}...${text.slice(-tailLen)}`;
+}
+
+// ============ Detail 提取 ============
+
+function extractDetail(args: unknown, detailKeys: string[]): string | undefined {
+  if (!args || typeof args !== "object" || !detailKeys.length) return undefined;
+  const record = args as Record<string, unknown>;
+  const parts: string[] = [];
+  for (const key of detailKeys) {
+    const value = record[key];
+    if (value === undefined || value === null) continue;
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    if (!str) continue;
+    parts.push(truncateText(str, 60, 20));
+  }
+  return parts.length > 0 ? parts.join(", ") : undefined;
+}
+
+function extractFallbackDetail(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") return undefined;
+  const record = args as Record<string, unknown>;
+  // Try 'action' field first as verb
+  if (typeof record.action === "string" && record.action.trim()) {
+    const otherParts: string[] = [];
+    for (const [key, value] of Object.entries(record)) {
+      if (key === "action") continue;
+      if (value === undefined || value === null) continue;
+      const str = typeof value === "string" ? value : JSON.stringify(value);
+      if (str) {
+        otherParts.push(truncateText(str, 40, 15));
+        break; // Only take the first extra field
+      }
+    }
+    const verb = record.action as string;
+    return otherParts.length > 0 ? `${verb} ${otherParts[0]}` : verb;
+  }
+  // Otherwise take the first field value
+  for (const value of Object.values(record)) {
+    if (value === undefined || value === null) continue;
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    if (str) return truncateText(str, 60, 20);
+  }
+  return undefined;
+}
+
+// ============ 核心：resolveToolDisplay ============
+
+export interface ToolDisplay {
+  emoji: string;
+  title: string;
+  detail?: string;
+}
+
+export function resolveToolDisplay(name?: string, args?: unknown): ToolDisplay {
+  const normalized = normalizeToolName(name);
+  const key = normalized.toLowerCase();
+  const spec = TOOL_DISPLAY_MAP[key];
+
+  const emoji = spec?.emoji ?? FALLBACK_EMOJI;
+  const title = spec?.title ?? defaultTitle(normalized);
+
+  let detail: string | undefined;
+  if (spec?.detailKeys && spec.detailKeys.length > 0) {
+    detail = extractDetail(args, spec.detailKeys);
+  }
+  if (!detail) {
+    detail = extractFallbackDetail(args);
+  }
+  // Truncate entire detail to 200 chars
+  if (detail && detail.length > 200) {
+    detail = truncateText(detail, 120, 40);
+  }
+
+  return { emoji, title, detail };
+}
+
+// ============ 纯文本格式化 ============
+
+export function formatToolStartText(name?: string, args?: unknown): string {
+  const display = resolveToolDisplay(name, args);
+  const lines = [`${display.emoji} ${display.title} 开始调用`];
+  if (display.detail) {
+    lines.push(`参数: ${display.detail}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatToolResultText(name?: string, result?: unknown, isError?: boolean, meta?: string): string {
+  const display = resolveToolDisplay(name);
+  const lines = [`${display.emoji} ${display.title} 调用完成`];
+
+  if (isError) {
+    lines.push("调用结果: 失败");
+    const errMsg = extractErrorMessage(result);
+    if (errMsg) {
+      lines.push(`错误信息: ${truncateText(errMsg, 80, 40)}`);
+    }
+  } else {
+    lines.push("调用结果: 成功");
+    const resultMeta = meta ? truncateText(meta, 120, 40) : `${display.title}执行成功`;
+    lines.push(`结果摘要: ${resultMeta}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ============ 结果摘要 ============
+
+export function formatResultSummary(result: unknown): string {
+  if (result === null || result === undefined) return "null";
+  if (typeof result === "string") return `String (${result.length} chars)`;
+  if (Array.isArray(result)) return `Array (${result.length} items)`;
+  if (typeof result === "object") {
+    const keys = Object.keys(result as object);
+    return `Object (${keys.length} keys)`;
+  }
+  return String(result);
+}
+
+function extractErrorMessage(result: unknown): string | undefined {
+  if (typeof result === "string") return result;
+  if (result && typeof result === "object") {
+    const record = result as Record<string, unknown>;
+    if (typeof record.error === "string") return record.error;
+    if (typeof record.message === "string") return record.message;
+    try {
+      return JSON.stringify(result).slice(0, 200);
+    } catch {
+      return undefined;
+    }
+  }
+  return result != null ? String(result) : undefined;
+}
+
+// ============ 结构化字段深度截断 ============
+
+const TOOL_CONTENT_MAX_LEN = 2000;
+const TOOL_CONTENT_STRING_MAX = 200;
+const TOOL_CONTENT_ARRAY_MAX_ITEMS = 3;
+
+export function truncateForToolContent(result: unknown, maxLen = TOOL_CONTENT_MAX_LEN): unknown {
+  if (result === null || result === undefined) return result;
+
+  // String: simple truncation
+  if (typeof result === "string") {
+    if (result.length <= maxLen) return result;
+    return `${result.slice(0, Math.min(1500, maxLen - 200))}...${result.slice(-200)}`;
+  }
+
+  // Primitive: pass through
+  if (typeof result !== "object") return result;
+
+  // Check if already small enough
+  try {
+    const serialized = JSON.stringify(result);
+    if (serialized && serialized.length <= maxLen) return result;
+  } catch {
+    return "[unserializable]";
+  }
+
+  // Deep truncate
+  return deepTruncate(result, maxLen);
+}
+
+function deepTruncate(value: unknown, budget: number): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") {
+    return value.length > TOOL_CONTENT_STRING_MAX
+      ? `${value.slice(0, TOOL_CONTENT_STRING_MAX - 20)}...${value.slice(-15)}`
+      : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return value;
+
+  if (Array.isArray(value)) {
+    const truncated: unknown[] = [];
+    const limit = Math.min(value.length, TOOL_CONTENT_ARRAY_MAX_ITEMS);
+    for (let i = 0; i < limit; i++) {
+      truncated.push(deepTruncate(value[i], Math.floor(budget / limit)));
+    }
+    if (value.length > limit) {
+      truncated.push({ __truncated: true, __total: value.length });
+    }
+    return truncated;
+  }
+
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    const entries = Object.entries(value as Record<string, unknown>);
+    let accumulated = 2; // "{}"
+    const perKeyBudget = Math.floor(budget / Math.max(entries.length, 1));
+
+    for (const [key, val] of entries) {
+      const truncatedVal = deepTruncate(val, perKeyBudget);
+      let addedSize: number;
+      try {
+        addedSize = JSON.stringify(truncatedVal).length + key.length + 4; // key:"val",
+      } catch {
+        addedSize = 50;
+      }
+      accumulated += addedSize;
+      if (accumulated > budget) {
+        result.__truncated = true;
+        break;
+      }
+      result[key] = truncatedVal;
+    }
+    return result;
+  }
+
+  return value;
+}

package/src/types.ts

@@ -51,6 +51,8 @@ export interface PalzConfig {
   sessionTimeout?: number;
   /** 群聊上下文缓存开关：true=未@消息缓存为上下文（默认），false=所有群聊消息直接发送给AI */
   groupContextCache?: boolean;
+  /** 是否将工具调用和思考过程发送到 IM，仅单聊生效，默认 false */
+  showProcess?: boolean;
 }
 
 export interface ResolvedPalzAccount {
@@ -90,4 +92,8 @@ export interface SendToIMParams {
   msgType?: string;
   /** 群组 ID，群聊时透传 */
   groupId?: string;
+  /** Palz 自定义消息类型（tool_start / tool_result） */
+  palzMsgType?: string;
+  /** 工具调用结构化内容 */
+  toolContent?: Record<string, unknown>;
 }