chatccc 0.2.57 → 0.2.59

package/README.md

@@ -32,7 +32,7 @@ ChatCCC 把本地 AI 编程工具接入即时通讯软件。你可以在手机
 | 会话形态 | 群聊，一群一会话 | 私聊，一对一 |
 | 消息展示 | CardKit 卡片，流式更新 | 纯文本，增量推送 |
 | `/new` | 自动创建新群并绑定新会话 | 在当前私聊里创建新会话 |
-| 多会话并行 | 直接切换不同群 | 需要在同一私聊内切换上下文 |
+| 多会话并行 | 直接切换不同群 | 支持并行，使用切换指令后未完成的任务会继续在后台进行，但不如飞书直观方便 |
 | 群管理 | 支持创建、重命名、解散、头像 | 不支持 |
 | 接入成本 | 需要配置飞书应用 | 启动后扫码登录 |
 
@@ -158,9 +158,9 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
   "claude": {
     "enabled": false,
     "defaultAgent": true,
-    "model": "claude-sonnet-4-6",
-    "subagentModel": "",
-    "effort": "",
+    "model": "claude-sonnet-4-6",
+    "subagentModel": "",
+    "effort": "",
     "apiKey": "",
     "baseUrl": ""
   },
@@ -189,9 +189,9 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `gitTimeoutSeconds` | `/git` 命令超时时间，默认 180 秒 |
 | `*.enabled` | 是否启用对应 AI Agent |
 | `*.defaultAgent` | `/new` 未指定 Agent 时使用哪个工具 |
-| `cursor.path` / `codex.path` | CLI 可执行文件路径；留空时自动探测或使用 PATH |
-| `claude.model` / `claude.subagentModel` | Claude Code 主模型 / subagent 模型；`subagentModel` 仅在第三方 API 模式下注入 `CLAUDE_CODE_SUBAGENT_MODEL` |
-| `claude.apiKey` / `claude.baseUrl` | 第三方 Anthropic 兼容网关配置；官方 Claude 用户留空 |
+| `cursor.path` / `codex.path` | CLI 可执行文件路径；留空时自动探测或使用 PATH |
+| `claude.model` / `claude.subagentModel` | Claude Code 主模型 / subagent 模型；`subagentModel` 仅在第三方 API 模式下注入 `CLAUDE_CODE_SUBAGENT_MODEL` |
+| `claude.apiKey` / `claude.baseUrl` | 第三方 Anthropic 兼容网关配置；官方 Claude 用户留空 |
 
 > 当前 ChatCCC 以 `bypassPermissions` 模式运行，会跳过 Agent 操作确认。请只在可信环境中使用。
 

package/config.sample.json

@@ -10,14 +10,14 @@
   "port": 18080,
   "gitTimeoutSeconds": 180,
   "allowInterrupt": false,
