前言¶

DeepSeek Harness (DSH) 是一个面向智能体开发的工具平台。在实际开发过程中，工具执行产生的交付文件（如代码、文档）通常散落在对话上下文中，难以持久化或统一管理。dsh-openlist-sync 是 DeepSeek Harness (DSH) 的 OpenList 文件同步插件，负责把各对话中 Agent 交付的文件自动上传到 OpenList 指定目录，并赋予 DSH 对该目录的完整读写能力。

功能特性¶

该插件基于纯 Node ESM 实现，零第三方运行时依赖，兼容 Alist / Alist 系 / OpenList v3/v4 的 /api/fs/* 接口。

1. 交付文件自动同步
   插件监听 DSH 每个会话里的工具执行结果。一旦产生交付文件，就会自动上传到 OpenList 的 targetDir。它支持两类来源：dsh_im_return_file 返回的聊天交付文件，以及 write / edit / str_replace_editor 等工具产生的产物。

2. 目录全读写工具集
   在配置完成后，DSH 拥有对 targetDir 的完整操作权限。提供以下工具：
   * openlist_health：自检配置与连通性。
   * openlist_list / openlist_stat：列出目录或查看文件元信息。
   * openlist_read_file / openlist_write_file / openlist_write_text：读取或写入文件。
   * openlist_mkdir / openlist_remove / openlist_rename / openlist_move：创建、删除、重命名、移动文件。

3. Web 设置面板
   插件注册了 Web 设置面板，可在 DSH 设置中直接配置 OpenList 地址、认证信息、目标目录和布局规则，无需手动编辑 YAML 文件。

安装与启用¶

使用官方提供的 tarball 包进行安装。

# 安装插件
dsh plugin --profile web add ./dsh-openlist-sync-0.3.1.tgz

安装完成后，需要重启 dsh web 才能使插件生效。

配置说明¶

配置文件位于 $DSH_HOME/profiles/web/cordis.patch.yml（即 ~/.dsh/profiles/web/cordis.patch.yml）。在配置文件中追加或覆盖 tool-openlist-sync 配置项。

- id: tool-openlist-sync
  config:
    baseUrl: "https://your-openlist.example.com"   # OpenList 访问地址
    username: admin
    password: 你的密码
    targetDir: "/DSH交付"                  # 交付文件自动存放目录
    autoSync: true                          # 总开关
    syncChatDeliveries: true                # 聊天交付文件
    syncProducedFiles: true                 # 工具产物
    overwrite: false                        # 远端同名是否覆盖
    restrictToRoot: true                    # 目录工具是否锁定在 targetDir 内

也可以通过 Web 设置面板进行配置，在设置中找到 OpenList 同步选项，输入地址、认证信息并保存。

使用方式¶

1. 配置完成后，DSH 会在工具执行成功后自动将交付文件上传到 OpenList。
2. 在 DSH 中直接调用 openlist_* 工具，即可在配置的 targetDir 内进行读写操作。

注意事项¶

1. 目录隔离：默认 restrictToRoot: true，目录工具只允许在 targetDir 内操作，防止越权。
2. 升级方式：升级插件必须走 dsh plugin add <新 tgz> 命令。Profile 目录由 pnpm 管理，绝不要使用 cp 覆盖 node_modules，否则 pnpm 会将依赖清单回退到旧版本。
3. 兼容性：兼容 Alist / Alist 系 / OpenList v3/v4 的 /api/fs/* 接口。