分流对话 xiez0324-rgb/dsh-dual-bridge

分流对话 · dsh-dual-bridge

Plugins of Conversation Departure — 把「读项目」分流给免费的 DeepSeek 网页版，把「改代码」留给 Harness API。

DeepSeek Harness（DSH）侧边栏插件：把项目上下文打包成结构化 prompt → 复制到剪贴板 → 同屏打开 DeepSeek 网页版粘贴提问。

定位是「双入口分流」：读项目/答疑走网页版（免费），复杂推理/改码仍走 Harness API（计费）。

纯本地：不联网、不爬虫、不操控浏览器、不调用网页版任何接口，也不上传任何文件。

安装

⚠️ 必须先装 dsh-better-sidebar。 本插件的 UI 挂在它的侧边栏上；而 DSH 的 bundle 挂载只认 profile 的直接依赖（传递依赖会被装进 node_modules，但不会被挂载），所以只装本插件会出现「装好了但界面没变化」的静默失败。

一条命令装好（推荐）

dsh plugin add dsh-better-sidebar && dsh plugin add dsh-dual-bridge

从插件市场装：在市场（Discover）里先搜 dsh-better-sidebar 装上，再搜 dsh-dual-bridge。

从本仓库直装（不走 npm）

dsh plugin add dsh-better-sidebar && \
dsh plugin add git+https://github.com/xiez0324-rgb/dsh-dual-bridge.git

装完重启一次 dsh web（host 端路由要加载），刷新页面后侧边栏出现「⇄ 分流对话」Tab。

只装本插件忘了装前置时，host 日志会打印明确提示： [dsh-dual-bridge] 未检测到 dsh-better-sidebar 服务 …

版本要求：engines.dsh 为 >=0.2.1-rc.1 <0.3.0（dsh --version 可查）。

30 秒上手

1. 在 DSH 里打开一个会话（需要有工作区），侧边栏点「⇄ 分流对话」
2. 展开目录，勾选要问的文件（勾目录 = 整棵子树；默认什么都不选）
3. 点「📦 打包选中文件」→「📋 复制到剪贴板」
4. 点「🚀 同屏打开网页版」→ 在网页版输入框 Cmd/Ctrl+V 粘贴 → 提问
5. 需要改代码/复杂推理时，回 Harness 走 API

PDF/Word/PPT/Excel/RTF 先点「提取文字」，图片点「OCR 文字」——提取结果也会进剪贴板。
无法转文本的文件（视频/压缩包等）会自动打包到 ~/Desktop/dsh-pack-<时间戳>/，拖进网页版上传即可。

它解决什么问题

在 Harness 里读代码、解释项目、回答"这个功能怎么实现的"，每次都要消耗 API token。
这类上下文密集型任务其实是免费的网页版最擅长的。本插件负责把"上下文搬运"这半件事做到顺手：

① 扫描工作区 → 目录树勾选 → 设 token 预算 → 打包并复制 ② 一键同屏打开 DeepSeek 网页版（右侧并排窗口，不占用当前标签页） ③ Cmd/Ctrl + V 粘贴 → 提问（免费） ④ 需要改代码/复杂推理 → 回到 Harness 走 API

功能

| 能力 | 说明 |
| 项目扫描 | 解析 .gitignore + 内置 30+ 排除规则（node_modules、.git、build、__pycache__、.env …）；扫描上限可调（500 / 2000 / 10000 / 不限，默认 2000）并显式报告截断 |
| 目录树选择 | 可折叠；勾选目录 = 选中整棵子树（三态含半选）；默认不选任何文件；「全选 / 仅代码 / 全不选」 |
| 二进制可见 | PDF/Office/图片不出现"凭空消失"：目录标注「不可打包 N」，文件行置灰 |
| token 预算 | 按 1 token ≈ 4 字符估算；「超预算时」可选只提示 / 按预算截断（贪心填充，被丢文件逐条列出） |
| prompt 组装 | 项目结构树 + 逐文件代码块（语言标注、反引号自适应） |
| 附件声明（可选） | 勾选后把同目录下未包含的附件列进 prompt（上限 20 条），默认关闭 |
| 按需文本抽取 | 对单个 PDF/Office 文件点「抽取文本」，抽出的正文并入 prompt（见下方平台支持） |
| 同屏打开网页版 | 贴在屏幕右侧的独立窗口 + 自动聚焦；重复点击只聚焦、不刷新已有对话 |
| 复制到剪贴板 | 一步写入系统剪贴板 |

架构

┌──────────────────────────────┐ ┌──────────────────────────────────┐
│ 浏览器：侧边栏 UI │ │ DSH 的 Node 进程（host） │ │ lib/client.js │ fetch │ lib/index.js │ │ · 目录树 / 勾选 / token 预算 │ ─────▶ │ 本地路由（仅 127.0.0.1 可达） │ │ · 组装 prompt / 剪贴板 │ │ /dual-bridge/capabilities │ │ · 同屏窗口（window.open） │ │ /dual-bridge/extract │ │ │ │ /dual-bridge/ocr │ │ 读不到二进制原文、不能起进程 │ │ /dual-bridge/bundle │ └──────────────────────────────┘ │ /dual-bridge/reveal │ └──────────────────────────────────┘

