chatccc 0.2.33 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

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

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { getPlatform, setPlatform, getTenantAccessToken, getChatInfo, createGroupChat, updateChatInfo, sendTextReply, sendCardReply, extractSessionInfo, formatDelayNotice, reportPermissionResults, verifyAllPermissions, addReaction, recallMessage, updateCardMessage, setChatAvatar, sendRestartCard } from "../feishu-platform.ts";
+import type { FeishuPlatform } from "../feishu-platform.ts";
+
+const realPlatform = getPlatform();
+
+describe("feishu-platform", () => {
+  it("默认使用真实实现", () => {
+    expect(realPlatform).toBeDefined();
+    expect(typeof realPlatform.getTenantAccessToken).toBe("function");
+    expect(typeof realPlatform.sendTextReply).toBe("function");
+  });
+
+  it("setPlatform 可替换实现，包装函数委托到新实现", async () => {
+    const mock: FeishuPlatform = {
+      getTenantAccessToken: async () => "mock_token",
+      sendTextReply: async () => true,
+      sendCardReply: async () => true,
+      sendImageReply: async () => true,
+      sendFileReply: async () => true,
+      addReaction: async () => {},
+      recallMessage: async () => false,
+      updateCardMessage: async () => true,
+      createGroupChat: async () => "mock_chat",
+      updateChatInfo: async () => {},
+      getChatInfo: async () => ({ name: "x", description: "y" }),
+      setChatAvatar: async () => {},
+      getOrDownloadImage: async () => "/tmp/img.png",
+      verifyAllPermissions: async () => [],
+      reportPermissionResults: realPlatform.reportPermissionResults,
+      extractSessionInfo: realPlatform.extractSessionInfo,
+      extractSessionId: realPlatform.extractSessionId,
+      formatDelayNotice: realPlatform.formatDelayNotice,
+      sendRestartCard: async () => {},
+    };
+
+    setPlatform(mock);
+    try {
+      expect(await getTenantAccessToken()).toBe("mock_token");
+      expect(await sendTextReply("t", "c", "hi")).toBe(true);
+      expect(await createGroupChat("t", "g", [])).toBe("mock_chat");
+      expect(await getChatInfo("t", "mock_chat")).toEqual({ name: "x", description: "y" });
+      const perms = await verifyAllPermissions("t");
+      expect(perms).toEqual([]);
+    } finally {
+      // 恢复到真实实现，避免影响后续测试
+      setPlatform(realPlatform);
+    }
+  });
+
+  it("恢复真实实现后函数正常工作", async () => {
+    setPlatform(realPlatform);
+    expect(getPlatform()).toBe(realPlatform);
+  });
+});

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

