@kiwifruit/dsh-jit-viewer
DSH 平台插件 —— 在对话流中直接预览本机文档（PDF / Word / Excel / PPT / OFD / TXT / MD / CSV / HTML / 图片 / 视频），基于 jit-viewer SDK。
安装
dsh plugin --profile web add @kiwifruit/dsh-jit-viewer
本包声明 dsh.bundle.patch 与 dsh.client.platform，安装后自动进入 bundle 层与 Web client 装载，重启 dsh web 生效。
Model Experience（给模型的话）
当用户要求查看某个文档 / 文件，或你在了解上下文时需要打开某份文档时，调用 preview_document 工具来在界面中预览它，不要用 read / 文本类工具读取二进制文档（会报二进制错）。
- 支持：
pdf、docx、doc、xlsx、xls、pptx、ppt、ofd、txt、md、markdown、csv、html、htm、png、jpg、jpeg、gif、webp、svg、bmp、mp4、webm。
- 传入该文档的本地完整路径（
file）；可选 filename 覆盖预览标题。
- 若工具返回
ok:false（不支持类型 / 非法路径），直接告知用户"无法预览该文件"，不要自行解析。
- 预览由客户端打开浮窗渲染，你只需返回预览已触发的结果。
能力
- 模型工具
preview_document：注册到工具表，schema 校验必填 file，返回规范 JSON。
- 预览浮窗（Client bundle）：
preview_document 工具卡上的「预览」按钮 → 全屏浮窗，经宿主 HTTP 端点取文件并以 jit-viewer 渲染。随包内置 jit-viewer.min.js，离线可用。
- 持久 Host↔Client 通道：
webServer exact 路由：
GET /api/jit-viewer/pending-preview —— 当前已准入的待预览目标，返回 { file, name, type, previewMode }GET /api/jit-viewer/file?path= —— 从本地读取文件（带 safeServePath 校验：拒绝空 / NUL / .. 段），支持 Range 请求
配置
| 配置项 | 类型 | 默认 | 说明 |
|---|
theme | "light" | "dark" | "light" | 客户端查看器默认主题 |
配置经 Config（schemastery schema）校验，非法配置 fail loud，插件不启动。
扩展点与依赖
- 服务依赖：
tools、systemPrompt（硬，inject 声明）；webServer（可选）。
webServer 只在 web profile 下存在，所以不能写进 inject——那是硬依赖，非 web 宿主下 fiber 会一直 PENDING。- 可选服务的正确读法是
ctx.get('webServer') + 判空降级。不能写成 ctx.webServer：ctx 是 Proxy，读到未声明的服务名会直接抛 cannot get property "webServer" without inject，后面的判空永远执行不到。
- 无 webServer 时插件照常注册
preview_document，只是不挂 HTTP 端点（降级为无浏览器预览）。
- Client slots：
tool.call.toolview（key preview_document）、shell.overlay（id jit-viewer-preview）。
- 运行依赖以
peerDependencies 声明（@deepseek-ai/cordis / dsh-client-runtime）。
命令
npm install
npm run typecheck # tsc --noEmit
npm run build:host # tsc emit → lib/index.js + lib/index.d.ts（ESM）
npm run build:client # tsdown --config tsdown.client.config.ts → lib/client.js（CJS browser）
npm run build # typecheck + build:host + build:client
发布检查
License
Apache-2.0
