UnforgetMemory/um-dsh-azimg

um-dsh-azimg

为 DeepSeek Harness agent 装上眼睛 —— 本地图片视觉分析动态插件

简体中文 | English

um-dsh-azimg 是一个 DSH 动态 Cordis 插件，为（尤其纯文本输入的）agent 提供本地图片分析能力：注册 um_analyze_img 工具，把本地图片交给选定的 vision 模型，返回结构化分析结果。

✨ 功能亮点

- 多图分析 —— 一次调用 1–8 张本地图片，交给同一 vision 模型，prompt 带顺序与文件名
- 真实格式嗅探 —— 魔数判定 PNG / JPEG / GIF / WebP，不信任扩展名；附件限额预检 + 批量原子入库
- 智能模型调度 —— provider 模型图片能力三分识别（image / text / unknown）+ 适配器复核；失败自动切换并聚合归因（凭据 / stopReason / diagnostic）
- 热切换 —— 设置页选择即时生效，无需重启；可用性探测 + 最近一次调用回显
- 原生 UI —— 设置页与工具卡完全遵循 DSH 设计令牌（--dsw-alias-），自动适配明暗主题
- 国际化 —— 设置页与工具卡全量支持简体中文 / 英文双语，跟随 DSH locale 服务规范，随语言切换自动重渲染

🚀 快速开始

本仓库是动态插件的函数体源码快照：host.js / client.js 即 cordis_define 的 code.host / code.client 原文（纯 JS function body，无 TS / import / JSX）。

在 DSH 会话中恢复插件：

1. 读取本仓库 host.js 与 client.js
2. 分别作为 cordis_define 的 code.host / code.client 提交
3. cordis_run 激活

激活后，agent 即可调用工具：

um_analyze_img(image_paths: ["C:/path/a.png", "C:/path/b.jpg"], question: "描述图中内容")

以 profile bundle 安装（推荐）

本仓库是完整 profile bundle（package.json → dsh.bundle + dsh.client → cordis.patch.yml 单行双面）：

dsh plugin --profile  add github:UnforgetMemory/um-dsh-azimg

安装即加入 profile 层栈并激活：Host 半 lib/index.js 注册 um_analyze_img 工具与 umimg/ 设置数据服务（Typert Remote，SRC 回退暴露），Client 半 lib/client.js（手写 factory-form bundle，零构建）提供设置页与工具卡；随 profile 常驻，重启不丢。升级：

dsh plugin --profile  update

故障兜底：可在 profile 的 cordis.patch.yml 写 - id: umimg, disabled: true 禁用该行。

⚙️ 工作原理

模型调用 um_analyze_img(image_paths[1..8], question?)
│
▼
Host 插件 ── 限额预检 → 魔数嗅探真实格式 → 批量原子入库 → 组装 prompt（文本 + N 个 image 块）
│
▼
候选模型 ── 面板已选择 → 只试指定模型（不静默切换）
未选择     → 依次尝试全部 image 能力模型（失败自动切换）
│
▼
llm.stream({ provider, model, messages }) → 进程内直调 vision 模型（附件像素由适配器就地解析）
│
▼
{ analysis, meta } —— 模型读 analysis，工具卡读 meta（模型 / 张数 / 尝试次数 / 耗时）

Host 依赖服务：tools · llm · attachments · fs

🖥️ 设置页与工具卡

- 设置页（settings.section · 「图片分析」）：按 provider 分组列出全部模型并标注图片能力（支持 / 未声明 / 纯文本），支持热切换、可用性探测与最近调用回显
- 工具卡（tool.call.toolview）：状态标签、模型徽标、切换次数、可点击图片名、结果折叠展开、耗时统计

🔌 RPC 契约（Client → Host，Package 私有）

| method | 入参 | 返回 |
|--------|------|------|
| state | { refresh?: boolean } | { selection, groups, stats, lastRun, limits, toolName } |
| select | { provider, model } 或 null | { selection, warning }（warning 非空 = 该模型不在支持图片列表） |
| probe | { provider, model } | { ok: true, provider, model, name, inputModalities, contextWindow } / { ok: false, detail, code } |

📦 仓库文件

| 文件 | 内容 |
|------|------|
| host.js / client.js | 动态形态源码快照（会话内 cordis_define 恢复用，见快速开始） |
| lib/index.js | 静态 Host 半：um_analyze_img 工具 + umimg/* Remote 设置服务 |
| lib/client.js | 静态 Client 半：手写 factory-form 浏览器 bundle（零构建） |
| package.json / cordis.patch.yml | dsh.bundle + dsh.client 声明与单行双面层 |
| README.en.md | English README |
| hero.jpg | 头图（README 引用；原稿本地留存于 .um.agents/local/，不入库） |

代码组织：两个函数体内部按 libraries → provider → scenario → app 分区（单函数体约束下的区内分层，依赖单向向下），execute 为线性编排入口。

📋 版本

当前 0.3.0 —— 变更历史见 CHANGELOG.md。

☕ 支持本项目

如果这个插件对你有帮助，欢迎请我喝杯咖啡：

📝 备注

- 动态插件生命周期跟随 DSH 进程：进程退出即消失，重新提交源码即可恢复；模型选择（selection）不持久化，重启回到「自动」
- 长期安装：本仓库已是完整静态 bundle——dsh plugin add 安装即随 profile 层常驻激活（lib/index.js + lib/client.js），无需会话内 cordis_define