bilisum 1.20.0-alpha.3 → 1.20.0-alpha.4

package/README.md

@@ -43,6 +43,8 @@ bilisum summarize --help
 ```bash
 bilisum env                      # 查看环境状态
 bilisum env use cli              # 切换到独立环境
+bilisum desktop                  # 快捷切换到桌面端环境
+bilisum auto                     # 恢复自动选择
 bilisum env setup                # 初始化独立环境（内置运行时，需 Python 3.12）
 bilisum --setting                # 打开当前环境的网页设置（cli 环境无需桌面端）
 bilisum summarize <url> --environment cli   # 单次使用某环境
@@ -60,14 +62,14 @@ bilisum summarize <url> --environment cli   # 单次使用某环境
 
 ## 它如何"控制现有程序"
 
-- 默认连接桌面端服务 `http://127.0.0.1:3838`，任务、结果、知识库都与桌面端**同一个数据库**。
+- `desktop` 环境连接桌面端服务 `http://127.0.0.1:3838`，任务、结果、知识库都与桌面端**同一个数据库**；默认 `auto` 会优先探测 desktop，不可达时使用 cli 独立环境。
 - 访问令牌自动获取：`--token` → `VIDEO_SUM_ACCESS_TOKEN` → 桌面端自己的 token 文件（`%APPDATA%\BiliSum\access-token.json` 等）→ 服务侧 `{数据根}\data\auth.json`。桌面端正在运行时通常无需任何配置。
-- 数据根默认与桌面端一致（Windows `%LOCALAPPDATA%\bilisum`，macOS `~/Library/Application Support/bilisum`），可用 `--data` / `BILISUM_DATA_ROOT` 覆盖。
+- desktop 数据根默认与桌面端一致（Windows `%LOCALAPPDATA%\bilisum`，macOS `~/Library/Application Support/bilisum`）；cli 使用独立的 `CLI_HOME`。
 - 配置（LLM / ASR Key 等）跟随服务端设置，桌面端里配好了，CLI 直接用。
 
 ## 服务不在线时
 
-`summarize / brief / transcribe / status / tasks` 会先探活；如果 `127.0.0.1:3838` 没有服务，就**用桌面端数据目录自动后台拉起一个**（优先用桌面端自带的托管 Python 运行时，其次系统 Python 3.12），等 `/health` 就绪后继续。CLI 拉起的服务进程记录在 `{数据根}\cli-runtime-<port>.json`：
+`summarize / brief / transcribe / status / tasks` 会先探活当前环境。desktop 不可达时用桌面端数据目录拉起服务，cli 不可达时用 CLI 独立数据目录和 venv 拉起服务；custom 只连接指定地址，不会在本机拉起替代服务。CLI 拉起的服务进程记录在 `{数据根}\cli-runtime-<port>.json`：
 
 ```bash
 bilisum start --no-open   # 前台启动（可选，一般不用）
@@ -84,13 +86,13 @@ bilisum stop              # 停止 CLI 拉起的服务
 npm install -g bilisum          # 或 npx bilisum ...
 ```
 
-包内**不包含 Python 运行时**（CLI 是纯客户端），首次使用要求机器上已有桌面版 BiliSum 或 Python 3.12。
+包内包含构建独立环境所需的 Python 源码；首次执行 `bilisum env setup` 仍要求系统已有 Python 3.12。
 
 ## 常用选项
 
 | 选项 | 说明 |
 |------|------|
-| `--host / --port` | 服务地址（默认 `127.0.0.1:3838`） |
+| `--host / --port` | 自定义服务地址（显式指定时进入 custom 环境） |
 | `--data <path>` | 桌面端数据根（默认 `%LOCALAPPDATA%\bilisum`） |
 | `--token <token>` | 访问令牌（默认自动读桌面端 token） |
 | `--format json\|markdown\|transcript` | 输出格式，默认 markdown |

package/bin/bilisum.js

