@wszhoho/dsh-file-attachment 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ DeepSeek Harness (dsh) web GUI 插件：在会话输入框中**拖入或 Ctrl+V
 
 图片文件由插件接管后走 dsh web 既有草稿图片流程（`addImages`）：不落盘、不进文件条、不缩放；仅当输入框未就绪且为纯图片时，才原样交回原生。
 
-另外，输入框工具栏（加号之后）提供了一个**上传按钮（📎 回形针图标）**，点击后弹出系统文件选择框，可多选文档/图片，复用与拖入/粘贴完全一致的落盘 + `@路径` 插入管线。PC 与移动端浏览器均适用（移动端走原生文件/拍照选择器）。
+另外，输入框工具栏（加号之后）提供了一个**上传按钮（📎 回形针图标）**，点击后弹出系统文件选择框，可多选文档/图片，复用与拖入/粘贴完全一致的落盘 + `@路径` 插入管线。PC 与移动端浏览器均适用（移动端走原生文件选择器）。
 
 ## 界面
 
@@ -14,11 +14,15 @@ DeepSeek Harness (dsh) web GUI 插件：在会话输入框中**拖入或 Ctrl+V
 
 **上传按钮**：输入框工具栏 `+` 之后的 📎 回形针图标，点击弹出系统文件选择框（可多选文档/图片）。
 
+**可上传类型设置**：「设置 → 文件附件」页可按 文档 / 代码 / 配置文件 三类增删扩展名（小写、不带点），图片恒可发送。
+
+![可上传类型设置](docs/settings-file-types.png)
+
 ## 行为一览
 
 | 操作 | 行为 |
 | --- | --- |
-| 点击**上传按钮（📎）**，在系统文件选择框中**多选**文档/图片 | 与拖入/粘贴同一管线：文档 → 落盘 + 光标插入全部 `@` 路径；图片 → 走既有草稿图片流程；`accept` 限定图片 + 常见文档扩展名，移动端自动弹出文件/拍照选择器 |
+| 点击**上传按钮（📎）**，在系统文件选择框中**多选**文档/图片 | 与拖入/粘贴同一管线：文档 → 落盘 + 光标插入全部 `@` 路径；图片 → 走既有草稿图片流程；`accept` 限定图片 + 常见文档扩展名，移动端自动弹出文件选择器 |
 | 拖入/粘贴 **文档/代码/配置文件**（非图片，默认 doc·code·config 三类扩展名，如 docx/xlsx/pdf/md/txt/js/json） | 浏览器读全文 → base64 → 宿主落盘 `<会话工作区>/.dsh-file-attachment/<日期>/<文件名>` → 光标插入 `@绝对路径`，成功不提示、失败简短 toast |
 | 一次拖入/粘贴 **多个文件**（支持多文件） | 批量处理：逐个读取全文 → base64 → 落盘 → 在光标处一次性插入全部 `@` 引用；全部成功不提示，部分失败仅简短提示「N 个已跳过」 |
 | 拖入 **目录** | 拒绝，toast 提示「不支持拖入目录」，不插入引用 |

package/lib/client.js

