dsh-plugin-image-tools 0.3.1

package/scripts/selfcheck.mjs

@@ -0,0 +1,140 @@
+/**
+ * dsh-plugin-image-tools 自检：对 lib/index.js 导出的纯函数做离线冒烟测试。
+ * 运行：node scripts/selfcheck.mjs
+ */
+import { strict as assert } from 'node:assert'
+import {
+  sniffMediaType,
+  resolveMediaType,
+  buildPickMarker,
+  parsePickMarker,
+  loadOptionImage,
+  originOf,
+  safeAlt,
+  MAX_IMAGE_BYTES,
+} from '../lib/index.js'
+
+let passed = 0
+async function ok(name, fn) {
+  await fn()
+  passed += 1
+  console.log(`  ok  ${name}`)
+}
+
+async function main() {
+  console.log('[dsh-plugin-image-tools] selfcheck')
+
+  // --- sniffMediaType ---
+  await ok('sniff PNG', () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00])
+    assert.equal(sniffMediaType(png), 'image/png')
+  })
+  await ok('sniff JPEG', () => {
+    assert.equal(sniffMediaType(Buffer.from([0xff, 0xd8, 0xff, 0xe0])), 'image/jpeg')
+  })
+  await ok('sniff WebP', () => {
+    const webp = Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WEBP')])
+    assert.equal(sniffMediaType(webp), 'image/webp')
+  })
+  await ok('sniff GIF', () => {
+    assert.equal(sniffMediaType(Buffer.from('GIF89a')), 'image/gif')
+  })
+  await ok('sniff unknown -> undefined', () => {
+    assert.equal(sniffMediaType(Buffer.from('hello world')), undefined)
+  })
+
+  // --- resolveMediaType ---
+  await ok('resolve by magic bytes', () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    assert.equal(resolveMediaType(undefined, png), 'image/png')
+  })
+  await ok('resolve honors declared type', () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    assert.equal(resolveMediaType('png', png), 'image/png')
+    assert.equal(resolveMediaType('image/png', png), 'image/png')
+  })
+  await ok('resolve rejects mismatch', () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    assert.throws(() => resolveMediaType('jpeg', png), /不符/)
+  })
+  await ok('resolve rejects unsupported', () => {
+    assert.throws(() => resolveMediaType('image/bmp', Buffer.from([0x42, 0x4d])), /不支持/)
+    assert.throws(() => resolveMediaType(undefined, Buffer.from('nope')), /无法识别/)
+  })
+
+  // --- 标记编解码 round-trip（ASCII JSON，客户端 atob 可直接解析） ---
+  await ok('marker round-trip', () => {
+    const marker = buildPickMarker('abc-123', [0, 2, 5])
+    const parsed = parsePickMarker(marker + '\n\n补充说明')
+    assert.deepEqual(parsed, { pickId: 'abc-123', images: [0, 2, 5], human: '\n\n补充说明' })
+    assert.ok(/^[A-Za-z0-9_-]+$/.test(marker.slice('<!--dsh-pick:v1:'.length, marker.length - '-->'.length)))
+  })
+  await ok('marker absent -> null', () => {
+    assert.equal(parsePickMarker(undefined), null)
+    assert.equal(parsePickMarker('普通 detail'), null)
+    assert.equal(parsePickMarker('<!--dsh-pick:v1:broken-->'), null)
+  })
+
+  // --- originOf（show_images 的绝对 URL 推导） ---
+  await ok('origin uses host/port', () => {
+    assert.equal(originOf({ webServer: { host: '127.0.0.1', port: 3080 } }), 'http://127.0.0.1:3080')
+  })
+  await ok('origin falls back for 0.0.0.0', () => {
+    assert.equal(originOf({ webServer: { host: '0.0.0.0', port: 5173 } }), 'http://127.0.0.1:5173')
+  })
+  await ok('origin tolerates missing ctx', () => {
+    assert.equal(originOf(undefined), 'http://127.0.0.1')
+    assert.equal(originOf({}), 'http://127.0.0.1')
+  })
+
+  // --- safeAlt（caption → markdown alt 安全文本） ---
+  await ok('safeAlt keeps normal caption', () => {
+    assert.equal(safeAlt('深海鲸鱼封面'), '深海鲸鱼封面')
+  })
+  await ok('safeAlt strips markdown-breaking chars', () => {
+    assert.equal(safeAlt('A]B\nC\rD'), 'A B C D')
+    assert.equal(safeAlt('   '), '图片')
+    assert.equal(safeAlt(undefined), '图片')
+  })
+
+  // --- loadOptionImage：data URI / path（url 需要网络，跳过） ---
+  await ok('load data URI', async () => {
+    const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    const data = `data:image/png;base64,${pngBytes.toString('base64')}`
+    const loaded = await loadOptionImage({ data }, process.cwd())
+    assert.equal(loaded.mediaType, 'image/png')
+    assert.deepEqual(loaded.bytes, pngBytes)
+  })
+  await ok('load data URI respects declared mediaType', async () => {
+    const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    const data = `data:image/png;base64,${pngBytes.toString('base64')}`
+    const loaded = await loadOptionImage({ data, mediaType: 'png' }, process.cwd())
+    assert.equal(loaded.mediaType, 'image/png')
+  })
+  await ok('load rejects declared/media mismatch', async () => {
+    const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    const data = `data:image/png;base64,${pngBytes.toString('base64')}`
+    await assert.rejects(() => loadOptionImage({ data, mediaType: 'webp' }, process.cwd()), /不符/)
+  })
+  await ok('load rejects bad data URI', async () => {
+    await assert.rejects(() => loadOptionImage({ data: 'not-a-uri' }, process.cwd()), /data URI/)
+  })
+  await ok('load rejects missing sources', async () => {
+    await assert.rejects(() => loadOptionImage({}, process.cwd()), /path \/ url \/ data/)
+  })
+  await ok('load rejects oversized', async () => {
+    // 构造一个超过上限的 data URI（只做 base64 展开，不落盘）
+    const big = Buffer.alloc(MAX_IMAGE_BYTES + 1, 0x89)
+    await assert.rejects(
+      () => loadOptionImage({ data: `data:image/png;base64,${big.toString('base64')}` }, process.cwd()),
+      /大小上限/,
+    )
+  })
+
+  console.log(`\n[dsh-plugin-image-tools] ${passed} checks passed`)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/scripts/smoke-client.mjs

