dsh-picflow

一句话

粘贴的截图按编号引用：每一次 Ctrl+V 的图都会进入附件库、拿到固定编号（图片N）、列在输入框旁的面板里，并可以一键把「图片N」这张引用芯片插到光标处。

为什么需要它

往输入框 Ctrl+V 一张图，内核只把它当成随手贴的草稿附件——内存里的 object URL，字节要等你按发送才上传。在那之前，磁盘上的附件库根本没有它，于是谁都没法指向它：@ 菜单里没有这一条，也没有一个编号让你说清「我刚才贴的那张」。

结果只能靠嘴描述：「第一张」「图2」——三张就说不清，切一趟对话回来更说不清。

dsh-picflow 补的就是这个缺口：粘贴那一刻就把图收进官方附件库，它拿到的编号，和发送之后是同一个；插进正文要么点一下，要么（开着自动插入时）一下都不用点。

它做什么

• 粘贴即入库。 客户端每 350 ms 读一次输入框的实时草稿附件，把字节 POST 给插件自己的宿主路由，由宿主调用官方 attachments.saveImage。同一套规范化、同一个 sha256、同一个对象——所以不会出现两条记录，编号也不会变。
• 编号固定。 图片N 按全库文件 mtime 升序排定：最早的那张是 图片1。新图只会拿到更大的号，所以你昨天写下的编号，今天还是同一张图。
• 输入框旁的面板。 N 张图 胶囊展开成「引用素材」：最新的在最前，一格一张图，带编号、时间、大小，以及 插到光标处、挂上（把这张存图重新挂成当前消息的附件，模型直接看到图）、路径（复制 markdown 引用）。点缩略图是全屏放大浮层，点一下或 Esc 关闭。
• 搜索与筛选。 图片12、10-04、昨天、png、sha 前缀、128kb 都能搜；另有按天筛选与 最新 / 最早 / 最大 排序，翻页一次 120 张。
• @图片 源。 打 @ 会多出一个「图片」分组，选中插入的就是同一张编号引用芯片，和面板按钮完全等价。
• 自动插入（默认开）。 开着时：入库完成后引用芯片自己落到光标处，面板不弹出来挡你打字。想改回手动，在面板头部点 自动插入 开/关——关掉后粘贴只入库，插不插由你点。这个选择记在 localStorage 里。
• 如实说明代价。 因为入库发生在粘贴时，一张图即便你最后没发送，也已经进了库。 这正是它的意义，但它确实是行为变化，所以写在这里，而不是让你事后发现。

安装

curl -fsSL https://raw.githubusercontent.com/XWIDE/dsh-picflow/main/install.sh | sh

手动等价写法：

dsh plugin --profile web add git+https://github.com/XWIDE/dsh-picflow.git

装完把承载插件的应用重启一次——宿主半边在启动时注册 HTTP 路由：

• DSH 桌面端：重启 DSH NEXT（它标题栏的重启菜单里也有「重新加载界面」，但那只够刷新浏览器半边）。
• dsh web：重启 dsh 进程。

没有构建步骤、没有运行时依赖，源码安装直接可用，不会弹 allowBuilds 授权。

它怎么工作

部件	作用
GET /plugins/dsh-picflow/version	廉价库指纹（只 readdir + stat 分片目录）。客户端每 3 秒问一次，变了才重取清单。
POST /plugins/dsh-picflow/admit	body 就是图片字节。按字节嗅探格式（不信 content-type），调官方 attachments.saveImage，返回 {sha, ordinal, label, bytes, ext, path?}。
GET /plugins/dsh-picflow/images	清单：limit、materialize、offset、q、day、source、sort、pin、session。materialize=N 把前 N 行落进工作区，pin=<sha> 只落指定那一张。
GET /plugins/dsh-picflow/raw	图片字节，媒体类型也是按文件内容嗅探的。

四条路由都走宿主信任栅栏：默认只对回环地址开放，除非你把某个来源写进 trustedHosts。

插到光标处 需要一个模型读得到的路径，所以宿主会在你的工作区留一份副本：<工作区>/.dsh/pics/pic-<MMDD-HHMM>-<sha8>.<ext>（已有一模一样的副本就跳过），插入的引用芯片指向它，地址形如 dsh-resource://file/absolute/...。

兼容性

dsh-picflow	Harness	说明
0.1.0	0.2.0-rc.2（实测）	针对桌面端 0.2.0-rc.2 开发与测试：真实 profile 上验证过 install 与 start；uninstall / rollback 标为 unknown，因为这个版本上还没实际演练过。

宿主半边需要 Node.js 22.19+ 或 24+（与 harness CLI 自身的下限一致）。

浏览器半边由宿主模块加载器载入、require('react')；本插件不声明任何 npm 依赖，也不钉任何官方 @deepseek-ai/* 包，因此宿主 roster 的版本漂移不会把安装带崩。

配置

- id: picflow
  name: 'dsh-picflow'
  config:
    trustedHosts: []        # 除回环外允许访问本插件路由的来源，如
                            # ["my-box.local:3080", "192.168.1.20:3080"] —— host[:port]

非回环来源没登记就访问路由会得到 403，响应里直接给出该补的那一行。

其余都是自动发现的，不需要配：附件库从 DSH_HOME（取不到时 ~/.dsh）下的 attachments/v1 读，落盘副本写进会话自己的工作区。

边界

• 格式：PNG、JPEG、WebP、GIF。官方附件库不收 BMP，/admit 会回 400 unsupported-image；改名伪装的文件按内容嗅探被拒，不看扩展名。
• 大小：官方库单张上限 20 MB；/admit 的请求体上限 24 MB（超出回 413 body-too-large）。
• 清单：单次请求默认 60 行、最多 400 行；面板一次翻 120 张。

隐私

不联网。插件只读本机附件库、只往会话工作区写副本，只跟宿主自己的回环路由通信；没有遥测，没有外部端点，图不会被重新上传到任何地方。

它只在本地留两样东西：<工作区>/.dsh/pics/（图片副本，引用要靠它解析）和一个 localStorage 键 dsh-picflow.autoInsert（那个开关）。

疑难

• 面板提示「宿主半边还是旧版」 —— 客户端半边比已加载的宿主模块新。重启应用；刷新页面换不掉宿主代码。
• 从局域网地址访问得到 403 —— 把那个 host[:port] 加进 trustedHosts（响应里给了可照抄的那行）。
• 粘了图但面板里没有 —— 草稿附件是数据源，所以图要真的落在当前会话的输入框里。面板的 刷新 会强制重取，@图片 读的是同一份清单。
• 点 插到光标处 说「还没落盘副本」 —— 引用需要磁盘路径；如果这个会话没有可写入的工作区，插件会退而给出纯 markdown 形式。
• 自动插入没触发 —— 它不跟你抢：输入框正忙（有回合在流式输出）或光标不在输入框时，它会改为弹出面板并说明原因，你点一下即可。
• 贴了又删掉的图还在库里 —— 预期行为，见上面的取舍。从库里删掉那个对象，面板里也就没了。

开发

node tests/host.mjs     # 宿主路由：24 项检查
node tests/chip.mjs     # 客户端半边：78 项检查（假加载器 + 假 React，不开浏览器）

两套测试都是纯 Node、零依赖。

卸载

dsh plugin --profile web remove dsh-picflow

想把落盘副本也清掉就删 <工作区>/.dsh/pics/；图片本体在官方附件库里，本插件不动它们。

许可

MIT —— 见 LICENSE。

作者

X-WIDE —— GitHub @XWIDE · B 站 374064919 · xiupk@sina.com.cn

有问题、想提需求，开 issue 就行。