@wszhoho/dsh-file-attachment 0.5.1 → 0.5.3

package/README.md

@@ -1,20 +1,27 @@
 # dsh-file-attachment
 
-DeepSeek Harness (dsh) web GUI 插件：在会话输入框中**拖入或 Ctrl+V 粘贴文档（支持多文件，一次可拖入/粘贴多个文件）**时，浏览器端批量读取全文，保存到**当前会话工作区根目录下的 `.dsh-file-attachment/`**，并在输入框光标处插入 `@<保存副本绝对路径>` 引用。agent 读取 `@路径` 时直接读到落盘副本，不再依赖原始文件位置。
+DeepSeek Harness (dsh) web GUI 插件：在会话输入框中**拖入或 Ctrl+V 粘贴文档/图片（支持多文件，一次可拖入/粘贴多个文件）**、或通过 **📎 附件按钮上传**时，浏览器端批量读取全文，保存到**当前会话工作区根目录下的 `.dsh-file-attachment/`**，并在输入框光标处插入 `@<保存副本绝对路径>` 引用。agent 读取 `@路径` 时直接读到落盘副本，不再依赖原始文件位置。
 
-图片文件由插件接管后走 dsh web 既有草稿图片流程（`addImages`）：不落盘、不进文件条、不缩放；仅当输入框未就绪且为纯图片时，才原样交回原生。
+图片与文档走**同一条落盘管线**：图片在输入框**内联附件条**中以缩略图预览（点击放大），在聊天区渲染为**可点击放大的缩略图**；文档在附件条中以类型图标 + 文件名条目显示，在聊天区保持芯片样式。当前会话模型不支持多模态时，图片自动调用**可配置 VLM** 识别生成中文描述回填草稿，文本模型也能「看懂」图片。
 
-另外，输入框工具栏（加号之后）提供了一个**上传按钮（📎 回形针图标）**，点击后弹出系统文件选择框，可多选文档/图片，复用与拖入/粘贴完全一致的落盘 + `@路径` 插入管线。PC 与移动端浏览器均适用（移动端走原生文件选择器）。
+插件接管 dsh 原生 **📎 附件上传按钮**（hero / composer 两种输入模式共用同一位置：加号右侧、modes 左侧），点击后弹出系统文件选择框，可多选文档/图片，复用与拖入/粘贴完全一致的落盘 + `@路径` 插入管线。PC 与移动端浏览器均适用（移动端走原生文件选择器）。
 
 ## 界面
 
-**演示**：拖入/粘贴文档 → 落盘并在输入框插入 `@` 引用 → 输入框上方 dock 文件条待发送状态（完整流程见 gif）。
+**演示**：拖入/粘贴文档或图片 → 落盘并在输入框插入 `@` 引用 → 输入框内联附件条待发送状态（完整流程见 gif）。
 
 ![插件演示](docs/demo.gif)
 
-**上传按钮**：输入框工具栏 `+` 之后的 📎 回形针图标，点击弹出系统文件选择框（可多选文档/图片）。
+**内联附件条**：上传后在 composer 卡片内部、编辑区上方显示——图片为缩略图（点击放大），文档为类型图标 + 文件名条目；条目可移除（同步清除草稿中对应 `@引用`），发送后自动清空。
 
-**可上传类型设置**：「设置 → 文件附件」页可按 文档 / 代码 / 配置文件 三类增删扩展名（小写、不带点），图片恒可发送。
+**聊天区图片缩略图**：历史对话中用户消息里的 `@图片路径` 渲染为缩略图（点击打开 Lightbox 放大层）；`@文件路径` 保持芯片样式。
+
+**上传按钮**：接管 dsh 原生 📎 附件按钮（加号右侧、modes 左侧），点击弹出系统文件选择框（可多选文档/图片）。
+
+**设置页**：「设置 → 文件附件」页两部分：
+
+- **可上传类型**：按 文档 / 代码 / 配置文件 三类增删扩展名（小写、不带点），图片恒可发送；
+- **多模态识别参数（VLM）**：Base URL / API Key / 模型 / 思考模式开关（默认禁用），仅当前会话模型不支持多模态时调用，未填 API Key 时静默跳过。
 
 ![可上传类型设置](docs/settings-file-types.png)
 
