chatccc 0.2.190 → 0.2.191

package/src/session.ts

@@ -2,9 +2,9 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import {
-  CLAUDE_API_KEY,
-  CLAUDE_BASE_URL,
-  CLAUDE_MAX_TURN,
+  CLAUDE_API_KEY,
+  CLAUDE_BASE_URL,
+  CLAUDE_MAX_TURN,
   CLAUDE_MODEL,
   CLAUDE_SUBAGENT_MODEL,
   CHATCCC_PORT,
@@ -14,13 +14,13 @@ import {
   addRecentDir,
   anthropicConfigDisplay,
   config,
-  fileLog,
-  getDefaultCwd,
-  getDefaultEffortForTool,
-  isAnthropicConfigEmpty,
-  toolDisplayName,
-  ts,
-} from "./config.ts";
+  fileLog,
+  getDefaultCwd,
+  getDefaultEffortForTool,
+  isAnthropicConfigEmpty,
+  toolDisplayName,
+  ts,
+} from "./config.ts";
 import { buildProgressCard, getToolEmoji, isCodeBlockOpen, truncateContent } from "./cards.ts";
 import { simplifyToolUse, simplifyToolResult } from "./simplify.ts";
 import { logTrace } from "./trace.ts";
@@ -333,14 +333,14 @@ export function resetState(): void {
   for (const prompt of activePrompts.values()) {
     if (prompt.processMonitor) clearInterval(prompt.processMonitor);
   }
-  activePrompts.clear();
-  displayCards.clear();
-  sessionModelOverrides.clear();
-  sessionEffortOverrides.clear();
-  adapterCache.clear();
-  stopUnifiedDisplayLoop();
-  console.log(`[${ts()}] [RESET] State cleared (dedup + active sessions + bindings)`);
-}
+  activePrompts.clear();
+  displayCards.clear();
+  sessionModelOverrides.clear();
+  sessionEffortOverrides.clear();
+  adapterCache.clear();
+  stopUnifiedDisplayLoop();
+  console.log(`[${ts()}] [RESET] State cleared (dedup + active sessions + bindings)`);
+}
 
 // 注:`rebuildBindingsFromRegistry` 定义在下方与 loadSessionRegistry 同区域,
 // 是 onReady/onReconnected 取代 resetState 的正确入口。
