本地NPU生图 133563825as-ai/dsh-localdream

dsh-localdream

开源（MIT）的 DeepSeek Harness 专用插件：把手机端 Local Dream 的本地 NPU 生图接进对话 —— 一句话出图、图生图、放大与分块重绘，全程只跟本机 loopback 说话，不走云端、不计费、无内容审查。

插件不内置任何模型清单、不预设任何画风偏好：基准尺寸与默认步数 / CFG / 采样器全部从 Local Dream 后端现读，换模型、换机器都照样能用。属于你自己那台机器的偏好（默认负面词、比例、per-model 参数、提示词模板）都放在容器里的普通 JSON 文件里，随时可查可改。

运行期零依赖：dependencies 与 peerDependencies 都是空的，不需要软链、不需要 npm install，装它不会动你现有的任何东西。详见安装一节。

前置条件

1. 手机上装了 Local Dream（3.0.0-alpha.3 及以上实测通过，更低版本未验证）。
2. 在 App 里手动打开受控模式 —— 这一步只能手点：

Local Dream → 模型列表右上角 ⋮ → 设备互联 → 受控模式区块 → 「进入受控模式」

受控模式的服务在 AndroidManifest.xml 里是 exported="false"，外部唤起不了，插件也不会替你去点。

打开后会暴露两个端口，插件就用这两个：

| 端口 | 性质 | 用到的端点 |
| 127.0.0.1:8808 | 控制口（JSON API） | GET /info /models /status，POST /select /stop |
| 127.0.0.1:8081 | 生成口（native 后端） | POST /generate（SSE）、POST /upscale（raw body） |

自检：

curl -s --max-time 6 http://127.0.0.1:8808/info
{"app":"localdream","protocol":1,"version":"3.0.0-alpha.3","device":"..."}

没有响应就是受控模式没开或被系统回收了，回 App 里重点一次 —— 重试不会让它自己起来。

安装

git clone https://github.com/133563825as-ai/dsh-localdream.git ~/dsh-localdream

dsh plugin --profile web add link:~/dsh-localdream

装完重启 dsh 才生效。验证装上了：

dsh --profile web --dump-config | grep -A3 dsh-localdream

不需要装依赖，也不会碰你的环境

插件运行期零依赖：它只 import Node 内置模块，dependencies 和 peerDependencies 都是空的。

所以不要往插件目录里放 node_modules，也不要在那里跑 npm install —— 不需要。这一点是刻意的：

- 如果插件目录里有一条 node_modules -> <宿主>/node_modules 的软链，任何人误在插件目录跑一次 npm install，都会顺着链接把包写进宿主的 node_modules，污染整个 dsh 安装。这个插件从设计上不留这个口子。
- 插件不注册全局命令、不改宿主文件、不写 profile 之外的路径。它只做三件事：注册工具、在 <DSH_HOME>/localdream/ 下读写自己的 JSON、往 webServer 挂一组 /localdream/ 接口。
- 卸载就是 dsh plugin --profile web remove dsh-localdream，删掉目录即可；<DSH_HOME>/localdream/ 留着不影响任何东西，想一起清掉就删它。

这一条是给别人用的前提。 一台机器上装几十个插件时，最怕的不是功能少，而是某个插件在你没注意的时候动了别人的东西。

六个工具

| 工具 | 作用 |
| ld_status | 受控模式在不在线、当前挂着哪个模型、后端状态、生成口是否可连、已装模型与放大器清单。出图前先跑它。 |
| ld_select | 显式挂载模型并等到可出图。ld_draw 的 model 只在后端被回收时才重挂，想主动换模型得用它。 |
| ld_draw | 文生图 / 图生图。 |
| ld_enhance | mode="upscale" ×4 放大；mode="ultrafix" 分块重绘。 |
| ld_config | 查看与修改容器里的使用偏好、per-model 参数预设。 |
| ld_prompt | 提示词模板库：存、列、看、删。 |

典型对话：

帮我画一张在雨里撑伞的少女，竖版 → ld_draw({ prompt: '...', aspectRatio: '3:4' })

把这张图放大四倍再重绘成高清的 → ld_enhance({ mode: 'upscale', image: '...' }) → ld_enhance({ mode: 'ultrafix', image: '...', prompt: '...' })

出图与后处理流程

ld_status → ld_draw → ld_enhance(upscale) → ld_enhance(ultrafix)
1024 图 ×4 放大 分块重绘

一个容易搞混的点：UltraFix 本身不放大。它吃一张已经是目标尺寸的大图，按 tile 切开做分块 img2img 再混合重叠区。所以顺序永远是先放大、再 UltraFix。

upscale 的请求体是 raw RGB24，所以输入必须是 PNG（ld_draw 的默认输出格式就是 PNG，可以直接喂）。UltraFix 的输入走 base64，PNG / JPEG 都行。
UltraFix 只被 SD1.5 QNN 与 SDXL QNN 后端支持，MNN / Anima / DiT 后端会直接报 ultrafix not supported by this backend。

容器里的配置与提示词

都落在 <DSH_HOME>/localdream/（通常是 /root/.dsh/localdream/），全是普通 JSON，可以直接编辑：

localdream/
├── settings.json 使用偏好 ├── models.json per-model 参数预设 ├── prompts/ 提示词模板，一个模板一个 JSON └── out/ 出图输出

用工具改（推荐，会做校验）：

ld_config({ action: 'show' })
ld_config({ action: 'set', key: 'defaultAspectRatio', value: '3:4' })
ld_config({ action: 'set', key: 'models.<模型id>.cfg', value: '6' })
ld_config({ action: 'reset', key: '' })

ld_prompt({ action: 'save', name: '雨夜少女', prompt: '...', aspectRatio: '3:4', steps: 30 })
ld_prompt({ action: 'list' })

