@kiwifruit/dsh-jit-viewer

Readme

# @kiwifruit/dsh-jit-viewer

DSH 平台插件 —— 在对话流中直接预览本机文档（PDF / Word / Excel / PPT / OFD / TXT / MD / CSV / HTML / 图片 / 视频），基于 [jit-viewer](https://github.com/kiwifruit13/jit-viewer-sdk-main) SDK。

## 安装

```bash
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`）。

## 命令

```bash
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
```

## 发布检查

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

## License

Apache-2.0