bilisum 1.20.0-alpha.1 → 1.20.0-alpha.2

package/README.md

@@ -1,11 +1,14 @@
 # BiliSum CLI
 
-`bilisum` 是 BiliSum 的命令行控制面：**直接控制已安装的 BiliSum（桌面端 / 已运行的服务）**，让 Agent / 脚本做视频理解（转写 + 摘要），不打开浏览器、不复用任何独立环境。
+`bilisum` 是 BiliSum 的命令行控制面：**控制已安装的 BiliSum（桌面端 / 已运行的服务），或完全独立运行**（未安装桌面端也能用），让 Agent / 脚本做视频理解（转写 + 摘要）。
 
 ```bash
 # 摘要一个视频（默认输出：元数据 + 总结内容，不含字幕）
 bilisum summarize "https://www.bilibili.com/video/BV1xxxx"
 
+# 快速摘要卡片（跳过知识笔记 LLM 调用，更快）
+bilisum brief "https://www.bilibili.com/video/BV1xxxx"
+
 # 输出 JSON 给 Agent 解析（stdout 只含 JSON，进度在 stderr）
 bilisum summarize "https://www.bilibili.com/video/BV1xxxx" --format json
 
@@ -26,12 +29,35 @@ bilisum --help
 bilisum summarize --help
 ```
 