@@ -49,9 +49,10 @@ window.__ModuleLoader__.load({
 			config: ['json', 'yml', 'yaml', 'toml', 'ini', 'conf', 'cfg', 'env', 'properties', 'xml', 'html', 'css'],
 		}
 		const allowedTypes = { doc: DEFAULT_TYPES.doc.slice(), code: DEFAULT_TYPES.code.slice(), config: DEFAULT_TYPES.config.slice() }
+		// 多模态 VLM 识别参数（仅当前模型非多模态时调用）：baseURL/apiKey/model/thinkingType
+		let vlmCfg = { baseURL: 'https://api.xiaomimimo.com/v1', apiKey: '', model: 'mimo-v2.5', thinkingType: 'disabled' }
 		let allowedExts = null // Set<ext>，rebuildAllowed 填充；上传校验用
-		let acceptString = 'image/*' // 上传按钮 <input accept>，buildAccept 生成
-		const acceptListeners = new Set() // accept 变化订阅（设置页保存 → 上传按钮重渲染）
+		let acceptString = 'image/*' // 文件选择器 <input accept>，buildAccept 生成；劫持📎打开前赋值
 		// 规范化扩展名列表（小写/去点/去重/仅 [a-z0-9]），与 host 侧同逻辑
 		function normalizeList(arr) {
 			const out = []
@@ -71,20 +72,90 @@ window.__ModuleLoader__.load({
 			allowedExts = set
 		}
 		function buildAccept() {
-			const parts = ['image/*']
-			const set = new Set()
-			for (const key of ['doc', 'code', 'config']) for (const ext of allowedTypes[key]) set.add(ext)
-			for (const ext of set) parts.push('.' + ext)
-			return parts.join(',')
+			// 默认所有文件类型可见（浏览器文件选择器不按扩展名过滤）；
+			// 扩展名白名单校验在 runBatch 阶段执行（不在允许列表则 announce 拒绝）。
+			return '*/*'
+		}
+		// ---- 劫持 dsh 原生📎按钮（hero / composer 两模式同一 InputBar，按钮都在加号右侧、modes 左侧）----
+		// 插件不再渲染自己的上传按钮；而是 capture 阶段拦截原生📎 click，改走本插件文件选择器，
+		// ---- 接管 dsh 原生📎：上传入口位于与 dsh 本体完全一致的位置（hero/composer 两模式同一按钮）----
+		// 方案：不劫持📎 click（原生 onClick 会打开 dsh 自己的 fileInput，files 可靠），
+		// 改为劫持 dsh 原生 fileInput 的 change 事件（元素级监听先于 React 冒泡，stopImmediatePropagation 阻断 onPickFiles），
+		// 读 files 后改走本插件 runBatch 管线。修复：自建隐藏 input 的 files 在某些浏览器返回空（count:0）导致上传失效。
+		const hijackedInputs = new WeakSet() // 已挂拦截的原生 fileInput
+		let uploadBusy = false // 文件选择中防重入
+		const nativeFileInputSelector = '[data-composer-card] input[type="file"], [data-composer-card] input[type=file]'
+		function onNativeFileChange(e) {
+			const el = e.currentTarget
+			if (el === null || el === void 0) return
+			const list = el.files
+			if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] native fileInput change', { count: list === null ? 0 : list.length })
+			if (list === null || list.length === 0) return
+			e.preventDefault()
+			e.stopImmediatePropagation()
+			// FileList 是活对象：el.value='' 会把它清空（length 变 0），必须先快照成数组
+			const files = Array.prototype.slice.call(list)
+			try { el.value = '' } catch (err) { /* 忽略 */ }
+			const images = []
+			const docs = []
+			for (let i = 0; i < files.length; i++) {
+				const f = files[i]
+				if (f.type && f.type.indexOf('image/') === 0) { images.push(f); continue }
+				docs.push({ path: null, name: f.name, isDir: false, file: f })
+			}
+			if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] native change classified', { images: images.length, docs: docs.length })
+			if (images.length === 0 && docs.length === 0) return
+			uploadBusy = true
+			try {
+				runBatch(images, docs).catch((err) => {
+					console.error('[dsh-file-attachment] runBatch rejected:', err)
+					announce('文件处理失败: ' + (err !== null && err !== void 0 && err.message ? err.message : String(err)))
+				})
+			} finally { uploadBusy = false }
+		}
+		function hijackFileInput(el) {
+			if (hijackedInputs.has(el)) return
+			hijackedInputs.add(el)
+			el.addEventListener('change', onNativeFileChange)
+		}
+		function installNativeAttachHijack() {
+			if (typeof document === 'undefined' || document.body === null || document.body === undefined) return
+			let body
+			try { body = document.body } catch (err) { return }
+			if (!(body instanceof Node)) return
+			const scan = () => {
+				let all = []
+				try { all = Array.from(body.querySelectorAll(nativeFileInputSelector)) } catch (err) { all = [] }
+				for (let i = 0; i < all.length; i++) hijackFileInput(all[i])
+			}
+			scan()
+			const mo = new MutationObserver(() => scan())
+			try { mo.observe(body, { childList: true, subtree: true }) } catch (err) { /* 忽略 */ }
+			// 兜底定时重扫：MutationObserver 偶发漏报（如同一帧内大段替换）时保底
+			const timer = setInterval(scan, 1500)
+			return { mo, timer }
 		}
-		// 应用配置：更新 allowedTypes → 重建校验 Set + accept → 通知上传按钮重渲染
+		// 客户端侧多模态参数规范化（空值回退默认，与 host normalizeMimo 一致）
+		function normalizeVlmClient(raw) {
+			const d = { baseURL: 'https://api.xiaomimimo.com/v1', apiKey: '', model: 'mimo-v2.5', thinkingType: 'disabled' }
+			if (raw === null || typeof raw !== 'object') return d
+			const pick = (k) => (typeof raw[k] === 'string' && raw[k] !== '') ? raw[k] : d[k]
+			return { baseURL: pick('baseURL'), apiKey: pick('apiKey'), model: pick('model'), thinkingType: raw.thinkingType === 'enabled' ? 'enabled' : 'disabled' }
+		}
+		// 应用配置：更新 allowedTypes → 重建校验 Set + accept（劫持📎在打开选择器时读取 acceptString）
 		function applyConfig(cfg) {
-			allowedTypes.doc = normalizeList(cfg && cfg.doc)
-			allowedTypes.code = normalizeList(cfg && cfg.code)
-			allowedTypes.config = normalizeList(cfg && cfg.config)
+			// 空数组/未配置 → 回退默认类型（否则 config 空数组会清空 allowedTypes，文档全被拒）
+			allowedTypes.doc = pickTypes(cfg && cfg.doc, DEFAULT_TYPES.doc)
+			allowedTypes.code = pickTypes(cfg && cfg.code, DEFAULT_TYPES.code)
+			allowedTypes.config = pickTypes(cfg && cfg.config, DEFAULT_TYPES.config)
+			vlmCfg = normalizeVlmClient(cfg && (cfg.vlm || cfg.mimo))
 			rebuildAllowed()
 			acceptString = buildAccept()
-			for (const fn of acceptListeners) { try { fn() } catch (err) { /* 忽略订阅者异常 */ } }
+		}
+		// 配置优先：list 规范化后非空则采用，否则回退默认（allow all 由设置页传 '*' 表达）
+		function pickTypes(list, fallback) {
+			const n = normalizeList(list)
+			return n.length > 0 ? n : fallback.slice()
 		}
 		// 拉取持久化配置；成功覆盖默认，失败保留默认。幂等（复用同一 Promise）
 		let configPromise = null
@@ -146,7 +217,7 @@ window.__ModuleLoader__.load({
 			const isTarget = (oc) => oc.ref === plain || oc.ref === quoted
 				|| (oc.clipboardText !== void 0 && (oc.clipboardText === plain || oc.clipboardText === quoted))
 			for (let n = 0; n < 64; n++) {
-				const snap = shell.snapshot
+				const snap = readShellSnapshot(shell)
 				if (snap === null || snap === void 0 || typeof snap.draft !== 'string') break
 				// 发送进行中不动草稿（此时 occurrence 会随发送完成清空）
 				if (snap.phase === 'adjudicating' || snap.phase === 'submitting') break
@@ -300,10 +371,25 @@ window.__ModuleLoader__.load({
 			return seg
 		}
 
-		// 找可写的 composer textarea：可见、未禁用、未只读、phase 为 plain；
-		// 多个候选时优先 value 与桥内草稿一致的那一个（排除审批弹窗里的同名元素）
-		function findComposerTextarea() {
-			const list = Array.from(document.querySelectorAll('[data-composer-card] textarea'))
+		// 输入机快照读取：兼容两代 dsh。
+		// 旧版（纯文本机，alpha.2 之前）：shell.snapshot 直接是 InputState；
+		// 新版（Lexical composer，alpha.2 起）：shell.state 是 SnapshotStore，经
+		// getSnapshot() 取值（字段不变：draft/draftRev/phase/occurrences）。
+		function readShellSnapshot(shell) {
+			if (shell === null || shell === void 0) return undefined
+			const st = shell.state
+			if (st !== null && st !== void 0 && typeof st.getSnapshot === 'function') {
+				return st.getSnapshot()
+			}
+			return shell.snapshot
+		}
+
+		// 找可写的 composer 输入表面：可见、未禁用、未只读、phase 为 plain；
+		// 多个候选时优先文本与桥内草稿一致的那一个（排除审批弹窗里的同名元素）。
+		// 双代兼容：旧版 textarea（[data-composer-card] textarea）；
+		// 新版 Lexical contenteditable（[data-composer-card] [data-composer-input]）。
+		function findComposerInput() {
+			const list = Array.from(document.querySelectorAll('[data-composer-card] textarea, [data-composer-card] [data-composer-input]'))
 			const live = list.filter((ta) => {
 				if (ta.disabled || ta.readOnly) return false
 				const phase = ta.getAttribute('data-phase')
@@ -312,9 +398,10 @@ window.__ModuleLoader__.load({
 			})
 			if (live.length === 0) return null
 			const draft = bridge.input !== void 0 ? bridge.input.draft : undefined
+			const textOf = (el) => (el.tagName === 'TEXTAREA' ? el.value : (el.textContent || ''))
 			if (typeof draft === 'string') {
 				for (let i = 0; i < live.length; i++) {
-					if (live[i].value === draft) return live[i]
+					if (textOf(live[i]) === draft) return live[i]
 				}
 			}
 			return live[0]
@@ -369,6 +456,7 @@ window.__ModuleLoader__.load({
 			return out
 		}
 
+		// File → dataURL（base64 data: 前缀），供 host /describe 的 VLM 识别
 		// 触发应用自身 drop 浮层的关闭：应用在 window 上监听 dragend 执行 reset()。
 		// 从 OS 拖入时浏览器不派发 dragend，且我们拦截 drop 后应用的 drop 监听收不到事件，浮层会残留。
 		function dismissDropOverlay() {
@@ -391,7 +479,15 @@ window.__ModuleLoader__.load({
 			const docs = [] // { path, name, isDir, file }
 			for (let i = 0; i < files.length; i++) {
 				const file = files[i]
-				if (file.type && file.type.indexOf('image/') === 0) { images.push(file); continue }
+				// File.type 在剪贴板截图场景下可能为空（浏览器未填充 MIME）；
+				// 回退到 DataTransferItem.type 判定，并创建带正确 MIME 的 File 副本，
+				// 确保 createDrafts 的 imageMediaType 校验通过。
+				const effType = file.type || ((items && items[i]) ? items[i].type : '') || ''
+				if (effType.indexOf('image/') === 0) {
+					// file.type 为空时用 items[i].type 补全，生成新 File 对象
+					images.push(file.type ? file : new File([file], file.name || 'image.png', { type: effType }))
+					continue
+				}
 				let entry = null
 				const item = items ? items[i] : null
 				if (item && typeof item.webkitGetAsEntry === 'function') {
@@ -414,7 +510,7 @@ window.__ModuleLoader__.load({
 				announce('输入框不可用')
 				return true
 			}
-			// 有输入桥：接管全部（图片 + 文档统一落盘 → 芯片），彻底绕开 dsh 原生图片发送流程（解 413）
+			// 有输入桥：接管全部（图片与文档统一落盘 → @引用芯片，方案 B 绕开 dsh image 能力检查）
 			e.preventDefault()
 			e.stopImmediatePropagation()
 			dismissDropOverlay()
@@ -423,14 +519,16 @@ window.__ModuleLoader__.load({
 		}
 
 		// 异步批处理：文档 + 图片统一落盘 → shell.insertReference 芯片（不显示长路径，发送还原 @ 路径）。
-		// 图片先 downscale（≤MAX_DIM，GIF 原样保动画）；目录拒绝；扩展名按配置校验（图片恒允许）。
+		// 图片不走 dsh 草稿附件链路（方案 B：文本模型被 dsh 拒绝 image 附件），改与文档同链路：落盘 → @引用 → 文件条登记。
+		// 目录拒绝；扩展名按配置校验（图片恒允许）。
 		async function runBatch(images, docs) {
 			const shell = bridge.shell
+			if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] runBatch start', { images: images.length, docs: docs.length, shell: shell === null ? 'null' : 'ok', mounted: bridge.mounted })
 			if (shell === null || typeof shell.insertReference !== 'function') {
 				announce(`输入框不可用 [mounted:${bridge.mounted} shell:${shell === null ? 'null' : 'ok'} addImg:${typeof bridge.addImages}]`)
 				return
 			}
-			const snap0 = shell.snapshot
+			const snap0 = readShellSnapshot(shell)
 			const phase = snap0 ? snap0.phase : 'plain'
 			if (phase !== 'plain' && phase !== 'command' && phase !== 'claimed') {
 				announce('输入框正忙')
@@ -465,12 +563,69 @@ window.__ModuleLoader__.load({
 				const it = pending[i]
 				try {
 					if (it.isImage) {
-						// 图片完全走 dsh 原生链路：addImages（草稿图片），不缩放/不落盘/不进文件条
-						const addImages = typeof bridge.addImages === 'function' ? bridge.addImages : null
-						if (addImages === null) { failed += 1; continue }
-						let imgErr = null; try { imgErr = addImages([it.file]) } catch (err) { imgErr = err instanceof Error ? err.message : String(err) }
-						if (imgErr) { failed += 1; continue }
-						inserted += 1
+						// 图片：落盘 → @引用芯片 + 文件条登记（方案 B：走文件引用链路，
+						// 不触发 dsh 的 image 能力检查，文本模型可正常发送到历史）
+						const data = it.file
+						const name = it.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()
+						const b64 = bytesToBase64(new Uint8Array(buf))
+						if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] before saveFileToHost', { name, b64len: b64.length })
+						const res = await saveFileToHost(name, b64, bridge.sessionId)
+						if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] saved', res.path)
+						const m = formatMention(res.path, false)
+						const clipboardText = m !== undefined ? m : '@' + res.path
+						// 文件条缩略图：data URL（图片已读入内存（buf），直接用 b64 组装，不重复读文件/不用 FileReader）
+						const mime = data.type && data.type !== '' ? data.type : 'application/octet-stream'
+						const thumbUrl = 'data:' + mime + ';base64,' + b64
+						// 每次插入前重取 snapshot（draftRev 随插入递增，span 取当前末尾）
+						const snap = readShellSnapshot(shell)
+						// 前导分隔空格：聊天记录对 @引用 的 file-chip 渲染（projectUserText）
+						// 要求 @ 前是行首或空白，而 insertReference 只在 chip 后补空格。
+						// 草稿末尾紧贴文字时先补一格，否则发送后聊天记录显示裸 @路径。
+						if (snap !== void 0 && typeof snap.draft === 'string' && snap.draft !== ''
+							&& !isSpace(snap.draft.charCodeAt(snap.draft.length - 1))) {
+							const leadSpan = { draftRev: snap.draftRev, start: snap.draft.length, end: snap.draft.length }
+							if (typeof shell.insertText === 'function') {
+								try { shell.insertText(' ', leadSpan) } catch (err) { /* 忽略：补空格失败不阻塞插入 */ }
+							} else if (typeof shell.setDraft === 'function') {
+								try { shell.setDraft(snap.draft + ' ') } catch (err) { /* 忽略 */ }
+							}
+						}
+						// 补空格会递增 draftRev，重新取快照后再定插入 span。
+						// 关键：insertReference 的 span 是 detect 坐标（编辑器实际节点坐标），
+						// draft.length 是 clipboard 投影坐标（chip 展开为 @路径 文本），草稿含 chip 时两者不一致
+						// 会导致 selectSpan 越界失败（span.end > detectLength → null → ok:false）。
+						// 用 shell.caretSpan() 拿 detect 坐标（有光标返回光标处，否则返回文档末尾）。
+						const snap2 = readShellSnapshot(shell)
+						let span
+						if (typeof shell.caretSpan === 'function') {
+							try {
+								const cs = shell.caretSpan()
+								span = { draftRev: snap2.draftRev, start: cs.start, end: cs.end }
+							} catch (err) {
+								span = { draftRev: snap2.draftRev, start: snap2.draft.length, end: snap2.draft.length }
+							}
+						} else {
+							span = { draftRev: snap2.draftRev, start: snap2.draft.length, end: snap2.draft.length }
+						}
+						const okInsert = shell.insertReference(
+							{
+								source: 'reference', // 复用内置已注册的 @引用 source（带 codec.serialize），否则报 no serializer
+								ref: clipboardText, // codec.serialize 原样返回 ref 作为模型文本，故放完整 @路径
+								label: name,
+								appearance: 'file',
+								clipboardText: clipboardText,
+							},
+							span,
+						)
+						if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] image insertReference result', { ok: okInsert, span, clipboardText, draftRev: snap2.draftRev, draftLen: snap2.draft.length })
+						if (okInsert) {
+							inserted += 1
+							// 登记到文件条（图片：data URL 缩略图 + 点击打开；发送后随 chip 清空）
+							attachFile({ id: 'fa' + (++faSeq), name, path: res.path, isImage: true, url: thumbUrl, sessionId: bridge.sessionId })
+						} else failed += 1
 						continue
 					}
 					// 文档：原样落盘 → @引用芯片 + 文件条登记
@@ -484,8 +639,35 @@ window.__ModuleLoader__.load({
 					const m = formatMention(res.path, false)
 					const clipboardText = m !== undefined ? m : '@' + res.path
 					// 每次插入前重取 snapshot（draftRev 随插入递增，span 取当前末尾）
-					const snap = shell.snapshot
-					const span = { draftRev: snap.draftRev, start: snap.draft.length, end: snap.draft.length }
+					const snap = readShellSnapshot(shell)
+					// 前导分隔空格：聊天记录对 @引用 的 file-chip 渲染（projectUserText）
+					// 要求 @ 前是行首或空白，而 insertReference 只在 chip 后补空格。
+					// 草稿末尾紧贴文字时先补一格，否则发送后聊天记录显示裸 @路径
+					//（旧版 insertTextAtCaret 的 padStart 同款保底）。
+					if (snap !== void 0 && typeof snap.draft === 'string' && snap.draft !== ''
+						&& !isSpace(snap.draft.charCodeAt(snap.draft.length - 1))) {
+						const leadSpan = { draftRev: snap.draftRev, start: snap.draft.length, end: snap.draft.length }
+						if (typeof shell.insertText === 'function') {
+							try { shell.insertText(' ', leadSpan) } catch (err) { /* 忽略：补空格失败不阻塞插入 */ }
+						} else if (typeof shell.setDraft === 'function') {
+							// 含 chip 的草稿末尾必为空白（chip 自动尾随空格），故此处必为纯文本，拼接安全
+							try { shell.setDraft(snap.draft + ' ') } catch (err) { /* 忽略 */ }
+						}
+					}
+					// 补空格会递增 draftRev，重新取快照后再定插入 span。
+					// 与图片分支同理：insertReference 的 span 须为 detect 坐标，优先 shell.caretSpan()。
+					const snap2 = readShellSnapshot(shell)
+					let span
+					if (typeof shell.caretSpan === 'function') {
+						try {
+							const cs = shell.caretSpan()
+							span = { draftRev: snap2.draftRev, start: cs.start, end: cs.end }
+						} catch (err) {
+							span = { draftRev: snap2.draftRev, start: snap2.draft.length, end: snap2.draft.length }
+						}
+					} else {
+						span = { draftRev: snap2.draftRev, start: snap2.draft.length, end: snap2.draft.length }
+					}
 					const okInsert = shell.insertReference(
 						{
 							source: 'reference', // 复用内置已注册的 @引用 source（带 codec.serialize），否则报 no serializer
@@ -498,11 +680,12 @@ window.__ModuleLoader__.load({
 					)
 					if (okInsert) {
 						inserted += 1
-						// 登记到文件条（文档：类型图标 + 点击打开；图片走原生 addImages 不登记）
+						// 登记到文件条（图片：data URL 缩略图；文档：类型图标；发送后随 chip 清空）
 						attachFile({ id: 'fa' + (++faSeq), name, path: res.path, isImage: false, url: null, sessionId: bridge.sessionId })
 					} else failed += 1
 				} catch (err) {
 					failed += 1
+					if (typeof console !== 'undefined' && console.error) console.error('[dsh-file-attachment] item failed', { name: it && it.name, isImage: it && it.isImage, error: err instanceof Error ? (err.message + '\n' + (err.stack || '')) : String(err) })
 				}
 			}
 			if (inserted === 0) {
@@ -523,12 +706,12 @@ window.__ModuleLoader__.load({
 			handleFilesEvent(e, files, dt.items, 'drop')
 		}
 
-		// document 级 paste（capture）：仅当粘贴目标就是 composer textarea 时接管文件；
+		// document 级 paste（capture）：仅当粘贴目标就是 composer 输入表面时接管文件；
 		// 纯文本（含目录路径字符串）完全原生，不改写。
 		function onPaste(e) {
 			const t = e.target
-			const ta = findComposerTextarea()
-			if (ta === null || t !== ta) return
+			const ta = findComposerInput()
+			if (ta === null || (t !== ta && !(ta.contains && ta.contains(t)))) return
 			const cd = e.clipboardData
 			if (cd === null || cd === void 0) return
 			const files = Array.prototype.slice.call(cd.files)
@@ -548,6 +731,7 @@ window.__ModuleLoader__.load({
 			react.useEffect(() => {
 				if (bridge.noticeText !== null) setText(bridge.noticeText)
 				bridge.noticeSub = setText
+				if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] FaToast mounted')
 				return () => { if (bridge.noticeSub === setText) bridge.noticeSub = null }
 			})
 			if (text === null || text === '') return null
@@ -588,8 +772,8 @@ window.__ModuleLoader__.load({
 						if (shell !== null) {
 							addImages = (files) => {
 								try {
-									const images = conversation.createDraftImages(files)
-									if (!shell.addImages(images.map((image) => image.id))) conversation.releaseDraftImages(images)
+									const drafts = conversation.createDrafts(sessionId, files)
+									if (!shell.addAttachments(drafts.map((draft) => draft.id))) conversation.releaseDraftAttachments(drafts)
 									return null
 								} catch (error) {
 									return error instanceof Error ? error.message : String(error)
@@ -599,13 +783,14 @@ window.__ModuleLoader__.load({
 					}
 				}
 			} catch (err) { shell = null; addImages = null }
-			const input = shell !== null && shell.snapshot !== void 0 ? shell.snapshot : undefined
+			const input = readShellSnapshot(shell)
 			react.useEffect(() => {
 				bridge.shell = shell
 				bridge.addImages = addImages
 				bridge.input = input
 				bridge.sessionId = sessionId
 				bridge.mounted = true
+				if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] FaBridge mounted', { sessionId, shell: shell === null ? 'null' : 'ok', addImages: typeof addImages })
 				return () => {
 					bridge.shell = null
 					bridge.addImages = null
@@ -635,12 +820,12 @@ window.__ModuleLoader__.load({
 				attachedListeners.add(fn)
 				return () => { attachedListeners.delete(fn) }
 			}, [])
-			// 发送后清空：轮询 shell.snapshot，occurrences 从有→无 即一次发送完成
+			// 发送后清空：轮询输入机快照，occurrences 从有→无 即一次发送完成
 			const hadOcc = react.useRef(false)
 			react.useEffect(() => {
 				const timer = setInterval(() => {
 					const shell = bridge.shell
-					const snap = shell ? shell.snapshot : null
+					const snap = readShellSnapshot(shell)
 					const occ = snap ? snap.occurrences : null
 					const has = !!(occ && occ.length > 0)
 					const s = bridge.sessionId
@@ -685,87 +870,6 @@ window.__ModuleLoader__.load({
 			)
 		}
 
-		// conversation.input.left 槽（操作行左侧动作区，官方扩展点）：文件上传按钮。
-		// 点击触发隐藏 <input type=file multiple>（PC/移动端原生文件选择器，accept 过滤图片+常见文档），
-		// 选中后复用既有 runBatch 管线：文档落盘→@引用插入，图片走 createDraftImages+addImages 草稿机制。
-		// 运行状态经 bridge（FaBridge 在 input.dock 槽填充 actions/input/sessionId，apply 填充 conversation）。
-		function FaUploadButton() {
-			const inputRef = react.useRef(null)
-			const busyState = react.useState(false)
-			const busy = busyState[0]
-			const setBusy = busyState[1]
-			// 订阅 accept 变化（设置页保存配置 → 重渲染，accept 属性随之刷新）
-			const [, forceAccept] = react.useState(0)
-			react.useEffect(() => {
-				const fn = () => forceAccept((n) => n + 1)
-				acceptListeners.add(fn)
-				return () => { acceptListeners.delete(fn) }
-			}, [])
-			function onClick() {
-				const el = inputRef.current
-				if (el === null || busy) return
-				el.click()
-			}
-			async function onChange(e) {
-				const list = e.target.files
-				if (list === null || list.length === 0) return
-				const images = []
-				const docs = []
-				for (let i = 0; i < list.length; i++) {
-					const file = list[i]
-					if (file.type && file.type.indexOf('image/') === 0) { images.push(file); continue }
-					docs.push({ path: null, name: file.name, isDir: false, file })
-				}
-				setBusy(true)
-				try {
-					await runBatch(images, docs)
-				} finally {
-					// 重置 input 值，允许再次选择同名文件
-					e.target.value = ''
-					setBusy(false)
-				}
-			}
-			return react.createElement('span', { style: { display: 'inline-flex', alignItems: 'center' } },
-				react.createElement('input', {
-					ref: inputRef,
-					type: 'file',
-					multiple: true,
-					accept: acceptString,
-					style: { display: 'none' },
-					onChange: onChange,
-				}),
-				react.createElement('button', {
-					type: 'button',
-					title: '上传文件',
-					'aria-label': '上传文件',
-					disabled: busy,
-					onClick: onClick,
-					style: {
-						display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
-						width: '28px', height: '28px', padding: 0, margin: 0, border: 'none',
-						// 与 dsh 输入栏加号按钮同款（InputBar.module.css .add）：全圆 + selector 填充，无阴影
-					background: 'var(--dsw-specific-selector, rgba(128,128,128,0.10))',
-					color: 'var(--dsw-alias-label-primary, currentColor)',
-						cursor: busy ? 'default' : 'pointer', borderRadius: '999px',
-						opacity: busy ? 0.45 : 1, transition: 'background 120ms ease, opacity 120ms ease',
-					},
-					onMouseEnter: (ev) => { if (!busy) ev.currentTarget.style.background = 'var(--dsw-alias-interactive-bg-hover-solid, rgba(128,128,128,0.16))' },
-					onMouseLeave: (ev) => { ev.currentTarget.style.background = 'var(--dsw-specific-selector, rgba(128,128,128,0.10))' },
-				},
-					react.createElement('svg', {
-						// 回形针按用户反馈取 12px（比加号 14px 小 2px）；描边 2/24×12≈1px
-					width: 12, height: 12, viewBox: '0 0 24 24', fill: 'none',
-						'aria-hidden': true, style: { display: 'block' },
-					},
-						react.createElement('path', {
-							d: 'm21.44 12.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48',
-							stroke: 'currentColor', strokeWidth: 2,
-							strokeLinecap: 'round', strokeLinejoin: 'round',
-						})
-					)
-				)
-			)
-		}
 
 		// 扩展名规范化：小写/去前导点/仅 [a-z0-9]；非法返回 null
 		function normExt(v) {
@@ -828,6 +932,10 @@ window.__ModuleLoader__.load({
 			const [doc, setDoc] = react.useState(DEFAULT_TYPES.doc.slice())
 			const [code, setCode] = react.useState(DEFAULT_TYPES.code.slice())
 			const [config, setConfig] = react.useState(DEFAULT_TYPES.config.slice())
+			const [vlmBaseURL, setVlmBaseURL] = react.useState('')
+			const [vlmApiKey, setVlmApiKey] = react.useState('')
+			const [vlmModel, setVlmModel] = react.useState('')
+			const [vlmThinking, setVlmThinking] = react.useState(false)
 			const [docIn, setDocIn] = react.useState('')
 			const [codeIn, setCodeIn] = react.useState('')
 			const [cfgIn, setCfgIn] = react.useState('')
@@ -841,6 +949,10 @@ window.__ModuleLoader__.load({
 					setDoc(allowedTypes.doc.slice())
 					setCode(allowedTypes.code.slice())
 					setConfig(allowedTypes.config.slice())
+					setVlmBaseURL(vlmCfg.baseURL)
+					setVlmApiKey(vlmCfg.apiKey)
+					setVlmModel(vlmCfg.model)
+					setVlmThinking(vlmCfg.thinkingType === 'enabled')
 				})
 				return () => { live = false }
 			}, [])
@@ -853,7 +965,7 @@ window.__ModuleLoader__.load({
 			async function save() {
 				setSaving(true); setSaved(false)
 				try {
-					const body = { doc: doc, code: code, config: config }
+					const body = { doc: doc, code: code, config: config, vlm: { baseURL: vlmBaseURL, apiKey: vlmApiKey, model: vlmModel, thinkingType: vlmThinking ? 'enabled' : 'disabled' } }
 					const r = await fetch('/dsh-file-attachment/config', {
 						method: 'POST',
 						headers: { 'Content-Type': 'application/json' },
@@ -876,6 +988,23 @@ window.__ModuleLoader__.load({
 				react.createElement(FaExtGroup, { title: t('doc.title'), list: doc, setList: setDoc, input: docIn, setInput: setDocIn }),
 				react.createElement(FaExtGroup, { title: t('code.title'), list: code, setList: setCode, input: codeIn, setInput: setCodeIn }),
 				react.createElement(FaExtGroup, { title: t('config.title'), list: config, setList: setConfig, input: cfgIn, setInput: setCfgIn }),
+				react.createElement('div', { style: { margin: '16px 0', padding: '12px', borderRadius: '8px', background: 'rgba(128,128,128,0.08)', border: '1px solid rgba(128,128,128,0.15)' } },
+					react.createElement('div', { style: { marginBottom: '8px', fontSize: '13px', fontWeight: '600' } }, t('vlm.title')),
+					react.createElement('div', { style: { marginBottom: '10px', fontSize: '12px', color: 'rgba(128,128,128,0.9)' } }, t('vlm.hint')),
+					react.createElement('div', { style: { display: 'grid', gridTemplateColumns: '110px 1fr', gap: '8px 10px', alignItems: 'center' } },
+						react.createElement('span', { style: { fontSize: '12px' } }, t('vlm.baseURL')),
+						react.createElement('input', { value: vlmBaseURL, onChange: (e) => setVlmBaseURL(e.target.value), placeholder: 'https://api.xiaomimimo.com/v1', style: { padding: '6px 8px', borderRadius: '6px', border: '1px solid rgba(128,128,128,0.3)', background: 'transparent', color: 'inherit', fontSize: '12px' } }),
+						react.createElement('span', { style: { fontSize: '12px' } }, t('vlm.apiKey')),
+						react.createElement('input', { value: vlmApiKey, onChange: (e) => setVlmApiKey(e.target.value), type: 'password', placeholder: 'sk-...', style: { padding: '6px 8px', borderRadius: '6px', border: '1px solid rgba(128,128,128,0.3)', background: 'transparent', color: 'inherit', fontSize: '12px' } }),
+						react.createElement('span', { style: { fontSize: '12px' } }, t('vlm.model')),
+						react.createElement('input', { value: vlmModel, onChange: (e) => setVlmModel(e.target.value), placeholder: 'mimo-v2.5', style: { padding: '6px 8px', borderRadius: '6px', border: '1px solid rgba(128,128,128,0.3)', background: 'transparent', color: 'inherit', fontSize: '12px' } }),
+						react.createElement('span', { style: { fontSize: '12px' } }),
+						react.createElement('label', { style: { display: 'inline-flex', alignItems: 'center', gap: '6px', fontSize: '12px' } },
+							react.createElement('input', { type: 'checkbox', checked: vlmThinking, onChange: (e) => setVlmThinking(e.target.checked) }),
+							t('vlm.thinking'),
+						),
+					),
+				),
 				react.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: '12px' } },
 					react.createElement('button', {
 						type: 'button', onClick: save, disabled: saving,
@@ -892,6 +1021,7 @@ window.__ModuleLoader__.load({
 
 		function apply(ctx) {
 			ctxRef = ctx
+			if (typeof console !== 'undefined' && console.log) console.log('[dsh-file-attachment] apply', { hasSlots: ctx.get('slots') !== undefined, hasConversation: ctx.get('conversation') !== undefined })
 			// 接入即拉持久化配置（幂等）：让自定义类型每次会话生效，而非仅打开设置页才加载
 			void loadConfig()
 			// 注册设置页文案（zh/en）
@@ -902,6 +1032,12 @@ window.__ModuleLoader__.load({
 					'doc.title': '文档',
 					'code.title': '代码',
 					'config.title': '配置文件',
+					'vlm.title': '多模态识别参数',
+					'vlm.hint': '当前会话模型不支持多模态时，粘贴图片将调用此 VLM 生成描述回填草稿；支持多模态则模型直接看图，不调用。',
+					'vlm.baseURL': 'Base URL',
+					'vlm.apiKey': 'API Key',
+					'vlm.model': '模型',
+					'vlm.thinking': '启用思考模式（默认禁用）',
 					'save': '保存',
 					'saving': '保存中…',
 					'saved': '已保存',
@@ -912,6 +1048,12 @@ window.__ModuleLoader__.load({
 					'doc.title': 'Documents',
 					'code.title': 'Code',
 					'config.title': 'Config Files',
+					'vlm.title': 'Multimodal VLM',
+					'vlm.hint': 'When the session model is not multimodal, pasted images are described by this VLM and appended to the draft; multimodal models read images directly (no call).',
+					'vlm.baseURL': 'Base URL',
+					'vlm.apiKey': 'API Key',
+					'vlm.model': 'Model',
+					'vlm.thinking': 'Enable thinking mode (disabled by default)',
 					'save': 'Save',
 					'saving': 'Saving…',
 					'saved': 'Saved',
@@ -942,11 +1084,6 @@ window.__ModuleLoader__.load({
 					{ name: 'shell.overlay', id: 'dsh-file-attachment-toast', order: 100 },
 					FaToast
 				))
-				// 操作行左侧动作区（官方扩展点）：文件上传按钮，复用既有 runBatch 管线
-				slots.inject('conversation.input.left', () => slots.register(
-					{ name: 'conversation.input.left', id: 'dsh-file-attachment-upload', order: 10 },
-					FaUploadButton
-				))
 				// 设置页：文件附件类型配置（左侧菜单项 + 右侧配置页）
 				slots.inject('settings.section', () => [
 					slots.register({
@@ -958,6 +1095,17 @@ window.__ModuleLoader__.load({
 				])
 			}
 			bridge.conversation = ctx.get('conversation')
+			// 劫持 dsh 原生📎：让上传入口位于与 dsh 本体一致的位置（hero/composer 两模式同一按钮），
+			// 点击改走本插件文件选择器；MutationObserver + 定时重扫随 ctx.effect 生命周期清理
+			ctx.effect(() => {
+				const h = installNativeAttachHijack()
+				return () => {
+					if (h !== null && h !== void 0) {
+						try { h.mo.disconnect() } catch (err) { /* 忽略 */ }
+						try { clearInterval(h.timer) } catch (err) { /* 忽略 */ }
+					}
+				}
+			}, 'dsh-file-attachment: native attach hijack')
 			// document 级 capture 监听：dragenter/drop/paste 都先于既有 bubble 监听器；随 Fiber 停止
 			ctx.effect(() => {
 				document.addEventListener('dragenter', onDragEnterCap, true)

package/lib/index.js

@@ -7,10 +7,12 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
 
 /** 本包声明依赖的 Host 服务。 */
 export const name = 'dsh-file-attachment'
-export const inject = ['webServer']
+export const inject = ['webServer', 'tools']
 
 // 临时目录名：落在会话工作区根下；每个项目都能看到自己引用过的文档
 const ATTACHMENT_DIR = '.dsh-file-attachment'
@@ -136,27 +138,50 @@ function normalizeTypeList(arr) {
   return out
 }
 
-/** 读取配置；文件缺失/损坏时回退默认值（保持三类齐全）。 */
+// 多模态识别（VLM）默认参数：用户在「设置→文件附件」可覆盖；空值回退默认，保证开箱可用。
+const VLM_DEFAULTS = {
+  baseURL: 'https://api.xiaomimimo.com/v1',
+  apiKey: '',
+  model: 'mimo-v2.5',
+  thinkingType: 'disabled',
+}
+
+/** 规范化多模态参数（缺省/空值回退默认，trim 去空白）。 */
+function normalizeVlm(raw) {
+  const r = (raw && typeof raw === 'object') ? raw : {}
+  const pick = (key) => (typeof r[key] === 'string' && r[key].trim() !== '' ? r[key].trim() : VLM_DEFAULTS[key])
+  return {
+    baseURL: pick('baseURL'),
+    apiKey: pick('apiKey'),
+    model: pick('model'),
+    thinkingType: pick('thinkingType'),
+  }
+}
+
+/** 读取配置；文件缺失/损坏时回退默认值（保持三类 + 多模态参数齐全）。 */
 async function readConfig() {
+  let stored = {}
   try {
     const text = await readFile(CONFIG_PATH, 'utf8')
-    const doc = JSON.parse(text)
-    return {
-      doc: normalizeTypeList(doc && doc.doc),
-      code: normalizeTypeList(doc && doc.code),
-      config: normalizeTypeList(doc && doc.config),
-    }
+    stored = JSON.parse(text) || {}
   } catch (err) {
-    return { doc: [...DEFAULT_TYPES.doc], code: [...DEFAULT_TYPES.code], config: [...DEFAULT_TYPES.config] }
+    stored = {}
+  }
+  return {
+    doc: normalizeTypeList(stored.doc),
+    code: normalizeTypeList(stored.code),
+    config: normalizeTypeList(stored.config),
+    vlm: normalizeVlm(stored.vlm || stored.mimo),
   }
 }
 
-/** 保存配置（全量覆盖三类）；返回规范化后的配置。 */
+/** 保存配置（全量覆盖三类 + 多模态参数）；返回规范化后的配置。 */
 async function writeConfig(body) {
   const next = {
     doc: normalizeTypeList(body && body.doc),
     code: normalizeTypeList(body && body.code),
     config: normalizeTypeList(body && body.config),
+    vlm: normalizeVlm(body && (body.vlm || body.mimo)),
   }
   await writeFile(CONFIG_PATH, JSON.stringify(next, null, 2) + '\n', 'utf8')
   return next
@@ -195,6 +220,47 @@ async function handleSave(root, body) {
   return { path: target, dir, name: safe, size: bytes.length }
 }
 
+/**
+ * 调 VLM（OpenAI 兼容 chat/completions）识别图片，返回中文描述。
+ * @param vlm - 多模态参数 { baseURL, apiKey, model, thinkingType }（来自配置）。
+ * @param dataUrl - base64 data URL（形如 data:image/png;base64,xxx）。
+ * @returns 图片的简洁中文描述。
+ * @throws VLM 请求失败或未返回有效内容时抛错。
+ */
+async function describeImage(vlm, dataUrl) {
+  const url = vlm.baseURL.replace(/\/+$/u, '') + '/chat/completions'
+  const payload = {
+    model: vlm.model,
+    thinkingType: vlm.thinkingType,
+    messages: [
+      { role: 'system', content: '你是图片描述助手，用简洁中文描述图片主要内容。' },
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: '请描述这张图片。' },
+          { type: 'image_url', image_url: { url: dataUrl } },
+        ],
+      },
+    ],
+  }
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'authorization': 'Bearer ' + vlm.apiKey,
+    },
+    body: JSON.stringify(payload),
+  })
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => '')
+    throw new Error('VLM 请求失败 ' + resp.status + (text !== '' ? ' ' + text.slice(0, 200) : ''))
+  }
+  const data = await resp.json()
+  const content = data && data.choices && data.choices[0] && data.choices[0].message && data.choices[0].message.content
+  if (typeof content !== 'string' || content === '') throw new Error('VLM 未返回有效内容')
+  return content
+}
+
 /** 注册 /dsh-file-attachment 前缀路由（save POST）。 */
 function registerRoutes(ctx) {
   const webserver = ctx.get('webServer')
@@ -242,15 +308,117 @@ function registerRoutes(ctx) {
         json(res, { ok: true, value: { saved: true, config: value } })
         return
       }
-      json(res, { ok: false, error: 'only POST /dsh-file-attachment/save and GET/POST /dsh-file-attachment/config are allowed' }, 405)
+      if (req.method === 'POST' && pathname === '/dsh-file-attachment/describe') {
+        const body = await readJsonBody(req, MAX_BODY_BYTES)
+        if (body === null || typeof body !== 'object') {
+          json(res, { ok: false, error: '请求体必须是 JSON（68MB 内）' }, 400)
+          return
+        }
+        const dataUrl = typeof body.dataUrl === 'string' ? body.dataUrl : ''
+        if (dataUrl === '') {
+          json(res, { ok: false, error: 'dataUrl 必须是非空字符串（base64 data URL）' }, 400)
+          return
+        }
+        const cfg = await readConfig()
+        const vlm = cfg.vlm
+        if (vlm.apiKey === '') {
+          json(res, { ok: false, error: '未配置多模态 API Key（设置→文件附件填写）' }, 400)
+          return
+        }
+        try {
+          const description = await describeImage(vlm, dataUrl)
+          json(res, { ok: true, value: { description } })
+          return
+        } catch (err) {
+          const message = err && err.message ? err.message : '识别失败'
+          json(res, { ok: false, error: message }, 502)
+          return
+        }
+      }
+      json(res, { ok: false, error: 'only POST /dsh-file-attachment/save、GET/POST /dsh-file-attachment/config 与 POST /dsh-file-attachment/describe are allowed' }, 405)
     },
   })
 }
 
+// 图片扩展名判定（describe_image 工具用）
+const IMAGE_EXT = /\.(png|jpe?g|gif|webp|bmp)$/iu
+
+/** 按扩展名推断 MIME（缺省 image/png）。 */
+function mimeFromPath(p) {
+  const ext = String(p ?? '').toLowerCase().split('.').pop() || ''
+  switch (ext) {
+    case 'jpg':
+    case 'jpeg': return 'image/jpeg'
+    case 'png': return 'image/png'
+    case 'webp': return 'image/webp'
+    case 'gif': return 'image/gif'
+    case 'bmp': return 'image/bmp'
+    default: return 'image/png'
+  }
+}
+
+/**
+ * 注册 describe_image 工具：模型看到用户消息里的图片路径引用（@/绝对路径）时调用，
+ * 读图片 → 调 VLM 识别 → 描述仅注入模型上下文（deferContext，不进 UI/session 历史），
+ * UI 只渲染简短确认。实现「图片进历史后自动识别、结果不发给用户」。
+ */
+function registerTools(ctx) {
+  const tools = (ctx !== undefined && ctx !== null && typeof ctx.tools === 'object' && ctx.tools !== null)
+    ? ctx.tools
+    : (typeof ctx.get === 'function' ? ctx.get('tools') : undefined)
+  if (tools === undefined || typeof tools.register !== 'function') {
+    console.warn('[dsh-file-attachment] tools 服务不可用，跳过 describe_image 注册')
+    return
+  }
+  tools.register(defineTool({
+    name: 'describe_image',
+    description: '当用户消息里出现图片路径引用（形如 @/绝对路径，扩展名 png/jpg/jpeg/gif/webp/bmp）且需要理解图片内容时调用此工具，获取该图片的中文内容描述。path 参数填去掉前导 @ 的绝对路径。',
+    parameters: {
+      path: {
+        type: 'string',
+        required: true,
+        description: '图片文件的绝对路径（去掉前导 @）',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [
+        { type: 'text', text: (value && value.ok === true) ? '（图片已识别，描述已注入上下文）' : '（图片识别失败）' },
+      ],
+    },
+    async execute(args, exec) {
+      let path = typeof args.path === 'string' ? args.path.trim() : ''
+      if (path.startsWith('@')) path = path.slice(1)
+      if (path === '') throw new Error('path 不能为空')
+      if (!IMAGE_EXT.test(path)) throw new Error('path 不是受支持的图片（png/jpg/jpeg/gif/webp/bmp）')
+      const bytes = await readFile(path)
+      if (bytes.length === 0) throw new Error('图片文件为空')
+      const dataUrl = 'data:' + mimeFromPath(path) + ';base64,' + bytes.toString('base64')
+      const cfg = await readConfig()
+      if (cfg.vlm.apiKey === '') throw new Error('未配置多模态 API Key（设置→文件附件填写），无法识别图片')
+      const description = await describeImage(cfg.vlm, dataUrl)
+      // 描述仅注入模型上下文（不进 session 历史 / UI），实现「结果不发给用户」
+      exec.deferContext(createUserMessage({
+        content: [{ type: 'text', text: '图片 ' + path + ' 的内容描述：' + description }],
+        source: { kind: 'plugin', plugin: 'dsh-file-attachment' },
+      }))
+      return { ok: true }
+    },
+  }))
+  console.log('[dsh-file-attachment] describe_image tool registered')
+}
+
 /**
- * @param ctx - 宿主上下文（webServer 注入）。
+ * @param ctx - 宿主上下文（webServer + tools 注入）。
  */
 export function apply(ctx, config = {}) {
+  registerTools(ctx)
   registerRoutes(ctx)
-  console.log('[dsh-file-attachment] host loaded (webServer routes)')
+  console.log('[dsh-file-attachment] host loaded (webServer routes + describe_image tool)')
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wszhoho/dsh-file-attachment",
-  "version": "0.4.0",
-  "description": "文件附件：输入框上传按钮 + 拖拽/粘贴文件（支持多文件）；图片走 dsh 原生图片草稿机制（addImages，不缩放/不落盘），文档落盘到 .dsh-file-attachment 并以芯片 @短名 引用（发送时还原 @绝对路径）；文档/代码/配置文件可上传类型可在设置页配置；支持 PC 与移动端浏览器",
+  "version": "0.5.0",
+  "description": "文件附件：输入框上传按钮 + 拖拽/粘贴文件（支持多文件）；图片走 dsh 原生图片草稿机制（addImages，不缩放/不落盘），文档落盘到 .dsh-file-attachment 并以芯片 @短名 引用（发送时还原 @绝对路径）；非多模态模型下图片自动调用可配置 VLM 识别生成中文描述回填草稿；文档/代码/配置文件可上传类型可在设置页配置；支持 PC 与移动端浏览器",
   "keywords": [
     "dsh",
     "plugin",
@@ -33,6 +33,9 @@
   "engines": {
     "node": ">=18"
   },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.0-rc.1 <0.1.1-0 || >=0.1.1-rc.1 <0.1.2-0 || >=0.1.2-alpha.1 <0.2.0-0"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },