123云盘 cny919191/dsh-123pan

dsh-123pan

把 123 云盘 接进 DeepSeek Harness：用手机号 / 邮箱 + 密码登录，直接在 DSH 里上传、下载、浏览和管理网盘文件，并把工作区增量备份到云端。

不需要安装 123 云盘桌面客户端，也不需要开放平台的 appid / secret。

dsh 插件 ──工具/设置页──▶ 123pan-core.exe（C++ 静态链接）──▶ 123 云盘

网络请求、MD5、16MB 分片上传、CDN 下载、token 加密全部在 C++ 核心里完成；插件层只用 Node.js 做参数拼装与 UI，不依赖 Python，也不需要任何运行时。

功能

| 功能 | 说明 |
| 手机号 / 邮箱 + 密码登录 | 密码只用于换一次 token，不落盘 |
| API Key / Token 登录 | 直接粘贴客户端 JWT，无需账号密码；也可用配置 apiToken 完全免登录 |
| token 本地加密 | Windows DPAPI，绑定当前用户 |
| 自动续期 | 每次 status 顺手刷新 token |
| 浏览 / 搜索 | 列目录、翻页、按文件名搜索、回收站 |
| 上传 | MD5 秒传 + 16MB 分片，进度可见 |
| 下载 | 直链 + 断点无关的单流写入，受限于 CDN 能力 |
| 直链 | 取临时签名下载链接，可给外部使用 |
| 重命名 / 移动 / 删除 | 列表里可直接把文件拖到文件夹上移动；删除默认进回收站，可再彻底删除 |
| 工作区增量备份 | 跳过未变化文件、保留目录结构、可预演 |
| 侧边栏面板 | 左侧栏「123 云盘」图标，点开就是网盘文件浏览 |
| 拖拽上传 | 把文件拖进侧栏面板（或点「选择文件」）直接上传到当前目录 |
| 拖拽下载 | 点文件行的「下载」，默认存到工作区根目录，可在面板底部改 |
| 在线预览 | 点文件名直接看文本 / 图片 / 视频 / 音频 / PDF，不用先下载 |
| 主题跟随 | 设置页与侧栏面板只用宿主主题 token，亮/暗色自动跟随 |

安装

方式一：下载 Release（推荐）

Releases → 下载 dsh-123pan-vX.Y.Z.zip，解压到固定目录（例如 D:\plugins\dsh-123pan）。

这个 zip 是插件目录，不是安装程序，不需要运行任何 exe。

然后把它接线进 profile：

1) 目录联接（不需要管理员权限） cmd /c mklink /J "%USERPROFILE%\.dsh\profiles\<profile>\node_modules\dsh-123pan" "D:\plugins\dsh-123pan"

2) 编辑 %USERPROFILE%\.dsh\profiles\<profile>\package.json，两处都要加：

{
"dependencies": { "dsh-123pan": "file:D:/plugins/dsh-123pan" },
"dsh": { "profile": { "bundles": ["...", "dsh-123pan"] } }
}

3) 完全退出 DSH（任务管理器确认 DeepSeek Harness.exe 全部消失）再打开。

方式二：从源码

1) 在插件目录构建核心（需要 MSYS2 ucrt64 的 g++）
cd native/core
./build.sh # Linux/macOS 下请改用对应工具链，见下文

2) 从本地目录安装进 DSH profile
dsh plugin --profile <profile> add /absolute/path/to/dsh-123pan

在 DSH 的「设置 → 插件」里确认 dsh-123pan 已启用，然后打开「设置 → 123 云盘」登录。

详细步骤（含「装了没反应」的排查）见 docs/USAGE.md §2。

关于核心可执行文件

native/core/123pan-core.exe 是用 MSYS2 ucrt64 的 g++ 编译的静态链接程序：

* 只依赖 Windows 系统 DLL（ws2_32 / crypt32 / shell32 / ole32）；
* OpenSSL 静态编入，不需要额外 DLL，也不需要 openssl.exe；
* TLS 根证书在运行时从 Windows 证书存储（LOCAL_MACHINE\ROOT）加载，不依赖任何 cert.pem，用户机器上无需额外配置。

重新构建：

Windows（MSYS2 ucrt64）
cd native/core && ./build.sh

其他平台（需自行替换 OpenSSL 与 Winsock 相关部分） g++ -O2 -std=c++17 main.cpp api.cpp http.cpp winutil.cpp -o 123pan-core -lssl -lcrypto

核心当前实现了 Windows 传输层（Winsock + DPAPI + 证书存储）。
移植到 Linux/macOS 需要替换 http.cpp 的连接层与 winutil.cpp 的加密/路径部分，其余 API 逻辑（api.cpp）与协议无关，可直接复用。

