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#<commit>

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

⚠️ 升级必须走 dsh plugin add <新 tgz>，绝不要 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](https://github.com/bg8lng/dsh-openlist-sync/blob/HEAD/...args)（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 <新 tgz>，不得 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