PicGo 图床上传 PicGo/dsh-plugin

@picgo/dsh-plugin

@picgo/dsh-plugin

从 DeepSeek Harness 上传图片和文件到你的图床，由 PicGo 驱动。

Harness 能给智能体看截图，但没办法把本地文件变成链接。于是智能体写 README、渲染图表、截屏的时候，图片只能留在磁盘上，你一 push， 就成了死链。这个插件补上这一环。

上传走的是你在 PicGo 里已经配好的图床——PicGo Cloud、GitHub、S3、腾讯 COS、七牛，或者你装过的任何第三方上传插件。不用重新配置。没用过 PicGo 也没关系，插件会带你开通 PicGo Cloud 免费版。

如果 PicGo 桌面端正在运行，上传就走它，复用你在它窗口里配好的图床。否则在进程内上传。见上传路径。

安装

dsh plugin --profile web add @picgo/dsh-plugin

然后照常启动：

dsh --profile web

你会得到什么

picgo_upload —— 一个工具，本地文件需要变成链接时，模型会自己调用它。返回结构化结果，所以在 Code Mode 里可以直接用：

const { uploaded } = await tools.picgo_upload({ paths: ['/tmp/chart.png'] })
console.log(uploaded[0].imgUrl)

/picgo —— 一条命令，上传不消耗模型轮次：

| 命令 | 作用 |
| /picgo | 上传剪贴板里的图片 |
| /picgo <path>... | 上传一个或多个文件 |
| /picgo status | 显示当前图床和登录状态 |
| /picgo login [token] | 登录 PicGo Cloud |
| /picgo logout | 退出登录 |

Harness 里的 /picgo 命令和内置技能

一个内置技能，教模型什么时候该上传——往文档里插截图是主要场景——什么时候不该（你指定了目标位置，或者你要留一份本地副本）。

上传路径

这个插件有两条路能到达你的图床，每次上传时选一条：

1. PicGo 桌面端，前提是它正在运行。它会开一个本地上传服务，走这条路，上传就遵循你在它窗口里配好的图床。
2. 进程内 PicGo，其余情况——picgo 库读取 ~/.picgo/config.json。

这一点很关键，因为两者读的配置文件不一样。桌面端把设置存在系统应用数据目录（macOS 上是 ~/Library/Application Support/picgo/data.json），而库读的是 ~/.picgo/config.json。如果你一直只用图形界面，库这条路看到的是你从没碰过的配置——多半是空的，默认走 PicGo Cloud。优先用桌面端，才能让「直接沿用你现有的配置」这句话成立。
从 0.1.x 升级？ 如果桌面应用正在运行，并且两份配置指向不同主机，你的上传现在会落到应用的主机，而不是命令行的主机。把 gui.mode 设为 off 可保留旧行为。

/picgo status 会告诉你当前走哪条路由。关于桌面应用路由，有两点值得了解：

- 应用会把每个 URL 复制到剪贴板并弹出通知 —— 这是应用自身的行为，本插件无法关闭。
- 如果那里的上传因登录错误失败，请从应用自己的窗口登录。/picgo login 写的是 PicGo 命令行配置，桌面应用不读它。

首次运行

如果你从未配置过 PicGo，上传默认走 PicGo Cloud，需要一次性登录。免费额度够日常使用。

/picgo login

它会打开浏览器，完成后回报结果。如果你已经从 PicGo Cloud 控制台拿到 token，/picgo login <token> 立即生效。

模型永远不会替你执行这条命令：没有 token 时，登录会阻塞等待浏览器回调，导致会话卡住。它只会转达指令并等待。

已经在 PicGo 里用 GitHub、S3 或其他主机？以上都不适用 —— 你的现有配置原样使用，不涉及登录。

配置

每个字段都有可用默认值。在你的配置档 cordis.patch.yml 里覆盖：

- id: picgo
name: '@picgo/dsh-plugin'
config:
silent: true
timeoutMs: 120000

| 字段 | 默认值 | 含义 |
| configPath | '' | PicGo 配置文件；留空则用 PicGo 自己的默认路径（~/.picgo/config.json） |
| silent | true | 屏蔽 PicGo 的控制台输出和 picgo.log 写入 |
| timeoutMs | 120000 | 单次上传的等待时长 |
| registerSkill | true | 注册内置的 picgo-upload 技能 |
| registerCommand | true | 注册 /picgo 命令 |
| announceSignIn | true | 启动时，提示未登录 PicGo Cloud 的用户执行 /picgo login |
| gui | 见下文 | 如何连接正在运行的 PicGo 桌面应用 |

gui 控制 上传路由 中描述的桌面应用路由：

| 字段 | 默认值 | 含义 |
| gui.mode | auto | auto 在应用有响应时使用应用；off 从不尝试；only 强制使用应用，而不是上传到其他主机 |
| gui.host | 127.0.0.1 | 应用上传服务的监听地址 |
| gui.port | 36677 | 同上 |
| gui.secret | '' | 认证密钥，前提是你在应用里启用了。留空则回退到 $PICGO_SERVER_SECRET |
| gui.probeTimeoutMs | 1500 | 等待应用响应心跳的时长 |
| gui.probeTtlMs | 5000 | 心跳结果的复用时长，避免多文件上传时每个文件都重新探测 |
| gui.timeoutMs | 0 | 这条路由的上传截止时间；0 表示继承 timeoutMs |
补丁会替换整行 config，不会按 key 合并，所以想保留的字段都要重新写一遍。在 gui 内部，没写的 key 仍会回落到上面的默认值——只覆盖 gui.mode 没问题。

