dsh-file-vision

English | 中文

DSH（DeepSeek Harness）插件：对话输入框按类别上传文件（表格/文档/图片/视频），图片与视频通过用户自配的视觉模型（OpenAI 兼容 /v1/chat/completions，独立 baseURL + apiKey）识别，Excel/PDF/Word 等文本类文件本地解析；Agent 在思考过程中调用 inspect_attachment（概览）与 analyze_attachment（明细）工具，识别/解析结果返回主流程。附件支持「共享到项目（跨会话）」开关，插件配置页内置「环境诊断」面板与测试视觉连接。同时兼容 DSH Desktop 与普通 dsh web，在 Desktop 下存储按激活 profile 隔离。

功能特性

| 特性 | 说明 | | --- | --- | | 分类上传 | 输入框「表格/文档/图片/视频」四个按钮 + 跨会话共享勾选 | | 文本类解析 | Excel(.xlsx/.xls，SheetJS)、PDF(pdf-parse)、Word(.docx，mammoth)、CSV(UTF-8/GBK 自动探测)、TXT/MD | | 图片/视频识别 | 用户自配 OpenAI 兼容视觉模型（baseURL + apiKey + model）；视频 ffmpeg 抽帧（sequential / multi-image） | | 两级查询 | inspect_attachment 低消耗概览 → analyze_attachment 按需明细，语义缓存避免重复调用 | | 跨会话共享 | 附件可勾选「共享到项目」，其他会话可引用同一附件 id | | 环境诊断 | 插件配置页展示 OS/Node/包管理器/ffmpeg/存储目录状态、按平台安装步骤、测试视觉连接、诊断日志 | | 跨平台 | Windows / macOS / Linux；路径/换行/编码/权限按平台规范；ffmpeg 由 ffmpeg-static 内置，无需系统安装 |

环境要求

• Node.js ≥ 22（本插件在 v24.13.0 验证通过）
• pnpm（推荐；npm/yarn 亦可）
• 视觉识别需要可用的 OpenAI 兼容视觉模型端点（baseURL + apiKey + model）
• ffmpeg / ffprobe：无需系统安装，由 ffmpeg-static 内置平台二进制提供

安装到 DSH

方式一：从 npm 安装（推荐，已发布）

dsh plugin --profile web add dsh-file-vision

安装后重启 dsh web：输入框出现「表格/文档/图片/视频」按钮，设置页出现 file-vision 配置与环境诊断卡片。

方式二：本地仓库安装（开发调试 / 未发布时）

# 1. 获取源码（本地路径或 clone）
cd dsh-file-vision

# 2. 安装依赖并构建（本机已验证通过）
pnpm install
pnpm build

# 3. 链接安装到 DSH web profile
dsh plugin --profile web add link:$(pwd)

# 4. 重启 DSH Web GUI
# 重启后：输入框出现「表格/文档/图片/视频」按钮；设置页出现 file-vision 配置与「环境诊断」卡片

Windows 下 $(pwd) 不可用时，直接写绝对路径：

dsh plugin --profile web add link:C:\path\to\dsh-file-vision

验证安装

1. 重启 dsh web 后，新建会话的输入框左侧出现「表格/文档/图片/视频」四个按钮；
2. 打开 Settings → 插件配置 → file-vision，能看到视觉模型配置项与「环境诊断」卡片（OS/Node/ffmpeg 状态、安装步骤、重新检测、测试视觉连接、诊断日志）；
3. 上传一个 .csv/.txt 文件并提问，Agent 应能通过工具读取内容（本地解析，无需视觉模型）。

卸载

dsh plugin --profile web remove file-vision

DSH Desktop 兼容

本插件同时兼容 DSH Desktop 与普通 dsh web：

• 顶层 inject 只依赖普通 DSH service（tools + webServer），不含任何 Desktop-only service，因此在 CLI、dsh web、DSH Desktop 中都能直接加载（遵循 DSH Desktop 插件开发契约中「兼容 Desktop 和普通 DSH」的模式）。
• 插件加载时通过 desktopProfiles（来自 dsh-plugin-desktop，类型仅 devDependency，构建时不打包）动态探测：当运行在 Desktop 下，文件存储与诊断日志作用域到当前激活 profile 的目录（<profileDir>/file-vision），随 profile 切换而隔离；不存在该 service 时回退到普通 ~/.dsh/file-vision。
• 从不在工艺参数 / ctx.baseUrl / settings / $DSH_HOME 中猜测 Desktop profile，profile 身份只取自 desktopProfiles.current。
• 「环境诊断」卡片会显示当前宿主（web 或 desktop/profile=<name>）与实际的存储目录，便于排查。

配置

Settings → 插件配置 → file-vision：