@@ -0,0 +1,77 @@
+import { describe, it, expect, afterAll } from "vitest";
+import { unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { SimulatedPlatform, SIM_DEFAULT_CHAT_ID } from "../sim-platform.ts";
+
+const MESSAGES_FILE = join(homedir(), ".chatccc", "sim", "messages.jsonl");
+
+describe("SimulatedPlatform", () => {
+  afterAll(async () => {
+    // 清理测试消息文件
+    try { await unlink(MESSAGES_FILE); } catch { /* ok */ }
+  });
+
+  it("getTenantAccessToken 返回固定 token", async () => {
+    const token = await SimulatedPlatform.getTenantAccessToken();
+    expect(token).toBe("sim_token");
+  });
+
+  it("createGroupChat 创建群并返回 sim_xxx ID", async () => {
+    const chatId = await SimulatedPlatform.createGroupChat("t", "测试群", ["u1"]);
+    expect(chatId).toMatch(/^sim_[0-9a-f]{8}$/);
+    const info = await SimulatedPlatform.getChatInfo("t", chatId);
+    expect(info.name).toBe("测试群");
+  });
+
+  it("getChatInfo 默认群存在", async () => {
+    const info = await SimulatedPlatform.getChatInfo("t", SIM_DEFAULT_CHAT_ID);
+    expect(info.name).toBe("默认模拟会话");
+  });
+
+  it("updateChatInfo 更新群信息", async () => {
+    const chatId = await SimulatedPlatform.createGroupChat("t", "原群名", ["u1"]);
+    await SimulatedPlatform.updateChatInfo("t", chatId, "新群名", "Claude Session: abc123");
+    const info = await SimulatedPlatform.getChatInfo("t", chatId);
+    expect(info.name).toBe("新群名");
+    expect(info.description).toContain("Claude Session");
+  });
+
+  it("sendTextReply 返回 true", async () => {
+    const ok = await SimulatedPlatform.sendTextReply("t", "ch1", "你好");
+    expect(ok).toBe(true);
+  });
+
+  it("sendCardReply 返回 true", async () => {
+    const ok = await SimulatedPlatform.sendCardReply("t", "ch1", "标题", "内容", "blue");
+    expect(ok).toBe(true);
+  });
+
+  it("verifyAllPermissions 全部通过", async () => {
+    const results = await SimulatedPlatform.verifyAllPermissions("t");
+    expect(results.length).toBe(5);
+    expect(results.every((r) => r.ok)).toBe(true);
+  });
+
+  it("addReaction 无异常", async () => {
+    await expect(SimulatedPlatform.addReaction("t", "msg1")).resolves.toBeUndefined();
+  });
+
+  it("setChatAvatar 无异常", async () => {
+    await expect(SimulatedPlatform.setChatAvatar("t", "ch1", "claude", "busy")).resolves.toBeUndefined();
+  });
+
+  it("纯函数 extractSessionInfo 正常工作", () => {
+    const result = SimulatedPlatform.extractSessionInfo("Claude Code Session: a1b2c3d4-e5f6-7890-abcd-ef1234567890");
+    expect(result).toEqual({ sessionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", tool: "claude" });
+  });
+
+  it("纯函数 formatDelayNotice 正常工作", () => {
+    const notice = SimulatedPlatform.formatDelayNotice(Date.now() - 20 * 60 * 1000, "测试消息");
+    expect(notice).toBeDefined();
+    expect(notice).toContain("延迟送达");
+    // 近期消息不触发
+    expect(SimulatedPlatform.formatDelayNotice(Date.now(), "test")).toBeNull();
+  });
+});

package/src/agent-file-rpc.ts

@@ -3,7 +3,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { extname, isAbsolute, resolve } from "node:path";
 import { stat } from "node:fs/promises";
 
-import { getTenantAccessToken, sendFileReply, sendTextReply } from "./feishu-api.ts";
+import { getTenantAccessToken, sendFileReply, sendTextReply } from "./feishu-platform.ts";
 import { ts } from "./config.ts";
 import { logTrace } from "./trace.ts";
 import { readUtf8JsonBody } from "./agent-rpc-body.ts";

package/src/agent-image-rpc.ts

@@ -3,7 +3,7 @@ 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 { getTenantAccessToken, sendImageReply, sendTextReply } from "./feishu-platform.ts";
 import { ts } from "./config.ts";
 import { logTrace } from "./trace.ts";
 import { readUtf8JsonBody } from "./agent-rpc-body.ts";

package/src/config.ts

@@ -454,6 +454,7 @@ export const config: AppConfig = loadConfig();
 // （前提是导入端在函数体内读，不是在模块顶层读）。
 
 export const USE_LOCAL = process.argv.includes("--local");
+export const USE_SIMULATE = process.argv.includes("--simulate");
 export let APP_ID = config.feishu.appId;
 export let APP_SECRET = config.feishu.appSecret;
 export const BASE_URL = "https://open.feishu.cn/open-apis";

package/src/feishu-api.ts

@@ -794,6 +794,33 @@ export async function sendCardReply(
   }
 }
 
+export async function sendRawCard(
+  token: string,
+  chatId: string,
+  cardJson: string
+): Promise<boolean> {
+  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: cardJson }),
+    });
+    const data = (await resp.json().catch(() => ({}))) as { code: number; msg?: string; data?: { message_id?: string } };
+    if (data.code !== 0) {
+      console.error(`[${ts()}] [SEND] raw_card FAIL: chatId=${chatId} code=${data.code} msg="${data.msg ?? ""}"`);
+      return false;
+    }
+    console.log(`[${ts()}] [SEND] raw_card OK: chatId=${chatId} msgId=${data.data?.message_id ?? "N/A"}`);
+    return true;
+  } catch (err) {
+    console.error(`[${ts()}] [SEND] raw_card FAIL: chatId=${chatId} ${(err as Error).message}`);
+    return false;
+  }
+}
+
 // 重启后，向最后有发言的会话发送 "已重启" 卡片（基于 chat_logs 的文件修改时间）
 export async function sendRestartCard(token: string): Promise<void> {
   try {

package/src/feishu-platform.ts

@@ -0,0 +1,134 @@
+/**
+ * feishu-platform.ts — 可替换的飞书 API 实现层
+ *
+ * 默认情况下所有函数直接委托给 feishu-api.ts（真实飞书 API）。
+ * 在 --simulate 模式下通过 setPlatform() 整体替换为 SimulatedPlatform。
+ *
+ * 设计：每个导出函数都是一个"通过 _impl 代理"的包装器，
+ * 消费者不需要感知底层是真实飞书还是模拟实现。
+ */
+
+import * as realApi from "./feishu-api.ts";
+
+// ---------------------------------------------------------------------------
+// 平台接口：覆盖 feishu-api.ts 的所有公开导出函数签名
+// ---------------------------------------------------------------------------
+
+export interface FeishuPlatform {
+  getTenantAccessToken: typeof realApi.getTenantAccessToken;
+  sendTextReply: typeof realApi.sendTextReply;
+  sendCardReply: typeof realApi.sendCardReply;
+  sendRawCard: typeof realApi.sendRawCard;
+  sendImageReply: typeof realApi.sendImageReply;
+  sendFileReply: typeof realApi.sendFileReply;
+  addReaction: typeof realApi.addReaction;
+  recallMessage: typeof realApi.recallMessage;
+  updateCardMessage: typeof realApi.updateCardMessage;
+  createGroupChat: typeof realApi.createGroupChat;
+  updateChatInfo: typeof realApi.updateChatInfo;
+  getChatInfo: typeof realApi.getChatInfo;
+  setChatAvatar: typeof realApi.setChatAvatar;
+  getOrDownloadImage: typeof realApi.getOrDownloadImage;
+  verifyAllPermissions: typeof realApi.verifyAllPermissions;
+  reportPermissionResults: typeof realApi.reportPermissionResults;
+  extractSessionInfo: typeof realApi.extractSessionInfo;
+  extractSessionId: typeof realApi.extractSessionId;
+  formatDelayNotice: typeof realApi.formatDelayNotice;
+  sendRestartCard: typeof realApi.sendRestartCard;
+}
+
+let _impl: FeishuPlatform = realApi;
+
+/** 替换当前平台实现（模拟模式入口） */
+export function setPlatform(impl: FeishuPlatform): void {
+  _impl = impl;
+}
+
+/** 获取当前平台实现（仅供诊断/测试） */
+export function getPlatform(): FeishuPlatform {
+  return _impl;
+}
+
+// ---------------------------------------------------------------------------
+// 包装器：每个函数直接委托到 _impl，签名与原函数完全一致
+// ---------------------------------------------------------------------------
+
+export function getTenantAccessToken(): ReturnType<typeof realApi.getTenantAccessToken> {
+  return _impl.getTenantAccessToken();
+}
+
+export function sendTextReply(...args: Parameters<typeof realApi.sendTextReply>): ReturnType<typeof realApi.sendTextReply> {
+  return _impl.sendTextReply(...args);
+}
+
+export function sendCardReply(...args: Parameters<typeof realApi.sendCardReply>): ReturnType<typeof realApi.sendCardReply> {
+  return _impl.sendCardReply(...args);
+}
+
+export function sendRawCard(...args: Parameters<typeof realApi.sendRawCard>): ReturnType<typeof realApi.sendRawCard> {
+  return _impl.sendRawCard(...args);
+}
+
+export function sendImageReply(...args: Parameters<typeof realApi.sendImageReply>): ReturnType<typeof realApi.sendImageReply> {
+  return _impl.sendImageReply(...args);
+}
+
+export function sendFileReply(...args: Parameters<typeof realApi.sendFileReply>): ReturnType<typeof realApi.sendFileReply> {
+  return _impl.sendFileReply(...args);
+}
+
+export function addReaction(...args: Parameters<typeof realApi.addReaction>): ReturnType<typeof realApi.addReaction> {
+  return _impl.addReaction(...args);
+}
+
+export function recallMessage(...args: Parameters<typeof realApi.recallMessage>): ReturnType<typeof realApi.recallMessage> {
+  return _impl.recallMessage(...args);
+}
+
+export function updateCardMessage(...args: Parameters<typeof realApi.updateCardMessage>): ReturnType<typeof realApi.updateCardMessage> {
+  return _impl.updateCardMessage(...args);
+}
+
+export function createGroupChat(...args: Parameters<typeof realApi.createGroupChat>): ReturnType<typeof realApi.createGroupChat> {
+  return _impl.createGroupChat(...args);
+}
+
+export function updateChatInfo(...args: Parameters<typeof realApi.updateChatInfo>): ReturnType<typeof realApi.updateChatInfo> {
+  return _impl.updateChatInfo(...args);
+}
+
+export function getChatInfo(...args: Parameters<typeof realApi.getChatInfo>): ReturnType<typeof realApi.getChatInfo> {
+  return _impl.getChatInfo(...args);
+}
+
+export function setChatAvatar(...args: Parameters<typeof realApi.setChatAvatar>): ReturnType<typeof realApi.setChatAvatar> {
+  return _impl.setChatAvatar(...args);
+}
+
+export function getOrDownloadImage(...args: Parameters<typeof realApi.getOrDownloadImage>): ReturnType<typeof realApi.getOrDownloadImage> {
+  return _impl.getOrDownloadImage(...args);
+}
+
+export function verifyAllPermissions(...args: Parameters<typeof realApi.verifyAllPermissions>): ReturnType<typeof realApi.verifyAllPermissions> {
+  return _impl.verifyAllPermissions(...args);
+}
+
+export function reportPermissionResults(...args: Parameters<typeof realApi.reportPermissionResults>): ReturnType<typeof realApi.reportPermissionResults> {
+  return _impl.reportPermissionResults(...args);
+}
+
+export function extractSessionInfo(...args: Parameters<typeof realApi.extractSessionInfo>): ReturnType<typeof realApi.extractSessionInfo> {
+  return _impl.extractSessionInfo(...args);
+}
+
+export function extractSessionId(...args: Parameters<typeof realApi.extractSessionId>): ReturnType<typeof realApi.extractSessionId> {
+  return _impl.extractSessionId(...args);
+}
+
+export function formatDelayNotice(...args: Parameters<typeof realApi.formatDelayNotice>): ReturnType<typeof realApi.formatDelayNotice> {
+  return _impl.formatDelayNotice(...args);
+}
+
+export function sendRestartCard(...args: Parameters<typeof realApi.sendRestartCard>): ReturnType<typeof realApi.sendRestartCard> {
+  return _impl.sendRestartCard(...args);
+}

package/src/index.ts

@@ -24,7 +24,7 @@
 
 import { spawn } from "node:child_process";
 import { readdir, stat } from "node:fs/promises";
-import { createServer, type Server } from "node:http";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { resolve, dirname } from "node:path";
 
 import { WSClient, EventDispatcher } from "@larksuiteoapi/node-sdk";
@@ -47,6 +47,7 @@ import {
   PID_FILE,
   PROJECT_ROOT,
   USE_LOCAL,
+  USE_SIMULATE,
   appendChatLog,
   explainMissingFeishuCredentialsAndExit,
   fileLog,
@@ -71,6 +72,7 @@ import {
   getTenantAccessToken,
   recallMessage,
   sendCardReply,
+  sendRawCard,
   sendTextReply,
   setChatAvatar,
   updateCardMessage,
@@ -79,12 +81,14 @@ import {
   sendRestartCard,
   verifyAllPermissions,
   reportPermissionResults,
-} from "./feishu-api.ts";
+  setPlatform,
+} from "./feishu-platform.ts";
 import { buildHelpCard, buildStatusCard, buildProgressCard, buildCdContent, buildCdCard, buildSessionsCard } from "./cards.ts";
 import { updateCardKitCard } from "./cardkit.ts";
 import { handleAgentImageRequest } from "./agent-image-rpc.ts";
 import { handleAgentFileRequest } from "./agent-file-rpc.ts";
 import { handleAgentGrantsRequest } from "./agent-grants-rpc.ts";
+import { SimulatedPlatform, SIM_DEFAULT_CHAT_ID } from "./sim-platform.ts";
 import { formatGitResult, gitResultHeaderTemplate, runGitCommand } from "./git-command.ts";
 import {
   MAX_PROCESSED,
@@ -251,6 +255,53 @@ function parseCardAction(data: unknown): CardActionResult | null {
 
 let broadcastToRelay: (data: unknown) => void = () => {};
 
+// ---------------------------------------------------------------------------
+// Simulate mode: inject message via HTTP
+// ---------------------------------------------------------------------------
+
+async function handleSimInjectMessage(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname !== "/api/sim/inject-message") return false;
+  if (req.method !== "POST") {
+    res.writeHead(405, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: "Method not allowed, use POST" }));
+    return true;
+  }
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) { chunks.push(Buffer.from(chunk)); }
+  const body = Buffer.concat(chunks).toString("utf-8");
+  let parsed: { text?: string; chat_id?: string; open_id?: string; chat_type?: string };
+  try { parsed = JSON.parse(body); } catch {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: "Invalid JSON body" }));
+    return true;
+  }
+
+  const text = parsed.text;
+  if (!text) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: "Missing 'text' field" }));
+    return true;
+  }
+
+  const chatId = parsed.chat_id || SIM_DEFAULT_CHAT_ID;
+  const openId = parsed.open_id || "sim_user_001";
+  const chatType = parsed.chat_type || "group";
+
+  console.log(`[${ts()}] [SIM:INJECT] chat=${chatId} text="${text.slice(0, 80)}"`);
+  appendChatLog(chatId, openId, text);
+
+  // Fire and forget: process command, respond 202 immediately
+  handleCommand(text, chatId, openId, Date.now(), chatType).catch((err) =>
+    console.error(`[${ts()}] [SIM:INJECT] handleCommand error: ${(err as Error).message}`)
+  );
+
+  res.writeHead(202, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify({ ok: true, chat_id: chatId }));
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Command handler
 // ---------------------------------------------------------------------------
