夸克网盘助手 shimiei/dsh-better-quark-drive

dsh-better-quark-drive

让 DeepSeek Harness 里的 AI 一句话就能操作夸克网盘：上传 + 生成分享链接一步到位，搜索 / 浏览 / 转存 / 下载全部工具化。

这是什么

dsh-better-quark-drive 是 DeepSeek Harness 的 cordis 插件：它把夸克网盘官方命令行（quarkclouddrive/scripts/quark-drive.cjs）包装成 12 个 AI 友好的工具。

不重写协议、不落地凭证——只做三件让模型少犯错的事：

1. 把 3 步并成 1 步：quark_send = 上传 → 分享 → 返回链接，模型不必拆成三次调用。
2. 把机器输出变成模型输入：命令行输出 NDJSON（progress/list/result/artifact），插件只回一段紧凑的 Markdown 表格 + 可直接复用的 fid。
3. 把错误码变成下一步：14001、32003、-403 这类返回值，插件会翻译成「该怎么改参数」的提示，而不是把原始 JSON 丢给模型猜。

flowchart LR
U[你：把这个 PDF 发到夸克] --> A[DSH Agent]
A -->|quark_send| P[dsh-better-quark-drive]
P -->|spawn + 自动 session 参数| C[官方 quark-drive.cjs]
C -->|NDJSON| P
P -->|链接 / 提取码 / fid| A
A -->|可点击链接| U

为什么不是直接让 AI 调命令行

| 裸命令行 | 本插件 |
| 每条命令都要 --session-input / --session-id，模型容易瞎编 | 插件按 DSH 会话自动生成并复用 |
| 输出是 NDJSON 流，result 常被 list / progress 淹没 | 解析成单一对象 + Markdown 表格 |
| 上传要 2 次调用才拿到链接（upload → share → 手抄 fid） | quark_send 一次完成 |
| 14001 upload dir blank 需要人判断「要不要传根目录」 | 自动回落根目录，并在结果里明说 |
| notice.text 容易被忽略（合规提示丢失） | 每条结果原样附在末尾 |
| 超时、授权过期只会卡住 | 明确报错 + 可执行的修复步骤（quark_setup） |

安装

前置：先有官方命令行

插件不自带夸克 API 实现，需要本机已有 quarkclouddrive 的命令行：

官方 skill 放在下列任一位置即可被自动发现 $DSH_HOME/skills/quarkclouddrive/ ~/.agents/skills/quarkclouddrive/ ~/.claude/skills/quarkclouddrive/ bash scripts/install.sh # 安装 / 更新 CLI 并完成登录

找不到命令行时，任何工具都会返回安装指引，而不是抛栈。

方式一：DSH 插件（推荐）

把本仓库放进 DSH 的插件搜索路径，或直接在配置档里安装：

在 DSH profile 目录下
pnpm add dsh-better-quark-drive

package.json 已经声明了 dsh.install（tarball / zip / git）与 dsh.bundle.patch，DSH 会读取 cordis.patch.yml 自动插入插件行。

方式二：本地开发 / 私有安装

git clone https://github.com/shimiei/dsh-better-quark-drive.git
cd dsh-better-quark-drive
npm run smoke # 离线自检，不需要网盘账号
npm run smoke:live # 额外验证 CLI 与授权（只读 get-user-info）

然后在配置档的 package.json 里 link: 到该目录（或 pnpm add file:../dsh-better-quark-drive），重启 DSH 生效。

方式三：只改配置

已经装过插件的话，只想调整行为——改 cordis.patch.yml 里的 config，重启即可，无需重装：

- insert:
- id: better-quark-drive
name: 'dsh-better-quark-drive'
config:
shareExpireDays: 30 # 默认分享 30 天 shareUrlType: 2 # 默认私密链接（带提取码）

工具清单

| 工具 | 作用 | 典型触发语 |
| quark_send | 上传 + 分享，返回链接、提取码、有效期 | 「把这个文件用夸克发给我」 |
| quark_upload | 只上传，返回 fid | 「先存到网盘里」 |
| quark_share | 已有 fid → 生成分享链接 | 「把那个文件夹分享出去」 |
| quark_search | 关键词搜索，返回名称/大小/时间/fid | 「找我网盘里那份报告」 |
| quark_browse | 列出目录直接子项 | 「我网盘里都有什么」 |
| quark_mkdir | 新建文件夹 | 「建个 2026 归档 文件夹」 |
| quark_move | 移动文件到指定目录 | 「把这些都挪到归档」 |
| quark_saveas | 转存别人的分享链接（支持提取码） | 「这个链接帮我转存」 |
| quark_download | 下载到本地目录 | 「把那个 PDF 下下来」 |
| quark_whoami | 会员类型 / 容量占用 | 「网盘还剩多少空间」 |
| quark_setup | 环境检查、安装脚本、登录指引 | 「夸克怎么用不了」 |
| quark_help | 工具速查表 | 「你有哪几个夸克工具」 |