| 设计点 | 原因 |
| UI / host 分离 | 浏览器侧读不到二进制原文（fs.read 只回文本），也不能启动子进程；解析与写文件必须落到 host |
| 能力探测 | UI 先问 /capabilities（PDF/Office/OCR 是否可用），只显示真正能用的按钮，杜绝「点了才报不支持」 |
| 纯函数内核 | 目录树、预算裁剪、OOXML/RTF 解析、OCR 引擎链都是无副作用函数，可单测（83 个测试） |
| 路径围栏 | host 端所有文件操作都校验「必须在本会话工作区内」；子进程一律 argv 数组，不拼 shell |
| 显式截断 | 扫描上限、读取上限、预算截断、超大文件全部明说，不静默少文件 |
| 失败降级 | 缺 poppler 就不显示 PDF 按钮；host 版本落后会提示重启，而不是行为错位 |
| 跨平台 | docx/pptx/xlsx/rtf 用内置 ZIP+XML 解析（不依赖 macOS textutil）；OCR 三级链 Vision → tesseract → 内置 WASM；reveal/zip 按平台分支 |

平台支持

| 能力 | macOS | Linux | Windows |
| 扫描 / 打包 / 复制 / 同屏打开 | ✅ | ✅ | ✅ |
| docx / pptx / xlsx / rtf 抽取 | ✅ 内置解析器 | ✅ 内置解析器 | ✅ 内置解析器 |
| 旧版二进制 .doc | ✅ textutil | ❌ 建议另存为 docx | ❌ 建议另存为 docx |
| PDF 抽取 | ✅ 需 poppler | ✅ 需 poppler | ✅ 需 poppler |
| 图片 OCR | ✅ Vision（最快）→ 内置 WASM | ✅ 内置 WASM | ✅ 内置 WASM |
| 导出包打 zip | ✅ zip | ✅ zip | ✅ Compress-Archive |
| 在文件管理器中显示 | ✅ open -R | ✅ xdg-open | ✅ explorer /select, |

OCR 开箱可用：内置 tesseract.js(WASM) + 中文训练数据，Windows/Linux/macOS 都无需安装。
macOS 若可用会优先走系统 Vision（更快更准），否则自动退回 WASM。
代价：相关依赖安装后约 +80MB（tesseract.js-core 49MB + chi_sim 22MB + eng 14MB）。

poppler 不在 npm 包里（它约 200MB，仅 PDF 抽取需要）。装完即可，插件会自动发现，不需要配环境变量：

brew install poppler # macOS
sudo apt install -y poppler-utils # Debian/Ubuntu
Windows：解压 poppler-windows 到 %LOCALAPPDATA%\poppler

自动探测顺序：DSH_DUAL_BRIDGE_POPPLER → PATH → Homebrew（/opt/homebrew/bin、/opt/homebrew/opt/poppler/bin）→ /usr/local/bin → conda 常见目录 → Windows %LOCALAPPDATA%\poppler。

没有 poppler 时：PDF 按钮不显示，DOCX/PPTX/XLSX/RTF 与 OCR 不受影响。扫描件/图片型 PDF 抽不出文字——这类请直接把文件拖进网页版上传。

安装

前置

- DSH ≥ 0.2.1-rc.2
- dsh-better-sidebar@0.28.0：本插件的 Tab 由它提供宿主，必须一起安装（同一条命令里写两个包）。

一条命令（桌面 App / 命令行）

桌面 App（profile = desktop）
dsh plugin --profile desktop add dsh-dual-bridge dsh-better-sidebar@0.28.0 --allow-build=tesseract.js

命令行版 dsh web（profile = web）
dsh plugin --profile web add dsh-dual-bridge dsh-better-sidebar@0.28.0 --allow-build=tesseract.js

说明：

- 两个包要写进同一条命令：DSH 只把 profile 的直接依赖登记为 bundle。先装 sidebar 再装插件也能用，但分成两条命令时第二步如果被 pnpm 的构建拦截打断，bundle 就不会登记。
- 为什么不把 sidebar 塞进本包的 patch 自动挂载：实测会重复注册 /sidebar/api（已有 sidebar 的 profile）或拿不到 betterSidebar 服务（没有 sidebar 的 profile）。DSH 的 bundle 层不支持「包内再挂一个 bundle」，所以 sidebar 必须是 profile 的直接依赖。
- --allow-build=tesseract.js 只放行 OCR 引擎的一条 postinstall（opencollective 提示），不影响其它包。
- 装完完全退出并重开 App（host 端路由只在启动时加载）。

在 App 内安装

