前言¶

DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”。現有的 DSH 工具生態主要處理“文本形態”的數據，例如 CSV 或 JSON。當 Agent 會話中出現 .db 或 .sqlite 文件（例如爬蟲結果導出、本地應用數據快照）時，直接調用 bash 命令行往往不夠靈活。

dsh-tool-sqlite 插件補齊了這一塊，它提供了零依賴的數據庫處理能力，允許 Agent 在工作區內直接操作 SQLite 文件。

插件簡介¶

插件名稱：dsh-tool-sqlite
維護者：WODE25500
許可證：MIT

該插件直接使用 Node.js 內置的 node:sqlite 模塊，不引入任何第三方數據庫庫。它主要解決三個問題：列出工作區內的數據庫文件、查看錶結構、以及執行只讀 SQL 查詢。

安裝與啓用¶

在 DSH 的配置文件（如 cordis.yml 或 dsh.profile）中引入即可。啓動後，控制台出現 [tool-sqlite] 相關日誌即表示加載成功。

plugins:
  - id: tool-sqlite
    name: 'dsh-tool-sqlite'

核心功能¶

插件提供了以下 5 個核心工具：

1. sqlite_list
   掃描工作區（限制 2 層深度，跳過 node_modules 與隱藏目錄），找出所有 .db、.sqlite、.sqlite3、.db3 文件。

2. sqlite_tables
   列出指定數據庫內的所有表與視圖。

3. sqlite_schema
   查看指定表的列結構，包含列類型、NOT NULL 約束、默認值、主鍵信息。

4. sqlite_summary
   生成單表的列統計摘要，包含總行數、每列類型、distinct 值、min/max/avg。該工具旨在減少 token 消耗，避免全表掃描。

5. sqlite_query
   執行只讀 SQL 查詢，返回 { columns, rows } JSON 格式結果。

典型用法¶

以下是插件提供的可復現示例：

sqlite_list → data/app.db

sqlite_tables db: data/app.db → users, orders

sqlite_schema db: data/app.db table: users → id INTEGER PK(1) / name TEXT NOT NULL …

sqlite_query db: data/app.db sql: "SELECT name, age FROM users WHERE age >= ?" params: [30]

安全模型與限制¶

插件內置了嚴格的安全與性能限制，以確保運行環境的穩定。

• 只讀硬約束：數據庫始終以 readOnly: true 打開。任何寫操作（INSERT/UPDATE/DELETE/CREATE/DROP/ATTACH）都會被 SQLite 拒絕（attempt to write a readonly database）。
• 語句白名單：僅放行以 SELECT / WITH / PRAGMA / EXPLAIN / VALUES 開頭的單條語句。只走 prepare 執行，不走多語句 exec。
• 路徑邊界：所有 db 參數解析後必須位於工作區內，防止路徑穿越攻擊（../ 與絕對路徑越界直接報錯）。
• 輸出預算：結果默認顯示 100 行，硬上限爲 500 行。超限時明確標註截斷，防止輸出膨脹。
• 超時兜底：查詢操作限制 5000ms，其他操作限制 3000ms。

開發與依賴¶

• Node.js 版本：要求 ^22.19.0 || >=24.0.0（node:sqlite 需要 Node 22.5+）。
• Peer Dependencies：
  • @deepseek-ai/dsh-tools
  • @deepseek-ai/cordis
• 開發命令：使用 npm run check 進行類型檢查、測試和構建。

結語¶

dsh-tool-sqlite 通過直接利用 Node 內置模塊，爲 DSH 插件生態提供了處理本地數據庫文件的能力。開發者無需配置數據庫環境，即可在工作區中對 .db 文件進行結構化探索。更多細節可參考 GitHub 倉庫。