简体中文 | English

@dsh-external/dsh-document-drop

DeepSeek Harness 文档拖拽读取插件（hybrid：Cordis Host + Web Client UI）。 拖入 PDF / Word / Excel / 文本自动解析进对话：轻量文档内联注入，大型文档挂载工作区

• doc_read 工具按需检索；扫描件自动走 Windows 11 原生 WinRT OCR（中英双语）， 页面高清原图可供多模态模型 read_image 调阅。零修改 DSH 上游，运行时热注入。

安装（DSH 用户）

方式一 · 官方装配（生产态，重启后由 bundles 接管）：

# 下载 Release 的 tgz 解压得到插件目录（含 lib/ 与 scripts/），然后：
dsh plugin --profile web add <解压目录>
# 或 git 仓库直装（仓库需含预构建 lib/，本仓库 Release tgz 已含）：
dsh plugin --profile web add github:Su2uka111/dsh-document-drop

方式二 · 运行时热注入（开发态，免重启；需环境已常驻 dsh-super-injector）：

对 DSH 里的 AI 说：dev_inject_plugin <解压后的插件目录>

环境要求：Windows 11（阶段 5 扫描件 OCR 依赖系统内置 WinRT PdfDocument/OcrEngine 与 PowerShell 5.1；非扫描件功能不受此限制）。DSH ≥ 0.1.0-rc.5。

安装后拖一个 PDF/DOCX 进聊天窗口即可看到输入框上方的文档胶囊。

由 dsh-super-injector dev_scaffold_plugin 形态规范生成，按 plan/DeepSeek-Harness-文档拖拽读取插件开发计划.md 分阶段实现。

阶段进度

• 阶段 0（已交付）：hybrid 骨架 + 双端打包 + 注入链路。 Host：日志探针（启动 + 心跳）+ hello API（GET /dsh-document-drop/api/hello|probe）。 Client：模块装载骨架（ModuleLoader bundle）。
• 阶段 1（已交付）：捕获阶段拖拽拦截（stopImmediatePropagation 截断原生 InputBar 图片白名单报错，图片原样放行）+ conversation.input.dock 文档胶囊栏 （PDF/DOCX/XLS/TXT 徽章、体积、[×] 移除）+ 会话隔离暂存 Store。
• 阶段 2（已交付）：Host 存储与解析流水线。
  • POST /dsh-document-drop/api/doc-drop/upload：裸字节流 + 元数据头 （x-dd-session-id / x-dd-file-name），硬上限 50MB。
  • 存储：会话 cwd（ctx.get('sessions') → SessionHeader.cwd）优先， 落盘 <workspace>/.dsh/attachments/<sessionId>/<safe-name>， 返回相对工作区的 POSIX 路径；无会话回退 ~/.dsh/attachments/<sessionId>/； 文件名白名单化 + 同名内容哈希防覆盖 + 写入路径围栏。
  • 解析：PDF（unpdf，逐页文本 + 扫描件检测：<50 有效字符或页均 <10 判 scanned → HTTP 422）/ Word（mammoth → Markdown）/ 表格（SheetJS，Sheet 元数据 + 字段头 + 前 50 行 Markdown 预览，>1000 行强制 mounted）/ 文本（UTF-8）。
  • 双轨研判：inline 当且仅当字符 < 3,000 且体积 < 15KB（表格按 Markdown 序列化体积判轨，规避 SheetJS zip 基线开销误判）；否则 mounted 返回摘要。
  • 30 项单测全绿（样本现场合成：txt/xlsx/docx/pdf/扫描件/存储安全）。
• 阶段 3（已交付）：双轨 Prompt 组装 + doc_read 自主检索工具。
  • DraftAssembler.ts：Enter 捕获富化 + inputActions.submit 包装（双保险，取即清防重复拼接）；inputActions 缺席的 hero 屏兜底走 Lexical execCommand 写路径（peek → 写 → 成功才清暂存）。
  • doc_read 工具：PDF 按页码范围 / 表格按 Sheet+行偏移 / 文本按行窗口；路径物理定位用上传时登记的会话根表（sessionRoots）；永不抛出（操作型错误以可读字符串回传）。
  • 实测：Agent 真实调用 doc_read 分节调阅挂载文档并正确概括（两轮回合验证，标记格式与计划书一致）。