- 给人看：docs/USAGE.md（安装、登录、上传下载、备份、AI 工具、常见问题、安全说明）
- 给 Agent 看：AGENT.md（上传自己生成的文件时照这个做，不要生成 .py 中转脚本）

两种入口

| 入口 | 位置 | 用途 |
| 侧边栏面板 | 左侧栏的云朵图标 | 日常上传/下载/浏览，支持拖拽文件 |
| 设置页 | 设置 → 123 云盘 | 登录、容量、备份、关于 |

拖拽上传的实现：浏览器无法把本地路径交给宿主，所以面板把 File 读成 base64 POST /api/dsh-123pan/uploadBytes，宿主落到临时文件后交给核心上传，用完即删。
受此限制，单个文件上限取 maxFileBytes（默认 200MB）。
下载目录的优先级（前面的赢）：

1. 请求里的 out（完整文件路径）
2. 请求里的 dir（目录）
3. 插件配置 downloadDir
4. 会话工作区根目录（默认就是这里，例如 D:\python）

面板底部有「下载目录」输入框：默认自动跟随当前工作区。
在侧栏切换工作区后，下载目录会立刻跟着变（无需重启）。手动填一个路径后会固定下来，点旁边的「跟随工作区」按钮即可恢复自动跟随。

⚠️ 核心 123pan-core.exe 位于工作区，通常带 Low 完整性标签，因此它能写工作区，但写不了 %TEMP%、%USERPROFILE%\.dsh、桌面这类 Medium 目录。
下载因此分两步：先直连目标；若报 cannot open output file，改为先下到 <工作区>\.dsh-123pan-staging\，再由 Node 搬到目标位置（Node 两边都能写）。
这样"下载到 .dsh"或"下载到桌面"也能正常工作。

工作区跟随是怎么实现的

- 客户端订阅会话 store，取 retainedBy.mainView > 0 的那个会话（即主视图正在显示的会话）的 cwd，切换工作区时它会变，面板随即重算下载目录；另有 8 秒轮询 + 窗口获得焦点时刷新兜底。
- Host 端 getWorkspaceRoot() 按「最近有活动」的会话 cwd 解析（最后一条事件时间），供 HTTP API 使用；都取不到才退回 workingDirectory.defaultDirectory / 进程 cwd。

给 AI / 脚本的 JSON API

插件在宿主里注册了本机 HTTP 路由，AI 不需要生成任何 .py 脚本，直接调即可：

按本地路径批量上传（推荐）
curl -X POST http://127.0.0.1:<port>/api/dsh-123pan/uploadBatch -H 'content-type: application/json' -d '{"files":["D:\work\a.zip","D:\work\b.txt"],"parentId":0}'

下载（不传 out/dir 时落到工作区根目录）
curl -X POST http://127.0.0.1:<port>/api/dsh-123pan/download -H 'content-type: application/json' -d '{"fileId":123,"name":"a.zip","dir":"D:\work"}'

完整路由：status · login · loginToken · logout · list · mkdir · upload · uploadBytes · uploadBatch · download · preview · media(GET) · url · rename · move · trash · purge · version · diag · scan · backup · backups · forget

状态查询：GET/POST http://127.0.0.1:<port>/api/dsh-123pan/status（只接受 POST + 本机回环）。

直接用 API Key（免账号密码）

拿到 token 后有三种用法，选一种即可：

1) 验证并存入本地加密会话（一次，之后 upload/download/list 都能用）
curl -X POST http://127.0.0.1:<port>/api/dsh-123pan/loginToken \
-H 'content-type: application/json' \
-d '{"token":"eyJhbGciOiJIUzI1NiIs..."}'

2) 之后正常上传 / 下载
curl -X POST http://127.0.0.1:<port>/api/dsh-123pan/upload \
-H 'content-type: application/json' \
-d '{"file":"D:\\work\\a.zip","parentId":0}'
curl -X POST http://127.0.0.1:<port>/api/dsh-123pan/download \
-H 'content-type: application/json' \
-d '{"fileId":123,"name":"a.zip","dir":"D:\\work"}'

3) 或者完全不登录：profile 的 cordis.patch.yml 里配 apiToken

token 从哪来：已登录的 123 云盘桌面客户端日志 %APPDATA%\123pan\log\YYYY-MM-DD.log 里搜 Token:Bearer eyJ...。
也可以用 pan123_login_token 工具直接交给 agent。

loginToken 会先调一次 status 验证 token 有效，再 DPAPI 落盘；无效 token 直接报 401，不会生成坏会话。
用 apiToken 配置时 status 不会回写会话文件（配置只读）。

配置

在 profile 的 cordis.patch.yml 里可以覆盖（都有默认值）：

