dsh-openlist-sync
OpenList 文件同步插件（含设置面板）：自动把 DSH 对话交付文件上传到 OpenList 挂载目录，并提供该目录的完整读写工具集。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:bg8lng/dsh-openlist-sync#286f920f3eb4cd82062ac996729ada896f4e2819Openlist Sync 以 dsh-openlist-sync 发布，当前版本为 0.3.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
给 DeepSeek Harness (DSH) 的 OpenList 文件同步插件：把各对话中 agent 交付的文件自动存入 OpenList 指定目录，并让 DSH 对该目录拥有完整的读写能力（列出 / 读取 / 写入 / 删除 / 重命名 / 移动，全部走 OpenList API）。
纯 Node ESM 实现，零第三方运行时依赖（只用内置模块 + fetch），全平台可用；兼容 Alist / Alist 系 / OpenList v3/v4 的 /api/fs/* 接口。
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 查看；| 工具 | 作用 |
|---|---|
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 内
| 变量 | 说明 |
|---|---|
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：{ 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 # 假想示例
0.2.0 起插件注册进 DSH 设置面板（设置 → OpenList 同步 (dsh-openlist-sync)），无需手写 YAML 即可配置：OpenList 地址(baseUrl)、令牌或账号密码、挂载目录(targetDir)、存放规则(layout/overwrite/自动同步开关)、目录规则(restrictToRoot/包含排除/单文件上限)，并带「测试连接」。保存后实时生效（下次工具调用即用新配置）；秘密字段（密码/令牌）按 secret 存储不会出现在导出/诊断。
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/远端} 与失败列表；多会话共享一份，重启不重复上传。openlist_sync_retry 重试。dsh plugin --profile web remove dsh-openlist-sync
# 并手动删除 ~/.dsh/profiles/web/cordis.patch.yml 里 tool-openlist-sync 行与 ~/.dsh/dsh-openlist-sync 状态目录
现象：手动 openlist_write_file（尤其带 overwrite: true）向会话返回裸 Error: this is not a function，但同一时刻自动同步已把文件真实上传成功（远端 size 与本地一致）。
根因（两层，缺一不可）：
LoggerService 的级别方法是原型方法，内部实现为 return this()[type](...args)（logger 实例本身可调用）。旧 SyncEngine._log 先把 ctx.logger[level] 取出存成局部变量再调用，this 丢失 → TypeError: this is not a function。该日志调用位于上传成功收尾处，于是「文件已落盘却被报失败」。
该问题在 v0.2.7 已修，但——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 时间戳。）修复：
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，一眼识别运行实例与仓库的版本漂移；dsh plugin add <新 tgz>，不得 cp 覆盖 node_modules」；scripts/install-local.sh：npm pack + dsh plugin add 一键正确安装。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"。
category-workspace-date（= targetDir/{分类}/{工作区名}/{YYYY-MM-DD}/文件名）与 category-workspace、category-date；
配合 DSH交互 目录规范：交付按 README 主题分类 → 工作区命名文件夹 → 日期（会话）三层存放；workspaceCategories（工作区名 → 分类名映射）与 defaultCategory（默认 待整理）；openlist_write_file 新增可选参数 category，可显式指定分类，否则按工作区自动映射；ws/date 拼成 wsdate），保证 分类/工作区/日期 真实三层目录；openlist_config 显示 defaultCategory / workspaceCategories；openlist_write_file/自动同步落到该规范目录，会话末尾回执远端地址。LoggerService 级别方法是原型方法，内部依赖 this()（logger 实例本身可调用）。旧 SyncEngine._log 先把 ctx.logger[level] 取出存成局部变量再调用，导致 this 丢失，抛出 TypeError: this is not a function。该日志调用位于上传成功收尾处，于是每次上传“文件已落盘却被报失败”，并污染失败清单（0.2.6 已加收尾兜底与去重，但未触及此根因）。_log 改为内联调用（logger.warn?.(...) 保留 this），任何日志异常只回退 console，绝不影响上传业务；增加 cordis 形态日志器的回归测试。openlist_write_file / 自动同步明明把文件传上了 OpenList，会话却收到 Error: this is not a function，失败清单也被污染。tools/result 事件 1.2s 窗口去重，杜绝同一产物被重复派发上传；e.stack 前 6 行），便于下次定位；openlist_write_file / openlist_sync_retry 内部异常统一转结构化结果返回，不再向会话抛裸错误。npm test # node --test，含 mock OpenList 服务器的离线测试
npm pack # 打 tgz 交付包
测试覆盖：路径规范化 / 工具注册 / health / list / 读写文本 / 上传本地文件 / dsh_im_return_file 自动同步与去重 / 目录守卫（越界与根目录保护）/ mkdir-rename-move-read-remove 闭环。
MIT
producedTools | 见下 | 工具名→路径参数映射（扩展） |