DshOmniFile（dsh-omnifile）

文件适配插件：在 DSH 中 拖拽 / 粘贴 / 点击多选 / @ 选择 本地文件，用 anydoc 解析文档、多模态模型识别图片，把解析结果整合给主模型。

English | 中文

功能

• 文件接入：拖拽到窗口、输入框粘贴、输入框左侧「上传」按钮多选、输入 @ 选工作区文件；文件以带 📂 图标、缩短名的 chip 插入输入区最前，加入后自动聚焦输入框，可一次选多个。
• 文档解析：支持 Office 文档、PDF、电子表格、EPUB、CSV 等常见格式（.doc/.docx/.ppt/.pptx/.xls/.xlsx/.pdf/.odt/.ods/.odp/.rtf/.epub/.csv 及变体），以及纯文本（.json/.txt/.md/.html/.shtml）；纯扫描 PDF 走逐页识别。
• 多模态识图：图片 / 文档内嵌图片 / 扫描 PDF 交给配置的多模态模型转为文字描述；同一图片结果按内容缓存，避免重复调用。
• 后台解析 + 发送等待：文件一经选择立即后台解析，发送时若仍有文件未解析完会等待全部完成后再发出、才开始回答；等待期间实时显示解析进度，可随时移除单个文件而不影响本次发送。
• 聊天内文件卡片：每条用户消息上方一行文件卡片（图标 + 文件名），点击展开/收缩查看解析全文；右侧 📂 用本地默认程序打开源文件。
• 文本-only 主模型增强：对不支持图片的主模型，发送时自动把图片块改写为多模态文字描述（并结合你当前的问题生成）；支持图片的主模型直接看原图，无需此步。
• omnifile 工具：主模型可随时自行解析本地文件。
• 会话内消息导航：聊天区右缘显示用户消息定位条，每个用户消息一个锚点圆点，点击即可滚动定位（长 AI 回复中快速回到各用户提问）。

前置要求

• DSH（Desktop 或 Web）环境。
• 一个支持图片输入的多模态模型，并在「设置-模型」中配置好（见「配置」）。

部署

用 DSH 插件命令安装（自动拉取 GitHub 仓库、安装并启用本插件的 bundle）：

dsh plugin --profile web add github:zuuky/dsh-omnifile

安装后：

1. 在 $DSH_HOME/settings.yaml 添加 omnifile: 小节（见「配置」）；若主模型是文本-only，再把 agent-default-model.provider 指到对应的 omnifile-* 变体（多模态主模型可跳过）。
2. 重启 DSH Desktop（或 dsh web），加载插件后即可使用。

配置

多模态模型在 DSH 的「设置-模型」中配置，然后在本插件设置页里选择其一，保存为一条 providerRef 引用（下拉会标注图片能力：🖼 支持图片输入 / 📝 纯文本；请选择带 🖼 的模型，纯文本模型用于识图会失败）。

settings.yaml 里可覆盖的常用项：

omnifile:
  providerRef: llm-pi-ai/vision/general-model   # 「设置-模型」中选择的多模态模型唯一引用
  describePrompt: '请按要求描述这张图片。'      # 发送给多模态模型识图时的固定提问
  timeoutMs: 60000            # 单次多模态调用超时（毫秒）
  maxFileBytes: 52428800      # 单文件大小上限（50MB）
  maxBatchFiles: 20           # 单次上传文件总数上限（图片也是文件；超出自动截断并提示）
  listMaxFiles: 2000          # @ 文件选择器最多列出文件数
  listMaxDepth: 12            # @ 文件选择器递归深度
  concurrency: 1              # 多模态识别并发数（超过的自动排队等待，不拒绝文件）
  temperature: 0.7            # 采样温度（0-2）
  maxTokens: 8192             # 单次识图最大输出 token 数

其余参数（采样 top_p、思考模式、文件名长度、文档内嵌图/字符限制等）固定使用合理默认值，无需配置。

日志与排障（Linux 上报问题时先看这里）

插件内置 4 级日志（debug / info / warn / error），统一前缀 [dsh-omnifile]，可在「设置 → DshOmniFile → 日志级别」选择，也可以直接写进 settings.yaml：

omnifile:
  logLevel: debug        # debug / info / warn（默认）/ error
  pdfScan: auto          # auto / force —— 扫描件与图文混排 PDF 的处理策略
  pdfPython: ''          # PDF 扫描页渲染用的 Python 解释器路径（已装 pymupdf）；留空自动探测

