bb-sync 1.9.0__tar.gz → 2.0.0__tar.gz

{bb_sync-1.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.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 和真实凭据；测试与质量检查完全离线。
 
 ### 提交前质量门禁（改动必须全绿）
@@ -90,17 +91,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 +139,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.9.0 → bb_sync-2.0.0}/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [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
+
+### 新增
+
+- `--help` / `-h` 与无参数帮助支持彩色输出：章节标题与 `Usage:` 加粗，
+  选项名、命令名用青色。颜色只在输出到终端时出现——管道或重定向时 Click 会
+  自动剥掉 ANSI，脚本里 grep 帮助内容不受影响。
+- `-h, --help` 与 `--version` 的说明文案本地化为中文。此前是 Click 硬编码的
+  `Show this message and exit.` / `Show the version and exit.`，与其余中文
+  说明不一致。
+
+### 变更
+
+- 子命令帮助不再走 Typer 自带的 Rich 面板，统一改用 Click 的 formatter。
+  那套面板在终端里其实并不上色，而且 Rich 会二次处理彩色转义序列（`\x1b`
+  被吃掉、只剩字面量 `[1m`）。换掉之后 `bb-sync --help` 不再导入 rich，
+  帮助路径也随之变快。
+
+### 测试
+
+- 新增彩色帮助的回归用例：管道下必须无 ANSI；伪终端下必须有 ANSI，且剥离
+  转义后与管道版本逐字一致（守住列对齐没被样式破坏）；`--help` 不得导入 rich；
+  `-h, --help` 的说明须为中文。
+
 ## [1.9.0] — 2026-10-14
 
 ### 变更

{bb_sync-1.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bb-sync
-Version: 1.9.0
+Version: 2.0.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.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.0}/docs/scripting.md

@@ -72,7 +72,7 @@ fi
 | 4 | 配置文件问题 |
 | 5 | 网络 / 代理 / 下载失败 |
 | 6 | 目标不存在（课程、配置键等） |
-| 7 | 环境依赖缺失（Node / 浏览器 / Steel） |
+| 7 | 环境依赖缺失（未检测到浏览器、浏览器启动失败等） |
 | 8 | 用户中断 |
 
 > 未捕获的意外异常统一归为 1，并会把堆栈打到 stderr。
@@ -85,7 +85,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.9.0 → bb_sync-2.0.0}/pyproject.toml

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

{bb_sync-1.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.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.9.0 → bb_sync-2.0.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-2.0.0/src/bb_sync/browser/__init__.py

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