bb-sync 1.10.0__tar.gz → 2.1.0__tar.gz

{bb_sync-1.10.0 → bb_sync-2.1.0}/.github/workflows/ci.yml

@@ -76,11 +76,11 @@ jobs:
           bb-sync --version
           # 注意：doctor 的诊断输出走 stderr（stdout 只留给 --json 的结构化结果），
           # 因此必须用 2>&1 才能把体检结果落进文件供 grep 断言。
-          # 容器里没有 Node/浏览器，doctor 会报缺项（预期，退出码非 0），只断言基础项
-          bb-sync doctor > doctor.txt 2>&1 || true
+          # 容器里没有浏览器，doctor 会报缺项（预期，退出码非 0），只断言基础项。
+          # 网络项探的是校园站点 bb.cuhk.edu.cn（校外需要 VPN），CI 上不作要求，故跳过。
+          bb-sync doctor --skip-network > doctor.txt 2>&1 || true
           grep -q "✓.*Python" doctor.txt
           grep -q "✓.*git" doctor.txt
-          grep -q "✓.*网络" doctor.txt
           # CLI 结构断言：无参数出帮助且退出码 0
           bb-sync >/dev/null
           test $? -eq 0
@@ -91,7 +91,7 @@ jobs:
           bb-sync definitely-not-a-command >/dev/null 2>&1 || rc=$?
           test "$rc" -eq 2
           # --json 的 JSON 必须落在 stdout 且可被解析（诊断走 stderr 不污染）
-          bb-sync --json doctor 2>/dev/null | python -c "import json,sys; json.load(sys.stdin)"
+          bb-sync --json doctor --skip-network 2>/dev/null | python -c "import json,sys; json.load(sys.stdin)"
 
   # 分支保护要求状态检查名为 `quality`；矩阵任务改名后由这个聚合门禁继续提供。
   quality:

{bb_sync-1.10.0 → bb_sync-2.1.0}/AGENTS.md

@@ -13,7 +13,8 @@
   PowerShell 与 zsh / bash。
 - **技术栈**：Python ≥3.11；Typer + Click（CLI）、pydantic v2（配置）、PyYAML、rich（输出）、
   keyring（凭据）、Playwright（浏览器自动化）。
-- **浏览器后端**：Steel——本地 Node ≥22 服务，通过 CDP 接入，Chrome profile 持久化登录态。
+- **浏览器后端**：直接驱动本机已装的 Chrome / Edge——分离进程 + CDP + 持久 profile，
+  不引入 Node / npm 等额外运行时（也不要为此加回任何需要联网下载的浏览器依赖）。
 - **打包**：hatchling，`src/` 布局，入口 `bb-sync = bb_sync.cli:main`。
 - **语言**：代码注释、docstring、提交信息、用户文档一律中文。安装与路径示例同时覆盖
   Windows PowerShell 和 macOS zsh / bash。
@@ -26,10 +27,10 @@
 | `src/bb_sync/context.py` | 全局 Context（`--json/--quiet/--verbose/--config`），惰性导入 |
 | `src/bb_sync/paths.py` | `BB_SYNC_HOME`（默认 `~/.bb-sync`）与配置文件查找 |
 | `src/bb_sync/creds.py` | keyring 凭据读写 |
-| `src/bb_sync/commands/` | 子命令：run / doctor / config / auth / course |
+| `src/bb_sync/commands/` | 子命令：run / due / doctor / config / auth / course / browser |
 | `src/bb_sync/core/` | config（分层加载）、config_store（行级 YAML 编辑）、service（同步编排）、doctor、output（Console）、errors（退出码） |
 | `src/bb_sync/blackboard/` | login（ADFS SSO）、scraper（列表 / 内容抓取）、downloader、models |
-| `src/bb_sync/browser/steel.py` | Steel 后端定位 / 安装 / 启动、CDP 会话、持久 profile |
+| `src/bb_sync/browser/launcher.py` | 本机浏览器探测 / 分离启动 / CDP 接入、持久 profile |
 | `tests/` | 全部离线：`test_units.py`（纯逻辑）+ `test_cli_e2e.py`（进程内 CLI 契约） |
 | `scripts/debug_*.py` | 手工调试脚本，会真实登录 / 访问站点；不属于测试，不要在 CI 或非必要时运行 |
 
