chatccc 0.2.202 → 0.2.203

package/README.md

@@ -352,10 +352,12 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `/plan <内容>` | 只读计划模式：仅允许读文件和 stop-stuck-loop 请求，不执行任何写操作 |
 | `/ask <内容>` | 只读问答模式：与 /plan 相同，仅允许读文件和 stop-stuck-loop 请求 |
 | `/restart` | 重启机器人进程 |
-| `/update` | 更新 npm 全局包并重启（仅限 `npm install -g chatccc` 安装的全局进程） |
-| `/deleteg` | 解散当前飞书会话群；Agent 会话记录保留 |
-
-> **模型切换**：`/model` 查看当前会话 Agent 的可选模型清单，`/model <名称>` 模糊匹配切换，`/model clear` 恢复默认。可选模型来自当前 Agent 的配置：Claude 使用 `claude.model` / `claude.subagentModel`，Cursor 使用 `cursor.model`，Codex 使用 `codex.model`。
+| `/update` | 更新 npm 全局包并重启（仅限 `npm install -g chatccc` 安装的全局进程；同一飞书事件跨重启去重） |
+| `/deleteg` | 解散当前飞书会话群；Agent 会话记录保留 |
+
+`/update` 会在执行 npm 更新前把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略；用户主动发送的新 `/update` 因事件 ID 不同，仍可立即执行。该保护仅作用于 `/update`，普通消息与 `/restart` 的处理不变。
+
+> **模型切换**：`/model` 查看当前会话 Agent 的可选模型清单，`/model <名称>` 模糊匹配切换，`/model clear` 恢复默认。可选模型来自当前 Agent 的配置：Claude 使用 `claude.model` / `claude.subagentModel`，Cursor 使用 `cursor.model`，Codex 使用 `codex.model`。
 
 ---
 

package/package.json

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

package/src/__tests__/update-command-guard.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  acquireUpdateCommandGuard,
+  buildUpdateCommandId,
+  extractFeishuEventId,
+} from "../update-command-guard.ts";
+
+describe("Feishu update command IDs", () => {
+  it("extracts and namespaces a card callback event_id", () => {
+    const eventId = extractFeishuEventId({
+      schema: "2.0",
+      header: { event_id: "evt_update_001" },
+      event: { action: { value: { action: "update" } } },
+    });
+
+    expect(buildUpdateCommandId("card", eventId)).toBe("card:evt_update_001");
+    expect(buildUpdateCommandId("message", "om_update_001")).toBe("message:om_update_001");
+  });
+});
+
+describe("acquireUpdateCommandGuard", () => {
+  let tempDir: string;
+  let guardFile: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "chatccc-update-guard-"));
+    guardFile = join(tempDir, "state", "update-command-guard.json");
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("persists an accepted update ID before returning", async () => {
+    const result = acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 1_000,
+    });
+
+    expect(result).toEqual({ allowed: true, reason: "accepted" });
+    const saved = JSON.parse(await readFile(guardFile, "utf8"));
+    expect(saved).toEqual({
+      version: 1,
+      processed: [{ id: "message:om_update_001", recordedAt: 1_000 }],
+    });
+  });
+
+  it("rejects the same ID after a simulated process restart", () => {
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 1_000,
+    }).allowed).toBe(true);
+
+    // 第二次调用不共享任何内存状态，只通过落盘文件模拟新进程重启后的判断。
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 9_999_999,
+    })).toEqual({ allowed: false, reason: "duplicate_id" });
+  });
+
+  it("accepts different IDs immediately without a cooldown", () => {
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 1_000,
+    }).allowed).toBe(true);
+
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_002",
+      now: 1_001,
+    })).toEqual({ allowed: true, reason: "accepted" });
+  });
+
+  it("repairs a corrupt state file and warns without creating an update loop", async () => {
+    await mkdir(join(tempDir, "state"), { recursive: true });
+    await writeFile(guardFile, "not-json", "utf8");
+    const warn = vi.fn();
+
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 1_000,
+      warn,
+    })).toEqual({ allowed: true, reason: "accepted" });
+    expect(warn).toHaveBeenCalledOnce();
+
+    // 损坏文件已被有效状态覆盖，因此重启后的重复投递仍会被拦截。
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: "message:om_update_001",
+      now: 2_000,
+      warn,
+    })).toEqual({ allowed: false, reason: "duplicate_id" });
+  });
+
+  it("fails closed when the accepted ID cannot be persisted", async () => {
+    const blocker = join(tempDir, "not-a-directory");
+    await writeFile(blocker, "block", "utf8");
+    const warn = vi.fn();
+
+    expect(acquireUpdateCommandGuard({
+      filePath: join(blocker, "update-command-guard.json"),
+      commandId: "message:om_update_001",
+      now: 1_000,
+      warn,
+    })).toEqual({ allowed: false, reason: "state_write_failed" });
+    expect(warn).toHaveBeenCalledOnce();
+  });
+
+  it("allows sources without a stable ID without writing a misleading record", async () => {
+    expect(acquireUpdateCommandGuard({
+      filePath: guardFile,
+      commandId: undefined,
+      now: 1_000,
+    })).toEqual({ allowed: true, reason: "missing_id" });
+    await expect(readFile(guardFile, "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("keeps only the newest configured number of update IDs", async () => {
+    for (let i = 0; i < 4; i++) {
+      expect(acquireUpdateCommandGuard({
+        filePath: guardFile,
+        commandId: `message:om_update_${i}`,
+        now: i,
+        maxEntries: 3,
+      }).allowed).toBe(true);
+    }
+
+    const saved = JSON.parse(await readFile(guardFile, "utf8"));
+    expect(saved.processed.map((entry: { id: string }) => entry.id)).toEqual([
+      "message:om_update_1",
+      "message:om_update_2",
+      "message:om_update_3",
+    ]);
+  });
+});