@@ -0,0 +1,116 @@
+/**
+ * dsh-plugin-image-tools 客户端冒烟测试：
+ * 用 Node 模拟浏览器模块加载器执行 lib/client.js，再用 profile 里的真实
+ * react / react-dom/server 渲染一次图片选择卡，验证：
+ *   1. 模块加载、apply/inject 导出正常；
+ *   2. selectPickChoice 认领带图片标记的问题、放过纯文字问题；
+ *   3. parseMarker 与服务端 buildPickMarker 产出互通；
+ *   4. 组件能完整渲染出图片卡片（hooks/JSX 全部跑通）；
+ *   5. 内嵌图片增强的纯函数（isShowImageSrc / IMAGE_SHOW_PREFIX）行为正确。
+ *
+ * 运行：node scripts/smoke-client.mjs
+ */
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { strict as assert } from 'node:assert'
+import { buildPickMarker } from '../lib/index.js'
+
+const require = createRequire(import.meta.url)
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+// 从 profile 的共享 node_modules 树解析 react（单实例：jsx-runtime/react-dom 同源）
+const profileRequire = createRequire(join('C:/Users/18303/.dsh/profiles/node_modules', 'noop.cjs'))
+const reactRoot = dirname(profileRequire.resolve('react'))
+const jsxRuntime = join(reactRoot, 'jsx-runtime.js')
+const reactModule = profileRequire('react')
+const reactDomServer = profileRequire('react-dom/server')
+
+// 1) 模拟浏览器模块加载器
+let spec = null
+globalThis.window = {
+  __ModuleLoader__: {
+    load: (value) => { spec = value },
+  },
+}
+const code = readFileSync(join(ROOT, 'lib', 'client.js'), 'utf8')
+new Function(code)()
+assert.ok(spec !== null, 'module loader not invoked')
+assert.equal(spec.id, 'dsh-plugin-image-tools')
+
+const shimRequire = (name) => {
+  if (name === 'react/jsx-runtime') return require(jsxRuntime)
+  if (name === 'react') return reactModule
+  throw new Error(`unexpected require: ${name}`)
+}
+const mod = spec.factory(shimRequire)
+assert.equal(typeof mod.apply, 'function')
+assert.deepEqual(mod.inject, ['slots', 'locale'])
+assert.equal(typeof mod.selectPickChoice, 'function')
+assert.equal(typeof mod.ImageChoiceComposer, 'function')
+assert.equal(typeof mod.Lightbox, 'function')
+assert.equal(typeof mod.isShowImageSrc, 'function')
+assert.equal(typeof mod.startInlineEnhancer, 'function')
+
+// 5) 内嵌图片增强纯函数
+assert.ok(mod.isShowImageSrc('/dsh-plugin-image-tools/show/abc-123/0'), 'show 路由 src 应被识别')
+assert.ok(mod.isShowImageSrc('http://127.0.0.1:3080/dsh-plugin-image-tools/show/abc/1'), '绝对 URL 也应被识别')
+assert.ok(!mod.isShowImageSrc('/dsh-plugin-image-tools/abc/0'), '选择卡路由不应被识别为内嵌图')
+assert.ok(!mod.isShowImageSrc('https://example.com/a.png'), '外部图片不应被识别')
+assert.equal(mod.startInlineEnhancer(), null, '无 DOM 环境下不应启动观察器')
+
+// 2) select：认领带标记问题，放过纯文字问题
+const markerDetail = buildPickMarker('pick-1', [0, 2]) + '\n\n请选择一张图'
+const withImage = {
+  kind: 'question',
+  key: 'q:1',
+  sessionId: 's1',
+  payload: { type: 'question/requested', sessionId: 's1', questions: [{ id: 'a', question: '选图', detail: markerDetail, options: [{ label: 'A' }, { label: 'B' }, { label: 'C' }] }] },
+}
+const plain = {
+  kind: 'question',
+  key: 'q:2',
+  sessionId: 's2',
+  payload: { type: 'question/requested', sessionId: 's2', questions: [{ id: 'b', question: '纯文字', options: [{ label: 'X' }] }] },
+}
+const approval = { kind: 'approval', key: 'a:1', sessionId: 's1', payload: {} }
+assert.equal(mod.selectPickChoice({ interactions: [plain] }), null, '纯文字问题应放行')
+assert.equal(mod.selectPickChoice({ interactions: [approval, plain] }), null, '无图问题应放行')
+assert.equal(mod.selectPickChoice({ interactions: [plain, withImage] }), withImage, '带图问题应认领')
+
+// 3) parseMarker 与服务端互通
+const parsed = mod.parseMarker(markerDetail)
+assert.deepEqual({ pickId: parsed.pickId, images: parsed.images, human: parsed.human }, { pickId: 'pick-1', images: [0, 2], human: '\n\n请选择一张图' })
+
+// 4) 渲染图片选择卡（react-dom/server 初次渲染）
+const { renderToString } = reactDomServer
+const fakeT = (key) => ({ 'nav.cancel': '取消', 'action.skip': '跳过', 'action.next': '下一步', 'submit': '提交', 'option.recommended': '推荐', 'custom.placeholder': '输入答案', 'image.failed': '加载失败', 'image.zoom': '放大查看', 'image.close': '关闭' }[key] ?? key)
+const fakeWait = {
+  key: 'q:1',
+  sessionId: 's1',
+  payload: { type: 'question/requested', sessionId: 's1', questions: [{ id: 'a', question: '选一张封面', header: '封面', detail: markerDetail, multiSelect: false, options: [{ label: 'A (Recommended)', description: '第一张' }, { label: 'B' }, { label: 'C' }] }] },
+  respond: async (r) => ({ accepted: true }),
+}
+const html = renderToString(reactModule.createElement(mod.ImageChoiceComposer, { matched: fakeWait, t: fakeT }))
+assert.ok(html.includes('dshpick-card'), '卡片未渲染')
+assert.ok(html.includes('选一张封面'), '问题文本缺失')
+assert.ok(html.includes('/dsh-plugin-image-tools/pick-1/0'), '图片 URL 缺失')
+assert.ok(html.includes('/dsh-plugin-image-tools/pick-1/2'), '第二张图片 URL 缺失')
+assert.ok(html.includes('A'), '选项 label 缺失')
+assert.ok(!html.includes('<!--dsh-pick:v1:'), '标记注释应被剥离，不能出现在界面上')
+
+// 5) 放大查看：卡片渲染出 zoom 触发按钮（aria-label/title 走 locale），
+//    Lightbox 单独渲染时包含大图、说明与关闭按钮
+assert.ok(html.includes('放大查看'), 'zoom 触发按钮的 locale 文案缺失')
+assert.ok(html.includes('dshpick-zoomHint'), 'zoom 提示图标缺失')
+const lightboxHtml = renderToString(reactModule.createElement(mod.Lightbox, {
+  zoom: { src: '/dsh-plugin-image-tools/pick-1/0', label: 'A', description: '第一张' },
+  onClose: () => {},
+  t: fakeT,
+}))
+assert.ok(lightboxHtml.includes('dshpick-lightbox'), 'lightbox 遮罩未渲染')
+assert.ok(lightboxHtml.includes('/dsh-plugin-image-tools/pick-1/0'), 'lightbox 大图 URL 缺失')
+assert.ok(lightboxHtml.includes('第一张'), 'lightbox 说明缺失')
+assert.ok(lightboxHtml.includes('关闭'), 'lightbox 关闭按钮文案缺失')
+
+console.log('[dsh-plugin-image-tools] client smoke passed')

