chatccc 0.2.19 → 0.2.21

package/README.md

@@ -12,7 +12,7 @@ ChatCCC 把 Claude Code、Cursor Agent、Codex (OpenAI) 接入了飞书群聊：
 
 - **手机上也能用 Claude Code / Cursor / Codex** —— 在飞书群里发消息就等于在终端输入指令，AI 的思考和回复会流式展示在群卡片里
 - **多会话并行** —— 一个群就是一个 AI 会话，完全隔离、互不干扰，并行工作效率更高
-- **多工具切换** —— `/new claude` 创建 Claude Code 会话，`/new cursor` 创建 Cursor 会话，`/new codex` 创建 Codex 会话，各取所长
+- **多工具切换** —— `/new` 使用默认 Agent 创建会话，也可用 `/new claude`、`/new cursor`、`/new codex` 指定工具，各取所长
 
 一句话：**在任何设备上打开飞书，就能让 Claude Code / Cursor / Codex 帮你写代码、排查问题、分析项目。**
 
@@ -118,7 +118,7 @@ ChatCCC 启动时会按以下顺序确定 Cursor Agent CLI：
 
 > 旧版字段 `cursor.command` 仍可读取（启动时会打印一次 warning 提示改名），新配置请统一使用 `cursor.path`。
 
-> **说明**：只使用 Claude Code（`/new claude` 或 `/new`）的用户无需安装 Cursor CLI。
+> **说明**：只使用 Claude Code（`/new claude`，或把 Claude Code 设为默认 Agent 后使用 `/new`）的用户无需安装 Cursor CLI。
 
 #### Codex CLI（使用 Codex 会话时需要）
 
@@ -215,21 +215,24 @@ ChatCCC 的所有运行参数都集中在包根目录的 `config.json`。
   },
   "port": 18080,
   "gitTimeoutSeconds": 180,