@@ -47,9 +48,9 @@ uv run bb-sync doctor      # 环境体检（触网；诊断走 stderr）
 ```
 
 以上命令在 Windows PowerShell 与 macOS zsh / bash 中相同。macOS 前置依赖可用
-`brew install git node uv` 安装。
+`brew install git uv` 安装。
 
-只有真实运行 `run` / `course list` / `doctor`（未加 `--skip-network`）才需要 Node ≥22、
+只有真实运行 `run` / `course list` / `doctor`（未加 `--skip-network`）才需要本机的
 Chrome 或 Edge 和真实凭据；测试与质量检查完全离线。
 
 ### 提交前质量门禁（改动必须全绿）
@@ -68,6 +69,9 @@ uv run pyright
 ### 1. 输出通道：stdout 只放结果，stderr 只放诊断
 
 - 所有输出走 `core.output.Console`，**禁止直接 `print`**。
+- 诊断行需要强调时用 `console.line((文本, 样式), ...)` 并引用 `output.STYLE_*` 语义色板，
+  不要在调用点新造颜色名；**不要打开 Rich markup**——诊断里到处是 `[new]`、`[作业]`
+  这类方括号文本，会被当成标签。着色在非 TTY、`NO_COLOR`、`--json` 下自动关闭。
 - `--json` 时 stdout 有且仅有一个 JSON 文档；出错时 stdout 保持为空，错误走 stderr。
 - 新增命令或字段时，同步更新 `docs/scripting.md` 的 JSON 结构表与对应测试。
 
@@ -90,17 +94,29 @@ CLI 参数 > `BB_SYNC_<KEY>` 环境变量 > config.yaml > 内置默认。
 `config set/unset` 通过 `core/config_store.py` 做**行级编辑**，必须保留注释与未知键；
 不要改成整份 YAML 重写。路径常量在 import 时快照，测试靠 monkeypatch 覆盖。
 
-### 5. Steel 后端锚定快照
+### 5. 浏览器后端：分离进程 + 自有 profile
 
-`browser/steel.py` 的 `STEEL_REF` 固定到验证过的 commit，不追随上游 `main`；
-升级方式 = 改 `STEEL_REF` 并在 `CHANGELOG.md` 记录。
-Steel 安装目录只能是 `BB_SYNC_HOME/.steel`，任何情况下不读写用户家目录的 `~/.steel`。
+浏览器就是用户机器上的 Chrome / Edge，由 `browser/launcher.py` 以
+`--remote-debugging-port=0` 拉起，Playwright 只当 CDP 客户端。四条不能破的约束：
+
+- **跑完自动关**：默认命令结束（成功或失败）就关掉浏览器，不留后台进程。
+  `browser_session` 的 finally 负责收尾，`--keep-open` 才保留实例供手动过 MFA
+  或连续多次运行——不要在命令里留下没人管的浏览器。
+- **分离**：进程独立于 CLI 存活（Windows 用 `CREATE_NO_WINDOW|CREATE_NEW_PROCESS_GROUP`，
+  POSIX 用 `start_new_session`），命令跑到一半终端被关掉也不会把它带走，
+  `--keep-open` 保留下来的实例下次运行直接复用。
+- **端口自发现**：只认浏览器自己写下的 `DevToolsActivePort`，不要改成固定端口或自建注册表。
+- **profile 隔离**：`--user-data-dir` 只能是 `BB_SYNC_HOME/.browser-profile/<chrome|edge>`，
+  任何情况下不读不写用户日常使用的浏览器 profile。
+- **关闭方式**：只能走 CDP 的 `Browser.close`（`stop_browser`），不要按 PID 杀进程——
+  记录下来的 PID 可能已被系统回收。
 
 ## 测试要求
 
 - 默认测试套件必须离线：不登录、不下载、不起浏览器、不碰真实钥匙串。
-  `tests/conftest.py` 自动隔离 `BB_SYNC_HOME`、CWD、keyring 与 Steel 路径——
-  新测试直接依赖既有 fixture（`cli`、`config_file` 等），不要连接真实环境。
+  `tests/conftest.py` 自动隔离 `BB_SYNC_HOME`、CWD、keyring 与浏览器 profile 路径——
+  新测试直接依赖既有 fixture（`cli`、`config_file` 等），不要连接真实环境，
+  更不要在测试里真的拉起浏览器进程。
 - 新行为要带测试：纯逻辑进 `tests/test_units.py`，CLI 契约 / 退出码 / 输出分流进 `tests/test_cli_e2e.py`。
 - 真实站点逻辑（登录、抓取、下载）无法离线覆盖时，在提交信息或 PR 里写清可重复的手工验证步骤。
 
@@ -126,5 +142,7 @@ Steel 安装目录只能是 `BB_SYNC_HOME/.steel`，任何情况下不读写用
 - GitHub Actions 的 run 默认 `set -e`，断言非零退出码需用 `|| true` 兜住（见 `ci.yml` 注释）。
 - Windows 与 macOS 是主要目标平台，CI 同时跑 Ubuntu、macOS 与 Windows；路径、后台进程和
   浏览器探测相关改动两个平台都要考虑。
-- 首次准备 Steel 需从 GitHub / npm 拉依赖，国内网络慢时可临时用代理或镜像，不要写永久全局配置。
+- 浏览器后端不需要任何联网安装步骤；如果哪天又引入需要下载的组件，先想清楚国内网络下的代价。
+- 关闭后台浏览器只能走 CDP（`browser stop`）；直接 kill 浏览器进程会留下失效的
+  `DevToolsActivePort`，虽然下次启动会清掉，但 profile 可能没落盘。
 - 下载目录默认 `~/courses`，课程资料有版权；禁止提交或外传 `courses/`、`.workbuddy/` 内容。

{bb_sync-1.10.0 → bb_sync-2.1.0}/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.1.0] — 2026-10-31
+
+### 新增
+
+- `bb-sync run` 在「汇总」之后新增「新下载明细」，逐行列出本轮真正新落盘的文件
+  及其课程（相对课程目录的路径，作业带 `hwN/`），例如
+  `[new] CSC5010 | assignments/hw2/report.pdf`；没有新文件时不打印。`--json run`
+  同步增加 `files` 数组（`course` / `category` / `name` / `path`，其中 `path` 为
+  绝对路径），脚本可以直接取用。
+- 诊断输出改用语义色板：章节标题加粗、课程代码与 `[due]` / `[new]` 前缀青色、
+  新下载绿色、dry-run 与待办黄色、逾期红色、测验 / 考试徽标紫色、关键数字加粗，
+  正文从淡灰色恢复为终端默认前景色。颜色只在 `core/output.py` 定义一处；新增
+  `Console.line((文本, 样式), ...)` 按片段上色，不启用 Rich markup——诊断里的
+  方括号文本（`[new]`、`[作业]`）不会被误判成标签。
+- 着色随终端能力自动开关：输出被重定向、终端不支持颜色、设置 `NO_COLOR`
+  （任意非空值）或 `--json` 时都不输出转义序列，stdout 的 JSON 保持纯净。
+
+## [2.0.0] — 2026-10-14
+
+### 变更（破坏性）
+
+- **移除 Steel 浏览器后端，改用本机已装的 Chrome / Edge**（没有 Chrome 时自动回退
+  Edge），通过 CDP 驱动。不再需要 Node.js / npm，首次运行也不再从 GitHub 下载
+  约 90 MB 源码再跑 `npm install`——此前首次准备要几分钟、安装目录约 700 MB，
+  现在这些全部省掉，且不再依赖 github.com 可达。
+- 浏览器以**分离进程**运行——独立于 CLI 存活，命令跑到一半关掉终端也不会被带走——
+  但**跑完会自动关闭**，成功或失败都不留后台进程。保留状态下的冷启动 0.3 秒、
+  复用 0.01 秒（本机实测）。
+- **登录态位置变更**：profile 改存 `~/.bb-sync/.browser-profile/<chrome|edge>`，
+  登录态仍跨次运行保留；旧目录 `steel-chrome` 不再使用，升级后需要重新登录一次。
+- `bb-sync doctor` 去掉 Node.js / npm 两项（现在只依赖浏览器），网络项改为探测
+  Blackboard 站点本身——原来探 github.com 只是为了下载 Steel。
+- 旧版 `~/.bb-sync/.steel` 目录如仍存在，`bb-sync doctor` 会提示手动删除以释放空间。
+
+### 新增
+
+- `--keep-open`（`run` / `due` / `course list`）：跑完保留后台浏览器，供手动过 MFA、
+  连续多次运行或调试；配套 `bb-sync browser status` 查看状态、`bb-sync browser stop`
+  关闭（登录态保留在 profile，下次同步会自动重启）。
+- 抹掉 `navigator.webdriver`：浏览器一旦开启远程调试端口，这个值就是 true，
+  站点常据此判定「被自动化控制」；现在通过 init script 处理，与旧后端的反检测
+  能力保持对齐。
+
+### 测试
+
+- 删除 Steel 部署 / 回滚 / 锚点相关用例，新增浏览器探测、启动参数、端口文件解析、
+  实例复用与显示模式切换、CDP 关闭等用例；`doctor` 的检查项回归防线同步更新。
+
 ## [1.10.0] — 2026-10-14
 
 ### 新增

{bb_sync-1.10.0 → bb_sync-2.1.0}/CONTRIBUTING.md

@@ -9,9 +9,9 @@
 - Python 3.11 或更高版本；
 - [uv](https://docs.astral.sh/uv/)；
 - Git；
-- Node.js 22+ 与 npm
+- Chrome 或 Edge（只有真实跑 `run` / `course list` 时才用到）
 
-macOS 可用 `brew install git node uv`；Windows 可按 README 用 `winget` 安装。
+macOS 可用 `brew install git uv`；Windows 可按 README 用 `winget` 安装。
 
 初始化并安装开发依赖：
 
@@ -54,7 +54,7 @@ uv run pyright
 - pytest；
 - 干净容器中的安装冒烟测试。
 
-启动 Steel、登录 Blackboard 和真实下载不属于默认离线测试范围。修改相关逻辑时，请在本地补充可重复的手工验证步骤。
+启动浏览器、登录 Blackboard 和真实下载不属于默认离线测试范围。修改相关逻辑时，请在本地补充可重复的手工验证步骤。
 
 ## 提交习惯
 

{bb_sync-1.10.0 → bb_sync-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bb-sync
-Version: 1.10.0
+Version: 2.1.0
 Summary: 港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办
 Project-URL: Homepage, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 Project-URL: Repository, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
@@ -135,7 +135,7 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 ## 安装
 
-需要 Git、Node.js 22+（含 npm）、uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置。
+需要 uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置，Windows 自带的 Edge 直接可用。
 
 ### Windows
 
@@ -143,10 +143,11 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 ```powershell
 winget install --id Git.Git -e
