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

package/README.md

@@ -1,11 +1,123 @@
-# BiliSum
+# BiliSum CLI
 
-`bilisum` starts the local BiliSum browser service from npx.
+`bilisum` 是 BiliSum 的命令行控制面：**控制已安装的 BiliSum（桌面端 / 已运行的服务），或完全独立运行**（未安装桌面端也能用），让 Agent / 脚本做视频理解（转写 + 摘要）。
 
 ```bash
-npx bilisum
-npx bilisum start --port 3839
-npx bilisum doctor
+# 摘要一个视频（默认输出：元数据 + 总结内容，不含字幕）
+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
+
+# 总结 + 追加转写全文 / 只要转写
+bilisum summarize "https://www.bilibili.com/video/BV1xxxx" --with-transcript
+bilisum transcribe ./demo.mp4 --output transcript.txt
+
+# 多 P / 异步
+bilisum summarize "https://www.bilibili.com/video/BV1xxxx" --page 2
+bilisum summarize "https://www.bilibili.com/video/BV1xxxx" --all-pages --no-wait
+
+# 任务管理
+bilisum status <task-id> --json
+bilisum tasks --limit 10
+
+# 帮助（无参数执行也会显示 help，不会自动启动服务）
+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）+ 总结内容（`summarize` 为知识笔记，`brief` 为摘要卡片），**不含字幕**；加 `--with-transcript` 会追加转写全文。
+- **`json`**：完整任务对象（含 `result`，字幕在 `result.transcript_text`）。
+- **`transcript`**：仅转写全文（`bilisum transcribe` 的默认输出）。
+
+任务等待期间进度显示在 stderr（`[task_id]  12% [stage] 消息`），stdout 保持干净。
+
+## 它如何"控制现有程序"
+
+- 默认连接桌面端服务 `http://127.0.0.1:3838`，任务、结果、知识库都与桌面端**同一个数据库**。
+- 访问令牌自动获取：`--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` 覆盖。
+- 配置（LLM / ASR Key 等）跟随服务端设置，桌面端里配好了，CLI 直接用。
+
+## 服务不在线时
+
+`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 拉起的服务
 ```
 
-Python 3.12 is required. On first run, BiliSum creates a managed Python virtual environment under the user's local app data directory.
+**无任务自动关闭**：CLI 后台拉起的服务默认空闲 10 分钟（且无排队/运行中任务）自动退出，可用 `--idle-timeout <sec>` 或 `BILISUM_CLI_IDLE_TIMEOUT` 环境变量调整。该机制只作用于 CLI 自己拉起的服务（通过 `VIDEO_SUM_CLI_MANAGED` 标记），**桌面端启动的服务绝不会被自动关闭**。
+
+> 注意：桌面端自己运行的服务不受 `bilisum stop` 影响（没有 cli-runtime 记录时会提示）。
+
+## 安装
+
+```bash
+npm install -g bilisum          # 或 npx bilisum ...
+```
+
+包内**不包含 Python 运行时**（CLI 是纯客户端），首次使用要求机器上已有桌面版 BiliSum 或 Python 3.12。
+
+## 常用选项
+
+| 选项 | 说明 |
+|------|------|
+| `--host / --port` | 服务地址（默认 `127.0.0.1:3838`） |
+| `--data <path>` | 桌面端数据根（默认 `%LOCALAPPDATA%\bilisum`） |
+| `--token <token>` | 访问令牌（默认自动读桌面端 token） |
+| `--format json\|markdown\|transcript` | 输出格式，默认 markdown |
+| `--output <path> / -o` | 结果写入文件 |
+| `--with-transcript` | markdown 输出追加转写全文（默认不含字幕） |
+| `--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`，可用：
+
+```bash
+node "<安装目录>\resources\cli\bin\bilisum.js" summarize "https://..."
+```
+
+## 开发
+
+```bash
+npm test --prefix packages/npx   # node:test 单元测试
+npm run npx:test                 # 版本 + 单测 + npm pack 校验（根目录）
+```