然后出图时带模板名即可套用：

ld_draw({ template: '雨夜少女' })

每次调用都重新读盘，改完立即生效，不需要重启宿主。

settings.json 的键

| 键 | 说明 | 默认 |
| defaultNegativePrompt | 默认负面提示词（cfg > 1 时生效） | 内置通用质量词表 |
| defaultAspectRatio | 默认宽高比 | 1:1 |
| defaultCount | 默认连出张数 | 1 |
| defaultOutputFormat | 默认落盘格式 | png |
| defaultModel | 后端被回收时默认重挂哪个模型 | 空（必须显式指定） |
| maxBatch | 单次连出张数上限 | 2 |

maxBatch 默认 2 是有意的：手机 NPU 一次连出更多会持续高负载、发热甚至顶掉内存。想要更多张，优先分多次调用。

参数从哪来

同一个数字可能在四个地方被定义，优先级从高到低：

1. 调用方显式传参 —— 这次出图的入参
2. 提示词模板 —— ld_prompt 存的模板里带的 steps / cfg / scheduler
3. 容器预设 —— models.json 里为该模型存的值
4. 后端模型默认值 —— /models 报出的该模型自己的 defaults
5. 全局兜底 —— 20 步 / CFG 7 / dpm

第 4 层是整个插件通用性的关键：它让插件适配任意模型，而不是绑定某一台机器上装了什么。工具返回里会有一个 参数来源 告诉你这次用的是哪一层。

已知限制与常见坑

- width / height 是无效字段。 真正决定成图尺寸的是 aspect_ratio：长边固定为该模型的基准尺寸（generation_size），短边按比例换算后向 8 的倍数取整（3:2 → 682.7 → 680，不是 683）。
- 后端对不认识的字段一律静默忽略。 图生图的输入图字段只有 image 一个；写成 init_image / input_image / image_base64 会照常返回一张 txt2img 的图，且不报任何错。
- cfg = 1.0 等于关掉负面提示词分支，此时 negativePrompt 写了也没用。要让它生效就把 cfg 提到 5~7。
- 图生图的输入图尺寸必须等于 aspectRatio 的换算值，否则后端报 Img size mismatch。先用 convert in.png -resize 576x768^ -gravity center -extent 576x768 out.png 标准化。
- /select 的宽高只改状态回显，不影响成图。
- 避开 _turbo 模型：吃内存，在 12G 机器上容易把后台进程一起挤掉。

排障

| 症状 | 原因 | 对策 |
| ld_status 报未在线 | 受控模式被回收或没开 | 回 App 里重点「进入受控模式」 |
| 状态 idle、8081 无监听 | native 后端被系统回收 | ld_draw 已内置自愈，会自动重挂（代价是一次冷启动） |
| 出图报「没有收到 complete 事件」 | 后端在生成中途被回收 | 重跑一次；仍失败先 ld_select 再重试 |
| gen 出来的却是上一个模型 | 后端还热着旧模型 | 用 ld_select 显式切换，别指望 ld_draw 的 model 主动换 |
| HTTP Error 404 on /select | host 在 idle 切换的窗口期偶发 | 重跑一次；仍 404 就 ld_select 重来 |
| 出图很慢（> 90s） | 冷启动未预热 | 正常，第二张起回到热态速度 |
| Img size mismatch | 图生图输入图尺寸不符 | 按 aspectRatio 换算值标准化 |
| ultrafix not supported by this backend | 当前后端不支持 | 换 SD1.5 QNN / SDXL QNN 后端的模型 |

稳定性建议：App 里的 「纯黑屏幕（保持运行）」 能保持屏幕常亮、避免 doze 回收；系统设置里给 Local Dream 开电池不优化 / 后台锁定。

界面

侧边栏底部一枚胶囊（压在「导出会话日志」上面），点开是完整面板。视觉沿用这套 GUI 既有的设计语言：--dsw-* 令牌，胶囊的尺寸与描边对齐同区域的 session-log pill，图标直接用宿主原语库里的官方图标（取法与 dsh-web-mobile 一致，取不到才回落到自绘 SVG）。

| 位置 | 内容 |
| 侧边栏胶囊 | 状态灯 + 图标 +「本地生图」+ 当前状态（模型名 / 15/29 / 未连接） |
| 点开后的面板 | 出图（提示词、模板、模型、比例、步数、CFG、采样器、张数 → 出图并预览）· 历史（输出目录里的图）· 模型（设备上已下载的模型与放大器，可一键切换）· 提示词（模板增删改）· 设置 |
| 设置 → 连接地址 | 胶囊形输入框，可手填控制口 / 生成口地址，带「测试连接」与「恢复自动」 |

面板里出的图和 Agent 调 ld_draw 出的图走的是同一条链路（src/draw-core.js），参数解析规则完全一致。同一时刻只允许一个出图任务：手机 NPU 扛不住并发。

连接地址：自动还是手动？

默认自动。 Local Dream 的受控模式固定监听 127.0.0.1:8808（控制口）与 127.0.0.1:8081（生成口），插件直接连，不需要填任何东西。注意这里没有"发现"过程——端口是 Local Dream 写死的，不是扫描出来的。

需要时才手动覆盖：只有把 Local Dream 跑在别处（另一台设备、端口转发）才用得上。在面板「设置 → 连接地址」里填，两个输入框都留空就等于恢复自动。改完下一次请求就生效，不用重启宿主。

地址的合法性在写入时就校验：必须 http(s)://host:port，不接受带路径或查询串的值。

开发

npm test # node --test，96 项，离线，秒级
npm run check # 逐个文件的语法检查

测试不需要装任何东西（没有 node_modules 也能全绿）—— 这本身就是「零依赖」这条约束的回归测试。

许可

MIT