-  "claude": {
-    "enabled": false,
-    "defaultAgent": true,
-    "model": "claude-sonnet-4-6",
-    "subagentModel": "",
-    "effort": "",
-    "apiKey": "",
-    "baseUrl": ""
+  "claude": {
+    "enabled": false,
+    "defaultAgent": true,
+    "model": "claude-sonnet-4-6",
+    "subagentModel": "",
+    "effort": "",
+    "apiKey": "",
+    "baseUrl": ""
   },
   "cursor": {
     "enabled": false,

package/im-skills/wechat-skill/receive-send-image.md

@@ -0,0 +1,39 @@
+# Receiving & Sending Images (WeChat)
+
+## Receive Images
+
+Images sent to the bot are **automatically downloaded** to `~/.chatccc/images/downloads/` with the `wx_` filename prefix.
+
+The message text you receive will include the downloaded path in the format:
+```
+[图片] C:\Users\<用户名>\.chatccc\images\downloads\wx_<key>.png
+```
+
+You can read the image file at that path to understand what the user sent.
+
+## Send Images
+
+### Script (recommended)
+```bash
+node "{{wechat_send_image_script}}" --path "<absolute image path>" --caption "<optional caption>"
+```
+
+The script reads the current WeChat session's auth token, chat ID, and context token from `~/.chatccc/state/ilink-auth.json`, then sends the image to the most recent chat.
+
+### Direct usage in test scripts
+
+The underlying SDK call is:
+```ts
+import { Client as OpenIlinkWire } from "@openilink/openilink-sdk-node";
+const wire = new OpenIlinkWire(token, { base_url: baseUrl });
+await wire.sendMediaFile(chatId, contextToken, imageBuffer, "filename.png", "caption");
+```
+
+### Rules
+
+- Save or choose a local image file first.
+- Use an absolute local path.
+- Supported formats: .png, .jpg, .jpeg, .webp, .gif, .bmp.
+- Max image size: 10MB (SDK guideline; larger files upload slower).
+- Only send an image when the user asked for one or when it materially helps the answer.
+- **Claw 限制**: 图片发送也计入微信 claw 连发计数，连续 10 条未回复会截断。

package/im-skills/wechat-skill/send-image.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { homedir } from "node:os";
+
+import { Client as OpenIlinkWire } from "@openilink/openilink-sdk-node";
+
+const ILINK_AUTH_PATH = join(homedir(), ".chatccc", "state", "ilink-auth.json");
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const ALLOWED_EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp"]);
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function usage() {
+  console.error(`Usage:
+  node ${basename(process.argv[1])} --path <absolute image path> [--caption <text>]`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const imagePath = args.path;
+  const caption = args.caption || "";
+
+  if (!imagePath) {
+    usage();
+    process.exit(1);
+  }
+
+  const ext = extname(imagePath).toLowerCase();
+  if (!ALLOWED_EXTS.has(ext)) {
+    console.error(`Unsupported image extension: ${ext || "(none)"}`);
+    process.exit(1);
+  }
+
+  const st = statSync(imagePath);
+  if (!st.isFile()) {
+    console.error("Image path is not a file");
+    process.exit(1);
+  }
+  if (st.size > MAX_IMAGE_BYTES) {
+    console.error("Image file exceeds 10MB limit");
+    process.exit(1);
+  }
+
+  if (!existsSync(ILINK_AUTH_PATH)) {
+    console.error(`Auth snapshot not found: ${ILINK_AUTH_PATH}`);
+    console.error("Make sure the WeChat iLink platform is logged in.");
+    process.exit(1);
+  }
+
+  const snap = JSON.parse(readFileSync(ILINK_AUTH_PATH, "utf8"));
+  if (!snap.token || !snap.lastChatId || !snap.contextToken) {
+    console.error("Auth snapshot missing token, lastChatId, or contextToken.");
+    process.exit(1);
+  }
+
+  const imgData = readFileSync(imagePath);
+  const fileName = basename(imagePath);
+
+  const wire = new OpenIlinkWire(snap.token, {
+    base_url: snap.baseUrl,
+  });
+
+  await wire.sendMediaFile(snap.lastChatId, snap.contextToken, imgData, fileName, caption);
+  console.log(JSON.stringify({ ok: true, sentTo: 1 }));
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/im-skills/wechat-skill/skill.md

@@ -0,0 +1,11 @@
+---
+name: wechat-skill
+description: WeChat iLink local skills for sending and receiving images.
+---
+
+Current working directory: {{cwd}}
+
+WeChat images are handled through the iLink SDK. The local server does NOT have HTTP RPC endpoints for WeChat; use the helper scripts below instead.
+
+- **Receive images**: Images sent to the bot are automatically downloaded to `~/.chatccc/images/downloads/` with the filename prefix `wx_`. The message text will include the local path as `[图片] <absolute path>`.
+- **Send images**: Use the send-image helper script — read `{{im_skills_cache_dir}}/wechat-skill/receive-send-image.md`

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "chatccc",
-  "version": "0.2.57",
-  "description": "Feishu bot bridge for Claude Code",
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "./src/index.ts",
-  "bin": {
-    "chatccc": "bin/chatccc.mjs"
-  },
-  "files": [
-    "src/",
-    "bin/",
-    "demo/ilink_echo_probe.ts",
-    "im-skills/",
-    "images/img_readme_*.jpg",
-    "images/img_readme_*.png",
-    "images/avatars/status_*.png",
-    "images/avatars/badges/",
-    "package.json",
-    "README.md",
-    "config.sample.json"
-  ],
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "chatccc": "tsx src/index.ts",
-    "start": "tsx src/index.ts",
-    "demo:bot-test": "tsx demo/bot_test.ts",
-    "demo:bot-test:local": "tsx demo/bot_test.ts --local",
-    "demo:create-group": "tsx src/index.ts",
-    "demo:create-group:local": "tsx src/index.ts --local",
-    "demo:permission-check": "tsx demo/permission_check.ts",
-    "demo:claude-hi": "tsx demo/claude_say_hi.ts",
-    "demo:codex-hi": "tsx demo/codex_say_hi.ts",
-    "demo:ilink-echo": "tsx demo/ilink_echo_probe.ts",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.2.133",
-    "@larksuiteoapi/node-sdk": "^1.59.0",
-    "@openilink/openilink-sdk-node": "^0.6.0",
-    "nodemailer": "^8.0.7",
-    "qrcode-terminal": "^0.12.0",
-    "sharp": "^0.34.5",
-    "tsx": "^4.0.0",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/qrcode-terminal": "^0.12.2",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.0.0",
-    "vitest": "^4.1.5"
-  },
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "chatccc",
+  "version": "0.2.59",
+  "description": "Feishu bot bridge for Claude Code",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "chatccc": "bin/chatccc.mjs"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "demo/ilink_echo_probe.ts",
+    "im-skills/",
+    "images/img_readme_*.jpg",
+    "images/img_readme_*.png",
+    "images/avatars/status_*.png",
+    "images/avatars/badges/",
+    "package.json",
+    "README.md",
+    "config.sample.json"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "chatccc": "tsx src/index.ts",
+    "start": "tsx src/index.ts",
+    "demo:bot-test": "tsx demo/bot_test.ts",
+    "demo:bot-test:local": "tsx demo/bot_test.ts --local",
+    "demo:create-group": "tsx src/index.ts",
+    "demo:create-group:local": "tsx src/index.ts --local",
+    "demo:permission-check": "tsx demo/permission_check.ts",
+    "demo:claude-hi": "tsx demo/claude_say_hi.ts",
+    "demo:codex-hi": "tsx demo/codex_say_hi.ts",
+    "demo:ilink-echo": "tsx demo/ilink_echo_probe.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.2.133",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "@openilink/openilink-sdk-node": "^0.6.0",
+    "nodemailer": "^8.0.7",
+    "qrcode-terminal": "^0.12.0",
+    "sharp": "^0.34.5",
+    "tsx": "^4.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/__tests__/claude-adapter.test.ts

@@ -771,10 +771,10 @@ describe("createClaudeAdapter — env 注入", () => {
     expect(opts.env.ANTHROPIC_BASE_URL).toBe("https://api.deepseek.com/anthropic");
   });
 
-  it("apiKey + baseUrl 都设置 → 同时覆盖", async () => {
-    setupMockCreateSession();
-    const adapter = createClaudeAdapter({
-      model: "",
+  it("apiKey + baseUrl 都设置 → 同时覆盖", async () => {
+    setupMockCreateSession();
+    const adapter = createClaudeAdapter({
+      model: "",
       effort: "",
       isEmpty: (v) => v.trim() === "",
       apiKey: "sk-x",
@@ -784,50 +784,50 @@ describe("createClaudeAdapter — env 注入", () => {
     await adapter.createSession("/cwd");
 
     const opts = sdk.unstable_v2_createSession.mock.calls[0][0];
-    expect(opts.env.ANTHROPIC_API_KEY).toBe("sk-x");
-    expect(opts.env.ANTHROPIC_BASE_URL).toBe("https://gateway.example/anthropic");
-  });
-
-  it("官方 API 模式下 subagentModel 不注入 env，也不覆盖 Claude 登录环境", async () => {
-    setupMockCreateSession();
-    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-from-login";
-    const adapter = createClaudeAdapter({
-      model: "claude-sonnet-4-6",
-      subagentModel: "claude-haiku-4-5-20251001",
-      effort: "",
-      isEmpty: (v) => v.trim() === "",
-      apiKey: "",
-      baseUrl: "",
-    });
-
-    await adapter.createSession("/cwd");
-
-    const opts = sdk.unstable_v2_createSession.mock.calls[0][0];
-    expect(opts).not.toHaveProperty("env");
-  });
-
-  it("第三方 API 模式下 subagentModel 通过 CLAUDE_CODE_SUBAGENT_MODEL 覆盖 Haiku", async () => {
-    setupMockCreateSession();
-    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-from-login";
-    const adapter = createClaudeAdapter({
-      model: "claude-sonnet-4-6",
-      subagentModel: "claude-haiku-4-5-20251001",
-      effort: "",
-      isEmpty: (v) => v.trim() === "",
-      apiKey: "sk-thirdparty",
-      baseUrl: "https://gateway.example/anthropic",
-    });
-
-    await adapter.createSession("/cwd");
-
-    const opts = sdk.unstable_v2_createSession.mock.calls[0][0];
-    expect(opts.model).toBe("claude-sonnet-4-6");
-    expect(opts.env.ANTHROPIC_API_KEY).toBe("sk-thirdparty");
-    expect(opts.env.CLAUDE_CODE_SUBAGENT_MODEL).toBe("claude-haiku-4-5-20251001");
-    expect(opts.env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
-  });
-
-  it("ChatCCC API config is isolated from Claude settings auth/model env", async () => {
+    expect(opts.env.ANTHROPIC_API_KEY).toBe("sk-x");
+    expect(opts.env.ANTHROPIC_BASE_URL).toBe("https://gateway.example/anthropic");
+  });
+
+  it("官方 API 模式下 subagentModel 不注入 env，也不覆盖 Claude 登录环境", async () => {
+    setupMockCreateSession();
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-from-login";
+    const adapter = createClaudeAdapter({
+      model: "claude-sonnet-4-6",
+      subagentModel: "claude-haiku-4-5-20251001",
+      effort: "",
+      isEmpty: (v) => v.trim() === "",
+      apiKey: "",
+      baseUrl: "",
+    });
+
+    await adapter.createSession("/cwd");
+
+    const opts = sdk.unstable_v2_createSession.mock.calls[0][0];
+    expect(opts).not.toHaveProperty("env");
+  });
+
+  it("第三方 API 模式下 subagentModel 通过 CLAUDE_CODE_SUBAGENT_MODEL 覆盖 Haiku", async () => {
+    setupMockCreateSession();
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-from-login";
+    const adapter = createClaudeAdapter({
+      model: "claude-sonnet-4-6",
+      subagentModel: "claude-haiku-4-5-20251001",
+      effort: "",
+      isEmpty: (v) => v.trim() === "",
+      apiKey: "sk-thirdparty",
+      baseUrl: "https://gateway.example/anthropic",
+    });
+
+    await adapter.createSession("/cwd");
+
+    const opts = sdk.unstable_v2_createSession.mock.calls[0][0];
+    expect(opts.model).toBe("claude-sonnet-4-6");
+    expect(opts.env.ANTHROPIC_API_KEY).toBe("sk-thirdparty");
+    expect(opts.env.CLAUDE_CODE_SUBAGENT_MODEL).toBe("claude-haiku-4-5-20251001");
+    expect(opts.env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
+  });
+
+  it("ChatCCC API config is isolated from Claude settings auth/model env", async () => {
     setupMockCreateSession();
     process.env.ANTHROPIC_AUTH_TOKEN = "token-from-claude-settings";
     process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-from-claude-settings";

package/src/__tests__/config-reload.test.ts

@@ -10,9 +10,9 @@ import {
   CHATCCC_PORT,
   CLAUDE_API_KEY,
   CLAUDE_BASE_URL,
-  CLAUDE_EFFORT,
-  CLAUDE_MODEL,
-  CLAUDE_SUBAGENT_MODEL,
+  CLAUDE_EFFORT,
+  CLAUDE_MODEL,
+  CLAUDE_SUBAGENT_MODEL,
   CURSOR_AGENT_ARGS,
   CURSOR_AGENT_COMMAND,
   FEISHU_ENABLED,
@@ -44,10 +44,10 @@ const baseAppConfig: AppConfig = {
   allowInterrupt: false,
   claude: {
     enabled: true,
-    defaultAgent: true,
-    model: "initial-model",
-    subagentModel: "initial-subagent-model",
-    effort: "initial-effort",
+    defaultAgent: true,
+    model: "initial-model",
+    subagentModel: "initial-subagent-model",
+    effort: "initial-effort",
     apiKey: "sk-initial",
     baseUrl: "https://initial.gw/anthropic",
   },
@@ -80,22 +80,22 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
     expect(APP_SECRET).toBe("NEW_APP_SECRET");
   });
 
-  it("更新 Claude 配置（model / subagentModel / effort / apiKey / baseUrl）", () => {
+  it("更新 Claude 配置（model / subagentModel / effort / apiKey / baseUrl）", () => {
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
       claude: {
         enabled: true,
-        defaultAgent: true,
-        model: "claude-sonnet-4-6",
-        subagentModel: "claude-haiku-4-5-20251001",
-        effort: "high",
+        defaultAgent: true,
+        model: "claude-sonnet-4-6",
+        subagentModel: "claude-haiku-4-5-20251001",
+        effort: "high",
         apiKey: "sk-newkey",
         baseUrl: "https://gw2.example/anthropic",
       },
     });
 
-    expect(CLAUDE_MODEL).toBe("claude-sonnet-4-6");
-    expect(CLAUDE_SUBAGENT_MODEL).toBe("claude-haiku-4-5-20251001");
+    expect(CLAUDE_MODEL).toBe("claude-sonnet-4-6");
+    expect(CLAUDE_SUBAGENT_MODEL).toBe("claude-haiku-4-5-20251001");
     expect(CLAUDE_EFFORT).toBe("high");
     expect(CLAUDE_API_KEY).toBe("sk-newkey");
     expect(CLAUDE_BASE_URL).toBe("https://gw2.example/anthropic");

package/src/__tests__/config-sample.test.ts

@@ -6,25 +6,25 @@ import { describe, expect, it } from "vitest";
 describe("config.sample.json", () => {
   it("enables Feishu and WeChat iLink by default", () => {
     const configSamplePath = join(process.cwd(), "config.sample.json");
-    const sample = JSON.parse(readFileSync(configSamplePath, "utf8")) as {
-      platforms?: {
-        feishu?: { enabled?: unknown };
-        ilink?: { enabled?: unknown };
-      };
-      claude?: { model?: unknown; subagentModel?: unknown };
-    };
-
-    expect(sample.platforms?.feishu?.enabled).toBe(true);
-    expect(sample.platforms?.ilink?.enabled).toBe(true);
-  });
-
-  it("uses an Anthropic official main model and leaves subagent override empty by default", () => {
-    const configSamplePath = join(process.cwd(), "config.sample.json");
-    const sample = JSON.parse(readFileSync(configSamplePath, "utf8")) as {
-      claude?: { model?: unknown; subagentModel?: unknown };
-    };
-
-    expect(sample.claude?.model).toBe("claude-sonnet-4-6");
-    expect(sample.claude?.subagentModel).toBe("");
-  });
-});
+    const sample = JSON.parse(readFileSync(configSamplePath, "utf8")) as {
+      platforms?: {
+        feishu?: { enabled?: unknown };
+        ilink?: { enabled?: unknown };
+      };
+      claude?: { model?: unknown; subagentModel?: unknown };
+    };
+
+    expect(sample.platforms?.feishu?.enabled).toBe(true);
+    expect(sample.platforms?.ilink?.enabled).toBe(true);
+  });
+
+  it("uses an Anthropic official main model and leaves subagent override empty by default", () => {
+    const configSamplePath = join(process.cwd(), "config.sample.json");
+    const sample = JSON.parse(readFileSync(configSamplePath, "utf8")) as {
+      claude?: { model?: unknown; subagentModel?: unknown };
+    };
+
+    expect(sample.claude?.model).toBe("claude-sonnet-4-6");
+    expect(sample.claude?.subagentModel).toBe("");
+  });
+});

package/src/__tests__/orchestrator.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { PlatformAdapter } from "../platform-adapter.ts";
+import type { SessionInfo, ToolAdapter } from "../adapters/adapter-interface.ts";
+
+const mockStreamStates = new Map<string, { status: "running" | "done" | "stopped"; finalReply: string }>();
+
+vi.mock("../im-skills.ts", () => ({
+  buildImSkillsPrompt: async () => "",
+  exportSkillSubDocs: async () => {},
+}));
+
+vi.mock("../stream-state.ts", () => ({
+  readStreamState: async (sessionId: string) => {
+    const state = mockStreamStates.get(sessionId);
+    if (!state) return null;
+    return {
+      sessionId,
+      status: state.status,
+      accumulatedContent: "",
+      finalReply: state.finalReply,
+      chunkCount: 0,
+      turnCount: 1,
+      contextTokens: 0,
+      updatedAt: Date.now(),
+      cwd: "F:\\repo",
+      tool: "claude",
+    };
+  },
+  writeStreamState: async (state: { sessionId: string; status: "running" | "done" | "stopped"; finalReply: string }) => {
+    mockStreamStates.set(state.sessionId, {
+      status: state.status,
+      finalReply: state.finalReply,
+    });
+  },
+  createEmptyStreamState: (sessionId: string, cwd: string, tool: string, turnCount: number) => ({
+    sessionId,
+    status: "running" as const,
+    accumulatedContent: "",
+    finalReply: "",
+    chunkCount: 0,
+    turnCount,
+    contextTokens: 0,
+    updatedAt: Date.now(),
+    cwd,
+    tool,
+  }),
+  fixStaleStreamStates: async () => {},
+}));
+
+import { handleCommand } from "../orchestrator.ts";
+import {
+  _clearAdapterCacheForTest,
+  _resetSessionRegistryFileForTest,
+  _resetSessionToolsFileForTest,
+  _setAdapterForToolForTest,
+  _setSessionRegistryFileForTest,
+  _setSessionToolsFileForTest,
+  recordSessionRegistry,
+  resetState,
+} from "../session.ts";
+import { activePrompts, resetBindingState } from "../session-chat-binding.ts";
+
+function mockPlatform(): PlatformAdapter {
+  return {
+    kind: "wechat",
+    sendText: vi.fn(async () => true),
+    sendCard: vi.fn(async () => true),
+    sendRawCard: vi.fn(async () => true),
+    createGroup: vi.fn(async () => "unused-group"),
+    updateChatInfo: vi.fn(async () => {}),
+    getChatInfo: vi.fn(async () => ({ name: "微信会话", description: "" })),
+    disbandChat: vi.fn(async () => {}),
+    setChatAvatar: vi.fn(async () => {}),
+    extractSessionInfo: vi.fn(() => null),
+    cardCreate: vi.fn(async () => "card-id"),
+    cardSend: vi.fn(async () => "message-id"),
+    cardUpdate: vi.fn(async () => {}),
+  };
+}
+
+function mockAdapter(): ToolAdapter {
+  return {
+    displayName: "Claude",
+    sessionDescPrefix: "Claude Session:",
+    createSession: async () => ({ sessionId: "sid-wechat" }),
+    prompt: async function* () {
+      yield {
+        type: "assistant",
+        blocks: [{ type: "text", text: "done" }],
+      };
+    },
+    getSessionInfo: async (sessionId: string): Promise<SessionInfo> => ({
+      sessionId,
+      cwd: "F:\\repo",
+    }),
+    closeSession: async () => {},
+  };
+}
+
+describe("handleCommand WeChat processing ack", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    tempDir = await mkdtemp(join(tmpdir(), "chatccc-orchestrator-"));
+    _setSessionRegistryFileForTest(join(tempDir, "session-registry.json"));
+    _setSessionToolsFileForTest(join(tempDir, "sessions.json"));
+    resetState();
+    resetBindingState();
+    mockStreamStates.clear();
+    _setAdapterForToolForTest("claude", mockAdapter());
+  });
+
+  afterEach(async () => {
+    resetState();
+    resetBindingState();
+    _clearAdapterCacheForTest();
+    _resetSessionRegistryFileForTest();
+    _resetSessionToolsFileForTest();
+    vi.useRealTimers();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("does not send the WeChat processing ack when the session is already running", async () => {
+    const platform = mockPlatform();
+    await recordSessionRegistry({
+      chatId: "wx-chat",
+      sessionId: "sid-wechat",
+      tool: "claude",
+      chatName: "busy-session",
+      running: true,
+    });
+    activePrompts.set("sid-wechat", {
+      controller: new AbortController(),
+      stopped: false,
+      startTime: Date.now(),
+    });
+
+    await handleCommand(platform, "继续说明", "wx-chat", "wx-user", Date.now(), "p2p");
+
+    expect(platform.sendText).not.toHaveBeenCalledWith("wx-chat", "生成中...");
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "wx-chat",
+      "生成中",
+      "该会话正在生成回复中，请等待完成后再发送新消息。",
+      "yellow",
+    );
+  });
+
+  it("sends the WeChat processing ack after the busy check for normal prompts", async () => {
+    const platform = mockPlatform();
+    await recordSessionRegistry({
+      chatId: "wx-chat",
+      sessionId: "sid-wechat",
+      tool: "claude",
+      chatName: "ready-session",
+      running: false,
+    });
+
+    await handleCommand(platform, "继续说明", "wx-chat", "wx-user", Date.now(), "p2p");
+
+    expect(platform.sendText).toHaveBeenCalledWith("wx-chat", "生成中...");
+  });
+});

package/src/__tests__/web-ui.test.ts

@@ -1,10 +1,10 @@
 import { describe, it, expect } from "vitest";
 import {
-  applyClaudeApiMode,
-  chooseStartPath,
-  detectClaudeApiMode,
-  unflattenConfig,
-} from "../web-ui.ts";
+  applyClaudeApiMode,
+  chooseStartPath,
+  detectClaudeApiMode,
+  unflattenConfig,
+} from "../web-ui.ts";
 
 // ---------------------------------------------------------------------------
 // detectClaudeApiMode — 加载已有 config 时如何判定 UI 初始模式
@@ -57,7 +57,7 @@ describe("detectClaudeApiMode", () => {
 //   - mode 未传 默认按 official 兌底（不保留可能误填的密钥）
 // ---------------------------------------------------------------------------
 
-describe("applyClaudeApiMode", () => {
+describe("applyClaudeApiMode", () => {
   it("mode=official 时清空 CLAUDE_API_KEY / CLAUDE_BASE_URL（即使 vars 没传）", () => {
     const out = applyClaudeApiMode({ CHATCCC_APP_ID: "x" }, "official");
     expect(out).toEqual({
@@ -128,23 +128,23 @@ describe("applyClaudeApiMode", () => {
     expect(input).toEqual({ CLAUDE_API_KEY: "sk-x" }); // 原对象未变
     expect(out).not.toBe(input);
   });
-});
-
-describe("unflattenConfig", () => {
-  it("maps Claude subagent model into claude.subagentModel", () => {
-    expect(
-      unflattenConfig({
-        CHATCCC_ANTHROPIC_MODEL: "claude-sonnet-4-6",
-        CHATCCC_ANTHROPIC_SUBAGENT_MODEL: "claude-haiku-4-5-20251001",
-      }),
-    ).toEqual({
-      claude: {
-        model: "claude-sonnet-4-6",
-        subagentModel: "claude-haiku-4-5-20251001",
-      },
-    });
-  });
-});
+});
+
+describe("unflattenConfig", () => {
+  it("maps Claude subagent model into claude.subagentModel", () => {
+    expect(
+      unflattenConfig({
+        CHATCCC_ANTHROPIC_MODEL: "claude-sonnet-4-6",
+        CHATCCC_ANTHROPIC_SUBAGENT_MODEL: "claude-haiku-4-5-20251001",
+      }),
+    ).toEqual({
+      claude: {
+        model: "claude-sonnet-4-6",
+        subagentModel: "claude-haiku-4-5-20251001",
+      },
+    });
+  });
+});
 
 // ---------------------------------------------------------------------------
 // chooseStartPath — /api/start 的路径选择

package/src/__tests__/wechat-platform.test.ts

@@ -1,9 +1,17 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import { buildHelpCard } from "../cards.ts";
-import { createWechatAdapter } from "../wechat-platform.ts";
+import {
+  _flushPendingClawFinalTextForTest,
+  _resetWechatClawStateForTest,
+  createWechatAdapter,
+} from "../wechat-platform.ts";
 
 describe("createWechatAdapter", () => {
+  beforeEach(() => {
+    _resetWechatClawStateForTest();
+  });
+
   it("degrades raw cards to plain text messages", async () => {
     const wire = {
       push: vi.fn(async (_chatId: string, _text: string) => "msg-id"),
@@ -54,4 +62,38 @@ describe("createWechatAdapter", () => {
       "[WECHAT] sendText skipped (claw limit): chatId=wx-chat-limit count=11",
     );
   });
+
+  it("queues final messages after the claw limit until the user wakes the chat", async () => {
+    const wire = {
+      push: vi.fn(async (_chatId: string, _text: string) => "msg-id"),
+      sendText: vi.fn(
+        async (_chatId: string, _text: string, _contextToken?: string) =>
+          "msg-id",
+      ),
+    };
+    const log = vi.fn();
+    const platform = createWechatAdapter({
+      getWire: () => wire,
+      log,
+    });
+    const chatId = "wx-chat-final-limit";
+    const finalText = "done\n━━━ 回答结束 ━━━";
+
+    for (let i = 0; i < 10; i++) {
+      await expect(platform.sendText(chatId, `chunk ${i}`)).resolves.toBe(true);
+    }
+
+    await expect(platform.sendText(chatId, finalText)).resolves.toBe(true);
+    expect(wire.push).toHaveBeenCalledTimes(10);
+    expect(log).toHaveBeenCalledWith(
+      `[WECHAT] final queued (claw limit): chatId=${chatId} count=11 len=${finalText.length}`,
+    );
+
+    await expect(_flushPendingClawFinalTextForTest(chatId, wire, log)).resolves.toBe(true);
+    expect(wire.push).toHaveBeenCalledTimes(11);
+    expect(wire.push).toHaveBeenLastCalledWith(chatId, finalText);
+    expect(log).toHaveBeenCalledWith(
+      `[WECHAT] pending final sent after claw wake: chatId=${chatId} len=${finalText.length}`,
+    );
+  });
 });

package/src/adapters/claude-adapter.ts

@@ -86,33 +86,33 @@ function buildSdkEnv(
   baseUrl: string | undefined,
   subagentModel: string | undefined,
 ): Record<string, string | undefined> | undefined {
-  const apiKeyTrim = (apiKey ?? "").trim();
-  const baseUrlTrim = (baseUrl ?? "").trim();
-  const subagentModelTrim = (subagentModel ?? "").trim();
-  const hasApiOverride = Boolean(apiKeyTrim || baseUrlTrim);
-  if (!hasApiOverride) return undefined;
-
-  const env: Record<string, string | undefined> = { ...process.env };
-  // ChatCCC's third-party Claude API config is authoritative when present.
-  // Remove Claude Code/user settings env that can silently override gateway/auth/model choice.
-  delete env.ANTHROPIC_AUTH_TOKEN;
-  delete env.CLAUDE_CODE_OAUTH_TOKEN;
-  delete env.ANTHROPIC_MODEL;
-  delete env.ANTHROPIC_DEFAULT_OPUS_MODEL;
-  delete env.ANTHROPIC_DEFAULT_SONNET_MODEL;
-  delete env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
-  delete env.CLAUDE_CODE_SUBAGENT_MODEL;
-  delete env.CLAUDE_CODE_EFFORT_LEVEL;
-
-  if (apiKeyTrim) env.ANTHROPIC_API_KEY = apiKeyTrim;
-  if (baseUrlTrim) {
-    env.ANTHROPIC_BASE_URL = baseUrlTrim;
-  } else {
-    delete env.ANTHROPIC_BASE_URL;
-  }
-  if (subagentModelTrim) env.CLAUDE_CODE_SUBAGENT_MODEL = subagentModelTrim;
-  return env;
-}
+  const apiKeyTrim = (apiKey ?? "").trim();
+  const baseUrlTrim = (baseUrl ?? "").trim();
+  const subagentModelTrim = (subagentModel ?? "").trim();
+  const hasApiOverride = Boolean(apiKeyTrim || baseUrlTrim);
+  if (!hasApiOverride) return undefined;
+
+  const env: Record<string, string | undefined> = { ...process.env };
+  // ChatCCC's third-party Claude API config is authoritative when present.
+  // Remove Claude Code/user settings env that can silently override gateway/auth/model choice.
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  delete env.CLAUDE_CODE_OAUTH_TOKEN;
+  delete env.ANTHROPIC_MODEL;
+  delete env.ANTHROPIC_DEFAULT_OPUS_MODEL;
+  delete env.ANTHROPIC_DEFAULT_SONNET_MODEL;
+  delete env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
+  delete env.CLAUDE_CODE_SUBAGENT_MODEL;
+  delete env.CLAUDE_CODE_EFFORT_LEVEL;
+
+  if (apiKeyTrim) env.ANTHROPIC_API_KEY = apiKeyTrim;
+  if (baseUrlTrim) {
+    env.ANTHROPIC_BASE_URL = baseUrlTrim;
+  } else {
+    delete env.ANTHROPIC_BASE_URL;
+  }
+  if (subagentModelTrim) env.CLAUDE_CODE_SUBAGENT_MODEL = subagentModelTrim;
+  return env;
+}
 
 function resolveSettingSources(
   _apiKey: string | undefined,
@@ -291,19 +291,19 @@ class ClaudeAdapter implements ToolAdapter {
       this.baseUrl,
       this.subagentModel,
     );
-    const session = unstable_v2_resumeSession(
-      sessionId,
-      sessionOpts as any,
-    );
-
-    if (signal?.aborted) {
-      session.close();
-      return;
-    }
-    const onAbort = () => { session.close(); };
-    signal?.addEventListener("abort", onAbort, { once: true });
-
-    await session.send(userText);
+    const session = unstable_v2_resumeSession(
+      sessionId,
+      sessionOpts as any,
+    );
+
+    if (signal?.aborted) {
+      session.close();
+      return;
+    }
+    const onAbort = () => { session.close(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    await session.send(userText);
 
     const stream = session.stream();
 

package/src/index.ts

@@ -84,9 +84,9 @@ import {
   updateCardKitCard,
 } from "./cardkit.ts";
 import {
-  MAX_PROCESSED,
-  clearAdapterCache,
-  loadSessionRegistryForBinding,
+  MAX_PROCESSED,
+  clearAdapterCache,
+  loadSessionRegistryForBinding,
   processedMessages,
   rebuildBindingsFromRegistry,
   resetState,
@@ -744,12 +744,12 @@ async function main(): Promise<void> {
   // "保存并启动" 时，web-ui 会调用本回调，把磁盘上刚保存的 config.json
   // 刷进进程内的 export let 常量（live binding 让 CLAUDE_MODEL 等下次创建
   // 会话时自动看到新值）。setup 首次激活走 onActivate 路径，不依赖此 hook。
-  setReloadConfigHook(() => {
-    reloadConfigFromDisk();
-    clearAdapterCache();
-    appendStartupTrace("reload-from-ui: config reloaded", {
-      appIdMask: maskAppId(APP_ID),
-    });
+  setReloadConfigHook(() => {
+    reloadConfigFromDisk();
+    clearAdapterCache();
+    appendStartupTrace("reload-from-ui: config reloaded", {
+      appIdMask: maskAppId(APP_ID),
+    });
   });
   setExtraApiHandler(async (req, res) => {
     return (await handleAgentImageRequest(req, res)) || (await handleAgentFileRequest(req, res));
@@ -769,12 +769,12 @@ async function main(): Promise<void> {
       // 凭证不全：进 setup 向导。注入 onActivate 回调让用户点"保存并启动"
       // 时，原地（同进程）调用 startBotService，复用 setup HTTP server。
       startSetupMode(CHATCCC_PORT, {
-        onActivate: async (httpServer: Server) => {
-          reloadConfigFromDisk();
-          clearAdapterCache();
-          appendStartupTrace("setup-activate: reloaded config from disk", {
-            appIdMaskAfterReload: maskAppId(APP_ID),
-          });
+        onActivate: async (httpServer: Server) => {
+          reloadConfigFromDisk();
+          clearAdapterCache();
+          appendStartupTrace("setup-activate: reloaded config from disk", {
+            appIdMaskAfterReload: maskAppId(APP_ID),
+          });
           try {
             await startBotService({ httpServer, port: CHATCCC_PORT });
             installShutdownHandlers(httpServer);
@@ -818,8 +818,8 @@ async function main(): Promise<void> {
     try {
       await startBotService({ httpServer, port: CHATCCC_PORT });
     } catch (err) {
-      printServiceDidNotStart((err as Error).message);
-      process.exit(1);
+      console.error(`\n[飞书] 启动失败: ${(err as Error).message}`);
+      console.error("[飞书] 微信等其他平台不受影响，将继续启动。\n");
     }
   }
 

package/src/orchestrator.ts

@@ -80,6 +80,14 @@ function isUntitledSessionChatName(name: string): boolean {
   return name === "新会话" || name.startsWith("新会话-");
 }
 
+function shouldSendWechatProcessingAck(
+  platform: PlatformAdapter,
+  textLower: string,
+  chatType: string,
+): boolean {
+  return platform.kind === "wechat" && chatType === "p2p" && !textLower.startsWith("/");
+}
+
 // ---------------------------------------------------------------------------
 // handleCommand — 平台无关的命令分发
 // ---------------------------------------------------------------------------
@@ -988,6 +996,10 @@ export async function handleCommand(
       return;
     }
 
+    if (shouldSendWechatProcessingAck(platform, textLower, chatType)) {
+      await platform.sendText(chatId, "生成中...").catch(() => {});
+    }
+
     try {
       logTrace(tid, "RESUME", { sessionId, tool: descriptionTool });
       await resumeAndPrompt(

package/src/session.ts

@@ -698,6 +698,7 @@ export async function runAgentSession(
 
     // 构建 IM skills prompt（sessionId 方式，无 token）
     const feishuSkillDir = join(PROJECT_ROOT, "im-skills", "feishu-skill");
+    const wechatSkillDir = join(PROJECT_ROOT, "im-skills", "wechat-skill");
     const imSkillsCacheDir = join(USER_DATA_DIR, "im-skills");
     const skillVariables = {
       cwd,
@@ -708,6 +709,7 @@ export async function runAgentSession(
       send_image_script: join(feishuSkillDir, "send-image.mjs"),
       send_file_script: join(feishuSkillDir, "send-file.mjs"),
       download_video_script: join(feishuSkillDir, "download-video.mjs"),
+      wechat_send_image_script: join(wechatSkillDir, "send-image.mjs"),
     };
     var imSkillsPrompt = await buildImSkillsPrompt({ variables: skillVariables });
     await exportSkillSubDocs({ variables: skillVariables }, imSkillsCacheDir);

package/src/web-ui.ts

@@ -270,9 +270,8 @@ async function handleApiCheck(_req: IncomingMessage, res: ServerResponse): Promi
   if (hasConfig) {
     const c = loadConfig();
     const feishuEnabled = c.platforms?.feishu?.enabled !== false; // 默认 true（向后兼容）
-    const ilinkEnabled = c.platforms?.ilink?.enabled !== false;
     const feishuOk = feishuEnabled && Boolean(c.feishu?.appId?.trim() && c.feishu?.appSecret?.trim());
-    hasCreds = feishuOk || ilinkEnabled;
+    hasCreds = feishuOk || !feishuEnabled;
   }
   jsonReply(res, 200, { hasConfig, hasCreds, configPath: CONFIG_FILE });
 }
@@ -1198,9 +1197,14 @@ function renderStep1() {
   var f = c.feishu || {};
   prefillNested('field-CHATCCC_APP_ID', f.appId);
   prefillNested('field-CHATCCC_APP_SECRET', f.appSecret);
-  // 平台开关：按已有 config 回填，缺省飞书和微信都开启
-  var feishuEnabled = c.platforms && c.platforms.feishu ? c.platforms.feishu.enabled !== false : true;
-  var ilinkEnabled = c.platforms && c.platforms.ilink ? c.platforms.ilink.enabled !== false : true;
+  // 平台开关：按已有 config 回填；首次配置（无飞书凭证）时默认关闭飞书、开启微信
+  var hasExistingCreds = Boolean(c.feishu?.appId?.trim() && c.feishu?.appSecret?.trim());
+  var feishuEnabled = hasExistingCreds
+    ? (c.platforms?.feishu?.enabled !== false)
+    : false;
+  var ilinkEnabled = hasExistingCreds
+    ? (c.platforms?.ilink?.enabled !== false)
+    : true;
   state.platformsEnabled = { feishu: feishuEnabled, ilink: ilinkEnabled };
   var feToggle = document.getElementById('platform-enable-feishu');
   if (feToggle) feToggle.checked = feishuEnabled;

package/src/wechat-platform.ts

@@ -10,7 +10,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
 import { homedir } from "node:os";
 
 import {
@@ -19,6 +19,7 @@ import {
   type GetUpdatesResponse,
   type WeixinMessage,
 } from "@openilink/openilink-sdk-node";
+import type { CDNMedia, ImageItem } from "@openilink/openilink-sdk-node";
 
 import type { PlatformAdapter } from "./platform-adapter.ts";
 import { setupFileLogging } from "./shared.ts";
@@ -56,10 +57,17 @@ const { logPath: WECHAT_LOG_PATH } =
   setupFileLogging(ILINK_LOG_DIR, "wechat");
 
 let ilinkWire: OpenIlinkWire | null = null;
+
+/** 获取当前 iLink wire 实例（供外部脚本/测试使用） */
+export function getIlinkWire(): OpenIlinkWire | null {
+  return ilinkWire;
+}
 /** chatId → 最新 context_token */
 const contextTokenMap = new Map<string, string>();
 /** chatId → 用户未回复时已连发消息数 */
 const consecutiveSendCount = new Map<string, number>();
+/** chatId → claw 限制后等待用户唤醒再补发的最终消息 */
+const pendingClawFinalText = new Map<string, string>();
 const textCardMap = new Map<string, { chatId?: string; text: string; lastSentText: string; lastSentAt: number }>();
 let textCardSeq = 0;
 let platformLog: (msg: string) => void = () => {};
@@ -87,6 +95,49 @@ function compressGeneratingText(text: string): string {
   return [...lines.slice(0, 5), "...", ...lines.slice(-5)].join("\n");
 }
 
+async function sendWechatTextRaw(wire: WechatWireSender, chatId: string, text: string): Promise<void> {
+  const contextToken = contextTokenMap.get(chatId);
+  if (contextToken) {
+    await wire.sendText(chatId, text, contextToken);
+  } else {
+    await wire.push(chatId, text);
+  }
+}
+
+async function flushPendingClawFinalText(
+  chatId: string,
+  wire: WechatWireSender | null,
+  log: (msg: string) => void,
+): Promise<boolean> {
+  const text = pendingClawFinalText.get(chatId);
+  if (!text || !wire) return false;
+
+  try {
+    await sendWechatTextRaw(wire, chatId, text);
+    pendingClawFinalText.delete(chatId);
+    consecutiveSendCount.set(chatId, 1);
+    log(`[WECHAT] pending final sent after claw wake: chatId=${chatId} len=${text.length}`);
+    return true;
+  } catch (err) {
+    log(`[WECHAT] pending final send failed: ${(err as Error).message}`);
+    return false;
+  }
+}
+
+export function _resetWechatClawStateForTest(): void {
+  consecutiveSendCount.clear();
+  pendingClawFinalText.clear();
+  contextTokenMap.clear();
+}
+
+export async function _flushPendingClawFinalTextForTest(
+  chatId: string,
+  wire: WechatWireSender | null,
+  log: (msg: string) => void = () => {},
+): Promise<boolean> {
+  return flushPendingClawFinalText(chatId, wire, log);
+}
+
 // ---------------------------------------------------------------------------
 // Snapshot 持久化
 // ---------------------------------------------------------------------------
@@ -160,19 +211,20 @@ export function createWechatAdapter(
         text = text + "\n━━ 后台工作中，由于微信claw机制限制，请唤醒我才能继续发送消息";
       }
 
-      // 超过10条后非最终消息不再发送（claw 限制）
-      if (count > 10 && !isFinal) {
-        log(`[WECHAT] sendText skipped (claw limit): chatId=${chatId} count=${count}`);
-        return false;
+      // 超过10条后不再直接发送。微信端 claw 可能会静默丢弃，即使 iLink 返回 OK。
+      if (count > 10) {
+        if (isFinal) {
+          pendingClawFinalText.set(chatId, text);
+          log(`[WECHAT] final queued (claw limit): chatId=${chatId} count=${count} len=${text.length}`);
+          return true;
+        } else {
+          log(`[WECHAT] sendText skipped (claw limit): chatId=${chatId} count=${count}`);
+          return false;
+        }
       }
 
       try {
-        const contextToken = contextTokenMap.get(chatId);
-        if (contextToken) {
-          await wire.sendText(chatId, text, contextToken);
-        } else {
-          await wire.push(chatId, text);
-        }
+        await sendWechatTextRaw(wire, chatId, text);
         const preview = text.length > 60 ? text.slice(0, 60) + "..." : text;
         log(`[WECHAT] sendText OK: chatId=${chatId} len=${text.length} count=${count} text="${preview}"`);
         return true;
@@ -467,6 +519,44 @@ export async function startWechatPlatform(
   );
 }
 
+const WECHAT_IMAGE_DOWNLOAD_DIR = join(homedir(), ".chatccc", "images", "downloads");
+
+function extFromMimeOrName(mime?: string | null, fileName?: string | null): string {
+  if (mime) {
+    const map: Record<string, string> = {
+      "image/png": ".png",
+      "image/jpeg": ".jpg",
+      "image/webp": ".webp",
+      "image/gif": ".gif",
+      "image/bmp": ".bmp",
+      "image/svg+xml": ".svg",
+    };
+    const key = mime.split(";")[0].trim().toLowerCase();
+    if (map[key]) return map[key];
+  }
+  if (fileName) {
+    const ext = extname(fileName).toLowerCase();
+    if (ext) return ext;
+  }
+  return ".png";
+}
+
+async function downloadWechatImage(imageItem: ImageItem, msgId?: number): Promise<string> {
+  const wire = ilinkWire;
+  if (!wire) throw new Error("iLink wire not available");
+  if (!imageItem.media) throw new Error("image item has no media");
+
+  const data = await wire.downloadMedia(imageItem.media);
+  const mime = (imageItem as Record<string, unknown>).mime_type as string | undefined;
+  const ext = extFromMimeOrName(mime);
+  const key = imageItem.media.aes_key?.slice(0, 16) ?? (msgId?.toString() ?? Date.now().toString());
+  await mkdirSync(WECHAT_IMAGE_DOWNLOAD_DIR, { recursive: true });
+  const localPath = join(WECHAT_IMAGE_DOWNLOAD_DIR, `wx_${key}${ext}`);
+  writeFileSync(localPath, data);
+  platformLog(`图片已下载: ${localPath}`);
+  return localPath;
+}
+
 async function handleWechatMessage(
   message: WeixinMessage,
   handler: MessageHandler,
@@ -492,29 +582,52 @@ async function handleWechatMessage(
   const text = extractText(message).trim();
   const msgTimestamp = message.create_time_ms ?? Date.now();
 
+  // 检测并下载图片
+  const imagePaths: string[] = [];
+  const items = message.item_list;
+  if (items) {
+    for (const item of items) {
+      if (item.image_item?.media) {
+        try {
+          const localPath = await downloadWechatImage(item.image_item, message.message_id);
+          imagePaths.push(localPath);
+        } catch (err) {
+          platformLog(`图片下载失败: ${(err as Error).message}`);
+        }
+      }
+    }
+  }
+
+  // 构建消息文本：文本内容 + 图片路径
+  let fullText = text;
+  if (imagePaths.length > 0) {
+    const imageLines = imagePaths.map((p) => `[图片] ${p}`).join("\n");
+    fullText = fullText ? `${fullText}\n${imageLines}` : imageLines;
+  }
+
+  // 纯图片且无文字时跳过（避免空消息触发会话）
+  if (!fullText.trim()) {
+    platformLog(`跳过纯媒体消息（无文本）: chatId=${chatId}`);
+    return;
+  }
+
   platformLog(
-    `收到消息: chatId=${chatId} text="${text.slice(0, 80)}"`,
+    `收到消息: chatId=${chatId} text="${text.slice(0, 80)}" images=${imagePaths.length}`,
   );
-  appendChatLog(chatId, chatId, text);
+  appendChatLog(chatId, chatId, fullText);
 
   // 用户回复，重置 claw 连发计数
   consecutiveSendCount.set(chatId, 0);
 
-  // 非指令消息：立即发送"生成中..."，让用户知道消息已收到并正在处理
-  if (text && !text.startsWith("/") && ilinkWire) {
-    const ctxToken = contextTokenMap.get(chatId);
-    if (ctxToken) {
-      ilinkWire.sendText(chatId, "生成中...", ctxToken).catch(() => {});
-    } else {
-      ilinkWire.push(chatId, "生成中...").catch(() => {});
-    }
-    // "生成中..." 计为第1条连发消息
-    consecutiveSendCount.set(chatId, 1);
+  // 如果上一轮最终消息因 claw 被暂存，这次用户消息只作为唤醒使用。
+  if (pendingClawFinalText.has(chatId)) {
+    await flushPendingClawFinalText(chatId, ilinkWire, platformLog);
+    return;
   }
 
   // WeChat 中所有会话都视为 p2p，/new 复用 p2p 路径（等同飞书 /newh 效果）
   // 不 await：避免长 prompt 阻塞后续消息处理（如 /cd、/stop 等命令）
-  handler(text, chatId, chatId, msgTimestamp, "p2p").catch((err) => {
+  handler(fullText, chatId, chatId, msgTimestamp, "p2p").catch((err) => {
     platformLog(`消息处理失败: ${(err as Error).stack ?? (err as Error).message}`);
   });
 }