OpenList 文件同步bg8lng/dsh-openlist-sync

dsh-openlist-sync

给 DeepSeek Harness (DSH) 的 OpenList 文件同步插件：把各对话中 agent 交付的文件自动存入 OpenList 指定目录，并让 DSH 对该目录拥有完整的读写能力（列出 / 读取 / 写入 / 删除 / 重命名 / 移动，全部走 OpenList API）。

纯 Node ESM 实现，零第三方运行时依赖（只用内置模块 + fetch），全平台可用；兼容 Alist / Alist 系 / OpenList v3/v4 的 /api/fs/ 接口。

功能

1) 交付文件自动同步（核心）

- 监听 DSH 每个会话里的工具执行结果，一旦产生交付文件就自动上传到 OpenList 的 targetDir；
- 默认覆盖两类来源（对应界面上的「交付文件」）：
- 聊天交付：dsh_im_return_file 返回给用户的文件 / 图片；
- 工具产物：write / edit / str_replace_editor 写出的文件；
- 目录组织：flat（平铺）/ date（默认，targetDir/2026-09-03/文件名）/ date-session（按日期+会话分组）/ workspace（按工作区）/ workspace-date（工作区+日期）
以及 分类布局（v0.3.0，用于 DSH交互 规范）：category-workspace-date → targetDir/{分类}/{工作区名}/{YYYY-MM-DD}/文件名（分类=README 主题分类；工作区名取自会话 cwd，未命中用 defaultCategory）；
- 智能去重：同路径同内容未变 => 跳过；远端已有同名（默认不覆盖）=> 跳过并提示；可选 dedupeByContent 按 sha256 全局去重；
- 失败自动记录到 state.json，可用 openlist_sync_retry 重试；同步状态随时用 openlist_sync_status 查看；
- 上传全程串行队列，不阻塞 agent 的工具调用（fire-and-forget + 队列）。

2) 目录全读写工具集（DSH 可完全读写 targetDir）

| 工具 | 作用 |
|---|---|
| openlist_health | 自检：配置 + 连通性 + targetDir 可达性与写权限 |
| openlist_config | 查看生效配置（密码/令牌掩码） |
| openlist_list | 列出远端目录（表格渲染） |
| openlist_stat | 查看单个文件/目录元信息 |
| openlist_read_file | 读：把远端文件内容读回对话（UTF-8 文本全文 / 二进制 base64 摘要） |
| openlist_write_file | 写：上传本地文件（支持指定远端路径或按 layout 自动归位） |
| openlist_write_text | 写：文本直接写成远端文件 |
| openlist_mkdir | 递归创建目录 |
| openlist_remove | 删除（目录递归删除；拒绝删除 targetDir 根；破坏性操作会先提示） |
| openlist_rename | 重命名 |
| openlist_move | 移动（跨目录自动建目录） |
| openlist_sync_status / openlist_sync_retry | 自动同步状态 / 重试失败 |

默认 restrictToRoot: true：目录工具只允许在 targetDir 内操作，防止越权/误删；确需全盘访问可关闭。

安装

1) 本地 tarball（推荐本仓库交付物）
dsh plugin --profile web add ./dsh-openlist-sync-0.3.1.tgz

2) 或 npm 发布后
dsh plugin --profile web add dsh-openlist-sync

3) 或从 GitHub
dsh plugin --profile web add github:你的账号/dsh-openlist-sync#

装完重启 dsh web。插件自带空配置，未配置时不会弄崩启动；任何 openlist_ 工具会返回配置提示。

⚠️ 升级必须走 dsh plugin add ，绝不要 cp 覆盖 node_modules/dsh-openlist-sync。
Profile 目录由 pnpm 管理：package.json / pnpm-lock.yaml 里记录的是「装的是哪个 tgz」。
手工 cp 只改了磁盘上的文件、没改依赖清单，pnpm 一旦重新物化（dsh 启动、pnpm install 等）
就会把代码静默回退到清单里那个旧版本——表现为「仓库明明已修，运行实例却还有旧 bug」。
用 openlist_health / openlist_config 查看 pluginVersion，即可确认运行实例到底加载的是哪个版本。