在 Plugins 页依次安装 dsh-better-sidebar@0.28.0 和 dsh-dual-bridge，两个都选 Enable now，构建脚本提示时选「允许」，然后重启 App。

从 0.13.0 升级

0.13.0 尝试过自动挂载 sidebar，已在 0.13.1 撤回。升级时用上面的双包命令覆盖安装即可；若 profile 里留下了 dual-bridge-sidebar 条目，先删掉那一行再重启。

本地开发安装

cd ~/.dsh/profiles/desktop
pnpm add link:/path/to/dsh-dual-bridge

使用

1. 打开侧边栏 「⇄ 分流对话」
2. 等扫描完成（顶部显示 N 个可打包文件 · M 个目录）
3. 展开目录、勾选要带的文件（勾目录 = 整棵子树）
4. 设 token 预算、选「超预算时」的策略
5. 点 📦 打包选中文件 → 看预览 → 📋 复制到剪贴板
6. 点 🚀 同屏打开网页版 → 在网页版输入框 Cmd/Ctrl+V 粘贴 → 提问

关于 PDF / Office

- 二进制文件不会被当成代码打包；它们在树里置灰显示，可点「抽取文本」
- 抽取是按需、逐个的：不会因为选了七个 PDF 就把预算打爆
- 抽取结果带「已抽取 N 字 / 移除」，进入 prompt 的【抽取的附件文本】段
- 排版损失不可避免（双栏会串行、公式可能变乱码）。保真度要求高就直接上传原文件

为什么不能把网页版内嵌在页面里？

DeepSeek 网页版响应头声明：

content-security-policy: frame-ancestors 'none'

'none' 表示任何站点都不允许 iframe 内嵌它（Harness 自带的「内嵌浏览器」也会显示"拒绝了嵌入请求"）。
这是站点安全策略、由浏览器强制执行，前端无法绕过；唯一能绕过的办法是本地代理改响应头或浏览器扩展去 CSP —— 那既越界也不合理。

所以本插件用同屏独立窗口（贴在侧边栏右侧、自动聚焦）达到"并排、不用切标签"的效果。

隐私与合规

- 不联网：扫描、打包、复制、抽取全部在本机完成；插件没有任何出站请求
- 不上传：文件内容只进你的剪贴板，由你自己决定粘贴到哪里
- 不自动化：不操控浏览器、不模拟点击、不调用网页版接口
- 抽取路由只在 localhost：POST /dual-bridge/extract 挂在 DSH 已有的本地 web 服务上（不额外开端口），并限制只能抽取当前会话工作区之内的文件；execFile + argv 数组（路径不作为 shell 片段）
- 唯一的网络行为是「打开一个新的浏览器窗口指向 chat.deepseek.com」——由你的浏览器自己发起

已知限制

1. 依赖 dsh-better-sidebar 的内部路由（POST /sidebar/api/{session.cwd, fs.tree, fs.trees, fs.read}）。
这些接口不是公开 API，上游改字段本插件就会失效——已在 dependencies 中锁定版本。
2. host 端改动需重启 dsh web；client 改动刷新页面即可。
3. 子目录里嵌套的 .gitignore 不解析（只读项目根）。
4. 不跟随目录软链。
5. 扫描上限默认 2000 个文件（可在界面调整）；超大仓库建议把扫描范围收窄到子目录。
6. 抽取为纯文本，丢失排版/表格/图片/公式结构。
7. OCR 质量：macOS Vision > 系统 tesseract > 内置 WASM。WASM 对排版规范的文档截图较准，对艺术字/宣传海报容易出噪声——这类图建议直接上传原图让 AI 看图。
8. 首次 OCR 需初始化 WASM worker（约 0.3–1s），之后复用。

开发

npm install
npm run typecheck # tsc --noEmit (strict)
npm run test # node --test（59 个用例）
npm run build # esbuild -> lib/index.js + lib/client.js
npm run verify # 三条一起跑
npm run pack:check # 检查 npm 包内容（确认不含 vendor/）

工程结构：

src/
client.tsx # client 入口：注册「分流对话」Tab DualBridgeTab.tsx # Tab UI：扫描/树/预算/打包/复制/抽取/同屏打开 file-tree.ts # 目录树纯逻辑（三态勾选、跳过统计） pack.ts # 过滤规则、prompt 组装、预算裁剪、附件筛选 split-window.ts # 同屏窗口几何（纯函数 + 打开逻辑） api.ts # 复刻 better-sidebar 的文件 API（fs.tree/fs.read 等） extract.ts # host：PDF/Office 文本抽取（poppler / textutil） index.ts # host 入口：注册 POST /dual-bridge/extract scripts/build.mjs # host ESM + client ModuleLoader(CJS) 双产物

本地调试 PDF 抽取时可以把 poppler 放在 <repo>/vendor/poppler（插件会自动探测），但它不会被打包发布（files 白名单已排除）。

License

MIT