PicGo 图床上传PicGo/dsh-plugin

@picgo/dsh-plugin

@picgo/dsh-plugin

通过 DeepSeek Harness，由 PicGo 提供支持，将图片和文件上传到你的图床。

Harness 可以向你的 agent 展示一张截图，但它无法将本地文件转换为链接。因此，当 agent 编写 README、渲染图表或截取屏幕截图时，图片会留在磁盘上，而  在你推送的那一刻就变成了死链接。这个插件填补了这一空白。

它通过你在 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 ... | 上传一个或多个文件 |
| /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。如果你只用过 GUI，那么库路径看到的将是一个你从未碰过的配置——很可能为空，并默认使用 PicGo Cloud。优先使用应用，才让“它只是使用我现有的设置”这句话成立。
从 0.1.x 升级？ 如果桌面应用正在运行，并且两个配置指向不同的主机，你的上传现在会落到应用的主机上，而不是 CLI 的主机。设置 gui.mode: off 以保持旧行为。

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

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

首次运行

如果你从未配置过 PicGo，上传默认使用 PicGo Cloud，这需要一次性登录。免费套餐足以满足日常使用。

/picgo login

这会打开你的浏览器，并在完成后回报结果。如果你已经从 PicGo Cloud 仪表盘获得了令牌，/picgo login  会立即完成。

模型绝不会替你运行此命令：没有令牌时，登录会阻塞等待浏览器回调，这会导致会话挂起。它会转达指令并等待。

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

配置

每个字段都有可用的默认值。从你的 profile 的 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，而不是合并键，因此请重新声明你想保留的每一个字段。在 gui 内，未设置的键仍会回退到上面的默认值——只覆盖 gui.mode 是可以的。

注意事项

上传的链接是公开的。 任何拿到 URL 的人都能打开它，而且已删除的文件可能仍留在缓存中。对于截图和文档图片来说没问题；但在上传合同 PDF 或内部归档之前，请三思。内置技能会告诉模型，对于任何看起来敏感的内容都要先确认。

你的 PicGo 配置被视为只读，但有一个本插件无法控制的例外：当 PicGo Cloud 拒绝已存储的令牌时，PicGo 自身会从 ~/.picgo/config.json 中清除它。通过 /picgo login / /picgo logout 登录和登出也会写入该令牌，正如你所预期的那样。

剪贴板上传需要桌面会话，并且只能通过 /picgo 触发——模型永远不会获得上传你剪贴板内容的途径，因为它无法知道剪贴板上有什么。

回退到进程内路由是刻意收窄的。 如果桌面应用在检查与上传之间停止运行，上传会在进程内重试。但被拒绝的上传、缺失的认证密钥或超时都会被报告出来，而不会在其他地方重试：应用可能已经接受了该文件，静默重新上传会在你并未选择的托管服务上留下第二份副本。

如果通过应用上传卡住了，请检查其设置中是否启用了“上传前重命名”——这会打开一个对话框并等待人工操作，而在代理会话中没有任何东西会去应答它。超时消息也会说明这一点。

开发

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 会一步完成版本号提升、编写变更日志、提交和打标签：

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

然后推送标签——这才是触发发布的操作：

pnpm push-release
release 工作流在发布前会运行类型检查、测试和构建，并且如果标签与 package.json 不匹配，就会拒绝发布。预发布标签会选择自己的 dist-tag（-beta.x → beta，-alpha.x → alpha，其他任何预发布版本 → next），因此 npm install @picgo/dsh-plugin 永远不会解析到预发布版本。

npm 身份验证

npm 无法为一个尚不存在的包配置可信发布者，因此首次发布和之后的每次发布采用不同的身份验证方式。

首次发布 —— 需要一个 NPM_TOKEN 仓库密钥（一个对 @picgo 范围具有发布权限的细粒度令牌）：

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

在首次发布落地之后，切换到可信发布，这样就不涉及长期有效的令牌。在 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 而不是令牌。一旦可信发布成功，删除 NPM_TOKEN 密钥并撤销该令牌，然后将 Settings → Publishing access 设置为 "Require two-factor authentication and disallow tokens"。

可信发布需要 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.1.1-rc.2（2026-08-22）和 PicGo Core 3.0.1 进行测试。需要 Node ^22.19.0 || >=24.0.0。

桌面应用路线需要一个足够新的 PicGo 应用，以暴露本地上传服务器。如果你的版本较旧，gui.mode: auto 只会永远找不到它，一切都会像以前一样在进程内运行。

Harness 是开发者预览版，其 API 经常变化。如果某个版本破坏了此插件，请提交 issue。

许可证

MIT