-  "claude": {
-    "enabled": false,
-    "model": "",
+  "claude": {
+    "enabled": false,
+    "defaultAgent": true,
+    "model": "",
     "effort": "",
     "apiKey": "",
     "baseUrl": ""
   },
-  "cursor": {
-    "enabled": false,
-    "path": "",
+  "cursor": {
+    "enabled": false,
+    "defaultAgent": false,
+    "path": "",
     "model": ""
   },
-  "codex": {
-    "enabled": false,
-    "path": "",
+  "codex": {
+    "enabled": false,
+    "defaultAgent": false,
+    "path": "",
     "model": "",
     "effort": ""
   }
@@ -242,9 +245,10 @@ ChatCCC 的所有运行参数都集中在包根目录的 `config.json`。
 | --- | --- | --- |
 | `feishu.appId` / `feishu.appSecret` | 是 | 飞书应用「凭证与基础信息」中的 App ID / App Secret |
 | `port` | 否 | 本地 WebSocket 中继 + Web 向导监听端口，默认 `18080`；同机多实例时改成不同值即可 |
-| `gitTimeoutSeconds` | 否 | `/git` 命令在会话工作目录执行时的单次超时秒数，默认 `180`，允许范围 `1–3600`，超时会被 `SIGKILL` 强制终止 |
-| `claude.enabled` / `cursor.enabled` / `codex.enabled` | 否 | 是否启用对应 AI Agent；Web 向导/管理页只展示 `enabled: true` 的 agent 卡片。字段缺省时按「任一配置字段非空」自动判定（向后兼容） |
-| `claude.model` | 否 | Claude Code 会话使用的模型；留空（`""` / 全空白）→ 不向 SDK 传 `model`，由 SDK / 服务商默认决定 |
+| `gitTimeoutSeconds` | 否 | `/git` 命令在会话工作目录执行时的单次超时秒数，默认 `180`，允许范围 `1–3600`，超时会被 `SIGKILL` 强制终止 |
+| `claude.enabled` / `cursor.enabled` / `codex.enabled` | 否 | 是否启用对应 AI Agent；Web 向导/管理页只展示 `enabled: true` 的 agent 卡片。字段缺省时按「任一配置字段非空」自动判定（向后兼容） |
+| `claude.defaultAgent` / `cursor.defaultAgent` / `codex.defaultAgent` | 否 | `/new` 未指定具体 Agent 时使用哪个默认 Agent；同一时间应只有一个为 `true`。Web 配置页切换某个 Agent 为默认时会自动关闭其它 Agent 的默认开关 |
+| `claude.model` | 否 | Claude Code 会话使用的模型；留空（`""` / 全空白）→ 不向 SDK 传 `model`，由 SDK / 服务商默认决定 |
 | `claude.effort` | 否 | Claude 思考深度（如 `low` / `medium` / `high` / `max`）；留空 → 不向 SDK 传 `effort` |
 | `claude.apiKey` | 否 | 第三方 Anthropic 兼容网关的 API 密钥；**官方 Claude 用户保持 `""` 即可**，详见下文「第三方 API」一节 |
 | `claude.baseUrl` | 否 | 第三方 Anthropic 兼容网关的 base URL（例如 `https://api.deepseek.com/anthropic`）；**官方 Claude 用户保持 `""` 即可** |
@@ -289,14 +293,14 @@ ChatCCC 的所有运行参数都集中在包根目录的 `config.json`。
 
 ### 5. 开始使用
 
-在飞书中找到你的机器人，发送 `/new`（默认 Claude Code）或 `/new claude` / `/new cursor` / `/new codex`，机器人会自动创建一个群聊并把 AI 会话绑定到该群。之后直接在群里发消息就能对话。
+在飞书中找到你的机器人，发送 `/new`（使用 `config.json` 中 `defaultAgent: true` 的默认 Agent）或 `/new claude` / `/new cursor` / `/new codex`，机器人会自动创建一个群聊并把 AI 会话绑定到该群。之后直接在群里发消息就能对话。
 
 ### 可用指令
 
 
 | 指令            | 作用                           |
 | --------------- | ---------------------------- |
-| `/new`          | 创建新的 Claude Code 会话（默认）    |
+| `/new`          | 使用默认 Agent 创建新会话            |
 | `/new claude`   | 创建新的 Claude Code 会话          |
 | `/new cursor`   | 创建新的 Cursor 会话               |
 | `/new codex`    | 创建新的 Codex 会话（OpenAI）         |
@@ -313,4 +317,4 @@ ChatCCC 的所有运行参数都集中在包根目录的 `config.json`。
 
 ## 技术栈
 
-TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / Cursor Agent CLI / Codex CLI (OpenAI) / 飞书 WebSocket API / CardKit
+TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / Cursor Agent CLI / Codex CLI (OpenAI) / 飞书 WebSocket API / CardKit

package/config.sample.json

@@ -7,6 +7,7 @@
   "gitTimeoutSeconds": 180,
   "claude": {
     "enabled": false,
+    "defaultAgent": true,
     "model": "",
     "effort": "",
     "apiKey": "",
@@ -14,11 +15,13 @@
   },
   "cursor": {
     "enabled": false,
+    "defaultAgent": false,
     "path": "",
     "model": ""
   },
   "codex": {
     "enabled": false,
+    "defaultAgent": false,
     "path": "",
     "model": "",
     "effort": ""

package/package.json

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

package/src/__tests__/config-reload.test.ts

@@ -16,10 +16,11 @@ import {
   CURSOR_AGENT_COMMAND,
   GIT_TIMEOUT_MS,
   GIT_TIMEOUT_SECONDS,
-  applyLoadedConfig,
-  config,
-  type AppConfig,
-} from "../config.ts";
+  applyLoadedConfig,
+  config,
+  resolveDefaultAgentTool,
+  type AppConfig,
+} from "../config.ts";
 
 // ---------------------------------------------------------------------------
 // applyLoadedConfig — setup → service「在线切换」时刷新进程内 config 的核心机制
@@ -36,15 +37,16 @@ const baseAppConfig: AppConfig = {
   feishu: { appId: "INITIAL_APP", appSecret: "INITIAL_SECRET" },
   port: 18080,
   gitTimeoutSeconds: 180,
-  claude: {
-    enabled: true,
-    model: "initial-model",
+  claude: {
+    enabled: true,
+    defaultAgent: true,
+    model: "initial-model",
     effort: "initial-effort",
     apiKey: "sk-initial",
     baseUrl: "https://initial.gw/anthropic",
   },
-  cursor: { enabled: true, path: "/initial/cursor", model: "initial-cursor-model" },
-  codex: { enabled: true, path: "/initial/codex", model: "initial-codex-model", effort: "initial-codex-effort" },
+  cursor: { enabled: true, defaultAgent: false, path: "/initial/cursor", model: "initial-cursor-model" },
+  codex: { enabled: true, defaultAgent: false, path: "/initial/codex", model: "initial-codex-model", effort: "initial-codex-effort" },
 };
 
 // 把 module 状态抢救快照：每个 it 跑前重置回这个状态，避免污染相邻测试。
@@ -75,9 +77,10 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
   it("更新 Claude 配置（model / effort / apiKey / baseUrl）", () => {
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
-      claude: {
-        enabled: true,
-        model: "deepseek-v4-pro",
+      claude: {
+        enabled: true,
+        defaultAgent: true,
+        model: "deepseek-v4-pro",
         effort: "high",
         apiKey: "sk-newkey",
         baseUrl: "https://gw2.example/anthropic",
@@ -104,7 +107,7 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
   it("CURSOR_AGENT_ARGS 跟随 cursor.model 重新解析", () => {
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
-      cursor: { enabled: true, path: "/x/cursor", model: "claude-3.7-sonnet" },
+      cursor: { enabled: true, defaultAgent: false, path: "/x/cursor", model: "claude-3.7-sonnet" },
     });
 
     // CURSOR_AGENT_ARGS 是 ['-p', '--force', ..., '--model', 'claude-3.7-sonnet']
@@ -115,7 +118,7 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
   it("cursor.model 留空时 CURSOR_AGENT_ARGS 不含 --model", () => {
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
-      cursor: { enabled: true, path: "/x/cursor", model: "" },
+      cursor: { enabled: true, defaultAgent: false, path: "/x/cursor", model: "" },
     });
 
     expect(CURSOR_AGENT_ARGS).not.toContain("--model");
@@ -124,7 +127,7 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
   it("CURSOR_AGENT_COMMAND 优先取 config.cursor.path", () => {
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
-      cursor: { enabled: true, path: "C:/custom/cursor.exe", model: "" },
+      cursor: { enabled: true, defaultAgent: false, path: "C:/custom/cursor.exe", model: "" },
     });
 
     expect(CURSOR_AGENT_COMMAND).toBe("C:/custom/cursor.exe");
@@ -142,14 +145,14 @@ describe("applyLoadedConfig — 刷新 export let 常量", () => {
   });
 });
 
-describe("applyLoadedConfig — config 对象引用契约", () => {
+describe("applyLoadedConfig — config 对象引用契约", () => {
   it("config 引用保持不变（就地更新），但字段被刷新", () => {
     const refBefore = config;
 
     applyLoadedConfig({
       ...structuredClone(baseAppConfig),
       feishu: { appId: "REF_TEST_APP", appSecret: "REF_TEST_SECRET" },
-      codex: { enabled: true, path: "/refresh/codex", model: "fresh-model", effort: "low" },
+      codex: { enabled: true, defaultAgent: false, path: "/refresh/codex", model: "fresh-model", effort: "low" },
     });
 
     // 必须是同一个引用：codex-adapter 等下游模块"直接 import config"，
@@ -167,5 +170,24 @@ describe("applyLoadedConfig — config 对象引用契约", () => {
     expect(APP_ID).toBe("");
     expect(APP_SECRET).toBe("");
     expect(config.feishu.appId).toBe("");
-  });
-});
+  });
+});
+
+describe("resolveDefaultAgentTool", () => {
+  it("优先使用显式 defaultAgent 且已启用的 Agent", () => {
+    const cfg = structuredClone(baseAppConfig);
+    cfg.claude.defaultAgent = false;
+    cfg.cursor.defaultAgent = true;
+
+    expect(resolveDefaultAgentTool(cfg)).toBe("cursor");
+  });
+
+  it("defaultAgent 指向未启用 Agent 时回退到第一个已启用 Agent", () => {
+    const cfg = structuredClone(baseAppConfig);
+    cfg.claude.enabled = false;
+    cfg.claude.defaultAgent = true;
+    cfg.cursor.defaultAgent = false;
+
+    expect(resolveDefaultAgentTool(cfg)).toBe("cursor");
+  });
+});

package/src/cards.ts

@@ -108,13 +108,17 @@ export function buildProgressCard(
   });
 }
 
-export function buildHelpCard(userText: string, opts: { greeting?: string } = {}): string {
-  const greeting = opts.greeting ?? `你发送了: ${userText}`;
-  const lines = [
-    "发送 **/new** 创建新会话（默认 Claude Code）",
-    "发送 **/new claude** 创建新 Claude 对话",
-    "发送 **/new cursor** 创建新 Cursor 会话",
-    "发送 **/new codex** 创建新 Codex 会话",
+export function buildHelpCard(
+  userText: string,
+  opts: { greeting?: string; defaultToolLabel?: string } = {},
+): string {
+  const greeting = opts.greeting ?? `你发送了: ${userText}`;
+  const defaultToolLabel = opts.defaultToolLabel ?? "Claude Code";
+  const lines = [
+    `发送 **/new** 创建新会话（默认 ${defaultToolLabel}）`,
+    "发送 **/new claude** 创建新 Claude 对话",
+    "发送 **/new cursor** 创建新 Cursor 会话",
+    "发送 **/new codex** 创建新 Codex 会话",
     "发送 **/forget** 重置当前会话（保留工作目录，同一群内继续）",
   ].join("\n");
   return JSON.stringify({
@@ -124,7 +128,7 @@ export function buildHelpCard(userText: string, opts: { greeting?: string } = {}
       { tag: "div", text: { tag: "lark_md", content: greeting } },
       { tag: "div", text: { tag: "lark_md", content: lines } },
       buildButtons([
-        { text: "新建 Claude Code 会话（/new claude）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
+        { text: `新建默认会话（/new，${defaultToolLabel}）`, value: JSON.stringify({ cmd: "new" }), type: "primary" },
         { text: "新建 Cursor 会话（/new cursor）", value: JSON.stringify({ cmd: "new cursor" }), type: "primary" },
         { text: "新建 Codex 会话（/new codex）", value: JSON.stringify({ cmd: "new codex" }), type: "primary" },
         { text: "重启 ChatCCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
@@ -248,14 +252,15 @@ export function buildCdCard(
 }
 
 // 所有会话列表卡片（Claude Code 优先，然后 Cursor）
-export function buildSessionsCard(sessions: Array<{
-  sessionId: string;
-  active: boolean;
-  turnCount: number;
-  elapsedSeconds: number | null;
-  model: string;
-  tool: string;
-}>): string {
+export function buildSessionsCard(sessions: Array<{
+  sessionId: string;
+  active: boolean;
+  turnCount: number;
+  elapsedSeconds: number | null;
+  model: string;
+  tool: string;
+}>, opts: { defaultToolLabel?: string } = {}): string {
+  const defaultToolLabel = opts.defaultToolLabel ?? "Claude Code";
   // 按 tool 分组排序：Claude Code 在前，Cursor 其次，Codex 最后
   const claudeCodeSessions = sessions.filter(s => s.tool !== "cursor" && s.tool !== "codex");
   const cursorSessions = sessions.filter(s => s.tool === "cursor");
@@ -269,7 +274,7 @@ export function buildSessionsCard(sessions: Array<{
       config: { wide_screen_mode: true },
       header: { template: "blue", title: { content: "所有会话", tag: "plain_text" } },
       elements: [
-        { tag: "div", text: { tag: "lark_md", content: "当前没有会话记录。\n\n使用 **/new**（默认 Claude Code）、**/new claude**、**/new cursor** 或 **/new codex** 创建新会话。" } },
+        { tag: "div", text: { tag: "lark_md", content: `当前没有会话记录。\n\n使用 **/new**（默认 ${defaultToolLabel}）、**/new claude**、**/new cursor** 或 **/new codex** 创建新会话。` } },
         { tag: "hr" },
         { tag: "action", actions: [{ tag: "button", text: { tag: "plain_text", content: "收起" }, type: "default", value: { action: "close" } }] },
       ],
@@ -355,4 +360,4 @@ export function buildStatusCard(statusText: string, template = "blue"): string {
       },
     ],
   });
-}
+}

package/src/config.ts

@@ -58,6 +58,8 @@ export async function appendChatLog(chatId: string, sender: string, text: string
 export interface ClaudeConfig {
   /** 是否启用 Claude Code Agent；缺省时按"有任意字段非空"自动判定（向后兼容） */
   enabled: boolean;
+  /** 是否作为 /new 未指定工具时使用的默认 Agent */
+  defaultAgent: boolean;
   model: string;
   effort: string;
   apiKey: string;
@@ -67,6 +69,8 @@ export interface ClaudeConfig {
 export interface CursorConfig {
   /** 是否启用 Cursor Agent；缺省时按"有任意字段非空"自动判定（向后兼容） */
   enabled: boolean;
+  /** 是否作为 /new 未指定工具时使用的默认 Agent */
+  defaultAgent: boolean;
   /** Cursor Agent CLI 可执行文件绝对路径；留空时由运行时按 LocalAppData / PATH 兜底 */
   path: string;
   model: string;
@@ -75,6 +79,8 @@ export interface CursorConfig {
 export interface CodexConfig {
   /** 是否启用 Codex Agent；缺省时按"有任意字段非空"自动判定（向后兼容） */
   enabled: boolean;
+  /** 是否作为 /new 未指定工具时使用的默认 Agent */
+  defaultAgent: boolean;
   /** Codex CLI 可执行文件绝对路径；留空时退回到 PATH 中的 `codex` */
   path: string;
   model: string;
@@ -95,6 +101,9 @@ export interface AppConfig {
   codex: CodexConfig;
 }
 
+export type AgentTool = "claude" | "cursor" | "codex";
+export const AGENT_TOOLS: AgentTool[] = ["claude", "cursor", "codex"];
+
 const CONFIG_FILE = join(PROJECT_ROOT, "config.json");
 const CONFIG_SAMPLE_FILE = join(PROJECT_ROOT, "config.sample.json");
 
@@ -203,9 +212,9 @@ function loadConfig(): AppConfig {
     feishu: { appId: "", appSecret: "" },
     port: 18080,
     gitTimeoutSeconds: 180,
-    claude: { enabled: false, model: "", effort: "", apiKey: "", baseUrl: "" },
-    cursor: { enabled: false, path: "", model: "claude-opus-4-7-max" },
-    codex: { enabled: false, path: "", model: "", effort: "" },
+    claude: { enabled: false, defaultAgent: true, model: "", effort: "", apiKey: "", baseUrl: "" },
+    cursor: { enabled: false, defaultAgent: false, path: "", model: "claude-opus-4-7-max" },
+    codex: { enabled: false, defaultAgent: false, path: "", model: "", effort: "" },
   };
 
   if (!existsSync(CONFIG_FILE)) {
@@ -239,8 +248,8 @@ function loadConfig(): AppConfig {
 
   let parsed: Partial<AppConfig> & {
     claude?: Partial<ClaudeConfig> & { enabled?: unknown };
-    cursor?: { enabled?: unknown; path?: unknown; command?: unknown; model?: unknown };
-    codex?: { enabled?: unknown; path?: unknown; command?: unknown; model?: unknown; effort?: unknown };
+    cursor?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown };
+    codex?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown; effort?: unknown };
   };
   try {
     parsed = JSON.parse(raw);
@@ -251,8 +260,8 @@ function loadConfig(): AppConfig {
 
   const feishu = parsed.feishu ?? { appId: "", appSecret: "" };
   const claude = parsed.claude ?? {} as Partial<ClaudeConfig>;
-  const cursorRaw = parsed.cursor ?? {};
-  const codexRaw = parsed.codex ?? {};
+  const cursorRaw = (parsed.cursor ?? {}) as NonNullable<typeof parsed.cursor>;
+  const codexRaw = (parsed.codex ?? {}) as NonNullable<typeof parsed.codex>;
 
   // 兼容旧字段 `command`：命中时打印一次性 warning 提示用户改名
   const onLegacyField = (label: string, value: string): void => {
@@ -292,6 +301,21 @@ function loadConfig(): AppConfig {
       (typeof codexRaw.effort === "string" && (codexRaw.effort as string).trim()),
     );
 
+  const claudeEnabled = resolveEnabled(claude.enabled, claudeNonEmpty);
+  const cursorEnabled = resolveEnabled(cursorRaw.enabled, cursorNonEmpty);
+  const codexEnabled = resolveEnabled(codexRaw.enabled, codexNonEmpty);
+  const explicitDefaultTool: AgentTool | null =
+    typeof claude.defaultAgent === "boolean" && claude.defaultAgent && claudeEnabled ? "claude" :
+    typeof cursorRaw.defaultAgent === "boolean" && cursorRaw.defaultAgent && cursorEnabled ? "cursor" :
+    typeof codexRaw.defaultAgent === "boolean" && codexRaw.defaultAgent && codexEnabled ? "codex" :
+    null;
+  const fallbackDefaultTool: AgentTool =
+    claudeEnabled ? "claude" :
+    cursorEnabled ? "cursor" :
+    codexEnabled ? "codex" :
+    "claude";
+  const defaultTool = explicitDefaultTool ?? fallbackDefaultTool;
+
   return {
     feishu: {
       appId: feishu.appId ?? "",
@@ -300,19 +324,22 @@ function loadConfig(): AppConfig {
     port: typeof parsed.port === "number" ? parsed.port : 18080,
     gitTimeoutSeconds: typeof parsed.gitTimeoutSeconds === "number" ? parsed.gitTimeoutSeconds : 180,
     claude: {
-      enabled: resolveEnabled(claude.enabled, claudeNonEmpty),
+      enabled: claudeEnabled,
+      defaultAgent: defaultTool === "claude",
       model: normalizeOptionalConfigField(claude.model, { label: "claude.model" }),
       effort: normalizeOptionalConfigField(claude.effort, { label: "claude.effort" }),
       apiKey: claude.apiKey ?? "",
       baseUrl: claude.baseUrl ?? "",
     },
     cursor: {
-      enabled: resolveEnabled(cursorRaw.enabled, cursorNonEmpty),
+      enabled: cursorEnabled,
+      defaultAgent: defaultTool === "cursor",
       path: readToolCliPath(cursorRaw, { label: "cursor", onLegacyField }),
       model: normalizeOptionalConfigField(cursorRaw.model, { label: "cursor.model", fallback: "claude-opus-4-7-max" }),
     },
     codex: {
-      enabled: resolveEnabled(codexRaw.enabled, codexNonEmpty),
+      enabled: codexEnabled,
+      defaultAgent: defaultTool === "codex",
       path: readToolCliPath(codexRaw, { label: "codex", onLegacyField }),
       model: normalizeOptionalConfigField(codexRaw.model, { label: "codex.model" }),
       effort: normalizeOptionalConfigField(codexRaw.effort, { label: "codex.effort" }),
@@ -612,5 +639,13 @@ export function toolDisplayName(tool: string): string {
   return "Claude Code";
 }
 
+/** 解析 /new 未指定工具时使用的默认 Agent。旧配置缺省 defaultAgent 时保持 Claude 优先。 */
+export function resolveDefaultAgentTool(cfg: AppConfig = config): AgentTool {
+  const explicit = AGENT_TOOLS.find((tool) => cfg[tool].enabled && cfg[tool].defaultAgent);
+  if (explicit) return explicit;
+  const enabledFallback = AGENT_TOOLS.find((tool) => cfg[tool].enabled);
+  return enabledFallback ?? "claude";
+}
+
 // 导出 config 对象供其他模块直接访问原始配置
-export { CONFIG_FILE, CONFIG_SAMPLE_FILE };
+export { CONFIG_FILE, CONFIG_SAMPLE_FILE };

package/src/feishu-api.ts

@@ -1,6 +1,6 @@
-import { readdir, stat, readFile, mkdir, writeFile } from "node:fs/promises";
-import { resolve as resolvePath } from "node:path";
-import { dirname, join } from "node:path";
+import { readdir, stat, readFile, mkdir, writeFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import { dirname, join } from "node:path";
 import sharp from "sharp";
 
 import {
@@ -260,94 +260,94 @@ export function extractSessionId(description: string): string | null {
 // Avatar
 // ---------------------------------------------------------------------------
 
-const AVATAR_DIR = resolvePath(PROJECT_ROOT, "images", "avatars");
-const AVATAR_BADGE_DIR = resolvePath(AVATAR_DIR, "badges");
-const AVATAR_KEY_CACHE_FILE = resolvePath(PROJECT_ROOT, "state", "avatar-image-keys.json");
-const AVATAR_SOURCES: Record<string, string> = {
-  new: resolvePath(AVATAR_DIR, "status_new.png"),
-  busy: resolvePath(AVATAR_DIR, "status_busy.png"),
-  idle: resolvePath(AVATAR_DIR, "status_idle.png"),
-};
-const AVATAR_BADGES: Record<string, string> = {
-  claude: resolvePath(AVATAR_BADGE_DIR, "badge_claude.png"),
-  cursor: resolvePath(AVATAR_BADGE_DIR, "badge_cursor.png"),
-  codex: resolvePath(AVATAR_BADGE_DIR, "badge_codex.png"),
-};
-const AVATAR_SIZE = 256;
-const BADGE_SIZE = 92;
-const BADGE_MARGIN = 10;
-
-const avatarKeyCache = new Map<string, string>();
-let avatarKeyCacheLoaded = false;
-
-function normalizeAvatarTool(tool: string): string {
-  return AVATAR_BADGES[tool] ? tool : "claude";
-}
-
-function normalizeAvatarStatus(status: string): string {
-  return AVATAR_SOURCES[status] ? status : "idle";
-}
-
-function avatarCacheKey(tool: string, status: string): string {
-  return `${normalizeAvatarTool(tool)}:${normalizeAvatarStatus(status)}`;
-}
-
-async function loadAvatarKeyCache(): Promise<void> {
-  if (avatarKeyCacheLoaded) return;
-  avatarKeyCacheLoaded = true;
-  try {
-    const raw = await readFile(AVATAR_KEY_CACHE_FILE, "utf-8");
-    const parsed = JSON.parse(raw) as Record<string, unknown>;
-    for (const [key, value] of Object.entries(parsed)) {
-      if (typeof value === "string" && value.trim()) avatarKeyCache.set(key, value);
-    }
-  } catch {
-    // Missing or malformed cache should not block avatar updates.
-  }
-}
-
-async function persistAvatarKeyCache(): Promise<void> {
-  await mkdir(dirname(AVATAR_KEY_CACHE_FILE), { recursive: true });
-  await writeFile(
-    AVATAR_KEY_CACHE_FILE,
-    JSON.stringify(Object.fromEntries(avatarKeyCache.entries()), null, 2),
-    "utf-8",
-  );
-}
-
-async function renderAvatar(tool: string, status: string): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
-  const normalizedTool = normalizeAvatarTool(tool);
-  const normalizedStatus = normalizeAvatarStatus(status);
-  const badge = await sharp(await readFile(AVATAR_BADGES[normalizedTool]))
-    .resize(BADGE_SIZE, BADGE_SIZE, {
-      fit: "contain",
-      kernel: sharp.kernel.lanczos3,
-      background: { r: 0, g: 0, b: 0, alpha: 0 },
-    })
-    .png()
-    .toBuffer();
-
-  const jpeg = await sharp(await readFile(AVATAR_SOURCES[normalizedStatus]))
-    .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: "cover", position: "center" })
-    .composite([{
-      input: badge,
-      left: AVATAR_SIZE - BADGE_SIZE - BADGE_MARGIN,
-      top: AVATAR_SIZE - BADGE_SIZE - BADGE_MARGIN,
-    }])
-    .flatten({ background: "#ffffff" })
-    .removeAlpha()
-    .jpeg({ quality: 95, progressive: false })
+const AVATAR_DIR = resolvePath(PROJECT_ROOT, "images", "avatars");
+const AVATAR_BADGE_DIR = resolvePath(AVATAR_DIR, "badges");
+const AVATAR_KEY_CACHE_FILE = resolvePath(PROJECT_ROOT, "state", "avatar-image-keys.json");
+const AVATAR_SOURCES: Record<string, string> = {
+  new: resolvePath(AVATAR_DIR, "status_new.png"),
+  busy: resolvePath(AVATAR_DIR, "status_busy.png"),
+  idle: resolvePath(AVATAR_DIR, "status_idle.png"),
+};
+const AVATAR_BADGES: Record<string, string> = {
+  claude: resolvePath(AVATAR_BADGE_DIR, "badge_claude.png"),
+  cursor: resolvePath(AVATAR_BADGE_DIR, "badge_cursor.png"),
+  codex: resolvePath(AVATAR_BADGE_DIR, "badge_codex.png"),
+};
+const AVATAR_SIZE = 256;
+const BADGE_SIZE = 92;
+const BADGE_MARGIN = 10;
+
+const avatarKeyCache = new Map<string, string>();
+let avatarKeyCacheLoaded = false;
+
+function normalizeAvatarTool(tool: string): string {
+  return AVATAR_BADGES[tool] ? tool : "claude";
+}
+
+function normalizeAvatarStatus(status: string): string {
+  return AVATAR_SOURCES[status] ? status : "idle";
+}
+
+function avatarCacheKey(tool: string, status: string): string {
+  return `${normalizeAvatarTool(tool)}:${normalizeAvatarStatus(status)}`;
+}
+
+async function loadAvatarKeyCache(): Promise<void> {
+  if (avatarKeyCacheLoaded) return;
+  avatarKeyCacheLoaded = true;
+  try {
+    const raw = await readFile(AVATAR_KEY_CACHE_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string" && value.trim()) avatarKeyCache.set(key, value);
+    }
+  } catch {
+    // Missing or malformed cache should not block avatar updates.
+  }
+}
+
+async function persistAvatarKeyCache(): Promise<void> {
+  await mkdir(dirname(AVATAR_KEY_CACHE_FILE), { recursive: true });
+  await writeFile(
+    AVATAR_KEY_CACHE_FILE,
+    JSON.stringify(Object.fromEntries(avatarKeyCache.entries()), null, 2),
+    "utf-8",
+  );
+}
+
+async function renderAvatar(tool: string, status: string): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
+  const normalizedTool = normalizeAvatarTool(tool);
+  const normalizedStatus = normalizeAvatarStatus(status);
+  const badge = await sharp(await readFile(AVATAR_BADGES[normalizedTool]))
+    .resize(BADGE_SIZE, BADGE_SIZE, {
+      fit: "contain",
+      kernel: sharp.kernel.lanczos3,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    })
+    .png()
     .toBuffer();
 
-  return {
-    buffer: jpeg,
-    contentType: "image/jpeg",
-    filename: `avatar_${normalizedTool}_${normalizedStatus}.jpg`,
-  };
-}
-
-async function uploadImage(token: string, tool: string, status: string): Promise<string> {
-  const image = await renderAvatar(tool, status);
+  const jpeg = await sharp(await readFile(AVATAR_SOURCES[normalizedStatus]))
+    .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: "cover", position: "center" })
+    .composite([{
+      input: badge,
+      left: AVATAR_SIZE - BADGE_SIZE - BADGE_MARGIN,
+      top: AVATAR_SIZE - BADGE_SIZE - BADGE_MARGIN,
+    }])
+    .flatten({ background: "#ffffff" })
+    .removeAlpha()
+    .jpeg({ quality: 95, progressive: false })
+    .toBuffer();
+
+  return {
+    buffer: jpeg,
+    contentType: "image/jpeg",
+    filename: `avatar_${normalizedTool}_${normalizedStatus}.jpg`,
+  };
+}
+
+async function uploadImage(token: string, tool: string, status: string): Promise<string> {
+  const image = await renderAvatar(tool, status);
   const blob = new Blob([new Uint8Array(image.buffer)], { type: image.contentType });
   const form = new FormData();
   form.append("image_type", "avatar");
@@ -368,23 +368,23 @@ async function uploadImage(token: string, tool: string, status: string): Promise
   return data.data!.image_key!;
 }
 
-async function getOrUploadAvatarKey(token: string, tool: string, status: string): Promise<string> {
-  await loadAvatarKeyCache();
-  const keyName = avatarCacheKey(tool, status);
-  const cached = avatarKeyCache.get(keyName);
+async function getOrUploadAvatarKey(token: string, tool: string, status: string): Promise<string> {
+  await loadAvatarKeyCache();
+  const keyName = avatarCacheKey(tool, status);
+  const cached = avatarKeyCache.get(keyName);
   if (cached) return cached;
-  const key = await uploadImage(token, tool, status);
-  avatarKeyCache.set(keyName, key);
-  await persistAvatarKeyCache().catch((err) => {
-    console.error(`[${ts()}] [AVATAR] persist cache FAIL: ${(err as Error).message}`);
-  });
+  const key = await uploadImage(token, tool, status);
+  avatarKeyCache.set(keyName, key);
+  await persistAvatarKeyCache().catch((err) => {
+    console.error(`[${ts()}] [AVATAR] persist cache FAIL: ${(err as Error).message}`);
+  });
   console.log(`[${ts()}] [AVATAR] Uploaded "${status}" → image_key=${key}`);
   return key;
 }
 
-export async function setChatAvatar(token: string, chatId: string, tool: string, status: string): Promise<void> {
-  try {
-    const avatarKey = await getOrUploadAvatarKey(token, tool, status);
+export async function setChatAvatar(token: string, chatId: string, tool: string, status: string): Promise<void> {
+  try {
+    const avatarKey = await getOrUploadAvatarKey(token, tool, status);
     const resp = await fetch(`${BASE_URL}/im/v1/chats/${chatId}`, {
       method: "PUT",
       headers: {
@@ -401,14 +401,122 @@ export async function setChatAvatar(token: string, chatId: string, tool: string,
     }
     if (data.code !== 0) throw new Error(`[${data.code}] ${data.msg}`);
   } catch (err) {
-    console.error(`[${ts()}] [AVATAR] setChatAvatar FAIL: chatId=${chatId} tool=${tool} status=${status} ${(err as Error).message}`);
-  }
-}
+    console.error(`[${ts()}] [AVATAR] setChatAvatar FAIL: chatId=${chatId} tool=${tool} status=${status} ${(err as Error).message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Image download & cache
+// ---------------------------------------------------------------------------
+
+const IMAGE_DOWNLOAD_DIR = resolvePath(PROJECT_ROOT, "images", "downloads");
+const IMAGE_CACHE_FILE = resolvePath(PROJECT_ROOT, "state", "image-cache.json");
+
+const imageCache = new Map<string, string>();
+let imageCacheLoaded = false;
+
+async function loadImageCache(): Promise<void> {
+  if (imageCacheLoaded) return;
+  imageCacheLoaded = true;
+  try {
+    const raw = await readFile(IMAGE_CACHE_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string" && value.trim()) imageCache.set(key, value);
+    }
+  } catch { /* missing or malformed cache is not fatal */ }
+}
+
+async function persistImageCache(): Promise<void> {
+  await mkdir(dirname(IMAGE_CACHE_FILE), { recursive: true });
+  await writeFile(
+    IMAGE_CACHE_FILE,
+    JSON.stringify(Object.fromEntries(imageCache.entries()), null, 2),
+    "utf-8",
+  );
+}
+
+function extFromContentType(contentType: string | null): string {
+  if (!contentType) return ".png";
+  const mime = contentType.split(";")[0].trim().toLowerCase();
+  const map: Record<string, string> = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "image/bmp": ".bmp",
+    "image/svg+xml": ".svg",
+  };
+  return map[mime] ?? ".png";
+}
+
+async function downloadImage(token: string, messageId: string, fileKey: string): Promise<string> {
+  const resp = await fetch(`${BASE_URL}/im/v1/messages/${messageId}/resources/${fileKey}?type=image`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`downloadImage HTTP ${resp.status}: ${text.slice(0, 200)}`);
+  }
+  const ext = extFromContentType(resp.headers.get("content-type"));
+  const buffer = Buffer.from(await resp.arrayBuffer());
+  await mkdir(IMAGE_DOWNLOAD_DIR, { recursive: true });
+  const localPath = resolvePath(IMAGE_DOWNLOAD_DIR, `${fileKey}${ext}`);
+  await writeFile(localPath, buffer);
+  return localPath;
+}
+
+export async function getOrDownloadImage(token: string, messageId: string, fileKey: string): Promise<string> {
+  await loadImageCache();
+  const cached = imageCache.get(fileKey);
+  if (cached) return cached;
+  const localPath = await downloadImage(token, messageId, fileKey);
+  imageCache.set(fileKey, localPath);
+  await persistImageCache().catch((err) => {
+    console.error(`[${ts()}] [IMAGE] persist cache FAIL: ${(err as Error).message}`);
+  });
+  console.log(`[${ts()}] [IMAGE] Downloaded ${fileKey} -> ${localPath}`);
+  return localPath;
+}
 
 // ---------------------------------------------------------------------------
 // Messaging
 // ---------------------------------------------------------------------------
 
+const DELAY_NOTICE_THRESHOLD_MS = 15 * 60 * 1000; // 15 分钟
+
+/** 消息延迟超过阈值时生成提醒文本，否则返回 null */
+export function formatDelayNotice(createTimeMs: number, nowMs?: number): string | null {
+  const now = nowMs ?? Date.now();
+  const delayMs = now - createTimeMs;
+  if (delayMs < DELAY_NOTICE_THRESHOLD_MS) return null;
+
+  const sendDate = new Date(createTimeMs);
+  const month = sendDate.getMonth() + 1;
+  const day = sendDate.getDate();
+  const hour = String(sendDate.getHours()).padStart(2, "0");
+  const min = String(sendDate.getMinutes()).padStart(2, "0");
+  const sendTimeStr = `${month}月${day}日 ${hour}:${min}`;
+
+  const totalMinutes = Math.floor(delayMs / 60000);
+  let delayStr: string;
+  if (totalMinutes < 60) {
+    delayStr = `${totalMinutes} 分钟`;
+  } else {
+    const hours = Math.floor(totalMinutes / 60);
+    const mins = totalMinutes % 60;
+    if (hours < 24) {
+      delayStr = mins > 0 ? `${hours} 小时 ${mins} 分钟` : `${hours} 小时`;
+    } else {
+      const days = Math.floor(hours / 24);
+      const remainHours = hours % 24;
+      delayStr = remainHours > 0 ? `${days} 天 ${remainHours} 小时` : `${days} 天`;
+    }
+  }
+
+  return `> ⚠️ 延迟送达提醒：此消息于 ${sendTimeStr} 发送，因服务离线，延迟约 ${delayStr}后送达`;
+}
+
 export async function sendTextReply(
   token: string,
   chatId: string,

package/src/index.ts

@@ -3,7 +3,7 @@
  * =================================================================
  * Supported tools: Claude Code, Cursor, Codex (OpenAI).
  *
- * When a user sends "/new [tool]" to the bot:
+ * When a user sends "/new [tool]" to the bot (omitting tool uses the configured default Agent):
  *   1. Create an AI tool session via the corresponding adapter, get session ID
  *   2. Create a new Feishu group chat and add the user
  *   3. Rename the group (name + description) to the session ID
@@ -56,6 +56,7 @@ import {
   getRecentDirs,
   addRecentDir,
   sessionPrefixForTool,
+  resolveDefaultAgentTool,
   toolDisplayName,
   ts,
 } from "./config.ts";
@@ -64,6 +65,7 @@ import {
   addReaction,
   createGroupChat,
   extractSessionInfo,
+  formatDelayNotice,
   getChatInfo,
   getTenantAccessToken,
   recallMessage,
@@ -72,6 +74,7 @@ import {
   setChatAvatar,
   updateCardMessage,
   updateChatInfo,
+  getOrDownloadImage,
   sendRestartCard,
   verifyAllPermissions,
   reportPermissionResults,
@@ -124,7 +127,7 @@ function getInnerEvent(data: Evt): InnerEvent {
  * 将飞书消息的原始 content JSON 结构转成可读文本，保留代码块等结构信息。
  * 未知类型直接返回 JSON 原文，让 AI 自行理解。
  */
-function formatMessageContent(message: { message_type?: string; content?: string }): string {
+async function formatMessageContent(message: { message_id?: string; message_type?: string; content?: string }): Promise<string> {
   const contentStr = message.content ?? "{}";
   let content: Record<string, unknown>;
   try { content = JSON.parse(contentStr); } catch { return ""; }
@@ -141,7 +144,21 @@ function formatMessageContent(message: { message_type?: string; content?: string
     return formatPostContent(content);
   }
 
-  // 其他类型（image, file, audio, media, sticker）直接给原始 JSON
+  if (message.message_type === "image") {
+    const imageKey = content.image_key as string | undefined;
+    const messageId = message.message_id;
+    if (!imageKey || !messageId) return contentStr;
+    try {
+      const token = await getTenantAccessToken();
+      const localPath = await getOrDownloadImage(token, messageId, imageKey);
+      return `[图片] ${localPath}`;
+    } catch (err) {
+      console.error(`[${ts()}] [IMAGE] download failed for ${imageKey}: ${(err as Error).message}`);
+      return `[图片: ${imageKey}]`;
+    }
+  }
+
+  // 其他类型（file, audio, media, sticker）直接给原始 JSON
   return contentStr;
 }
 
@@ -195,7 +212,7 @@ function parseCardAction(data: unknown): CardActionResult | null {
   }
   if (!cmd) return null;
 
-  const CMD_MAP: Record<string, string> = { stop: "/stop", new: "/new", "new cursor": "/new cursor", "new codex": "/new codex", restart: "/restart", status: "/status", cd: "/cd", sessions: "/sessions", forget: "/forget" };
+  const CMD_MAP: Record<string, string> = { stop: "/stop", new: "/new", "new claude": "/new claude", "new cursor": "/new cursor", "new codex": "/new codex", restart: "/restart", status: "/status", cd: "/cd", sessions: "/sessions", forget: "/forget" };
   let text = CMD_MAP[cmd] ?? "";
   if (cmd === "cd" && typeof action.value === "object" && action.value !== null) {
     const path = (action.value as Record<string, string>).path;
@@ -405,7 +422,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
     );
 
     console.log(`[${ts()}] [STEP 4/4] Replied to new group → OK`);
-    setChatAvatar(freshToken, newChatId, tool, "new").catch(() => {});
+    setChatAvatar(freshToken, newChatId, tool, "new").catch(() => {});
     console.log(`${"=".repeat(60)}`);
     return;
   }
@@ -558,7 +575,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           tool: descriptionTool,
         });
 
-        setChatAvatar(freshToken, chatId, descriptionTool, "new").catch(() => {});
+        setChatAvatar(freshToken, chatId, descriptionTool, "new").catch(() => {});
 
         await sendCardReply(
           freshToken, chatId, `${toolLabel} Session Reset`,
@@ -721,8 +738,8 @@ async function startBotServiceCore(): Promise<void> {
   console.log(`${"=".repeat(60)}`);
   console.log(`  ChatCCC — Feishu Bot Bridge for Claude Code${modeTag}`);
   console.log(`${"=".repeat(60)}`);
-  console.log(`  Send "/new" to the bot to create a new group + Claude session.`);
-  console.log(`  In a Claude session group, send any message to resume & prompt.`);
+  console.log(`  Send "/new" to the bot to create a new group + ${toolDisplayName(resolveDefaultAgentTool())} session.`);
+  console.log(`  In a session group, send any message to resume & prompt.`);
   console.log(`${"=".repeat(60)}`);
 
   console.log(`\n[启动 4/7] 向飞书开放平台申请 tenant_access_token …`);
@@ -782,7 +799,7 @@ async function startBotServiceCore(): Promise<void> {
         }
       }
 
-      const text = formatMessageContent(message);
+      const text = await formatMessageContent(message);
       const sender = event.sender;
       const openId = sender?.sender_id?.open_id ?? "";
       const chatId = message.chat_id ?? "";
@@ -802,6 +819,11 @@ async function startBotServiceCore(): Promise<void> {
 
       if (!text) return;
       const msgTimestamp = parseInt(message.create_time ?? "0", 10) || Date.now();
+      const delayNotice = formatDelayNotice(msgTimestamp);
+      if (delayNotice) {
+        const delayToken = await getTenantAccessToken();
+        await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => {});
+      }
       await handleCommand(text, chatId, openId, msgTimestamp);
       } catch (err) {
         console.error(`[${ts()}] [FATAL] im.message.receive_v1 handler crashed: ${(err as Error).message}`);
@@ -861,7 +883,7 @@ async function startBotServiceCore(): Promise<void> {
       console.log("[启动 7/7] 已连接本地中继，可接收转发事件。\n");
       printServiceRunningHint("local", `http://127.0.0.1:${CHATCCC_PORT}`);
     });
-    ws.on("message", (raw: Buffer) => {
+    ws.on("message", async (raw: Buffer) => {
       try {
         const data = JSON.parse(raw.toString()) as Evt;
         const action = parseCardAction(data);
@@ -874,7 +896,7 @@ async function startBotServiceCore(): Promise<void> {
         const event = getInnerEvent(data);
         const message = event.message;
         if (!message) return;
-        const text = formatMessageContent(message);
+        const text = await formatMessageContent(message);
         const openId = event.sender?.sender_id?.open_id ?? "";
         const chatId = message.chat_id ?? "";
         appendChatLog(chatId, openId, text);

package/src/session.ts

@@ -251,7 +251,7 @@ export function accumulateBlockContent(
 }
 
 // ---------------------------------------------------------------------------
-// Claude session management
+// AI tool session management
 // ---------------------------------------------------------------------------
 
 /**
@@ -324,7 +324,7 @@ export async function resumeAndPrompt(
   });
   const myGen = sessionGen;
 
-  setChatAvatar(token, chatId, tool, "busy").catch(() => {});
+  setChatAvatar(token, chatId, tool, "busy").catch(() => {});
 
   const now = Date.now();
   const existingInfo = sessionInfoMap.get(chatId);
@@ -466,7 +466,7 @@ export async function resumeAndPrompt(
   if (!cEntry || cEntry.gen !== myGen) return;
   const wasStopped = cEntry.stopped;
   chatSessionMap.delete(chatId);
-  setChatAvatar(token, chatId, tool, "idle").catch(() => {});
+  setChatAvatar(token, chatId, tool, "idle").catch(() => {});
 
   const finalCardContent = state.accumulatedContent || " ";
   if (cardId) {

package/src/web-ui.ts

@@ -27,10 +27,10 @@ interface AppConfig {
   feishu?: { appId?: string; appSecret?: string };
   port?: number;
   gitTimeoutSeconds?: number;
-  claude?: { enabled?: boolean; model?: string; effort?: string; apiKey?: string; baseUrl?: string };
+  claude?: { enabled?: boolean; defaultAgent?: boolean; model?: string; effort?: string; apiKey?: string; baseUrl?: string };
   // `command` 是已废弃的旧字段名，保留只读以兼容升级前的 config.json
-  cursor?: { enabled?: boolean; path?: string; command?: string; model?: string };
-  codex?: { enabled?: boolean; path?: string; command?: string; model?: string; effort?: string };
+  cursor?: { enabled?: boolean; defaultAgent?: boolean; path?: string; command?: string; model?: string };
+  codex?: { enabled?: boolean; defaultAgent?: boolean; path?: string; command?: string; model?: string; effort?: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -343,6 +343,9 @@ function unflattenConfig(flat: Record<string, unknown>): Record<string, unknown>
     } else if (key === "CHATCCC_CLAUDE_ENABLED") {
       result.claude = result.claude || {};
       (result.claude as Record<string, unknown>).enabled = val === true || val === "true";
+    } else if (key === "CHATCCC_CLAUDE_DEFAULT_AGENT") {
+      result.claude = result.claude || {};
+      (result.claude as Record<string, unknown>).defaultAgent = val === true || val === "true";
     } else if (key === "CHATCCC_CURSOR_PATH") {
       result.cursor = result.cursor || {};
       (result.cursor as Record<string, unknown>).path = val;
@@ -352,6 +355,9 @@ function unflattenConfig(flat: Record<string, unknown>): Record<string, unknown>
     } else if (key === "CHATCCC_CURSOR_ENABLED") {
       result.cursor = result.cursor || {};
       (result.cursor as Record<string, unknown>).enabled = val === true || val === "true";
+    } else if (key === "CHATCCC_CURSOR_DEFAULT_AGENT") {
+      result.cursor = result.cursor || {};
+      (result.cursor as Record<string, unknown>).defaultAgent = val === true || val === "true";
     } else if (key === "CHATCCC_CODEX_PATH") {
       result.codex = result.codex || {};
       (result.codex as Record<string, unknown>).path = val;
@@ -364,6 +370,9 @@ function unflattenConfig(flat: Record<string, unknown>): Record<string, unknown>
     } else if (key === "CHATCCC_CODEX_ENABLED") {
       result.codex = result.codex || {};
       (result.codex as Record<string, unknown>).enabled = val === true || val === "true";
+    } else if (key === "CHATCCC_CODEX_DEFAULT_AGENT") {
+      result.codex = result.codex || {};
+      (result.codex as Record<string, unknown>).defaultAgent = val === true || val === "true";
     }
   }
   return result;
@@ -519,6 +528,8 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
 .agent-toggle:checked{background:#3b82f6}
 .agent-toggle::before{content:"";position:absolute;width:18px;height:18px;border-radius:50%;background:#fff;top:2px;left:2px;transition:left .2s;box-shadow:0 1px 2px rgba(0,0,0,.2)}
 .agent-toggle:checked::before{left:18px}
+.agent-default-row{display:flex;align-items:center;gap:8px;font-size:13px;color:#334155;margin:-4px 0 12px}
+.agent-default-row input{margin:0}
 .agent-body{flex:1}
 .agent-body fieldset{border:none;padding:0;margin:0}
 .agent-body fieldset[disabled]{opacity:.45;pointer-events:none}
@@ -600,6 +611,10 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
               <div class="desc">Anthropic Claude Agent SDK<br>官方/第三方 API 均可</div>
             </div>
           </div>
+          <label class="agent-default-row">
+            <input type="checkbox" id="agent-default-claude" onchange="onDefaultAgentToggle('claude', this.checked)">
+            设为默认 Agent
+          </label>
           <fieldset class="agent-body" id="agent-body-claude" disabled>
             <div class="form-group" style="background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:12px 14px">
               <label style="margin-bottom:8px;font-weight:600;color:#334155">API 来源</label>
@@ -649,6 +664,10 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
               <div class="desc">Cursor Agent CLI<br>需安装 Cursor</div>
             </div>
           </div>
+          <label class="agent-default-row">
+            <input type="checkbox" id="agent-default-cursor" onchange="onDefaultAgentToggle('cursor', this.checked)">
+            设为默认 Agent
+          </label>
           <fieldset class="agent-body" id="agent-body-cursor" disabled>
             <div class="form-group">
               <label>CLI 路径</label>
@@ -673,6 +692,10 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
               <div class="desc">OpenAI Codex CLI<br>需安装并登录</div>
             </div>
           </div>
+          <label class="agent-default-row">
+            <input type="checkbox" id="agent-default-codex" onchange="onDefaultAgentToggle('codex', this.checked)">
+            设为默认 Agent
+          </label>
           <fieldset class="agent-body" id="agent-body-codex" disabled>
             <div class="form-group">
               <label>CLI 路径</label>
@@ -741,6 +764,7 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
         <div class="config-row" id="cfg-row-CLAUDE_BASE_URL"><span class="key">Base URL</span><span class="val" id="cfg-CLAUDE_BASE_URL">-</span></div>
         <div class="config-row"><span class="key">模型</span><span class="val" id="cfg-ANTHROPIC_MODEL">-</span></div>
         <div class="config-row"><span class="key">Effort</span><span class="val" id="cfg-ANTHROPIC_EFFORT">-</span></div>
+        <label class="agent-default-row" style="margin-top:10px"><input type="checkbox" id="dash-default-claude" onchange="setDashboardDefaultAgent('claude', this.checked)"> 设为默认 Agent</label>
         <button class="btn btn-outline" style="margin-top:8px" onclick="editSection('claude')">编辑</button>
       </div>
     </details>
@@ -750,6 +774,7 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
       <div class="section-detail">
         <div class="config-row"><span class="key">CLI 路径</span><span class="val" id="cfg-CURSOR_PATH">-</span></div>
         <div class="config-row"><span class="key">模型</span><span class="val" id="cfg-CURSOR_MODEL">-</span></div>
+        <label class="agent-default-row" style="margin-top:10px"><input type="checkbox" id="dash-default-cursor" onchange="setDashboardDefaultAgent('cursor', this.checked)"> 设为默认 Agent</label>
         <button class="btn btn-outline" style="margin-top:8px" onclick="editSection('cursor')">编辑</button>
       </div>
     </details>
@@ -760,6 +785,7 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
         <div class="config-row"><span class="key">CLI 路径</span><span class="val" id="cfg-CODEX_PATH">-</span></div>
         <div class="config-row"><span class="key">模型</span><span class="val" id="cfg-CODEX_MODEL">-</span></div>
         <div class="config-row"><span class="key">Effort</span><span class="val" id="cfg-CODEX_EFFORT">-</span></div>
+        <label class="agent-default-row" style="margin-top:10px"><input type="checkbox" id="dash-default-codex" onchange="setDashboardDefaultAgent('codex', this.checked)"> 设为默认 Agent</label>
         <button class="btn btn-outline" style="margin-top:8px" onclick="editSection('codex')">编辑</button>
       </div>
     </details>
@@ -791,6 +817,7 @@ let state = {
   view: 'loading',
   // 三个 Agent 各自的启用开关；初始全 false，renderStep2() 会按已存在 config 自动打开
   agentsEnabled: { claude: false, cursor: false, codex: false },
+  defaultAgent: 'claude',
   wizardStep: 1,
   config: {},
   running: false,
@@ -855,6 +882,51 @@ function onAgentToggle(agent, enabled) {
   if (card) card.classList.toggle('enabled', enabled);
   var body = document.getElementById('agent-body-' + agent);
   if (body) body.disabled = !enabled;
+  if (!enabled && state.defaultAgent === agent) {
+    state.defaultAgent = firstEnabledAgent();
+  } else if (enabled && !state.defaultAgent) {
+    state.defaultAgent = agent;
+  }
+  updateDefaultAgentToggles();
+  updateStep2NextBtn();
+}
+
+function firstEnabledAgent() {
+  if (state.agentsEnabled.claude) return 'claude';
+  if (state.agentsEnabled.cursor) return 'cursor';
+  if (state.agentsEnabled.codex) return 'codex';
+  return null;
+}
+
+function resolveDefaultAgentFromConfig(c, claudeOn, cursorOn, codexOn) {
+  if (claudeOn && c.claude && c.claude.defaultAgent === true) return 'claude';
+  if (cursorOn && c.cursor && c.cursor.defaultAgent === true) return 'cursor';
+  if (codexOn && c.codex && c.codex.defaultAgent === true) return 'codex';
+  if (claudeOn) return 'claude';
+  if (cursorOn) return 'cursor';
+  if (codexOn) return 'codex';
+  return 'claude';
+}
+
+function updateDefaultAgentToggles() {
+  ['claude','cursor','codex'].forEach(function(agent){
+    var el = document.getElementById('agent-default-' + agent);
+    if (el) {
+      el.checked = state.defaultAgent === agent;
+      el.disabled = !state.agentsEnabled[agent];
+    }
+    var dashEl = document.getElementById('dash-default-' + agent);
+    if (dashEl) dashEl.checked = state.defaultAgent === agent;
+  });
+}
+
+function onDefaultAgentToggle(agent, enabled) {
+  if (enabled) {
+    state.defaultAgent = agent;
+  } else if (state.defaultAgent === agent) {
+    state.defaultAgent = null;
+  }
+  updateDefaultAgentToggles();
   updateStep2NextBtn();
 }
 
@@ -878,6 +950,10 @@ function updateStep2NextBtn() {
   if (state.agentsEnabled.claude && isClaudeFieldsValid()) validCount++;
   if (state.agentsEnabled.cursor) validCount++;
   if (state.agentsEnabled.codex) validCount++;
+  if (validCount > 0 && !state.defaultAgent) {
+    state.defaultAgent = firstEnabledAgent();
+    updateDefaultAgentToggles();
+  }
   btn.disabled = validCount === 0;
 }
 
@@ -1018,12 +1094,14 @@ function renderStep2() {
   var claudeOn = isAgentEnabled(c.claude, CLAUDE_FALLBACK_KEYS);
   var cursorOn = isAgentEnabled(c.cursor, CURSOR_FALLBACK_KEYS);
   var codexOn = isAgentEnabled(c.codex, CODEX_FALLBACK_KEYS);
+  state.defaultAgent = resolveDefaultAgentFromConfig(c, claudeOn, cursorOn, codexOn);
   document.getElementById('agent-enable-claude').checked = claudeOn;
   document.getElementById('agent-enable-cursor').checked = cursorOn;
   document.getElementById('agent-enable-codex').checked = codexOn;
   onAgentToggle('claude', claudeOn);
   onAgentToggle('cursor', cursorOn);
   onAgentToggle('codex', codexOn);
+  updateDefaultAgentToggles();
 
   // Cursor path placeholder/hint：把已探测到的路径显示为占位
   var hint = document.getElementById('cursor-path-hint');
@@ -1060,6 +1138,12 @@ function collectAllFields() {
   vars.CHATCCC_CLAUDE_ENABLED = !!state.agentsEnabled.claude;
   vars.CHATCCC_CURSOR_ENABLED = !!state.agentsEnabled.cursor;
   vars.CHATCCC_CODEX_ENABLED = !!state.agentsEnabled.codex;
+  if (!state.defaultAgent || !state.agentsEnabled[state.defaultAgent]) {
+    state.defaultAgent = firstEnabledAgent();
+  }
+  vars.CHATCCC_CLAUDE_DEFAULT_AGENT = state.defaultAgent === 'claude';
+  vars.CHATCCC_CURSOR_DEFAULT_AGENT = state.defaultAgent === 'cursor';
+  vars.CHATCCC_CODEX_DEFAULT_AGENT = state.defaultAgent === 'codex';
   if (state.agentsEnabled.claude) {
     AGENT_FIELDS.claude.forEach(function(key){
       var el = document.getElementById('field-' + key);
@@ -1099,6 +1183,9 @@ function renderStep3() {
   if (state.agentsEnabled.codex) enabledList.push('codex');
   if (enabledList.length === 0) {
     lines.push('<div style="color:#ef4444">未启用任何 AI Agent</div>');
+  } else {
+    var defaultLabel = state.defaultAgent === 'cursor' ? 'Cursor' : state.defaultAgent === 'codex' ? 'Codex' : 'Claude Code';
+    lines.push('<div class="config-row"><span class="key">/new 默认 Agent</span><span class="val">' + defaultLabel + '</span></div>');
   }
   enabledList.forEach(function(t){
     if (t === 'claude') {
@@ -1146,6 +1233,33 @@ async function saveConfig(vars) {
   return result.ok;
 }
 
+async function setDashboardDefaultAgent(agent, enabled) {
+  if (!enabled) {
+    updateDefaultAgentToggles();
+    return;
+  }
+  state.defaultAgent = agent;
+  var vars = {
+    CHATCCC_CLAUDE_DEFAULT_AGENT: agent === 'claude',
+    CHATCCC_CURSOR_DEFAULT_AGENT: agent === 'cursor',
+    CHATCCC_CODEX_DEFAULT_AGENT: agent === 'codex'
+  };
+  var result = await api('/api/config', 'POST', { vars: vars, claudeApiMode: detectClaudeApiModeFromConfig(state.config && state.config.claude) });
+  if (result.ok) {
+    state.config.claude = state.config.claude || {};
+    state.config.cursor = state.config.cursor || {};
+    state.config.codex = state.config.codex || {};
+    state.config.claude.defaultAgent = agent === 'claude';
+    state.config.cursor.defaultAgent = agent === 'cursor';
+    state.config.codex.defaultAgent = agent === 'codex';
+    updateDefaultAgentToggles();
+    toast('默认 Agent 已更新');
+  } else {
+    toast('保存失败: ' + (result.error || '未知错误'), 'error');
+    updateDefaultAgentToggles();
+  }
+}
+
 async function saveAndStart() {
   var vars = collectAllFields();
   if (!vars.CHATCCC_APP_ID || !vars.CHATCCC_APP_SECRET) {
@@ -1233,9 +1347,12 @@ function updateDashboardUI() {
   var claudeOn = isAgentEnabled(c.claude, CLAUDE_FALLBACK_KEYS);
   var cursorOn = isAgentEnabled(c.cursor, CURSOR_FALLBACK_KEYS);
   var codexOn = isAgentEnabled(c.codex, CODEX_FALLBACK_KEYS);
+  state.agentsEnabled = { claude: claudeOn, cursor: cursorOn, codex: codexOn };
+  state.defaultAgent = resolveDefaultAgentFromConfig(c, claudeOn, cursorOn, codexOn);
   document.getElementById('dash-claude').style.display = claudeOn ? '' : 'none';
   document.getElementById('dash-cursor').style.display = cursorOn ? '' : 'none';
   document.getElementById('dash-codex').style.display = codexOn ? '' : 'none';
+  updateDefaultAgentToggles();
   // 三个都未启用时给一个空态提示，引导用户去配置向导启用
   var emptyHint = document.getElementById('dash-no-agent-hint');
   if (emptyHint) emptyHint.style.display = (!claudeOn && !cursorOn && !codexOn) ? '' : 'none';
@@ -1588,4 +1705,4 @@ export function startSetupMode(port: number, options: StartSetupModeOptions = {}
     console.log("");
     openInBrowser(url);
   });
-}
+}