-winget install --id OpenJS.NodeJS.LTS -e
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
+（Git 只在「从 GitHub 安装」时需要，走 PyPI 安装可以跳过。）
+
 Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
 
 ### macOS
@@ -154,7 +155,7 @@ Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
 推荐先安装 [Homebrew](https://brew.sh/)，再执行：
 
 ```bash
-brew install git node uv
+brew install git uv
 brew install --cask google-chrome
 ```
 
@@ -175,7 +176,7 @@ bb-sync doctor
 uv tool install git+https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 ```
 
-`bb-sync doctor` 用于检查环境；刚安装时凭据或浏览器后端显示“未配置”是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
+`bb-sync doctor` 用于检查环境；刚安装时凭据显示“未配置”、浏览器后端显示“未运行”都是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
 
 ## 首次使用
 
@@ -193,12 +194,16 @@ bb-sync auth login
 bb-sync run --headed
 ```
 
-首次运行会自动准备浏览器后端，可能需要几分钟。保持网络连接，不要提前关闭终端。之后同步直接运行：
+这条命令会用你机器上的 Chrome（没有则用 Edge）打开一个窗口，登录一次即可。之后同步直接运行：
 
 ```bash
 bb-sync run
 ```
 
+浏览器默认在**后台无窗口**运行，**跑完自动关闭**，不会在你机器上留下进程。登录态存在 `~/.bb-sync/.browser-profile/` 下、跨次运行保留，所以不必每次登录。
+
+需要把窗口留在屏幕上时（手动过 MFA、或想连续跑几条命令）加 `--keep-open`，之后再 `bb-sync browser stop` 关闭。
+
 ## 文件位置
 
 默认下载到用户主目录下的 `courses`：
@@ -230,12 +235,15 @@ Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更
 | `bb-sync run --headed` | 显示浏览器，适合首次登录或 MFA |
 | `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用 |
 | `bb-sync run --dry-run` | 预览下载和待办，不写文件 |
+| `bb-sync run --keep-open` | 跑完保留后台浏览器（手动过 MFA / 连着跑多条命令） |
 | `bb-sync due` | 扫描全部课程主页的 Due / To Do 与公告测验、考试，生成 `due.md` |
 | `bb-sync due --course CSC5010` | 只整理指定课程的待办 |
 | `bb-sync course list` | 列出账号下的课程 |
 | `bb-sync auth login` / `logout` / `status` | 录入、删除、查看已保存的凭据 |
 | `bb-sync config show` | 显示配置文件内容 |
 | `bb-sync config set <键> <值>` | 修改配置；另有 `get` / `unset` / `edit` / `path` / `init` |
+| `bb-sync browser status` | 查看后台浏览器是否在运行（`--keep-open` 留下的实例） |
+| `bb-sync browser stop` | 关闭后台浏览器（登录态保留） |
 | `bb-sync doctor` | 检查环境是否就绪 |
 | `bb-sync --help` | 查看完整帮助 |
 
@@ -243,7 +251,7 @@ Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更
 
 - **`bb-sync` 找不到**：重开终端，或执行 `uv tool update-shell`。
 - **环境检查不通过**：按 `bb-sync doctor` 的提示安装或配置缺失项。
-- **第一次运行很慢**：首次需要准备浏览器后端，耐心等待。
+- **想留住浏览器窗口**：默认跑完会自动关；加 `--keep-open` 才会保留，之后用 `bb-sync browser status` 看状态、`bb-sync browser stop` 关闭（不影响登录态）。
 - **登录失败或需要 MFA**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
 - **更换密码**：重新运行 `bb-sync auth login`。
 

{bb_sync-1.10.0 → bb_sync-2.1.0}/README.md

@@ -84,7 +84,7 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 ## 安装
 
-需要 Git、Node.js 22+（含 npm）、uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置。
+需要 uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置，Windows 自带的 Edge 直接可用。
 
 ### Windows
 
@@ -92,10 +92,11 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 ```powershell
 winget install --id Git.Git -e
-winget install --id OpenJS.NodeJS.LTS -e
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
+（Git 只在「从 GitHub 安装」时需要，走 PyPI 安装可以跳过。）
+
 Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
 
 ### macOS
@@ -103,7 +104,7 @@ Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
 推荐先安装 [Homebrew](https://brew.sh/)，再执行：
 
 ```bash
-brew install git node uv
+brew install git uv
 brew install --cask google-chrome
 ```
 
@@ -124,7 +125,7 @@ bb-sync doctor
 uv tool install git+https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 ```
 
-`bb-sync doctor` 用于检查环境；刚安装时凭据或浏览器后端显示“未配置”是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
+`bb-sync doctor` 用于检查环境；刚安装时凭据显示“未配置”、浏览器后端显示“未运行”都是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
 
 ## 首次使用
 
@@ -142,12 +143,16 @@ bb-sync auth login
 bb-sync run --headed
 ```
 
-首次运行会自动准备浏览器后端，可能需要几分钟。保持网络连接，不要提前关闭终端。之后同步直接运行：
+这条命令会用你机器上的 Chrome（没有则用 Edge）打开一个窗口，登录一次即可。之后同步直接运行：
 
 ```bash
 bb-sync run
 ```
 
+浏览器默认在**后台无窗口**运行，**跑完自动关闭**，不会在你机器上留下进程。登录态存在 `~/.bb-sync/.browser-profile/` 下、跨次运行保留，所以不必每次登录。
+
+需要把窗口留在屏幕上时（手动过 MFA、或想连续跑几条命令）加 `--keep-open`，之后再 `bb-sync browser stop` 关闭。
+
 ## 文件位置
 
 默认下载到用户主目录下的 `courses`：
@@ -179,12 +184,15 @@ Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更
 | `bb-sync run --headed` | 显示浏览器，适合首次登录或 MFA |
 | `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用 |
 | `bb-sync run --dry-run` | 预览下载和待办，不写文件 |
+| `bb-sync run --keep-open` | 跑完保留后台浏览器（手动过 MFA / 连着跑多条命令） |
 | `bb-sync due` | 扫描全部课程主页的 Due / To Do 与公告测验、考试，生成 `due.md` |
 | `bb-sync due --course CSC5010` | 只整理指定课程的待办 |
 | `bb-sync course list` | 列出账号下的课程 |
 | `bb-sync auth login` / `logout` / `status` | 录入、删除、查看已保存的凭据 |
 | `bb-sync config show` | 显示配置文件内容 |
 | `bb-sync config set <键> <值>` | 修改配置；另有 `get` / `unset` / `edit` / `path` / `init` |
+| `bb-sync browser status` | 查看后台浏览器是否在运行（`--keep-open` 留下的实例） |
+| `bb-sync browser stop` | 关闭后台浏览器（登录态保留） |
 | `bb-sync doctor` | 检查环境是否就绪 |
 | `bb-sync --help` | 查看完整帮助 |
 
@@ -192,7 +200,7 @@ Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更
 
 - **`bb-sync` 找不到**：重开终端，或执行 `uv tool update-shell`。
 - **环境检查不通过**：按 `bb-sync doctor` 的提示安装或配置缺失项。
-- **第一次运行很慢**：首次需要准备浏览器后端，耐心等待。
+- **想留住浏览器窗口**：默认跑完会自动关；加 `--keep-open` 才会保留，之后用 `bb-sync browser status` 看状态、`bb-sync browser stop` 关闭（不影响登录态）。
 - **登录失败或需要 MFA**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
 - **更换密码**：重新运行 `bb-sync auth login`。
 

{bb_sync-1.10.0 → bb_sync-2.1.0}/docs/scripting.md

@@ -12,6 +12,10 @@ bb-sync 按 Unix CLI 惯例严格分流输出：**结果走 stdout，诊断走 s
 
 > 自动更新检查的提示也走 stderr，不会污染 stdout；`--quiet` 下会跳过检查。
 
+彩色只在交互式终端里启用：stdout 被重定向、终端不支持颜色、设置了 `NO_COLOR`
+（任意非空值）或加了 `--json` 时都会自动关闭。所以 `bb-sync run 2>&1 | tee log.txt`
+这类管道里拿到的是纯文本，stdout 的 JSON 更是永远不含转义序列。
+
 ## `--json`：机器可读输出
 
 `--json` 是**全局选项**，位置在子命令之前：
@@ -35,7 +39,7 @@ bb-sync --json doctor       | jq '.ok'
 | 命令 | stdout 的 JSON |
 | --- | --- |
 | `course list` | 数组：`[{"id","code","title","folder"}, ...]` |
-| `run` | 对象：`{"downloaded","exists","would_download","empty","failed","courses"}` |
+| `run` | 对象：`{"downloaded","exists","would_download","empty","failed","courses","files"}`；`files` 是本次**真正新落盘**的文件（dry-run 时为空），元素为 `{"course","category","name","path"}`——`name` 相对课程目录、`path` 为绝对路径 |
 | `due` | 对象：`{"path","total","failed","announcement_failed","courses","items"}`；`items` 含课程、标题、类型（`task` / `quiz` / `exam`）与 ISO 日期 |
 | `doctor` | 对象：`{"ok": bool, "checks": [{"label","ok","detail","hint","required"}]}` |
 | `doctor --list` | 对象：`{"checks": ["python","git", ...]}` |
@@ -72,7 +76,7 @@ fi
 | 4 | 配置文件问题 |
 | 5 | 网络 / 代理 / 下载失败 |
 | 6 | 目标不存在（课程、配置键等） |
-| 7 | 环境依赖缺失（Node / 浏览器 / Steel） |
+| 7 | 环境依赖缺失（未检测到浏览器、浏览器启动失败等） |
 | 8 | 用户中断 |
 
 > 未捕获的意外异常统一归为 1，并会把堆栈打到 stderr。
@@ -85,7 +89,7 @@ case $? in
     0) echo "同步完成" ;;
     3) echo "需要先 bb-sync auth login" >&2 ;;
     5) echo "网络/代理异常，检查 Clash 是否开启" >&2 ;;
-    7) echo "缺 Node/浏览器，先跑 bb-sync doctor" >&2 ;;
+    7) echo "缺浏览器，先跑 bb-sync doctor" >&2 ;;
     *) echo "其它错误" >&2 ;;
 esac
 ```

{bb_sync-1.10.0 → bb_sync-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bb-sync"
-version = "1.10.0"
+version = "2.1.0"
 description = "港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办"
 readme = "README.md"
 license = { file = "LICENSE" }

{bb_sync-1.10.0 → bb_sync-2.1.0}/scripts/debug_course.py

@@ -14,7 +14,7 @@ from playwright.sync_api import sync_playwright
 
 from bb_sync.blackboard.login import ensure_login
 from bb_sync.blackboard.models import BASE
-from bb_sync.browser import steel
+from bb_sync.browser import launcher
 from bb_sync.core.output import Console
 from bb_sync.paths import BB_SYNC_HOME
 
@@ -23,10 +23,9 @@ COURSE_ID = sys.argv[1] if len(sys.argv) > 1 else "_18482_1"  # CSC5010
 
 
 def main() -> None:
-    steel.ensure_server(console)
-    session = steel.create_session(console=console)
+    session = launcher.ensure_browser(console)
     with sync_playwright() as p:
-        browser, ctx, page = steel.connect(p, session)
+        browser, ctx, page = launcher.connect(p, session)
         ensure_login(page, console)
 
         for label, url in [
@@ -72,9 +71,7 @@ def main() -> None:
             for link in interesting[:20]:
                 console.log(f"        {link[:150]}")
 
-        ctx.close()
-        browser.close()
-    steel.release_session(session, console)
+        # 调试脚本故意不关浏览器（方便接着看现场）；用完 bb-sync browser stop 关闭
 
 
 if __name__ == "__main__":

{bb_sync-1.10.0 → bb_sync-2.1.0}/scripts/debug_courses.py

@@ -13,7 +13,7 @@ from playwright.sync_api import sync_playwright
 
 from bb_sync.blackboard.login import ensure_login
 from bb_sync.blackboard.models import BASE
-from bb_sync.browser import steel
+from bb_sync.browser import launcher
 from bb_sync.core.output import Console
 from bb_sync.paths import BB_SYNC_HOME
 
@@ -22,10 +22,9 @@ PORTAL = f"{BASE}/webapps/portal/execute/tabs/tabAction?tab_tab_group_id=_1_1"
 
 
 def main() -> None:
-    steel.ensure_server(console)
-    session = steel.create_session(console=console)
+    session = launcher.ensure_browser(console)
     with sync_playwright() as p:
-        browser, ctx, page = steel.connect(p, session)
+        browser, ctx, page = launcher.connect(p, session)
         ensure_login(page, console)
         console.success("已登录")
 
@@ -69,9 +68,7 @@ def main() -> None:
         for link in links:
             console.log(f"    {link[:140]}")
 
-        ctx.close()
-        browser.close()
-    steel.release_session(session, console)
+        # 调试脚本故意不关浏览器（方便接着看现场）；用完 bb-sync browser stop 关闭
 
 
 if __name__ == "__main__":

{bb_sync-1.10.0 → bb_sync-2.1.0}/scripts/debug_login.py

@@ -12,7 +12,7 @@ import re
 from playwright.sync_api import sync_playwright
 
 from bb_sync.blackboard.models import LOGIN_URL
-from bb_sync.browser import steel
+from bb_sync.browser import launcher
 from bb_sync.core.output import Console
 from bb_sync.creds import load_credentials
 from bb_sync.paths import BB_SYNC_HOME
@@ -45,10 +45,9 @@ def dump(page, tag: str) -> None:
 
 
 def main() -> None:
-    steel.ensure_server(console)
-    session = steel.create_session(console=console)
+    session = launcher.ensure_browser(console)
     with sync_playwright() as p:
-        browser, ctx, page = steel.connect(p, session)
+        browser, ctx, page = launcher.connect(p, session)
         page.goto(LOGIN_URL, wait_until="domcontentloaded")
         dump(page, "01_bb_login")
 
@@ -70,9 +69,7 @@ def main() -> None:
 
         page.wait_for_timeout(5000)
         dump(page, "07_final")
-        ctx.close()
-        browser.close()
-    steel.release_session(session, console)
+        # 调试脚本故意不关浏览器（方便接着看现场）；用完 bb-sync browser stop 关闭
 
 
 if __name__ == "__main__":

{bb_sync-1.10.0 → bb_sync-2.1.0}/src/bb_sync/__init__.py

@@ -5,7 +5,7 @@
 - :mod:`bb_sync.cli`            Typer 命令行入口
 - :mod:`bb_sync.core`           配置、输出、异常等基础设施
 - :mod:`bb_sync.blackboard`     Blackboard 站点交互（登录 / 抓取 / 下载）
-- :mod:`bb_sync.browser`        Steel 浏览器后端
+- :mod:`bb_sync.browser`        本机浏览器后端（分离进程 + CDP）
 """
 
 from __future__ import annotations

{bb_sync-1.10.0 → bb_sync-2.1.0}/src/bb_sync/blackboard/downloader.py

@@ -192,8 +192,11 @@ def _content_length(headers) -> int | None:
         return None
 
 
-def _category_dir(course_dir: Path, item: FileItem) -> Path:
-    """条目落盘目录；作业按 hwN 归档，对齐已有目录习惯。"""
+def category_dir(course_dir: Path, item: FileItem) -> Path:
+    """条目落盘目录；作业按 hwN 归档，对齐已有目录习惯。
+
+    对外的唯一含义是「这个条目会写到哪里」，汇总明细与真实写入共用它。
+    """
     cat_dir = course_dir / item.category
     if item.category == "assignments" and item.name:
         m = HW_NUM.search(item.name)
@@ -202,7 +205,7 @@ def _category_dir(course_dir: Path, item: FileItem) -> Path:
     return cat_dir
 
 
-def _relpath(path: Path, course_dir: Path) -> str:
+def relative_path(path: Path, course_dir: Path) -> str:
     """相对课程目录的展示路径；跨盘等取不到相对路径时退回文件名。"""
     try:
         return str(path.relative_to(course_dir)).replace("\\", "/")
@@ -262,12 +265,12 @@ class DownloadSession:
 
         状态取值：``downloaded`` / ``exists`` / ``would-download`` / ``empty``。
         """
-        cat_dir = _category_dir(course_dir, item)
+        cat_dir = category_dir(course_dir, item)
         name, size = self.probe(item)
 
         already = _index_match(index, name, size)
         if already is not None:
-            return ("exists", _relpath(already, course_dir))
+            return ("exists", relative_path(already, course_dir))
         target = cat_dir / name
         if target.exists():
             return ("exists", target.name)
@@ -344,5 +347,7 @@ __all__ = [
     "SIZE_DEDUP_THRESHOLD",
     "SNIFF_BYTES",
     "build_index",
+    "category_dir",
+    "relative_path",
     "sniff_ext",
 ]

{bb_sync-1.10.0 → bb_sync-2.1.0}/src/bb_sync/blackboard/login.py

@@ -87,7 +87,8 @@ def do_login(page: Page, username: str, password: str) -> None:
         raise AuthError(
             f"登录失败（当前 URL: {_safe_url(page)}）：{detail}",
             f"已保存登录现场到 {home}（debug_login.png / debug_login.html）。"
-            "若页面停在 ADFS / MFA / 验证码，请用 bb-sync run --headed 手动完成；"
+            "若页面停在 ADFS / MFA / 验证码，请用 bb-sync run --headed --keep-open 手动完成"
+            "（--keep-open 让浏览器在命令结束后留在屏幕上）；"
             f"若怀疑是登录流程改版或 bb-sync 的问题，欢迎到 {ISSUES_URL} 提 issue，"
             "并附上 debug_login.html（以及上面这行 URL）。",
         ) from exc
@@ -161,7 +162,7 @@ def resolve_credentials(console: Console) -> Credentials:
 def ensure_login(page: Page, console: Console, *, headed: bool = False) -> None:
     """确保处于登录态（复用 profile → 静默登录 → 有头模式等人工过 MFA）。"""
     if is_logged_in(page):
-        console.log("[login] 已有有效登录态（复用 Steel profile）")
+        console.log("[login] 已有有效登录态（复用浏览器 profile）")
         return
 
     creds = resolve_credentials(console)

{bb_sync-1.10.0 → bb_sync-2.1.0}/src/bb_sync/blackboard/models.py

@@ -76,6 +76,24 @@ class DueItem:
         }
 
 
+@dataclass(frozen=True)
+class SavedFile:
+    """本次同步新落盘的一个文件。"""
+
+    course: str  # 课程代码；没有代码时退回课程标题
+    category: str  # lectures / assignments / tutorials / other
+    name: str  # 相对课程目录的路径，如 assignments/hw2/report.pdf
+    path: str = ""  # 绝对路径，便于脚本直接取用
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "course": self.course,
+            "category": self.category,
+            "name": self.name,
+            "path": self.path,
+        }
+
+
 @dataclass
 class SyncStats:
     """一次同步的统计结果。"""
@@ -86,6 +104,8 @@ class SyncStats:
     empty: int = 0
     failed: int = 0
     courses: list[str] = field(default_factory=list)
+    #: 本次真正新落盘的文件（不含已存在 / dry-run），供末尾明细与 --json 使用
+    files: list[SavedFile] = field(default_factory=list)
 
     def bump(self, status: str) -> None:
         key = status.replace("-", "_")
@@ -100,6 +120,7 @@ class SyncStats:
             "empty": self.empty,
             "failed": self.failed,
             "courses": self.courses,
+            "files": [saved.as_dict() for saved in self.files],
         }
 
 
@@ -139,5 +160,6 @@ __all__ = [
     "DueItem",
     "DueStats",
     "FileItem",
+    "SavedFile",
     "SyncStats",
 ]

bb_sync-2.1.0/src/bb_sync/browser/__init__.py

@@ -0,0 +1,5 @@
+"""浏览器后端：直接驱动本机 Chrome / Edge（分离进程 + CDP）。"""
+
+from __future__ import annotations
+
+__all__: list[str] = []