chatccc 0.2.202 → 0.2.204

package/src/index.ts

@@ -28,12 +28,18 @@ import { WSClient, EventDispatcher, Domain } from "@larksuiteoapi/node-sdk";
 import WebSocket from "ws";
 
 import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging, waitForPortFree } from "./shared.ts";
-import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import {
+  buildWebUiUrl,
+  openWebUiInDefaultBrowser,
+  shouldAutoOpenWebUi,
+} from "./startup-lifecycle.ts";
 import { buildPlatformStartupPlan } from "./platform-startup.ts";
 import { makeTraceId, logTrace } from "./trace.ts";
 import {
-  CHATCCC_PORT,
-  APP_ID,
+  CHATCCC_PORT,
+  config,
+  APP_ID,
   APP_SECRET,
   FEISHU_ENABLED,
   FEISHU_PLATFORM_TYPE,
@@ -189,16 +195,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 +248,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 +448,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 +510,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 +544,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;
@@ -681,11 +726,17 @@ async function startConfiguredPlatforms(
 // Main
 // ---------------------------------------------------------------------------
 
-async function main(): Promise<void> {
-  appendStartupTrace("main: entered", {
-    argv: process.argv.join(" ").slice(0, 400),
-    CHATCCC_PORT,
-    PROJECT_ROOT,
+async function main(): Promise<void> {
+  // 用户直接运行 chatccc 时打开系统默认浏览器；由 `/restart`、`/update`
+  // 或 Web UI 拉起的替代进程会携带内部标记，不重复打扰用户。
+  const autoOpenWebUi = shouldAutoOpenWebUi({
+    openOnStart: config.webUi.openOnStart,
+  });
+  appendStartupTrace("main: entered", {
+    argv: process.argv.join(" ").slice(0, 400),
+    CHATCCC_PORT,
+    PROJECT_ROOT,
+    autoOpenWebUi,
   });
 
   // 黑匣子：所有未捕获异常 / 信号 / beforeExit 都同步写入 startup-trace.log（appendFileSync）。
@@ -741,9 +792,18 @@ async function main(): Promise<void> {
     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);
+    console.log(`${"=".repeat(60)}\n`);
+
+    if (autoOpenWebUi) {
+      const url = buildWebUiUrl(SIM_PORT);
+      const opened = openWebUiInDefaultBrowser(SIM_PORT);
+      appendStartupTrace(
+        opened ? "web-ui: opening simulate browser" : "web-ui: simulate browser unavailable",
+        { url },
+      );
+    }
+
+    installShutdownHandlers(simServer);
     return;
   }
 
@@ -791,8 +851,9 @@ async function main(): Promise<void> {
     if (!APP_ID.trim() || !APP_SECRET.trim()) {
       // 凭证不全：进 setup 向导。注入 onActivate 回调让用户点"保存并启动"
       // 时，原地（同进程）调用 startBotService，复用 setup HTTP server。
-      startSetupMode(CHATCCC_PORT, {
-        onActivate: async (httpServer: Server) => {
+      startSetupMode(CHATCCC_PORT, {
+        openBrowser: autoOpenWebUi,
+        onActivate: async (httpServer: Server) => {
           reloadRuntimeConfig("setup-activate");
           appendStartupTrace("setup-activate: reloaded config from disk", {
             appIdMaskAfterReload: maskAppId(APP_ID),
@@ -828,17 +889,35 @@ async function main(): Promise<void> {
     await waitForPortFree(CHATCCC_PORT);
     appendStartupTrace("main: port free confirmed", { CHATCCC_PORT });
   }
-  const httpServer = createServer(createUiRouter());
-  await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err: NodeJS.ErrnoException) => {
+  const httpServer = createServer(createUiRouter());
+  await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err: NodeJS.ErrnoException) => {
     console.error(`\n[启动] 本地中继 WebSocket 监听失败：端口 ${CHATCCC_PORT}（${err.code ?? "?"} — ${err.message}）`);
     console.error(
       "  处理建议: 关闭占用该端口的其它程序，或在 config.json 的 port 字段里改成其它未占用端口（如 18081）。"
     );
     printServiceDidNotStart(`本地中继端口 ${CHATCCC_PORT} 无法监听（${err.code ?? "?"} — ${err.message}）`);
-    process.exit(1);
-  });
-
-  await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
+    process.exit(1);
+  });
+
+  // 必须等 HTTP server 真正监听后再发起打开请求，避免浏览器先到一步看到
+  // ERR_CONNECTION_REFUSED。Chrome CDP 守护仍保持自己原有的独立行为。
+  if (autoOpenWebUi) {
+    const url = buildWebUiUrl(CHATCCC_PORT);
+    const opened = openWebUiInDefaultBrowser(CHATCCC_PORT);
+    if (opened) {
+      console.log(`[WEB-UI] 已请求系统默认浏览器打开: ${url}`);
+      appendStartupTrace("web-ui: opening default browser", { url });
+    } else {
+      appendStartupTrace("web-ui: default browser unavailable", { url });
+    }
+  } else {
+    appendStartupTrace("web-ui: default browser skipped by lifecycle or preference", {
+      url: buildWebUiUrl(CHATCCC_PORT),
+      openOnStart: config.webUi.openOnStart,
+    });
+  }
+
+  await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
 
   installShutdownHandlers(httpServer);
 }

package/src/orchestrator.ts

@@ -90,6 +90,8 @@ 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";
+import { createInternalRestartEnv } from "./startup-lifecycle.ts";
 export { type PlatformAdapter } from "./platform-adapter.ts";
 import type { ChatAvatarUsageHints, PlatformAdapter } from "./platform-adapter.ts";
 import type { CodexUsageSummary } from "./feishu-api.ts";
@@ -479,7 +481,12 @@ function syncUpdateAndRestart(): void {
 
   // 3. spawn new chatccc
   try {
-    const child = spawn(binPath, [], { detached: true, stdio: "ignore", shell: true });
+    const child = spawn(binPath, [], {
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      env: createInternalRestartEnv(),
+    });
     child.unref();
     updLog(`spawn new chatccc OK, childPid=${child.pid}, bin=${binPath}`);
     appendStartupTrace("update: spawn OK", { childPid: child.pid, binPath });
@@ -497,15 +504,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;
@@ -543,9 +551,10 @@ export async function handleCommand(
     appendStartupTrace("restart: spawn begin", { fromPid: process.pid });
     const child = spawn("npx", ["tsx", "src/index.ts"], {
       cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      shell: true,
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      env: createInternalRestartEnv(),
     });
 
     child.on("error", (err) => {
@@ -570,16 +579,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/startup-lifecycle.ts

@@ -0,0 +1,96 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+/**
+ * ChatCCC 自己拉起替代进程时使用的内部标记。
+ *
+ * 不能用“是否已有配置”判断是否打开控制台：首次配置和日常直接启动都应该
+ * 打开，而 `/restart`、`/update` 和 Web UI 重启都不应该打扰用户。环境变量
+ * 会自然穿过 cmd/bash/npx 这几层启动器，因此也适用于 Windows 与 Linux。
+ */
+export const INTERNAL_RESTART_ENV_VAR = "CHATCCC_INTERNAL_RESTART";
+
+type Environment = Record<string, string | undefined>;
+
+export function createInternalRestartEnv(
+  inherited: Environment = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...inherited,
+    [INTERNAL_RESTART_ENV_VAR]: "1",
+  };
+}
+
+/** 用户直接启动时打开；ChatCCC 内部重启产生的替代进程不打开。 */
+interface AutoOpenWebUiOptions {
+  env?: Environment;
+  openOnStart?: boolean;
+}
+
+export function shouldAutoOpenWebUi(options: AutoOpenWebUiOptions = {}): boolean {
+  const env = options.env ?? process.env;
+  return options.openOnStart !== false && env[INTERNAL_RESTART_ENV_VAR] !== "1";
+}
+
+/** Web UI 始终使用 localhost，并跟随实际配置端口。 */
+export function buildWebUiUrl(port: number): string {
+  return `http://localhost:${port}/`;
+}
+
+interface OpenBrowserDeps {
+  platform?: NodeJS.Platform;
+  env?: Environment;
+  spawnImpl?: typeof spawn;
+  onError?: (message: string) => void;
+  onInfo?: (message: string) => void;
+}
+
+/**
+ * 调用操作系统默认浏览器打开 Web UI，与 Chrome CDP 守护功能完全独立。
+ * 返回值仅表示打开请求是否成功发起；浏览器是否复用标签页由系统浏览器决定。
+ */
+export function openWebUiInDefaultBrowser(
+  port: number,
+  deps: OpenBrowserDeps = {},
+): boolean {
+  const url = buildWebUiUrl(port);
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const spawnImpl = deps.spawnImpl ?? spawn;
+  const onError = deps.onError ?? ((message: string) => console.error(message));
+  const onInfo = deps.onInfo ?? ((message: string) => console.log(message));
+
+  // Linux 服务器通常没有图形会话。此时调用 xdg-open 只会制造噪音；
+  // 直接给出可复制的 SSH 隧道命令，让用户从自己的电脑访问本地 Web UI。
+  if (platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    onInfo(
+      `[WEB-UI] 未检测到 Linux 图形桌面，跳过自动打开浏览器。` +
+      `可在本机执行 ssh -L ${port}:127.0.0.1:${port} <user>@<server>，` +
+      `然后访问 ${url}`,
+    );
+    return false;
+  }
+
+  try {
+    let child: ChildProcess;
+    if (platform === "win32") {
+      // `start` 会把第一个带引号的参数当窗口标题，空字符串是必要占位符。
+      child = spawnImpl("cmd.exe", ["/c", "start", "", url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } else if (platform === "darwin") {
+      child = spawnImpl("open", [url], { detached: true, stdio: "ignore" });
+    } else {
+      child = spawnImpl("xdg-open", [url], { detached: true, stdio: "ignore" });
+    }
+    child.on("error", (err) => {
+      onError(`[WEB-UI] 自动打开浏览器失败: ${err.message}`);
+    });
+    child.unref();
+    return true;
+  } catch (err) {
+    onError(`[WEB-UI] 自动打开浏览器失败: ${(err as Error).message}`);
+    return false;
+  }
+}

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" };
+}