chatccc 0.2.21 → 0.2.23

package/README.md

@@ -16,11 +16,13 @@ ChatCCC 把 Claude Code、Cursor Agent、Codex (OpenAI) 接入了飞书群聊：
 
 一句话：**在任何设备上打开飞书，就能让 Claude Code / Cursor / Codex 帮你写代码、排查问题、分析项目。**
 
-<p align="center">
-  <img src="images/img_readme_0.jpg" alt="飞书群聊中使用 ChatCCC" width="280" />
-  &emsp;
-  <img src="images/img_readme_1.jpg" alt="思考过程和工具调用" width="280" />
-</p>
+<p align="center">
+  <img src="images/img_readme_messages.jpg" alt="飞书会话列表" width="220" align="top" />
+  &nbsp;
+  <img src="images/img_readme_0.jpg" alt="飞书群聊中使用 ChatCCC" width="220" align="top" />
+  &nbsp;
+  <img src="images/img_readme_1.jpg" alt="思考过程和工具调用" width="220" align="top" />
+</p>
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,10 @@
   "files": [
     "src/",
     "bin/",
-    "images/",
+    "images/img_readme_*.jpg",
+    "images/img_readme_*.png",
+    "images/avatars/status_*.png",
+    "images/avatars/badges/",
     "package.json",
     "README.md",
     "config.sample.json"

package/src/__tests__/agent-image-rpc.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  AGENT_SEND_IMAGE_PATH,
+  buildAgentImageCapabilityPrompt,
+  createAgentImageGrant,
+  getAgentImageGrantFromAuthorization,
+  revokeAgentImageGrant,
+} from "../agent-image-rpc.ts";
+
+describe("agent image RPC grants", () => {
+  it("creates a per-turn grant and validates bearer authorization", () => {
+    const grant = createAgentImageGrant({
+      chatId: "oc_chat",
+      sessionId: "sid-1",
+      cwd: "F:/repo",
+      port: 18080,
+      nowMs: 1000,
+      ttlMs: 60_000,
+    });
+
+    expect(grant.url).toBe(`http://127.0.0.1:18080${AGENT_SEND_IMAGE_PATH}`);
+    expect(grant.token.length).toBeGreaterThan(20);
+
+    const found = getAgentImageGrantFromAuthorization(
+      `Bearer ${grant.token}`,
+      30_000,
+    );
+    expect(found).toMatchObject({
+      chatId: "oc_chat",
+      sessionId: "sid-1",
+      cwd: "F:/repo",
+    });
+
+    revokeAgentImageGrant(grant.token);
+    expect(getAgentImageGrantFromAuthorization(`Bearer ${grant.token}`, 30_000)).toBeNull();
+  });
+
+  it("rejects missing, malformed, revoked, and expired authorization", () => {
+    const grant = createAgentImageGrant({
+      chatId: "oc_chat",
+      sessionId: "sid-1",
+      cwd: "F:/repo",
+      port: 18080,
+      nowMs: 1000,
+      ttlMs: 10,
+    });
+
+    expect(getAgentImageGrantFromAuthorization("", 1000)).toBeNull();
+    expect(getAgentImageGrantFromAuthorization(grant.token, 1000)).toBeNull();
+    expect(getAgentImageGrantFromAuthorization(`Basic ${grant.token}`, 1000)).toBeNull();
+    expect(getAgentImageGrantFromAuthorization(`Bearer ${grant.token}`, 1011)).toBeNull();
+  });
+
+  it("builds prompt instructions without requiring environment variables", () => {
+    const prompt = buildAgentImageCapabilityPrompt({
+      url: `http://127.0.0.1:18080${AGENT_SEND_IMAGE_PATH}`,
+      token: "tok_test",
+    });
+
+    expect(prompt).toContain("POST http://127.0.0.1:18080/api/agent/send-image");
+    expect(prompt).toContain("Authorization: Bearer tok_test");
+    expect(prompt).toContain("\"path\"");
+    expect(prompt).not.toContain("CHATCCC_SEND_IMAGE_URL");
+    expect(prompt).not.toContain("CHATCCC_SEND_IMAGE_TOKEN");
+  });
+});

package/src/agent-image-rpc.ts