fid 是插件里唯一需要传递的「中间变量」：search / browse / upload 都会返回它，share / move / download 都吃它。模型不需要记住格式，照抄即可。

一次典型对话

你：把 D:\reports\q3.pdf 传到夸克，给我个 7 天的链接

AI：quark_send({ paths: ["D:\\reports\\q3.pdf"], expireDays: 7 })

已上传并生成分享链接 ✅
- q3.pdf（2.4 MB）链接：https://pan.quark.cn/s/xxxxxxxx 链接类型：公开链接 ｜ 有效期：7 天 fid：209a7f1e…

分享有效期与链接类型都是入参，也可以固化成插件默认值：

| expireDays | 含义 |
| 0 | 永久有效 |
| 1 / 7 / 30 / 60 / 100 / 180 | 对应天数（CLI 的 --expired-type 枚举） |

urlType: 2 时服务端会自动生成提取码，插件把 passcode 一并返回。

配置

| 键 | 默认值 | 说明 |
| enabled | true | false 时整套工具下线 |
| cliPath | '' | 留空则自动发现 quark-drive.cjs |
| shareUrlType | 1 | 1 公开，2 私密（带提取码） |
| shareExpireDays | 7 | 分享默认有效期（天），0 = 永久 |
| timeoutMs | 180000 | 普通命令超时 |
| uploadTimeoutMs | 1800000 | 上传 / 下载超时 |
| maxRows | 20 | 列表类工具单次最多回给模型多少行 |

环境变量 DSH_QUARK_CLI / QUARK_DRIVE_CLI 也会被当作 CLI 路径候选。

设计要点

- 默认不猜目录：parentFid 是选填参数，插件不会替你发明一个目录。只有 CLI 自己报 14001 upload dir blank（本机没配默认上传目录）时，才会重试一次网盘根目录，并在结果里写明「本次已上传到根目录」。
- 一次重试，不掩盖失败：除上述情形外不做静默重试；失败就带着提示抛出来。
- notice.text 一定透出：官方 CLI 的提示文本（升级/会员/合规）逐字附在结果末尾，不会被摘要吞掉。
- 启动不依赖外部状态：插件挂载时只注册工具，不探测网络、不读 token；环境问题延后到第一次调用。

细节实现见 docs/design.md。

隐私与安全

- 插件不读取、不缓存、不上传任何凭证；登录态由官方 CLI 自己维护。
- 日志只输出「CLI 是否找到」「注册了几个工具」，不打印账号标识、文件路径或 token。
- 仓库内的示例链接、fid、路径均为占位符；测试脚本使用临时会话 id。
- 除非显式 urlType: 2，生成的链接是公开链接——别把公开链接贴到公开场合。

开发

npm run smoke # 12 个工具 spec 校验 + 配置归一化 + CLI 发现
npm run smoke:live # 追加一次真实只读调用（get-user-info）

scripts/smoke.mjs 在 DSH 之外运行时用内置的 defineTool 兼容层，因此在任何 Node ≥ 18 环境都能跑，不会污染宿主。

目录结构：

lib/cli.js # CLI 发现、spawn、NDJSON 解析、错误 → 提示 lib/tools.js # 12 个 defineTool 规格与业务编排 lib/format.js # 体积/时间/表格/markdown 渲染 lib/index.js # cordis 入口（inject: ['tools']） cordis.patch.yml # 插件行与默认配置

兼容性

- DSH：dshTarget: 0.2.0-rc.2，依赖 @deepseek-ai/dsh-tools（宿主注入）。
- 官方 CLI：quarkclouddrive ≥ 1.0.x（quark-drive.cjs）。
- Node：≥ 18（ESM + top-level await）。

License

MIT © dsh-better-quark-drive contributors

本项目只封装命令行调用方式，不包含夸克网盘服务端代码与任何账号数据；请遵守夸克网盘的服务条款。