配置

在 $DSH_HOME/profiles/web/cordis.patch.yml（即 ~/.dsh/profiles/web/cordis.patch.yml）中追加/覆盖：

- id: tool-openlist-sync
config:
baseUrl: "https://your-openlist.example.com"   # OpenList 访问地址；挂在子路径则带子路径
username: admin
password: 你的密码                      # 建议改用环境变量 DSH_OPENLIST_PASSWORD，见下
token: "站点令牌"                    # 二选一：OpenList 后台 设置→其他→站点令牌，优先于账号密码
targetDir: "/DSH交付"                  # 交付文件自动存放目录（自动创建）
layout: "category-workspace-date"       # flat | date（默认）| date-session | workspace | workspace-date | category-*
分类布局的工作区→分类映射（layout 为 category-* 时生效；未命中走 defaultCategory）
workspaceCategories:
DoveSky: 运维部署
"BG8LNG-SEO": 运维部署
renwu: 运维部署
"DSH插件开发": 插件开发
cs75: 项目文档
爱雅娱乐: 爱雅娱乐
考试生成: 课件
头发保卫战: 头发保卫战
defaultCategory: "待整理"               # 未命中映射时兜底分类
autoSync: true                          # 总开关
syncChatDeliveries: true                # dsh_im_return_file 聊天交付
syncProducedFiles: true                 # write/edit/str_replace_editor 产物
overwrite: false                        # 远端同名是否覆盖
restrictToRoot: true                    # 目录工具是否锁定在 targetDir 内

环境变量（优先级最高，避免明文密码进 YAML）

| 变量 | 说明 |
|---|---|
| DSH_OPENLIST_BASE_URL | OpenList 地址 |
| DSH_OPENLIST_USERNAME | 用户名 |
| DSH_OPENLIST_PASSWORD | 密码（推荐） |
| DSH_OPENLIST_TOKEN | 站点令牌（替代账号密码） |
| DSH_OPENLIST_TARGET_DIR | 目标目录 |

完整配置项

| 配置 | 默认 | 说明 |
|---|---|---|
| baseUrl | 空 | OpenList 根地址（含子路径则到子路径） |
| username / password | 空 | 账号密码登录 |
| token | 空 | 站点令牌（优先） |
| targetDir | /DSH交付 | 交付目录 |
| layout | date | flat / date / date-session / workspace / workspace-date / category-date / category-workspace / category-workspace-date |
| workspaceCategories | {} | 工作区名 → 分类名（category- 布局生效） |
| defaultCategory | 待整理 | 工作区未命中 workspaceCategories 时的兜底分类 |
| autoSync | true | 自动同步总开关 |
| syncChatDeliveries | true | 聊天交付文件（dsh_im_return_file） |
| syncProducedFiles | true | write/edit/str_replace_editor 产物 |
| overwrite | false | 同名覆盖 |
| dedupeByContent | false | 按 sha256 内容全局去重 |
| includes | [] | 文件名白名单（/?），空=不限 |
| excludes | [] | 文件名黑名单 |
| maxBytes | 314572800 | 单文件上限（默认 300MB） |
| restrictToRoot | true | 目录工具锁在 targetDir |
| dataDir | ~/.dsh/dsh-openlist-sync | state.json 存放处 |
| timeoutMs | 30000 | API 超时 |
| producedTools | 见下 | 工具名→路径参数映射（扩展） |

默认 producedTools：{ write: file_path, edit: file_path, str_replace_editor: path, dsh_im_return_file: path }。其它插件产出的文件可在配置里追加，例如：

producedTools:
excel_task: outPath        # dsh-excel-chat 任务输出也自动同步
run_code: outputPath       # 假想示例

Web 设置面板（DSH 设置 → OpenList 同步）

0.2.0 起插件注册进 DSH 设置面板（设置 → OpenList 同步 (dsh-openlist-sync)），无需手写 YAML 即可配置：OpenList 地址(baseUrl)、令牌或账号密码、挂载目录(targetDir)、存放规则(layout/overwrite/自动同步开关)、目录规则(restrictToRoot/包含排除/单文件上限)，并带「测试连接」。保存后实时生效（下次工具调用即用新配置）；秘密字段（密码/令牌）按 secret 存储不会出现在导出/诊断。