@@ -0,0 +1,204 @@
+import { randomBytes } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extname, isAbsolute, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+
+import { getTenantAccessToken, sendImageReply, sendTextReply } from "./feishu-api.ts";
+import { ts } from "./config.ts";
+import { logTrace } from "./trace.ts";
+
+export const AGENT_SEND_IMAGE_PATH = "/api/agent/send-image";
+
+const DEFAULT_GRANT_TTL_MS = 30 * 60 * 1000;
+const MAX_REQUEST_BYTES = 64 * 1024;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const ALLOWED_IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp"]);
+
+export interface AgentImageGrant {
+  token: string;
+  url: string;
+  chatId: string;
+  sessionId: string;
+  cwd: string;
+  expiresAt: number;
+  traceId: string;
+}
+
+interface CreateAgentImageGrantInput {
+  chatId: string;
+  sessionId: string;
+  cwd: string;
+  port: number;
+  traceId?: string;
+  nowMs?: number;
+  ttlMs?: number;
+}
+
+const imageGrants = new Map<string, AgentImageGrant>();
+
+function createToken(): string {
+  return randomBytes(24).toString("base64url");
+}
+
+export function createAgentImageGrant(input: CreateAgentImageGrantInput): AgentImageGrant {
+  const now = input.nowMs ?? Date.now();
+  const token = createToken();
+  const grant: AgentImageGrant = {
+    token,
+    url: `http://127.0.0.1:${input.port}${AGENT_SEND_IMAGE_PATH}`,
+    chatId: input.chatId,
+    sessionId: input.sessionId,
+    cwd: input.cwd,
+    expiresAt: now + (input.ttlMs ?? DEFAULT_GRANT_TTL_MS),
+    traceId: input.traceId ?? "",
+  };
+  imageGrants.set(token, grant);
+  if (grant.traceId) logTrace(grant.traceId, "IMAGE_GRANT_CREATED", { sessionId: grant.sessionId, ttlMs: input.ttlMs ?? DEFAULT_GRANT_TTL_MS });
+  return grant;
+}
+
+export function revokeAgentImageGrant(token: string): void {
+  const grant = imageGrants.get(token);
+  if (grant?.traceId) logTrace(grant.traceId, "IMAGE_GRANT_REVOKED", {});
+  imageGrants.delete(token);
+}
+
+export function getAgentImageGrantFromAuthorization(
+  authorization: string | undefined,
+  nowMs = Date.now(),
+): AgentImageGrant | null {
+  const match = (authorization ?? "").match(/^Bearer\s+(.+)$/i);
+  if (!match) return null;
+  const grant = imageGrants.get(match[1]);
+  if (!grant) return null;
+  if (grant.expiresAt <= nowMs) {
+    imageGrants.delete(match[1]);
+    return null;
+  }
+  return grant;
+}
+
+export function buildAgentImageCapabilityPrompt(input: {
+  url: string;
+  token: string;
+  cwd?: string;
+}): string {
+  const lines = [
+    "[ChatCCC local capability: send image]",
+    "You can send an image to the current Feishu chat in real time by calling this local endpoint.",
+    "",
+    `POST ${input.url}`,
+    `Authorization: Bearer ${input.token}`,
+    "Content-Type: application/json",
+    "",
+    'Body: {"path":"absolute image file path","caption":"optional caption"}',
+    "",
+    "Rules:",
+    "- Save or choose a local image file first, then call the endpoint.",
+    "- Use an absolute local file path. Do not call Feishu Open Platform directly.",
+    "- Only call this endpoint when the user asked for an image or when an image is useful to the answer.",
+    "[/ChatCCC local capability: send image]",
+  ];
+  if (input.cwd) {
+    lines.splice(2, 0, `Current working directory: ${input.cwd}`);
+  }
+  return lines.join("\n");
+}
+
+function jsonReply(res: ServerResponse, status: number, data: unknown): void {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(data));
+}
+
+function readLimitedBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    let size = 0;
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_REQUEST_BYTES) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      body += chunk.toString("utf8");
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
+async function resolveAndValidateImagePath(grant: AgentImageGrant, rawPath: unknown): Promise<string> {
+  if (typeof rawPath !== "string" || rawPath.trim() === "") {
+    throw new Error("path must be a non-empty string");
+  }
+
+  const sessionRoot = resolve(grant.cwd);
+  const imagePath = isAbsolute(rawPath)
+    ? resolve(rawPath)
+    : resolve(sessionRoot, rawPath);
+
+  const ext = extname(imagePath).toLowerCase();
+  if (!ALLOWED_IMAGE_EXTS.has(ext)) {
+    throw new Error(`unsupported image extension: ${ext || "(none)"}`);
+  }
+
+  const st = await stat(imagePath);
+  if (!st.isFile()) throw new Error("image path is not a file");
+  if (st.size <= 0) throw new Error("image file is empty");
+  if (st.size > MAX_IMAGE_BYTES) throw new Error("image file is larger than 10MB");
+  return imagePath;
+}
+
+export async function handleAgentImageRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname !== AGENT_SEND_IMAGE_PATH) return false;
+
+  if (req.method !== "POST") {
+    jsonReply(res, 405, { ok: false, error: "Method not allowed" });
+    return true;
+  }
+
+  const grant = getAgentImageGrantFromAuthorization(req.headers.authorization);
+  if (!grant) {
+    jsonReply(res, 401, { ok: false, error: "Invalid or expired image-send token" });
+    return true;
+  }
+  const tid = grant.traceId;
+
+  let payload: { path?: unknown; caption?: unknown };
+  try {
+    payload = JSON.parse(await readLimitedBody(req));
+  } catch (err) {
+    if (tid) logTrace(tid, "IMAGE_REQ", { outcome: "invalid_json", error: (err as Error).message });
+    jsonReply(res, 400, { ok: false, error: (err as Error).message || "Invalid JSON" });
+    return true;
+  }
+
+  let imagePath: string;
+  try {
+    imagePath = await resolveAndValidateImagePath(grant, payload.path);
+  } catch (err) {
+    if (tid) logTrace(tid, "IMAGE_REQ", { outcome: "invalid_path", path: String(payload.path), error: (err as Error).message });
+    jsonReply(res, 400, { ok: false, error: (err as Error).message });
+    return true;
+  }
+
+  try {
+    const token = await getTenantAccessToken();
+    const caption = typeof payload.caption === "string" ? payload.caption.trim() : "";
+    await sendImageReply(token, grant.chatId, imagePath);
+    if (caption) await sendTextReply(token, grant.chatId, caption);
+    if (tid) logTrace(tid, "IMAGE_REQ", { outcome: "sent", path: imagePath, hasCaption: !!caption });
+    console.log(`[${ts()}] [AGENT-IMAGE] sent image chat=${grant.chatId} session=${grant.sessionId} path=${imagePath}`);
+    jsonReply(res, 200, { ok: true });
+  } catch (err) {
+    if (tid) logTrace(tid, "IMAGE_REQ", { outcome: "send_failed", path: imagePath!, error: (err as Error).message });
+    console.error(`[${ts()}] [AGENT-IMAGE] send failed: ${(err as Error).message}`);
+    jsonReply(res, 500, { ok: false, error: (err as Error).message });
+  }
+  return true;
+}