• pdfScan：auto（默认）只在 anydoc 提取不到文本时才把 PDF 逐页渲染为图片识别；扫描页 + 文字混排的 PDF 里 anydoc 若能抽到部分文字，auto 不会触发逐页渲染，图片页会丢失——这类文件请改用 force（任何 PDF 都逐页渲染识别，成本较高）。
• 扫描 PDF 的逐页渲染依赖 PyMuPDF（Linux 常用 python3 环境里需先安装，否则日志出现
  「pymupdf not installed under python3」且扫描页一图都出不来）：

  python3 -m pip install pymupdf      # 或 python3 -m pip install pymupdf --user
  python3 -c "import pymupdf"        # 验证安装成功（无输出即 OK）
  

  若 DSH 宿主进程 PATH 里的解释器不对，可在设置里把 pdfPython 填成已装好 pymupdf 的解释器路径，
  或启动 DSH 时用环境变量 DSH_OMNIFILE_PYTHON=<解释器路径>（环境变量优先级最高）。
• 日志出处（双份，便于定位）：
  • 宿主端：每条日志同时镜像到 DSH 宿主 ctx.logger 和 console.error。DSH 会把 ctx.logger 持久化到
    <userData>/logs/dsh-YYYY-MM-DD.log（全量）与 dsh-YYYY-MM-DD.error.log（warn/error），
    userData 即 Electron app.getPath('userData')：Windows 为 %APPDATA%\DSH Desktop，
    Linux 为 ~/.config/DSH Desktop（以实际安装为准，可在设置里或 SDK app.getPath('userData') 查到）。
    console.error 同时输出到宿主进程 stderr（终端启动时可见）。
  • 浏览器端：网页 DevTools Console（F12），前缀 [dsh-omnifile]。
• 宿主日志级别同时受环境变量控制（优先级最高）：DSH_OMNIFILE_LOG_LEVEL=debug 启动 DSH 即可，
  且该 env 会经 /api/omnifile/config 的 effectiveLogLevel 同步到浏览器端，设置没保存也能开 debug。
• 排障端点：浏览器/curl 访问 http://127.0.0.1:<port>/api/omnifile/settings-raw 可回读宿主持久化里
  本插件命名空间的原始值，对照设置页就能确认「保存到底落盘没有」；设置保存路径本身会打印每次
  set/unset 的结果、scope 的 status/writable/mode/revision，超时/拒绝原因一目了然。

使用

1. 通过 拖拽 / 粘贴 / 点击上传按钮 / @ 选文件 把文件加入输入框：输入框出现文件 chip（可一次选多个，图片走 DSH 原生附件），并自动聚焦输入框，可直接打字或继续添加。
2. 文件加入后立即开始后台解析，进度实时显示在 chip 上；解析完成后聊天内生成可展开的文件卡片。
3. 点击发送：若还有文件在解析会先等待（对话区底部显示“正在解析文件 x/y：…”），全部完成后消息发出、主模型开始回答。
4. 聊天卡片上点 📂 打开源文件；点卡片行展开查看解析后的全文。

架构

插件源码按功能块组织，运行时分宿主/客户端两端：

src/core/      全项目共享层：常量/消息标记/工具、宿主侧配置/路径/HTTP/限制器等
src/host/      宿主组合根（apply 入口，装配各功能块的服务与路由）
src/client/    客户端组合根（apply 入口，装配各功能块的 UI 安装器）
src/features/  按功能划分的模块：
               file-intake  文件接入（拖拽/粘贴/上传/@ 选择、chip、发送等待）
               file-parsing 文档解析（anydoc + 纯文本解码）
               vision       多模态识图（模型枚举、provider 解析、内容缓存、并发排队）
               variants     文本-only 主模型增强（omnifile-* 图像变体）
               omnifile-tool 主模型可用工具
               chat-card    聊天内文件卡片
               navigation   会话内消息导航
               settings     设置面板

构建产物保持三个入口（宿主 / 客户端 / 双端共用），目录与依赖约定详见 docs/ARCHITECTURE.md。

局限

• 识图依赖多模态模型：必须在「设置-模型」中选择支持图片输入（🖼 标注）的模型，否则图片/文档内嵌图片/扫描 PDF 识别会失败；DSH 内置 DeepSeek 为纯文本模型，不能用于识图。
• 文档内容不做截断：解析后的 Markdown 全文交由主模型自行处理；超大文档可能超出模型上下文长度（由模型侧处理），不会在插件层被截断而丢内容。
• 数量/并发：一次上传文件数受 maxBatchFiles 限制（超出自动截断并提示）；多图片识别按 concurrency 排队执行。
• 本插件不向第三方云端传任何内容，多模态调用只指向你配置的本地/内网端点。

许可

MIT