package/src/index.ts

@@ -189,16 +189,21 @@ function getInnerEvent(data: Evt): InnerEvent {
   return (data.event ?? data) as InnerEvent;
 }
 
-import { formatMessageContent } from "./format-message.ts";
+import { formatMessageContent } from "./format-message.ts";
+import {
+  buildUpdateCommandId,
+  extractFeishuEventId,
+} from "./update-command-guard.ts";
 
 // ---------------------------------------------------------------------------
 // Card action helper: parse button click into text command
 // ---------------------------------------------------------------------------
 
-interface CardActionResult {
-  text: string;
-  chatId: string;
-  openId: string;
+interface CardActionResult {
+  text: string;
+  chatId: string;
+  openId: string;
+  commandId?: string;
 }
 
 function parseCardAction(data: unknown): CardActionResult | null {
@@ -237,7 +242,12 @@ function parseCardAction(data: unknown): CardActionResult | null {
     ((raw as Record<string, unknown>).operator as Record<string, unknown>)?.open_id as string ??
     "";
 
-  return { text, chatId, openId };
+  return {
+    text,
+    chatId,
+    openId,
+    commandId: buildUpdateCommandId("card", extractFeishuEventId(data)),
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -432,7 +442,18 @@ async function startBotServiceCore(): Promise<void> {
         const delayToken = await getTenantAccessToken();
         await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => {});
       }
-      await handleCommand(feishuPlatform, text, chatId, openId, msgTimestamp, chatType, traceId);
+      // 仅 `/update` 会使用这个稳定 ID 做跨重启幂等；其他命令仍沿用
+      // processedMessages 的进程内去重。
+      await handleCommand(
+        feishuPlatform,
+        text,
+        chatId,
+        openId,
+        msgTimestamp,
+        chatType,
+        traceId,
+        buildUpdateCommandId("message", messageId),
+      );
       } catch (err) {
         logTrace(traceId, "ERROR", { message: (err as Error).message });
         console.error(`[${ts()}] [FATAL] im.message.receive_v1 handler crashed: ${(err as Error).message}`);
@@ -483,7 +504,16 @@ async function startBotServiceCore(): Promise<void> {
       const result = parseCardAction(data);
       if (!result) return;
       console.log(`[BTN] chat=${result.chatId} text="${result.text}"`);
-      handleCommand(feishuPlatform, result.text, result.chatId, result.openId, Date.now()).catch((err) =>
+      handleCommand(
+        feishuPlatform,
+        result.text,
+        result.chatId,
+        result.openId,
+        Date.now(),
+        "group",
+        undefined,
+        result.commandId,
+      ).catch((err) =>
         console.error(`[${ts()}] [BTN] handleCommand failed: ${(err as Error).message}`)
       );
       } catch (err) {
@@ -508,7 +538,16 @@ async function startBotServiceCore(): Promise<void> {
         const data = JSON.parse(raw.toString()) as Evt;
         const action = parseCardAction(data);
         if (action) {
-          handleCommand(feishuPlatform, action.text, action.chatId, action.openId, Date.now()).catch((err) =>
+          handleCommand(
+            feishuPlatform,
+            action.text,
+            action.chatId,
+            action.openId,
+            Date.now(),
+            "group",
+            undefined,
+            action.commandId,
+          ).catch((err) =>
             console.error(`[${ts()}] [BTN] handleCommand failed: ${(err as Error).message}`)
           );
           return;

package/src/orchestrator.ts

@@ -90,6 +90,7 @@ import { getChatGptSubscriptionStatus, type ChatGptSubscriptionResult } from "./
 import { applySharedPrefix } from "./shared-prefix.ts";
 import { cwdDisplayName, sessionChatName } from "./session-name.ts";
 import { reloadRuntimeConfig } from "./runtime-reload.ts";
+import { acquireUpdateCommandGuard } from "./update-command-guard.ts";
 export { type PlatformAdapter } from "./platform-adapter.ts";
 import type { ChatAvatarUsageHints, PlatformAdapter } from "./platform-adapter.ts";
 import type { CodexUsageSummary } from "./feishu-api.ts";
@@ -497,15 +498,16 @@ function syncUpdateAndRestart(): void {
 // handleCommand — 平台无关的命令分发
 // ---------------------------------------------------------------------------
 
-export async function handleCommand(
-  platform: PlatformAdapter,
-  text: string,
-  chatId: string,
-  openId: string,
-  msgTimestamp: number,
-  chatType = "group",
-  traceId?: string,
-): Promise<void> {
+export async function handleCommand(
+  platform: PlatformAdapter,
+  text: string,
+  chatId: string,
+  openId: string,
+  msgTimestamp: number,
+  chatType = "group",
+  traceId?: string,
+  commandId?: string,
+): Promise<void> {
   const tid = traceId ?? makeTraceId();
   const sharedPrefix = applySharedPrefix(text);
   const promptText = sharedPrefix.text;
@@ -570,16 +572,40 @@ export async function handleCommand(
     return;
   }
 
-  if (isCommandText && textLower === "/update") {
-    logTrace(tid, "BRANCH", { cmd: "/update" });
-    const isGlobal = isRunningFromGlobalNpm();
-    appendStartupTrace("update: command received", { isGlobal, chatId });
+  if (isCommandText && textLower === "/update") {
+    logTrace(tid, "BRANCH", { cmd: "/update" });
+    const isGlobal = isRunningFromGlobalNpm();
+    appendStartupTrace("update: command received", { isGlobal, chatId });
     if (!isGlobal) {
       await platform.sendText(chatId, "当前进程非 npm 全局安装，无法使用 /update 更新。请通过 npm install -g chatccc 安装后使用。").catch(() => {});
-      logTrace(tid, "DONE", { outcome: "update_not_global" });
-      return;
-    }
-    await platform.sendText(chatId, "正在更新并重启，请稍候...").catch(() => {});
+      logTrace(tid, "DONE", { outcome: "update_not_global" });
+      return;
+    }
+
+    // `/update` 会主动重启进程，内存 processedMessages 随之丢失。必须在发送
+    // “正在更新”以及执行 npm 命令之前同步落盘，才能挡住新进程收到的飞书重投。
+    // 该护栏只位于此分支，不改变普通消息和 `/restart` 的现有去重行为。
+    const updateGuard = acquireUpdateCommandGuard({ commandId });
+    appendStartupTrace("update: command guard checked", {
+      allowed: updateGuard.allowed,
+      reason: updateGuard.reason,
+      hasCommandId: Boolean(commandId),
+    });
+    if (!updateGuard.allowed) {
+      if (updateGuard.reason === "duplicate_id") {
+        // 同一条飞书消息的重投静默丢弃，避免用户再次看到重复提示。
+        logTrace(tid, "DONE", { outcome: "update_duplicate_id" });
+        return;
+      }
+      await platform.sendText(
+        chatId,
+        "无法写入更新保护状态。为避免连续更新和重启，本次 /update 未执行。",
+      ).catch(() => {});
+      logTrace(tid, "DONE", { outcome: "update_guard_write_failed" });
+      return;
+    }
+
+    await platform.sendText(chatId, "正在更新并重启，请稍候...").catch(() => {});
     logTrace(tid, "DONE", { outcome: "update" });
     appendStartupTrace("update: sync update begin", { fromPid: process.pid });
     syncUpdateAndRestart();

package/src/update-command-guard.ts

@@ -0,0 +1,165 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const UPDATE_COMMAND_GUARD_FILE = join(
+  homedir(),
+  ".chatccc",
+  "state",
+  "update-command-guard.json",
+);
+
+const UPDATE_COMMAND_GUARD_VERSION = 1;
+const DEFAULT_MAX_PROCESSED_IDS = 100;
+
+interface ProcessedUpdateCommand {
+  id: string;
+  recordedAt: number;
+}
+
+interface UpdateCommandGuardState {
+  version: 1;
+  processed: ProcessedUpdateCommand[];
+}
+
+export type UpdateCommandGuardResult =
+  | { allowed: true; reason: "accepted" | "missing_id" }
+  | { allowed: false; reason: "duplicate_id" | "state_write_failed" };
+
+export interface AcquireUpdateCommandGuardOptions {
+  filePath?: string;
+  commandId?: string;
+  now?: number;
+  maxEntries?: number;
+  warn?: (message: string) => void;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+/** 从飞书事件信封中读取重投时保持不变的 event_id。 */
+export function extractFeishuEventId(data: unknown): string | undefined {
+  const envelope = asRecord(data);
+  const event = asRecord(envelope?.event);
+  const header = asRecord(envelope?.header) ?? asRecord(event?.header);
+  const context = asRecord(event?.context);
+  const candidates = [header?.event_id, envelope?.event_id, event?.event_id, context?.event_id];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+  }
+  return undefined;
+}
+
+/** 分隔文字消息和卡片回调 ID 的命名空间。 */
+export function buildUpdateCommandId(
+  source: "message" | "card",
+  id: string | undefined,
+): string | undefined {
+  const normalized = id?.trim();
+  return normalized ? `${source}:${normalized}` : undefined;
+}
+
+function emptyState(): UpdateCommandGuardState {
+  return { version: UPDATE_COMMAND_GUARD_VERSION, processed: [] };
+}
+
+function parseState(raw: string, maxEntries: number): UpdateCommandGuardState {
+  const parsed = JSON.parse(raw) as Partial<UpdateCommandGuardState>;
+  if (parsed.version !== UPDATE_COMMAND_GUARD_VERSION || !Array.isArray(parsed.processed)) {
+    throw new Error("invalid update command guard schema");
+  }
+
+  const processed = parsed.processed.map((entry) => {
+    if (
+      typeof entry !== "object"
+      || entry === null
+      || typeof entry.id !== "string"
+      || entry.id.length === 0
+      || typeof entry.recordedAt !== "number"
+      || !Number.isFinite(entry.recordedAt)
+      || entry.recordedAt < 0
+    ) {
+      throw new Error("invalid processed update command entry");
+    }
+    return { id: entry.id, recordedAt: entry.recordedAt };
+  });
+
+  return {
+    version: UPDATE_COMMAND_GUARD_VERSION,
+    processed: processed.slice(-maxEntries),
+  };
+}
+
+function loadState(
+  filePath: string,
+  maxEntries: number,
+  warn: (message: string) => void,
+): UpdateCommandGuardState {
+  if (!existsSync(filePath)) return emptyState();
+  try {
+    return parseState(readFileSync(filePath, "utf8"), maxEntries);
+  } catch (err) {
+    warn(`[UPDATE-GUARD] 状态文件损坏，将重建 ${filePath}: ${(err as Error).message}`);
+    return emptyState();
+  }
+}
+
+/**
+ * 原子写入更新命令 ID。写失败时调用方必须拒绝更新：只有先落盘，
+ * 新进程才能识别飞书在旧进程退出后重投的同一条 `/update`。
+ */
+function persistState(filePath: string, state: UpdateCommandGuardState): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    renameSync(tempPath, filePath);
+  } catch (err) {
+    try { rmSync(tempPath, { force: true }); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * 获取 `/update` 执行资格。只比较稳定消息/事件 ID，因此用户主动发送的
+ * 不同 `/update` 消息仍可立即执行。
+ */
+export function acquireUpdateCommandGuard(
+  options: AcquireUpdateCommandGuardOptions = {},
+): UpdateCommandGuardResult {
+  const filePath = options.filePath ?? UPDATE_COMMAND_GUARD_FILE;
+  const commandId = options.commandId?.trim() || undefined;
+  const now = options.now ?? Date.now();
+  const maxEntries = Number.isInteger(options.maxEntries) && (options.maxEntries ?? 0) > 0
+    ? options.maxEntries!
+    : DEFAULT_MAX_PROCESSED_IDS;
+  const warn = options.warn ?? ((message: string) => console.warn(message));
+
+  // 模拟注入等没有稳定事件 ID 的入口无法做跨重启判断，保持原有行为。
+  if (!commandId) return { allowed: true, reason: "missing_id" };
+
+  const state = loadState(filePath, maxEntries, warn);
+  if (state.processed.some((entry) => entry.id === commandId)) {
+    return { allowed: false, reason: "duplicate_id" };
+  }
+
+  state.processed.push({ id: commandId, recordedAt: now });
+  state.processed = state.processed.slice(-maxEntries);
+  try {
+    persistState(filePath, state);
+  } catch (err) {
+    warn(`[UPDATE-GUARD] 无法写入状态文件 ${filePath}: ${(err as Error).message}`);
+    return { allowed: false, reason: "state_write_failed" };
+  }
+  return { allowed: true, reason: "accepted" };
+}