dsh-dock 0.1.0 → 0.4.1

package/features/visionproxy/host.js

@@ -0,0 +1,301 @@
+// dsh-dock · 功能模块【图片理解代理】· 宿主半部（v0.3.1 迁自 index.js，行为不变）
+//
+// 纯文本模型收到图片时，自动调用配置的视觉模型识别图片，
+// 把识别文本替换进请求（多模态模型不受影响，原样自识别）。
+// 拦截点：官方 llm/stream 瀑布流不允许改写 frozen 请求、registerAdapter 拒绝重复注册，
+// 故对 llm.stream / llm.prepareCall 做方法级包装（保存原函数，dispose 恢复）。
+// 配置存自有 settings 命名空间 dsh-dock（visionProxy: enabled/provider/model），
+// 其编辑 UI 在模型设置页内（见 features/modelconfig/view.js）。
+import { BlockAssembler } from '@deepseek-ai/dsh-llm'
+import { DOCK_NS } from '../../src/host-core.js'
+import { readModelDirectory } from '../modelconfig/host.js'
+
+/** 递归判断内容块里是否有图片（含 tool-result 嵌套，与官方 contentHasImage 同构）。 */
+function contentHasImageDeep(content) {
+  if (!Array.isArray(content)) return false
+  for (const block of content) {
+    if (block && block.type === 'image') return true
+    if (block && block.type === 'tool-result' && contentHasImageDeep(block.content)) return true
+  }
+  return false
+}
+
+/** 让视觉模型描述一张图片，返回识别文本（失败抛错）。 */
+async function describeImage(deps, cfg, block, signal) {
+  const prompt = '请用中文详细描述这张图片的内容：主体、文字（若有则逐字转写）、数据/图表要点、与编码任务相关的细节。控制在 300 字以内，直接输出描述，不要客套。'
+  // 单次识别调用：返回文本（可为空串，由调用方决定重试），失败抛错。
+  // ⚠️ 不带 sessionId：llm/stream 的会话检查点监听对带 sessionId 的调用先做检查点，
+  // 回合进行中会 fail-closed 短路适配器。
+  // ⚠️ 走 prepareCall 通道而非 llm.stream：llm/stream 公共路径对带图请求实测会被
+  // 截断（单 block-start 后静默结束，两种适配器均然，端点直连正常）；agent-loop 的
+  // 带图请求全部经 prepareCall().stream() 且工作正常，此处同通道。
+  // prepareCall(config).stream(options) 要求 options 与 config 在 provider/model/
+  // reasoningEffort/maxTokens 等请求控制字段上完全一致，故两处同源构造。
+  const run = async (effort) => {
+    const config = { provider: cfg.provider, model: cfg.model, maxTokens: 4096 }
+    if (effort) config.reasoningEffort = effort
+    const prepared = await deps.prepareCall(config, signal)
+    // options 必须与 resolvedConfig 完全一致（callConfigEquals），以 prepared.config 为底
+    const options = Object.assign({}, prepared.config, {
+      messages: [{
+        role: 'user',
+        source: { kind: 'plugin', plugin: 'dsh-dock' },
+        content: [block, { type: 'text', text: prompt }],
+      }],
+      // 递归保护：本请求由代理发起，包装层直接放行
+      dockVisionProxy: true,
+    })
+    if (signal) options.signal = signal
+    const assembler = new BlockAssembler()
+    for await (const chunk of prepared.stream(options)) {
+      assembler.push(chunk)
+      // ⚠️ BlockAssembler.finish 是 getter，未收到 finish chunk 时也返回 {kind:'stop'}
+      // （恒真值）——只能用 chunk.type 判断，用 assembler.finish 当条件会在第一个
+      // chunk 后就 break，识别永远为空（2026-08-22 排查一下午的根因）。
+      if (chunk && chunk.type === 'finish') break
+    }
+    if (assembler.finish && assembler.finish.kind === 'error') {
+      throw new Error(String(assembler.finish.failure?.message || '视觉模型调用失败'))
+    }
+    return assembler.blocks()
+      .filter((b) => b && b.type === 'text')
+      .map((b) => b.text)
+      .join('')
+      .trim()
+  }
+  // 识别是辅助调用，求快：先试关思考（off）；报不支持或返回空内容都回退默认档重试
+  let text
+  try {
+    text = await run('off')
+  } catch (e) {
+    if (!(e instanceof Error && /does not support reasoning effort|UNSUPPORTED_REASONING_EFFORT/i.test(e.message))) {
+      throw e
+    }
+  }
+  if (!text) text = await run(undefined)
+  if (!text) throw new Error('视觉模型没有返回文本')
+  return text
+}
+
+/**
+ * 识别结果缓存（attachmentId + 视觉模型 → 文本）。
+ * 端点对连续识图有节流（实测第 ~6 次起掐流成单个 block-start）；agent 每轮
+ * 重试/多步都会带着历史图片重发请求，逐图重识别既慢又会撞限流——同一张图
+ * 10 分钟内只识别一次，失败不缓存。
+ */
+const describeCache = new Map()
+const DESCRIBE_CACHE_TTL = 10 * 60 * 1000
+const DESCRIBE_CACHE_MAX = 64
+
+function cacheKey(cfg, block) {
+  return `${cfg.provider}/${cfg.model}:${block && block.attachment ? block.attachment.attachmentId : ''}`
+}
+
+function cacheGet(key) {
+  const hit = describeCache.get(key)
+  if (!hit) return undefined
+  if (Date.now() - hit.at > DESCRIBE_CACHE_TTL) {
+    describeCache.delete(key)
+    return undefined
+  }
+  return hit.text
+}
+
+function cacheSet(key, text) {
+  if (describeCache.size >= DESCRIBE_CACHE_MAX) {
+    const oldest = describeCache.keys().next().value
+    describeCache.delete(oldest)
+  }
+  describeCache.set(key, { text, at: Date.now() })
+}
+
+/**
+ * 请求改写：目标是纯文本模型且带图片时，逐图调用视觉模型，图片块替换为识别文本。
+ * 任何失败都只降级（保留原图或占位说明），绝不阻断主请求。
+ * @returns 改写后的 options（无需改写时原样返回）
+ */
+async function transformForVisionProxy(deps, options) {
+  const cfg = deps.config()
+  const log = (msg) => { try { console.log('[dsh-dock] visionproxy ' + msg) } catch { /* 日志失败不影响主流程 */ } }
+  try {
+    if (!cfg || !cfg.enabled || !cfg.provider || !cfg.model) return options
+    if (!options || typeof options !== 'object') return options
+    if (options.dockVisionProxy) return options
+    if (options.provider === cfg.provider && options.model === cfg.model) return options
+    if (options.purpose) return options // 内部辅助调用（如会话标题）不代理
+    if (!Array.isArray(options.messages)) return options
+    if (!options.messages.some((m) => m && contentHasImageDeep(m.content))) return options
+    log(`带图请求 ${options.provider}/${options.model}`)
+
+    // 目标模型是否支持图片：优先问运行时（llm.resolveModelInfo，与官方投影同源：
+    // entry.input → 内置目录 → 路由默认），避免插件目录误判"靠内置目录继承多模态"的
+    // 模型（如 kimi-k2.7，条目未写 input 但目录里是 [text,image]）；
+    // 旧宿主无此方法或单次解析失败时，退回插件目录视图兜底。
+    let imageCapable
+    try {
+      const info = deps.resolveModelInfo ? await deps.resolveModelInfo(options.provider, options.model) : undefined
+      if (info && Array.isArray(info.inputModalities)) imageCapable = info.inputModalities.includes('image')
+    } catch {
+      // 落到目录回退
+    }
+    if (imageCapable === undefined) {
+      const dir = deps.directory()
+      const p = (dir.providers || []).find((x) => x.id === options.provider)
+      const m = p && Array.isArray(p.models) ? p.models.find((x) => x.id === options.model) : undefined
+      imageCapable = !!(m && Array.isArray(m.input) && m.input.includes('image'))
+    }
+    if (imageCapable) {
+      log(`跳过 ${options.provider}/${options.model}：运行时判定多模态（原图直发）`)
+      return options
+    }
+
+    let changed = false
+    const replaceBlocks = async (blocks) => {
+      const next = []
+      for (const block of blocks) {
+        if (block && block.type === 'image') {
+          changed = true
+          const key = cacheKey(cfg, block)
+          const cached = cacheGet(key)
+          if (cached !== undefined) {
+            log('命中识别缓存')
+            next.push({ type: 'text', text: `[图片内容（由视觉模型 ${cfg.provider}/${cfg.model} 识别）：${cached}]` })
+            continue
+          }
+          try {
+            const desc = await describeImage(deps, cfg, block, options.signal)
+            cacheSet(key, desc)
+            log(`识别成功 ${desc.length} 字`)
+            next.push({ type: 'text', text: `[图片内容（由视觉模型 ${cfg.provider}/${cfg.model} 识别）：${desc}]` })
+          } catch (e) {
+            // 识别失败：降级为说明文本，官方投影不会再把请求打挂
+            log(`识别失败：${e instanceof Error ? e.message : String(e)}`)
+            next.push({ type: 'text', text: `[图片未能识别（${e instanceof Error ? e.message : String(e)}），已省略]` })
+          }
+          continue
+        }
+        if (block && block.type === 'tool-result' && contentHasImageDeep(block.content)) {
+          next.push(Object.assign({}, block, { content: await replaceBlocks(block.content) }))
+          continue
+        }
+        next.push(block)
+      }
+      return next
+    }
+    const messages = []
+    for (const msg of options.messages) {
+      if (msg && contentHasImageDeep(msg.content)) {
+        messages.push(Object.assign({}, msg, { content: await replaceBlocks(msg.content) }))
+      } else {
+        messages.push(msg)
+      }
+    }
+    return changed ? Object.assign({}, options, { messages }) : options
+  } catch {
+    return options // 总兜底：代理自身异常不影响主请求
+  }
+}
+
+/** 安装 llm 方法包装：stream 与 prepareCall 两条入口都过一遍图片代理改写。 */
+function installVisionProxy(ctx, directory) {
+  const llm = ctx.get('llm')
+  if (!llm || typeof llm.stream !== 'function' || typeof llm.prepareCall !== 'function') {
+    throw new Error('llm 服务不可用，无法安装图片理解代理')
+  }
+  // 原函数先绑定保存：改写判定与识别调用都走原函数，不受包装影响
+  const origResolve = typeof llm.resolveModelInfo === 'function' ? llm.resolveModelInfo.bind(llm) : null
+  if (origResolve) llm.__dockOrigResolveModelInfo = origResolve
+  const origPrepareCall = llm.prepareCall.bind(llm)
+  const deps = {
+    config: () => {
+      try {
+        const settings = ctx.get('settings')
+        const v = settings && typeof settings.get === 'function' ? settings.get(DOCK_NS) : undefined
+        return v && v.visionProxy ? v.visionProxy : { enabled: false, provider: '', model: '' }
+      } catch {
+        return { enabled: false, provider: '', model: '' }
+      }
+    },
+    // 识别调用走保存的原函数：天然绕开包装层，无递归
+    stream: (options) => llm.__dockOrigStream(options),
+    // 识别调用走原 prepareCall 通道（带图请求的被验证路径）
+    prepareCall: origPrepareCall,
+    // 运行时模型信息查询（图片能力判定与官方投影同源）；旧宿主无此方法时为 null
+    resolveModelInfo: origResolve,
+    directory,
+  }
+  llm.__dockOrigStream = llm.stream.bind(llm)
+  const origPrepare = llm.prepareCall
+  llm.stream = (options) => (async function* () {
+    yield* llm.__dockOrigStream(await transformForVisionProxy(deps, options))
+  })()
+  llm.prepareCall = async (config, signal) => {
+    const prepared = await origPrepare.call(llm, config, signal)
+    // prepared 是冻结对象：浅拷贝后包一层 stream，dispatched 一次性约束经原闭包保持。
+    // ⚠️ stream 必须同步返回 AsyncIterable：消费方 `for await (of stream)` 不接受
+    // Promise（Node 语义：of 表达式直接取 Symbol.asyncIterator），async 包装会令
+    // 全部请求报 "stream is not async iterable"（2026-08-22 事故）。
+    return Object.assign({}, prepared, {
+      stream: (options) => (async function* () {
+        yield* prepared.stream(await transformForVisionProxy(deps, options))
+      })(),
+    })
+  }
+  // 虚拟多模态：代理启用时，纯文本模型对外宣称支持图片，让官方带图准入放行——
+  // apiproxy 的 prompt 收图校验、mcp-client/tool-fs 的图片声明检查都查
+  // llm.resolveModelInfo 的 inputModalities；图片真正到端点前会被 stream/prepareCall
+  // 包装层替换为识别文本。视觉模型自身与多模态模型不受影响；官方内部投影不走
+  // 此公共方法，truth 不变。
+  if (origResolve) {
+    llm.resolveModelInfo = async (provider, model, signal) => {
+      const info = await origResolve(provider, model, signal)
+      try {
+        const cfg = deps.config()
+        if (!cfg || !cfg.enabled || !cfg.provider || !cfg.model) return info
+        if (provider === cfg.provider && model === cfg.model) return info
+        if (info && Array.isArray(info.inputModalities) && info.inputModalities.length > 0
+          && !info.inputModalities.includes('image')) {
+          return Object.assign({}, info, { inputModalities: info.inputModalities.concat('image') })
+        }
+      } catch {
+        // 保真回退
+      }
+      return info
+    }
+  }
+  return () => {
+    delete llm.__dockOrigStream
+    delete llm.stream
+    delete llm.prepareCall
+    delete llm.__dockOrigResolveModelInfo
+    delete llm.resolveModelInfo
+  }
+}
+
+/** 测试钩子：清空识别缓存（冒烟在用例间隔离）。 */
+export function __clearDescribeCache() {
+  describeCache.clear()
+}
+
+/** 功能注册表条目：index.js 组装 hostSetups 时使用。 */
+export const feature = {
+  id: 'visionproxy',
+  name: '图片理解代理',
+  description: '纯文本模型收图时自动调用视觉模型识别（多模态模型不受影响）',
+  defaultEnabled: true,
+  setup(ctx) {
+    // 模型目录的 TTL 缓存：图片代理判定目标模型是否纯文本时用（避免每个请求都全量 describe）
+    let dockDirCache = { at: 0, data: { providers: [] } }
+    const directoryCached = () => {
+      if (Date.now() - dockDirCache.at > 10000) {
+        try {
+          dockDirCache = { at: Date.now(), data: readModelDirectory(ctx) }
+        } catch {
+          // 保持旧缓存
+        }
+      }
+      return dockDirCache.data
+    }
+    return installVisionProxy(ctx, directoryCached)
+  },
+}

