@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

发布检查

• 命名导出 name / inject / Config / apply
• main / types / exports 指向 lib/ 产物
• cordis.patch.yml 用 scoped 包名 insert
• files 只含运行入口 / 声明 / patch
• 注册全部可逆（经 ctx.effect）

License

Apache-2.0