package/src/feishu-api.ts

@@ -1,5 +1,5 @@
 import { readdir, stat, readFile, mkdir, writeFile } from "node:fs/promises";
-import { resolve as resolvePath } from "node:path";
+import { extname, resolve as resolvePath } from "node:path";
 import { dirname, join } from "node:path";
 import sharp from "sharp";
 
@@ -424,7 +424,7 @@ async function loadImageCache(): Promise<void> {
     for (const [key, value] of Object.entries(parsed)) {
       if (typeof value === "string" && value.trim()) imageCache.set(key, value);
     }
-  } catch { /* missing or malformed cache is not fatal */ }
+  } catch { /* missing or malformed cache is not fatal */ }
 }
 
 async function persistImageCache(): Promise<void> {
@@ -475,7 +475,7 @@ export async function getOrDownloadImage(token: string, messageId: string, fileK
   await persistImageCache().catch((err) => {
     console.error(`[${ts()}] [IMAGE] persist cache FAIL: ${(err as Error).message}`);
   });
-  console.log(`[${ts()}] [IMAGE] Downloaded ${fileKey} -> ${localPath}`);
+  console.log(`[${ts()}] [IMAGE] Downloaded ${fileKey} -> ${localPath}`);
   return localPath;
 }
 
@@ -521,23 +521,103 @@ export async function sendTextReply(
   token: string,
   chatId: string,
   text: string
-): Promise<void> {
+): Promise<boolean> {
   const card = JSON.stringify({
     config: { wide_screen_mode: true },
     elements: [{ tag: "markdown", content: text }],
   });
-  await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+  try {
+    const resp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: "interactive",
+        content: card,
+      }),
+    });
+    const data = (await resp.json().catch(() => ({}))) as { code: number; msg?: string; data?: { message_id?: string } };
+    if (data.code !== 0) {
+      console.error(`[${ts()}] [SEND] text FAIL: chatId=${chatId} code=${data.code} msg="${data.msg ?? ""}"`);
+      return false;
+    }
+    console.log(`[${ts()}] [SEND] text OK: chatId=${chatId} msgId=${data.data?.message_id ?? "N/A"}`);
+    return true;
+  } catch (err) {
+    console.error(`[${ts()}] [SEND] text FAIL: chatId=${chatId} ${(err as Error).message}`);
+    return false;
+  }
+}
+
+function messageImageContentType(imagePath: string): string {
+  const ext = extname(imagePath).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".bmp") return "image/bmp";
+  return "image/png";
+}
+
+async function uploadMessageImage(token: string, imagePath: string): Promise<string> {
+  const buffer = await readFile(imagePath);
+  const blob = new Blob([new Uint8Array(buffer)], {
+    type: messageImageContentType(imagePath),
+  });
+  const form = new FormData();
+  form.append("image_type", "message");
+  form.append("image", blob, imagePath.split(/[\\/]/).pop() || "image.png");
+
+  const resp = await fetch(`${BASE_URL}/im/v1/images`, {
     method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      receive_id: chatId,
-      msg_type: "interactive",
-      content: card,
-    }),
+    headers: { Authorization: `Bearer ${token}` },
+    body: form,
   });
+  const text = await resp.text();
+  let data: { code: number; msg?: string; data?: { image_key?: string } };
+  try { data = JSON.parse(text); } catch {
+    throw new Error(`uploadMessageImage non-JSON response: ${text.slice(0, 200)}`);
+  }
+  if (data.code !== 0) throw new Error(`[${data.code}] ${data.msg}`);
+  const imageKey = data.data?.image_key;
+  if (!imageKey) throw new Error("uploadMessageImage response missing image_key");
+  return imageKey;
+}
+
+export async function sendImageReply(
+  token: string,
+  chatId: string,
+  imagePath: string,
+): Promise<boolean> {
+  try {
+    const imageKey = await uploadMessageImage(token, imagePath);
+    const resp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: "image",
+        content: JSON.stringify({ image_key: imageKey }),
+      }),
+    });
+    const data = (await resp.json().catch(() => ({}))) as { code?: number; msg?: string; data?: { message_id?: string } };
+    if (data.code !== 0) {
+      console.error(`[${ts()}] [SEND] image FAIL: chatId=${chatId} path=${imagePath} code=${data.code} msg="${data.msg ?? ""}"`);
+      throw new Error(`[${data.code}] ${data.msg ?? "send image failed"}`);
+    }
+    console.log(`[${ts()}] [SEND] image OK: chatId=${chatId} msgId=${data.data?.message_id ?? "N/A"}`);
+    return true;
+  } catch (err) {
+    if (!(err instanceof Error && err.message.startsWith("["))) {
+      console.error(`[${ts()}] [SEND] image FAIL: chatId=${chatId} path=${imagePath} ${(err as Error).message}`);
+    }
+    throw err;
+  }
 }
 
 export async function addReaction(
@@ -561,21 +641,33 @@ export async function sendCardReply(
   title: string,
   content: string,
   template = "green"
-): Promise<void> {
+): Promise<boolean> {
   const card = JSON.stringify({
     config: { wide_screen_mode: true },
     header: { template, title: { content: title, tag: "plain_text" } },
     elements: [{ tag: "div", text: { tag: "lark_md", content } }],
   });
 
-  await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
-  });
+  try {
+    const resp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
+    });
+    const data = (await resp.json().catch(() => ({}))) as { code: number; msg?: string; data?: { message_id?: string } };
+    if (data.code !== 0) {
+      console.error(`[${ts()}] [SEND] card FAIL: chatId=${chatId} title="${title}" code=${data.code} msg="${data.msg ?? ""}"`);
+      return false;
+    }
+    console.log(`[${ts()}] [SEND] card OK: chatId=${chatId} title="${title}" msgId=${data.data?.message_id ?? "N/A"}`);
+    return true;
+  } catch (err) {
+    console.error(`[${ts()}] [SEND] card FAIL: chatId=${chatId} title="${title}" ${(err as Error).message}`);
+    return false;
+  }
 }
 
 // 重启后，向最后有发言的会话发送 "已重启" 卡片（基于 chat_logs 的文件修改时间）

