chatccc 0.2.252 → 0.2.254

package/{src/web-ui.ts → dist/src/web-ui.js}

@@ -1,700 +1,637 @@
-// =============================================================================
-// web-ui.ts — Setup Wizard & Management Dashboard HTTP Server
-// =============================================================================
-// Serves on the same port as the WebSocket relay (18080 default).
-// - Setup mode: no config.json → show setup wizard, skip Feishu connection
-// - Dashboard mode: config.json exists → serve management page alongside WS relay
-// =============================================================================
-
-import { createServer, IncomingMessage, ServerResponse } from "node:http";
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { readFile, writeFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { spawn, execSync } from "node:child_process";
-import {
-  buildWebUiUrl,
-  createInternalRestartEnv,
-  openWebUiInDefaultBrowser,
-} from "./startup-lifecycle.ts";
-import {
-  getClaudeSdkInstalledVersion,
-  getLastInstallProgress,
-  installClaudeSdk,
-  isClaudeSdkInstalled,
-  isInstallRunning,
-} from "./claude-sdk-installer.ts";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = join(__dirname, "..");
-const USER_DATA_DIR = join(homedir(), ".chatccc");
-const CONFIG_FILE = join(USER_DATA_DIR, "config.json");
-const CONFIG_SAMPLE_FILE = join(PROJECT_ROOT, "config.sample.json");
-const PID_FILE = join(USER_DATA_DIR, "state", "runtime.pid");
-const ILINK_AUTH_PATH = join(USER_DATA_DIR, "state", "ilink-auth.json");
-
-// ---------------------------------------------------------------------------
-// Helpers — config.json parsing & generation
-// ---------------------------------------------------------------------------
-
-interface AppConfig {
-  feishu?: { appId?: string; appSecret?: string };
-  platforms?: {
-    feishu?: { enabled?: boolean; platformType?: string };
-    ilink?: { enabled?: boolean; reuseTokenOnStart?: boolean };
-  };
-  webUi?: { openOnStart?: boolean };
-  chromeDevtools?: { enabled?: boolean; port?: number; chromePath?: string };
-  port?: number;
-  gitTimeoutSeconds?: number;
-  claude?: { enabled?: boolean; defaultAgent?: boolean; model?: string; subagentModel?: string; effort?: string; apiKey?: string; baseUrl?: string; maxTurn?: number };
-  // `command` 是已废弃的旧字段名，保留只读以兼容升级前的 config.json
-  cursor?: {
-    enabled?: boolean;
-    defaultAgent?: boolean;
-    path?: string;
-    command?: string;
-    model?: string;
-    alternativeModel?: string;
-    avatarBatteryMode?: string;
-    onDemandMonthlyBudget?: number;
-  };
-  codex?: { enabled?: boolean; defaultAgent?: boolean; path?: string; command?: string; model?: string; alternativeModel?: string; effort?: string; fastMode?: boolean };
-  ccc?: {
-    enabled?: boolean;
-    defaultAgent?: boolean;
-    DEEPSEEK_API_KEY?: string;
-    DEEPSEEK_BASE_URL?: string;
-    model?: string;
-    alternativeModel?: string;
-    effort?: string;
-    /** 留空（""）= 不 override，跟随 DeepCCC 内核配置（~/.deepccc/config.json 或 DEEPCCC_PROVIDER） */
-    provider?: "" | "openai" | "anthropic";
-  };
-}
-
-// ---------------------------------------------------------------------------
-// /api/start 路径选择（纯函数，便于单测护栏）
-// ---------------------------------------------------------------------------
-//
-// 三种语义：
-//   - "inplace" : setup 模式，原地启动飞书 service（同进程，不动 PID 文件）
-//   - "spawn"   : dashboard 模式 + service 未运行，spawn 子进程（旧 service 退出后场景）
-//   - "reload"  : dashboard 模式 + service 已经在跑（通常就是当前进程自己）→
-//                 仅调用 reloadConfigFromDisk() 刷新 export let 常量，**不真正重启**。
-//                 用户的设计意图："让新 config 生效就行，不用走 spawn+exit 的真重启"。
-//
-// 关键契约：只要 setup 模式注册了 onActivate 回调，无条件走 inplace —— 因为
-// setup 进程**总是**占着 PID 文件、isServiceRunning() 永远为 true，再判 PID
-// 会陷入"自己挡自己"的死循环（用户点保存并启动只会得到 already running）。
-//
-// 历史：曾经在 service 已运行时返回 "reject-already-running"，但 dashboard 的
-// UI 本身就在跑着的进程内，service 必然在跑——重新跑向导改完配置点"保存并启动"
-// 100% 会撞到这条 reject 路径，造成"自己挡自己"的死循环。改 reload 后即可
-// 让常量热更新（API 来源、模型、effort、CLI 路径等下次创建会话即生效）。
-// 已建立的飞书 WSClient 仍持有旧 APP_ID/APP_SECRET 句柄——如改了飞书凭证，
-// 仍需重启 chatccc 进程才能让 WS 长连接换 token；但这是用户少见路径，文档说明即可。
-
-export type StartPath = "inplace" | "spawn" | "reload";
-
-export function chooseStartPath(input: {
-  hasInplaceActivateHook: boolean;
-  isServiceRunning: boolean;
-}): StartPath {
-  if (input.hasInplaceActivateHook) return "inplace";
-  if (input.isServiceRunning) return "reload";
-  return "spawn";
-}
-
-/** 读取 cursor / codex 的 CLI 路径，优先新字段 path，回退旧字段 command */
-function readToolPath(tool?: { path?: string; command?: string }): string {
-  if (!tool) return "";
-  if (tool.path && tool.path.trim()) return tool.path;
-  if (tool.command && tool.command.trim()) return tool.command;
-  return "";
-}
-
-function loadConfig(): AppConfig {
-  if (!existsSync(CONFIG_FILE)) return {};
-  try {
-    let raw = readFileSync(CONFIG_FILE, "utf8");
-    // 移除可能意外写入的 UTF-8 BOM，避免 JSON.parse 失败导致返回空对象、
-    // UI 显示所有配置为空。
-    if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
-    return JSON.parse(raw);
-  } catch {
-    return {};
-  }
-}
-
-function saveConfig(cfg: AppConfig): void {
-  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf8");
-}
-
-type ConfigApplyMode = "saved" | "reload" | "restart-required";
-
-interface ConfigApplyResult {
-  mode: ConfigApplyMode;
-  restartRequired: boolean;
-  restartReasons: string[];
-}
-
-function stringValue(value: unknown): string {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function portValue(cfg: AppConfig): number {
-  return Number.isInteger(cfg.port) && cfg.port! >= 1 && cfg.port! <= 65535 ? cfg.port! : 18080;
-}
-
-function platformEnabled(cfg: AppConfig, platform: "feishu" | "ilink"): boolean {
-  return cfg.platforms?.[platform]?.enabled !== false;
-}
-
-function feishuPlatformType(cfg: AppConfig): string {
-  return cfg.platforms?.feishu?.platformType === "lark" ? "lark" : "feishu";
-}
-
-function ilinkReuseTokenOnStart(cfg: AppConfig): boolean {
-  return cfg.platforms?.ilink?.reuseTokenOnStart !== false;
-}
-
-export function getRestartRequiredReasons(before: AppConfig, after: AppConfig): string[] {
-  const reasons: string[] = [];
-
-  if (portValue(before) !== portValue(after)) reasons.push("port");
-  if (stringValue(before.feishu?.appId) !== stringValue(after.feishu?.appId)) reasons.push("feishu.appId");
-  if (stringValue(before.feishu?.appSecret) !== stringValue(after.feishu?.appSecret)) reasons.push("feishu.appSecret");
-  if (feishuPlatformType(before) !== feishuPlatformType(after)) reasons.push("platforms.feishu.platformType");
-  if (platformEnabled(before, "feishu") !== platformEnabled(after, "feishu")) reasons.push("platforms.feishu.enabled");
-  if (platformEnabled(before, "ilink") !== platformEnabled(after, "ilink")) reasons.push("platforms.ilink.enabled");
-  if (ilinkReuseTokenOnStart(before) !== ilinkReuseTokenOnStart(after)) {
-    reasons.push("platforms.ilink.reuseTokenOnStart");
-  }
-
-  return reasons;
-}
-
-async function applySavedConfigIfPossible(before: AppConfig, after: AppConfig): Promise<ConfigApplyResult> {
-  const setupMode = Boolean(setupActivateHook && setupHttpServer);
-  if (setupMode) {
-    return { mode: "saved", restartRequired: false, restartReasons: [] };
-  }
-
-  const running = isServiceRunning();
-  if (!running) {
-    return { mode: "saved", restartRequired: false, restartReasons: [] };
-  }
-
-  const restartReasons = getRestartRequiredReasons(before, after);
-  if (restartReasons.length > 0) {
-    return { mode: "restart-required", restartRequired: true, restartReasons };
-  }
-  if (!reloadConfigHook) {
-    return { mode: "saved", restartRequired: false, restartReasons: [] };
-  }
-
-  await reloadConfigHook();
-  return { mode: "reload", restartRequired: false, restartReasons: [] };
-}
-
-function maskSecret(value: string | undefined): string {
-  if (!value) return "(未设置)";
-  if (value.length <= 8) return "***";
-  return value.slice(0, 4) + "***" + value.slice(-4);
-}
-
-// ---------------------------------------------------------------------------
-// Helpers — process management
-// ---------------------------------------------------------------------------
-
-function isServiceRunning(): boolean {
-  if (!existsSync(PID_FILE)) return false;
-  try {
-    const raw = readFileSync(PID_FILE, "utf8").trim();
-    const pid = parseInt(raw, 10);
-    if (isNaN(pid)) return false;
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function getServicePid(): number | null {
-  if (!existsSync(PID_FILE)) return null;
-  try {
-    const pid = parseInt(readFileSync(PID_FILE, "utf8").trim(), 10);
-    return isNaN(pid) ? null : pid;
-  } catch {
-    return null;
-  }
-}
-
-function getServiceUptime(): number | null {
-  try {
-    const s = statSync(PID_FILE);
-    return Math.floor((Date.now() - s.mtimeMs) / 1000);
-  } catch {
-    return null;
-  }
-}
-
-import { statSync } from "node:fs";
-
-function spawnService(): { ok: boolean; pid?: number; error?: string } {
-  const indexPath = join(PROJECT_ROOT, "src", "index.ts");
-  if (!existsSync(indexPath)) {
-    return { ok: false, error: `Entry not found: ${indexPath}` };
-  }
-  try {
-    const child = spawn("npx", ["tsx", "src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      shell: true,
-      env: createInternalRestartEnv(),
-    });
-    child.unref();
-    return { ok: true, pid: child.pid ?? undefined };
-  } catch (err) {
-    return { ok: false, error: (err as Error).message };
-  }
-}
-
-/**
- * 安排一次真正的进程重启：先回复 HTTP 请求，再 spawn 一个延迟启动的子进程，
- * 然后退出当前进程。延迟是为了让当前进程完全退出并释放端口。
- */
-function scheduleRestart(): void {
-  const indexPath = join(PROJECT_ROOT, "src", "index.ts");
-  if (!existsSync(indexPath)) return;
-  if (process.platform === "win32") {
-    // Windows: ping 作为 sleep（ping 自己 3 次 ≈ 2 秒延迟）
-    spawn("cmd.exe", ["/c", "ping -n 3 127.0.0.1 > nul && npx tsx src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-      env: createInternalRestartEnv(),
-    }).unref();
-  } else {
-    spawn("bash", ["-c", "sleep 2 && npx tsx src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      env: createInternalRestartEnv(),
-    }).unref();
-  }
-}
-
-function stopService(): { ok: boolean; error?: string } {
-  const pid = getServicePid();
-  if (!pid) return { ok: false, error: "No PID file found" };
-  try {
-    if (process.platform === "win32") {
-      execSync(`taskkill /PID ${pid} /F /T`, { stdio: "pipe", windowsHide: true });
-    } else {
-      process.kill(pid, "SIGTERM");
-    }
-    return { ok: true };
-  } catch (err) {
-    return { ok: false, error: (err as Error).message };
-  }
-}
-
-function validateCli(tool: string): { ok: boolean; path?: string; error?: string } {
-  const cfg = loadConfig();
-  let cmd: string;
-  if (tool === "cursor") {
-    cmd = readToolPath(cfg.cursor) || detectCursorAgentPath();
-  } else {
-    cmd = readToolPath(cfg.codex) || "codex";
-  }
-  try {
-    const out = execSync(`"${cmd}" --version`, { encoding: "utf8", timeout: 10000, windowsHide: true }).trim();
-    return { ok: true, path: cmd, error: out.slice(0, 200) };
-  } catch (err) {
-    return { ok: false, path: cmd, error: (err as Error).message };
-  }
-}
-
-function detectCursorAgentPath(): string {
-  const localAppData = process.env.LOCALAPPDATA;
-  if (localAppData) {
-    const defaultPath = join(localAppData, "cursor-agent", "agent.cmd");
-    if (existsSync(defaultPath)) return defaultPath;
-  }
-  return "agent";
-}
-
-// ---------------------------------------------------------------------------
-// Helpers — HTTP
-// ---------------------------------------------------------------------------
-
-function jsonReply(res: ServerResponse, code: number, data: unknown): void {
-  res.writeHead(code, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(JSON.stringify(data));
-}
-
-function readRequestBody(req: IncomingMessage): Promise<string> {
-  return new Promise((resolve) => {
-    let body = "";
-    req.on("data", (chunk: Buffer) => { body += chunk.toString(); });
-    req.on("end", () => resolve(body));
-  });
-}
-
-// ---------------------------------------------------------------------------
-// API route handlers
-// ---------------------------------------------------------------------------
-
-async function handleApiCheck(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const hasConfig = existsSync(CONFIG_FILE);
-  let hasCreds = false;
-  if (hasConfig) {
-    const c = loadConfig();
-    const feishuEnabled = c.platforms?.feishu?.enabled !== false; // 默认 true（向后兼容）
-    const feishuOk = feishuEnabled && Boolean(c.feishu?.appId?.trim() && c.feishu?.appSecret?.trim());
-    hasCreds = feishuOk || !feishuEnabled;
-  }
-  jsonReply(res, 200, { hasConfig, hasCreds, configPath: CONFIG_FILE });
-}
-
-async function handleGetConfig(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const running = isServiceRunning();
-  const pid = getServicePid();
-  const vars = loadConfig();
-  let ilinkAuthExists = false;
-  if (existsSync(ILINK_AUTH_PATH)) {
-    try {
-      const auth = JSON.parse(readFileSync(ILINK_AUTH_PATH, "utf8"));
-      ilinkAuthExists = Boolean(auth.token);
-    } catch { /* ignore parse errors */ }
-  }
-  jsonReply(res, 200, { vars, running, pid, ilinkAuthExists });
-}
-
-async function handlePostConfig(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const body = await readRequestBody(req);
-  let updates: Record<string, unknown>;
-  try {
-    const parsed = JSON.parse(body);
-    updates = parsed.vars ?? {};
-  } catch {
-    jsonReply(res, 400, { ok: false, error: "Invalid JSON" });
-    return;
-  }
-  const existing = loadConfig();
-  // AppConfig 是闭合接口（无 index signature），但运行时本质就是 JSON 对象，
-  // 这里通过 unknown 桥接到 Record 让 deepMerge 能复用；写回前断言回 AppConfig。
-  const merged = deepMerge(
-    existing as unknown as Record<string, unknown>,
-    unflattenConfig(updates),
-  ) as AppConfig;
-  try {
-    saveConfig(merged);
-    const applyResult = await applySavedConfigIfPossible(existing, merged);
-    jsonReply(res, 200, { ok: true, ...applyResult });
-  } catch (err) {
-    jsonReply(res, 500, { ok: false, saved: true, error: (err as Error).message });
-  }
-}
-
-function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
-  const result = { ...target };
-  for (const [key, val] of Object.entries(source)) {
-    if (val !== null && typeof val === "object" && !Array.isArray(val) && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key])) {
-      result[key] = deepMerge(result[key] as Record<string, unknown>, val as Record<string, unknown>);
-    } else {
-      result[key] = val;
-    }
-  }
-  return result;
-}
-
-// Convert flat key-value pairs to nested config structure
-export function unflattenConfig(flat: Record<string, unknown>): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const [key, val] of Object.entries(flat)) {
-    if (key === "CHATCCC_APP_ID") {
-      result.feishu = result.feishu || {};
-      (result.feishu as Record<string, unknown>).appId = val;
-    } else if (key === "CHATCCC_APP_SECRET") {
-      result.feishu = result.feishu || {};
-      (result.feishu as Record<string, unknown>).appSecret = val;
-    } else if (key === "CHATCCC_FEISHU_ENABLED") {
-      result.platforms = result.platforms || {};
-      (result.platforms as Record<string, unknown>).feishu = (result.platforms as Record<string, unknown>).feishu || {};
-      ((result.platforms as Record<string, unknown>).feishu as Record<string, unknown>).enabled = val === true || val === "true";
-    } else if (key === "CHATCCC_FEISHU_PLATFORM_TYPE") {
-      result.platforms = result.platforms || {};
-      (result.platforms as Record<string, unknown>).feishu = (result.platforms as Record<string, unknown>).feishu || {};
-      ((result.platforms as Record<string, unknown>).feishu as Record<string, unknown>).platformType = val;
-    } else if (key === "CHATCCC_ILINK_ENABLED") {
-      result.platforms = result.platforms || {};
-      (result.platforms as Record<string, unknown>).ilink = (result.platforms as Record<string, unknown>).ilink || {};
-      ((result.platforms as Record<string, unknown>).ilink as Record<string, unknown>).enabled = val === true || val === "true";
-    } else if (key === "CHATCCC_WEB_UI_OPEN_ON_START") {
-      result.webUi = result.webUi || {};
-      (result.webUi as Record<string, unknown>).openOnStart = val === true || val === "true";
-    } else if (key === "CHATCCC_CHROME_DEVTOOLS_ENABLED") {
-      result.chromeDevtools = result.chromeDevtools || {};
-      (result.chromeDevtools as Record<string, unknown>).enabled = val === true || val === "true";
-    } else if (key === "CHATCCC_CHROME_DEVTOOLS_PORT") {
-      result.chromeDevtools = result.chromeDevtools || {};
-      (result.chromeDevtools as Record<string, unknown>).port = parseInt(val as string, 10) || 15166;
-    } else if (key === "CHATCCC_CHROME_DEVTOOLS_PATH") {
-      result.chromeDevtools = result.chromeDevtools || {};
-      (result.chromeDevtools as Record<string, unknown>).chromePath = val;
-    } else if (key === "CHATCCC_PORT") {
-      result.port = parseInt(val as string, 10) || 18080;
-    } else if (key === "CHATCCC_GIT_TIMEOUT_SECONDS") {
-      result.gitTimeoutSeconds = parseInt(val as string, 10) || 180;
-    } else if (key === "CHATCCC_ANTHROPIC_MODEL") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).model = val;
-    } else if (key === "CHATCCC_ANTHROPIC_SUBAGENT_MODEL") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).subagentModel = val;
-    } else if (key === "CHATCCC_ANTHROPIC_EFFORT") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).effort = val;
-    } else if (key === "CHATCCC_ANTHROPIC_API_KEY") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).apiKey = val;
-    } else if (key === "CHATCCC_ANTHROPIC_BASE_URL") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).baseUrl = val;
-    } else if (key === "CHATCCC_ANTHROPIC_MAX_TURN") {
-      result.claude = result.claude || {};
-      (result.claude as Record<string, unknown>).maxTurn = (function(v){ var n = parseInt(v, 10); return isNaN(n) ? 0 : n; })(val as string);
-    } 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;
-    } else if (key === "CHATCCC_CURSOR_MODEL") {
-      result.cursor = result.cursor || {};
-      (result.cursor as Record<string, unknown>).model = val;
-    } else if (key === "CHATCCC_CURSOR_ALTERNATIVE_MODEL") {
-      result.cursor = result.cursor || {};
-      (result.cursor as Record<string, unknown>).alternativeModel = val;
-    } else if (key === "CHATCCC_CURSOR_AVATAR_BATTERY_MODE") {
-      result.cursor = result.cursor || {};
-      (result.cursor as Record<string, unknown>).avatarBatteryMode = val;
-    } else if (key === "CHATCCC_CURSOR_ON_DEMAND_MONTHLY_BUDGET") {
-      result.cursor = result.cursor || {};
-      (result.cursor as Record<string, unknown>).onDemandMonthlyBudget = Number(val);
-    } 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;
-    } else if (key === "CHATCCC_CODEX_MODEL") {
-      result.codex = result.codex || {};
-      (result.codex as Record<string, unknown>).model = val;
-    } else if (key === "CHATCCC_CODEX_ALTERNATIVE_MODEL") {
-      result.codex = result.codex || {};
-      (result.codex as Record<string, unknown>).alternativeModel = val;
-    } else if (key === "CHATCCC_CODEX_EFFORT") {
-      result.codex = result.codex || {};
-      (result.codex as Record<string, unknown>).effort = val;
-    } else if (key === "CHATCCC_CODEX_FAST_MODE") {
-      result.codex = result.codex || {};
-      (result.codex as Record<string, unknown>).fastMode = val === true || val === "true";
-    } 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";
-    } else if (key === "CHATCCC_CCC_API_KEY") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).DEEPSEEK_API_KEY = val;
-    } else if (key === "CHATCCC_CCC_BASE_URL") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).DEEPSEEK_BASE_URL = val;
-    } else if (key === "CHATCCC_CCC_MODEL") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).model = val;
-    } else if (key === "CHATCCC_CCC_ALTERNATIVE_MODEL") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).alternativeModel = val;
-    } else if (key === "CHATCCC_CCC_EFFORT") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).effort = val;
-    } else if (key === "CHATCCC_CCC_PROVIDER") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).provider = val;
-    } else if (key === "CHATCCC_CCC_ENABLED") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).enabled = val === true || val === "true";
-    } else if (key === "CHATCCC_CCC_DEFAULT_AGENT") {
-      result.ccc = result.ccc || {};
-      (result.ccc as Record<string, unknown>).defaultAgent = val === true || val === "true";
-    }
-  }
-  return result;
-}
-
-async function handleGetStatus(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const running = isServiceRunning();
-  const pid = getServicePid();
-  const uptime = running ? getServiceUptime() : null;
-  jsonReply(res, 200, { running, pid, uptime });
-}
-
-async function handleStartService(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const path = chooseStartPath({
-    hasInplaceActivateHook: Boolean(setupActivateHook && setupHttpServer),
-    isServiceRunning: isServiceRunning(),
-  });
-
-  if (path === "inplace") {
-    // setup 模式：原地启动飞书 service，复用 setup HTTP server，不动 PID 文件。
-    // 注意 hook 和 setupHttpServer 在 chooseStartPath() 之后**绝不会被并发清空**
-    // —— init 时一次性赋值，且当前函数是 onActivate 唯一调用点；非 null 断言安全。
-    const hook = setupActivateHook!;
-    const server = setupHttpServer!;
-    const result = await hook(server);
-    if (result.ok) {
-      // 切换成功：清掉 hook 防止再次走 inplace 路径（service 已经在跑了）。
-      // setupHttpServer 不清 —— 它已经接管为 service server，dashboard 仍要用。
-      setupActivateHook = null;
-      jsonReply(res, 200, { ok: true, pid: process.pid, mode: "inplace" });
-    } else {
-      jsonReply(res, 500, { ok: false, error: result.error });
-    }
-    return;
-  }
-
-  if (path === "reload") {
-    // service 已经在跑：只刷新进程内配置，让后续消息/新会话使用新值。
-    if (!reloadConfigHook) {
-      jsonReply(res, 200, { ok: true, pid: process.pid, mode: "saved" });
-      return;
-    }
-    try {
-      await reloadConfigHook();
-      jsonReply(res, 200, { ok: true, pid: process.pid, mode: "reload" });
-    } catch (err) {
-      jsonReply(res, 500, { ok: false, error: (err as Error).message });
-    }
-    return;
-  }
-
-  const result = spawnService();
-  if (result.ok) {
-    await new Promise((r) => setTimeout(r, 1000));
-    jsonReply(res, 200, { ok: true, pid: result.pid, mode: "spawn" });
-  } else {
-    jsonReply(res, 500, result);
-  }
-}
-
-async function handleStopService(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const running = isServiceRunning();
-  if (!running) {
-    jsonReply(res, 200, { ok: false, error: "Service is not running" });
-    return;
-  }
-  jsonReply(res, 200, { ok: true });
-  setImmediate(() => {
-    stopService();
-  });
-}
-
-async function handleRestartService(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  jsonReply(res, 200, { ok: true, message: "Restarting..." });
-  scheduleRestart();
-  process.exit(0);
-}
-
-async function handleValidate(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const body = await readRequestBody(req);
-  let tool: string;
-  try { tool = JSON.parse(body).tool; } catch {
-    jsonReply(res, 400, { ok: false, error: "Missing tool" });
-    return;
-  }
-  const result = validateCli(tool);
-  jsonReply(res, 200, result);
-}
-
-async function handleForgetIlink(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  try {
-    if (existsSync(ILINK_AUTH_PATH)) {
-      unlinkSync(ILINK_AUTH_PATH);
-    }
-    jsonReply(res, 200, { ok: true });
-  } catch (err) {
-    jsonReply(res, 500, { ok: false, error: (err as Error).message });
-  }
-}
-
-async function handleClaudeSdkStatus(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const progress = getLastInstallProgress();
-  jsonReply(res, 200, {
-    installed: isClaudeSdkInstalled(),
-    version: getClaudeSdkInstalledVersion(),
-    running: isInstallRunning(),
-    // 展开到顶层：前端轮询 JS 读顶层 phase/message/percent/error（历史契约），
-    // 若只放在 progress 嵌套里，前端 s.phase 恒为 undefined → 进度条永不渲染。
-    ...progress,
-    // 保留嵌套结构，兼容其它调用方。
-    progress,
-  });
-}
-
-async function handleClaudeSdkInstall(_req: IncomingMessage, res: ServerResponse): Promise<void> {
-  if (isInstallRunning()) {
-    jsonReply(res, 200, { ok: true, alreadyRunning: true });
-    return;
-  }
-  try {
-    // 后台执行，不阻塞响应；前端通过 /api/claude-sdk/status 轮询进度
-    installClaudeSdk().catch((err: unknown) => {
-      console.error(`[WEB-UI] Claude SDK 安装失败: ${(err as Error).message}`);
-    });
-    jsonReply(res, 200, { ok: true });
-  } catch (err) {
-    jsonReply(res, 500, { ok: false, error: (err as Error).message });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// HTML page (embedded template)
-// ---------------------------------------------------------------------------
-
-/** Agent Team 的首个占位页面：按产品约定只展示标题，不提前放入功能内容。 */
-export const AGENT_TEAM_PAGE_HTML = `<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Agent Team</title>
-<style>
-*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
-body{min-height:100vh;display:grid;place-items:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:radial-gradient(circle at 50% 20%,#312e81 0,#111827 42%,#020617 100%);color:#fff}
-h1{font-size:clamp(40px,8vw,88px);font-weight:750;letter-spacing:-.04em;text-shadow:0 12px 42px rgba(129,140,248,.45)}
-</style>
-</head>
-<body>
-  <h1>Agent Team</h1>
-</body>
-</html>`;
-
-export const PAGE_HTML = `<!DOCTYPE html>
+// =============================================================================
+// web-ui.ts — Setup Wizard & Management Dashboard HTTP Server
+// =============================================================================
+// Serves on the same port as the WebSocket relay (18080 default).
+// - Setup mode: no config.json → show setup wizard, skip Feishu connection
+// - Dashboard mode: config.json exists → serve management page alongside WS relay
+// =============================================================================
+import { createServer } from "node:http";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn, execSync } from "node:child_process";
+import { CHATCCC_PACKAGE_ROOT } from "./package-root.js";
+import { resolveChatCccRuntimeSpawnSpec } from "./runtime-entry.js";
+import { handleAgentTeamRequest } from "./agent-team/http/board-routes.js";
+import { AGENT_TEAM_PAGE_HTML } from "./agent-team/web/agent-team-page.js";
+export { AGENT_TEAM_PAGE_HTML } from "./agent-team/web/agent-team-page.js";
+import { buildWebUiUrl, createInternalRestartEnv, openWebUiInDefaultBrowser, } from "./startup-lifecycle.js";
+import { getClaudeSdkInstalledVersion, getLastInstallProgress, installClaudeSdk, isClaudeSdkInstalled, isInstallRunning, } from "./claude-sdk-installer.js";
+const PROJECT_ROOT = CHATCCC_PACKAGE_ROOT;
+const USER_DATA_DIR = join(homedir(), ".chatccc");
+const CONFIG_FILE = join(USER_DATA_DIR, "config.json");
+const CONFIG_SAMPLE_FILE = join(PROJECT_ROOT, "config.sample.json");
+const PID_FILE = join(USER_DATA_DIR, "state", "runtime.pid");
+const ILINK_AUTH_PATH = join(USER_DATA_DIR, "state", "ilink-auth.json");
+export function chooseStartPath(input) {
+    if (input.hasInplaceActivateHook)
+        return "inplace";
+    if (input.isServiceRunning)
+        return "reload";
+    return "spawn";
+}
+/** 读取 cursor / codex 的 CLI 路径，优先新字段 path，回退旧字段 command */
+function readToolPath(tool) {
+    if (!tool)
+        return "";
+    if (tool.path && tool.path.trim())
+        return tool.path;
+    if (tool.command && tool.command.trim())
+        return tool.command;
+    return "";
+}
+function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        let raw = readFileSync(CONFIG_FILE, "utf8");
+        // 移除可能意外写入的 UTF-8 BOM，避免 JSON.parse 失败导致返回空对象、
+        // UI 显示所有配置为空。
+        if (raw.charCodeAt(0) === 0xfeff)
+            raw = raw.slice(1);
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function saveConfig(cfg) {
+    writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf8");
+}
+function stringValue(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function portValue(cfg) {
+    return Number.isInteger(cfg.port) && cfg.port >= 1 && cfg.port <= 65535 ? cfg.port : 18080;
+}
+function platformEnabled(cfg, platform) {
+    return cfg.platforms?.[platform]?.enabled !== false;
+}
+function feishuPlatformType(cfg) {
+    return cfg.platforms?.feishu?.platformType === "lark" ? "lark" : "feishu";
+}
+function ilinkReuseTokenOnStart(cfg) {
+    return cfg.platforms?.ilink?.reuseTokenOnStart !== false;
+}
+export function getRestartRequiredReasons(before, after) {
+    const reasons = [];
+    if (portValue(before) !== portValue(after))
+        reasons.push("port");
+    if (stringValue(before.feishu?.appId) !== stringValue(after.feishu?.appId))
+        reasons.push("feishu.appId");
+    if (stringValue(before.feishu?.appSecret) !== stringValue(after.feishu?.appSecret))
+        reasons.push("feishu.appSecret");
+    if (feishuPlatformType(before) !== feishuPlatformType(after))
+        reasons.push("platforms.feishu.platformType");
+    if (platformEnabled(before, "feishu") !== platformEnabled(after, "feishu"))
+        reasons.push("platforms.feishu.enabled");
+    if (platformEnabled(before, "ilink") !== platformEnabled(after, "ilink"))
+        reasons.push("platforms.ilink.enabled");
+    if (ilinkReuseTokenOnStart(before) !== ilinkReuseTokenOnStart(after)) {
+        reasons.push("platforms.ilink.reuseTokenOnStart");
+    }
+    return reasons;
+}
+async function applySavedConfigIfPossible(before, after) {
+    const setupMode = Boolean(setupActivateHook && setupHttpServer);
+    if (setupMode) {
+        return { mode: "saved", restartRequired: false, restartReasons: [] };
+    }
+    const running = isServiceRunning();
+    if (!running) {
+        return { mode: "saved", restartRequired: false, restartReasons: [] };
+    }
+    const restartReasons = getRestartRequiredReasons(before, after);
+    if (restartReasons.length > 0) {
+        return { mode: "restart-required", restartRequired: true, restartReasons };
+    }
+    if (!reloadConfigHook) {
+        return { mode: "saved", restartRequired: false, restartReasons: [] };
+    }
+    await reloadConfigHook();
+    return { mode: "reload", restartRequired: false, restartReasons: [] };
+}
+function maskSecret(value) {
+    if (!value)
+        return "(未设置)";
+    if (value.length <= 8)
+        return "***";
+    return value.slice(0, 4) + "***" + value.slice(-4);
+}
+// ---------------------------------------------------------------------------
+// Helpers — process management
+// ---------------------------------------------------------------------------
+function isServiceRunning() {
+    if (!existsSync(PID_FILE))
+        return false;
+    try {
+        const raw = readFileSync(PID_FILE, "utf8").trim();
+        const pid = parseInt(raw, 10);
+        if (isNaN(pid))
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getServicePid() {
+    if (!existsSync(PID_FILE))
+        return null;
+    try {
+        const pid = parseInt(readFileSync(PID_FILE, "utf8").trim(), 10);
+        return isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+function getServiceUptime() {
+    try {
+        const s = statSync(PID_FILE);
+        return Math.floor((Date.now() - s.mtimeMs) / 1000);
+    }
+    catch {
+        return null;
+    }
+}
+import { statSync } from "node:fs";
+function spawnService() {
+    const spec = resolveChatCccRuntimeSpawnSpec(PROJECT_ROOT);
+    if (!existsSync(spec.args[0]))
+        return { ok: false, error: `Entry not found: ${spec.args[0]}` };
+    try {
+        const child = spawn(spec.command, spec.args, {
+            cwd: PROJECT_ROOT,
+            detached: true,
+            stdio: "ignore",
+            shell: false,
+            env: createInternalRestartEnv(),
+        });
+        child.unref();
+        return { ok: true, pid: child.pid ?? undefined };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+/**
+ * 安排一次真正的进程重启：先回复 HTTP 请求，再 spawn 一个延迟启动的子进程，
+ * 然后退出当前进程。延迟是为了让当前进程完全退出并释放端口。
+ */
+function scheduleRestart() {
+    const spec = resolveChatCccRuntimeSpawnSpec(PROJECT_ROOT);
+    if (!existsSync(spec.args[0]))
+        return;
+    const delayedLauncher = [
+        "const { spawn } = require('node:child_process');",
+        `const command = ${JSON.stringify(spec.command)};`,
+        `const args = ${JSON.stringify(spec.args)};`,
+        `const cwd = ${JSON.stringify(PROJECT_ROOT)};`,
+        "setTimeout(() => {",
+        "  const child = spawn(command, args, { cwd, detached: true, stdio: 'ignore', shell: false, env: process.env });",
+        "  child.unref();",
+        "}, 2000);",
+    ].join("\n");
+    if (process.platform === "win32") {
+        // Windows keeps the helper window hidden; the helper itself provides the delay.
+        spawn(process.execPath, ["-e", delayedLauncher], {
+            cwd: PROJECT_ROOT,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: createInternalRestartEnv(),
+        }).unref();
+    }
+    else {
+        spawn(process.execPath, ["-e", delayedLauncher], {
+            cwd: PROJECT_ROOT,
+            detached: true,
+            stdio: "ignore",
+            env: createInternalRestartEnv(),
+        }).unref();
+    }
+}
+function stopService() {
+    const pid = getServicePid();
+    if (!pid)
+        return { ok: false, error: "No PID file found" };
+    try {
+        if (process.platform === "win32") {
+            execSync(`taskkill /PID ${pid} /F /T`, { stdio: "pipe", windowsHide: true });
+        }
+        else {
+            process.kill(pid, "SIGTERM");
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+function validateCli(tool) {
+    const cfg = loadConfig();
+    let cmd;
+    if (tool === "cursor") {
+        cmd = readToolPath(cfg.cursor) || detectCursorAgentPath();
+    }
+    else {
+        cmd = readToolPath(cfg.codex) || "codex";
+    }
+    try {
+        const out = execSync(`"${cmd}" --version`, { encoding: "utf8", timeout: 10000, windowsHide: true }).trim();
+        return { ok: true, path: cmd, error: out.slice(0, 200) };
+    }
+    catch (err) {
+        return { ok: false, path: cmd, error: err.message };
+    }
+}
+function detectCursorAgentPath() {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (localAppData) {
+        const defaultPath = join(localAppData, "cursor-agent", "agent.cmd");
+        if (existsSync(defaultPath))
+            return defaultPath;
+    }
+    return "agent";
+}
+// ---------------------------------------------------------------------------
+// Helpers — HTTP
+// ---------------------------------------------------------------------------
+function jsonReply(res, code, data) {
+    res.writeHead(code, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(data));
+}
+function readRequestBody(req) {
+    return new Promise((resolve) => {
+        let body = "";
+        req.on("data", (chunk) => { body += chunk.toString(); });
+        req.on("end", () => resolve(body));
+    });
+}
+// ---------------------------------------------------------------------------
+// API route handlers
+// ---------------------------------------------------------------------------
+async function handleApiCheck(_req, res) {
+    const hasConfig = existsSync(CONFIG_FILE);
+    let hasCreds = false;
+    if (hasConfig) {
+        const c = loadConfig();
+        const feishuEnabled = c.platforms?.feishu?.enabled !== false; // 默认 true（向后兼容）
+        const feishuOk = feishuEnabled && Boolean(c.feishu?.appId?.trim() && c.feishu?.appSecret?.trim());
+        hasCreds = feishuOk || !feishuEnabled;
+    }
+    jsonReply(res, 200, { hasConfig, hasCreds, configPath: CONFIG_FILE });
+}
+async function handleGetConfig(_req, res) {
+    const running = isServiceRunning();
+    const pid = getServicePid();
+    const vars = loadConfig();
+    let ilinkAuthExists = false;
+    if (existsSync(ILINK_AUTH_PATH)) {
+        try {
+            const auth = JSON.parse(readFileSync(ILINK_AUTH_PATH, "utf8"));
+            ilinkAuthExists = Boolean(auth.token);
+        }
+        catch { /* ignore parse errors */ }
+    }
+    jsonReply(res, 200, { vars, running, pid, ilinkAuthExists });
+}
+async function handlePostConfig(req, res) {
+    const body = await readRequestBody(req);
+    let updates;
+    try {
+        const parsed = JSON.parse(body);
+        updates = parsed.vars ?? {};
+    }
+    catch {
+        jsonReply(res, 400, { ok: false, error: "Invalid JSON" });
+        return;
+    }
+    const existing = loadConfig();
+    // AppConfig 是闭合接口（无 index signature），但运行时本质就是 JSON 对象，
+    // 这里通过 unknown 桥接到 Record 让 deepMerge 能复用；写回前断言回 AppConfig。
+    const merged = deepMerge(existing, unflattenConfig(updates));
+    try {
+        saveConfig(merged);
+        const applyResult = await applySavedConfigIfPossible(existing, merged);
+        jsonReply(res, 200, { ok: true, ...applyResult });
+    }
+    catch (err) {
+        jsonReply(res, 500, { ok: false, saved: true, error: err.message });
+    }
+}
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, val] of Object.entries(source)) {
+        if (val !== null && typeof val === "object" && !Array.isArray(val) && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key])) {
+            result[key] = deepMerge(result[key], val);
+        }
+        else {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+// Convert flat key-value pairs to nested config structure
+export function unflattenConfig(flat) {
+    const result = {};
+    for (const [key, val] of Object.entries(flat)) {
+        if (key === "CHATCCC_APP_ID") {
+            result.feishu = result.feishu || {};
+            result.feishu.appId = val;
+        }
+        else if (key === "CHATCCC_APP_SECRET") {
+            result.feishu = result.feishu || {};
+            result.feishu.appSecret = val;
+        }
+        else if (key === "CHATCCC_FEISHU_ENABLED") {
+            result.platforms = result.platforms || {};
+            result.platforms.feishu = result.platforms.feishu || {};
+            result.platforms.feishu.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_FEISHU_PLATFORM_TYPE") {
+            result.platforms = result.platforms || {};
+            result.platforms.feishu = result.platforms.feishu || {};
+            result.platforms.feishu.platformType = val;
+        }
+        else if (key === "CHATCCC_ILINK_ENABLED") {
+            result.platforms = result.platforms || {};
+            result.platforms.ilink = result.platforms.ilink || {};
+            result.platforms.ilink.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_WEB_UI_OPEN_ON_START") {
+            result.webUi = result.webUi || {};
+            result.webUi.openOnStart = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CHROME_DEVTOOLS_ENABLED") {
+            result.chromeDevtools = result.chromeDevtools || {};
+            result.chromeDevtools.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CHROME_DEVTOOLS_PORT") {
+            result.chromeDevtools = result.chromeDevtools || {};
+            result.chromeDevtools.port = parseInt(val, 10) || 15166;
+        }
+        else if (key === "CHATCCC_CHROME_DEVTOOLS_PATH") {
+            result.chromeDevtools = result.chromeDevtools || {};
+            result.chromeDevtools.chromePath = val;
+        }
+        else if (key === "CHATCCC_PORT") {
+            result.port = parseInt(val, 10) || 18080;
+        }
+        else if (key === "CHATCCC_GIT_TIMEOUT_SECONDS") {
+            result.gitTimeoutSeconds = parseInt(val, 10) || 180;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_MODEL") {
+            result.claude = result.claude || {};
+            result.claude.model = val;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_SUBAGENT_MODEL") {
+            result.claude = result.claude || {};
+            result.claude.subagentModel = val;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_EFFORT") {
+            result.claude = result.claude || {};
+            result.claude.effort = val;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_API_KEY") {
+            result.claude = result.claude || {};
+            result.claude.apiKey = val;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_BASE_URL") {
+            result.claude = result.claude || {};
+            result.claude.baseUrl = val;
+        }
+        else if (key === "CHATCCC_ANTHROPIC_MAX_TURN") {
+            result.claude = result.claude || {};
+            result.claude.maxTurn = (function (v) { var n = parseInt(v, 10); return isNaN(n) ? 0 : n; })(val);
+        }
+        else if (key === "CHATCCC_CLAUDE_ENABLED") {
+            result.claude = result.claude || {};
+            result.claude.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CLAUDE_DEFAULT_AGENT") {
+            result.claude = result.claude || {};
+            result.claude.defaultAgent = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CURSOR_PATH") {
+            result.cursor = result.cursor || {};
+            result.cursor.path = val;
+        }
+        else if (key === "CHATCCC_CURSOR_MODEL") {
+            result.cursor = result.cursor || {};
+            result.cursor.model = val;
+        }
+        else if (key === "CHATCCC_CURSOR_ALTERNATIVE_MODEL") {
+            result.cursor = result.cursor || {};
+            result.cursor.alternativeModel = val;
+        }
+        else if (key === "CHATCCC_CURSOR_AVATAR_BATTERY_MODE") {
+            result.cursor = result.cursor || {};
+            result.cursor.avatarBatteryMode = val;
+        }
+        else if (key === "CHATCCC_CURSOR_ON_DEMAND_MONTHLY_BUDGET") {
+            result.cursor = result.cursor || {};
+            result.cursor.onDemandMonthlyBudget = Number(val);
+        }
+        else if (key === "CHATCCC_CURSOR_ENABLED") {
+            result.cursor = result.cursor || {};
+            result.cursor.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CURSOR_DEFAULT_AGENT") {
+            result.cursor = result.cursor || {};
+            result.cursor.defaultAgent = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CODEX_PATH") {
+            result.codex = result.codex || {};
+            result.codex.path = val;
+        }
+        else if (key === "CHATCCC_CODEX_MODEL") {
+            result.codex = result.codex || {};
+            result.codex.model = val;
+        }
+        else if (key === "CHATCCC_CODEX_ALTERNATIVE_MODEL") {
+            result.codex = result.codex || {};
+            result.codex.alternativeModel = val;
+        }
+        else if (key === "CHATCCC_CODEX_EFFORT") {
+            result.codex = result.codex || {};
+            result.codex.effort = val;
+        }
+        else if (key === "CHATCCC_CODEX_FAST_MODE") {
+            result.codex = result.codex || {};
+            result.codex.fastMode = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CODEX_ENABLED") {
+            result.codex = result.codex || {};
+            result.codex.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CODEX_DEFAULT_AGENT") {
+            result.codex = result.codex || {};
+            result.codex.defaultAgent = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CCC_API_KEY") {
+            result.ccc = result.ccc || {};
+            result.ccc.DEEPSEEK_API_KEY = val;
+        }
+        else if (key === "CHATCCC_CCC_BASE_URL") {
+            result.ccc = result.ccc || {};
+            result.ccc.DEEPSEEK_BASE_URL = val;
+        }
+        else if (key === "CHATCCC_CCC_MODEL") {
+            result.ccc = result.ccc || {};
+            result.ccc.model = val;
+        }
+        else if (key === "CHATCCC_CCC_ALTERNATIVE_MODEL") {
+            result.ccc = result.ccc || {};
+            result.ccc.alternativeModel = val;
+        }
+        else if (key === "CHATCCC_CCC_EFFORT") {
+            result.ccc = result.ccc || {};
+            result.ccc.effort = val;
+        }
+        else if (key === "CHATCCC_CCC_PROVIDER") {
+            result.ccc = result.ccc || {};
+            result.ccc.provider = val;
+        }
+        else if (key === "CHATCCC_CCC_ENABLED") {
+            result.ccc = result.ccc || {};
+            result.ccc.enabled = val === true || val === "true";
+        }
+        else if (key === "CHATCCC_CCC_DEFAULT_AGENT") {
+            result.ccc = result.ccc || {};
+            result.ccc.defaultAgent = val === true || val === "true";
+        }
+    }
+    return result;
+}
+async function handleGetStatus(_req, res) {
+    const running = isServiceRunning();
+    const pid = getServicePid();
+    const uptime = running ? getServiceUptime() : null;
+    jsonReply(res, 200, { running, pid, uptime });
+}
+async function handleStartService(_req, res) {
+    const path = chooseStartPath({
+        hasInplaceActivateHook: Boolean(setupActivateHook && setupHttpServer),
+        isServiceRunning: isServiceRunning(),
+    });
+    if (path === "inplace") {
+        // setup 模式：原地启动飞书 service，复用 setup HTTP server，不动 PID 文件。
+        // 注意 hook 和 setupHttpServer 在 chooseStartPath() 之后**绝不会被并发清空**
+        // —— init 时一次性赋值，且当前函数是 onActivate 唯一调用点；非 null 断言安全。
+        const hook = setupActivateHook;
+        const server = setupHttpServer;
+        const result = await hook(server);
+        if (result.ok) {
+            // 切换成功：清掉 hook 防止再次走 inplace 路径（service 已经在跑了）。
+            // setupHttpServer 不清 —— 它已经接管为 service server，dashboard 仍要用。
+            setupActivateHook = null;
+            jsonReply(res, 200, { ok: true, pid: process.pid, mode: "inplace" });
+        }
+        else {
+            jsonReply(res, 500, { ok: false, error: result.error });
+        }
+        return;
+    }
+    if (path === "reload") {
+        // service 已经在跑：只刷新进程内配置，让后续消息/新会话使用新值。
+        if (!reloadConfigHook) {
+            jsonReply(res, 200, { ok: true, pid: process.pid, mode: "saved" });
+            return;
+        }
+        try {
+            await reloadConfigHook();
+            jsonReply(res, 200, { ok: true, pid: process.pid, mode: "reload" });
+        }
+        catch (err) {
+            jsonReply(res, 500, { ok: false, error: err.message });
+        }
+        return;
+    }
+    const result = spawnService();
+    if (result.ok) {
+        await new Promise((r) => setTimeout(r, 1000));
+        jsonReply(res, 200, { ok: true, pid: result.pid, mode: "spawn" });
+    }
+    else {
+        jsonReply(res, 500, result);
+    }
+}
+async function handleStopService(req, res) {
+    const running = isServiceRunning();
+    if (!running) {
+        jsonReply(res, 200, { ok: false, error: "Service is not running" });
+        return;
+    }
+    jsonReply(res, 200, { ok: true });
+    setImmediate(() => {
+        stopService();
+    });
+}
+async function handleRestartService(_req, res) {
+    jsonReply(res, 200, { ok: true, message: "Restarting..." });
+    scheduleRestart();
+    process.exit(0);
+}
+async function handleValidate(req, res) {
+    const body = await readRequestBody(req);
+    let tool;
+    try {
+        tool = JSON.parse(body).tool;
+    }
+    catch {
+        jsonReply(res, 400, { ok: false, error: "Missing tool" });
+        return;
+    }
+    const result = validateCli(tool);
+    jsonReply(res, 200, result);
+}
+async function handleForgetIlink(_req, res) {
+    try {
+        if (existsSync(ILINK_AUTH_PATH)) {
+            unlinkSync(ILINK_AUTH_PATH);
+        }
+        jsonReply(res, 200, { ok: true });
+    }
+    catch (err) {
+        jsonReply(res, 500, { ok: false, error: err.message });
+    }
+}
+async function handleClaudeSdkStatus(_req, res) {
+    const progress = getLastInstallProgress();
+    jsonReply(res, 200, {
+        installed: isClaudeSdkInstalled(),
+        version: getClaudeSdkInstalledVersion(),
+        running: isInstallRunning(),
+        // 展开到顶层：前端轮询 JS 读顶层 phase/message/percent/error（历史契约），
+        // 若只放在 progress 嵌套里，前端 s.phase 恒为 undefined → 进度条永不渲染。
+        ...progress,
+        // 保留嵌套结构，兼容其它调用方。
+        progress,
+    });
+}
+async function handleClaudeSdkInstall(_req, res) {
+    if (isInstallRunning()) {
+        jsonReply(res, 200, { ok: true, alreadyRunning: true });
+        return;
+    }
+    try {
+        // 后台执行，不阻塞响应；前端通过 /api/claude-sdk/status 轮询进度
+        installClaudeSdk().catch((err) => {
+            console.error(`[WEB-UI] Claude SDK 安装失败: ${err.message}`);
+        });
+        jsonReply(res, 200, { ok: true });
+    }
+    catch (err) {
+        jsonReply(res, 500, { ok: false, error: err.message });
+    }
+}
+// ---------------------------------------------------------------------------
+// HTML page (embedded template)
+// ---------------------------------------------------------------------------
+export const PAGE_HTML = `<!DOCTYPE html>
 <html lang="zh-CN">
 <head>
 <meta charset="UTF-8">
@@ -2386,145 +2323,122 @@ init();
 setTimeout(claudeEngineRefreshStatus, 300);
 </script>
 </body>
-</html>`;
-
-// ---------------------------------------------------------------------------
-// Router
-// ---------------------------------------------------------------------------
-
-async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const url = req.url ?? "/";
-  const method = req.method ?? "GET";
-  const pathname = url.split("?", 1)[0];
-
-  if (extraApiHandler && await extraApiHandler(req, res)) return;
-
-  // API routes
-  if (url === "/api/check" && method === "GET") return handleApiCheck(req, res);
-  if (url === "/api/config" && method === "GET") return handleGetConfig(req, res);
-  if (url === "/api/config" && method === "POST") return handlePostConfig(req, res);
-  if (url === "/api/status" && method === "GET") return handleGetStatus(req, res);
-  if (url === "/api/start" && method === "POST") return handleStartService(req, res);
-  if (url === "/api/stop" && method === "POST") return handleStopService(req, res);
-  if (url === "/api/restart" && method === "POST") return handleRestartService(req, res);
-  if (url === "/api/validate" && method === "POST") return handleValidate(req, res);
-  if (url === "/api/ilink/forget" && method === "POST") return handleForgetIlink(req, res);
-  if (url === "/api/claude-sdk/status" && method === "GET") return handleClaudeSdkStatus(req, res);
-  if (url === "/api/claude-sdk/install" && method === "POST") return handleClaudeSdkInstall(req, res);
-
-  if (method === "GET" && (pathname === "/agent-team" || pathname === "/agent-team/")) {
-    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-    res.end(AGENT_TEAM_PAGE_HTML);
-    return;
-  }
-
-  // Serve HTML page for all other GET requests
-  if (method === "GET") {
-    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-    res.end(PAGE_HTML);
-    return;
-  }
-
-  jsonReply(res, 404, { error: "Not found" });
-}
-
-export function createUiRouter(): (req: IncomingMessage, res: ServerResponse) => void {
-  return (req, res) => {
-    handleRequest(req, res).catch((err) => {
-      console.error(`[WEB-UI] Unhandled error: ${(err as Error).message}`);
-      if (!res.headersSent) jsonReply(res, 500, { error: "Internal error" });
-    });
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Setup mode entry point — called from index.ts when no credentials
-// ---------------------------------------------------------------------------
-
-/**
- * setup → service「在线切换」回调签名：
- *   - 入参 httpServer：setup 模式当前监听的 HTTP server，会被复用为 service 的
- *     relay server（避免 close + recreate 的端口竞态）。
- *   - 返回 { ok: true } 表示原地启动成功，前端会刷新进 dashboard。
- *   - 返回 { ok: false, error } 表示启动失败，前端会 toast 错误。
- *     setup HTTP server **必须仍然可用**，让用户改完 config 再试一次。
- */
-export type SetupActivateHook = (
-  httpServer: ReturnType<typeof createServer>,
-) => Promise<{ ok: true } | { ok: false; error: string }>;
-
-export interface StartSetupModeOptions {
-  onActivate?: SetupActivateHook;
-  /** 内部重启进入 setup 模式时设为 false，避免重复弹出系统浏览器。 */
-  openBrowser?: boolean;
-}
-
-// setup HTTP server + onActivate 回调通过模块级变量暴露给 handleStartService。
-// 一旦 onActivate 成功执行，setupActivateHook 会被清空——避免 dashboard 模式下
-// 用户再点"启动"时还走 inplace 路径（service 已经在跑了）。
-let setupHttpServer: ReturnType<typeof createServer> | null = null;
-let setupActivateHook: SetupActivateHook | null = null;
-
-// reload-config 回调：dashboard 模式下用户点"保存并启动"时，service 已经在跑，
-// 仅需要把磁盘上刚保存的 config.json 刷进进程内的 export let 常量（live binding）。
-// 由 index.ts 注入，因为 web-ui.ts 自身**不应**直接 import config.ts——后者顶层
-// 有 loadConfig 副作用，被 web-ui.ts 间接 import 会污染所有依赖 web-ui.ts 的单测。
-let reloadConfigHook: (() => void) | null = null;
-type ExtraApiHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean;
-let extraApiHandler: ExtraApiHandler | null = null;
-
-/**
- * 注册"reload config"回调。约定：
- * - 由 index.ts 在 main() 中一次性调用，传入 () => reloadConfigFromDisk()。
- * - handleStartService 在 path="reload" 分支会 await 调用一次；hook 抛错会被
- *   捕获并以 500 回前端，避免 service 死锁。
- */
-export function setReloadConfigHook(hook: () => void | Promise<void>): void {
-  reloadConfigHook = hook;
-}
-
-export function setExtraApiHandler(handler: ExtraApiHandler): void {
-  extraApiHandler = handler;
-}
-
-export function startSetupMode(
-  port: number,
-  options: StartSetupModeOptions = {},
-): ReturnType<typeof createServer> {
-  const router = createUiRouter();
-  const server = createServer(router);
-  setupHttpServer = server;
-  setupActivateHook = options.onActivate ?? null;
-
-  server.on("error", (err: NodeJS.ErrnoException) => {
-    if (err.code === "EADDRINUSE") {
-      console.error(`\n[WEB-UI] 端口 ${port} 已被占用。请检查是否有其他 ChatCCC 实例在运行。`);
-      console.error("  可以先停止旧进程，或修改 config.json 中的 port 为其他端口。");
-    } else {
-      console.error(`\n[WEB-UI] HTTP 服务器错误: ${err.message}`);
-    }
-    process.exit(1);
-  });
-
-  server.listen(port, "127.0.0.1", () => {
-    const url = buildWebUiUrl(port);
-    console.log("");
-    console.log("=".repeat(60));
-    console.log("  ChatCCC — 首次配置向导");
-    console.log("=".repeat(60));
-    console.log("  未检测到已配置的飞书凭证，已启动配置界面。");
-    if (options.openBrowser !== false) {
-      console.log(`  已启用启动时自动打开浏览器: ${url}`);
-    } else {
-      console.log(`  内部重启不会自动打开浏览器，请按需访问: ${url}`);
-    }
-    console.log("  若浏览器未自动弹出，请手动访问上面的地址。");
-    console.log("");
-    console.log("  在向导里填好 App ID / App Secret 后点「保存并启动」，");
-    console.log("  服务会在当前进程内直接激活，不需要重新运行 chatccc。");
-    console.log("=".repeat(60));
-    console.log("");
-    if (options.openBrowser !== false) openWebUiInDefaultBrowser(port);
-  });
-  return server;
-}
+</html>`;
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+async function handleRequest(req, res) {
+    const url = req.url ?? "/";
+    const method = req.method ?? "GET";
+    const pathname = url.split("?", 1)[0];
+    if (extraApiHandler && await extraApiHandler(req, res))
+        return;
+    if (await handleAgentTeamRequest(req, res))
+        return;
+    // API routes
+    if (url === "/api/check" && method === "GET")
+        return handleApiCheck(req, res);
+    if (url === "/api/config" && method === "GET")
+        return handleGetConfig(req, res);
+    if (url === "/api/config" && method === "POST")
+        return handlePostConfig(req, res);
+    if (url === "/api/status" && method === "GET")
+        return handleGetStatus(req, res);
+    if (url === "/api/start" && method === "POST")
+        return handleStartService(req, res);
+    if (url === "/api/stop" && method === "POST")
+        return handleStopService(req, res);
+    if (url === "/api/restart" && method === "POST")
+        return handleRestartService(req, res);
+    if (url === "/api/validate" && method === "POST")
+        return handleValidate(req, res);
+    if (url === "/api/ilink/forget" && method === "POST")
+        return handleForgetIlink(req, res);
+    if (url === "/api/claude-sdk/status" && method === "GET")
+        return handleClaudeSdkStatus(req, res);
+    if (url === "/api/claude-sdk/install" && method === "POST")
+        return handleClaudeSdkInstall(req, res);
+    if (method === "GET" && (pathname === "/agent-team" || pathname === "/agent-team/")) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(AGENT_TEAM_PAGE_HTML);
+        return;
+    }
+    // Serve HTML page for all other GET requests
+    if (method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(PAGE_HTML);
+        return;
+    }
+    jsonReply(res, 404, { error: "Not found" });
+}
+export function createUiRouter() {
+    return (req, res) => {
+        handleRequest(req, res).catch((err) => {
+            console.error(`[WEB-UI] Unhandled error: ${err.message}`);
+            if (!res.headersSent)
+                jsonReply(res, 500, { error: "Internal error" });
+        });
+    };
+}
+// setup HTTP server + onActivate 回调通过模块级变量暴露给 handleStartService。
+// 一旦 onActivate 成功执行，setupActivateHook 会被清空——避免 dashboard 模式下
+// 用户再点"启动"时还走 inplace 路径（service 已经在跑了）。
+let setupHttpServer = null;
+let setupActivateHook = null;
+// reload-config 回调：dashboard 模式下用户点"保存并启动"时，service 已经在跑，
+// 仅需要把磁盘上刚保存的 config.json 刷进进程内的 export let 常量（live binding）。
+// 由 index.ts 注入，因为 web-ui.ts 自身**不应**直接 import config.ts——后者顶层
+// 有 loadConfig 副作用，被 web-ui.ts 间接 import 会污染所有依赖 web-ui.ts 的单测。
+let reloadConfigHook = null;
+let extraApiHandler = null;
+/**
+ * 注册"reload config"回调。约定：
+ * - 由 index.ts 在 main() 中一次性调用，传入 () => reloadConfigFromDisk()。
+ * - handleStartService 在 path="reload" 分支会 await 调用一次；hook 抛错会被
+ *   捕获并以 500 回前端，避免 service 死锁。
+ */
+export function setReloadConfigHook(hook) {
+    reloadConfigHook = hook;
+}
+export function setExtraApiHandler(handler) {
+    extraApiHandler = handler;
+}
+export function startSetupMode(port, options = {}) {
+    const router = createUiRouter();
+    const server = createServer(router);
+    setupHttpServer = server;
+    setupActivateHook = options.onActivate ?? null;
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`\n[WEB-UI] 端口 ${port} 已被占用。请检查是否有其他 ChatCCC 实例在运行。`);
+            console.error("  可以先停止旧进程，或修改 config.json 中的 port 为其他端口。");
+        }
+        else {
+            console.error(`\n[WEB-UI] HTTP 服务器错误: ${err.message}`);
+        }
+        process.exit(1);
+    });
+    server.listen(port, "127.0.0.1", () => {
+        const url = buildWebUiUrl(port);
+        console.log("");
+        console.log("=".repeat(60));
+        console.log("  ChatCCC — 首次配置向导");
+        console.log("=".repeat(60));
+        console.log("  未检测到已配置的飞书凭证，已启动配置界面。");
+        if (options.openBrowser !== false) {
+            console.log(`  已启用启动时自动打开浏览器: ${url}`);
+        }
+        else {
+            console.log(`  内部重启不会自动打开浏览器，请按需访问: ${url}`);
+        }
+        console.log("  若浏览器未自动弹出，请手动访问上面的地址。");
+        console.log("");
+        console.log("  在向导里填好 App ID / App Secret 后点「保存并启动」，");
+        console.log("  服务会在当前进程内直接激活，不需要重新运行 chatccc。");
+        console.log("=".repeat(60));
+        console.log("");
+        if (options.openBrowser !== false)
+            openWebUiInDefaultBrowser(port);
+    });
+    return server;
+}