@@ -352,8 +352,8 @@ export function resetState(): void {
 const adapterCache = new Map<string, ToolAdapter>();
 
 // Per-session 模型覆盖（/model 命令设置，不持久化）
-const sessionModelOverrides = new Map<string, string>();
-const sessionEffortOverrides = new Map<string, string>();
+const sessionModelOverrides = new Map<string, string>();
+const sessionEffortOverrides = new Map<string, string>();
 
 /** 返回 session 的生效模型：优先 per-session 覆盖，其次全局配置（Claude） */
 function getModelForSession(sessionId?: string): string {
@@ -365,26 +365,26 @@ function getModelForSession(sessionId?: string): string {
 }
 
 /** 返回指定 tool 的生效模型：优先 per-session 覆盖，其次 tool 默认配置 */
-export function getEffectiveModelForTool(tool: string, sessionId?: string): string {
-  if (sessionId) {
-    const override = sessionModelOverrides.get(sessionId);
-    if (override) return override;
-  }
+export function getEffectiveModelForTool(tool: string, sessionId?: string): string {
+  if (sessionId) {
+    const override = sessionModelOverrides.get(sessionId);
+    if (override) return override;
+  }
   if (tool === "cursor") return config.cursor.model;
   if (tool === "codex") return config.codex.model;
-  return CLAUDE_MODEL;
-}
-
-export function getEffectiveEffortForTool(tool: string, sessionId?: string): string {
-  if (sessionId) {
-    const override = sessionEffortOverrides.get(sessionId);
-    if (override) return override;
-  }
-  if (tool === "claude" || tool === "codex") {
-    return getDefaultEffortForTool(tool);
-  }
-  return "";
-}
+  return CLAUDE_MODEL;
+}
+
+export function getEffectiveEffortForTool(tool: string, sessionId?: string): string {
+  if (sessionId) {
+    const override = sessionEffortOverrides.get(sessionId);
+    if (override) return override;
+  }
+  if (tool === "claude" || tool === "codex") {
+    return getDefaultEffortForTool(tool);
+  }
+  return "";
+}
 
 /** 为指定 session 设置模型覆盖（/model <name>） */
 export function setSessionModelOverride(sessionId: string, model: string): void {
@@ -393,41 +393,41 @@ export function setSessionModelOverride(sessionId: string, model: string): void
 }
 
 /** 清除指定 session 的模型覆盖（/model clear） */
-export function clearSessionModelOverride(sessionId: string): void {
-  sessionModelOverrides.delete(sessionId);
-  adapterCache.clear();
-}
-
-export function setSessionEffortOverride(sessionId: string, effort: string): void {
-  sessionEffortOverrides.set(sessionId, effort);
-  adapterCache.clear();
-}
-
-export function clearSessionEffortOverride(sessionId: string): void {
-  sessionEffortOverrides.delete(sessionId);
-  adapterCache.clear();
-}
-
-export function getAdapterForTool(tool: string, sessionId?: string): ToolAdapter {
-  const effectiveModel = getEffectiveModelForTool(tool, sessionId);
-  const effectiveEffort = getEffectiveEffortForTool(tool, sessionId);
-  const cacheKey = `${tool}:${effectiveModel || ""}:${effectiveEffort || ""}`;
-  const cached = adapterCache.get(cacheKey);
-  if (cached) return cached;
-
-  let adapter: ToolAdapter;
-  if (tool === "cursor") {
-    adapter = createCursorAdapter({ model: effectiveModel || undefined });
-  } else if (tool === "codex") {
-    adapter = createCodexAdapter({ model: effectiveModel || undefined, effort: effectiveEffort || undefined });
-  } else {
-    adapter = createClaudeAdapter({
-      model: effectiveModel,
-      subagentModel: CLAUDE_SUBAGENT_MODEL,
-      effort: effectiveEffort,
-      apiKey: CLAUDE_API_KEY,
-      baseUrl: CLAUDE_BASE_URL,
-      isEmpty: isAnthropicConfigEmpty,
+export function clearSessionModelOverride(sessionId: string): void {
+  sessionModelOverrides.delete(sessionId);
+  adapterCache.clear();
+}
+
+export function setSessionEffortOverride(sessionId: string, effort: string): void {
+  sessionEffortOverrides.set(sessionId, effort);
+  adapterCache.clear();
+}
+
+export function clearSessionEffortOverride(sessionId: string): void {
+  sessionEffortOverrides.delete(sessionId);
+  adapterCache.clear();
+}
+
+export function getAdapterForTool(tool: string, sessionId?: string): ToolAdapter {
+  const effectiveModel = getEffectiveModelForTool(tool, sessionId);
+  const effectiveEffort = getEffectiveEffortForTool(tool, sessionId);
+  const cacheKey = `${tool}:${effectiveModel || ""}:${effectiveEffort || ""}`;
+  const cached = adapterCache.get(cacheKey);
+  if (cached) return cached;
+
+  let adapter: ToolAdapter;
+  if (tool === "cursor") {
+    adapter = createCursorAdapter({ model: effectiveModel || undefined });
+  } else if (tool === "codex") {
+    adapter = createCodexAdapter({ model: effectiveModel || undefined, effort: effectiveEffort || undefined });
+  } else {
+    adapter = createClaudeAdapter({
+      model: effectiveModel,
+      subagentModel: CLAUDE_SUBAGENT_MODEL,
+      effort: effectiveEffort,
+      apiKey: CLAUDE_API_KEY,
+      baseUrl: CLAUDE_BASE_URL,
+      isEmpty: isAnthropicConfigEmpty,
       maxTurn: CLAUDE_MAX_TURN,
     });
   }
@@ -855,18 +855,18 @@ export async function switchChatBinding(args: SwitchChatBindingArgs): Promise<Sw
 function formatToolConfigForLog(tool: string, sessionModel?: string, sessionId?: string): string {
   if (tool === "cursor") {
     return `model=${sessionModel ?? "(由 cursor-agent 决定，init 事件后学习)"}`;
-  }
-  if (tool === "codex") {
-    const m = getEffectiveModelForTool(tool, sessionId);
-    const e = getEffectiveEffortForTool(tool, sessionId);
+  }
+  if (tool === "codex") {
+    const m = getEffectiveModelForTool(tool, sessionId);
+    const e = getEffectiveEffortForTool(tool, sessionId);
     const modelStr = m.trim() !== "" ? m : "(由 codex config.toml 决定)";
     const effortStr = e.trim() !== ""
       ? `effort=${e}`
       : "effort=(由 codex config.toml 决定)";
     return `model=${modelStr}, ${effortStr}`;
   }
-  return `model=${anthropicConfigDisplay(getModelForSession(sessionId))}, subagentModel=${anthropicConfigDisplay(CLAUDE_SUBAGENT_MODEL)}, effort=${anthropicConfigDisplay(getEffectiveEffortForTool(tool, sessionId))}`;
-}
+  return `model=${anthropicConfigDisplay(getModelForSession(sessionId))}, subagentModel=${anthropicConfigDisplay(CLAUDE_SUBAGENT_MODEL)}, effort=${anthropicConfigDisplay(getEffectiveEffortForTool(tool, sessionId))}`;
+}
 
 export async function initClaudeSession(tool: string, overrideCwd?: string, chatId?: string): Promise<{ sessionId: string; cwd: string }> {
   const cwd = overrideCwd ?? (await getDefaultCwd(chatId));
@@ -981,12 +981,12 @@ export async function runAgentSession(
     const imSkillsCacheDir = join(USER_DATA_DIR, "im-skills");
     const skillVariables = {
       cwd,
-      session_id: sessionId,
-      im_skills_cache_dir: imSkillsCacheDir,
-      delegate_task_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/delegate-task`,
-      send_image_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-image`,
-      send_file_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-file`,
-      send_image_script: join(feishuSkillDir, "send-image.mjs"),
+      session_id: sessionId,
+      im_skills_cache_dir: imSkillsCacheDir,
+      delegate_task_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/delegate-task`,
+      send_image_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-image`,
+      send_file_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-file`,
+      send_image_script: join(feishuSkillDir, "send-image.mjs"),
       send_file_script: join(feishuSkillDir, "send-file.mjs"),
       download_video_script: join(feishuSkillDir, "download-video.mjs"),
       wechat_send_image_script: join(wechatImageSkillDir, "send-image.mjs"),
@@ -1780,20 +1780,20 @@ async function resolveModelEffort(
       // adapter 异常时降级为占位符（不阻塞 /state 卡片）
     }
     return { model, effort: null };
-  }
-  if (tool === "codex") {
-    const m = getEffectiveModelForTool(tool, sessionId);
-    const e = getEffectiveEffortForTool(tool, sessionId);
+  }
+  if (tool === "codex") {
+    const m = getEffectiveModelForTool(tool, sessionId);
+    const e = getEffectiveEffortForTool(tool, sessionId);
     return {
       model: m.trim() !== "" ? m : UNKNOWN_MODEL_PLACEHOLDER,
       effort: e.trim() !== "" ? e : UNKNOWN_MODEL_PLACEHOLDER,
     };
-  }
-  return {
-    model: anthropicConfigDisplay(getModelForSession(sessionId)),
-    effort: anthropicConfigDisplay(getEffectiveEffortForTool(tool, sessionId)),
-  };
-}
+  }
+  return {
+    model: anthropicConfigDisplay(getModelForSession(sessionId)),
+    effort: anthropicConfigDisplay(getEffectiveEffortForTool(tool, sessionId)),
+  };
+}
 
 export async function getSessionStatus(chatId: string): Promise<SessionStatus | null> {
   const info = sessionInfoMap.get(chatId);
@@ -1899,9 +1899,9 @@ export function _setAdapterForToolForTest(tool: string, adapter: ToolAdapter): v
   adapterCache.set(tool, adapter);
   // 同时设置当前配置模型对应的 key（getAdapterForTool 会优先 lookup 含 model 的 key）
   const effective = getEffectiveModelForTool(tool);
-  const effort = getEffectiveEffortForTool(tool);
-  adapterCache.set(`${tool}:${effective || ""}:${effort || ""}`, adapter);
-  if (effective) adapterCache.set(`${tool}:${effective}`, adapter);
+  const effort = getEffectiveEffortForTool(tool);
+  adapterCache.set(`${tool}:${effective || ""}:${effort || ""}`, adapter);
+  if (effective) adapterCache.set(`${tool}:${effective}`, adapter);
 }
 
 export function clearAdapterCache(): void {

package/src/shared-prefix.ts

@@ -1,29 +1,29 @@
-export const ABD_PREFIX = "/abd";
-
-export const ABD_APPEND_PROMPT =
-  "请从第一性原理出发挖掘我的真实需求。你觉得我的需求合理吗？开始实现之前有什么问题要问我的？";
-
-export const ABD_HELP_LINE =
-  `发送 **${ABD_PREFIX}** 前缀消息，将以第一性原理追问真实需求、合理性和实现前问题`;
-
-export interface SharedPrefixResult {
-  matched: boolean;
-  text: string;
-  body: string;
-  prefix?: typeof ABD_PREFIX;
-}
-
-export function applySharedPrefix(text: string): SharedPrefixResult {
-  if (!text.toLowerCase().startsWith(ABD_PREFIX)) {
-    return { matched: false, text, body: text };
-  }
-
-  const body = text.slice(ABD_PREFIX.length).replace(/^\s+/, "");
-  const appendix = ["---", ABD_APPEND_PROMPT].join("\n");
-  return {
-    matched: true,
-    prefix: ABD_PREFIX,
-    body,
-    text: body ? [body, appendix].join("\n\n") : appendix,
-  };
-}
+export const ABD_PREFIX = "/abd";
+
+export const ABD_APPEND_PROMPT =
+  "请从第一性原理出发挖掘我的真实需求。你觉得我的需求合理吗？开始实现之前有什么问题要问我的？";
+
+export const ABD_HELP_LINE =
+  `发送 **${ABD_PREFIX}** 前缀消息，将以第一性原理追问真实需求、合理性和实现前问题`;
+
+export interface SharedPrefixResult {
+  matched: boolean;
+  text: string;
+  body: string;
+  prefix?: typeof ABD_PREFIX;
+}
+
+export function applySharedPrefix(text: string): SharedPrefixResult {
+  if (!text.toLowerCase().startsWith(ABD_PREFIX)) {
+    return { matched: false, text, body: text };
+  }
+
+  const body = text.slice(ABD_PREFIX.length).replace(/^\s+/, "");
+  const appendix = ["---", ABD_APPEND_PROMPT].join("\n");
+  return {
+    matched: true,
+    prefix: ABD_PREFIX,
+    body,
+    text: body ? [body, appendix].join("\n\n") : appendix,
+  };
+}

package/src/sim-platform.ts

@@ -123,25 +123,25 @@ export const SimulatedPlatform: FeishuPlatform = {
   },
 
   // ---- 头像 ----
-  async setChatAvatar(_token, _chatId, _tool, _status) {
-    // 模拟模式不需要头像
-  },
-
-  async getCodexUsageSummary() {
-    return {
-      fiveHour: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
-      weekly: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
-      rateLimitResetCreditsAvailable: null,
-      rateLimitResetCredits: null,
-    };
-  },
-
-  async consumeCodexRateLimitResetCredit(_redeemRequestId) {
-    return { code: "no_credit" as const, windowsReset: 0 };
-  },
-
-  // ---- 图片下载 ----
-  async getOrDownloadImage(_token, _messageId, fileKey) {
+  async setChatAvatar(_token, _chatId, _tool, _status) {
+    // 模拟模式不需要头像
+  },
+
+  async getCodexUsageSummary() {
+    return {
+      fiveHour: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
+      weekly: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
+      rateLimitResetCreditsAvailable: null,
+      rateLimitResetCredits: null,
+    };
+  },
+
+  async consumeCodexRateLimitResetCredit(_redeemRequestId) {
+    return { code: "no_credit" as const, windowsReset: 0 };
+  },
+
+  // ---- 图片下载 ----
+  async getOrDownloadImage(_token, _messageId, fileKey) {
     return join(SIM_DIR, "images", fileKey);
   },
 
@@ -174,4 +174,4 @@ export const SimulatedPlatform: FeishuPlatform = {
 };
 
 /** 模拟模式下的默认 chat_id（重新导出以保持向后兼容） */
-export { SIM_DEFAULT_CHAT_ID } from "./sim-store.ts";
+export { SIM_DEFAULT_CHAT_ID } from "./sim-store.ts";

package/src/turn-cards.ts

@@ -1,118 +1,118 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import { USER_DATA_DIR, ts } from "./config.ts";
-
-// ---------------------------------------------------------------------------
-// turn-cards.json — 每个 session 的卡片归属持久化
-// 记录每个 turn 有哪些卡片（轮转会产生多张），以及每张卡片的状态
-// ---------------------------------------------------------------------------
-
-export const TURNS_DIR = join(USER_DATA_DIR, "state", "turns");
-
-export interface TurnCardEntry {
-  cardId: string;
-  status: "active" | "done" | "stopped";
-  createdAt: number;
-}
-
-export interface TurnCardsFile {
-  sessionId: string;
-  turns: { turnCount: number; cards: TurnCardEntry[] }[];
-}
-
-function getTurnCardsPath(sessionId: string): string {
-  return join(TURNS_DIR, `${sessionId}.json`);
-}
-
-export function createEmptyTurnCards(sessionId: string): TurnCardsFile {
-  return { sessionId, turns: [] };
-}
-
-export async function readTurnCards(sessionId: string): Promise<TurnCardsFile | null> {
-  try {
-    const raw = await readFile(getTurnCardsPath(sessionId), "utf-8");
-    const parsed = JSON.parse(raw) as TurnCardsFile;
-    if (parsed && typeof parsed.sessionId === "string" && Array.isArray(parsed.turns)) {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-export async function writeTurnCards(sessionId: string, data: TurnCardsFile): Promise<void> {
-  try {
-    const filePath = getTurnCardsPath(sessionId);
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
-  } catch (err) {
-    console.error(`[${ts()}] Failed to write turn-cards for ${sessionId}: ${(err as Error).message}`);
-  }
-}
-
-/** 向指定 turn 追加一张卡片并持久化。若 turn 不存在则创建。 */
-export async function addCardToTurn(
-  sessionId: string,
-  turnCount: number,
-  cardId: string,
-): Promise<void> {
-  const data = (await readTurnCards(sessionId)) ?? createEmptyTurnCards(sessionId);
-  let turn = data.turns.find(t => t.turnCount === turnCount);
-  if (!turn) {
-    turn = { turnCount, cards: [] };
-    data.turns.push(turn);
-  }
-  turn.cards.push({ cardId, status: "active", createdAt: Date.now() });
-  await writeTurnCards(sessionId, data);
-}
-
-/** 将指定 turn 的所有 active 卡片标记为终态并持久化。返回被标记的 cardId 列表。 */
-export async function finalizeTurnCards(
-  sessionId: string,
-  turnCount: number,
-  finalStatus: "done" | "stopped",
-): Promise<string[]> {
-  const data = await readTurnCards(sessionId);
-  if (!data) return [];
-  const turn = data.turns.find(t => t.turnCount === turnCount);
-  if (!turn) return [];
-  const finalized: string[] = [];
-  for (const card of turn.cards) {
-    if (card.status === "active") {
-      card.status = finalStatus;
-      finalized.push(card.cardId);
-    }
-  }
-  if (finalized.length > 0) {
-    await writeTurnCards(sessionId, data);
-  }
-  return finalized;
-}
-
-/** 将指定 turn 中的一张 active 卡片标记为 done（轮转时用），并持久化。 */
-export async function markCardDone(
-  sessionId: string,
-  turnCount: number,
-  cardId: string,
-): Promise<void> {
-  const data = await readTurnCards(sessionId);
-  if (!data) return;
-  const turn = data.turns.find(t => t.turnCount === turnCount);
-  if (!turn) return;
-  const card = turn.cards.find(c => c.cardId === cardId && c.status === "active");
-  if (!card) return;
-  card.status = "done";
-  await writeTurnCards(sessionId, data);
-}
-
-/** 清理 session 的 turn-cards 文件 */
-export async function removeTurnCards(sessionId: string): Promise<void> {
-  try {
-    const { unlink } = await import("node:fs/promises");
-    await unlink(getTurnCardsPath(sessionId));
-  } catch {
-    // 文件不存在，忽略
-  }
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { USER_DATA_DIR, ts } from "./config.ts";
+
+// ---------------------------------------------------------------------------
+// turn-cards.json — 每个 session 的卡片归属持久化
+// 记录每个 turn 有哪些卡片（轮转会产生多张），以及每张卡片的状态
+// ---------------------------------------------------------------------------
+
+export const TURNS_DIR = join(USER_DATA_DIR, "state", "turns");
+
+export interface TurnCardEntry {
+  cardId: string;
+  status: "active" | "done" | "stopped";
+  createdAt: number;
+}
+
+export interface TurnCardsFile {
+  sessionId: string;
+  turns: { turnCount: number; cards: TurnCardEntry[] }[];
+}
+
+function getTurnCardsPath(sessionId: string): string {
+  return join(TURNS_DIR, `${sessionId}.json`);
+}
+
+export function createEmptyTurnCards(sessionId: string): TurnCardsFile {
+  return { sessionId, turns: [] };
+}
+
+export async function readTurnCards(sessionId: string): Promise<TurnCardsFile | null> {
+  try {
+    const raw = await readFile(getTurnCardsPath(sessionId), "utf-8");
+    const parsed = JSON.parse(raw) as TurnCardsFile;
+    if (parsed && typeof parsed.sessionId === "string" && Array.isArray(parsed.turns)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeTurnCards(sessionId: string, data: TurnCardsFile): Promise<void> {
+  try {
+    const filePath = getTurnCardsPath(sessionId);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+  } catch (err) {
+    console.error(`[${ts()}] Failed to write turn-cards for ${sessionId}: ${(err as Error).message}`);
+  }
+}
+
+/** 向指定 turn 追加一张卡片并持久化。若 turn 不存在则创建。 */
+export async function addCardToTurn(
+  sessionId: string,
+  turnCount: number,
+  cardId: string,
+): Promise<void> {
+  const data = (await readTurnCards(sessionId)) ?? createEmptyTurnCards(sessionId);
+  let turn = data.turns.find(t => t.turnCount === turnCount);
+  if (!turn) {
+    turn = { turnCount, cards: [] };
+    data.turns.push(turn);
+  }
+  turn.cards.push({ cardId, status: "active", createdAt: Date.now() });
+  await writeTurnCards(sessionId, data);
+}
+
+/** 将指定 turn 的所有 active 卡片标记为终态并持久化。返回被标记的 cardId 列表。 */
+export async function finalizeTurnCards(
+  sessionId: string,
+  turnCount: number,
+  finalStatus: "done" | "stopped",
+): Promise<string[]> {
+  const data = await readTurnCards(sessionId);
+  if (!data) return [];
+  const turn = data.turns.find(t => t.turnCount === turnCount);
+  if (!turn) return [];
+  const finalized: string[] = [];
+  for (const card of turn.cards) {
+    if (card.status === "active") {
+      card.status = finalStatus;
+      finalized.push(card.cardId);
+    }
+  }
+  if (finalized.length > 0) {
+    await writeTurnCards(sessionId, data);
+  }
+  return finalized;
+}
+
+/** 将指定 turn 中的一张 active 卡片标记为 done（轮转时用），并持久化。 */
+export async function markCardDone(
+  sessionId: string,
+  turnCount: number,
+  cardId: string,
+): Promise<void> {
+  const data = await readTurnCards(sessionId);
+  if (!data) return;
+  const turn = data.turns.find(t => t.turnCount === turnCount);
+  if (!turn) return;
+  const card = turn.cards.find(c => c.cardId === cardId && c.status === "active");
+  if (!card) return;
+  card.status = "done";
+  await writeTurnCards(sessionId, data);
+}
+
+/** 清理 session 的 turn-cards 文件 */
+export async function removeTurnCards(sessionId: string): Promise<void> {
+  try {
+    const { unlink } = await import("node:fs/promises");
+    await unlink(getTurnCardsPath(sessionId));
+  } catch {
+    // 文件不存在，忽略
+  }
 }