@@ -51,6 +51,7 @@ function printHelp() {
   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 env [use <name>|setup]          Environment status / switch / setup");
+  console.log("  npx bilisum desktop|cli|custom|auto         Switch environment (shortcut)");
   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");
@@ -60,7 +61,7 @@ function printHelp() {
   console.log("");
   console.log("环境（bilisum env）：desktop 连桌面端服务 / cli 独立环境（自带运行时）/ custom 自定义 / auto 自动");
   console.log("");
-  console.log("默认连接桌面端服务 http://127.0.0.1:3838；未运行时自动用桌面端数据目录后台拉起。");
+  console.log("默认按已保存的环境连接；auto 模式优先桌面端，否则使用 CLI 独立环境。");
   console.log("");
   console.log("Options (all commands):");
   console.log("  --host <host>                        Host, default 127.0.0.1");
@@ -132,7 +133,7 @@ function parseConnectionOptions(args, { allowTaskId = false } = {}) {
     } else if (arg === "--token") {
       options.token = readValue(++index, arg);
     } else if (arg === "--environment" || arg === "--env-mode") {
-      const name = readValue(++index, arg);
+      const name = readValue(++index, arg).toLowerCase();
       if (!ENV_NAMES.includes(name)) {
         throw new UsageError(`--environment 仅支持 ${ENV_NAMES.join(" / ")}，收到：${name}`);
       }
@@ -514,11 +515,12 @@ async function envCommand(args) {
 
   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("|")}`);
+    if (!ENV_NAMES.includes(name) || args.length !== 2) {
+      throw new UsageError(`用法：bilisum env use ${ENV_NAMES.join("|")}`);
     }
     writeConfig({ ...config, env: name });
-    console.log(`已切换到 ${name} 环境。`);
+    const suffix = name === "auto" ? "（桌面端可用时优先 desktop，否则 cli）" : "";
+    console.log(`已切换到 ${name} 环境${suffix}。`);
     return;
   }
 
@@ -534,6 +536,10 @@ async function envCommand(args) {
     return;
   }
 
+  if (sub) {
+    throw new UsageError(`未知 env 子命令：${sub}`);
+  }
+
   // default: status
   const current = await resolveEnvironment({ environment: config.env || "auto" });
   const desktopUp = await isDesktopReachable();
@@ -548,7 +554,7 @@ async function envCommand(args) {
   console.log(`  custom     ${config.custom ? "● 已配置" : "○ 未配置（--host/--port/--token）"}`);
   console.log(`  auto       desktop 优先，否则 cli`);
   console.log("");
-  console.log("切换：bilisum env use desktop|cli|custom");
+  console.log("切换：bilisum env use desktop|cli|custom|auto（也可直接 bilisum desktop|cli|custom|auto）");
   if (config.env && config.env !== "auto") {
     console.log(`已持久化选择：${config.env}`);
   }
@@ -557,7 +563,8 @@ async function envCommand(args) {
 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 use <name>          Switch environment (desktop|cli|custom|auto)");
+  console.log("  bilisum <name>                  Shortcut for `bilisum env use <name>`");
   console.log("  bilisum env setup               Initialize the standalone cli environment");
   console.log("");
   console.log("Environments:");
@@ -619,6 +626,13 @@ async function main() {
       await envCommand(args);
       return;
     }
+    if (ENV_NAMES.includes(command)) {
+      if (args.length > 0) {
+        throw new UsageError(`用法：bilisum ${command}`);
+      }
+      await envCommand(["use", command]);
+      return;
+    }
     if (command === "settings" || command === "--setting" || command === "config") {
       await settingsCommand(args);
       return;

package/lib/args.js

@@ -74,7 +74,7 @@ function parseTaskCommandArgs(args, { defaultFormat = "markdown" } = {}) {
     } else if (arg === "--python") {
       options.python = readValue(args, ++index, arg);
     } else if (arg === "--environment" || arg === "--env-mode") {
-      const name = readValue(args, ++index, arg);
+      const name = readValue(args, ++index, arg).toLowerCase();
       if (!ENV_NAMES.includes(name)) {
         throw new UsageError(`--environment 仅支持 ${ENV_NAMES.join(" / ")}，收到：${name}`);
       }

package/lib/env.js

@@ -13,8 +13,8 @@
  * - 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)
+ * 1. explicit --host/--port (treated as a custom target)
+ * 2. --environment desktop|cli|custom|auto (one-shot override)
  * 3. config.env persisted by `bilisum env use <name>`
  * 4. auto
  */
@@ -74,20 +74,29 @@ async function resolveEnvironment(options = {}) {
   const config = readConfig();
   const explicitHost = Boolean(options._hostSet);
   const explicitPort = Boolean(options._portSet);
-  const flag = normalizeEnvName(options.environment);
+  const rawFlag = String(options.environment || "").trim();
+  const flag = normalizeEnvName(rawFlag);
 
-  let env;
+  if (rawFlag && !flag) {
+    throw new Error(`未知环境：${rawFlag}。可选值：${ENV_NAMES.join(" / ")}`);
+  }
+
+  let requestedEnv;
   if (explicitHost || explicitPort) {
     // Explicit connection target always wins (custom).
-    env = "custom";
-  } else if (flag && flag !== "auto") {
-    env = flag;
+    requestedEnv = "custom";
+  } else if (flag) {
+    // An explicit `auto` is a real one-shot override. It must not fall back to
+    // a persisted desktop/cli/custom selection.
+    requestedEnv = flag;
   } else {
-    env = currentEnvName(config);
-    if (env === "auto") {
-      const probe = options._desktopProbe || isDesktopReachable;
-      env = (await probe()) ? "desktop" : "cli";
-    }
+    requestedEnv = currentEnvName(config);
+  }
+
+  let env = requestedEnv;
+  if (env === "auto") {
+    const probe = options._desktopProbe || isDesktopReachable;
+    env = (await probe()) ? "desktop" : "cli";
   }
 
   let host;

package/lib/server.js

@@ -275,10 +275,17 @@ function buildStartupFailureHint(logPath) {
   return `详细日志：${logPath}`;
 }
 
+function buildAutoStartMessage(options) {
+  const url = baseUrlFor(options.host, options.port);
+  const dataRootLabel = options.environment === "cli" ? "CLI 独立数据目录" : "桌面端数据目录";
+  return `BiliSum 服务未在 ${url} 运行，正在用 ${dataRootLabel} 后台启动...`;
+}
+
 /**
- * Make sure a BiliSum service is reachable. If none is running, start one
- * headlessly sharing the desktop data root. When `accessToken` is known it is
- * injected into the spawned service so CLI and service always agree.
+ * Make sure a BiliSum service is reachable. If none is running, start a local
+ * service for the desktop/cli environments. A custom target is connection-only
+ * and is never replaced with an unrelated local process. When `accessToken` is
+ * known it is injected into the spawned service so CLI and service always agree.
  * Returns { started, payload }.
  */
 async function ensureService(options, { startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT_MS, log = console.error, accessToken = null } = {}) {
@@ -287,7 +294,13 @@ async function ensureService(options, { startupTimeoutMs = DEFAULT_STARTUP_TIMEO
     return { started: false, payload: await health(url) };
   }
 
-  log(`BiliSum 服务未在 ${url} 运行，正在用桌面端数据目录后台启动...`);
+  if (options.environment === "custom") {
+    throw new Error(
+      `无法连接自定义 BiliSum 服务（${url}）。请确认服务已启动，并检查 --host/--port 配置。`,
+    );
+  }
+
+  log(buildAutoStartMessage(options));
   const { child, logPath } = spawnService(options, { background: true, accessToken });
   const controller = new AbortController();
   const earlyExit = new Promise((resolve) => {
@@ -396,4 +409,5 @@ module.exports = {
   cliServiceLogPath,
   readServiceSettings,
   assertSpawnablePort,
+  buildAutoStartMessage,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bilisum",
-  "version": "1.20.0-alpha.3",
+  "version": "1.20.0-alpha.4",
   "description": "BiliSum CLI: control the installed BiliSum app, or run standalone with its own runtime.",
   "bin": {
     "bilisum": "bin/bilisum.js"

package/runtime/VERSION

@@ -1 +1 @@
-1.20.0-alpha.3
+1.20.0-alpha.4

package/runtime/apps/service/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "video-sum-service"
-version = "1.20.0-alpha.3"
+version = "1.20.0-alpha.4"
 description = "Local backend service for the video summarizer."
 requires-python = ">=3.12"
 dependencies = [

package/runtime/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "video-sum-core"
-version = "1.20.0-alpha.3"
+version = "1.20.0-alpha.4"
 description = "Core domain logic for the local video summarizer."
 requires-python = ">=3.12"
 dependencies = [

package/runtime/packages/infra/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "video-sum-infra"
-version = "1.20.0-alpha.3"
+version = "1.20.0-alpha.4"
 description = "Infrastructure layer for the local video summarizer."
 requires-python = ">=3.12"
 dependencies = [