- id: dsh-123pan
config:
defaultRemoteDir: dsh-backup/my-project # 备份默认目标 maxFileBytes: 209715200 # 单文件上限（200MB） maxFiles: 5000 # 单次备份文件数上限
ignoreDirs: ['.git', 'node_modules'] # 自定义忽略目录
ignoreGlobs: ['.log', '.tmp'] # 自定义忽略文件名
storeDir: '' # 会话与清单目录（默认 $DSH_HOME/dsh-123pan） corePath: '' # 核心 exe 路径（默认包内） apiToken: '' # 直接用 API Key 当会话（免登录）

给智能体用的工具

| 工具 | 用途 |
| pan123_login | 手机号/邮箱 + 密码登录 |
| pan123_login_token | 用 API Key / Token 登录（免密码） |
| pan123_status | 登录状态、容量、token 到期时间 |
| pan123_logout | 清除本地会话 |
| pan123_list | 列目录 / 搜索 / 回收站 |
| pan123_mkdir | 新建目录 |
| pan123_upload | 上传单个文件 |
| pan123_download | 按文件 id 下载到本地 |
| pan123_direct_link | 取临时直链 |
| pan123_rename / pan123_move / pan123_delete | 改名 / 移动 / 删除 |
| pan123_backup_workspace | 工作区增量备份（支持 dryRun 预演） |
| pan123_backup_status | 查看历史备份记录 |
| pan123_scan_workspace | 只扫描不上传，检查忽略规则与大小限制 |

会话里可以直接说：

把当前工作区备份到 123 云盘的 dsh-backup/python，先预演一遍。

安全说明

* 密码不保存：只用于调用一次登录接口，换回 JWT 后即丢弃；传递方式是子进程环境变量而不是命令行参数（命令行会出现在进程列表里）。
* token 加密存储：DPAPI 密文（用户级），文件在 $DSH_HOME/dsh-123pan/session.dat；拷贝到别的用户/机器上无法解密。加解密由核心的 protect / unprotect 子命令完成，但落盘始终由 Node 侧执行——因为核心子进程可能处于受限令牌，写不了用户目录。
* 接口是客户端私有 API：不是公开开放平台接口，可能随客户端版本变化；仅建议个人账号低频自用，高频调用可能触发风控。
* HTTP 桥只监听本机：/api/dsh-123pan/ 仅接受回环地址 + POST，并校验 Origin / Sec-Fetch-Site，避免被网页跨站调用。

目录结构

dsh-123pan/
├── index.js Host 入口：注册工具 + HTTP 桥 ├── client.js 设置页 UI（跟随宿主主题） ├── lib/ │ ├── core.js 核心进程封装（NDJSON 结果 + 进度轮询） │ ├── api.js 相关 —— 见 native/core │ ├── backup.js 工作区扫描、增量判定、目录结构还原 │ ├── bridge.js 本机 HTTP 桥（门禁 + 错误整形） │ └── tools.js agent 工具定义 ├── native/core/ │ ├── main.cpp CLI 与 NDJSON 协议 │ ├── api.cpp 123 云盘 API（登录/列目录/上传/下载/回收站） │ ├── http.cpp HTTPS 客户端（OpenSSL + Windows 证书存储） │ ├── winutil.cpp UTF-8/UTF-16、DPAPI、路径工具 │ ├── json.hpp 极简 JSON（解析 + 序列化） │ └── build.sh 静态构建脚本 ├── locale/{zh,en}.json 插件标题与描述 └── icon.svg

核心 CLI 约定

native/core/123pan-core.exe 也可以独立使用（调试或脚本化）：

输出默认到 stdout；用 --ndjson <文件> 改为追加写文件 123pan-core.exe list --parent 0 --limit 10 123pan-core.exe upload --file D:\x.zip --parent 0 123pan-core.exe download --id 123 --out D:\x.zip 123pan-core.exe protect --text '{"token":"..."}' # 输出 DPAPI 密文（base64）

每行一个 JSON 对象：{"type":"progress",...} 与 {"type":"result","ok":...}。
令牌可以用 DSH_123PAN_TOKEN 环境变量传入，或用 login --account <账号> 配合 DSH_123PAN_PASSWORD。

--ndjson 与 download --out 是两个不同的参数：前者指定协议输出文件，后者是下载目标路径。早期版本两者同名 --out 会造成冲突，现已改名。

已知限制

仅 Windows（核心用 Winsock + DPAPI + Windows 证书存储）。
* 下载不支持断点续传（123 的 CDN 直链带签名与过期时间）。
* 备份不做压缩，按原文件上传（云盘侧可自行压缩/去重）。
* 秒传命中时不重新计算远端 MD5 校验（服务端按 etag 判定）。

许可

MIT