package/src/index.ts

@@ -31,7 +31,8 @@ import { WSClient, EventDispatcher } from "@larksuiteoapi/node-sdk";
 import WebSocket from "ws";
 
 import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging } from "./shared.ts";
-import { createUiRouter, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import { makeTraceId, logTrace } from "./trace.ts";
 import {
   CHATCCC_PORT,
   APP_ID,
@@ -81,6 +82,7 @@ import {
 } from "./feishu-api.ts";
 import { buildHelpCard, buildStatusCard, buildProgressCard, buildCdContent, buildCdCard, buildSessionsCard } from "./cards.ts";
 import { updateCardKitCard } from "./cardkit.ts";
+import { handleAgentImageRequest } from "./agent-image-rpc.ts";
 import { formatGitResult, gitResultHeaderTemplate, runGitCommand } from "./git-command.ts";
 import {
   MAX_PROCESSED,
@@ -113,7 +115,7 @@ function isUntitledSessionChatName(name: string): boolean {
 // ---------------------------------------------------------------------------
 
 interface InnerEvent {
-  message?: { message_id?: string; message_type?: string; content?: string; chat_id?: string; create_time?: string };
+  message?: { message_id?: string; message_type?: string; content?: string; chat_id?: string; chat_type?: string; create_time?: string };
   sender?: { sender_id?: { open_id?: string; union_id?: string } };
 }
 
@@ -242,10 +244,13 @@ let broadcastToRelay: (data: unknown) => void = () => {};
 // Command handler
 // ---------------------------------------------------------------------------
 
-async function handleCommand(text: string, chatId: string, openId: string, msgTimestamp: number): Promise<void> {
+async function handleCommand(text: string, chatId: string, openId: string, msgTimestamp: number, chatType = "group", traceId?: string): Promise<void> {
+  const tid = traceId ?? makeTraceId();
   if (text === "/restart") {
+    logTrace(tid, "BRANCH", { cmd: "/restart" });
     const restartToken = await getTenantAccessToken();
     await sendTextReply(restartToken, chatId, "正在重启...").catch(() => {});
+    logTrace(tid, "DONE", { outcome: "restart" });
     console.log(`[${ts()}] [RESTART] Spawning new process...`);
     const child = spawn("npx", ["tsx", "src/index.ts"], {
       cwd: PROJECT_ROOT,
@@ -259,6 +264,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
   }
 
   if (text === "/cd" || text.startsWith("/cd ")) {
+    logTrace(tid, "BRANCH", { cmd: "/cd", arg: text.slice(3).trim() || "(none)" });
     const cdToken = await getTenantAccessToken();
     const currentDir = await getDefaultCwd();
 
@@ -290,10 +296,12 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     try {
       const s = await stat(targetDir);
       if (!s.isDirectory()) {
+        logTrace(tid, "DONE", { outcome: "cd_not_dir", targetDir });
         await sendCardReply(cdToken, chatId, "新会话工作路径", `路径存在但不是目录:\n\`${targetDir}\``, "red");
         return;
       }
     } catch {
+      logTrace(tid, "DONE", { outcome: "cd_not_found", targetDir });
       await sendCardReply(cdToken, chatId, "新会话工作路径", `路径不存在:\n\`${targetDir}\``, "red");
       return;
     }
@@ -310,6 +318,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     try {
       entries = await readdir(targetDir);
     } catch (err) {
+      logTrace(tid, "DONE", { outcome: "cd_readdir_fail", error: (err as Error).message });
       await sendCardReply(cdToken, chatId, "新会话工作路径", `无法读取目录:\n\`${targetDir}\`\n\n${(err as Error).message}`, "red");
       return;
     }
@@ -341,10 +350,12 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       });
       const respData: Record<string, any> = await resp.json().catch(() => ({}));
       console.log(`[${ts()}] [CD] card sent, code=${respData.code}, msgId=${respData.data?.message_id ?? "N/A"}, recentDirs=${recentDirs.length}`);
+      logTrace(tid, "DONE", { outcome: "cd_card", code: respData.code, msgId: respData.data?.message_id });
     } else {
       // /cd <path>：切换目录，发送文本卡片
       const content = buildCdContent(targetDir, withStats, isUpdate, sessionCwd);
       await sendCardReply(cdToken, chatId, "新会话工作路径", content, "blue");
+      logTrace(tid, "DONE", { outcome: "cd_path", targetDir, isUpdate });
     }
     return;
   }
@@ -352,8 +363,10 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
   if (text === "/new" || text.startsWith("/new ")) {
     const toolArg = text.slice(5).trim();
     const tool = toolArg || "claude";
+    logTrace(tid, "BRANCH", { cmd: "/new", tool });
     const validTools = ["claude", "cursor", "codex"];
     if (!validTools.includes(tool)) {
+      logTrace(tid, "DONE", { outcome: "new_invalid_tool", tool });
       const warnToken = await getTenantAccessToken();
       await sendCardReply(warnToken, chatId, "Error", `未知的工具类型: "${toolArg}"。支持: claude (Claude Code), cursor (Cursor), codex (Codex)。`, "red");
       return;
@@ -361,6 +374,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     const toolLabel = toolDisplayName(tool);
 
     if (!openId) {
+      logTrace(tid, "DONE", { outcome: "new_no_openid" });
       console.log(`[${ts()}] [WARN] Cannot get sender open_id`);
       const warnToken = await getTenantAccessToken();
       await sendCardReply(warnToken, chatId, "Error", "Cannot identify sender.", "red");
@@ -378,6 +392,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       console.log(`[${ts()}] [STEP 1/4] ${toolLabel} session created: ${sessionId} → OK`);
     } catch (err) {
       console.error(`[${ts()}] [STEP 1/4] FAIL: ${(err as Error).message}`);
+      logTrace(tid, "DONE", { outcome: "new_session_fail", error: (err as Error).message });
       await sendCardReply(
         freshToken, chatId, "Error",
         `Failed to initialize ${toolLabel} session:\n${(err as Error).message}`,
@@ -395,6 +410,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       console.log(`[${ts()}] [STEP 2/4] Created Feishu group: ${newChatId}  → OK`);
     } catch (err) {
       console.error(`[${ts()}] [STEP 2/4] FAIL: ${(err as Error).message}`);
+      logTrace(tid, "DONE", { outcome: "new_group_fail", error: (err as Error).message });
       await sendCardReply(freshToken, chatId, "Error", `Failed to create group:\n${(err as Error).message}`, "red");
       return;
     }
@@ -405,6 +421,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       console.log(`[${ts()}] [STEP 3/4] Renamed group → name="${initialName}" (${toolLabel}) → OK`);
     } catch (err) {
       console.error(`[${ts()}] [STEP 3/4] FAIL: ${(err as Error).message}`);
+      logTrace(tid, "DONE", { outcome: "new_rename_fail", error: (err as Error).message });
       await sendCardReply(freshToken, chatId, "Error", `Group created but rename failed:\n${(err as Error).message}`, "yellow");
       return;
     }
@@ -422,11 +439,14 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     );
 
     console.log(`[${ts()}] [STEP 4/4] Replied to new group → OK`);
+    logTrace(tid, "DONE", { outcome: "session_ready", newChatId, sessionId, tool });
     setChatAvatar(freshToken, newChatId, tool, "new").catch(() => {});
     console.log(`${"=".repeat(60)}`);
     return;
   }
 
+  // 私聊没有群 description，无法存储/获取 session ID，跳过群聊检测直接发 help card
+  if (chatType !== "p2p") {
   try {
     const token = await getTenantAccessToken();
     const chatInfo = await getChatInfo(token, chatId);
@@ -437,6 +457,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       const sessionId = sessionInfo.sessionId;
       const descriptionTool = sessionInfo.tool;
       const toolLabel = toolDisplayName(descriptionTool);
+      logTrace(tid, "BRANCH", { sessionId, tool: descriptionTool });
       console.log(`[${ts()}] [RESUME] ${toolLabel} session group detected, session=${sessionId} tool=${descriptionTool}`);
 
       const freshToken = await getTenantAccessToken();
@@ -457,6 +478,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       }
 
       if (text === "/stop") {
+        logTrace(tid, "BRANCH", { cmd: "/stop" });
         const cEntry = chatSessionMap.get(chatId);
         if (cEntry) {
           cEntry.stopped = true;
@@ -464,13 +486,16 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           cEntry.close();
           console.log(`[${ts()}] [STOP] User sent /stop, session=${sessionId}`);
           await sendTextReply(freshToken, chatId, "会话已停止。").catch(() => {});
+          logTrace(tid, "DONE", { outcome: "stopped" });
         } else {
           await sendTextReply(freshToken, chatId, "当前没有正在进行的会话。").catch(() => {});
+          logTrace(tid, "DONE", { outcome: "stop_no_session" });
         }
         return;
       }
 
       if (text === "/status") {
+        logTrace(tid, "BRANCH", { cmd: "/status" });
         const status = await getSessionStatus(chatId);
         const running = chatSessionMap.get(chatId);
         const isActive = running && !running.stopped;
@@ -507,10 +532,12 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         });
         const statusRespData: Record<string, any> = await statusResp.json().catch(() => ({}));
         console.log(`[${ts()}] [STATUS] card sent, code=${statusRespData.code}, msgId=${statusRespData.data?.message_id ?? "N/A"}`);
+        logTrace(tid, "DONE", { outcome: "status", code: statusRespData.code });
         return;
       }
 
       if (text === "/sessions") {
+        logTrace(tid, "BRANCH", { cmd: "/sessions" });
         const allSessions = await getAllSessionsStatus();
         const now = Date.now();
         const cardData = allSessions.map(s => ({
@@ -532,10 +559,12 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         });
         const sessionsRespData: Record<string, any> = await sessionsResp.json().catch(() => ({}));
         console.log(`[${ts()}] [SESSIONS] card sent, code=${sessionsRespData.code}, count=${allSessions.length}`);
+        logTrace(tid, "DONE", { outcome: "sessions", code: sessionsRespData.code, count: allSessions.length });
         return;
       }
 
       if (text === "/forget") {
+        logTrace(tid, "BRANCH", { cmd: "/forget" });
         const adapter = getAdapterForTool(descriptionTool);
         let cwd: string;
         try {
@@ -558,6 +587,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           const init = await initClaudeSession(descriptionTool, cwd);
           newSessionId = init.sessionId;
         } catch (err) {
+          logTrace(tid, "DONE", { outcome: "forget_session_fail", error: (err as Error).message });
           await sendCardReply(freshToken, chatId, "Error", `Failed to create new session:\n${(err as Error).message}`, "red");
           return;
         }
@@ -587,6 +617,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         );
 
         console.log(`[${ts()}] [FORGET] Session ${sessionId} → ${newSessionId} (same cwd=${cwd})`);
+        logTrace(tid, "DONE", { outcome: "forget", newSessionId, cwd });
         return;
       }
 
@@ -595,7 +626,9 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       // getDefaultCwd（下一次 /new 才会使用的默认路径）。
       if (text.startsWith("/git ") || text === "/git") {
         const args = text === "/git" ? "" : text.slice(5).trim();
+        logTrace(tid, "BRANCH", { cmd: "/git", args: args || "(none)" });
         if (!args) {
+          logTrace(tid, "DONE", { outcome: "git_no_args" });
           await sendCardReply(
             freshToken, chatId, "/git",
             "用法：`/git <子命令> [参数]`，例如 `/git status`、`/git log --oneline -n 5`。",
@@ -613,6 +646,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           console.error(`[${ts()}] [GIT] getSessionInfo FAIL: ${(err as Error).message}`);
         }
         if (!cwd) {
+          logTrace(tid, "DONE", { outcome: "git_no_cwd", tool: descriptionTool });
           // Cursor 会话的 cwd 依赖 state/cursor-session-meta.json 持久化映射；
           // 升级前创建的旧会话或映射文件丢失时，向会话发送一次普通消息即可触发
           // adapter 自动学习并补全（resume 流首条 init 事件携带 cwd）。
@@ -630,12 +664,14 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         const content = formatGitResult(args, cwd, result);
         const template = gitResultHeaderTemplate(result);
         await sendCardReply(freshToken, chatId, "/git 输出", content, template);
+        logTrace(tid, "DONE", { outcome: "git_result", exitCode: result.exitCode, durationMs: result.durationMs });
         return;
       }
 
       const existing = chatSessionMap.get(chatId);
       if (existing && !existing.stopped) {
         if (msgTimestamp <= existing.msgTimestamp) {
+          logTrace(tid, "DONE", { outcome: "skip_old_message", msgTimestamp, existingTimestamp: existing.msgTimestamp });
           console.log(`[${ts()}] [SKIP] Older message (${msgTimestamp} <= ${existing.msgTimestamp}), ignoring`);
           return;
         }
@@ -644,6 +680,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         existing.close();
         chatSessionMap.delete(chatId);
         console.log(`[${ts()}] [INTERRUPT] New message arrived, cancelled previous session ${sessionId}`);
+        logTrace(tid, "INTERRUPT", { oldSessionId: sessionId });
         if (existing.cardId) {
           while (existing.cardBusy) {
             await new Promise(r => setTimeout(r, 20));
@@ -662,9 +699,12 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       }
 
       try {
-        await resumeAndPrompt(sessionId, text, freshToken, chatId, msgTimestamp, descriptionTool);
+        logTrace(tid, "RESUME", { sessionId, tool: descriptionTool });
+        await resumeAndPrompt(sessionId, text, freshToken, chatId, msgTimestamp, descriptionTool, tid);
+        logTrace(tid, "DONE", { outcome: "resume_done", sessionId });
         console.log(`[${ts()}] [RESUME] Session ${sessionId} done`);
       } catch (err) {
+        logTrace(tid, "DONE", { outcome: "resume_fail", error: (err as Error).message });
         console.error(`[${ts()}] [RESUME] FAIL: ${(err as Error).message}`);
         fileLog.flush();
         await sendCardReply(
@@ -675,13 +715,19 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       }
       return;
     }
+    // 群聊但 description 中没有 session info → 也走 help card
+    logTrace(tid, "BRANCH", { reason: "no_session_info_in_group" });
   } catch (err) {
+    logTrace(tid, "BRANCH", { reason: "get_chat_info_failed", error: (err as Error).message });
     console.log(`[${ts()}] [INFO] Cannot get chat info for ${chatId}: ${(err as Error).message}`);
   }
+  } // end if (chatType !== "p2p")
 
+  // 私聊或群聊无 session info → 发送 help card
+  logTrace(tid, "SEND", { method: "help_card", chatId });
   const replyToken = await getTenantAccessToken();
   const card = buildHelpCard(text);
-  await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+  const helpResp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${replyToken}`,
@@ -689,6 +735,14 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     },
     body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
   });
+  const helpData = (await helpResp.json().catch(() => ({}))) as { code: number; msg?: string; data?: { message_id?: string } };
+  if (helpData.code !== 0) {
+    console.error(`[${ts()}] [SEND] help_card FAIL: chatId=${chatId} code=${helpData.code} msg="${helpData.msg ?? ""}"`);
+    logTrace(tid, "DONE", { outcome: "help_card_fail", code: helpData.code, msg: helpData.msg });
+  } else {
+    console.log(`[${ts()}] [SEND] help_card OK: chatId=${chatId} msgId=${helpData.data?.message_id ?? "N/A"}`);
+    logTrace(tid, "DONE", { outcome: "help_card_sent", msgId: helpData.data?.message_id });
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -779,6 +833,7 @@ async function startBotServiceCore(): Promise<void> {
   const eventDispatcher = new EventDispatcher({});
   eventDispatcher.register({
     "im.message.receive_v1": async (data: Evt) => {
+      const traceId = makeTraceId();
       try {
       broadcastToRelay(data);
 
@@ -803,8 +858,9 @@ async function startBotServiceCore(): Promise<void> {
       const sender = event.sender;
       const openId = sender?.sender_id?.open_id ?? "";
       const chatId = message.chat_id ?? "";
+      const chatType = message.chat_type ?? "group";
 
-      console.log(`[MSG] sender=${openId} chat=${chatId} text="${text}"`);
+      console.log(`[MSG] sender=${openId} chat=${chatId} type=${chatType} text="${text}"`);
       appendChatLog(chatId, openId, text);
 
       if (messageId) {
@@ -819,13 +875,15 @@ async function startBotServiceCore(): Promise<void> {
 
       if (!text) return;
       const msgTimestamp = parseInt(message.create_time ?? "0", 10) || Date.now();
+      logTrace(traceId, "RECV", { chatId, chatType, text: text.slice(0, 100) });
       const delayNotice = formatDelayNotice(msgTimestamp);
       if (delayNotice) {
         const delayToken = await getTenantAccessToken();
         await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => {});
       }
-      await handleCommand(text, chatId, openId, msgTimestamp);
+      await handleCommand(text, chatId, openId, msgTimestamp, chatType, traceId);
       } catch (err) {
+        logTrace(traceId, "ERROR", { message: (err as Error).message });
         console.error(`[${ts()}] [FATAL] im.message.receive_v1 handler crashed: ${(err as Error).message}`);
       }
     },
@@ -990,6 +1048,7 @@ async function main(): Promise<void> {
       appIdMask: maskAppId(APP_ID),
     });
   });
+  setExtraApiHandler(handleAgentImageRequest);
 
   console.log(`[启动 2/7] 环境与凭证检查`);
   reportEnvironmentVariableReadout();

package/src/session.ts

@@ -6,6 +6,7 @@ import {
   CLAUDE_BASE_URL,
   CLAUDE_EFFORT,
   CLAUDE_MODEL,
+  CHATCCC_PORT,
   SESSIONS_FILE,
   addRecentDir,
   anthropicConfigDisplay,
@@ -23,11 +24,17 @@ import {
   updateCardKitCard,
 } from "./cardkit.ts";
 import { sendTextReply, setChatAvatar } from "./feishu-api.ts";
+import { logTrace } from "./trace.ts";
 import type { UnifiedBlock } from "./adapters/adapter-interface.ts";
 import type { ToolAdapter } from "./adapters/adapter-interface.ts";
 import { createClaudeAdapter } from "./adapters/claude-adapter.ts";
 import { createCursorAdapter } from "./adapters/cursor-adapter.ts";
 import { createCodexAdapter } from "./adapters/codex-adapter.ts";
+import {
+  buildAgentImageCapabilityPrompt,
+  createAgentImageGrant,
+  revokeAgentImageGrant,
+} from "./agent-image-rpc.ts";
 
 // ---------------------------------------------------------------------------
 // Shared state (imported by index.ts)
@@ -251,7 +258,7 @@ export function accumulateBlockContent(
 }
 
 // ---------------------------------------------------------------------------
-// AI tool session management
+// AI tool session management
 // ---------------------------------------------------------------------------
 
 /**
@@ -300,13 +307,34 @@ export async function resumeAndPrompt(
   chatId: string,
   msgTimestamp: number,
   tool: string,
+  traceId?: string,
 ): Promise<void> {
+  const tid = traceId ?? "";
   const adapter = getAdapterForTool(tool);
   const info = await adapter.getSessionInfo(sessionId);
   const cwd = info?.cwd ?? (await getDefaultCwd());
+  if (tid) logTrace(tid, "SESSION_START", { sessionId, tool, cwd, turn: (sessionInfoMap.get(chatId)?.turnCount ?? 0) + 1 });
   console.log(
     `[${ts()}] Resuming ${adapter.displayName} session: ${sessionId} (${formatToolConfigForLog(tool, info?.model)}, cwd=${cwd})`
   );
+  const imageGrant = createAgentImageGrant({
+    chatId,
+    sessionId,
+    cwd,
+    port: CHATCCC_PORT,
+    traceId: tid || undefined,
+  });
+  const userTextWithCapabilities = [
+    buildAgentImageCapabilityPrompt({
+      url: imageGrant.url,
+      token: imageGrant.token,
+      cwd,
+    }),
+    "",
+    "[User message]",
+    userText,
+    "[/User message]",
+  ].join("\n");
 
   const controller = new AbortController();
 
@@ -338,6 +366,7 @@ export async function resumeAndPrompt(
 
   let cardId: string | null = null;
   cardId = await createCardKitCard(token, buildProgressCard("", { showStop: true, headerTitle: "生成中..." })).catch((err) => {
+    if (tid) logTrace(tid, "CARD_CREATE_FAIL", { error: (err as Error).message });
     console.error(`[${ts()}] [CARDIKT] createCard FAIL: chatId=${chatId} ${(err as Error).message}`);
     fileLog.flush();
     sendTextReply(token, chatId, "⚠️ 流式卡片创建失败（可能因限流），将使用文本回复。").catch(() => {});
@@ -347,6 +376,7 @@ export async function resumeAndPrompt(
     const cEntry = chatSessionMap.get(chatId);
     if (cEntry) { cEntry.cardId = cardId; cEntry.sequence = 1; }
     const sendOk = await sendCardKitMessage(token, chatId, cardId).catch((err) => {
+      if (tid) logTrace(tid, "CARD_SEND_FAIL", { cardId, error: (err as Error).message });
       console.error(`[${ts()}] [CARDIKT] sendMessage FAIL: chatId=${chatId} cardId=${cardId} ${(err as Error).message}`);
       fileLog.flush();
       return false;
@@ -445,7 +475,7 @@ export async function resumeAndPrompt(
   }
 
   try {
-    for await (const unifiedMsg of adapter.prompt(sessionId, userText, cwd, controller.signal)) {
+    for await (const unifiedMsg of adapter.prompt(sessionId, userTextWithCapabilities, cwd, controller.signal)) {
       for (const block of unifiedMsg.blocks) {
         accumulateBlockContent(block, state);
 
@@ -460,6 +490,7 @@ export async function resumeAndPrompt(
     console.error(`[${ts()}] [STREAM] Error in stream loop: ${(streamErr as Error).message}`);
   } finally {
     if (sendInterval) clearInterval(sendInterval);
+    revokeAgentImageGrant(imageGrant.token);
   }
 
   const cEntry = chatSessionMap.get(chatId);
@@ -501,6 +532,7 @@ export async function resumeAndPrompt(
       );
     }
     console.log(`[${ts()}] Session ${sessionId} stopped by user (content chunks: ${state.chunkCount})`);
+    if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "stopped", chunks: state.chunkCount });
     return;
   }
 
@@ -530,6 +562,7 @@ export async function resumeAndPrompt(
   }
 
   console.log(`[${ts()}] Session ${sessionId} stream complete (content chunks: ${state.chunkCount})`);
+  if (tid) logTrace(tid, "SESSION_END", { sessionId, chunks: state.chunkCount, finalTextLen: finalReply.length });
 }
 
 // ---------------------------------------------------------------------------

package/src/trace.ts

@@ -0,0 +1,51 @@
+/**
+ * 轻量级消息全链路 trace 工具。
+ *
+ * 每条消息生成唯一 traceId，在关键决策点、API 调用、消息发送时输出结构化日志。
+ * grep traceId 即可看到该消息的完整 RECV → BRANCH → SEND → DONE 链路。
+ *
+ * 设计原则：trace 自身绝不能抛异常导致主流程中断——所有函数内都有 try/catch 兜底。
+ */
+
+let _traceSeq = 0;
+
+/** 基于时间戳 + 递增序号生成短 trace ID（约 10 字符） */
+export function makeTraceId(): string {
+  try {
+    _traceSeq++;
+    const ts = Date.now().toString(36).slice(-6);
+    const seq = _traceSeq.toString(36).padStart(3, "0");
+    return `${ts}${seq}`;
+  } catch {
+    // 极端情况（计数器溢出等）降级为纯时间戳
+    return Date.now().toString(36);
+  }
+}
+
+/**
+ * 输出一条 trace 日志。
+ * detail 中的值做浅层截断（字符串 > 200 字符会截断），避免日志膨胀。
+ */
+export function logTrace(traceId: string, step: string, detail?: Record<string, unknown>): void {
+  try {
+    const safe: Record<string, unknown> = {};
+    if (detail) {
+      for (const [k, v] of Object.entries(detail)) {
+        if (typeof v === "string" && v.length > 200) {
+          safe[k] = v.slice(0, 200) + "...(truncated)";
+        } else {
+          safe[k] = v;
+        }
+      }
+    }
+    const extra = Object.keys(safe).length > 0 ? " " + JSON.stringify(safe) : "";
+    console.log(`[TRACE ${traceId}] ${step}${extra}`);
+  } catch {
+    // trace 自身绝不能抛异常
+  }
+}
+
+/** 重置序号（仅单测使用，确保 trace ID 可预测） */
+export function _resetTraceSeqForTest(): void {
+  _traceSeq = 0;
+}

package/src/web-ui.ts

@@ -1570,6 +1570,8 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
   const url = req.url ?? "/";
   const method = req.method ?? "GET";
 
+  if (extraApiHandler && await extraApiHandler(req, res)) return;
+
   // API routes
   if (url === "/api/check" && method === "GET") return handleApiCheck(req, res);
   if (url === "/api/config" && method === "GET") return handleGetConfig(req, res);
@@ -1662,6 +1664,8 @@ let setupActivateHook: SetupActivateHook | null = null;
 // 由 index.ts 注入，因为 web-ui.ts 自身**不应**直接 import config.ts——后者顶层
 // 有 loadConfig 副作用，被 web-ui.ts 间接 import 会污染所有依赖 web-ui.ts 的单测。
 let reloadConfigHook: (() => void) | null = null;
+type ExtraApiHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean;
+let extraApiHandler: ExtraApiHandler | null = null;
 
 /**
  * 注册"reload config"回调。约定：
@@ -1673,6 +1677,10 @@ export function setReloadConfigHook(hook: () => void | Promise<void>): void {
   reloadConfigHook = hook;
 }
 
+export function setExtraApiHandler(handler: ExtraApiHandler): void {
+  extraApiHandler = handler;
+}
+
 export function startSetupMode(port: number, options: StartSetupModeOptions = {}): void {
   const router = createUiRouter();
   const server = createServer(router);