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"

1. 编辑 %USERPROFILE%.dsh\profiles\\package.json，两处都要加：

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

1. 完全退出 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:/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 当会话（免登录）

给 agent 用的工具

工具 · 用途 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）