• 阶段 4（已交付）：端到端验收与稳定性验证（真实 Web 会话全链路）。
  • 测试资产生成器：tests/gen-e2e-assets.mjs（轻量 docx 多级标题+表格 / 15 页 PDF / 3 Sheet 250 行 xlsx / 纯图片扫描 PDF，全部现场合成免外部依赖）。
  • Case 1 轻量 Word：inline 胶囊 → 模型 6 秒直接翻译，零工具调用。
  • Case 2 大型 PDF：胶囊"已挂载 15页" → 模型调 doc_read 精准引用第 5 页核心论点原文。
  • Case 3 扫描件：客户端拒收胶囊"扫描件不支持，请转图片"，无崩溃。
  • Case 4 移除与清空：[X] 移除的文件不出现在外发消息，剩余文件以正确格式进入。
  • 零停机热重载：touch lib 产物 → 注入器 watcher 约 1.5s 自动重载（probe.appliedAt 更新、pid 不变、API 不中断）；dev_injected_list 等价通道确认 active。
  • 验收中发现并修复：表格判轨改为行数语义（§5.2.2 >100 行预览+挂载）； submit 包装改为渲染期安装（按钮路径无 keydown）； 真机实测修复——拦截 drop 后原生图片遮罩（图片拖动到此处即可添加）永久卡屏： 纯文档拖拽在 dragenter/dragover 捕获期阻断原生遮罩状态机（图片拖拽完全放行）， 拦截 drop 后补发 dragend 触发原生 reset()（兼容混合拖拽的遮罩收尾）。
• 阶段 5（已交付）：PDF 扫描件支持增强——拒收升级为「WinRT 光栅化 + 原生 OCR + 视觉/文本双模态」。
  • scripts/ocr-pdf.ps1：Windows 11 原生 WinRT 适配器（Windows.Data.Pdf.PdfDocument 按页渲染 高清 PNG + Windows.Media.Ocr.OcrEngine zh-Hans-CN/en-US 识别），零外部依赖（无 Tesseract/Python）。 必须走 powershell.exe 5.1（pwsh 7 无 WinRT 投影）；脚本需 UTF-8 BOM（PS5.1 无 BOM 按 GBK 解码会炸语法）。
  • src/host/parsers/ocr.ts：Node 侧调度器（spawn + 超时 + 结果 JSON 解析），每页结果写侧车缓存 （<image>.ocr.json），重复查询命中缓存不再拉 PowerShell（实测 84ms → 3ms）。
  • 上传流水线：unpdf 判 scanned 后不再 422——自动 OCR 前两页，返回 200 { track:'mounted', isScanned:true, pages, ocrEngine, markdown(前两页OCR预览), imagePages[PNG相对路径] }； OCR 失败也回 200 优雅降级（原图仍挂载，可 read_image）。扫描件强制 mounted 防撑爆输入框。
  • doc_read：扫描件按页返回 OCR 正文 + [该页高清原图路径: @…，多模态模型可使用 read_image 工具查看原件细节]。
  • 前端：DocChip 扫描件专属徽章「扫描件 N页 (OCR已就绪)」（不再红色错误）；挂载标记注明 「含 OCR 文本与页面原图（doc_read 阅读，read_image 查看原件）」。
  • 测试资产升级：tests/gen-e2e-assets.mjs 的 test-scan.pdf 改为 System.Drawing 渲染中英文文字 → JPEG → DCTDecode 内嵌（真·可 OCR 扫描件；手写 PDF 注意字典括号配平与间接 Resources 引用）。
  • 实测：拖入扫描件 → 徽章就绪 → 发送带 OCR 说明的挂载标记 → Agent 调 doc_read 读出 关键发现（中英双语原文）正确回答。