package/scripts/smoke-server.mjs

@@ -0,0 +1,194 @@
+/**
+ * dsh-plugin-image-tools 服务端集成冒烟：
+ * 用假 ctx 挂载插件（apply），完整验证：
+ *   1. 工具以 ask_user_choice / show_images 注册，schema 含 image 字段；
+ *   2. ask_user_choice.execute 归一化图片 → ask 请求的 detail 带标记、
+ *      选项只剩 label/description；
+ *   3. 图片路由能按 /dsh-plugin-image-tools/<pickId>/<index> 与
+ *      /dsh-plugin-image-tools/show/<showId>/<index> 出字节和 content-type；
+ *   4. 回答映射与清理（pick 条目在答案返回后被删除）；
+ *   5. show_images.execute 返回绝对 URL 的 markdown 片段，图片注册表存活
+ *      （回复渲染需要），路由可访问。
+ *
+ * 运行：node scripts/smoke-server.mjs
+ */
+import { strict as assert } from 'node:assert'
+import { apply, ROUTE_PREFIX } from '../lib/index.js'
+
+const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4])
+
+// --- 假 ctx ---
+let toolDefs = []
+let route = null
+let capturedAsk = null
+let resolveAsk = null
+const askPromise = new Promise((resolve) => { resolveAsk = resolve })
+
+const ctx = {
+  effect(fn) {
+    const result = fn()
+    return () => { if (typeof result === 'function') result() }
+  },
+  webServer: {
+    host: '127.0.0.1',
+    port: 3080,
+    register(r) { route = r; return () => {} },
+  },
+  tools: {
+    register(def) { toolDefs.push(def); return () => {} },
+  },
+  userQuestions: {
+    ask(request) {
+      capturedAsk = request
+      return askPromise
+    },
+  },
+}
+
+apply(ctx)
+
+const defByName = (name) => toolDefs.find((def) => def.name === name)
+const choiceDef = defByName('ask_user_choice')
+const showDef = defByName('show_images')
+
+// --- 1) 工具定义 ---
+assert.ok(choiceDef, 'ask_user_choice 未注册')
+assert.ok(choiceDef.parameters.properties.questions.items.properties.options.items.properties.image, '选项 schema 缺少 image 字段')
+assert.ok(choiceDef.parameters.properties.questions.items.properties.options.items.properties.label, '选项 schema 缺少 label')
+assert.equal(typeof choiceDef.execute, 'function')
+assert.ok(showDef, 'show_images 未注册')
+assert.ok(showDef.parameters.properties.images.items.properties.image, 'show_images schema 缺少 image 字段')
+assert.equal(typeof showDef.execute, 'function')
+
+// --- 2) ask_user_choice 执行：data URI 图片 + 纯文字选项混排 ---
+const dataUri = `data:image/png;base64,${pngBytes.toString('base64')}`
+const exec = { agent: { session: { header: { cwd: process.cwd() } } }, signal: undefined }
+const runPromise = choiceDef.execute({
+  questions: [
+    {
+      id: 'q1',
+      question: '选一张图',
+      header: '选图',
+      multi_select: true,
+      options: [
+        { label: '方案A (推荐)', description: '第一张', image: { data: dataUri } },
+        { label: '方案B' },
+        { label: '方案C', image: { data: dataUri } },
+      ],
+    },
+    { id: 'q2', question: '纯文字题', options: [{ label: '是' }, { label: '否' }] },
+  ],
+}, exec)
+
+// 等 execute 把 ask 请求送出去（假 ask 挂起，等待我们手动回答）
+await new Promise((r) => setTimeout(r, 0))
+assert.ok(capturedAsk !== null, 'execute 未调用 userQuestions.ask')
+assert.equal(capturedAsk.questions.length, 2)
+assert.equal(capturedAsk.questions[0].id, 'q1')
+assert.equal(capturedAsk.questions[0].multiSelect, true)
+
+// detail 带标记，标记 JSON 为 ASCII
+const detail = capturedAsk.questions[0].detail
+assert.ok(detail.startsWith('<!--dsh-pick:v1:'), 'detail 缺少标记')
+const markerBody = detail.slice('<!--dsh-pick:v1:'.length, detail.indexOf('-->'))
+assert.ok(/^[A-Za-z0-9_-]+$/.test(markerBody), '标记 JSON 应为 ASCII base64url')
+const marker = JSON.parse(Buffer.from(markerBody, 'base64url').toString('utf8'))
+assert.deepEqual(marker, { pickId: marker.pickId, images: [0, 2] })
+const pickId = marker.pickId
+
+// 选项只含 label/description（标准字段）
+assert.deepEqual(Object.keys(capturedAsk.questions[0].options[0]).sort(), ['description', 'label'])
+assert.deepEqual(capturedAsk.questions[0].options[1], { label: '方案B' })
+assert.equal(capturedAsk.questions[1].detail, undefined, '纯文字题不应带标记')
+
+// --- 3) 图片路由出图（选择卡） ---
+assert.equal(route.kind, 'prefix')
+assert.equal(route.path, ROUTE_PREFIX)
+let served = null
+route.handler(
+  { url: `${ROUTE_PREFIX}/${pickId}/0` },
+  {
+    writeHead(status, headers) { served = { status, headers } },
+    end(body) { served.body = body },
+  },
+)
+assert.equal(served.status, 200)
+assert.equal(served.headers['content-type'], 'image/png')
+assert.deepEqual(served.body, pngBytes)
+// 越界下标 → 404
+let notFound = null
+route.handler(
+  { url: `${ROUTE_PREFIX}/${pickId}/9` },
+  { writeHead(status, headers) { notFound = { status } }, end() {} },
+)
+assert.equal(notFound.status, 404)
+
+// --- 4) 回答映射 + 清理 ---
+resolveAsk({
+  answers: [
+    { id: 'q1', selected: ['方案A (推荐)', '方案C'] },
+    { id: 'q2', selected: [], custom: '自定义' },
+  ],
+})
+const result = await runPromise
+assert.deepEqual(result, {
+  answers: [
+    { id: 'q1', selected: ['方案A (推荐)', '方案C'] },
+    { id: 'q2', selected: [], custom: '自定义' },
+  ],
+})
+// finally 已清理：路由再访问应 404
+let afterCleanup = null
+route.handler(
+  { url: `${ROUTE_PREFIX}/${pickId}/0` },
+  { writeHead(status) { afterCleanup = { status } }, end() {} },
+)
+assert.equal(afterCleanup.status, 404, '回答后图片注册表应清理')
+
+// --- 5) show_images：注册 + markdown 片段 + 路由出图（条目存活供渲染） ---
+const showResult = await showDef.execute({
+  images: [
+    { image: { data: dataUri }, caption: '深海鲸鱼封面' },
+    { image: { data: dataUri } },
+  ],
+}, exec)
+assert.ok(Array.isArray(showResult.markdown), 'show_images 应返回 markdown 数组')
+assert.equal(showResult.markdown.length, 2)
+const url0 = showResult.markdown[0].match(/\]\((http[^)]+)\)/)?.[1]
+const url1 = showResult.markdown[1].match(/\]\((http[^)]+)\)/)?.[1]
+assert.ok(url0 && url0.startsWith('http://127.0.0.1:3080'), `URL 应为绝对 origin：${url0}`)
+assert.ok(url0.includes(`${ROUTE_PREFIX}/show/`), `URL 应含 show 路由：${url0}`)
+assert.ok(showResult.markdown[0].includes('![深海鲸鱼封面]'), '第一张应带 caption alt')
+assert.ok(showResult.markdown[1].includes('![图片]'), '无 caption 时 alt 用默认文案')
+const showId = url0.match(/\/show\/([^/]+)\//)?.[1]
+assert.ok(showId, '无法从 URL 提取 showId')
+
+// 回复渲染期条目应存活：两张都能出图
+let showServed = []
+for (const index of [0, 1]) {
+  route.handler(
+    { url: `${ROUTE_PREFIX}/show/${showId}/${index}` },
+    {
+      writeHead(status, headers) { showServed.push({ status, headers }) },
+      end(body) { showServed[showServed.length - 1].body = body },
+    },
+  )
+}
+assert.equal(showServed[0].status, 200)
+assert.equal(showServed[0].headers['content-type'], 'image/png')
+assert.deepEqual(showServed[0].body, pngBytes)
+assert.equal(showServed[1].status, 200)
+// 越界 → 404
+let showNotFound = null
+route.handler(
+  { url: `${ROUTE_PREFIX}/show/${showId}/9` },
+  { writeHead(status) { showNotFound = { status } }, end() {} },
+)
+assert.equal(showNotFound.status, 404)
+
+// show_images 参数校验
+await assert.rejects(() => showDef.execute({ images: [] }, exec), /不能为空/)
+await assert.rejects(() => showDef.execute({ images: [{ caption: '没有图' }] }, exec), /image 字段/)
+await assert.rejects(() => showDef.execute({ images: [{ image: {} }] }, exec), /path \/ url \/ data/)
+
+console.log('[dsh-plugin-image-tools] server smoke passed')

package//350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -0,0 +1,161 @@
+# dsh-plugin-image-tools 设计说明
+
+## 目标
+
+给 dsh Web GUI 增加两项图片能力：
+
+1. **带图片的选项选择**（`ask_user_choice`）：模型提问时，选项可以是纯图片、
+   纯文字、或图片+文字混合；用户在 GUI 里点图片卡片完成选择，答案协议与原生
+   `ask_user_question` 完全一致。
+2. **回复内嵌图片**（`show_images`）：模型在回复正文里展示图片（图片与文字混排），
+   点击可放大查看。
+
+## 现状（原生链路）
+
+```
+模型 → ask_user_question 工具
+  → ctx.userQuestions.ask({ questions })
+  → host-apiproxy 的 userQuestions provider：
+      注册 pending → 向浏览器 mux 流推送 question/requested 帧
+  → 浏览器 dsh-client-connection 用 muxFrameSchema.parse() 解析帧
+  → dsh-client-runtime 生成 PendingWait（kind="question"）
+  → dsh-client-ui-user-questions 在 conversation.composer slot 链
+      select({ interactions }) 匹配 kind === "question"
+  → QuestionComposer 渲染文字选项卡 → 用户点选 → wait.respond({...}) 回传
+  → provider 的 pending resolve → 工具返回 answers
+```
+
+助手消息渲染：模型文本 → 核心渲染器（micromark 直接 mdast→React）逐 block 渲染；
+`text` 块走 `MarkdownText`，`image` 块（需 attachment ref）走 `ImageGallery`——
+模型输出只有文本，没有携带结构化图片块的通道。
+
+## 关键约束
+
+- 浏览器端（`dsh-client-connection/lib/client.js`）消费 mux 流时执行
+  `muxFrameSchema.parse(payload)`（zod，默认 strip）。`question/requested` 帧的
+  选项 schema 只允许 `label` / `description`，**任何额外字段（如 `image`）都会被
+  静默剥离**。因此：
+  - ❌ 不能往 option 里塞图片数据/引用，客户端收不到；
+  - ❌ 不能新增 intent kind（discriminatedUnion 只认 `plan-review`，未知类型整帧被丢弃）；
+  - ✅ `detail`、`header`、`question`、`id` 等标准字符串字段**原样透传**——这是唯一的
+    出站通道。
+- 核心渲染器的 markdown 图片只放行**绝对 http(s) URL**（`sanitizeUrl`/`remoteImageUrl`
+  协议白名单），相对路径与原始 HTML 都不会进入 DOM。
+- 外壳把 `dsh-client-ui-primitives` 打成 frozen 静态模块，**无法包装 MarkdownText**；
+  消息渲染也没有 content 级 slot。因此回复内嵌图片走「绝对 URL markdown + DOM
+  渐进增强」而不是改渲染器。
+
+## 方案 A：选择卡（detail 携带不可见标记 + 独立图片字节路由）
+
+```
+模型 → ask_user_choice（本插件工具）
+  → 逐选项归一化图片（path/url/data → Buffer + 魔数校验 mediaType）
+  → pickId = uuid；bytes 存入内存注册表 picks：Map<pickId, images[]>
+  → 构造 ask() 请求：
+      options 只留 { label, description }（标准字段）
+      detail = "<!--dsh-pick:v1:<base64url({pickId,images:[下标]})-->" + 人类可读 detail
+      （标记是 HTML 注释，markdown 渲染不可见；JSON 全 ASCII，浏览器 atob 直接解）
+  → ctx.userQuestions.ask()（标准通道，provider/协议零改动）
+  → 浏览器照常收到 question/requested 帧（detail 原样）
+  → 本插件客户端在 conversation.composer 链注册 priority:-100 的条目：
+      select 检查任一 question.detail 是否带 dsh-pick 标记
+        · 带标记 → 认领，渲染图片选择卡（<img src="/dsh-plugin-image-tools/<pickId>/<index>">）
+        · 不带 → 返回 null，原生 QuestionComposer 照常接管（优雅降级）
+  → 用户点选 → 同一 wait.respond 协议回传 → 工具返回 answers
+  → finally：按批次删除注册表条目（字节立即释放；未答条目 30 分钟 TTL）
+```
+
+## 方案 B：回复内嵌图片（绝对 URL markdown + DOM 渐进增强）
+
+```
+模型 → show_images（本插件工具）
+  → 逐张归一化图片（复用 loadOptionImage）→ 内存注册表 shows：Map<showId, images[]>
+  → origin = originOf(ctx)（ctx.webServer.host/port；0.0.0.0 回退 127.0.0.1）
+  → 返回 { markdown: ["![caption](http://host:port/dsh-plugin-image-tools/show/<id>/<i>)"...] }
+  → 模型把 markdown 片段原样粘贴进回复正文
+  → 核心 MarkdownText 渲染绝对 URL 图片 → 图片随文字显示（零核心改动基线）
+  → 本插件客户端（MutationObserver 监听 document.body，rAF 合帧扫描
+      img[src^="/dsh-plugin-image-tools/show/"]）对图片做渐进增强：
+      加 .dshimg-inline 样式类（圆角/限高/悬浮说明）、点击打开命令式 Lightbox
+      （复用 .dshpick-lightbox 样式）、加载失败降级
+  → shows 条目无「回答完成」事件可依，依赖 30 分钟 TTL 清理
+```
+
+为什么选「绝对 URL markdown」作为主链路：模型输出只有文本，唯一能进正文且被
+核心渲染器安全显示的方式就是绝对 http(s) 图片 URL；客户端增强只是锦上添花，
+即使增强失效（无 DOM/观察器被禁），markdown 图片本身也完整可用。
+
+## 各侧职责
+
+### 服务端 lib/index.js（零运行时依赖，不 import @deepseek-ai/*）
+
+- 工具 `ask_user_choice`（原始 definition 形状，与 dsh-plugin-novel 同策略）：
+  - schema 与 `ask_user_question` 对齐 + 选项 `image` 字段；
+  - execute：归一化图片 → 组 ask 请求 → 等待 → 映射答案 → 清理。
+- 工具 `show_images`：
+  - schema：`images: [{ image: {path|url|data|mediaType}, caption? }]`（1~9 张）；
+  - execute：归一化 → 注册 shows → 返回绝对 URL markdown 片段 + 提示语。
+- web 路由 `ROUTE_PREFIX = /dsh-plugin-image-tools`（`ctx.webServer.register`，kind=prefix）：
+  - `/dsh-plugin-image-tools/<pickId>/<index>` → 选择卡图片；
+  - `/dsh-plugin-image-tools/show/<showId>/<index>` → 回复内嵌图片；
+  - bytes + content-type（nosniff + 短缓存），越界/未知 id → 404。
+- 图片来源归一化（两种工具共用 `loadOptionImage`）：
+  - `data`：data URI 解析（声明类型优先，魔数兜底，两者冲突报错）；
+  - `url`：`fetch`（30s 超时），content-type 或魔数定类型；
+  - `path`：相对会话 cwd（`agent.session.header.cwd`）解析，`readFile` 读取。
+  - 上限 20 MiB/张；类型限 PNG/JPEG/WebP/GIF（魔数校验）。
+
+### 客户端 lib/client.js（浏览器模块加载器格式，免构建）
+
+- 只 `require("react")` / `react/jsx-runtime`（与核心 client bundle 同解析方式），
+  不依赖其它 client 包；样式用全局主题 CSS 变量自绘。
+- `PendingChoice`：与原生 `PendingQuestion` 相同的 wire 编码
+  （`wait.respond({ ok:true, value:{ sessionId, answer } })`）。
+- `selectPickChoice`：只认领带标记的 question 交互。
+- `ImageChoiceFlow`：复刻原生 QuestionFlow 的交互模型（分页、多选、自定义答案、
+  跳过、取消、推荐标注、Enter 提交），差异是带图选项渲染为图片卡片网格；
+  同题内无图选项仍渲染为文字行。
+- `ImageCardBtn`：卡片 = `div[role=radio|checkbox]`（整卡可点选中）+ 内部
+  `button.dshpick-thumb`（点击放大查看，独立焦点）——避免嵌套 button 的非法 HTML。
+- `Lightbox`（React）：点击缩略图弹出全屏遮罩大图，关闭途径 Esc / 点遮罩 / 关闭按钮。
+- **内嵌图片增强**（命令式 DOM，与 React 树隔离）：
+  - `isShowImageSrc(src)`：纯字符串判定 `/dsh-plugin-image-tools/show/` 前缀；
+  - `upgradeInlineImage(img)`：只做**单节点**变更（dataset/class/事件监听），
+    不插入/移除 React 管理的结构 → 重渲染安全，观察器会重新应用；
+  - `startInlineEnhancer()`：`MutationObserver(document.body, childList+subtree)`
+    + rAF 合帧扫描；无 DOM 环境返回 null（优雅降级）；
+  - `openImageZoom(src, caption)`：命令式 Lightbox（复用 `.dshpick-lightbox` 样式），
+    带 Esc / 点遮罩 / 关闭按钮。
+- 注册：
+  - `ctx.slots.inject("conversation.composer", ...)`（priority -100，先于原生）；
+  - `ctx.effect(() => startInlineEnhancer())`（随插件卸载停止观察器）。
+
+## 为什么不改核心包
+
+- `dsh-tool-ask-user` / `dsh-user-questions` / `dsh-client-ui-user-questions` /
+  `dsh-host-apiproxy` 全是 npm 安装的发布包，改它们 = fork 核心，升级即失效。
+- 本方案所有改动都在插件包内：两个新工具 + 新客户端链条目 + 自有路由 + DOM 增强；
+  对核心只有「detail 里多了个不可见注释」和「正文里多了条 markdown 图片 URL」
+  这两个纯数据副作用。
+- 优雅降级：未装客户端（或纯文字题）时，问题退化为原生文字选项；内嵌图片
+  退化为核心 markdown 原生渲染。任何一侧缺失都不破坏流程。
+
+## 边界与取舍
+
+- 图片字节在内存（v1 简单可靠）；20 MiB × 张数有总量风险，后续可落盘/走附件。
+- 图片路由与 GUI 同信任级别，未加额外鉴权（与整站一致）。
+- detail 以纯文本展示（未引 MarkdownText，避免对 primitives 的依赖面）。
+- URL 图片由服务端拉取（浏览器跨域/CSP 不受影响）。
+- 内嵌图片 URL 是绝对地址：GUI 经反向代理/换端口访问时历史消息图片可能失效
+  （可后续用 `x-forwarded-*` / Host 头改进）。
+- `shows` 无「展示完成」事件，采用 TTL 清理（30 分钟），重启即失效（与选择卡一致）。
+
+## 验证
+
+- `scripts/selfcheck.mjs`：纯函数（魔数、类型、标记 round-trip、data URI、
+  originOf、safeAlt）。
+- `scripts/smoke-server.mjs`：假 ctx 全链路（两工具注册 → 归一化 → ask 请求 →
+  路由出图（pick + show）→ 回答映射 → 清理 + show 条目存活）。
+- `scripts/smoke-client.mjs`：真实 react 渲染一次图片选择卡 + 链选择器行为 +
+  Lightbox 放大层渲染 + 内嵌图片增强纯函数。
+- 均离线可跑：`npm run smoke`；发布前 `prepublishOnly` 自动重跑全套。