| 配置项 | 说明 | 默认 | | --- | --- | --- | | vision.baseURL | 视觉模型端点根地址（OpenAI 兼容） | 空（必须配置才能识别图片/视频） | | vision.apiKey | 视觉模型 API Key（secret，密文存储） | 空 | | vision.model | 视觉模型名，如 gpt-4o / qwen-vl-max | 空 | | vision.videoFrameIntervalSec | 视频抽帧间隔（秒） | 3 | | vision.videoMaxFrames | 视频最大抽帧数 | 20 | | vision.videoMode | sequential（逐帧）/ multi-image（单次多图） | sequential | | files.maxUploadCount | 单次上传数量上限 | 10 | | files.maxSizeMB | 各类文件大小上限（MB） | image 20 / video 200 / doc 50 / table 50 | | files.sharedByDefault | 跨会话共享默认开关 | false | | files.sharedRetentionHours | 共享附件保留时长（小时） | 168 | | parse.resultMaxChars | 结果注入主流程的最大字符数 | 32768 | | cache.enabled | 附件分析结果缓存 | true |

「环境诊断」卡片可在不改表单的情况下：查看环境状态、按平台复制安装命令、一键测试视觉连接、查看最近 50 条诊断日志。

使用

1. 输入框左侧点「表格/文档/图片/视频」选择文件（可勾选「跨会话共享」），附件引用自动插入草稿；
2. 发送后，Agent 思考时先调用 inspect_attachment 获取概览，再按问题调用 analyze_attachment 获取明细；
3. 文本类文件本地解析（零模型 token）；图片/视频需先配置视觉模型，否则返回 FVF_2001；
4. 同一附件重复提问命中缓存，不重复消耗视觉 API。

常见问题

• ffmpeg 没装能识别视频吗？ 能。插件内置 ffmpeg-static，环境诊断会显示 ffmpeg: bundled (ffmpeg-static)；也可用 FFMPEG_PATH 环境变量指向自定义二进制。
• pnpm install 报 ERR_PNPM_IGNORED_BUILDS？ 本仓库 pnpm-workspace.yaml 已放行 esbuild 与 ffmpeg-static 构建脚本。
• pdf-parse 加载报错？ 本插件走 pdf-parse/lib/pdf-parse.js 入口（其主入口有 npm 打包缺陷，require 时会读不存在的测试 PDF）。
• Windows 下 CSV 乱码？ CSV 先按严格 UTF-8 解码，失败自动回退 GBK；CRLF 换行已归一化。
• 图片/视频识别失败 FVF_2001？ 未配置视觉模型，请在插件配置填写 baseURL/apiKey/model 后用「测试视觉连接」验证。

开发

pnpm install
pnpm build      # tsc 类型检查 + tsdown 双端打包（lib/index.mjs + lib/client.mjs）
pnpm typecheck

产物：lib/index.mjs（宿主端：工具/路由/存储/解析/视觉）、lib/client.mjs（浏览器端：上传按钮/环境诊断卡片）。

CI（.github/workflows/ci.yml）：build-and-test 在 ubuntu 上执行 pnpm install --frozen-lockfile → pnpm build → pnpm test；打 v* tag 时 publish job 额外执行 npm publish（需 NPM_TOKEN secret）。dsh-plugin-desktop 仅是类型 devDependency——本插件从不运行/打包它，仅 import type 使用其 profile-service 类型，构建产物 lib/*.mjs 与 lib/*.d.mts 对其零引用。pnpm 会因 auto-install-peers 拉入它声明的 electron peer，故 CI 设 ELECTRON_SKIP_BINARY_DOWNLOAD=1（并禁 HUSKY），pnpm-workspace.yaml 的 allowBuilds 亦显式 electron: false，确保不在 CI/本机构建或下载 electron 二进制。

目录结构

src/
  index.ts                      宿主入口：inspect_attachment / analyze_attachment 工具 + 诊断路由
  config-resolve.ts             配置 Schema（视觉模型/文件限制/解析/缓存/共享）
  desktop-compat.ts             DSH Desktop 兼容层（desktopProfiles 探测 + profile 作用域存储解析）
  file-store.ts                 附件存储（sha256 内容寻址，会话级/共享级）
  file-types.ts                 文件分类（表格/文档/图片/视频）
  parsers.ts                    Excel/PDF/Word/CSV/TXT/MD 解析（含 GBK/CRLF 归一化）
  vision-client.ts              OpenAI 兼容视觉客户端（含缓存）
  video.ts                      ffmpeg 探测/抽帧（ffmpeg-static 内置）
  platform.ts                   跨平台环境自检
  diagnostics.ts                诊断日志（JSONL）
  attach-routes.ts              上传 / 回显 / 环境 / 测试视觉 / 诊断 路由
  client/
    index.ts                    客户端入口（槽位注册）
    upload-buttons.tsx          分类上传按钮 + 共享开关
    environment-diagnostics-card.tsx  配置页环境诊断卡片
    attach.ts                   上传客户端 + 草稿插入
    locales.ts                  中英文案
docs/
  PRD-dsh-file-vision.md        需求文档（含跨平台与环境自检设计）

开源

• 许可证：Apache-2.0（见 LICENSE）
• 需求文档：docs/PRD-dsh-file-vision.md
• 本目录为独立 git 仓库，可直接作为插件包提交到 DSH 插件仓库。

License

Apache-2.0