原理与边界

- 自动同步钩子：订阅 DSH 工具服务的事件 tools/result，在工具成功执行后按 producedTools 映射取出文件路径入队上传。只跟踪顶层工具调用（与界面「交付文件」口径一致）；run_code 内部的子调用不重复触发。
- 鉴权：优先 token（站点令牌直接放 Authorization 请求头）；否则 POST /api/auth/login 换 token，401 自动重登一次。
- 上传：PUT /api/fs/put，请求头 File-Path（URL 编码的全路径）+ 原始字节流 + X-File-Md5；个别环境不允许 raw PUT 时自动回退 multipart /api/fs/form。
- 读取：GET /d/{path} 直连下载，403 自动回退 /p，再回退 stat 的 raw_url（对开了 sign_all 的站点也可用）。
- 去重日志：dataDir/state.json 记录 {本地路径→sha256/size/mtime/远端} 与失败列表；多会话共享一份，重启不重复上传。
- 相对路径解析：自动同步按「工具参数原样 → 会话工作目录」尽力解析；DSH 工具通常传绝对路径，最稳。
- 大文件读取为内存 Buffer（300MB 上限内可控）；自动同步/上传失败不影响原会话，只记录并由 openlist_sync_retry 重试。

卸载

dsh plugin --profile web remove dsh-openlist-sync
并手动删除 ~/.dsh/profiles/web/cordis.patch.yml 里 tool-openlist-sync 行与 ~/.dsh/dsh-openlist-sync 状态目录

更新记录

v0.3.1（2026-09-11）修复“修复未真正上线”+ 上传成功不再可能被改判为失败

现象：手动 openlist_write_file（尤其带 overwrite: true）向会话返回裸 Error: this is not a function，但同一时刻自动同步已把文件真实上传成功（远端 size 与本地一致）。

根因（两层，缺一不可）：

1. 代码层：DSH 运行时（cordis）LoggerService 的级别方法是原型方法，内部实现为 return this()type（logger 实例本身可调用）。旧 SyncEngine._log 先把 ctx.logger[level] 取出存成局部变量再调用，this 丢失 → TypeError: this is not a function。该日志调用位于上传成功收尾处，于是「文件已落盘却被报失败」。
该问题在 v0.2.7 已修，但——
2. 部署层（本次复发的真正原因）：v0.2.6/v0.2.7/v0.3.0 的修复只被 cp 进 ~/.dsh/profiles/web/node_modules/dsh-openlist-sync，而 profile 的 package.json / pnpm-lock.yaml 始终指向 dsh-openlist-sync-0.2.5.tgz。pnpm 重新物化时按依赖清单还原，把 6 个源文件静默回退到 0.2.5。运行实例因此长期停留在 0.2.5（含旧 _log），bug 复现。
（旁证：被 cp 改过内容的 6 个文件 mtime 被 pnpm 重写，而内容与 0.2.5 完全相同的 openlist-client.js / web.js 保留了 cp 时间戳。）

修复：

- 代码层加固（0.2.7 已修的点保持不变，另补结构性防线）：
- SyncEngine._record() 全程 try/catch —— 遥测记账不可能失败，杜绝「成功被改判为失败」；
- 上传成功后的 state.record / clearFailure 收尾包进独立 try/catch，状态落盘异常不影响上传结论；
- openlist_write_file / openlist_write_text 把 recompute()、配置校验、路径守卫一并纳入结构化兜底：写入类工具永不以裸错误形式抛出，未配置时也返回 status: failed + reason。
- 部署层加固（防复发）：
- openlist_health / openlist_config / openlist_write_file 结果中回显 pluginVersion，一眼识别运行实例与仓库的版本漂移；
- README 明确「升级必须 dsh plugin add ，不得 cp 覆盖 node_modules」；
- 新增 scripts/install-local.sh：npm pack + dsh plugin add 一键正确安装。
- 测试：新增 3 个回归用例并通过 ——
① openlist_write_file + overwrite=true + cordis 形态日志器 → 必须 status: uploaded、不 reject、不残留失败记录；
② 写入类工具未配置时返回结构化失败而非裸错误；
③ health/config 回显 pluginVersion。
总计 13/13 通过。

