CLAUDE.md · diff
git:20261029.6a14ddd to git:20261029.b9bad61
9 added, 5 removed. Audit A to A.
# CLAUDE.md — bili-transcriber AI 协作规则
- B站音频本地转写桌面工具：yt-dlp 下载 → FFmpeg 转码 → 三引擎本地 GPU 转写 → SRT/TXT/Markdown。纯本地、数据不上传。当前 v0.1.44，测试 29 文件 / 525 passed。
+ B站音频本地转写桌面工具：yt-dlp 下载 → FFmpeg 转码 → 三引擎本地 GPU 转写 → SRT/TXT/Markdown。纯本地、数据不上传。当前 v0.1.45，测试 29 文件 / 544 passed。
## 速查命令
| 任务 | 命令 |
|---|---|
| 跑全量测试 | `.venv/Scripts/python.exe -m pytest tests/ -q` |
| 源码起 CLI | `.venv/Scripts/python.exe -m app.cli <参数>`（**不需要** `--cli`） |
| 源码起 MCP stdio | `python -m app.cli --mcp` |
| 源码起 MCP HTTP | `python -m app.cli --mcp-http [PORT]` |
| 自检 | `python -m app.cli --doctor [--json]` |
| 一键发布 | `.venv/Scripts/python.exe scripts/release.py`（`--wheel-only` / `--bin-only` / `--single-only` / `--setup-only`） |
| 上传 release | `python scripts/github_release_upload.py <tag> <assets...> --notes <md>` |
| 冻结包冒烟 | `dist/bili-transcriber/bili-transcriber.exe --cli --doctor`（exe 必须 `--cli`） |
Entry points（pyproject）：`bili-transcriber`=GUI / `bili-transcriber-cli`=CLI / `bili-transcriber-mcp`=MCP stdio。
- ## 架构速览（app/ 31 文件）
+ ## 架构速览（app/ 32 文件：28 顶层 + ui/4）
- **main.py** NiceGUI 三页签 UI；**pipeline.py** 单工作线程串行编排（状态机 queued→downloading→converting→transcribing→saving→done/failed）
- **cli.py / headless.py** 无头 CLI + Service 层；**mcp_server.py** MCP 11 工具（JSON-RPC stdio）；**mcp_http.py** Streamable HTTP（仅绑 127.0.0.1）
- **agent_setup.py** 8 客户端配置生成（workbuddy/dsh/codex/claude/cursor/vscode/tare/generic）
+ - **cookiebridge.py** 浏览器 Cookie 解密桥：Chrome 127+ 的 v20（应用绑定加密）只能由浏览器本体解，故复制最小 profile → 起无窗口临时实例 → stdlib WebSocket 走 CDP `Network.getAllCookies` 取明文 → 杀进程删目录
- 三引擎 transcriber/qwen_transcriber/sensevoice_transcriber，`load()` 均 double-checked locking
- 详细模块说明见 docs/technical-manual-zh.md（深入文档指针见文末表）
## 发布流程四大坑（违反必炸）
1. **沙箱钩子**：`scripts/release.py` 内已设 `CODEBUDDY_SAFE_DELETE_SANDBOX=0`。绕过脚本手动跑 PyInstaller 必须自己设，否则收尾 `os.remove` 被拦死、构建卡死退出码 1。
2. **版本三处同步**：release.py 自动 bump `pyproject.toml` / `build/installer.iss` / `app/__init__.py APP_VERSION`。手改版本必须三处一起改。
+ **文档版本号也自动递增**：`README.md` 与四份手册的头部声明必须保持可识别格式（中文含「对应」/ 英文含小写「matches」+ `**vX.Y.Z**`，且在文件前 20 行内），release.py 才会同步并生成快照；格式不对只打警告、快照会带过期头。
3. **snapshot_docs 滚动快照**：发布时生成 `docs/*-{ver}.md` 并删旧快照。**常驻文档（ai-integration.md、adversarial-review.md）不在快照列表，严禁当旧快照删除**（README 3 处 + 手册 2 处引用）。
4. **dist/build 清理**：旧产物移入待删目录（如 `dist/_trash_YYYYMMDD/`）而非 rm，避开 safe-delete 钩子。
## 质量基线与审查方法论
- - 全量 525 passed 是底线；任何改动后跑全量。
+ - 全量 544 passed 是底线；任何改动后跑全量。
- **测试全绿 ≠ 真机可用**：组装层（CLI 入口、HTTP 服务、冻结包）必须子进程级 e2e；render_cli 等文档片段的消费方是打包 exe，真机验证必须覆盖交付形态。
- 对抗性审查三视角（实现者/审查者/AI 使用方），工具闭环拿真实报错，清单兜底；历史清单在 docs/adversarial-review.md。
- 代码规范：配对操作同防（POST/DELETE 都要校验）；路径入盘必须 `resolve()`；空串 ≠ 默认值（set_settings 已统一守卫）；token 比较用 `hmac.compare_digest`。
- 中文注释、报错信息必须可行动（告诉用户下一步做什么，别裸抛 traceback）。
## 冻结版（exe）分发开关
`app/main.py` 入口分发：**exe 默认进 GUI，必须 `--cli` 才进 CLI**；源码 `python -m app.cli` 天然是 CLI、不需要该开关。改 `render_cli` / agent_setup 片段时，frozen 分支必须保留 `--cli`（第四轮曾误删，已用双向回归锁定：冻结版必含 / 源码版必不含）。
## 环境变量（代码实际读取）
| 变量 | 作用 |
|---|---|
| `BILI_DEVICE` / `BILI_COMPUTE_TYPE` | 覆盖设备/精度（auto/cuda/cpu） |
| `BILI_MCP_HTTP_TOKEN` | MCP HTTP Bearer token（未设则不校验） |
| `BILI_PORT` | 服务端口 |
| `BILI_TEST_IMPORTS` | 测试导入开关 |
+ | `BILI_FORCE_BROWSER` / `BILI_FORCE_NATIVE` / `BILI_NO_BROWSER` | 界面形态覆盖：强制浏览器 / 强制原生窗口 / 原生时不自动开浏览器 |
+ | `BILI_NO_TRAY` | `1` 不装托盘图标（真机冒烟用） |
| `CODEBUDDY_SAFE_DELETE_SANDBOX` | 构建沙箱钩子开关（见四大坑 #1） |
## 数据与配置位置
- - 设置：`data/settings.json`（output_dir / model_size / device / language / keep_audio / vad）
+ - 设置：`data/settings.json`（16 项，字段全表以 `app/store.py` 的 `DEFAULT_SETTINGS` 为准：输出/引擎/模型/设备/精度/语言/keep_audio/vad/讲义/Cookie/代理/workers/通道开关）
- 历史：`data/history.db`（SQLite，主键 media_id）
- 模型外置：`%LOCALAPPDATA%\Bili Note\models\`（安装版无写权限，走用户目录）
- 产物输出：默认 `data/settings.json` 的 output_dir（当前 `D:\个人用`）
## 大陆网络适配（改下载/模型逻辑前必读）
hf-mirror 镜像、SSL 证书自愈、CUDA pip 轮子注入；**urllib 客户端必须 `ProxyHandler({})`**——Clash 等系统代理会把 127.0.0.1 请求也代理出去导致本机回环挂死。
## 深入文档指针
| 文档 | 内容 |
|---|---|
- | [README.md](README.md) | 功能、33 参数、20 实例、概念图 |
+ | [README.md](README.md) | 功能、34 参数、20 实例、4 张概念图 |
| [docs/technical-manual-zh.md](docs/technical-manual-zh.md) | 架构与模块详解（中/英） |
| [docs/user-guide-zh.md](docs/user-guide-zh.md) | 用户手册（中/英） |
| [docs/ai-integration.md](docs/ai-integration.md) | CLI/MCP 参数、返回结构、8 客户端接入 |
| [docs/adversarial-review.md](docs/adversarial-review.md) | 五轮审查完整清单与方法论 |
| [docs/release-notes/](docs/release-notes/) | 各版本变更 |
| [.workbuddy/memory/MEMORY.md](.workbuddy/memory/MEMORY.md) | 项目长期笔记（会话记忆） |
<!-- neat-freak: initialized at 2026-10-29 -->