@@ -22,14 +29,15 @@ DeepSeek Harness (dsh) web GUI 插件：在会话输入框中**拖入或 Ctrl+V
 
 | 操作 | 行为 |
 | --- | --- |
-| 点击**上传按钮（📎）**，在系统文件选择框中**多选**文档/图片 | 与拖入/粘贴同一管线：文档 → 落盘 + 光标插入全部 `@` 路径；图片 → 走既有草稿图片流程；`accept` 限定图片 + 常见文档扩展名，移动端自动弹出文件选择器 |
-| 拖入/粘贴 **文档/代码/配置文件**（非图片，默认 doc·code·config 三类扩展名，如 docx/xlsx/pdf/md/txt/js/json） | 浏览器读全文 → base64 → 宿主落盘 `<会话工作区>/.dsh-file-attachment/<日期>/<文件名>` → 光标插入 `@绝对路径`，成功不提示、失败简短 toast |
+| 点击 **📎 附件按钮**（插件接管 dsh 原生按钮），在系统文件选择框中**多选**文档/图片 | 与拖入/粘贴同一管线：图片与文档统一落盘 + 光标插入全部 `@` 引用；移动端自动弹出文件选择器 |
+| 拖入/粘贴 **文档/代码/配置文件**（默认 doc·code·config 三类扩展名，如 docx/xlsx/pdf/md/txt/js/json） | 浏览器读全文 → base64 → 宿主落盘 `<会话工作区>/.dsh-file-attachment/<日期>/<文件名>` → 光标插入 `@绝对路径` chip，成功不提示、失败简短 toast |
 | 一次拖入/粘贴 **多个文件**（支持多文件） | 批量处理：逐个读取全文 → base64 → 落盘 → 在光标处一次性插入全部 `@` 引用；全部成功不提示，部分失败仅简短提示「N 个已跳过」 |
+| 拖入/粘贴 **图片** | 与文档同一落盘管线：插入 `@绝对路径` 引用 + 附件条登记缩略图；聊天区渲染为可点击放大的缩略图 |
+| 图片需要被理解，而当前模型**不支持多模态** | 粘贴/上传图片时自动调用可配置 VLM（OpenAI 兼容 `chat/completions`）生成中文描述回填草稿（仅注入模型上下文，不进对话界面）；agent 也可主动调用 `describe_image` 工具识别已落盘图片（含历史消息中的 `@图片` 引用） |
 | 拖入 **目录** | 拒绝，toast 提示「不支持拖入目录」，不插入引用 |
-| 拖入/粘贴 **图片** | 接管后走 dsh 既有草稿图片流程（`addImages`）：不落盘、不进文件条、不缩放；输入框未就绪且纯图片时原样交原生 |
 | 粘贴 **纯文本**（含从地址栏复制的目录路径字符串） | 不改写，完全原生行为 |
 | 重复拖入同名文件（同一天内） | 追加 `-1`、`-2` 序号，绝不覆盖 |
-| 点文件条（dock）`×` 移除 | 移除 dock 条目，并清除输入框中指向该文件路径的**全部** `@` 引用 chip（同一文件拖入多次产生的多个 chip 一并清除）；其他文件的引用不受影响 |
+| 点附件条 `×` 移除 | 移除附件条目，并清除输入框中指向该文件路径的**全部** `@` 引用 chip（同一文件上传多次产生的多个 chip 一并清除）；其他文件的引用不受影响 |
 | 单文件 > 50MB | 跳过并提示 |
 
 ### 文件命名
@@ -82,21 +90,30 @@ packages/dsh-file-attachment/
 ├── package.json          # dsh.client 声明 + bundle patch 指向
 ├── cordis.patch.yml      # bundle 补丁：插入本插件行
 └── lib/