+## 环境（Environment）
+
+四种环境决定连接哪个服务、用哪套数据：
+
+| 环境 | 说明 | 地址 |
+|------|------|------|
+| `desktop` | 连接桌面端服务（控制现有程序，同库同知识库） | `127.0.0.1:3838` |
+| `cli` | **独立环境**：自带运行时与配置，无需桌面端 | `127.0.0.1:3839` |
+| `custom` | 任意 host/port/token（Docker、远程） | 自定 |
+| `auto` | 默认：桌面端可达则 desktop，否则 cli | 自动 |
+
+```bash
+bilisum env                      # 查看环境状态
+bilisum env use cli              # 切换到独立环境
+bilisum env setup                # 初始化独立环境（内置运行时，需 Python 3.12）
+bilisum --setting                # 打开当前环境的网页设置（cli 环境无需桌面端）
+bilisum summarize <url> --environment cli   # 单次使用某环境
+```
+
+> 完整文档见 [BiliSum CLI 使用指南](https://github.com/lycohana/BiliSum/blob/master/docs/cli.md)。
+
 ## 输出格式
 
-- **`markdown`（默认）**：YAML 元数据头（task_id / status / title / video_id / source）+ 总结内容（知识笔记或概览+要点），**不含字幕**；加 `--with-transcript` 会追加转写全文。
+- **`markdown`（默认）**：YAML 元数据头（task_id / status / title / video_id / source）+ 总结内容（`summarize` 为知识笔记，`brief` 为摘要卡片），**不含字幕**；加 `--with-transcript` 会追加转写全文。
 - **`json`**：完整任务对象（含 `result`，字幕在 `result.transcript_text`）。
 - **`transcript`**：仅转写全文（`bilisum transcribe` 的默认输出）。
 
+任务等待期间进度显示在 stderr（`[task_id]  12% [stage] 消息`），stdout 保持干净。
+
 ## 它如何"控制现有程序"
 
 - 默认连接桌面端服务 `http://127.0.0.1:3838`，任务、结果、知识库都与桌面端**同一个数据库**。
@@ -41,13 +67,15 @@ bilisum summarize --help
 
 ## 服务不在线时
 
-`summarize / transcribe / status / tasks` 会先探活；如果 `127.0.0.1:3838` 没有服务，就**用桌面端数据目录自动后台拉起一个**（优先用桌面端自带的托管 Python 运行时，其次系统 Python 3.12），等 `/health` 就绪后继续。CLI 拉起的服务进程记录在 `{数据根}\cli-runtime.json`：
+`summarize / brief / transcribe / status / tasks` 会先探活；如果 `127.0.0.1:3838` 没有服务，就**用桌面端数据目录自动后台拉起一个**（优先用桌面端自带的托管 Python 运行时，其次系统 Python 3.12），等 `/health` 就绪后继续。CLI 拉起的服务进程记录在 `{数据根}\cli-runtime-<port>.json`：
 
 ```bash
 bilisum start --no-open   # 前台启动（可选，一般不用）
 bilisum stop              # 停止 CLI 拉起的服务
 ```
 
+**无任务自动关闭**：CLI 后台拉起的服务默认空闲 10 分钟（且无排队/运行中任务）自动退出，可用 `--idle-timeout <sec>` 或 `BILISUM_CLI_IDLE_TIMEOUT` 环境变量调整。该机制只作用于 CLI 自己拉起的服务（通过 `VIDEO_SUM_CLI_MANAGED` 标记），**桌面端启动的服务绝不会被自动关闭**。
+
 > 注意：桌面端自己运行的服务不受 `bilisum stop` 影响（没有 cli-runtime 记录时会提示）。
 
 ## 安装
@@ -71,11 +99,14 @@ npm install -g bilisum          # 或 npx bilisum ...
 | `--page <n> / --all-pages` | 多 P 视频分 P 选择 |
 | `--visual-note <mode>` | `text` / `frame_insert` / `vlm_integrated` |
 | `--no-wait` | 只创建任务，立即返回 task_id |
+| `--idle-timeout <sec>` | CLI 后台服务空闲自动关闭秒数（默认 600） |
 | `--timeout <sec>` | 等待完成超时（默认 3600） |
 | `--quiet` | 抑制 stderr 进度输出 |
 
 > 说明：任务转写与摘要在服务端一体执行；`transcribe` 输出转写全文，任务仍会顺带生成摘要。语言 / 摘要模式等参数跟随服务端设置。
 
+> 完整文档见 [BiliSum CLI 使用指南](https://github.com/lycohana/BiliSum/blob/master/docs/cli.md)。
+
 ## 桌面端内置
 
 桌面版 BiliSum 打包时会把 CLI 一并放进安装目录的 `resources/cli`，可用：

package/bin/bilisum.js

@@ -8,6 +8,7 @@ const { existsSync } = require("node:fs");
 const {
   baseUrlFor,
   getTask,
+  getTaskProgress,
   listTasks,
   probeVideo,
   uploadLocalMedia,
@@ -16,13 +17,20 @@ const {
 } = require("../lib/api");
 const { UsageError, parseTaskCommandArgs } = require("../lib/args");
 const { formatTasks, emit } = require("../lib/output");
-const { readVersion, locateBilisumDataRoot, findPython } = require("../lib/runtime");
+const { readVersion, locateBilisumDataRoot, findPython, cliHomeDir, ensureCliVenv, cliVenvPython, findSystemPython } = require("../lib/runtime");
 const { readToken } = require("../lib/token");
 const {
   ensureService,
   stopService,
   spawnService,
 } = require("../lib/server");
+const {
+  resolveEnvironment,
+  readConfig,
+  writeConfig,
+  ENV_NAMES,
+  isDesktopReachable,
+} = require("../lib/env");
 
 const RELEASES_URL = "https://github.com/lycohana/BiliSum/releases/latest";
 const REPO_URL = "https://github.com/lycohana/BiliSum";
@@ -37,26 +45,32 @@ function printHelp() {
   console.log("AI 视频总结与知识库工具：CLI 直接控制已安装的 BiliSum（桌面端/服务）。");
   console.log("");
   console.log("Usage:");
-  console.log("  npx bilisum summarize <url|file> [options]  Summarize a video (agent-friendly)");
+  console.log("  npx bilisum summarize <url|file> [options]  Summarize a video (knowledge note)");
+  console.log("  npx bilisum brief <url|file> [options]      Fast summary card only (skips note)");
   console.log("  npx bilisum transcribe <url|file> [options] Print the transcript of a video");
   console.log("  npx bilisum status <task-id> [--json]       Show task status");
   console.log("  npx bilisum tasks [--limit N] [--json]      List tasks");
-  console.log("  npx bilisum start [options]                 Start the service (desktop data dir)");
+  console.log("  npx bilisum env [use <name>|setup]          Environment status / switch / setup");
+  console.log("  npx bilisum --setting                       Open the web settings page");
+  console.log("  npx bilisum start [options]                 Start the service");
   console.log("  npx bilisum stop                            Stop the CLI-started BiliSum service");
-  console.log("  npx bilisum doctor                          Check service/Python setup");
+  console.log("  npx bilisum doctor                          Check environment/service/Python setup");
   console.log("  npx bilisum --version                       Print package version");
   console.log("  npx bilisum release                         Open the latest GitHub release");
   console.log("");
+  console.log("环境（bilisum env）：desktop 连桌面端服务 / cli 独立环境（自带运行时）/ custom 自定义 / auto 自动");
+  console.log("");
   console.log("默认连接桌面端服务 http://127.0.0.1:3838；未运行时自动用桌面端数据目录后台拉起。");
   console.log("");
   console.log("Options (all commands):");
   console.log("  --host <host>                        Host, default 127.0.0.1");
   console.log("  --port <port>                        Port, default 3838");
-  console.log("  --data <path>                        Desktop data root (default: desktop app data)");
-  console.log("  --token <token>                      Access token (default: desktop token)");
+  console.log("  --data <path>                        Data root (default: env-dependent)");
+  console.log("  --token <token>                      Access token (default: env-dependent)");
+  console.log("  --environment <name>                 desktop | cli | custom | auto (one-shot)");
   console.log("  --env KEY=VALUE                      Extra env for a CLI-started service");
   console.log("");
-  console.log("Options (summarize/transcribe):");
+  console.log("Options (summarize/brief/transcribe):");
   console.log("  --page <n>                           Process a specific P for multi-P videos");
   console.log("  --all-pages                          Process every P of a multi-P video");
   console.log("  --visual-note <mode>                 text | frame_insert | vlm_integrated");
@@ -65,11 +79,13 @@ function printHelp() {
   console.log("  --output <path> / -o <path>          Write result to a file instead of stdout");
   console.log("  --with-transcript                    Append the full transcript to markdown output");
   console.log("  --no-wait                            Create the task and exit immediately");
+  console.log("  --idle-timeout <sec>                 CLI 后台服务无任务自动关闭秒数，默认 600");
   console.log("  --timeout <sec>                      Max wait for completion, default 3600");
   console.log("  --startup-timeout <sec>              Max wait for service startup, default 300");
   console.log("  --quiet / -q                         Suppress progress output (stderr)");
   console.log("");
   console.log("默认输出为元数据 + 总结内容（不含字幕），需要字幕请加 --with-transcript。");
+  console.log("brief 只生成摘要卡片（跳过知识笔记 LLM 调用，更快）。");
   console.log("Options (start):");
   console.log("  --no-open                            Do not open the browser");
   console.log("");
@@ -85,6 +101,9 @@ function parseConnectionOptions(args, { allowTaskId = false } = {}) {
     data: process.env.BILISUM_DATA || locateBilisumDataRoot(),
     token: process.env.BILISUM_TOKEN || "",
     env: [],
+    environment: "",
+    _hostSet: false,
+    _portSet: false,
     json: false,
     limit: 20,
     help: false,
@@ -102,14 +121,22 @@ function parseConnectionOptions(args, { allowTaskId = false } = {}) {
     const arg = args[index];
     if (arg === "--host") {
       options.host = readValue(++index, arg);
+      options._hostSet = true;
     } else if (arg === "--port" || arg === "-p") {
       options.port = readValue(++index, arg);
+      options._portSet = true;
     } else if (arg === "--python") {
       options.python = readValue(++index, arg);
     } else if (arg === "--data") {
       options.data = readValue(++index, arg);
     } else if (arg === "--token") {
       options.token = readValue(++index, arg);
+    } else if (arg === "--environment" || arg === "--env-mode") {
+      const name = readValue(++index, arg);
+      if (!ENV_NAMES.includes(name)) {
+        throw new UsageError(`--environment 仅支持 ${ENV_NAMES.join(" / ")}，收到：${name}`);
+      }
+      options.environment = name;
     } else if (arg === "--env" || arg === "-e") {
       options.env.push(readValue(++index, arg));
     } else if (arg === "--json") {
@@ -157,6 +184,12 @@ async function ensureAuthenticatedService(options, log) {
   // Resolve the token first (desktop token / auth.json / --token / env) and
   // inject it into a service the CLI spawns, so both always agree.
   let token = readToken(options);
+  if (!token && options.environment === "cli") {
+    // Standalone cli environment: generate a token and inject it into the
+    // service (same pattern as the desktop app), so we never depend on
+    // auth.json creation timing.
+    token = require("node:crypto").randomBytes(32).toString("hex");
+  }
   await ensureService(options, { log, accessToken: token });
   if (!token) {
     // The CLI just spawned the service, which may have created {data}/auth.json.
@@ -220,6 +253,7 @@ async function resolveAndCreateTasks(source, options, token, baseUrl, log) {
       pageNumber,
       visualNoteMode: options.visualNote,
       promptPresetId: options.promptPreset,
+      summaryScope: options.brief ? "summary" : undefined,
     });
     created.push(task);
     log(`任务已创建：${task.task_id}`);
@@ -242,20 +276,25 @@ async function waitForTasks(taskIds, options, token, baseUrl, log) {
       }
       let progress = null;
       try {
-        progress = await getTask(baseUrl, token, taskId);
+        progress = await getTaskProgress(baseUrl, token, taskId);
       } catch (error) {
         if (error instanceof ApiError && error.status === 404) {
           throw new Error(`任务不存在：${taskId}`);
         }
-        throw error;
+        // Fall back to the detail endpoint if progress is unavailable.
+        progress = await getTask(baseUrl, token, taskId);
       }
       state.status = progress.status;
       states.set(taskId, state);
       if (!TERMINAL_STATUSES.has(progress.status)) {
-        const marker = `${taskId}:${progress.status}`;
+        const marker = `${taskId}:${progress.status}:${progress.progress ?? ""}:${progress.latest_stage ?? ""}`;
         if (!seenProgress.has(marker)) {
           seenProgress.add(marker);
-          log(`[${taskId}] ${progress.status}（${progress.title || "视频"}）`);
+          const pct = Number(progress.progress);
+          const pctText = Number.isFinite(pct) ? `${String(Math.max(0, Math.min(100, Math.round(pct)))).padStart(3)}%` : "  -%";
+          const stage = progress.latest_stage ? ` [${progress.latest_stage}]` : "";
+          const message = progress.latest_message ? ` ${progress.latest_message}` : "";
+          log(`[${taskId}] ${pctText}${stage}${message}`);
         }
       }
       allTerminal.push(TERMINAL_STATUSES.has(progress.status));
@@ -277,8 +316,9 @@ async function waitForTasks(taskIds, options, token, baseUrl, log) {
   }
 }
 
-async function runTaskCommand(args, { defaultFormat }) {
+async function runTaskCommand(args, { defaultFormat, brief = false }) {
   const { source, options } = parseTaskCommandArgs(args, { defaultFormat });
+  options.brief = brief;
   if (options.help) {
     printHelp();
     return;
@@ -288,6 +328,7 @@ async function runTaskCommand(args, { defaultFormat }) {
     throw new UsageError(`本地文件不存在：${source}`);
   }
   const log = options.quiet ? () => {} : console.error;
+  await resolveEnvironment(options);
   const baseUrl = baseUrlFor(options.host, options.port);
   const token = await ensureAuthenticatedService(options, log);
   const tasks = await resolveAndCreateTasks(source, options, token, baseUrl, log);
@@ -322,7 +363,7 @@ async function runTaskCommand(args, { defaultFormat }) {
     throw new Error(`${failed.length} 个任务失败。`);
   }
   const written = emit(
-    formatTasks(completed, options.format, { includeTranscript: options.withTranscript }),
+    formatTasks(completed, options.format, { includeTranscript: options.withTranscript, brief }),
     options,
   );
   if (written) {
@@ -340,6 +381,7 @@ async function statusCommand(args) {
     throw new UsageError("缺少 task-id。用法：bilisum status <task-id> [--json]");
   }
   const log = console.error;
+  await resolveEnvironment(options);
   const baseUrl = baseUrlFor(options.host, options.port);
   const token = await ensureAuthenticatedService(options, log);
   const taskId = positional[0];
@@ -379,6 +421,7 @@ async function tasksCommand(args) {
     return;
   }
   const log = console.error;
+  await resolveEnvironment(options);
   const baseUrl = baseUrlFor(options.host, options.port);
   const token = await ensureAuthenticatedService(options, log);
   const tasks = await listTasks(baseUrl, token);
@@ -400,10 +443,12 @@ async function tasksCommand(args) {
   }
 }
 
-function startService(args) {
+async function startService(args) {
   const { options } = parseConnectionOptions(args);
+  await resolveEnvironment(options);
   const url = `http://${options.host}:${options.port}`;
   console.log(`Starting BiliSum at ${url}`);
+  console.log(`Environment:    ${options.environment}`);
   console.log(`Data root:      ${options.data}`);
   console.log("");
   const { child } = spawnService(options, { background: false });
@@ -419,16 +464,96 @@ function startService(args) {
   });
 }
 
-function doctor(args) {
+async function doctor(args) {
   const { options } = parseConnectionOptions(args);
-  const python = options.python
-    ? { command: options.python, args: [] }
-    : findPython(options.data);
+  await resolveEnvironment(options);
+  const python = options.environment === "cli"
+    ? { command: cliVenvPython(), args: [] }
+    : options.python
+      ? { command: options.python, args: [] }
+      : findPython(options.data);
   console.log(`BiliSum package: ${readVersion()}`);
-  console.log(`Data root:       ${options.data}`);
-  console.log(`Python:          ${python ? [python.command, ...python.args].join(" ") : "未找到（请安装桌面版 BiliSum 或 Python 3.12）"}`);
+  console.log(`Environment:     ${options.environment}`);
   console.log(`Service:         http://${options.host}:${options.port}`);
-  console.log(`Token:           ${readToken(options) ? "已找到" : "未找到（连接服务时需 --token 或启动一次桌面端）"}`);
+  console.log(`Data root:       ${options.data}`);
+  console.log(`Python:          ${python && python.command ? [python.command, ...python.args].join(" ") : "未找到（请安装桌面版 BiliSum、Python 3.12，或运行 bilisum env setup）"}`);
+  console.log(`Token:           ${readToken(options) ? "已找到" : "未找到（desktop 环境请先启动桌面端；cli 环境运行后自动生成）"}`);
+  if (options.environment === "cli") {
+    console.log(`CLI env status:  ${require("node:fs").existsSync(cliVenvPython()) ? "就绪" : "未初始化（运行 bilisum env setup）"}`);
+  }
+}
+
+async function settingsCommand(args) {
+  const { options } = parseConnectionOptions(args);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  const log = console.error;
+  await resolveEnvironment(options);
+  await ensureService(options, { log });
+  const url = `http://${options.host}:${options.port}/settings`;
+  log(`打开设置页：${url}`);
+  openUrl(url);
+}
+
+async function envCommand(args) {
+  const sub = (args[0] || "").toLowerCase();
+  const config = readConfig();
+
+  if (sub === "use") {
+    const name = String(args[1] || "").toLowerCase();
+    if (!ENV_NAMES.includes(name) || name === "auto") {
+      throw new UsageError(`用法：bilisum env use ${ENV_NAMES.filter((item) => item !== "auto").join("|")}`);
+    }
+    writeConfig({ ...config, env: name });
+    console.log(`已切换到 ${name} 环境。`);
+    return;
+  }
+
+  if (sub === "setup") {
+    console.log(`初始化 CLI 独立环境（${cliHomeDir()}）...`);
+    const python = ensureCliVenv({ python: process.env.BILISUM_PYTHON || "", environment: "cli" }, console.error);
+    console.log(`CLI 独立环境就绪：${python}`);
+    return;
+  }
+
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    printEnvHelp();
+    return;
+  }
+
+  // default: status
+  const current = await resolveEnvironment({ environment: config.env || "auto" });
+  const desktopUp = await isDesktopReachable();
+  console.log(`当前环境:      ${current.env}`);
+  console.log(`服务地址:      http://${current.host}:${current.port}`);
+  console.log(`数据根:        ${current.dataRoot}`);
+  console.log("");
+  console.log("可用环境:");
+  console.log(`  desktop    ${desktopUp ? "● 桌面端服务在运行" : "○ 未检测到桌面端服务（127.0.0.1:3838）"}`);
+  const venvReady = require("node:fs").existsSync(cliVenvPython());
+  console.log(`  cli        ${venvReady ? "● 独立环境已就绪" : "○ 未初始化（bilisum env setup）"}  CLI_HOME=${cliHomeDir()}`);
+  console.log(`  custom     ${config.custom ? "● 已配置" : "○ 未配置（--host/--port/--token）"}`);
+  console.log(`  auto       desktop 优先，否则 cli`);
+  console.log("");
+  console.log("切换：bilisum env use desktop|cli|custom");
+  if (config.env && config.env !== "auto") {
+    console.log(`已持久化选择：${config.env}`);
+  }
+}
+
+function printEnvHelp() {
+  console.log("Usage:");
+  console.log("  bilisum env                     Show environment status");
+  console.log("  bilisum env use <name>          Switch environment (desktop|cli|custom)");
+  console.log("  bilisum env setup               Initialize the standalone cli environment");
+  console.log("");
+  console.log("Environments:");
+  console.log("  desktop  Connect to the installed desktop app service (127.0.0.1:3838)");
+  console.log("  cli      Standalone: own data root, own venv, own settings page (127.0.0.1:3839)");
+  console.log("  custom   Any host/port/token (Docker, remote)");
+  console.log("  auto     Desktop if reachable, otherwise cli (default)");
 }
 
 function openUrl(url) {
@@ -463,6 +588,10 @@ async function main() {
       await runTaskCommand(args, { defaultFormat: "markdown" });
       return;
     }
+    if (command === "brief") {
+      await runTaskCommand(args, { defaultFormat: "markdown", brief: true });
+      return;
+    }
     if (command === "transcribe" || command === "trans") {
       await runTaskCommand(args, { defaultFormat: "transcript" });
       return;
@@ -475,13 +604,22 @@ async function main() {
       await tasksCommand(args);
       return;
     }
+    if (command === "env") {
+      await envCommand(args);
+      return;
+    }
+    if (command === "settings" || command === "--setting" || command === "config") {
+      await settingsCommand(args);
+      return;
+    }
     if (command === "stop") {
       const { options } = parseConnectionOptions(args);
+      await resolveEnvironment(options);
       await stopService(options);
       return;
     }
     if (command === "doctor") {
-      doctor(args);
+      await doctor(args);
       return;
     }
     if (command === "help" || command === "-h" || command === "--help") {

package/lib/api.js

@@ -122,7 +122,7 @@ function uploadLocalMedia(baseUrl, token, filePath, { timeoutMs = 30 * 60_000 }
   });
 }
 
-function createVideoTask(baseUrl, token, videoId, { pageNumber, visualNoteMode, promptPresetId, timeoutMs = 30_000 } = {}) {
+function createVideoTask(baseUrl, token, videoId, { pageNumber, visualNoteMode, promptPresetId, summaryScope, timeoutMs = 30_000 } = {}) {
   const payload = {};
   if (pageNumber !== undefined && pageNumber !== null) {
     payload.page_number = pageNumber;
@@ -133,6 +133,9 @@ function createVideoTask(baseUrl, token, videoId, { pageNumber, visualNoteMode,
   if (promptPresetId) {
     payload.prompt_preset_id = promptPresetId;
   }
+  if (summaryScope) {
+    payload.summary_scope = summaryScope;
+  }
   return apiRequest(baseUrl, `/api/v1/videos/${encodeURIComponent(videoId)}/tasks`, {
     method: "POST",
     token,
@@ -141,6 +144,13 @@ function createVideoTask(baseUrl, token, videoId, { pageNumber, visualNoteMode,
   });
 }
 
+function getTaskProgress(baseUrl, token, taskId, { timeoutMs = 30_000 } = {}) {
+  return apiRequest(baseUrl, `/api/v1/tasks/${encodeURIComponent(taskId)}/progress`, {
+    token,
+    timeoutMs,
+  });
+}
+
 function getTask(baseUrl, token, taskId, { timeoutMs = 30_000 } = {}) {
   return apiRequest(baseUrl, `/api/v1/tasks/${encodeURIComponent(taskId)}`, {
     token,
@@ -169,6 +179,7 @@ module.exports = {
   uploadLocalMedia,
   createVideoTask,
   getTask,
+  getTaskProgress,
   listTasks,
   deleteTask,
 };

package/lib/args.js

@@ -5,6 +5,7 @@
  */
 
 const { locateBilisumDataRoot } = require("./runtime");
+const { ENV_NAMES } = require("./env");
 
 class UsageError extends Error {
   constructor(message) {
@@ -44,6 +45,9 @@ function parseTaskCommandArgs(args, { defaultFormat = "markdown" } = {}) {
     data: process.env.BILISUM_DATA || locateBilisumDataRoot(),
     token: process.env.BILISUM_TOKEN || "",
     env: [],
+    environment: "",
+    _hostSet: false,
+    _portSet: false,
     format: defaultFormat,
     output: "",
     wait: true,
@@ -53,6 +57,7 @@ function parseTaskCommandArgs(args, { defaultFormat = "markdown" } = {}) {
     visualNote: "",
     promptPreset: "",
     withTranscript: false,
+    idleTimeout: Number.parseInt(process.env.BILISUM_CLI_IDLE_TIMEOUT || "600", 10) || 600,
     timeoutSeconds: 3600,
     startupTimeoutSeconds: 300,
   };
@@ -62,10 +67,18 @@ function parseTaskCommandArgs(args, { defaultFormat = "markdown" } = {}) {
     const arg = args[index];
     if (arg === "--host") {
       options.host = readValue(args, ++index, arg);
+      options._hostSet = true;
     } else if (arg === "--port" || arg === "-p") {
       options.port = readValue(args, ++index, arg);
+      options._portSet = true;
     } else if (arg === "--python") {
       options.python = readValue(args, ++index, arg);
+    } else if (arg === "--environment" || arg === "--env-mode") {
+      const name = readValue(args, ++index, arg);
+      if (!ENV_NAMES.includes(name)) {
+        throw new UsageError(`--environment 仅支持 ${ENV_NAMES.join(" / ")}，收到：${name}`);
+      }
+      options.environment = name;
     } else if (arg === "--data") {
       options.data = readValue(args, ++index, arg);
     } else if (arg === "--token") {
@@ -98,6 +111,8 @@ function parseTaskCommandArgs(args, { defaultFormat = "markdown" } = {}) {
       options.visualNote = mode;
     } else if (arg === "--prompt-preset") {
       options.promptPreset = readValue(args, ++index, arg);
+    } else if (arg === "--idle-timeout") {
+      options.idleTimeout = parsePositiveInt(readValue(args, ++index, arg), "--idle-timeout");
     } else if (arg === "--timeout") {
       options.timeoutSeconds = parsePositiveInt(readValue(args, ++index, arg), "--timeout");
     } else if (arg === "--startup-timeout") {

package/lib/env.js

@@ -0,0 +1,138 @@
+"use strict";
+
+/**
+ * Environment resolution for the BiliSum CLI.
+ *
+ * Environments:
+ * - desktop: talk to an installed desktop app service (127.0.0.1:3838, desktop
+ *   data root + desktop token). This is the "control the existing program" mode.
+ * - cli: standalone mode — the CLI provides its own service (own data root
+ *   under CLI_HOME, own managed venv, own settings page). Works without any
+ *   installed BiliSum.
+ * - custom: any host/port/token (Docker, remote, ...).
+ * - auto (default): probe 127.0.0.1:3838 — reachable => desktop, else cli.
+ *
+ * Selection precedence:
+ * 1. --environment desktop|cli|custom (one-shot override)
+ * 2. explicit --host/--port (treated as a custom target)
+ * 3. config.env persisted by `bilisum env use <name>`
+ * 4. auto
+ */
+
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const { health } = require("./api");
+const { locateBilisumDataRoot, cliHomeDir } = require("./runtime");
+
+const ENV_NAMES = ["auto", "desktop", "cli", "custom"];
+const DESKTOP_HOST = "127.0.0.1";
+const DESKTOP_PORT = "3838";
+const CLI_PORT = "3839";
+
+function configPath() {
+  return join(cliHomeDir(), "config.json");
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    return { env: "auto" };
+  }
+}
+
+function writeConfig(config) {
+  mkdirSync(cliHomeDir(), { recursive: true });
+  writeFileSync(configPath(), JSON.stringify(config, null, 2), "utf8");
+}
+
+function normalizeEnvName(name) {
+  const normalized = String(name || "").trim().toLowerCase();
+  return ENV_NAMES.includes(normalized) ? normalized : null;
+}
+
+function currentEnvName(config) {
+  return normalizeEnvName((config && config.env) || "auto") || "auto";
+}
+
+async function isDesktopReachable(port = DESKTOP_PORT) {
+  try {
+    const payload = await health(`http://${DESKTOP_HOST}:${port}`);
+    return Boolean(payload && String(payload.service || "").trim() === "BiliSum");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve which environment a command should talk to and return concrete
+ * { env, host, port, dataRoot, token }. Mutates `options.host/port/data/token`
+ * to the resolved values (explicit flags win).
+ */
+async function resolveEnvironment(options = {}) {
+  const config = readConfig();
+  const explicitHost = Boolean(options._hostSet);
+  const explicitPort = Boolean(options._portSet);
+  const flag = normalizeEnvName(options.environment);
+
+  let env;
+  if (explicitHost || explicitPort) {
+    // Explicit connection target always wins (custom).
+    env = "custom";
+  } else if (flag && flag !== "auto") {
+    env = flag;
+  } else {
+    env = currentEnvName(config);
+    if (env === "auto") {
+      const probe = options._desktopProbe || isDesktopReachable;
+      env = (await probe()) ? "desktop" : "cli";
+    }
+  }
+
+  let host;
+  let port;
+  let dataRoot;
+  let token;
+
+  if (env === "desktop") {
+    host = explicitHost ? options.host : DESKTOP_HOST;
+    port = explicitPort ? options.port : DESKTOP_PORT;
+    dataRoot = options.data || locateBilisumDataRoot();
+    token = options.token || "";
+  } else if (env === "cli") {
+    const cliPort = String((config.cli && config.cli.port) || CLI_PORT);
+    host = DESKTOP_HOST;
+    port = explicitPort ? options.port : cliPort;
+    dataRoot = cliHomeDir();
+    token = options.token || "";
+  } else {
+    const custom = (config.custom && typeof config.custom === "object") ? config.custom : {};
+    host = explicitHost ? options.host : String(custom.host || DESKTOP_HOST);
+    port = explicitPort ? options.port : String(custom.port || DESKTOP_PORT);
+    dataRoot = cliHomeDir();
+    token = options.token || String(custom.token || "");
+  }
+
+  options.host = host;
+  options.port = port;
+  options.data = dataRoot;
+  options.token = token;
+  options.environment = env;
+  return { env, host, port, dataRoot, token };
+}
+
+module.exports = {
+  ENV_NAMES,
+  DESKTOP_HOST,
+  DESKTOP_PORT,
+  CLI_PORT,
+  cliHomeDir,
+  configPath,
+  readConfig,
+  writeConfig,
+  normalizeEnvName,
+  currentEnvName,
+  isDesktopReachable,
+  resolveEnvironment,
+};