前言¶

DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”，通過加載不同的能力模塊來擴展智能體的功能。Cloudflare D1 是基於 SQLite 的無服務器數據庫，它通過 REST API 訪問，沒有傳統的 TCP Socket。現有的 dsh-sql 插件無法直接連接 D1。dsh-d1 專爲解決這一問題而生，它直接通過 D1 的 HTTP API 與數據庫交互，爲 Harness Agent 提供了一組獨立的工具。

插件介紹¶

dsh-d1 是 Cloudflare D1 的管理工具集，歸屬於“聯網工具”類別，由開發者 cndn 維護。該插件以只讀模式爲默認策略，旨在讓智能體在安全的前提下查詢 D1 數據庫，僅在明確配置並獲取審批後才能執行寫入操作。它沒有運行時依賴，安裝後即可使用。

核心功能¶

插件註冊了六個工具，涵蓋了從數據庫探測、只讀查詢、表結構查看到統計信息獲取的全過程。

• d1_list：列出已配置的數據庫，並探測每個數據庫的連通性。
• d1_query：執行只讀語句。支持 SELECT、VALUES、WITH、PRAGMA（僅限 introspection）和 EXPLAIN。支持參數綁定，結果集受 maxRows 限制。
• d1_exec：執行寫入或 DDL 語句。在默認配置下被拒絕，需顯式開啓寫入權限並通過交互式審批。
• d1_schema：列出用戶表，或通過 PRAGMA table_info 描述指定表的列結構。
• d1_stats：獲取表數量、每錶行數（批處理）以及數據庫大小。
• d1_health：探測所有數據庫並打印安全配置及任何配置錯誤。

安裝與配置¶

插件通過 npm 安裝。由於 DSH 的 profile 目錄通常作爲 pnpm workspace 根目錄，安裝時需要使用 -w 參數。

dsh plugin --profile web add -w dsh-d1

安裝後，插件會自動在 profile 中插入配置行，但 API Token 不會寫入其中。你需要通過 cordis.patch.yml 覆蓋配置，指定 Cloudflare 的 accountId 以及要連接的 databases 列表。

- id: d1
  name: 'dsh-d1'
  config:
    accountId: 'your-32-hex-cloudflare-account-id'
    databases:
      - name: prod
        databaseId: 00000000-0000-0000-0000-000000000000
      - name: analytics
        databaseId: 11111111-1111-1111-1111-111111111111
    maxRows: 1000
    readOnly: true
    writeApproval: true
    queryTimeoutMs: 60000
    execTimeoutMs: 120000

安全與限制¶

dsh-d1 在安全上採取了雙層防護。

首先，API Token 環境隔離。Cloudflare 的 API Token 必須通過環境變量傳入，插件在運行時讀取，絕不存儲在配置文件或日誌中。支持全局令牌 (CLOUDFLARE_API_TOKEN) 或針對特定數據庫的令牌 (DSH_D1_TOKEN_<NAME>)。

其次，默認只讀與審批機制。默認情況下 readOnly: true，d1_exec 會被拒絕。即使設置爲 false，默認的 writeApproval: true 也會將所有寫入操作推送到 DSH 的審批服務，要求交互確認。

此外，d1_query 使用了詞法防護。在剝離註釋和字符串後，只允許執行特定的只讀語句。這防止了意外寫入，且不依賴關鍵字黑名單。錯誤信息會自動脫敏，移除 Token、請求頭和路徑中的敏感信息。