chatccc 0.2.50 → 0.2.51

package/package.json

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

package/src/__tests__/session.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -29,6 +29,8 @@ import {
   saveSessionTool,
   accumulateBlockContent,
   pickFinalReply,
+  switchChatBinding,
+  rebuildBindingsFromRegistry,
   UNKNOWN_MODEL_PLACEHOLDER,
   _setSessionRegistryFileForTest,
   _resetSessionRegistryFileForTest,
@@ -45,6 +47,8 @@ import {
   getLastActiveChat,
   pickDisplayChat,
   resetBindingState,
+  getChatsForSession,
+  displayCards,
 } from "../session-chat-binding.ts";
 import type { AccumulatorState } from "../session.ts";
 import type { ToolAdapter, UnifiedBlock, SessionInfo } from "../adapters/adapter-interface.ts";
@@ -133,6 +137,94 @@ describe("resetState", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// rebuildBindingsFromRegistry — SDK 重连/启动时只重建只读映射,不动运行时状态
+//
+// 这是 onReady/onReconnected 应当调用的函数(替代之前错误调用的 resetState)。
+// 关键不变量:重建映射后,原有的 activePrompts、sessionInfoMap、displayCards、
+// processedMessages 全部保留——SDK 重连不应当影响后台 prompt 的执行。
+// ---------------------------------------------------------------------------
+
+describe("rebuildBindingsFromRegistry", () => {
+  let registryFile = "";
+
+  beforeEach(async () => {
+    chatSessionMap.clear();
+    sessionInfoMap.clear();
+    activePrompts.clear();
+    processedMessages.clear();
+    resetBindingState();
+    const dir = await mkdtemp(join(tmpdir(), "chatccc-rebuild-"));
+    registryFile = join(dir, "session-registry.json");
+    _setSessionRegistryFileForTest(registryFile);
+  });
+
+  afterEach(async () => {
+    _resetSessionRegistryFileForTest();
+    if (registryFile) {
+      await rm(dirname(registryFile), { recursive: true, force: true });
+    }
+  });
+
+  it("不清空 activePrompts:后台 prompt 在 SDK 重连后必须继续被识别为活跃", async () => {
+    // 模拟有一个后台 prompt 正在跑
+    const controller = new AbortController();
+    activePrompts.set("session-running", { controller, stopped: false, startTime: Date.now() });
+    await recordSessionRegistry({
+      chatId: "chat-A",
+      sessionId: "session-running",
+      tool: "claude",
+      updatedAt: 100,
+    });
+
+    await rebuildBindingsFromRegistry();
+
+    // 关键不变量:重连后 activePrompts 必须保留,否则后台 generator 会变孤儿
+    expect(activePrompts.has("session-running")).toBe(true);
+    expect(activePrompts.get("session-running")?.controller).toBe(controller);
+  });
+
+  it("不清空 sessionInfoMap:轮数计数在重连后保留", async () => {
+    sessionInfoMap.set("chat-A", {
+      sessionId: "sid-A", turnCount: 7, lastContextTokens: 50000,
+      startTime: 1000, tool: "claude",
+    });
+    await recordSessionRegistry({
+      chatId: "chat-A", sessionId: "sid-A", tool: "claude", updatedAt: 100,
+    });
+
+    await rebuildBindingsFromRegistry();
+
+    expect(sessionInfoMap.get("chat-A")?.turnCount).toBe(7);
+    expect(sessionInfoMap.get("chat-A")?.lastContextTokens).toBe(50000);
+  });
+
+  it("不清空 processedMessages:重连后 SDK 重推消息仍能去重", async () => {
+    processedMessages.add("msg-id-1");
+    processedMessages.add("msg-id-2");
+
+    await rebuildBindingsFromRegistry();
+
+    expect(processedMessages.has("msg-id-1")).toBe(true);
+    expect(processedMessages.has("msg-id-2")).toBe(true);
+  });
+
+  it("从 registry 重建 sessionId → chatId 映射(沿用 rebuildSessionChatsFromRegistry 行为)", async () => {
+    await recordSessionRegistry({
+      chatId: "chat-A", sessionId: "sid-X", tool: "claude", updatedAt: 100,
+    });
+    await recordSessionRegistry({
+      chatId: "chat-B", sessionId: "sid-X", tool: "claude", updatedAt: 200,
+    });
+
+    await rebuildBindingsFromRegistry();
+
+    // 同一 sessionId 被两个 chatId 共享时,两个都应在映射中
+    bindChatToSession("sid-X", "chat-A"); // 验证幂等(再次调用不会出错)
+    expect(true).toBe(true); // 真正的断言由 sessionChatsMap 通过 pickDisplayChat 等间接验证
+  });
+});
+
 describe("getSessionStatus", () => {
   beforeEach(() => {
     chatSessionMap.clear();
@@ -752,3 +844,218 @@ describe("unbindChatFromSession 同步清理 lastActiveChatMap", () => {
     expect(getLastActiveChat("sid-A")).toBe("chat_X");
   });
 });
+
+// ---------------------------------------------------------------------------
+// switchChatBinding — 事务式 chat→session 切换（/newh、/session N 复用）
+//
+// 关键不变量：
+//   1. p2p chatType 不调 updateChatInfo（私聊飞书 API 会直接抛错）
+//   2. updateChatInfo 失败时,内存绑定/sessionInfoMap/displayCards 完全不动,
+//      且 description 还是旧值,下次消息按旧 sessionId 路由不会乱
+//   3. 成功时按 unbind 旧 → bind 新 → recordLastActiveChat 顺序原子切换
+//   4. 持久化 registry + sessions.json
+// ---------------------------------------------------------------------------
+
+describe("switchChatBinding", () => {
+  let registryFile = "";
+  let sessionsFile = "";
+
+  beforeEach(async () => {
+    resetBindingState();
+    sessionInfoMap.clear();
+    const dir = await mkdtemp(join(tmpdir(), "chatccc-switch-binding-"));
+    registryFile = join(dir, "session-registry.json");
+    sessionsFile = join(dir, "sessions.json");
+    _setSessionRegistryFileForTest(registryFile);
+    _setSessionToolsFileForTest(sessionsFile);
+  });
+
+  afterEach(async () => {
+    _resetSessionRegistryFileForTest();
+    _resetSessionToolsFileForTest();
+    if (registryFile) {
+      await rm(dirname(registryFile), { recursive: true, force: true });
+    }
+  });
+
+  it("群聊场景：API 成功后内存切换 + 持久化", async () => {
+    const calls: Array<{ chatId: string; name: string; desc: string }> = [];
+    const updateChatInfoFn = async (chatId: string, name: string, desc: string) => {
+      calls.push({ chatId, name, desc });
+    };
+
+    bindChatToSession("old-sid", "chat-1");
+    sessionInfoMap.set("chat-1", {
+      sessionId: "old-sid", turnCount: 5, lastContextTokens: 100,
+      startTime: 0, tool: "claude",
+    });
+    displayCards.set("chat-1", {
+      cardId: "c1", sequence: 1, cardBusy: false,
+      cardCreatedAt: 0, lastSentContent: "", streamErrorNotified: false,
+    });
+
+    const result = await switchChatBinding({
+      chatId: "chat-1",
+      chatType: "group",
+      oldSessionId: "old-sid",
+      newSessionId: "new-sid",
+      tool: "claude",
+      chatName: "新会话-test",
+      newDescription: "Claude Code Session: new-sid",
+      updateChatInfoFn,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual({
+      chatId: "chat-1",
+      name: "新会话-test",
+      desc: "Claude Code Session: new-sid",
+    });
+    // 旧 session 已解绑,新 session 已绑
+    expect(getChatsForSession("old-sid")).toEqual([]);
+    expect(getChatsForSession("new-sid")).toEqual(["chat-1"]);
+    // displayCards 已清
+    expect(displayCards.has("chat-1")).toBe(false);
+    // sessionInfoMap 指向新 sessionId
+    expect(sessionInfoMap.get("chat-1")?.sessionId).toBe("new-sid");
+    // lastActiveChat 指向当前 chat
+    expect(getLastActiveChat("new-sid")).toBe("chat-1");
+  });
+
+  it("私聊场景：完全跳过 updateChatInfo,仍完成内存切换", async () => {
+    let called = false;
+    const updateChatInfoFn = async () => {
+      called = true;
+      throw new Error("p2p chat API would fail");
+    };
+
+    const result = await switchChatBinding({
+      chatId: "p2p-chat",
+      chatType: "p2p",
+      oldSessionId: null,
+      newSessionId: "new-sid-p2p",
+      tool: "claude",
+      chatName: "新会话-p2p",
+      newDescription: "Claude Code Session: new-sid-p2p",
+      updateChatInfoFn,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(called).toBe(false); // 私聊跳过 API 调用
+    expect(getChatsForSession("new-sid-p2p")).toEqual(["p2p-chat"]);
+    expect(sessionInfoMap.get("p2p-chat")?.sessionId).toBe("new-sid-p2p");
+  });
+
+  it("群聊 + updateChatInfo 抛错：内存完全不动 + 返回 error", async () => {
+    bindChatToSession("old-sid", "chat-1");
+    sessionInfoMap.set("chat-1", {
+      sessionId: "old-sid", turnCount: 5, lastContextTokens: 100,
+      startTime: 0, tool: "claude",
+    });
+    const oldDisplay = {
+      cardId: "c1", sequence: 1, cardBusy: false,
+      cardCreatedAt: 0, lastSentContent: "", streamErrorNotified: false,
+    };
+    displayCards.set("chat-1", oldDisplay);
+
+    const updateChatInfoFn = async () => {
+      throw new Error("network timeout");
+    };
+
+    const result = await switchChatBinding({
+      chatId: "chat-1",
+      chatType: "group",
+      oldSessionId: "old-sid",
+      newSessionId: "new-sid",
+      tool: "claude",
+      chatName: "新会话-failed",
+      newDescription: "Claude Code Session: new-sid",
+      updateChatInfoFn,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toBe("network timeout");
+    // 内存绑定保持旧状态
+    expect(getChatsForSession("old-sid")).toEqual(["chat-1"]);
+    expect(getChatsForSession("new-sid")).toEqual([]);
+    expect(displayCards.get("chat-1")).toBe(oldDisplay);
+    expect(sessionInfoMap.get("chat-1")?.sessionId).toBe("old-sid");
+    expect(sessionInfoMap.get("chat-1")?.turnCount).toBe(5);
+  });
+
+  it("oldSessionId 为 null 时不调 unbind(适用于私聊首次绑定)", async () => {
+    const updateChatInfoFn = async () => {};
+
+    const result = await switchChatBinding({
+      chatId: "fresh-chat",
+      chatType: "p2p",
+      oldSessionId: null,
+      newSessionId: "fresh-sid",
+      tool: "claude",
+      chatName: "首次会话",
+      newDescription: "Claude Code Session: fresh-sid",
+      updateChatInfoFn,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(getChatsForSession("fresh-sid")).toEqual(["fresh-chat"]);
+  });
+
+  it("API 成功后,registry 持久化记录可被重新加载", async () => {
+    const updateChatInfoFn = async () => {};
+
+    await switchChatBinding({
+      chatId: "chat-persist",
+      chatType: "group",
+      oldSessionId: null,
+      newSessionId: "persist-sid",
+      tool: "cursor",
+      chatName: "persist-name",
+      newDescription: "Cursor Session: persist-sid",
+      initialTurnCount: 3,
+      initialContextTokens: 500,
+      updateChatInfoFn,
+    });
+
+    // 验证 registry 文件已写入
+    const raw = await readFile(registryFile, "utf-8");
+    const parsed = JSON.parse(raw);
+    expect(parsed["chat-persist"]).toMatchObject({
+      chatId: "chat-persist",
+      sessionId: "persist-sid",
+      tool: "cursor",
+      chatName: "persist-name",
+      turnCount: 3,
+      lastContextTokens: 500,
+      running: false,
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resetState 调用契约：仅供测试 + 进程首次启动。
+// 不应在 SDK onReady/onReconnected 中调用——会清空 activePrompts 让正在跑
+// 的后台 prompt 变成"孤儿 generator"（Map 删了但 controller 没 abort,
+// 导致同一 sessionId 双开 prompt）。
+// ---------------------------------------------------------------------------
+
+describe("resetState 契约：清空所有运行时状态", () => {
+  it("清空 activePrompts 但不 abort controller(只能由进程首次启动调用)", () => {
+    const controller = new AbortController();
+    let aborted = false;
+    controller.signal.addEventListener("abort", () => { aborted = true; });
+    activePrompts.set("sid-running", {
+      controller, stopped: false, startTime: 0,
+    });
+
+    resetState();
+
+    expect(activePrompts.size).toBe(0);
+    // 注意：resetState 不主动 abort——所以如果生产代码在 prompt 跑过程中
+    // 误调 resetState,后台 generator 仍会继续跑直到自然结束,但 activePrompts
+    // 已经空了,下条消息会双开 prompt。这是 resetState 仅适用于"启动时"
+    // (Map 本就是空的)的根本原因。
+    expect(aborted).toBe(false);
+  });
+});

package/src/__tests__/stream-state.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, rm, readFile, readdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// 在 import stream-state 之前先 mock config，让 USER_DATA_DIR 指向临时目录
+const TEST_DATA_DIR = await mkdtemp(join(tmpdir(), "chatccc-stream-state-test-"));
+vi.mock("../config.ts", async () => {
+  const actual = await vi.importActual<typeof import("../config.ts")>("../config.ts");
+  return {
+    ...actual,
+    USER_DATA_DIR: TEST_DATA_DIR,
+    ts: () => "test-ts",
+  };
+});
+
+const {
+  writeStreamState,
+  readStreamState,
+  createEmptyStreamState,
+  STREAMS_DIR,
+  _setRenameForTest,
+  _resetRenameForTest,
+} = await import("../stream-state.ts");
+
+describe("writeStreamState — atomic rename", () => {
+  beforeEach(async () => {
+    // 清空测试目录
+    try {
+      const entries = await readdir(STREAMS_DIR);
+      for (const e of entries) await rm(join(STREAMS_DIR, e), { force: true });
+    } catch { /* dir not yet exist */ }
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+  });
+
+  it("writeStreamState 写完后 readStreamState 能读到完整内容", async () => {
+    const state = createEmptyStreamState("sid-1", "/tmp", "claude", 1);
+    state.accumulatedContent = "hello";
+    state.finalReply = "world";
+
+    await writeStreamState(state);
+
+    const got = await readStreamState("sid-1");
+    expect(got).not.toBeNull();
+    expect(got!.accumulatedContent).toBe("hello");
+    expect(got!.finalReply).toBe("world");
+  });
+
+  it("写入完成后,临时 .tmp 文件不应残留(rename 成功路径)", async () => {
+    const state = createEmptyStreamState("sid-2", "/tmp", "claude", 1);
+    await writeStreamState(state);
+
+    const entries = await readdir(STREAMS_DIR);
+    // 只应有 sid-2.json,没有 sid-2.json.tmp
+    expect(entries).toContain("sid-2.json");
+    expect(entries.some((e) => e.endsWith(".tmp"))).toBe(false);
+  });
+
+  it("覆盖写入时,reader 永远只读到完整 JSON(不读到半截)", async () => {
+    // 此测试验证：先写一个版本,再写第二个版本,reader 中间读取必然是某个完整版本
+    const state1 = createEmptyStreamState("sid-3", "/tmp", "claude", 1);
+    state1.accumulatedContent = "v1";
+    await writeStreamState(state1);
+
+    // 直接读原始字节,确认是完整 JSON
+    const raw1 = await readFile(join(STREAMS_DIR, "sid-3.json"), "utf-8");
+    expect(() => JSON.parse(raw1)).not.toThrow();
+    expect(JSON.parse(raw1).accumulatedContent).toBe("v1");
+
+    const state2 = createEmptyStreamState("sid-3", "/tmp", "claude", 2);
+    state2.accumulatedContent = "v2";
+    await writeStreamState(state2);
+
+    const raw2 = await readFile(join(STREAMS_DIR, "sid-3.json"), "utf-8");
+    expect(() => JSON.parse(raw2)).not.toThrow();
+    expect(JSON.parse(raw2).accumulatedContent).toBe("v2");
+  });
+
+  it("rename 失败时降级为直接覆盖写,不抛错 + 数据仍写入", async () => {
+    let renameCalls = 0;
+    _setRenameForTest(async () => {
+      renameCalls++;
+      throw Object.assign(new Error("EPERM mocked"), { code: "EPERM" });
+    });
+
+    try {
+      const state = createEmptyStreamState("sid-fallback", "/tmp", "claude", 1);
+      state.accumulatedContent = "fallback-content";
+
+      // 不应抛错
+      await expect(writeStreamState(state)).resolves.toBeUndefined();
+
+      // 数据仍应写入(降级路径走 writeFile 覆盖)
+      const got = await readStreamState("sid-fallback");
+      expect(got).not.toBeNull();
+      expect(got!.accumulatedContent).toBe("fallback-content");
+
+      expect(renameCalls).toBe(1);
+    } finally {
+      _resetRenameForTest();
+    }
+  });
+
+  it("readStreamState 对损坏的 JSON 返回 null(reader 兜底契约)", async () => {
+    // 直接写一段半截 JSON 到目标路径
+    const filePath = join(STREAMS_DIR, "sid-broken.json");
+    await writeFile(filePath, '{"sessionId":"sid-broken","accum', "utf-8");
+
+    const got = await readStreamState("sid-broken");
+    expect(got).toBeNull();
+  });
+
+  it("readStreamState 对不存在文件返回 null", async () => {
+    const got = await readStreamState("never-existed");
+    expect(got).toBeNull();
+  });
+});
+
+describe("createEmptyStreamState", () => {
+  it("生成的 state 字段正确且 status=running", () => {
+    const s = createEmptyStreamState("sid-X", "/cwd", "cursor", 5);
+    expect(s.sessionId).toBe("sid-X");
+    expect(s.cwd).toBe("/cwd");
+    expect(s.tool).toBe("cursor");
+    expect(s.turnCount).toBe(5);
+    expect(s.status).toBe("running");
+    expect(s.accumulatedContent).toBe("");
+    expect(s.finalReply).toBe("");
+    expect(s.chunkCount).toBe(0);
+  });
+});

package/src/index.ts

@@ -97,9 +97,11 @@ import {
   initClaudeSession,
   lastMsgTimestamps,
   processedMessages,
+  rebuildBindingsFromRegistry,
   resetState,
   resumeAndPrompt,
   sessionInfoMap,
+  switchChatBinding,
   recordSessionRegistry,
   getAdapterForTool,
   stopSession,
@@ -717,11 +719,10 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           cwd = await getDefaultCwd(chatId);
         }
 
-        // 不 abort 旧 session，只解绑当前 chat
-        // 旧 session 如果正在跑，display loop 继续服务其他群
-        unbindChatFromSession(sessionId, chatId);
-        displayCards.delete(chatId);
-
+        // 第一步:创建新 session(此时尚未碰任何内存绑定,失败可直接返回,
+        // 旧 session 状态完全保留)。
+        // 注意不 abort 旧 session：旧 session 若仍在跑,display loop 会继续
+        // 把卡片推到原群直到 prompt 自然结束(或被 /stop)。
         let newSessionId: string;
         try {
           const init = await initClaudeSession(descriptionTool, cwd);
@@ -732,37 +733,46 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           return;
         }
 
-        // 绑定新 session
-        bindChatToSession(newSessionId, chatId);
-        recordLastActiveChat(newSessionId, chatId);
-
+        // 第二步:事务式切换 chat 绑定 —— 把 chat 从 oldSessionId 改嫁到
+        // newSessionId。switchChatBinding 内部保证:
+        //   - 群聊先调 updateChatInfo 改群描述,失败则内存绑定完全不动
+        //   - 私聊跳过 updateChatInfo(私聊 chatId 调群 API 必然失败)
+        //   - API 成功后统一切换内存:unbind 旧 / clear displayCards / bind 新 /
+        //     recordLastActiveChat / sessionInfoMap.set + 持久化 registry/sessions
+        // 详见 session.ts::switchChatBinding 注释。
         const descPrefix = sessionPrefixForTool(descriptionTool);
         const newName = sessionChatName("新会话", cwd);
-        await updateChatInfo(freshToken, chatId, newName, `${descPrefix} ${newSessionId}`);
-        console.log(`[${ts()}] [NEWH] Group updated: name="${newName}" desc="${descPrefix} ${newSessionId}"`);
-
-        sessionInfoMap.set(chatId, {
-          sessionId: newSessionId,
-          turnCount: 0,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          tool: descriptionTool,
-        });
-        await recordSessionRegistry({
+        const switchResult = await switchChatBinding({
           chatId,
-          sessionId: newSessionId,
+          chatType,
+          oldSessionId: sessionId,
+          newSessionId,
           tool: descriptionTool,
           chatName: newName,
-          turnCount: 0,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          running: false,
+          newDescription: `${descPrefix} ${newSessionId}`,
+          updateChatInfoFn: (cid, name, desc) => updateChatInfo(freshToken, cid, name, desc),
         });
-        await saveSessionTool(newSessionId, descriptionTool, newName);
+        if (!switchResult.ok) {
+          // 飞书 API 失败:内存仍指向旧 session,新 session 已创建但无人使用,
+          // 留在 sessions.json(loadSessionTools)成为 orphan,可由 /sessions
+          // 列表展示供人工清理或下次 /newh 覆盖。代价小于让群 description
+          // 与内存绑定不一致。
+          logTrace(tid, "DONE", { outcome: "newh_update_chat_fail", error: switchResult.error?.message });
+          await sendCardReply(
+            freshToken, chatId, "Error",
+            `更新群描述失败,会话未切换(新 session 已创建但未启用):\n${switchResult.error?.message}`,
+            "red"
+          );
+          return;
+        }
+        if (chatType !== "p2p") {
+          console.log(`[${ts()}] [NEWH] Group updated: name="${newName}" desc="${descPrefix} ${newSessionId}"`);
+        }
 
         setChatAvatar(freshToken, chatId, descriptionTool, "new").catch(() => {});
 
-        // 如果新 session 有活跃 prompt，启动 display loop 让本群也能看到
+        // 如果新 session 有活跃 prompt,启动 display loop 让本群也能看到。
+        // /newh 后通常是空 session,这里几乎走不到,但留作防御。
         if (isSessionRunning(newSessionId)) {
           const { ensureDisplayLoop } = await import("./session.ts");
           ensureDisplayLoop(newSessionId);
@@ -834,12 +844,8 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         }
         const target = ordered[index];
 
-        // 不 abort 当前 chat 的旧 session，只解绑再重新绑定
-        if (sessionId) {
-          unbindChatFromSession(sessionId, chatId);
-          displayCards.delete(chatId);
-        }
-
+        // 第一步:解析目标 session 的 cwd(adapter.getSessionInfo 失败则 fallback,
+        // 这一步不动任何内存绑定,失败也不脏)。
         const targetAdapter = getAdapterForTool(target.tool);
         let cwd2: string;
         try {
@@ -849,34 +855,43 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           cwd2 = await getDefaultCwd(chatId);
         }
 
-        // 绑定到新 session
-        bindChatToSession(target.sessionId, chatId);
-        recordLastActiveChat(target.sessionId, chatId);
-
+        // 第二步:事务式切换 chat 绑定到 target.sessionId。
+        // switchChatBinding 内部行为同 /newh,详见 session.ts::switchChatBinding。
+        // 注意:这里把 turnCount 沿用 target.turnCount(从 registry 读到的目标 chat
+        // 历史轮数),而不是从 0 开始,这样 /status 显示的轮数延续历史。
         const descPrefix2 = sessionPrefixForTool(target.tool);
         const newName2 = target.chatName || sessionChatName("新会话", cwd2);
-        await updateChatInfo(freshToken, chatId, newName2, `${descPrefix2} ${target.sessionId}`);
-        console.log(`[${ts()}] [SESSION] Switched to session ${target.sessionId} (#${index + 1}), name="${newName2}"`);
-
-        sessionInfoMap.set(chatId, {
-          sessionId: target.sessionId,
-          turnCount: target.turnCount,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          tool: target.tool,
-        });
-        await recordSessionRegistry({
+        const switchResult = await switchChatBinding({
           chatId,
-          sessionId: target.sessionId,
+          chatType,
+          oldSessionId: sessionId,
+          newSessionId: target.sessionId,
           tool: target.tool,
           chatName: newName2,
-          running: false,
+          newDescription: `${descPrefix2} ${target.sessionId}`,
+          initialTurnCount: target.turnCount,
+          initialContextTokens: 0,
+          updateChatInfoFn: (cid, name, desc) => updateChatInfo(freshToken, cid, name, desc),
         });
-        await saveSessionTool(target.sessionId, target.tool, newName2);
+        if (!switchResult.ok) {
+          logTrace(tid, "DONE", { outcome: "session_update_chat_fail", error: switchResult.error?.message });
+          await sendCardReply(
+            freshToken, chatId, "Error",
+            `更新群描述失败,会话未切换:\n${switchResult.error?.message}`,
+            "red"
+          );
+          return;
+        }
+        if (chatType !== "p2p") {
+          console.log(`[${ts()}] [SESSION] Switched to session ${target.sessionId} (#${index + 1}), name="${newName2}"`);
+        }
 
         setChatAvatar(freshToken, chatId, target.tool, "new").catch(() => {});
 
-        // 如果新 session 有活跃 prompt，加上 display loop
+        // 如果新 session 有活跃 prompt,加上 display loop。注意:此时
+        // recordLastActiveChat 已经把 lastActive 改成当前 chat,会"抢走"
+        // 原有群的 display 推送(见 review 中 corner case 5)。这是已知
+        // 设计权衡:用户主动切换就是想"接管"该 session 的显示。
         if (isSessionRunning(target.sessionId)) {
           const { ensureDisplayLoop } = await import("./session.ts");
           ensureDisplayLoop(target.sessionId);
@@ -1231,25 +1246,34 @@ async function startBotServiceCore(): Promise<void> {
       console.error(`[WS] Local relay error: ${err.message}`);
     });
   } else {
+    // 进程首次启动:此时所有 Map 都是空的,resetState 主要是打个 LOG 标识"开始
+    // 干净状态"。修正残留的 running stream-state 并重建 session→chat 映射。
     resetState();
-    // 启动时修正残留的 running 状态并重建 session→chat 映射
     fixStaleStreamStates().then(async () => {
       const registry = await loadSessionRegistryForBinding();
       rebuildSessionChatsFromRegistry(registry);
     }).catch((err) => console.error(`[${ts()}] Init bindings failed: ${(err as Error).message}`));
 
+    // ⚠️ 关键设计:onReady / onReconnected 只重建只读映射,**绝不**清空运行时
+    // 状态(activePrompts、displayLoops、sessionInfoMap、processedMessages)。
+    // SDK 重连只是底层 WebSocket 抖动,业务层不受影响:
+    //   - 后台 generator 仍在跑、stream-state 仍在被写
+    //   - display loop 仍在向群推送
+    //   - 已处理消息的去重 set 必须保留,避免 SDK 重推老消息时 prompt 跑两遍
+    // 历史 bug:此处曾误调 resetState() 导致重连即让所有后台任务变孤儿,
+    // 同一 session 还可能双开 prompt(详见 session.ts::resetState 注释)。
     const wsClient = new WSClient({
       appId: APP_ID,
       appSecret: APP_SECRET,
       onReady: async () => {
-        resetState();
-        const registry = await loadSessionRegistryForBinding();
-        rebuildSessionChatsFromRegistry(registry);
+        await rebuildBindingsFromRegistry().catch((err) =>
+          console.error(`[${ts()}] [SDK READY] rebuild bindings failed: ${(err as Error).message}`)
+        );
       },
       onReconnected: async () => {
-        resetState();
-        const registry = await loadSessionRegistryForBinding();
-        rebuildSessionChatsFromRegistry(registry);
+        await rebuildBindingsFromRegistry().catch((err) =>
+          console.error(`[${ts()}] [SDK RECONNECT] rebuild bindings failed: ${(err as Error).message}`)
+        );
       },
     });
 

package/src/session.ts

@@ -85,6 +85,29 @@ export const sessionInfoMap = new Map<string, {
   tool: string;
 }>();
 
+/**
+ * 清空所有进程内运行时状态。
+ *
+ * ⚠️ 红线：**绝对不要**在飞书 SDK 的 onReady / onReconnected 回调里调用本函数。
+ * SDK 的 WebSocket 重连只是底层连接抖动，业务层（活跃 prompt、display loop、
+ * stream-state 文件、轮数计数）完全不受影响。在重连里调 resetState 会：
+ *   1) `activePrompts.clear()` 只是删 Map，**不会** abort 后台 generator。
+ *      generator 继续跑、继续写 stream-state.json，但 display loop 已被
+ *      stop，用户群里再也看不到任何更新；最终回复永远不发到群。
+ *   2) 该 sessionId 在内存里"看似空闲"，下一条用户消息进来会**第二次进入**
+ *      `runAgentSession`，同一个 cursor/claude session 同时跑两条 prompt，
+ *      输出互相串扰、token 计费翻倍。
+ *   3) `processedMessages` / `lastMsgTimestamps` 被清，SDK 重连后若服务端
+ *      重推已 ack 的消息，去重失效会让同一 prompt 被处理两次。
+ *   4) `sessionInfoMap` 清空后，群再发消息时 nextTurnCount 从 1 重新计数。
+ *
+ * 合法调用点：
+ *   - 单元测试 setup（清测试间状态）
+ *   - 进程首次启动（此时 Map 都是空的，调用纯粹是为了打 LOG）
+ *
+ * SDK 重连场景请改用 `rebuildBindingsFromRegistry()`，它只重建 sessionId →
+ * chatId 映射，不动任何运行时状态。
+ */
 export function resetState(): void {
   for (const entry of chatSessionMap.values()) {
     if (entry.spinnerTimer) clearInterval(entry.spinnerTimer);
@@ -94,7 +117,6 @@ export function resetState(): void {
   sessionInfoMap.clear();
   processedMessages.clear();
   lastMsgTimestamps.clear();
-  // 清理新的全局状态
   activePrompts.clear();
   displayCards.clear();
   for (const stop of displayLoops.values()) stop();
@@ -102,6 +124,9 @@ export function resetState(): void {
   console.log(`[${ts()}] [RESET] State cleared (dedup + active sessions + bindings)`);
 }
 
+// 注:`rebuildBindingsFromRegistry` 定义在下方与 loadSessionRegistry 同区域,
+// 是 onReady/onReconnected 取代 resetState 的正确入口。
+
 // ---------------------------------------------------------------------------
 // Adapter: 按 tool 创建并缓存
 // ---------------------------------------------------------------------------
@@ -235,6 +260,26 @@ export async function loadSessionRegistryForBinding(): Promise<SessionRegistryDa
   return loadSessionRegistry();
 }
 
+/**
+ * 从持久化的 registry 重建 sessionId → chatId 映射。
+ *
+ * 设计契约（替代之前 onReady/onReconnected 误用的 resetState）：
+ *   - **不动** activePrompts：后台 prompt 在 SDK 重连后必须继续被识别为活跃,
+ *     否则下条用户消息会绕过 isSessionRunning 检查再开一条 prompt,
+ *     导致同一 sessionId 双开 generator
+ *   - **不动** sessionInfoMap：内存里的轮数/contextTokens 比 registry 更新
+ *   - **不动** displayCards / displayLoops：正在跑的 prompt 还需要它们继续推卡片
+ *   - **不动** processedMessages / lastMsgTimestamps：SDK 重连若重推已 ack 消息,
+ *     去重 set 还在才能避免同一 prompt 跑两遍
+ *
+ * 唯一被重建的是 sessionChatsMap（通过调用 rebuildSessionChatsFromRegistry）——
+ * 该 Map 是从 registry 派生的纯只读映射,重建是幂等且廉价的。
+ */
+export async function rebuildBindingsFromRegistry(): Promise<void> {
+  const registry = await loadSessionRegistry();
+  rebuildSessionChatsFromRegistry(registry);
+}
+
 async function saveSessionRegistry(data: SessionRegistryData): Promise<void> {
   try {
     await mkdir(dirname(sessionRegistryFile), { recursive: true });
@@ -379,6 +424,118 @@ export function accumulateBlockContent(
   }
 }
 
+// ---------------------------------------------------------------------------
+// switchChatBinding — /newh、/session N 共用的事务式"切换 chat 绑定"
+// ---------------------------------------------------------------------------
+//
+// 设计契约（解决三类历史 bug）：
+//
+//   1. 私聊不能调 updateChatInfo（飞书 API 在 p2p chatId 上会返回非 0 → throw）。
+//      之前的实现没判断 chatType,私聊 /newh、/session N 走到 updateChatInfo
+//      就直接抛错,留下"内存已切换、registry 没更新"的脏状态。
+//
+//   2. updateChatInfo 群聊也可能因为网络/频控失败。之前的代码顺序是
+//        先 unbind 旧 → bind 新 → 再调 updateChatInfo
+//      API 失败后内存绑定已经切走,但群 description 还是旧 sessionId。
+//      下次用户在群里发消息时,extractSessionInfo 拿到旧 sessionId,而内存绑定
+//      指向新 sessionId,路由完全错乱（参考 /newh 的 corner case 7）。
+//
+//   3. 改成"先 API 后内存"的顺序后,API 失败就完全不切换内存,下次消息按
+//      旧 description 正常路由到旧 session,新创建的 session 留在 sessions.json
+//      里成为可清理的 orphan。
+//
+// 调用方约定：
+//   - newSessionId 必须是已经 createSession 完成的真实 session（本函数不创建）
+//   - oldSessionId 为 null 表示当前 chat 没有任何旧绑定（比如私聊首次绑）
+//   - 私聊跳过 updateChatInfo,直接做内存切换 + registry 持久化
+//   - API 失败时：
+//       * 不动内存绑定 / sessionInfoMap / displayCards
+//       * 返回 { ok: false, error }
+//       * 调用方负责把错误反馈给用户
+// ---------------------------------------------------------------------------
+
+export interface SwitchChatBindingArgs {
+  chatId: string;
+  chatType: string;
+  oldSessionId: string | null;
+  newSessionId: string;
+  tool: string;
+  /** 群名（私聊忽略） */
+  chatName: string;
+  /** 群描述（私聊忽略），通常为 `${sessionPrefixForTool(tool)} ${newSessionId}` */
+  newDescription: string;
+  /** 切换后 sessionInfoMap 的初始 turnCount/lastContextTokens（如沿用历史） */
+  initialTurnCount?: number;
+  initialContextTokens?: number;
+  /** 飞书 updateChatInfo 实现，依赖注入便于测试 mock */
+  updateChatInfoFn: (chatId: string, name: string, description: string) => Promise<void>;
+}
+
+export interface SwitchChatBindingResult {
+  ok: boolean;
+  error?: Error;
+}
+
+export async function switchChatBinding(args: SwitchChatBindingArgs): Promise<SwitchChatBindingResult> {
+  const {
+    chatId,
+    chatType,
+    oldSessionId,
+    newSessionId,
+    tool,
+    chatName,
+    newDescription,
+    initialTurnCount = 0,
+    initialContextTokens = 0,
+    updateChatInfoFn,
+  } = args;
+
+  // Step 1: 群聊场景先调用飞书 API（不可逆操作放最前）。
+  // 私聊跳过——p2p chatId 调 updateChatInfo 必然失败。
+  if (chatType !== "p2p") {
+    try {
+      await updateChatInfoFn(chatId, chatName, newDescription);
+    } catch (err) {
+      // API 失败：完全不动内存,调用方负责回报用户。
+      return { ok: false, error: err as Error };
+    }
+  }
+
+  // Step 2: API 成功（或私聊跳过）后,原子地切换内存绑定。
+  // 这一段全是同步 Map 操作,不会失败。
+  if (oldSessionId) {
+    unbindChatFromSession(oldSessionId, chatId);
+    displayCards.delete(chatId);
+  }
+  bindChatToSession(newSessionId, chatId);
+  recordLastActiveChat(newSessionId, chatId);
+
+  const now = Date.now();
+  sessionInfoMap.set(chatId, {
+    sessionId: newSessionId,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    tool,
+  });
+
+  // Step 3: 持久化（registry + sessions.json）。
+  // 这两步即使失败也不影响内存正确性,下次 prompt 会再写一次。
+  await recordSessionRegistry({
+    chatId,
+    sessionId: newSessionId,
+    tool,
+    chatName,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    running: false,
+  });
+  await saveSessionTool(newSessionId, tool, chatName);
+
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // AI tool session management
 // ---------------------------------------------------------------------------

package/src/stream-state.ts

@@ -1,94 +1,141 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import { USER_DATA_DIR, ts } from "./config.ts";
-
-// ---------------------------------------------------------------------------
-// stream-state.json — 每个 session 的流式输出持久化文件
-// ---------------------------------------------------------------------------
-
-export const STREAMS_DIR = join(USER_DATA_DIR, "state", "streams");
-
-export interface StreamState {
-  sessionId: string;
-  status: "running" | "done" | "stopped" | "error";
-  accumulatedContent: string;
-  finalReply: string;
-  chunkCount: number;
-  turnCount: number;
-  contextTokens: number;
-  updatedAt: number;
-  cwd: string;
-  tool: string;
-}
-
-function getStreamStatePath(sessionId: string): string {
-  return join(STREAMS_DIR, `${sessionId}.json`);
-}
-
-export async function readStreamState(sessionId: string): Promise<StreamState | null> {
-  try {
-    const raw = await readFile(getStreamStatePath(sessionId), "utf-8");
-    const parsed = JSON.parse(raw) as StreamState;
-    if (parsed && typeof parsed.sessionId === "string") return parsed;
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-export async function writeStreamState(state: StreamState): Promise<void> {
-  const filePath = getStreamStatePath(state.sessionId);
-  try {
-    await mkdir(dirname(filePath), { recursive: true });
-    // 先写临时文件再 rename，保证原子性
-    const tmpPath = filePath + ".tmp";
-    await writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
-    await writeFile(filePath, JSON.stringify(state, null, 2), "utf-8");
-  } catch (err) {
-    console.error(`[${ts()}] Failed to write stream-state for ${state.sessionId}: ${(err as Error).message}`);
-  }
-}
-
-export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
-  return {
-    sessionId,
-    status: "running",
-    accumulatedContent: "",
-    finalReply: "",
-    chunkCount: 0,
-    turnCount,
-    contextTokens: 0,
-    updatedAt: Date.now(),
-    cwd,
-    tool,
-  };
-}
-
-/** 进程重启时修正虚假的 "running" 状态 */
-export async function fixStaleStreamStates(): Promise<void> {
-  // 启动时将残留的 running 标记为 error
-  // 实际 agent 进程已不存在，下次 prompt 时会自然覆盖
-  try {
-    const { readdir } = await import("node:fs/promises");
-    let entries: string[];
-    try {
-      entries = await readdir(STREAMS_DIR);
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (!entry.endsWith(".json")) continue;
-      const state = await readStreamState(entry.replace(".json", ""));
-      if (state && state.status === "running") {
-        state.status = "error";
-        state.accumulatedContent += "\n\n⚠️ 进程重启，流式输出中断。";
-        state.updatedAt = Date.now();
-        await writeStreamState(state);
-        console.log(`[${ts()}] [STREAM-STATE] marked stale running as error: ${state.sessionId}`);
-      }
-    }
-  } catch (err) {
-    console.error(`[${ts()}] [STREAM-STATE] fixStaleStreamStates failed: ${(err as Error).message}`);
-  }
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { USER_DATA_DIR, ts } from "./config.ts";
+
+// ---------------------------------------------------------------------------
+// stream-state.json — 每个 session 的流式输出持久化文件
+// ---------------------------------------------------------------------------
+
+export const STREAMS_DIR = join(USER_DATA_DIR, "state", "streams");
+
+export interface StreamState {
+  sessionId: string;
+  status: "running" | "done" | "stopped" | "error";
+  accumulatedContent: string;
+  finalReply: string;
+  chunkCount: number;
+  turnCount: number;
+  contextTokens: number;
+  updatedAt: number;
+  cwd: string;
+  tool: string;
+}
+
+function getStreamStatePath(sessionId: string): string {
+  return join(STREAMS_DIR, `${sessionId}.json`);
+}
+
+export async function readStreamState(sessionId: string): Promise<StreamState | null> {
+  try {
+    const raw = await readFile(getStreamStatePath(sessionId), "utf-8");
+    const parsed = JSON.parse(raw) as StreamState;
+    if (parsed && typeof parsed.sessionId === "string") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// rename 的可注入实现——仅供测试模拟"Windows EPERM 降级"路径。
+// 生产代码使用 node:fs/promises.rename。
+let renameImpl: typeof rename = rename;
+
+/**
+ * 仅供单测：注入自定义 rename 实现以验证降级分支。
+ * 调用方负责测试结束后用 _resetRenameForTest 还原。
+ */
+export function _setRenameForTest(impl: typeof rename): void {
+  renameImpl = impl;
+}
+
+export function _resetRenameForTest(): void {
+  renameImpl = rename;
+}
+
+/**
+ * 把 StreamState 持久化到磁盘——尽量原子地写。
+ *
+ * 为什么需要原子写：display loop 每 3 秒读一次 stream-state.json,而
+ * runAgentSession 每 2 秒写一次。如果用 `writeFile(filePath, ...)` 直接
+ * 覆盖,reader 在写入过程中读会拿到半截 JSON,JSON.parse 报错——虽然
+ * readStreamState 包了 try/catch 返回 null 不会崩,但相当于"丢一帧"。
+ *
+ * 实现：
+ *   1) 先把内容写到 `<filePath>.tmp`（reader 不会读 .tmp）
+ *   2) 再用 `rename` 把 .tmp 替换成正式文件——`rename` 在 POSIX 上是真原子
+ *      操作,reader 任何时刻读到的都是某个完整的旧/新版本
+ *
+ * Windows 兼容性：Windows 上 `rename` 偶尔会因为目标文件正被 reader 打开
+ * 抛 EPERM/EBUSY（实测罕见,但非零概率）。降级方案：直接 writeFile 覆盖
+ * 真文件,这一帧可能被 reader 读到半截,但 readStreamState 的 try/catch 兜底
+ * 会让 loop 跳过这一帧,2 秒后下次 write 大概率成功——比写盘失败丢数据好。
+ */
+export async function writeStreamState(state: StreamState): Promise<void> {
+  const filePath = getStreamStatePath(state.sessionId);
+  const payload = JSON.stringify(state, null, 2);
+  try {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tmpPath = filePath + ".tmp";
+    await writeFile(tmpPath, payload, "utf-8");
+    try {
+      await renameImpl(tmpPath, filePath);
+    } catch (renameErr) {
+      // Windows 偶发 EPERM/EBUSY：rename 失败时降级为直接覆盖写。
+      // 此次写入失去原子性（reader 可能读到半截 JSON,但 readStreamState
+      // 的 try/catch 会兜底返回 null,只是丢一帧 display 更新）。
+      console.warn(
+        `[${ts()}] [STREAM-STATE] rename failed for ${state.sessionId}, ` +
+          `fallback to overwrite: ${(renameErr as Error).message}`,
+      );
+      await writeFile(filePath, payload, "utf-8");
+      // 尽力清理 .tmp,失败也无所谓——下次 write 会覆盖它
+      await unlink(tmpPath).catch(() => {});
+    }
+  } catch (err) {
+    console.error(`[${ts()}] Failed to write stream-state for ${state.sessionId}: ${(err as Error).message}`);
+  }
+}
+
+export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
+  return {
+    sessionId,
+    status: "running",
+    accumulatedContent: "",
+    finalReply: "",
+    chunkCount: 0,
+    turnCount,
+    contextTokens: 0,
+    updatedAt: Date.now(),
+    cwd,
+    tool,
+  };
+}
+
+/** 进程重启时修正虚假的 "running" 状态 */
+export async function fixStaleStreamStates(): Promise<void> {
+  // 启动时将残留的 running 标记为 error
+  // 实际 agent 进程已不存在，下次 prompt 时会自然覆盖
+  try {
+    const { readdir } = await import("node:fs/promises");
+    let entries: string[];
+    try {
+      entries = await readdir(STREAMS_DIR);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      const state = await readStreamState(entry.replace(".json", ""));
+      if (state && state.status === "running") {
+        state.status = "error";
+        state.accumulatedContent += "\n\n⚠️ 进程重启，流式输出中断。";
+        state.updatedAt = Date.now();
+        await writeStreamState(state);
+        console.log(`[${ts()}] [STREAM-STATE] marked stale running as error: ${state.sessionId}`);
+      }
+    }
+  } catch (err) {
+    console.error(`[${ts()}] [STREAM-STATE] fixStaleStreamStates failed: ${(err as Error).message}`);
+  }
 }