package/index.js

@@ -1,37 +1,45 @@
-// dsh-dock · Host 半部（Node 侧入口）
+// dsh-dock · Host 半部（Node 侧入口）· v0.4.0 模块化架构
 //
-// v0.1.0 基础框架：
-//   - 功能注册表（FEATURES）：与 Client 半部注册表同构，规划中的功能已登记；
-//   - 每功能独立生命周期（hostSetups 返回 disposer，开关只影响自己）；
-//   - 函数级错误隔离：单个功能 setup 抛错只标记 error，不影响其他功能。
+// 功能坞 = hub + 一个个独立功能模块（像 dsh 本身由小包组成）：
+//   - 每个功能是一个 features/<id>/ 目录：host.js（宿主半部）+ view.js(x)（客户端视图），
+//     可整体拎出单独打包发布（scripts/extract-feature.mjs 生成独立包骨架）；
+//   - 独立发布的功能包装回本插件后，经 client 半部的 dockBridge 注册进面板菜单；
+//   - 本文件只做组装：import 各模块的 feature 描述符，统一生命周期（开关/错误隔离/卸载清理），
+//     不含任何具体功能逻辑。
 //
-// 路线图：
-//   - 0.2.0 接入模型余额：在 hostSetups.balance 里实现余额拉取，
-//     Client↔Host 联通（typert）随本版本一起打通；
-//   - 0.3.0 接入 Token 用量记录：hostSetups.tokenlog 监听事件记账；
-//   - 0.4.0 接入任务动画。
+// 功能清单（宿主半部；客户端菜单次序由 view 模块的 order 字段决定）：
+//   - models      模型设置（v0.3.0）：模型目录读 + 官方配置写
+//   - visionproxy 图片理解代理（v0.3.1）：纯文本模型收图自动走视觉模型识别
+//   - balance     模型余额（v0.2.0）：各 Provider 账户余额/配额
+//   - tokenlog    用量记录（v0.4.0）：LLM 调用记账与统计（移植自 @wycto/dsh-token-usage）
+//   - animation   任务动画（路线图 0.5.0 占位）
+import { DOCK_NS, DockConfig } from './src/host-core.js'
+import { feature as fModels } from './features/modelconfig/host.js'
+import { feature as fVisionProxy } from './features/visionproxy/host.js'
+import { feature as fBalance } from './features/balance/host.js'
+import { feature as fTokenlog } from './features/tokenlog/host.js'
+
 export const name = 'dsh-dock'
 