验证：用同一脚本分别加载运行实例（0.2.5）与修复版（0.3.1）——0.2.5 threw: true, error: "this is not a function"；0.3.1 threw: false, status: "uploaded"。

v0.3.0（2026-09-09）存储规范升级：分类 / 工作区 / 日期 布局

- 新增分类布局 category-workspace-date（= targetDir/{分类}/{工作区名}/{YYYY-MM-DD}/文件名）与 category-workspace、category-date；
配合 DSH交互 目录规范：交付按 README 主题分类 → 工作区命名文件夹 → 日期（会话）三层存放；
- 新增配置 workspaceCategories（工作区名 → 分类名映射）与 defaultCategory（默认 待整理）；
- openlist_write_file 新增可选参数 category，可显式指定分类，否则按工作区自动映射；
- 路径拼接改为按布局分段 join（此前因单段清洗会把 ws/date 拼成 wsdate），保证 分类/工作区/日期 真实三层目录；
- openlist_config 显示 defaultCategory / workspaceCategories；
- 强制交付约定：会话产生的交付文件须经 openlist_write_file/自动同步落到该规范目录，会话末尾回执远端地址。

v0.2.7（2026-09-08）真正根因修复：日志调用丢 this 导致上传假失败

- 根因（经运行日志堆栈定位）：DSH 运行时（cordis）的 LoggerService 级别方法是原型方法，内部依赖 this()（logger 实例本身可调用）。旧 SyncEngine._log 先把 ctx.logger[level] 取出存成局部变量再调用，导致 this 丢失，抛出 TypeError: this is not a function。该日志调用位于上传成功收尾处，于是每次上传“文件已落盘却被报失败”，并污染失败清单（0.2.6 已加收尾兜底与去重，但未触及此根因）。
- 修复：_log 改为内联调用（logger.warn?.(...) 保留 this），任何日志异常只回退 console，绝不影响上传业务；增加 cordis 形态日志器的回归测试。
- 保留 0.2.6 的全部健壮性改进（收尾兜底判定 recovered、并发/重复派发去重、state 落盘尽力而为、失败带堆栈、工具不抛裸错误）。

v0.2.6（2026-09-08）修复：上传成功却报“this is not a function”假失败

- 根因：个别运行环境在文件已成功写入远端、进入状态收尾阶段时会抛出一个运行时错误；旧实现一律按“上传失败”记录并上报，导致 openlist_write_file / 自动同步明明把文件传上了 OpenList，会话却收到 Error: this is not a function，失败清单也被污染。
- 修复：
- 上传收尾兜底：出错后先核对远端是否已存在同路径文件且大小一致 —— 一致即判定“已上传成功”并自动清理失败记录，不再产生假失败；
- 同文件并发去重：同一逻辑上传（插件重复加载 / 工具结果重复派发）并发出现时只真正上传一次，第二次复用结果，避免“远端已存在”类误报；
- tools/result 事件 1.2s 窗口去重，杜绝同一产物被重复派发上传；
- 状态落盘（state.json）改为尽力而为：多实例并发写 / 临时文件冲突不再向上传主流程抛错；
- 失败原因携带堆栈片段（e.stack 前 6 行），便于下次定位；
- openlist_write_file / openlist_sync_retry 内部异常统一转结构化结果返回，不再向会话抛裸错误。
- 测试：新增 2 个回归用例 —— “文件已落盘但接口报错 → 判定 recovered 成功、不写失败记录”“同一文件并发上传只落盘一份”。

开发与测试

npm test                # node --test，含 mock OpenList 服务器的离线测试
npm pack                # 打 tgz 交付包

测试覆盖：路径规范化 / 工具注册 / health / list / 读写文本 / 上传本地文件 / dsh_im_return_file 自动同步与去重 / 目录守卫（越界与根目录保护）/ mkdir-rename-move-read-remove 闭环。

License

MIT