dsh-omnifile

Readme

# DshOmniFile（dsh-omnifile）

> 文件适配插件：把本地文件（拖拽 / 粘贴 / 点击多选 / 官方 `@file`）加入对话，主模型按需解析文件内容后正常作答。
>
> **[English](README.en.md)** | 中文

## 工作方式（按需解析，不提前干预）

1. 文件加入输入区后显示为一个 chip，消息发送时序列化为 `文件：<绝对路径>` 引用。
2. 主模型在需要时调用 **dshomnifile 工具**解析引用路径，一次性获得 Markdown 内容。
3. 聊天内每条用户消息上方有文件卡片：图片显示缩略图（点击放大预览），其他文件显示文件行（点击用本地默认程序打开源文件）。

## 支持的解析路线

| 类型 | 处理方式 |
|---|---|
| 纯文本（`.json/.txt/.md/.html/.shtml`） | 多编码直读（UTF-8/16/32 、GB18030、BOM 识别），JSON 美化、HTML 剥标签；二进制内容拒绝 |
| 图片 | 配置的多模态模型识别（PNG/JPEG/WebP/GIF 原生；BMP/SVG/AVIF/TIFF 自动转码为 PNG 后识别），内容哈希缓存 + 并发排队 |
| Office 文档 / PDF / 表格 / EPUB / CSV 等 | 先由 anydoc 提取文本；**文档内嵌图片**解包提取后交多模态识别，按文档顺序组装进正文 |
| **PDF：纯文字** | anydoc 直接提取文字层（不渲染不 OCR，最省） |
| **PDF：图文混排 / 贴图** | 智能闸门检测到页面含位图 → 逐页渲染 + 逐页 OCR |
| **PDF：纯扫描件**（含 CCITT 传真 / JBIG2） | anydoc 提取不到 → 逐页渲染 + 逐页 OCR |

- PDF 逐页渲染为**进程内完成**（pdfjs-dist + @napi-rs/canvas，已配置 `wasmUrl` 等资源路径），跨平台无需安装任何本机工具；CCITT 传真 / JBIG2 的 1-bit 扫描页在 `auto` 下自动逐页识别。
- 批量解析时单个文件失败只影响该文件（结果内联报错），不会拖垮整批；取消操作立即中止。

## 前置要求

- DSH **0.1.2-alpha.1 及以上**（Desktop / Web）。
- 一个**支持图片输入**的多模态模型，并在「设置-模型」中配置好（见「配置」）。

## 安装（从 GitHub）

插件以「成品包」发布：`lib/` 构建产物与 `cordis.patch.yml` 已提交进仓库，安装即用、无需在本机构建（不上传时执行构建脚本，也就没有 pnpm 构建审批门槛）。

```bash
dsh plugin --profile desktop add github:<你的用户名>/dsh-omnifile
```

- 安装由 DSH 在对应 profile 目录（`$DSH_HOME/profiles/<profile 名>`）内执行 `pnpm add github:...`：
  - 运行时依赖（`@napi-rs/canvas`、`pdfjs-dist`、`@firecrawl/anydoc`）自动装进该 profile 的 `node_modules`，无需手动处理；
  - 装完自动把本插件加入 profile 的插件层，**重启 DSH** 后生效。
- 文档解析用的 anydoc CLI / extract-zip **不在安装时预装**：首次解析文档时由 `npx` 按需从 npm 仓库拉取固定版本并缓存（需联网；无网络环境首次解析会失败）。
- Desktop 端 pnpm 由 DSH 自带；Web / CLI 方式要求本机 PATH 中有 `pnpm`。

## 配置

在 DSH「设置-模型」配置模型后，本插件设置页选择其一保存为 `providerRef`；未选择时默认使用当前会话模型（需支持图片输入）。

`settings.yaml` 可覆盖项：

```yaml
omnifile:
  providerRef: llm-pi-ai/vision/general-model   # 「设置-模型」中选择的多模态模型唯一引用
  describePrompt: '请按要求描述这张图片。'      # 识图固定提问（工具可按需在图片问题上叠加）
  timeoutMs: 60000            # 单次多模态调用超时（毫秒）
  maxFileBytes: 50            # 单文件大小上限（MB）
  maxBatchFiles: 20           # 单次上传文件总数上限（超出自动截断并提示）
  concurrency: 10             # 多模态识别并发数（超过自动排队等待，不拒绝）
  maxTokens: 16384            # 单次识图最大输出 token 数
  logLevel: warn              # debug / info / warn / error
  pdfScan: auto               # PDF 策略：auto=智能（见上表）/ force=任何 PDF 都逐页渲染识别（最完整、成本最高，每页一次多模态调用）
```

## 日志与排障

- 4 级日志统一前缀 `[dsh-omnifile]`；宿主端镜像到 DSH `ctx.logger`（持久化到 `userData/logs/dsh-*.log`）与 `console.error`，浏览器端输出到 DevTools Console（F12）。
- 级别控制：设置页 → 环境变量 `DSH_OMNIFILE_LOG_LEVEL=debug`（优先级最高，且经 `/api/omnifile/config` 同步到浏览器端）→ `settings.yaml` 的 `omnifile.logLevel`。
- 排障入口：`http://127.0.0.1:<port>/api/omnifile/config` 可回读当前生效配置与限额。

## 架构

```text
src/core/          双端共用：常量 / 消息标记 / 工具 / 日志
src/core/host/     宿主侧：配置、路径、HTTP、分类（extensions）、文本解码、anydoc/npx、
                   PDF 渲染与位图检测（pdfrender）、解析管线（parse）、多模态（vision）、模型目录、工具注册
src/core/client/   客户端工具与日志适配
src/host/index.ts  宿主组合根：设置命名空间 + /api/omnifile/* 路由 + dshomnifile 工具
src/client/        客户端组合根：上传/拖拽/粘贴/@ 文件接入（intake）、chip 控制器、
                   聊天文件卡片（card）、设置页小节（settings）、样式（styles）
build/ scripts/    构建配置与入口（vite 三目标：host / common / client）
test/              node --test 回归（含传真 PDF 渲染、位图闸门、图片转码、多编码解码）
```

## 局限

- `@` 文件补全依赖宿主提供的工作区文件引用服务；缺失时仍可用拖拽 / 粘贴 / 上传按钮。
- 识图依赖配置的多模态模型；纯文本模型无法识图（会在解析时明确报错提示）。
- 无 BOM 的 UTF-16 中文短文本存在编码歧义，会按二进制拒绝（业界通病，建议文件自带 BOM）。
- 老式 `.doc/.xls/.ppt` 依赖 anydoc 支持；AVIF/TIFF 转码识别依赖运行环境解码能力。
- 超大文档解析后的全文交由主模型处理，插件层不截断、不丢内容。
- 本插件不向第三方云端传任何内容，多模态调用只指向你配置的端点。

## 许可

MIT