+// 硬依赖 webServer（路由注册）+ llm（图片理解代理包装）+ settings（自有命名空间读写）。
+export const inject = ['webServer', 'llm', 'settings']
+
+/** 测试钩子：清空识别缓存（冒烟在用例间隔离；实现在 visionproxy 模块）。 */
+export { __clearDescribeCache } from './features/visionproxy/host.js'
+
 export function apply(ctx) {
-  // ---- 功能注册表（Host 侧）----
-  // defaultEnabled 缺省为 false：v0.1.0 只有示例功能，真实功能按路线图接入后打开。
+  // ---- 功能注册表（Host 侧）：每个条目来自对应功能模块的 feature 描述符 ----
+  // defaultEnabled：与 Client 半部保持一致。已接入的功能默认打开，
+  // 规划中的功能缺省 false，等实现后移除 roadmap 并打开。
   const FEATURES = [
-    {
-      id: 'balance',
-      name: '模型余额',
-      roadmap: '0.2.0',
-      description: '拉取所有模型 Provider 账户余额',
-    },
-    {
-      id: 'tokenlog',
-      name: 'Token 用量记录',
-      roadmap: '0.3.0',
-      description: '记录全部 LLM API 调用并统计',
-    },
+    fModels,
+    fVisionProxy,
+    fBalance,
+    fTokenlog,
     {
       id: 'animation',
       name: '任务动画',
-      roadmap: '0.4.0',
+      roadmap: '0.5.0',
       description: '任务进度动画与通知',
     },
   ]
@@ -39,24 +47,23 @@ export function apply(ctx) {
   const state = new Map()
   for (const f of FEATURES) state.set(f.id, { enabled: false, dispose: null, error: null })
 
-  // 每个功能的 Host 半部安装函数：返回 disposer，关闭功能时调用。
-  // 接入时在此实现，例如：
-  //   balance: () => {
-  //     const stop = ctx.interval(pullBalance, 60_000)
-  //     return () => stop()
-  //   },
-  const hostSetups = {}
+  // 自有 settings 命名空间（dsh-dock）：图片理解代理等插件配置的持久化；
+  // 读取走 settings.get（内存 resolved 值，写入经 settings.mutate，均热生效）
+  ctx.inject(['settings'], (sctx) => {
+    sctx.settings.register(DOCK_NS, DockConfig, {})
+  })
 
+  // 每个功能的 Host 半部安装函数：setup 返回 disposer，关闭功能时调用。
   function setEnabled(id, enabled) {
     const st = state.get(id)
     if (!st || st.enabled === enabled) return
     st.enabled = enabled
     st.error = null
     if (enabled) {
-      const setup = hostSetups[id]
-      if (setup) {
+      const f = FEATURES.find((x) => x.id === id)
+      if (f && typeof f.setup === 'function') {
         try {
-          st.dispose = setup() || null
+          st.dispose = f.setup(ctx) || null
         } catch (err) {
           st.error = String((err && err.message) || err)
           console.error('[dsh-dock] feature setup failed:', id, err)
@@ -72,6 +79,13 @@ export function apply(ctx) {
     }
   }
 
+  // 默认启用已实现的功能（与 Client 半部 defaultEnabled 对齐）。
+  // 目前 Host↔Client 的开关同步在 0.5.0（持久化 + 双侧注册表打通）落地，
+  // 在此之前 Host 侧开关以本处 defaultEnabled 为准。
+  for (const f of FEATURES) {
+    if (f.defaultEnabled) setEnabled(f.id, true)
+  }
+
   console.log('[dsh-dock] host half loaded; features registered:', FEATURES.map((f) => f.id).join(', '))
 
   // 插件卸载/更新时兜底清理仍在运行的功能
@@ -86,4 +100,4 @@ export function apply(ctx) {
       }
     }
   })
-}
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "dsh-dock",
-  "version": "0.1.0",
-  "description": "DeepSeek Harness 功能中枢插件：用一张管理面板统一注册、开关所有小功能（模型余额、Token 用量记录、任务动画等）。0.1.0 为基础框架版本，功能接入路线见 README。",
+  "version": "0.4.1",
+  "description": "DeepSeek Harness 功能坞插件（dsh-dock）：模块化功能中枢——每个功能一个 features/ 模块（可单独提取成包发布，又可经 dockBridge 装回面板）。含用量记录（LLM 调用记账/费用统计）、模型设置、图片理解代理、模型余额；侧栏入口 + 可拖拽弹窗（最大化/最小化/缩放）。",
   "type": "module",
   "main": "index.js",
   "files": [
     "index.js",
     "client.js",
-    "cordis.patch.yml"
+    "src/",
+    "features/",
+    "cordis.patch.yml",
+    "screenshots"
   ],
   "exports": {
     ".": "./index.js",
@@ -15,17 +18,23 @@
     "./package.json": "./package.json"
   },
   "dsh": {
-    "bundle": { "patch": "./cordis.patch.yml" },
-    "client": { "platform": "web" }
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
   },
   "keywords": [
     "dsh",
     "deepseek-harness",
     "cordis",
     "plugin",
+    "dock",
+    "function-dock",
+    "功能坞",
     "panel",
     "hub",
-    "feature-hub",
     "web",
     "dashboard"
   ],
@@ -38,5 +47,11 @@
   "homepage": "https://github.com/wycto/dsh-dock",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
   }
-}
+}