前言¶

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/* 接口。