READMESource: main@a731fec3
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（按日期+会话分组）； - 智能去重：同路径同内容未变 => 跳过；远端已有同名（默认不覆盖）=> 跳过并提示；可选
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.1.0.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_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: "date" # flat | date（默认）| date-session
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 |
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.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
No comments yet. Be the first to write one.