端到端用例复跑

node tests/gen-e2e-assets.mjs   # 生成 .tmp-e2e/ 四类资产（含真·可 OCR 扫描件 test-scan.pdf）
# 在 DSH Web 会话拖入资产目录中的文件，按 README 阶段 4/5 用例核对胶囊与回答

构建与注入

npm install
DSH_CHECKOUT=<dsh checkout> bash scripts/build.sh   # host（tsc）+ client（tsdown）
npm pack                                            # 产出 tgz
# 注入器环境内（DSH Agent）：dev_inject_plugin <本目录>
# 等价 HTTP 通道（web 运行中）：
#   POST http://127.0.0.1:<port>/super-injector/api/inject  {"dir": "..."}
#   GET  http://127.0.0.1:<port>/super-injector/api/list    （dev_injected_list 等价）

scripts/build.sh 自动探测 DSH checkout（$DSH_CHECKOUT → 常见路径 → 本机 D:/code/预设/upstream/deepseek-harness），junction 链接 vendor 基线包后 先以 checkout 的 tsc 编译 host，再以 tsdown 打包 client（lib/client.js）。

结构

src/index.ts               Host 入口：日志探针 + hello/probe API + POST /doc-drop/upload（扫描件走 OCR）
src/host/storage.ts        工作区存储：.dsh/attachments/<sessionId>/，安全落盘 + 相对路径
src/host/parsers/index.ts  解析调度 + 双轨研判（inline/mounted，表格按行数判轨）
src/host/parsers/pdf.ts    PDF：unpdf 逐页文本 + 扫描件检测（有效字符阈值）
src/host/parsers/word.ts   Word：mammoth → Markdown
src/host/parsers/sheet.ts  表格：SheetJS，Sheet 元数据 + 前 50 行预览 + 行窗口读取
src/host/parsers/ocr.ts    扫描件 OCR 调度：spawn powershell + 侧车缓存（阶段 5）
src/host/tools/doc_read.ts doc_read 工具：PDF 按页 / 表格 Sheet+行 / 文本行 / 扫描件 OCR+原图
scripts/ocr-pdf.ps1        WinRT 光栅化 + OcrEngine 适配器（阶段 5，需 powershell.exe 5.1 + UTF-8 BOM）
src/client/index.ts        Client 入口：拦截器 + 组装器 + dock 插槽注册
src/client/types.ts        文档类型/白名单/分类/格式化（含 isScanned）
src/client/store.ts        会话隔离暂存 Store（useSyncExternalStore 可观察）
src/client/uploader.ts     上传器：字节流 POST + 状态流转 + OCR 字段回填
src/client/CaptureDropController.ts  捕获阶段拦截器 + 蓝色遮罩 + 原生遮罩收尾（dragend）
src/client/DocAttachmentRail.tsx     胶囊栏（空队列返回 null 不占高度）
src/client/DocChip.tsx               胶囊卡片（徽章/文件名/体积/状态/移除；扫描件专属徽章）
src/client/DraftAssembler.ts         双轨 Prompt 组装（Enter 富化 + submit 包装 + Lexical 兜底）
tests/gen-e2e-assets.mjs   端到端测试资产合成（docx/15页PDF/250行xlsx/真·可OCR扫描件）

验收基线（阶段 0-5）

• dev_injected_list（或 /super-injector/api/list）可见本插件且 host 激活。
• 拖入 PDF/DOCX/XLSX/MD：无原生"图片格式不支持"报错，输入框上方浮现文档胶囊。
• 拖入 PNG/JPG：原生图片拖拽行为不受影响。
• GET /dsh-document-drop/api/hello 返回插件元信息（stage=s5-ocr）；Host 日志可见探针心跳。
• 拖入扫描件 PDF：不再拒收——自动 WinRT OCR，胶囊「扫描件 N页 (OCR已就绪)」， 发送带 OCR+原图说明的挂载标记，Agent 调 doc_read 读出 OCR 正文与高清原图路径。