@@ -351,17 +402,9 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       // /cd 无参数：展示卡片（含最近使用路径按钮）
       const recentDirs = await getRecentDirs();
       const card = buildCdCard(targetDir, withStats, recentDirs, sessionCwd);
-      const resp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${cdToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
-      });
-      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 });
+      const ok = await sendRawCard(cdToken, chatId, card);
+      console.log(`[${ts()}] [CD] card sent, ok=${ok}, recentDirs=${recentDirs.length}`);
+      logTrace(tid, "DONE", { outcome: "cd_card", ok });
     } else {
       // /cd <path>：切换目录，发送文本卡片
       const content = buildCdContent(targetDir, withStats, isUpdate, sessionCwd);
@@ -537,17 +580,9 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           statusText.push(`**上下文 Token 数:** ~${status.lastContextTokens.toLocaleString()}`);
         }
         const card = buildStatusCard(statusText.join("\n"), isActive ? "blue" : "green");
-        const statusResp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${freshToken}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
-        });
-        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 });
+        const ok = await sendRawCard(freshToken, chatId, card);
+        console.log(`[${ts()}] [STATUS] card sent, ok=${ok}`);
+        logTrace(tid, "DONE", { outcome: "status", ok });
         return;
       }
 
@@ -564,17 +599,9 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           tool: s.tool,
         }));
         const card = buildSessionsCard(cardData);