-    ├── index.js          # Host 半：webServer 路由（POST /dsh-file-attachment/save），node:fs/promises 写盘
-    └── client.js         # Client 半：document 级 capture drop/paste/dragenter 监听 + 槽组件
+    ├── index.js          # Host 半：webServer 路由（/save /config /describe）+ describe_image 工具
+    └── client.js         # Client 半：document 级 capture drop/paste 监听 + 📎 按钮接管 + 槽组件
 ```
 
-- **Host 半**：`webServer.register` 前缀路由 `/dsh-file-attachment`，POST `/dsh-file-attachment/save` 接收 `{name, data(base64), sessionId}`，base64 解码后用 `node:fs/promises` 写盘到会话工作区 `.dsh-file-attachment/`，返回 `{ok, value:{path,dir,name,size}}`。
-- **Client 半**：`conversation.input.dock`（list 槽，同步桥状态，不渲染文本；经会话作用域取输入机，hero 首轮空白态也挂载）+ `shell.overlay`（list 槽，toast 通知展示）+ `conversation.input.left`（list 槽，**上传按钮**，渲染为左动作簇第 3 项），document 级 capture 监听先于应用 bubble 监听执行。
-- **上传按钮**：`FaUploadButton` 组件注入 `conversation.input.left`（`order:10`），内部是隐藏 `<input type="file" multiple accept>`（`accept` 限定 `image/*` + 常见文档扩展名），点击触发原生选择框；`onChange` 按 `file.type` 是否为 `image/` 分派到 `runBatch`（文档落盘插 `@`、图片走草稿图片流程），完成后清空 `input.value` 以便重复选择同一文件。图标为内联 SVG 回形针（📎，`stroke=currentColor`，随主题变色）。
+- **Host 半**：`webServer.register` 前缀路由 `/dsh-file-attachment`：
+  - POST `/save`：接收 `{name, data(base64), sessionId}`，base64 解码后用 `node:fs/promises` 写盘到会话工作区 `.dsh-file-attachment/`，返回 `{ok, value:{path,dir,name,size}}`；
+  - GET/POST `/config`：读写插件配置（可上传类型 + VLM 参数）；
+  - POST `/describe`：接收 `{dataUrl, prompt}`，调 VLM（OpenAI 兼容 `chat/completions`）识别图片，返回中文描述；
+  - `describe_image` 工具（Host 注册）：agent 需要理解 `@图片` 引用时调用——读已落盘图片 → VLM 识别 → 描述直接作为工具输出返回（UI 展示 + 模型可见）。
+- **Client 半**槽位：
+  - `conversation.input.attachments`（shadow 原生附件条，priority -100）：**内联附件条**，渲染自维护的附件登记表——图片为 data URL 缩略图（点击放大）、文档为类型图标 + 文件名；条目可移除（同步清除草稿 `@引用`），发送后自动清空，不依赖 dsh 附件草稿链路（文本模型可正常发送）；
+  - `conversation.chat.node` keyed `user`（shadow 原生用户消息渲染器，priority -100）：聊天区 `@图片路径` 渲染为缩略图（经宿主 `/api/file?path=` 读取落盘图片，点击打开 Lightbox 放大层），`@文件路径` 保持芯片样式；原生 image/file 附件块（多模态模型场景）仍交 dsh 渲染；
+  - `conversation.input.dock`：仅保留 `FaBridge` 桥槽（经会话作用域同步 shell/actions/input 状态，hero 首轮空白态也挂载），原文件条渲染已移除；
+  - `shell.overlay`（list 槽，toast 通知展示）。
+  - **📎 按钮接管**：capture 阶段拦截原生 `fileInput` 的 change 事件，文件进入插件自定义管线（图片/文档统一落盘 + 插 `@引用`）；纯文本粘贴完全原生，不做改写。document 级 capture 监听先于应用 bubble 监听执行。
 - **通知**：`shell.overlay` frame-wide 浮动 toast（不参与文档流，不破坏布局），4 秒自动消失。
 - **浮层**：拖入任何文件时 capture 阶段拦截应用自带「拖入图片…」DropOverlay（文案面向图片，对文档是误导）。
 
 ## 开发说明
 
 - `lib/*.js`、`package.json`、`cordis.patch.yml`、`README.md` 当前均为 **UTF-8 无 BOM**（以仓库实测为准）；编辑时保持原编码，不引入 BOM。
-- Host 半用 `webServer.register({ kind: 'prefix', path: '/dsh-file-attachment', handler })` 收文件，纯 ESM 无构建，不依赖装饰器/远程反射。
+- Host 半用 `webServer.register({ kind: 'prefix', path: '/dsh-file-attachment', handler })` 提供 `/save`、`/config`、`/describe` 三个路由，并经 `tools.register` 注册 `describe_image` 工具；纯 ESM 无构建，不依赖装饰器/远程反射。
 - Client 半保存用 `fetch('/dsh-file-attachment/save', { method: 'POST', body: JSON.stringify({ name, data, sessionId }) })`，信封为 `{ ok, value | error }`。
+- VLM 走 OpenAI 兼容 `chat/completions`（Base URL / API Key / 模型 / 思考模式可在设置页配置，默认关闭思考模式）；未填 API Key 时识别静默跳过，不影响落盘。
 - 项目根 = 会话工作区（`session.header.cwd` → `sandboxPolicy.workspaceRoot` → `process.cwd()` 兜底）。
 - 50MB 上限两侧一致（client 跳过 + host 校验）。
 

package/lib/client.js

@@ -40,7 +40,7 @@ window.__ModuleLoader__.load({
 		let noticeTimer = null
 		const NOTICE_MS = 4000
 		const MAX_BYTES = 50 * 1024 * 1024
-		const MAX_DIM = 640 // 图片缩放：最长边上限（GIF 例外，原样保动画）
+		const MAX_DIM = 640 // 图片缩放：宽或高任一边 >640 时等比缩小（GIF 例外，原样保动画）
 		// 可上传类型（三类：文档/代码/配置文件）；图片恒允许（image/*）。
 		// 首启为默认值，apply/设置页 fetch 持久化配置（~/.dsh/file-attachment.json）后覆盖。
 		const DEFAULT_TYPES = {
@@ -268,7 +268,7 @@ window.__ModuleLoader__.load({
 			throw new Error(errMsg)
 		}
 
-		// ---- 图片处理：扩展名 / GIF 判定 / 加载 / 缩放（≤MAX_DIM，GIF 原样保动画，PNG 保透明） ----
+		// ---- 图片处理：扩展名 / GIF 判定 / 加载 / 缩放（宽或高任一边 >MAX_DIM 时处理，GIF 原样保动画，PNG 保透明） ----
 		function fileExt(name) {
 			const s = String(name == null ? '' : name)
 			const dot = s.lastIndexOf('.')
@@ -286,7 +286,7 @@ window.__ModuleLoader__.load({
 				img.src = url
 			})
 		}
-		// 缩放：最长边 > maxDim 时等比缩小；返回 { data, name }（data 为 Blob/File）。
+		// 缩放：宽或高任一边 > maxDim 时等比缩小（两边都不超过 maxDim 时原样）；返回 { data, name }（data 为 Blob/File）。
 		// GIF 原样（canvas 取首帧丢动画 + 不支持 gif 输出）；PNG 输出 PNG 保透明；其余 JPEG 0.85。
 		// 缩放失败/无需缩放时回退原文件。
 		async function downscaleImage(file, maxDim) {
@@ -565,10 +565,11 @@ window.__ModuleLoader__.load({
 				const it = pending[i]
 				try {
 					if (it.isImage) {
-						// 图片：落盘 → @路径 纯文本 + 附件条登记（方案 B：走文件引用链路，
-						// 不触发 dsh 的 image 能力检查，文本模型可正常发送到历史）
-						const data = it.file
-						const name = it.name
+						// 图片：落盘前等比缩小（宽或高任一边 >MAX_DIM 才处理；GIF 原样保动画），
+						// 再走 @路径 纯文本 + 附件条登记（方案 B：不触发 dsh 的 image 能力检查）
+						const sized = await downscaleImage(it.file, MAX_DIM)
+						const data = sized.data
+						const name = sized.name
 						if (data === null || typeof data.size !== 'number' || data.size === 0) throw new Error('size')
 						if (data.size > MAX_BYTES) throw new Error('size')
 						const buf = await data.arrayBuffer()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wszhoho/dsh-file-attachment",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "文件附件：拖拽/粘贴/上传文件（支持多文件）；图片与文档统一落盘到 .dsh-file-attachment 并以 @绝对路径 引用发送（文本模型可正常使用）；输入框内联显示图片缩略图预览与文件条目，聊天区图片同样渲染为可点击放大的缩略图、文件保持芯片样式；非多模态模型下图片自动调用可配置 VLM 识别生成中文描述回填草稿；文档/代码/配置文件可上传类型可在设置页配置；支持 PC 与移动端浏览器",
   "keywords": [
     "dsh",