注意事项

上传后的链接是公开的。 任何人拿到 URL 都能打开，删掉的文件也可能留在缓存里。截图和文档配图无所谓；合同 PDF 或内部归档，上传前先想清楚。内置技能会让模型对看起来敏感的内容先跟你确认。

你的 PicGo 配置按只读处理，只有一个例外，且不受本插件控制：PicGo Cloud 拒绝已存的 token 时，PicGo 自己会把它从 ~/.picgo/config.json 里清掉。通过 /picgo login / /picgo logout 登录和登出也会写入 token，这在意料之中。

剪贴板上传需要桌面会话，而且只能通过 /picgo 触发——模型永远拿不到上传剪贴板的途径，因为它不知道剪贴板里有什么。

回落到进程内上传的路径刻意收得很窄。 如果桌面应用在检查和上传之间退出，上传会在进程内重试。但上传被拒、缺少 auth secret、超时，都只报错，不会换个地方重试：应用可能已经收下了文件，悄悄重传会在你没选的图床上多出一份。

通过应用上传卡住时，看看它的设置里是不是开了「上传前重命名」——那会弹对话框等人点，智能体会话里没人会去点。超时提示里也写了这一点。

开发

pnpm install
pnpm build
pnpm test

pnpm test:live 还会针对运行中的 PicGo 应用跑一遍桌面应用路径。它不在 pnpm test 里，因为它会把真实文件上传到你真实的图床。

想不打包、直接对着 dsh 源码检出跑，写一个 cordis.dev.yml（已 gitignore——路径因机器而异）：

- insert:
- id: picgo
name: '/absolute/path/to/dsh-plugin/lib/index.js'

然后在 dsh 检出目录里执行：

pnpm dsh web --patch /absolute/path/to/dsh-plugin/cordis.dev.yml

路径必须是绝对路径：补丁只添加配置，不会改变加载器的解析根目录。

发布

@picgo/bump-version 一步搞定升版本、写 changelog、提交、打 tag：

pnpm release # patch: 0.1.0 -> 0.1.1
pnpm release:minor # 0.1.0 -> 0.2.0
pnpm release:major # 0.1.0 -> 1.0.0
pnpm release:beta # 0.1.0 -> 0.1.1-beta.0
pnpm release:dry # print what would happen, change nothing

然后推 tag——发布就是靠它触发的：

pnpm push-release
release 工作流在发布前会跑类型检查、测试和构建；如果 tag 与 package.json 不匹配，就拒绝发布。预发布 tag 会各自选择 dist-tag（-beta.x → beta，-alpha.x → alpha，其他预发布 → next），所以 npm install @picgo/dsh-plugin 永远不会解析到预发布版本。

npm 认证

包还不存在时，npm 无法为它配置 trusted publisher，所以首次发布和之后的每次发布走不同的认证方式。

首次发布 —— 需要仓库密钥 NPM_TOKEN（一个 granular token，对 @picgo scope 有发布权限）：

gh secret set NPM_TOKEN --repo PicGo/dsh-plugin

首次发布落地之后，改用 trusted publishing，这样就不涉及长期有效的 token。在 npmjs.com 上打开该包 → Settings → Trusted Publisher，然后登记：

| 字段 | 值 |
| Publisher | GitHub Actions |
| Organization or user | PicGo |
| Repository | dsh-plugin |
| Workflow filename | release.yml（只填文件名，不是路径） |
| Environment name | 留空 |
| Allowed actions | npm publish |

工作流已经设置了 id-token: write，所以这边不用改任何东西 —— npm 会自动优先选 OIDC，而不是 token。一旦某次 trusted-publish 发布成功，就删掉 NPM_TOKEN 密钥并吊销该 token，然后把 Settings → Publishing access 设为 "Require two-factor authentication and disallow tokens"。

Trusted publishing 需要 npm ≥ 11.5.1，所以 release 工作流跑在 Node 24 上（自带 npm 11.x）。Node 22 自带 npm 10.x，会报一个误导性的 404。这个选择只影响执行发布的那台机器 —— 包本身仍然支持 Node ^22.19.0 || >=24.0.0，CI 也在 22 上测试。

兼容性

需要 DeepSeek Harness 0.2.1-rc.2 或更高版本（已在 0.2.1-rc.2 和 0.2.1-rc.3 上测试）以及 PicGo Core 3.0.1。需要 Node ^22.19.0 || >=24.0.0。更旧的 Harness 版本会把这个版本判为不兼容；那些版本请继续用 @picgo/dsh-plugin@0.2.0。

桌面应用这条路需要 PicGo 应用足够新，能暴露本地上传服务器。如果你的版本更旧，gui.mode: auto 就是永远找不到它，一切照旧在进程内运行。

Harness 是开发者预览版，API 经常变。如果某个版本弄坏了这个插件，请开 issue。

许可证

MIT