-        const sessionsResp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${freshToken}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({ receive_id: chatId, msg_type: "interactive", content: card }),
-        });
-        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 });
+        const ok = await sendRawCard(freshToken, chatId, card);
+        console.log(`[${ts()}] [SESSIONS] card sent, ok=${ok}, count=${allSessions.length}`);
+        logTrace(tid, "DONE", { outcome: "sessions", ok, count: allSessions.length });
         return;
       }
 
@@ -757,21 +784,13 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
   logTrace(tid, "SEND", { method: "help_card", chatId });
   const replyToken = await getTenantAccessToken();
   const card = buildHelpCard(text);
-  const helpResp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${replyToken}`,
-      "Content-Type": "application/json",
-    },
-    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 });
+  const ok = await sendRawCard(replyToken, chatId, card);
+  if (!ok) {
+    console.error(`[${ts()}] [SEND] help_card FAIL: chatId=${chatId}`);
+    logTrace(tid, "DONE", { outcome: "help_card_fail" });
   } 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 });
+    console.log(`[${ts()}] [SEND] help_card OK: chatId=${chatId}`);
+    logTrace(tid, "DONE", { outcome: "help_card_sent" });
   }
 }
 
@@ -1053,6 +1072,49 @@ async function main(): Promise<void> {
   // server.close）——只负责诊断与默认致命退出，不替代清理逻辑。
   installCrashLogging({ flush: () => fileLog.flush() });
 
+  // 模拟模式：独立端口 18079，不与 SDK 实例冲突，不走飞书凭证/权限/WSClient
+  if (USE_SIMULATE) {
+    const SIM_PORT = 18079;
+    console.log("\n[Simulate] 模拟飞书环境模式");
+    setPlatform(SimulatedPlatform);
+    console.log("  已切换到 SimulatedPlatform（零飞书依赖）");
+    appendStartupTrace("main: simulate mode", { port: SIM_PORT });
+
+    setExtraApiHandler(async (req, res) => {
+      const injected = await handleSimInjectMessage(req, res);
+      if (injected) return true;
+      return (await handleAgentGrantsRequest(req, res)) || (await handleAgentImageRequest(req, res)) || (await handleAgentFileRequest(req, res));
+    });
+
+    const simServer = createServer(createUiRouter());
+    await new Promise<void>((resolveListen, rejectListen) => {
+      const onError = (err: NodeJS.ErrnoException): void => {
+        simServer.removeListener("listening", onListening);
+        rejectListen(err);
+      };
+      const onListening = (): void => {
+        simServer.removeListener("error", onError);
+        resolveListen();
+      };
+      simServer.once("error", onError);
+      simServer.once("listening", onListening);
+      simServer.listen(SIM_PORT, "127.0.0.1");
+    }).catch((err: NodeJS.ErrnoException) => {
+      console.error(`\n[启动] 监听失败：端口 ${SIM_PORT}（${err.code ?? "?"} — ${err.message}）`);
+      process.exit(1);
+    });
+
+    console.log(`\n${"=".repeat(60)}`);
+    console.log(`  ChatCCC — 模拟飞书环境模式`);
+    console.log(`${"=".repeat(60)}`);
+    console.log(`  发送消息: POST http://127.0.0.1:${SIM_PORT}/api/sim/inject-message`);
+    console.log(`  消息日志: ~/.chatccc/sim/messages.jsonl`);
+    console.log(`${"=".repeat(60)}\n`);
+
+    installShutdownHandlers(simServer);
+    return;
+  }
+
   if (Number.isNaN(CHATCCC_PORT) || CHATCCC_PORT < 1 || CHATCCC_PORT > 65535) {
     console.error("\n[启动] 预检失败: config.json 的 port 字段不是有效端口号（1–65535）。");
     console.error(`  当前配置: ${CHATCCC_PORT}`);

package/src/session.ts

@@ -25,7 +25,7 @@ import {
   sendCardKitMessage,
   updateCardKitCard,
 } from "./cardkit.ts";
-import { sendTextReply, setChatAvatar } from "./feishu-api.ts";
+import { sendTextReply, setChatAvatar } from "./feishu-platform.ts";
 import { logTrace } from "./trace.ts";
 import type { UnifiedBlock } from "./adapters/adapter-interface.ts";
 import type { ToolAdapter } from "./adapters/adapter-interface.ts";

package/src/sim-platform.ts

@@ -0,0 +1,224 @@
+/**
+ * sim-platform.ts — SimulatedPlatform: 零飞书依赖的本地模拟实现
+ *
+ * 所有飞书 API 调用都由本地逻辑替代：
+ * - 消息写入本地 JSONL（~/.chatccc/sim/messages.jsonl）
+ * - 群聊信息存在内存 Map 中
+ * - createGroupChat 生成 "sim_<uuid>" 格式的 chat_id
+ *
+ * 纯函数（extractSessionInfo / formatDelayNotice / reportPermissionResults）
+ * 直接从 feishu-api.ts re-export，不重新实现。
+ */
+
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  extractSessionInfo as realExtractSessionInfo,
+  extractSessionId as realExtractSessionId,
+  formatDelayNotice as realFormatDelayNotice,
+  reportPermissionResults as realReportPermissionResults,
+} from "./feishu-api.ts";
+import type { FeishuPlatform } from "./feishu-platform.ts";
+
+// ---------------------------------------------------------------------------
+// 持久化路径
+// ---------------------------------------------------------------------------
+
+const SIM_DIR = join(homedir(), ".chatccc", "sim");
+const MESSAGES_FILE = join(SIM_DIR, "messages.jsonl");
+
+// ---------------------------------------------------------------------------
+// 内存状态
+// ---------------------------------------------------------------------------
+
+interface SimChat {
+  name: string;
+  description: string;
+  members: string[];
+}
+
+const chats = new Map<string, SimChat>();
+
+// 默认模拟群：用户注入消息时如果不指定 chat_id，就用这个
+const DEFAULT_CHAT_ID = "sim_default";
+chats.set(DEFAULT_CHAT_ID, {
+  name: "默认模拟会话",
+  description: "",
+  members: ["sim_user_001"],
+});
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+function ts(): string {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+async function appendJsonl(line: Record<string, unknown>): Promise<void> {
+  await mkdir(SIM_DIR, { recursive: true });
+  await appendFile(MESSAGES_FILE, JSON.stringify(line) + "\n", "utf-8");
+}
+
+/** 模拟 user_id 转 open_id 的映射 */
+function resolveOpenId(userIds: string[]): string {
+  return userIds[0] ?? "sim_user_001";
+}
+
+// ---------------------------------------------------------------------------
+// SimulatedPlatform
+// ---------------------------------------------------------------------------
+
+export const SimulatedPlatform: FeishuPlatform = {
+  // ---- 认证 ----
+  async getTenantAccessToken() {
+    return "sim_token";
+  },
+
+  // ---- 消息发送：全部写本地 JSONL ----
+  async sendTextReply(_token, chatId, text) {
+    console.log(`[${ts()}] [SIM:SEND] text → ${chatId}: ${text.slice(0, 80)}`);
+    await appendJsonl({
+      direction: "send",
+      chat_id: chatId,
+      msg_type: "text",
+      content: text,
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  async sendCardReply(_token, chatId, title, content, _template) {
+    console.log(`[${ts()}] [SIM:SEND] card → ${chatId}: [${title}]`);
+    const text = `**[${title}]**\n${content}`;
+    await appendJsonl({
+      direction: "send",
+      chat_id: chatId,
+      msg_type: "card",
+      header: title,
+      content: content,
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  async sendImageReply(_token, chatId, imagePath) {
+    console.log(`[${ts()}] [SIM:SEND] image → ${chatId}: ${imagePath}`);
+    await appendJsonl({
+      direction: "send",
+      chat_id: chatId,
+      msg_type: "image",
+      image_path: imagePath,
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  async sendFileReply(_token, chatId, filePath) {
+    console.log(`[${ts()}] [SIM:SEND] file → ${chatId}: ${filePath}`);
+    await appendJsonl({
+      direction: "send",
+      chat_id: chatId,
+      msg_type: "file",
+      file_path: filePath,
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  async sendRawCard(_token, chatId, cardJson) {
+    console.log(`[${ts()}] [SIM:SEND] raw_card → ${chatId}: ${cardJson.slice(0, 80)}...`);
+    await appendJsonl({
+      direction: "send",
+      chat_id: chatId,
+      msg_type: "raw_card",
+      card_json_preview: cardJson.slice(0, 500),
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  // ---- 消息管理 ----
+  async addReaction(_token, _messageId, _emojiType) {
+    // 模拟模式不需要表情回应
+  },
+
+  async recallMessage(_token, _messageId) {
+    return true; // 假装撤回成功
+  },
+
+  async updateCardMessage(_token, _messageId, content) {
+    // 模拟模式：写更新记录到 JSONL
+    await appendJsonl({
+      type: "card_update",
+      message_id: _messageId,
+      content_preview: content.slice(0, 200),
+      timestamp: Date.now(),
+    });
+    return true;
+  },
+
+  // ---- 群聊管理 ----
+  async createGroupChat(_token, name, userIds) {
+    const chatId = `sim_${randomUUID().slice(0, 8)}`;
+    chats.set(chatId, { name, description: "Creating...", members: userIds });
+    console.log(`[${ts()}] [SIM:CHAT] created: ${chatId} name="${name}" members=${userIds.length}`);
+    return chatId;
+  },
+
+  async updateChatInfo(_token, chatId, name, description) {
+    const existing = chats.get(chatId);
+    if (existing) {
+      existing.name = name;
+      existing.description = description;
+    } else {
+      chats.set(chatId, { name, description, members: ["sim_user_001"] });
+    }
+    console.log(`[${ts()}] [SIM:CHAT] updated: ${chatId} name="${name}"`);
+  },
+
+  async getChatInfo(_token, chatId) {
+    const chat = chats.get(chatId);
+    if (!chat) throw new Error(`[99999] chat not found: ${chatId}`);
+    return { name: chat.name, description: chat.description };
+  },
+
+  // ---- 头像 ----
+  async setChatAvatar(_token, _chatId, _tool, _status) {
+    // 模拟模式不需要头像
+  },
+
+  // ---- 图片下载 ----
+  async getOrDownloadImage(_token, _messageId, fileKey) {
+    // 模拟模式下图片不需要从飞书下载，返回占位路径
+    return join(SIM_DIR, "images", fileKey);
+  },
+
+  // ---- 权限验证 ----
+  async verifyAllPermissions(_token) {
+    return [
+      { scope: "im:chat", description: "模拟", ok: true, detail: "模拟模式跳过" },
+      { scope: "im:message:send_as_bot", description: "模拟", ok: true, detail: "模拟模式跳过" },
+      { scope: "im:message:reaction", description: "模拟", ok: true, detail: "模拟模式跳过" },
+      { scope: "im:message", description: "模拟", ok: true, detail: "模拟模式跳过" },
+      { scope: "cardkit:card", description: "模拟", ok: true, detail: "模拟模式跳过" },
+    ];
+  },
+
+  // ---- 纯函数：直接从真实实现 re-export ----
+  extractSessionInfo: realExtractSessionInfo,
+  extractSessionId: realExtractSessionId,
+  formatDelayNotice: realFormatDelayNotice,
+  reportPermissionResults: realReportPermissionResults,
+
+  // ---- 其他 ----
+  async sendRestartCard(_token) {
+    // 模拟模式不需要重启通知
+  },
+};
+
+/** 模拟模式下的默认 chat_id */
+export const SIM_DEFAULT_CHAT_ID = DEFAULT_CHAT_ID;