weacpx 0.4.0 → 0.4.2

package/dist/cli.js

@@ -2610,18 +2610,22 @@ class DaemonController {
   statusStore;
   startupPollIntervalMs;
   startupTimeoutMs;
+  onboardingStartupTimeoutMs;
   onStartupPoll;
   shutdownPollIntervalMs;
   shutdownTimeoutMs;
   onShutdownPoll;
+  now;
   constructor(paths, deps) {
     this.paths = paths;
     this.deps = deps;
     this.statusStore = new DaemonStatusStore(paths.statusFile);
     this.startupPollIntervalMs = deps.startupPollIntervalMs ?? 50;
     this.startupTimeoutMs = deps.startupTimeoutMs ?? 5000;
+    this.onboardingStartupTimeoutMs = deps.onboardingStartupTimeoutMs ?? 300000;
     this.shutdownPollIntervalMs = deps.shutdownPollIntervalMs ?? 50;
     this.shutdownTimeoutMs = deps.shutdownTimeoutMs ?? 5000;
+    this.now = deps.now ?? (() => Date.now());
     this.onStartupPoll = deps.onStartupPoll ?? (async () => {
       await new Promise((resolve) => setTimeout(resolve, this.startupPollIntervalMs));
     });
@@ -2648,7 +2652,7 @@ class DaemonController {
       status
     };
   }
-  async start() {
+  async start(options = {}) {
     const current = await this.getStatus();
     if (current.state === "running") {
       return { state: "already-running", pid: current.pid };
@@ -2657,9 +2661,9 @@ class DaemonController {
       throw new Error(`weacpx daemon process is already running (pid ${current.pid}) but status metadata is missing`);
     }
     await this.statusStore.clear();
-    const pid = await this.deps.spawnDetached();
+    const pid = await this.deps.spawnDetached(options);
     await this.writePid(pid);
-    await this.waitForStartupMetadata(pid);
+    await this.waitForStartupMetadata(pid, options.firstRunOnboarding ? this.onboardingStartupTimeoutMs : this.startupTimeoutMs, options.startupWait);
     return { state: "started", pid };
   }
   async stop() {
@@ -2695,9 +2699,10 @@ class DaemonController {
     await rm2(this.paths.pidFile, { force: true });
     await this.statusStore.clear();
   }
-  async waitForStartupMetadata(pid) {
-    const deadline = Date.now() + this.startupTimeoutMs;
-    while (Date.now() < deadline) {
+  async waitForStartupMetadata(pid, timeoutMs, startupWait) {
+    const startedAt = this.now();
+    const deadline = startedAt + timeoutMs;
+    while (this.now() < deadline) {
       const status = await this.statusStore.load();
       if (status?.pid === pid) {
         return;
@@ -2706,9 +2711,17 @@ class DaemonController {
         await this.clearRuntimeFiles();
         throw new Error(`weacpx daemon exited before reporting ready state (pid ${pid})`);
       }
+      if (startupWait?.shouldStopWaiting?.()) {
+        return;
+      }
+      await startupWait?.onPoll?.({
+        elapsedMs: this.now() - startedAt,
+        timeoutMs,
+        pid
+      });
       await this.onStartupPoll();
     }
-    throw new Error(`weacpx daemon did not report ready state within ${this.startupTimeoutMs}ms (pid ${pid})`);
+    throw new Error(`weacpx daemon did not report ready state within ${timeoutMs}ms (pid ${pid})`);
   }
   async waitForShutdown(pid) {
     const deadline = Date.now() + this.shutdownTimeoutMs;
@@ -2782,12 +2795,12 @@ import { spawn as spawn2 } from "node:child_process";
 function createDaemonController(paths, options) {
   return new DaemonController(paths, {
     isProcessRunning: options.isProcessRunning ?? defaultIsProcessRunning2,
-    spawnDetached: async () => {
+    spawnDetached: async (spawnOptions) => {
       await mkdir4(paths.runtimeDir, { recursive: true });
       const stdoutHandle = await open(paths.stdoutLog, "a");
       const stderrHandle = await open(paths.stderrLog, "a");
       try {
-        return await (options.spawnProcess ?? defaultSpawnProcess)(buildSpawnRequest(paths, options, stdoutHandle.fd, stderrHandle.fd));
+        return await (options.spawnProcess ?? defaultSpawnProcess)(buildSpawnRequest(paths, options, stdoutHandle.fd, stderrHandle.fd, spawnOptions));
       } finally {
         await stdoutHandle.close();
         await stderrHandle.close();
@@ -2804,7 +2817,7 @@ function defaultIsProcessRunning2(pid) {
     return false;
   }
 }
-function buildSpawnRequest(paths, options, stdoutFd, stderrFd) {
+function buildSpawnRequest(paths, options, stdoutFd, stderrFd, spawnOptions = {}) {
   const platform = options.platform ?? process.platform;
   if (platform === "win32") {
     return {
@@ -2825,7 +2838,8 @@ function buildSpawnRequest(paths, options, stdoutFd, stderrFd) {
           WEACPX_DAEMON_ARG1: "run",
           WEACPX_DAEMON_CWD: options.cwd,
           WEACPX_DAEMON_STDOUT: paths.stdoutLog,
-          WEACPX_DAEMON_STDERR: paths.stderrLog
+          WEACPX_DAEMON_STDERR: paths.stderrLog,
+          ...spawnOptions.firstRunOnboarding ? { WEACPX_FIRST_RUN_ONBOARDING: spawnOptions.firstRunOnboarding } : {}
         },
         stdio: ["ignore", "pipe", "ignore"],
         windowsHide: true
@@ -2839,7 +2853,10 @@ function buildSpawnRequest(paths, options, stdoutFd, stderrFd) {
     options: {
       cwd: options.cwd,
       detached: true,
-      env: options.env,
+      env: {
+        ...options.env,
+        ...spawnOptions.firstRunOnboarding ? { WEACPX_FIRST_RUN_ONBOARDING: spawnOptions.firstRunOnboarding } : {}
+      },
       stdio: ["ignore", stdoutFd, stderrFd]
     }
   };
@@ -9829,74 +9846,58 @@ var init_state_store = __esm(() => {
   init_types();
 });
 
-// src/channels/cli/weixin-provider.ts
-var weixinCliProvider;
-var init_weixin_provider = __esm(() => {
-  weixinCliProvider = {
-    type: "weixin",
-    displayName: "Weixin",
-    supportsLogin: true,
-    parseAddArgs(args) {
-      if (args.length > 0)
-        return { ok: false, message: `unknown weixin options: ${args.join(" ")}` };
-      return { ok: true, input: {} };
-    },
-    buildDefaultConfig(_input) {
-      return { id: "weixin", type: "weixin", enabled: true };
+// src/config/agent-templates.ts
+function getAgentTemplate(name) {
+  const template = TEMPLATES[name];
+  if (!template) {
+    return null;
+  }
+  return {
+    ...template
+  };
+}
+function listAgentTemplates() {
+  return Object.keys(TEMPLATES);
+}
+var TEMPLATES;
+var init_agent_templates = __esm(() => {
+  TEMPLATES = {
+    codex: {
+      driver: "codex"
     },
-    validateConfig(config2) {
-      const issues = [];
-      if (config2.id !== "weixin")
-        issues.push({ kind: "invalid-config", message: "weixin channel id must be weixin" });
-      if (config2.type !== "weixin")
-        issues.push({ kind: "invalid-config", message: "weixin channel type must be weixin" });
-      return issues;
+    claude: {
+      driver: "claude"
     },
-    renderSummary(config2) {
-      return [`type: ${config2.type}`, `enabled: ${config2.enabled}`];
+    opencode: {
+      driver: "opencode"
     },
-    async promptForMissingFields(input, _io) {
-      return input;
+    gemini: {
+      driver: "gemini"
     }
   };
 });
 
-// src/channels/cli/registry.ts
-function registerChannelCliProvider(provider) {
-  const type = provider.type.trim();
-  if (!type)
-    throw new Error("channel CLI provider type must be non-empty");
-  if (type.includes(":"))
-    throw new Error("channel CLI provider type must not contain ':'");
-  if (cliProviders.has(type)) {
-    throw new Error(`channel CLI provider is already registered: ${type}`);
-  }
-  cliProviders.set(type, provider);
-}
-function hasChannelCliProvider(type) {
-  bootstrapBuiltinChannelCliProviders();
-  return cliProviders.has(type);
-}
-function bootstrapBuiltinChannelCliProviders() {
-  if (builtinProvidersRegistered)
-    return;
-  builtinProvidersRegistered = true;
-  if (!cliProviders.has(weixinCliProvider.type))
-    registerChannelCliProvider(weixinCliProvider);
-}
-function listChannelCliProviders() {
-  bootstrapBuiltinChannelCliProviders();
-  return Array.from(cliProviders.values());
+// src/plugins/plugin-home.ts
+import { mkdir as mkdir6, writeFile as writeFile5 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+function resolvePluginHome(input = {}) {
+  if (input.pluginHome?.trim())
+    return input.pluginHome;
+  if (process.env.WEACPX_PLUGIN_HOME?.trim())
+    return process.env.WEACPX_PLUGIN_HOME;
+  const home = input.home ?? process.env.HOME ?? homedir3();
+  return join3(home, ".weacpx", "plugins");
 }
-function getChannelCliProvider(type) {
-  bootstrapBuiltinChannelCliProviders();
-  return cliProviders.get(type) ?? null;
+async function ensurePluginHome(pluginHome) {
+  await mkdir6(pluginHome, { recursive: true, mode: 448 });
+  await writeFile5(join3(pluginHome, "package.json"), JSON.stringify({ private: true, type: "module" }, null, 2) + `
+`, { flag: "wx" }).catch((error2) => {
+    if (error2.code !== "EEXIST")
+      throw error2;
+  });
 }
-var cliProviders, builtinProvidersRegistered = false;
-var init_registry = __esm(() => {
-  init_weixin_provider();
-  cliProviders = new Map;
-});
+var init_plugin_home = () => {};
 
 // src/weixin/storage/ensure-dir.ts
 import fs2 from "node:fs";
@@ -11984,7 +11985,7 @@ var init_types2 = __esm(() => {
 });
 
 // src/channels/media-store.ts
-import { access as access2, mkdir as mkdir6, readdir, rm as rm4, stat, writeFile as writeFile5 } from "node:fs/promises";
+import { access as access2, mkdir as mkdir7, readdir, rm as rm4, stat, writeFile as writeFile6 } from "node:fs/promises";
 import path6 from "node:path";
 
 class RuntimeMediaStore {
@@ -12002,13 +12003,13 @@ class RuntimeMediaStore {
     const safeMessageId = safePathSegment(input.messageId || "message");
     const baseFileName = sanitizeMediaFileName(input.fileName ?? "attachment", input.mimeType);
     const dir = path6.join(this.rootDir, input.channelId, safeChatKey, safeMessageId);
-    await mkdir6(dir, { recursive: true });
+    await mkdir7(dir, { recursive: true });
     const resolvedRoot = path6.resolve(this.rootDir);
     const resolvedFile = path6.resolve(path6.join(dir, await uniqueFileName(dir, baseFileName)));
     if (!isPathInside(resolvedFile, resolvedRoot)) {
       throw new Error("media path escapes runtime media root");
     }
-    await writeFile5(resolvedFile, input.buffer);
+    await writeFile6(resolvedFile, input.buffer);
     return {
       kind: input.kind,
       filePath: resolvedFile,
@@ -14167,16 +14168,16 @@ var init_deliver_coordinator_message = __esm(() => {
 });
 
 // src/weixin/monitor/consumer-lock.ts
-import { mkdir as mkdir7, open as open2, readFile as readFile6, rm as rm5 } from "node:fs/promises";
-import { dirname as dirname6, join as join3 } from "node:path";
-import { homedir as homedir3 } from "node:os";
+import { mkdir as mkdir8, open as open2, readFile as readFile6, rm as rm5 } from "node:fs/promises";
+import { dirname as dirname6, join as join4 } from "node:path";
+import { homedir as homedir4 } from "node:os";
 function createWeixinConsumerLock(options = {}) {
-  const lockFilePath = options.lockFilePath ?? join3(homedir3(), ".weacpx", "runtime", "weixin-consumer.lock.json");
+  const lockFilePath = options.lockFilePath ?? join4(homedir4(), ".weacpx", "runtime", "weixin-consumer.lock.json");
   const isProcessRunning = options.isProcessRunning ?? defaultIsProcessRunning4;
   const onDiagnostic = options.onDiagnostic;
   return {
     async acquire(meta2) {
-      await mkdir7(dirname6(lockFilePath), { recursive: true });
+      await mkdir8(dirname6(lockFilePath), { recursive: true });
       while (true) {
         try {
           const handle = await open2(lockFilePath, "wx");
@@ -14569,27 +14570,74 @@ var init_create_channel = __esm(() => {
   channelFactories = new Map;
 });
 
-// src/plugins/plugin-home.ts
-import { mkdir as mkdir8, writeFile as writeFile7 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { join as join4 } from "node:path";
-function resolvePluginHome(input = {}) {
-  if (input.pluginHome?.trim())
-    return input.pluginHome;
-  if (process.env.WEACPX_PLUGIN_HOME?.trim())
-    return process.env.WEACPX_PLUGIN_HOME;
-  const home = input.home ?? process.env.HOME ?? homedir4();
-  return join4(home, ".weacpx", "plugins");
+// src/channels/cli/weixin-provider.ts
+var weixinCliProvider;
+var init_weixin_provider = __esm(() => {
+  weixinCliProvider = {
+    type: "weixin",
+    displayName: "Weixin",
+    supportsLogin: true,
+    parseAddArgs(args) {
+      if (args.length > 0)
+        return { ok: false, message: `unknown weixin options: ${args.join(" ")}` };
+      return { ok: true, input: {} };
+    },
+    buildDefaultConfig(_input) {
+      return { id: "weixin", type: "weixin", enabled: true };
+    },
+    validateConfig(config2) {
+      const issues = [];
+      if (config2.id !== "weixin")
+        issues.push({ kind: "invalid-config", message: "weixin channel id must be weixin" });
+      if (config2.type !== "weixin")
+        issues.push({ kind: "invalid-config", message: "weixin channel type must be weixin" });
+      return issues;
+    },
+    renderSummary(config2) {
+      return [`type: ${config2.type}`, `enabled: ${config2.enabled}`];
+    },
+    async promptForMissingFields(input, _io) {
+      return input;
+    }
+  };
+});
+
+// src/channels/cli/registry.ts
+function registerChannelCliProvider(provider) {
+  const type = provider.type.trim();
+  if (!type)
+    throw new Error("channel CLI provider type must be non-empty");
+  if (type.includes(":"))
+    throw new Error("channel CLI provider type must not contain ':'");
+  if (cliProviders.has(type)) {
+    throw new Error(`channel CLI provider is already registered: ${type}`);
+  }
+  cliProviders.set(type, provider);
 }
-async function ensurePluginHome(pluginHome) {
-  await mkdir8(pluginHome, { recursive: true, mode: 448 });
-  await writeFile7(join4(pluginHome, "package.json"), JSON.stringify({ private: true, type: "module" }, null, 2) + `
-`, { flag: "wx" }).catch((error2) => {
-    if (error2.code !== "EEXIST")
-      throw error2;
-  });
+function hasChannelCliProvider(type) {
+  bootstrapBuiltinChannelCliProviders();
+  return cliProviders.has(type);
 }
-var init_plugin_home = () => {};
+function bootstrapBuiltinChannelCliProviders() {
+  if (builtinProvidersRegistered)
+    return;
+  builtinProvidersRegistered = true;
+  if (!cliProviders.has(weixinCliProvider.type))
+    registerChannelCliProvider(weixinCliProvider);
+}
+function listChannelCliProviders() {
+  bootstrapBuiltinChannelCliProviders();
+  return Array.from(cliProviders.values());
+}
+function getChannelCliProvider(type) {
+  bootstrapBuiltinChannelCliProviders();
+  return cliProviders.get(type) ?? null;
+}
+var cliProviders, builtinProvidersRegistered = false;
+var init_registry = __esm(() => {
+  init_weixin_provider();
+  cliProviders = new Map;
+});
 
 // src/channels/plugin.ts
 function registerChannelPlugin(plugin) {
@@ -14852,7 +14900,7 @@ var init_bootstrap = __esm(() => {
 
 // src/logging/app-logger.ts
 import { appendFile, mkdir as mkdir9, readdir as readdir2, rename, rm as rm6, stat as stat2 } from "node:fs/promises";
-import { basename, dirname as dirname7, join as join8 } from "node:path";
+import { basename, dirname as dirname8, join as join9 } from "node:path";
 function createNoopAppLogger() {
   return {
     debug: async () => {},
@@ -14892,7 +14940,7 @@ function createAppLogger(options) {
       return;
     }
     const line = formatLogLine(now(), level, event, message, context);
-    await mkdir9(dirname7(options.filePath), { recursive: true });
+    await mkdir9(dirname8(options.filePath), { recursive: true });
     await rotateIfNeeded(options.filePath, Buffer.byteLength(line), options.maxSizeBytes, options.maxFiles);
     await appendFile(options.filePath, line, "utf8");
   }
@@ -14930,7 +14978,7 @@ async function rotateIfNeeded(filePath, incomingSize, maxSizeBytes, maxFiles) {
   await rename(filePath, `${filePath}.1`);
 }
 async function cleanupExpiredRotatedLogs(filePath, retentionDays, now) {
-  const parentDir = dirname7(filePath);
+  const parentDir = dirname8(filePath);
   const prefix = `${basename(filePath)}.`;
   const cutoff = now().getTime() - retentionDays * 24 * 60 * 60 * 1000;
   let files = [];
@@ -14946,7 +14994,7 @@ async function cleanupExpiredRotatedLogs(filePath, retentionDays, now) {
     if (!file.startsWith(prefix) || !/^\d+$/.test(file.slice(prefix.length))) {
       continue;
     }
-    const candidate = join8(parentDir, file);
+    const candidate = join9(parentDir, file);
     const details = await stat2(candidate);
     if (details.mtime.getTime() < cutoff) {
       await rm6(candidate, { force: true });
@@ -14981,7 +15029,7 @@ var init_app_logger = __esm(() => {
 });
 
 // src/transport/acpx-session-index.ts
-import { readFile as readFile9 } from "node:fs/promises";
+import { readFile as readFile10 } from "node:fs/promises";
 import { homedir as homedir5 } from "node:os";
 import { resolve as resolve2 } from "node:path";
 async function resolveSessionAgentCommandFromIndex(session) {
@@ -14990,7 +15038,7 @@ async function resolveSessionAgentCommandFromIndex(session) {
     return;
   }
   try {
-    const raw = await readFile9(resolve2(home, ".acpx", "sessions", "index.json"), "utf8");
+    const raw = await readFile10(resolve2(home, ".acpx", "sessions", "index.json"), "utf8");
     const parsed = JSON.parse(raw);
     const targetCwd = resolve2(session.cwd);
     const match = parsed.entries?.find((entry) => entry.name === session.transportSession && entry.cwd === targetCwd && typeof entry.agentCommand === "string" && entry.agentCommand.trim().length > 0);
@@ -17304,37 +17352,6 @@ function isPartialPromptOutputError(message) {
   return message.includes("未收到最终回复");
 }
 
-// src/config/agent-templates.ts
-function getAgentTemplate(name) {
-  const template = TEMPLATES[name];
-  if (!template) {
-    return null;
-  }
-  return {
-    ...template
-  };
-}
-function listAgentTemplates() {
-  return Object.keys(TEMPLATES);
-}
-var TEMPLATES;
-var init_agent_templates = __esm(() => {
-  TEMPLATES = {
-    codex: {
-      driver: "codex"
-    },
-    claude: {
-      driver: "claude"
-    },
-    opencode: {
-      driver: "opencode"
-    },
-    gemini: {
-      driver: "gemini"
-    }
-  };
-});
-
 // src/commands/handlers/agent-handler.ts
 function handleAgents(context) {
   return { text: context.config ? renderAgents(context.config) : "No config loaded." };
@@ -17790,11 +17807,11 @@ var init_session_recovery_handler = __esm(() => {
 });
 
 // src/recovery/auto-install-optional-dep.ts
-import { spawn as spawn4 } from "node:child_process";
+import { spawn as spawn5 } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import { mkdir as mkdir10 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 async function autoInstallOptionalDep(pkg, parentPackages, options = {}) {
   const runCli = options.runCli ?? defaultRunCli;
   const openLog = options.openLog ?? defaultLogSink;
@@ -17873,7 +17890,7 @@ function tail(text, lines) {
 }
 var PRECISE_TIMEOUT_MS = 90000, GLOBAL_TIMEOUT_MS = 90000, TAIL_LINES = 10, PRECISE_COMMANDS, defaultRunCli = async (cmd, args, options) => {
   return await new Promise((resolve3) => {
-    const child = spawn4(cmd, args, {
+    const child = spawn5(cmd, args, {
       cwd: options.cwd,
       stdio: ["ignore", "pipe", "pipe"],
       shell: process.platform === "win32"
@@ -17909,10 +17926,10 @@ ${err.message}`, reason: "spawn" });
     });
   });
 }, defaultLogSink = async () => {
-  const dir = join9(homedir6(), ".weacpx", "logs");
+  const dir = join10(homedir6(), ".weacpx", "logs");
   await mkdir10(dir, { recursive: true });
   const timestamp = new Date().toISOString().replace(/[:.]/g, "").replace(/-/g, "");
-  const path13 = join9(dir, `auto-install-${timestamp}.log`);
+  const path13 = join10(dir, `auto-install-${timestamp}.log`);
   const stream = createWriteStream(path13, { flags: "a" });
   return {
     path: path13,
@@ -17934,11 +17951,11 @@ var init_auto_install_optional_dep = __esm(() => {
 });
 
 // src/recovery/discover-parent-package-paths.ts
-import { spawn as spawn5 } from "node:child_process";
+import { spawn as spawn6 } from "node:child_process";
 import { createRequire as createRequire3 } from "node:module";
 import { access as access3 } from "node:fs/promises";
 import { homedir as homedir7 } from "node:os";
-import { dirname as dirname8, join as join10 } from "node:path";
+import { dirname as dirname9, join as join11 } from "node:path";
 function deriveParentPackageName(platformPackage) {
   return platformPackage.replace(/-(?:linux|darwin|win32|windows|freebsd|openbsd|sunos|aix)(?:-(?:x64|arm64|ia32|arm|ppc64|s390x))?(?:-(?:baseline|musl|gnu|gnueabihf|musleabihf|msvc))?$/, "");
 }
@@ -17951,7 +17968,7 @@ async function discoverParentPackagePaths(platformPackage, seedPath, deps = {})
   const queryRoot = deps.queryPackageManagerRoot ?? defaultQueryPackageManagerRoot;
   const parentName = deriveParentPackageName(platformPackage);
   const rawCandidates = [];
-  const bunGlobalRoot = env.BUN_INSTALL ? join10(env.BUN_INSTALL, "install", "global", "node_modules") : join10(home, ".bun", "install", "global", "node_modules");
+  const bunGlobalRoot = env.BUN_INSTALL ? join11(env.BUN_INSTALL, "install", "global", "node_modules") : join11(home, ".bun", "install", "global", "node_modules");
   const [npmRoot, pnpmRoot, yarnRoot] = await Promise.all([
     queryRoot("npm"),
     queryRoot("pnpm"),
@@ -17974,20 +17991,20 @@ async function discoverParentPackagePaths(platformPackage, seedPath, deps = {})
     if (resolved)
       rawCandidates.push({ path: resolved, manager: classify(resolved) });
   }
-  rawCandidates.push({ path: join10(bunGlobalRoot, parentName), manager: "bun" });
+  rawCandidates.push({ path: join11(bunGlobalRoot, parentName), manager: "bun" });
   if (npmRoot)
-    rawCandidates.push({ path: join10(npmRoot, parentName), manager: "npm" });
+    rawCandidates.push({ path: join11(npmRoot, parentName), manager: "npm" });
   if (pnpmRoot)
-    rawCandidates.push({ path: join10(pnpmRoot, parentName), manager: "pnpm" });
+    rawCandidates.push({ path: join11(pnpmRoot, parentName), manager: "pnpm" });
   if (yarnRoot)
-    rawCandidates.push({ path: join10(yarnRoot, parentName), manager: "yarn" });
+    rawCandidates.push({ path: join11(yarnRoot, parentName), manager: "yarn" });
   const seen = new Set;
   const verified = [];
   for (const candidate of rawCandidates) {
     if (seen.has(candidate.path))
       continue;
     seen.add(candidate.path);
-    if (await fsExists(join10(candidate.path, "package.json"))) {
+    if (await fsExists(join11(candidate.path, "package.json"))) {
       verified.push(candidate);
     }
   }
@@ -18011,7 +18028,7 @@ function defaultResolveFromCwd(name, cwd) {
     const pkgJson = require2.resolve(`${name}/package.json`, {
       paths: [cwd, ...require2.resolve.paths(name) ?? []]
     });
-    return dirname8(pkgJson);
+    return dirname9(pkgJson);
   } catch {
     return null;
   }
@@ -18028,7 +18045,7 @@ async function defaultQueryPackageManagerRoot(tool) {
     };
     let child;
     try {
-      child = spawn5(spec.cmd, spec.args, {
+      child = spawn6(spec.cmd, spec.args, {
         stdio: ["ignore", "pipe", "pipe"],
         shell: process.platform === "win32"
       });
@@ -18058,7 +18075,7 @@ async function defaultQueryPackageManagerRoot(tool) {
       const trimmed = stdout2.trim().split(/\r?\n/).pop()?.trim() ?? "";
       if (!trimmed)
         return done(null);
-      done(spec.postfix ? join10(trimmed, spec.postfix) : trimmed);
+      done(spec.postfix ? join11(trimmed, spec.postfix) : trimmed);
     });
   });
 }
@@ -22624,6 +22641,7 @@ async function runConsole(paths, deps) {
   let heartbeatTimer = null;
   let gcResetTimer = null;
   let consumerLockAcquired = false;
+  let daemonRuntimeStarted = false;
   const shutdownController = new AbortController;
   const signalHandler = () => {
     shutdownController.abort();
@@ -22632,6 +22650,9 @@ async function runConsole(paths, deps) {
   addProcessListener("SIGTERM", signalHandler);
   try {
     runtime = await deps.buildApp(paths);
+    if (deps.afterBuild) {
+      await deps.afterBuild(runtime);
+    }
     try {
       await runtime.orchestration.service.purgeExpiredResetCoordinators({
         cutoffDays: 7,
@@ -22639,20 +22660,6 @@ async function runConsole(paths, deps) {
       });
     } catch {}
     consumerLock = deps.consumerLock ?? deps.consumerLockFactory?.(runtime);
-    if (deps.daemonRuntime) {
-      await deps.daemonRuntime.start({
-        configPath: paths.configPath,
-        statePath: paths.statePath
-      });
-      await runtime.orchestration.server.start();
-      heartbeatTimer = setIntervalFn(() => {
-        deps.daemonRuntime?.heartbeat().catch(() => {});
-      }, deps.heartbeatIntervalMs ?? 30000);
-      const runtimeForGc = runtime;
-      gcResetTimer = setIntervalFn(() => {
-        runtimeForGc.orchestration.service.purgeExpiredResetCoordinators({ cutoffDays: 7, trigger: "interval" }).catch(() => {});
-      }, 86400000);
-    }
     if (consumerLock) {
       const lockMeta = {
         pid: processPid,
@@ -22700,6 +22707,24 @@ async function runConsole(paths, deps) {
         throw error2;
       }
     }
+    if (deps.beforeReady) {
+      await deps.beforeReady(runtime);
+    }
+    if (deps.daemonRuntime) {
+      await deps.daemonRuntime.start({
+        configPath: paths.configPath,
+        statePath: paths.statePath
+      });
+      daemonRuntimeStarted = true;
+      await runtime.orchestration.server.start();
+      heartbeatTimer = setIntervalFn(() => {
+        deps.daemonRuntime?.heartbeat().catch(() => {});
+      }, deps.heartbeatIntervalMs ?? 30000);
+      const runtimeForGc = runtime;
+      gcResetTimer = setIntervalFn(() => {
+        runtimeForGc.orchestration.service.purgeExpiredResetCoordinators({ cutoffDays: 7, trigger: "interval" }).catch(() => {});
+      }, 86400000);
+    }
     await deps.channels.startAll({
       agent: runtime.agent,
       abortSignal: shutdownController.signal,
@@ -22718,7 +22743,8 @@ async function runConsole(paths, deps) {
       consumerLock,
       consumerLockAcquired,
       processPid,
-      channels: deps.channels
+      channels: deps.channels,
+      daemonRuntimeStarted
     });
   }
 }
@@ -22753,7 +22779,7 @@ async function runCleanupSequence(input) {
       cleanupError ??= error2;
     }
   }
-  if (input.daemonRuntime) {
+  if (input.daemonRuntime && input.daemonRuntimeStarted) {
     try {
       await input.daemonRuntime.stop();
     } catch (error2) {
@@ -22803,8 +22829,8 @@ function encodeBridgeSessionNoteEvent(event) {
 }
 
 // src/transport/acpx-bridge/acpx-bridge-client.ts
-import { spawn as spawn6 } from "node:child_process";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { spawn as spawn7 } from "node:child_process";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { createInterface } from "node:readline";
 
 class AcpxBridgeClient {
@@ -22924,12 +22950,12 @@ function buildBridgeSpawnSpec(options) {
   };
 }
 async function spawnAcpxBridgeClient(options = {}) {
-  const bridgeEntryPath = options.bridgeEntryPath ?? fileURLToPath2(new URL("../../bridge/bridge-main.ts", import.meta.url));
+  const bridgeEntryPath = options.bridgeEntryPath ?? fileURLToPath3(new URL("../../bridge/bridge-main.ts", import.meta.url));
   const spawnSpec = buildBridgeSpawnSpec({
     execPath: process.execPath,
     bridgeEntryPath
   });
-  const child = spawn6(spawnSpec.command, spawnSpec.args, {
+  const child = spawn7(spawnSpec.command, spawnSpec.args, {
     cwd: options.cwd ?? process.cwd(),
     env: {
       ...process.env,
@@ -23743,12 +23769,12 @@ var init_streaming_prompt = __esm(() => {
 
 // src/transport/acpx-cli/node-pty-helper.ts
 import { chmod as chmodFs } from "node:fs/promises";
-import { dirname as dirname9, join as join11 } from "node:path";
+import { dirname as dirname10, join as join12 } from "node:path";
 function resolveNodePtyHelperPath(packageJsonPath, platform, arch) {
   if (platform === "win32") {
     return null;
   }
-  return join11(dirname9(packageJsonPath), "prebuilds", `${platform}-${arch}`, "spawn-helper");
+  return join12(dirname10(packageJsonPath), "prebuilds", `${platform}-${arch}`, "spawn-helper");
 }
 async function ensureNodePtyHelperExecutable(helperPath, chmod2 = chmodFs) {
   if (!helperPath) {
@@ -23767,10 +23793,10 @@ var init_node_pty_helper = () => {};
 
 // src/transport/acpx-queue-owner-launcher.ts
 import { createHash as createHash3 } from "node:crypto";
-import { spawn as spawn7 } from "node:child_process";
-import { readFile as readFile10, unlink } from "node:fs/promises";
+import { spawn as spawn8 } from "node:child_process";
+import { readFile as readFile11, unlink } from "node:fs/promises";
 import { homedir as homedir8 } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function buildWeacpxMcpServerSpec(input) {
   const { command, args } = splitCommandLine(input.weacpxCommand);
   return {
@@ -23900,7 +23926,7 @@ function stringEnv(env) {
 }
 async function defaultQueueOwnerSpawner(command, args, options) {
   await new Promise((resolve3, reject) => {
-    const child = spawn7(command, args, {
+    const child = spawn8(command, args, {
       detached: true,
       stdio: "ignore",
       env: options.env,
@@ -23922,7 +23948,7 @@ async function terminateAcpxQueueOwner(sessionId) {
   const lockPath = queueLockFilePath(sessionId);
   let owner;
   try {
-    owner = JSON.parse(await readFile10(lockPath, "utf8"));
+    owner = JSON.parse(await readFile11(lockPath, "utf8"));
   } catch {
     return;
   }
@@ -23932,7 +23958,7 @@ async function terminateAcpxQueueOwner(sessionId) {
   await unlink(lockPath).catch(() => {});
 }
 function queueLockFilePath(sessionId) {
-  return join12(homedir8(), ".acpx", "queues", `${shortHash(sessionId, 24)}.lock`);
+  return join13(homedir8(), ".acpx", "queues", `${shortHash(sessionId, 24)}.lock`);
 }
 function shortHash(value, length) {
   return createHash3("sha256").update(value).digest("hex").slice(0, length);
@@ -23971,12 +23997,12 @@ function permissionModeToFlag(permissionMode) {
 
 // src/transport/acpx-cli/acpx-cli-transport.ts
 import { createRequire as createRequire5 } from "node:module";
-import { spawn as spawn8 } from "node:child_process";
+import { spawn as spawn9 } from "node:child_process";
 import { spawn as spawnPty } from "node-pty";
 async function defaultRunner(command, args, options) {
   return await new Promise((resolve3, reject) => {
     const spawnSpec = resolveSpawnCommand(command, args);
-    const child = spawn8(spawnSpec.command, spawnSpec.args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn9(spawnSpec.command, spawnSpec.args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout2 = "";
     let stderr = "";
     const onAbort = () => {
@@ -24223,7 +24249,7 @@ ${baseText}` : "" };
   }
   async runStreamingPrompt(command, args, reply, formatToolCalls = false, toolEventMode = "text", replyContext, onSegment, onToolEvent) {
     const hooks = this.streamingHooks;
-    const doSpawn = hooks.spawnPrompt ?? ((cmd, spawnArgs) => spawn8(cmd, spawnArgs, { stdio: ["ignore", "pipe", "pipe"] }));
+    const doSpawn = hooks.spawnPrompt ?? ((cmd, spawnArgs) => spawn9(cmd, spawnArgs, { stdio: ["ignore", "pipe", "pipe"] }));
     const setIntervalFn = hooks.setIntervalFn ?? ((fn, delay) => setInterval(fn, delay));
     const clearIntervalFn = hooks.clearIntervalFn ?? ((timer) => clearInterval(timer));
     const maxSegmentWaitMs = hooks.maxSegmentWaitMs ?? 30000;
@@ -24583,8 +24609,8 @@ __export(exports_main, {
 });
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { homedir as homedir9 } from "node:os";
-import { dirname as dirname10, join as join13 } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { dirname as dirname11, join as join14 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 function startProgressHeartbeat(orchestration, config2, logger2, channel) {
   const thresholdSeconds = config2.orchestration.progressHeartbeatSeconds;
   if (thresholdSeconds <= 0) {
@@ -24989,6 +25015,7 @@ async function buildApp(paths, deps = {}) {
     configStore,
     logger: logger2,
     quota,
+    transport,
     orchestration: {
       service: orchestration,
       server: orchestrationServer,
@@ -25038,8 +25065,8 @@ async function main() {
   }
 }
 async function prepareChannelMedia(configPath, config2) {
-  const runtimeDir = join13(dirname10(configPath), "runtime");
-  const mediaRootDir = join13(runtimeDir, "media");
+  const runtimeDir = join14(dirname11(configPath), "runtime");
+  const mediaRootDir = join14(runtimeDir, "media");
   const mediaStore = new RuntimeMediaStore({ rootDir: mediaRootDir });
   await mediaStore.cleanupExpired().catch((error2) => {
     console.error("[weacpx] media cleanup failed:", error2 instanceof Error ? error2.message : String(error2));
@@ -25053,7 +25080,7 @@ function resolveRuntimePaths() {
     throw new Error("Unable to resolve the current user home directory");
   }
   const configPath = process.env.WEACPX_CONFIG ?? `${home}/.weacpx/config.json`;
-  const runtimeDir = join13(dirname10(configPath), "runtime");
+  const runtimeDir = join14(dirname11(configPath), "runtime");
   return {
     configPath,
     statePath: process.env.WEACPX_STATE ?? `${home}/.weacpx/state.json`,
@@ -25062,14 +25089,14 @@ function resolveRuntimePaths() {
 }
 function resolveBridgeEntryPath() {
   if (import.meta.url.includes("/dist/")) {
-    return fileURLToPath3(new URL("./bridge/bridge-main.js", import.meta.url));
+    return fileURLToPath4(new URL("./bridge/bridge-main.js", import.meta.url));
   }
-  return fileURLToPath3(new URL("./bridge/bridge-main.ts", import.meta.url));
+  return fileURLToPath4(new URL("./bridge/bridge-main.ts", import.meta.url));
 }
 function resolveAppLogPath(configPath) {
-  const rootDir = dirname10(configPath);
-  const runtimeDir = join13(rootDir, "runtime");
-  return join13(runtimeDir, "app.log");
+  const rootDir = dirname11(configPath);
+  const runtimeDir = join14(rootDir, "runtime");
+  return join14(runtimeDir, "app.log");
 }
 function resolveOrchestrationSocketPathFromConfigPath(configPath) {
   const runtimeDir = resolveRuntimeDirFromConfigPath(configPath);
@@ -25106,7 +25133,7 @@ var init_main = __esm(async () => {
 });
 
 // src/doctor/checks/acpx-check.ts
-import { spawn as spawn9 } from "node:child_process";
+import { spawn as spawn10 } from "node:child_process";
 async function checkAcpx(options = {}) {
   const runtimePaths = (options.resolveRuntimePaths ?? resolveRuntimePaths)();
   try {
@@ -25153,7 +25180,7 @@ function buildDetails(metadata, version2, verbose) {
 async function defaultRunVersion(command) {
   const spawnSpec = resolveSpawnCommand(command, ["--version"]);
   return await new Promise((resolve3, reject) => {
-    const child = spawn9(spawnSpec.command, spawnSpec.args, {
+    const child = spawn10(spawnSpec.command, spawnSpec.args, {
       stdio: ["ignore", "pipe", "pipe"]
     });
     let stdout2 = "";
@@ -25291,7 +25318,7 @@ var init_config_check = __esm(async () => {
 });
 
 // src/doctor/checks/daemon-check.ts
-import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { homedir as homedir10 } from "node:os";
 async function checkDaemon(options = {}) {
   const home = options.home ?? process.env.HOME ?? homedir10();
@@ -25381,7 +25408,7 @@ function defaultIsProcessRunning5(pid) {
   }
 }
 function resolveCliEntryPath() {
-  return process.argv[1] ?? fileURLToPath4(import.meta.url);
+  return process.argv[1] ?? fileURLToPath5(import.meta.url);
 }
 function formatError5(error2) {
   return error2 instanceof Error ? error2.message : String(error2);
@@ -25443,7 +25470,7 @@ async function checkOrchestrationHealth(options) {
 // src/doctor/checks/runtime-check.ts
 import { constants } from "node:fs";
 import { access as access4, stat as stat3 } from "node:fs/promises";
-import { dirname as dirname11 } from "node:path";
+import { dirname as dirname12 } from "node:path";
 import { homedir as homedir11 } from "node:os";
 async function checkRuntime(options = {}) {
   const home = options.home ?? process.env.HOME ?? homedir11();
@@ -25540,7 +25567,7 @@ async function checkFileCreatable(label, path14, probe, platform) {
         detail: `${label}: ${path14} (unusable: ${formatError6(error2)})`
       };
     }
-    const parentCheck = await checkCreatableAncestorDirectory(dirname11(path14), probe, platform);
+    const parentCheck = await checkCreatableAncestorDirectory(dirname12(path14), probe, platform);
     if (!parentCheck.ok) {
       return {
         ok: false,
@@ -25576,7 +25603,7 @@ async function checkCreatableAncestorDirectory(path14, probe, platform) {
         blockingPath: path14
       };
     }
-    const parent = dirname11(path14);
+    const parent = dirname12(path14);
     if (parent === path14) {
       return {
         ok: false,
@@ -25999,7 +26026,7 @@ var init_render_doctor = __esm(() => {
 
 // src/doctor/doctor.ts
 import { homedir as homedir12 } from "node:os";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 async function runDoctor(options = {}, deps = {}) {
   const home = deps.home ?? process.env.HOME ?? homedir12();
   const runtimePaths = resolveDoctorRuntimePaths(home, deps.resolveRuntimePaths);
@@ -26052,8 +26079,8 @@ function resolveDoctorRuntimePaths(home, resolver) {
     return resolveRuntimePaths();
   }
   return {
-    configPath: join14(home, ".weacpx", "config.json"),
-    statePath: join14(home, ".weacpx", "state.json")
+    configPath: join15(home, ".weacpx", "config.json"),
+    statePath: join15(home, ".weacpx", "state.json")
   };
 }
 function depsUseExplicitRuntimeOverrides() {
@@ -26158,8 +26185,8 @@ init_create_daemon_controller();
 init_daemon_files();
 import { randomUUID as randomUUID4 } from "node:crypto";
 import { homedir as homedir13 } from "node:os";
-import { sep } from "node:path";
-import { fileURLToPath as fileURLToPath5 } from "node:url";
+import { dirname as dirname13, join as join16, sep } from "node:path";
+import { fileURLToPath as fileURLToPath6 } from "node:url";
 
 // src/daemon/daemon-runtime.ts
 init_daemon_status();
@@ -39577,6 +39604,372 @@ function parseSourceHandle(args, env = process.env) {
 // src/cli.ts
 init_workspace_path();
 init_state_store();
+
+// src/onboarding.ts
+init_workspace_path();
+init_agent_templates();
+function isFirstUse(config2, state) {
+  return Object.keys(state.sessions ?? {}).length === 0 && Object.keys(config2.workspaces ?? {}).length === 0 && (config2.plugins ?? []).length === 0;
+}
+async function maybeRunFirstUseOnboarding(input) {
+  if (!isFirstUse(input.config, input.state))
+    return { created: false };
+  if (!input.deps.isInteractive())
+    return { created: false };
+  const cwd = normalizeWorkspacePath(input.deps.cwd());
+  const workspaceName = allocateName(sanitizeName(basenameForWorkspacePath(cwd), "workspace"), input.config.workspaces);
+  const yes = (await input.deps.promptText(`检测到首次使用 weacpx。是否将当前目录创建为工作区「${workspaceName}」？[Y/n] `)).trim().toLowerCase();
+  if (yes === "n" || yes === "no")
+    return { created: false };
+  const templateNames = listAgentTemplates();
+  input.deps.print("请选择要添加并创建初始会话的 Agent：");
+  for (let index = 0;index < templateNames.length; index += 1) {
+    input.deps.print(`${index + 1}. ${templateNames[index]}`);
+  }
+  const answer = (await input.deps.promptText("输入数字或名称（默认 1）：")).trim();
+  const agentName = resolveTemplateChoice(answer, templateNames);
+  if (!agentName) {
+    input.deps.print("未选择有效 Agent，已跳过首次初始化。");
+    return { created: false };
+  }
+  const template = getAgentTemplate(agentName);
+  if (!template)
+    return { created: false };
+  const workspaceExisted = Boolean(input.config.workspaces[workspaceName]);
+  const agentExisted = Boolean(input.config.agents[agentName]);
+  input.config.workspaces[workspaceName] = { cwd };
+  input.config.agents[agentName] = template;
+  await input.saveConfig(input.config);
+  const alias = `${workspaceName}:${agentName}`;
+  input.deps.print(`已创建工作区「${workspaceName}」，正在创建初始会话「${alias}」...`);
+  return {
+    created: true,
+    workspace: workspaceName,
+    agent: agentName,
+    alias,
+    rollback: { workspaceExisted, agentExisted }
+  };
+}
+function resolveTemplateChoice(answer, names) {
+  if (!answer)
+    return names[0] ?? null;
+  const index = Number.parseInt(answer, 10);
+  if (Number.isFinite(index) && index >= 1 && index <= names.length)
+    return names[index - 1];
+  return names.includes(answer) ? answer : null;
+}
+function allocateName(base, existing) {
+  if (!existing[base])
+    return base;
+  let suffix = 2;
+  while (existing[`${base}-${suffix}`])
+    suffix += 1;
+  return `${base}-${suffix}`;
+}
+function sanitizeName(input, fallback) {
+  const sanitized = input.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || fallback;
+}
+
+// src/cli-update.ts
+init_plugin_home();
+import { spawn as spawn4 } from "node:child_process";
+import { readFile as readFile7 } from "node:fs/promises";
+import { dirname as dirname7, join as join6 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/plugins/package-manager.ts
+import { spawn as spawn3 } from "node:child_process";
+async function defaultRunCommand(command, args, options) {
+  await new Promise((resolve, reject) => {
+    const child = spawn3(command, args, { cwd: options.cwd, stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0)
+        resolve();
+      else
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+async function silentRun(command, args, options) {
+  await new Promise((resolve, reject) => {
+    const child = spawn3(command, args, { cwd: options.cwd, stdio: "ignore" });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0)
+        resolve();
+      else
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+async function detectPackageManager(runCommand) {
+  const override = process.env.WEACPX_PACKAGE_MANAGER?.trim().toLowerCase();
+  if (override === "bun" || override === "npm")
+    return override;
+  const probe = runCommand ?? silentRun;
+  try {
+    await probe("bun", ["--version"], { cwd: process.cwd() });
+    return "bun";
+  } catch {
+    return "npm";
+  }
+}
+async function installPluginPackage(input) {
+  const runCommand = input.runCommand ?? defaultRunCommand;
+  const packageManager = input.packageManager ?? await detectPackageManager();
+  const spec = input.version ? `${input.packageName}@${input.version}` : input.packageName;
+  if (packageManager === "bun") {
+    await runCommand("bun", ["add", spec], { cwd: input.pluginHome });
+    return;
+  }
+  await runCommand("npm", ["install", spec], { cwd: input.pluginHome });
+}
+async function updatePluginPackage(input) {
+  await installPluginPackage(input);
+}
+async function removePluginPackage(input) {
+  const runCommand = input.runCommand ?? defaultRunCommand;
+  const packageManager = input.packageManager ?? await detectPackageManager();
+  if (packageManager === "bun") {
+    await runCommand("bun", ["remove", input.packageName], { cwd: input.pluginHome });
+    return;
+  }
+  await runCommand("npm", ["uninstall", input.packageName], { cwd: input.pluginHome });
+}
+
+// src/cli-update.ts
+init_plugin_loader();
+init_validate_plugin();
+async function handleUpdateCli(args, deps) {
+  let all = false;
+  const explicitTargets = [];
+  for (const arg of args) {
+    if (arg === "--all")
+      all = true;
+    else
+      explicitTargets.push(arg);
+  }
+  if (all && explicitTargets.length > 0)
+    return null;
+  if (explicitTargets.length > 1)
+    return null;
+  const config2 = await deps.loadConfig();
+  const packageName = deps.packageName ?? await readPackageName();
+  const latestOf = deps.getLatestVersion ?? getLatestNpmVersion;
+  const targets = [
+    {
+      kind: "self",
+      name: packageName,
+      currentVersion: deps.readCurrentVersion(),
+      latestVersion: await latestOf(packageName)
+    }
+  ];
+  for (const plugin of config2.plugins ?? []) {
+    targets.push({
+      kind: "plugin",
+      name: plugin.name,
+      currentVersion: plugin.version,
+      pinned: Boolean(plugin.version),
+      latestVersion: await latestOf(plugin.name)
+    });
+  }
+  deps.print("可更新项：");
+  for (let index = 0;index < targets.length; index += 1) {
+    const target = targets[index];
+    deps.print(`${index + 1}. ${formatTarget(target)}`);
+  }
+  const unavailable = targets.filter((target) => !target.latestVersion || target.kind === "plugin" && !target.pinned);
+  if (all && unavailable.length > 0) {
+    deps.print(`以下项目无法检查最新版本，已取消更新：${unavailable.map((target) => target.name).join(", ")}`);
+    return 1;
+  }
+  const candidates = targets.filter((target) => target.latestVersion && (target.kind !== "plugin" || target.pinned) && target.currentVersion !== target.latestVersion);
+  const selected = await selectTargets(targets, candidates, { all, explicitTarget: explicitTargets[0], deps });
+  if (!selected.ok) {
+    deps.print(selected.message);
+    return selected.exitCode;
+  }
+  if (selected.targets.length === 0) {
+    deps.print("没有需要更新的项目。");
+    return 0;
+  }
+  const selfUpdater = deps.updateSelf ?? defaultUpdateSelf;
+  const pluginHome = deps.pluginHome ?? resolvePluginHome();
+  const pluginUpdater = deps.updatePlugin ?? (async (input) => {
+    await ensurePluginHome(pluginHome);
+    await updatePluginPackage({ ...input, pluginHome });
+  });
+  const validatePlugin = deps.validatePlugin ?? validatePluginDefault;
+  const updatedPlugins = [...config2.plugins ?? []];
+  for (const target of selected.targets) {
+    try {
+      if (target.kind === "self") {
+        if (!all && !explicitTargets[0]) {
+          if (!deps.isInteractive()) {
+            deps.print("更新 weacpx 本体需要确认；非交互模式请使用 `weacpx update --all` 或 `weacpx update weacpx`。");
+            return 1;
+          }
+          const answer = (await deps.promptText("确认更新 weacpx 本体？[y/N] ")).trim().toLowerCase();
+          if (answer !== "y" && answer !== "yes") {
+            deps.print("已取消更新 weacpx 本体。");
+            continue;
+          }
+        }
+        await selfUpdater(target.name);
+        deps.print(`weacpx 已更新：${target.latestVersion ?? "latest"}`);
+        continue;
+      }
+      const existing = updatedPlugins.find((plugin) => plugin.name === target.name);
+      const previousVersion = existing?.version;
+      const updateInput = target.latestVersion ? { packageName: target.name, version: target.latestVersion } : { packageName: target.name };
+      await pluginUpdater(updateInput);
+      try {
+        await validatePlugin(target.name, pluginHome);
+      } catch (validationError) {
+        if (previousVersion) {
+          try {
+            await pluginUpdater({ packageName: target.name, version: previousVersion });
+          } catch (rollbackError) {
+            deps.print(`回滚 ${target.name} 到 ${previousVersion} 失败：${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+          }
+        }
+        throw validationError;
+      }
+      if (!existing)
+        throw new Error(`配置中没有找到插件 ${target.name}`);
+      if (existing && target.latestVersion)
+        existing.version = target.latestVersion;
+      deps.print(`插件 ${target.name} 已更新：${target.latestVersion ?? "latest"}`);
+    } catch (error2) {
+      deps.print(`${target.name} 更新失败：${error2 instanceof Error ? error2.message : String(error2)}`);
+      return 1;
+    }
+  }
+  if (selected.targets.some((target) => target.kind === "plugin")) {
+    config2.plugins = updatedPlugins;
+    await deps.saveConfig(config2);
+  }
+  return 0;
+}
+function formatTarget(target) {
+  const current = target.currentVersion ?? "未锁定";
+  const latest = target.latestVersion ?? "无法检查";
+  const label = target.kind === "self" ? "weacpx" : `插件 ${target.name}`;
+  return `${label} (${current} -> ${latest})`;
+}
+async function selectTargets(targets, candidates, input) {
+  if (input.explicitTarget) {
+    const target = targets.find((entry) => entry.name === input.explicitTarget || input.explicitTarget === "weacpx" && entry.kind === "self");
+    if (!target)
+      return { ok: false, message: `没有找到更新项：${input.explicitTarget}`, exitCode: 1 };
+    if (!target.latestVersion)
+      return { ok: false, message: `${target.name} 无法检查最新版本，已跳过。`, exitCode: 1 };
+    if (target.kind === "plugin" && !target.pinned)
+      return { ok: false, message: `${target.name} 未记录当前版本；请先使用 \`weacpx plugin update ${target.name}\` 或显式选择版本。`, exitCode: 1 };
+    if (target.currentVersion === target.latestVersion)
+      return { ok: true, targets: [] };
+    return { ok: true, targets: [target] };
+  }
+  if (input.all || targets.length === 1)
+    return { ok: true, targets: candidates };
+  if (!input.deps.isInteractive()) {
+    return { ok: false, message: "检测到已安装插件；非交互模式请使用 `weacpx update --all` 或 `weacpx update <name>`。", exitCode: 1 };
+  }
+  const answer = (await input.deps.promptText("请选择要更新的项目（数字，逗号分隔，a=全部，回车取消）：")).trim().toLowerCase();
+  if (!answer)
+    return { ok: true, targets: [] };
+  if (answer === "a" || answer === "all")
+    return { ok: true, targets: candidates };
+  const selected = [];
+  for (const part of answer.split(",")) {
+    const index = Number.parseInt(part.trim(), 10);
+    if (!Number.isFinite(index) || index < 1 || index > targets.length) {
+      return { ok: false, message: `无效选择：${part.trim()}`, exitCode: 1 };
+    }
+    const target = targets[index - 1];
+    if (!target.latestVersion)
+      return { ok: false, message: `${target.name} 无法检查最新版本，已跳过。`, exitCode: 1 };
+    if (target.kind === "plugin" && !target.pinned)
+      return { ok: false, message: `${target.name} 未记录当前版本；请先使用 \`weacpx plugin update ${target.name}\` 或显式选择版本。`, exitCode: 1 };
+    if (target.currentVersion === target.latestVersion)
+      continue;
+    if (!selected.includes(target))
+      selected.push(target);
+  }
+  return { ok: true, targets: selected };
+}
+async function getLatestNpmVersion(packageName) {
+  const result = await runCapture("npm", ["view", packageName, "version", "--json"]);
+  if (result.code !== 0)
+    return null;
+  const raw = result.stdout.trim();
+  if (!raw)
+    return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "string" ? parsed : null;
+  } catch {
+    return raw.replace(/^"|"$/g, "") || null;
+  }
+}
+async function defaultUpdateSelf(packageName) {
+  const manager = process.env.WEACPX_PACKAGE_MANAGER?.trim().toLowerCase() === "bun" ? "bun" : "npm";
+  if (manager === "bun") {
+    await runInherit("bun", ["add", "-g", packageName]);
+    return;
+  }
+  await runInherit("npm", ["install", "-g", packageName]);
+}
+async function runCapture(command, args) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn4(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout2 = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout2 += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout: stdout2, stderr }));
+  });
+}
+async function runInherit(command, args) {
+  await new Promise((resolve, reject) => {
+    const child = spawn4(command, args, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0)
+        resolve();
+      else
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+async function readPackageName() {
+  try {
+    const here = dirname7(fileURLToPath2(import.meta.url));
+    for (const candidate of [join6(here, "..", "package.json"), join6(here, "..", "..", "package.json")]) {
+      try {
+        const parsed = JSON.parse(await readFile7(candidate, "utf8"));
+        if (typeof parsed.name === "string" && parsed.name.trim())
+          return parsed.name.trim();
+      } catch {}
+    }
+  } catch {}
+  return "weacpx";
+}
+async function validatePluginDefault(packageName, pluginHome) {
+  const moduleValue = await importPluginFromHome(packageName, pluginHome);
+  validateWeacpxPlugin(moduleValue, packageName);
+}
+
+// src/cli.ts
 init_version();
 
 // src/channels/cli/channel-cli.ts
@@ -40186,71 +40579,8 @@ async function setChannelAccountEnabled(type, accountId, enabled, rawArgs, deps)
 
 // src/plugins/plugin-cli.ts
 init_plugin_home();
-import { readFile as readFile8 } from "node:fs/promises";
-import { isAbsolute, join as join7, resolve } from "node:path";
-
-// src/plugins/package-manager.ts
-import { spawn as spawn3 } from "node:child_process";
-async function defaultRunCommand(command, args, options) {
-  await new Promise((resolve, reject) => {
-    const child = spawn3(command, args, { cwd: options.cwd, stdio: "inherit" });
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0)
-        resolve();
-      else
-        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
-    });
-  });
-}
-async function silentRun(command, args, options) {
-  await new Promise((resolve, reject) => {
-    const child = spawn3(command, args, { cwd: options.cwd, stdio: "ignore" });
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0)
-        resolve();
-      else
-        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
-    });
-  });
-}
-async function detectPackageManager(runCommand) {
-  const override = process.env.WEACPX_PACKAGE_MANAGER?.trim().toLowerCase();
-  if (override === "bun" || override === "npm")
-    return override;
-  const probe = runCommand ?? silentRun;
-  try {
-    await probe("bun", ["--version"], { cwd: process.cwd() });
-    return "bun";
-  } catch {
-    return "npm";
-  }
-}
-async function installPluginPackage(input) {
-  const runCommand = input.runCommand ?? defaultRunCommand;
-  const packageManager = input.packageManager ?? await detectPackageManager();
-  const spec = input.version ? `${input.packageName}@${input.version}` : input.packageName;
-  if (packageManager === "bun") {
-    await runCommand("bun", ["add", spec], { cwd: input.pluginHome });
-    return;
-  }
-  await runCommand("npm", ["install", spec], { cwd: input.pluginHome });
-}
-async function updatePluginPackage(input) {
-  await installPluginPackage(input);
-}
-async function removePluginPackage(input) {
-  const runCommand = input.runCommand ?? defaultRunCommand;
-  const packageManager = input.packageManager ?? await detectPackageManager();
-  if (packageManager === "bun") {
-    await runCommand("bun", ["remove", input.packageName], { cwd: input.pluginHome });
-    return;
-  }
-  await runCommand("npm", ["uninstall", input.packageName], { cwd: input.pluginHome });
-}
-
-// src/plugins/plugin-cli.ts
+import { readFile as readFile9 } from "node:fs/promises";
+import { isAbsolute, join as join8, resolve } from "node:path";
 init_plugin_loader();
 init_validate_plugin();
 
@@ -40259,14 +40589,14 @@ init_channel_scope();
 init_plugin_loader();
 init_validate_plugin();
 init_known_plugins();
-import { readFile as readFile7 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { readFile as readFile8 } from "node:fs/promises";
+import { join as join7 } from "node:path";
 function suggestedPluginPackageForChannel(type) {
   return findKnownPluginByChannel(type)?.packageName ?? `<npm-package-that-provides-${type}>`;
 }
 async function readDependencyEntries(pluginHome) {
   try {
-    const raw = await readFile7(join6(pluginHome, "package.json"), "utf8");
+    const raw = await readFile8(join7(pluginHome, "package.json"), "utf8");
     const parsed = JSON.parse(raw);
     const out = {};
     for (const [name, value] of Object.entries(parsed.dependencies ?? {})) {
@@ -40368,7 +40698,7 @@ function looksLikePath(spec) {
 }
 async function readDependencyEntries2(pluginHome) {
   try {
-    const raw = await readFile8(join7(pluginHome, "package.json"), "utf8");
+    const raw = await readFile9(join8(pluginHome, "package.json"), "utf8");
     const parsed = JSON.parse(raw);
     const out = {};
     for (const [name, value] of Object.entries(parsed.dependencies ?? {})) {
@@ -40394,7 +40724,7 @@ async function resolveLocalPluginName(installSpec, pluginHome, namesBeforeInstal
       return name;
   }
   try {
-    const raw = await readFile8(join7(installSpec, "package.json"), "utf8");
+    const raw = await readFile9(join8(installSpec, "package.json"), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.name === "string" && parsed.name.trim())
       return parsed.name.trim();
@@ -40822,6 +41152,79 @@ async function runRestart2(deps) {
   }
 }
 
+// src/cli/startup-wait-ui.ts
+var SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+var DEFAULT_SPINNER_FRAME = "⠋";
+var ENVIRONMENT_HINT_DELAY_MS = 20000;
+function renderStartupWaitLine(input) {
+  const elapsedSeconds = Math.floor(input.elapsedMs / 1000);
+  const timeoutSeconds = Math.ceil(input.timeoutMs / 1000);
+  const detail = input.elapsedMs >= ENVIRONMENT_HINT_DELAY_MS ? "，首次启动可能需要准备依赖和运行环境" : "";
+  return `${input.frame} 正在创建初始会话${detail} ${elapsedSeconds}s / ${timeoutSeconds}s，按 Ctrl+B 跳过等待`;
+}
+function createStartupWaitUi(input) {
+  const stdin2 = input.stdin ?? process.stdin;
+  const stdout2 = input.stdout ?? process.stdout;
+  if (!input.isInteractive() || !stdin2.isTTY || !stdout2.isTTY) {
+    return { stop: () => {} };
+  }
+  let skipped = false;
+  let interrupted = false;
+  let frameIndex = 0;
+  let rawModeEnabled = false;
+  let stopped = false;
+  const cleanup = () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    stdin2.off("data", onData);
+    if (rawModeEnabled && typeof stdin2.setRawMode === "function") {
+      stdin2.setRawMode(false);
+    }
+    stdin2.pause();
+    stdout2.write("\r\x1B[2K");
+  };
+  const onData = (chunk) => {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (buffer.includes(2)) {
+      skipped = true;
+    }
+    if (buffer.includes(3)) {
+      interrupted = true;
+      cleanup();
+      (input.onInterrupt ?? (() => process.kill(process.pid, "SIGINT")))();
+    }
+  };
+  if (typeof stdin2.setRawMode === "function") {
+    stdin2.setRawMode(true);
+    rawModeEnabled = true;
+  }
+  stdin2.resume();
+  stdin2.on("data", onData);
+  const render = (poll) => {
+    const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length] ?? DEFAULT_SPINNER_FRAME;
+    frameIndex += 1;
+    stdout2.write(`\r\x1B[2K${renderStartupWaitLine({
+      elapsedMs: poll.elapsedMs,
+      timeoutMs: poll.timeoutMs,
+      frame
+    })}`);
+  };
+  return {
+    wait: {
+      onPoll: render,
+      shouldStopWaiting: () => {
+        if (interrupted) {
+          throw new Error("startup wait interrupted");
+        }
+        return skipped;
+      }
+    },
+    stop: cleanup
+  };
+}
+
 // src/cli.ts
 init_bootstrap();
 async function prepareMcpCoordinatorStartup(input) {
@@ -40923,6 +41326,7 @@ var HELP_LINES = [
   "weacpx status - 查看状态",
   "weacpx stop   - 停止服务",
   "weacpx restart - 重启后台服务",
+  "weacpx update [--all|<name>] - 更新 weacpx 和已安装插件",
   "weacpx channel|ch list|show|add|rm|enable|disable [--account <id>] - 管理消息频道（多 bot 用 --account）",
   "weacpx plugin list|add|update|remove|enable|disable|doctor|known - 管理插件",
   "weacpx doctor - 运行诊断",
@@ -40958,8 +41362,28 @@ async function runCli(args, deps = {}) {
       await (deps.logout ?? defaultLogout)();
       return 0;
     case "run":
-      await (deps.run ?? defaultRun)();
+      const onboarding = await runOnboardingBeforeStart({
+        print,
+        cwd: deps.cwd ?? (() => process.cwd()),
+        isInteractive: deps.isInteractive,
+        promptText: deps.promptText
+      });
+      await (deps.run ?? defaultRun)({ firstRunOnboarding: onboarding ?? undefined });
       return 0;
+    case "update": {
+      const result = await (deps.update ?? ((subArgs) => defaultUpdate(subArgs, {
+        print,
+        isInteractive: deps.isInteractive,
+        promptText: deps.promptText,
+        overrides: deps.updateCliDeps
+      })))(args.slice(1));
+      if (result === null) {
+        for (const line of HELP_LINES)
+          print(line);
+        return 1;
+      }
+      return result;
+    }
     case "doctor": {
       const parsed = parseDoctorArgs(args.slice(1));
       if (!parsed.ok) {
@@ -41025,7 +41449,32 @@ async function runCli(args, deps = {}) {
     case "start": {
       const controller = deps.controller ?? createDefaultController();
       try {
-        const result = await controller.start();
+        const isInteractive = deps.isInteractive ?? defaultIsInteractive;
+        const status = await controller.getStatus();
+        if (status.state === "running") {
+          print("weacpx 已在后台运行");
+          print(`PID: ${status.pid}`);
+          return 0;
+        }
+        if (status.state === "indeterminate") {
+          throw new Error(`weacpx daemon process is already running (pid ${status.pid}) but status metadata is missing`);
+        }
+        const onboarding2 = await runOnboardingBeforeStart({
+          print,
+          cwd: deps.cwd ?? (() => process.cwd()),
+          isInteractive,
+          promptText: deps.promptText
+        });
+        const startupWaitUi = onboarding2 ? createStartupWaitUi({ isInteractive }) : null;
+        let result;
+        try {
+          result = await controller.start({
+            firstRunOnboarding: onboarding2 ?? undefined,
+            ...startupWaitUi?.wait ? { startupWait: startupWaitUi.wait } : {}
+          });
+        } finally {
+          startupWaitUi?.stop();
+        }
         if (result.state === "already-running") {
           print("weacpx 已在后台运行");
           print(`PID: ${result.pid}`);
@@ -41036,9 +41485,7 @@ async function runCli(args, deps = {}) {
         return 0;
       } catch (error2) {
         print(`weacpx 启动失败：${describeFriendlyError(error2)}`);
-        const stderrPath = safeStderrLogPath();
-        if (stderrPath)
-          print(`请查看 Stderr: ${stderrPath}`);
+        printDaemonLogHints(print);
         return 1;
       }
     }
@@ -41081,9 +41528,7 @@ async function runCli(args, deps = {}) {
         return await restartDaemonCli(controller, print);
       } catch (error2) {
         print(`weacpx 重启失败：${describeFriendlyError(error2)}`);
-        const stderrPath = safeStderrLogPath();
-        if (stderrPath)
-          print(`请查看 Stderr: ${stderrPath}`);
+        printDaemonLogHints(print);
         return 1;
       }
     }
@@ -41094,6 +41539,44 @@ async function runCli(args, deps = {}) {
       return 1;
   }
 }
+async function defaultUpdate(args, input) {
+  const store = await createCliConfigStore();
+  const deps = {
+    loadConfig: async () => await store.load(),
+    saveConfig: async (config2) => await store.save(config2),
+    readCurrentVersion: readVersion,
+    print: input.print,
+    isInteractive: input.isInteractive ?? defaultIsInteractive,
+    promptText: input.promptText ?? defaultPromptText,
+    ...input.overrides
+  };
+  return await handleUpdateCli(args, deps);
+}
+async function runOnboardingBeforeStart(input) {
+  const runtimePaths = (await init_main().then(() => exports_main)).resolveRuntimePaths();
+  await ensureConfigExists(runtimePaths.configPath);
+  const configStore = new ConfigStore(runtimePaths.configPath);
+  const stateStore = new StateStore(runtimePaths.statePath);
+  const config2 = await configStore.load();
+  const state = await stateStore.load();
+  const result = await maybeRunFirstUseOnboarding({
+    config: config2,
+    state,
+    saveConfig: async (next) => await configStore.save(next),
+    deps: {
+      print: input.print,
+      cwd: input.cwd,
+      isInteractive: input.isInteractive ?? defaultIsInteractive,
+      promptText: input.promptText ?? defaultPromptText
+    }
+  });
+  return result.created ? {
+    alias: result.alias,
+    agent: result.agent,
+    workspace: result.workspace,
+    rollback: result.rollback
+  } : null;
+}
 async function handleWorkspaceCli(args, deps) {
   const subcommand = args[0];
   switch (subcommand) {
@@ -41189,7 +41672,7 @@ async function defaultLoadConfiguredPluginsForChannelCli() {
   const { loadConfiguredPlugins: loadConfiguredPlugins2 } = await Promise.resolve().then(() => (init_plugin_loader(), exports_plugin_loader));
   await loadConfiguredPlugins2({ plugins: config2.plugins });
 }
-async function defaultRun() {
+async function defaultRun(options = {}) {
   const [{ buildApp: buildApp2, resolveRuntimePaths: resolveRuntimePaths2, prepareChannelMedia: prepareChannelMedia2 }, { runConsole: runConsole2 }] = await Promise.all([
     init_main().then(() => exports_main),
     Promise.resolve().then(() => (init_run_console(), exports_run_console))
@@ -41207,11 +41690,15 @@ async function defaultRun() {
   const channelRegistry = new MessageChannelRegistry2(createMessageChannels2(config2.channels, channelDeps));
   const lockCreators = channelRegistry.createConsumerLocks();
   const firstLockCreator = lockCreators[0];
+  const firstRunOnboarding = options.firstRunOnboarding ?? decodeFirstRunOnboarding(process.env.WEACPX_FIRST_RUN_ONBOARDING);
   await runConsole2(runtimePaths, {
     buildApp: (paths) => buildApp2(paths, {
       defaultLoggingLevel: resolveCliEntryPath2().includes(`${sep}src${sep}`) ? "debug" : "info",
       channel: channelRegistry
     }),
+    beforeReady: firstRunOnboarding ? async (runtime) => {
+      await createFirstRunSession(runtime, firstRunOnboarding);
+    } : undefined,
     channels: channelRegistry,
     daemonRuntime,
     ...firstLockCreator ? {
@@ -41224,6 +41711,42 @@ async function defaultRun() {
     } : {}
   });
 }
+async function createFirstRunSession(runtime, plan) {
+  const session = runtime.sessions.resolveSession(plan.alias, plan.agent, plan.workspace, plan.alias);
+  try {
+    await runtime.transport.ensureSession(session);
+    const exists = await runtime.transport.hasSession(session);
+    if (!exists) {
+      throw new Error(`first-run onboarding failed to create transport session: ${plan.alias}`);
+    }
+    await runtime.sessions.attachSession(plan.alias, plan.agent, plan.workspace, session.transportSession);
+  } catch (error2) {
+    await rollbackFirstRunConfig(runtime, plan);
+    throw error2;
+  }
+  await runtime.logger.info("onboarding.session_created", "created first-run transport session", {
+    alias: plan.alias,
+    agent: plan.agent,
+    workspace: plan.workspace
+  });
+}
+async function rollbackFirstRunConfig(runtime, plan) {
+  try {
+    const config2 = await runtime.configStore.load();
+    if (!plan.rollback.workspaceExisted && config2.workspaces[plan.workspace]) {
+      delete config2.workspaces[plan.workspace];
+    }
+    if (!plan.rollback.agentExisted && config2.agents[plan.agent]) {
+      delete config2.agents[plan.agent];
+    }
+    await runtime.configStore.save(config2);
+  } catch (error2) {
+    await runtime.logger.error("onboarding.rollback_failed", "failed to roll back first-run config", {
+      alias: plan.alias,
+      error: error2 instanceof Error ? error2.message : String(error2)
+    });
+  }
+}
 async function defaultDoctor(options) {
   const { main: main3 } = await init_doctor2().then(() => exports_doctor);
   return await main3(options);
@@ -41310,7 +41833,7 @@ async function createChannelCliDeps(input) {
     saveConfig: async (config2) => await store.save(config2),
     print: input.print,
     stderr: input.stderr ?? ((text) => process.stderr.write(text)),
-    isInteractive: input.isInteractive ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY)),
+    isInteractive: input.isInteractive ?? defaultIsInteractive,
     promptText: input.promptText ?? defaultPromptText,
     promptSecret: input.promptSecret ?? defaultPromptSecret,
     getDaemonStatus: async () => {
@@ -41332,7 +41855,7 @@ async function createPluginCliDeps(input) {
     loadConfig: async () => await store.load(),
     saveConfig: async (config2) => await store.save(config2),
     print: input.print,
-    isInteractive: input.isInteractive ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY)),
+    isInteractive: input.isInteractive ?? defaultIsInteractive,
     promptText: input.promptText ?? defaultPromptText,
     getDaemonStatus: async () => {
       const status = await controller.getStatus();
@@ -41408,12 +41931,43 @@ async function defaultPromptSecret(message) {
 }
 function createDefaultController() {
   const daemonPaths = resolveDaemonPaths({ home: requireHome2() });
-  return createDaemonController(daemonPaths, {
+  const controller = createDaemonController(daemonPaths, {
     processExecPath: process.execPath,
     cliEntryPath: resolveCliEntryPath2(),
     cwd: process.cwd(),
     env: process.env
   });
+  return {
+    getStatus: () => controller.getStatus(),
+    stop: () => controller.stop(),
+    start: (options) => controller.start({
+      ...options?.firstRunOnboarding ? { firstRunOnboarding: encodeFirstRunOnboarding(options.firstRunOnboarding) } : {},
+      ...options?.startupWait ? { startupWait: options.startupWait } : {}
+    })
+  };
+}
+function encodeFirstRunOnboarding(plan) {
+  return Buffer.from(JSON.stringify(plan), "utf8").toString("base64url");
+}
+function decodeFirstRunOnboarding(raw) {
+  if (!raw)
+    return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    if (typeof parsed.alias === "string" && typeof parsed.agent === "string" && typeof parsed.workspace === "string") {
+      const rollback = typeof parsed.rollback === "object" && parsed.rollback !== null ? parsed.rollback : {};
+      return {
+        alias: parsed.alias,
+        agent: parsed.agent,
+        workspace: parsed.workspace,
+        rollback: {
+          workspaceExisted: rollback.workspaceExisted === true,
+          agentExisted: rollback.agentExisted === true
+        }
+      };
+    }
+  } catch {}
+  return null;
 }
 function requireHome2() {
   const home = process.env.HOME ?? homedir13();
@@ -41422,12 +41976,27 @@ function requireHome2() {
   }
   return home;
 }
+function defaultIsInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 function describeFriendlyError(error2) {
   return error2 instanceof Error ? error2.message : String(error2);
 }
-function safeStderrLogPath() {
+function printDaemonLogHints(print) {
+  const paths = safeDaemonLogPaths();
+  if (!paths)
+    return;
+  print(`请查看 App Log: ${paths.appLog}`);
+  print(`请查看 Stderr: ${paths.stderrLog}`);
+}
+function safeDaemonLogPaths() {
   try {
-    return resolveDaemonPaths({ home: requireHome2() }).stderrLog;
+    const configPath = process.env.WEACPX_CONFIG ?? `${requireHome2()}/.weacpx/config.json`;
+    const paths = resolveDaemonPaths({ home: requireHome2() });
+    return {
+      appLog: join16(dirname13(configPath), "runtime", "app.log"),
+      stderrLog: paths.stderrLog
+    };
   } catch {
     return null;
   }
@@ -41436,7 +42005,7 @@ function resolveCliEntryPath2() {
   if (process.argv[1]) {
     return process.argv[1];
   }
-  return fileURLToPath5(import.meta.url);
+  return fileURLToPath6(import.meta.url);
 }
 function parseDoctorArgs(args) {
   const options = {};