前言¶

在 DeepSeek Harness（dsh）裏讓模型分析 CSV、Parquet 等本地表，常見做法是再接一層 Python MCP 或外部服務。社區裏已有類似方案會依賴 mcp-server-duckdb 和單獨的安裝腳本。若你希望模型直接在工作區內用 SQL 讀文件、先看 schema 再查數，且不想維護 Python 運行時或聯網服務，需要一種掛在 Cordis 上的原生插件路徑。下面介紹維護者 alitrack 發佈的 dsh-duckdb。

這是什麼¶

dsh-duckdb 是 DeepSeek Harness 的 Cordis 原生插件：通過 ctx.tools 註冊兩個面向模型的工具，在本地調用系統上的 duckdb 可執行文件，對附件數據文件執行 SQL。插件本身不依賴 Python，也不發起網絡連接。分類上屬於工作流類插件；源碼與說明見 GitHub，目錄頁見 SkillHub。

核心功能¶

插件暴露兩個工具，用途如下。

通過 files 參數掛載文件時，按順序映射爲視圖名 f0、f1、……。支持的輸入格式包括：.csv、.tsv、.parquet、.json、.jsonl、.ndjson、.duckdb。

與生態中僅有的可比項目（通過 Python MCP 接入 DuckDB 的方案）相比，本插件以零額外依賴的方式直接運行本地 duckdb 二進制。README 註明：截至 2026-10-29，公開 DSH 插件倉庫中尚無其它原生 DuckDB 工具。

安裝與啓用¶

使用前需在 PATH 上安裝較新版本的 duckdb CLI；也可通過環境變量 DSH_DUCKDB_BIN 指定二進制路徑。

從插件目錄安裝：

dsh plugin --profile web add dsh-duckdb

或從 GitHub 添加：

dsh plugin --profile web add github:alitrack/dsh-duckdb

版本匹配。 插件聲明 peerDependencies 爲 @deepseek-ai/dsh-tools: ^0.0.1-rc.1，README 標明在 dsh 0.2.1-rc.2 上測試。若運行時因 peer 版本不匹配而拒絕加載，可固定 dsh 到測試版本，或使用 profile 側的 compatibility.json / dsh plugin allow-version 機制（README 對 CLI 提示與真實機制有補充說明）。

本地開發時可用 overlay 指向插件 index.js 的絕對路徑，無需 pnpm；示例見倉庫 README 中的 local-overlay.yml。

典型用法¶

對話中可以先用 schema 再看數據，再用 query 聚合。README 中的示例如下（路徑需爲會話工作區內的絕對路徑）：

You: Look at /workspace/sales.csv and total the amount by city.

Agent: [duckdb_schema target=/workspace/sales.csv]
       columns: city VARCHAR, amount BIGINT
       approx rows: 3

       [duckdb_query sql="SELECT city, sum(amount) AS total FROM f0 GROUP BY city ORDER BY city"
        files=["/workspace/sales.csv"]]
       BJ | 300
       HZ | 100
       SH | 200

duckdb_query 參數摘要

duckdb_schema 參數摘要

安全模型與運行注意¶

一切在本地執行；插件不持有憑據、不連網。模型提交的 SQL 視爲不可信輸入，插件實現了多層約束：

1. 工作區限制：路徑必須爲絕對路徑且解析後會話工作區根目錄內；拒絕 ..、指向外部的符號鏈接、根外絕對路徑、目錄與缺失文件。
2. 默認只讀：默認僅接受 SELECT / WITH / VALUES / FROM / DESCRIBE / SHOW / SUMMARIZE / EXPLAIN / PRAGMA；寫操作需顯式 read_only: false。
3. 始終禁止的語句：即便開啓寫模式，COPY、ATTACH、DETACH、INSTALL、LOAD、SET 等仍可觸及進程外資源的語句仍被攔截。
4. 行數上限與單語句：結果在 max_rows 處截斷並返回真實 row_count；每次調用只允許一條語句；單次調用超時 30 秒。

插件以當前 dsh 進程的用戶權限運行 SQL 與文件訪問。安裝前建議閱讀倉庫源碼與 MIT 許可證，確認符合你的安全策略。

適用場景¶

• 智能體需要在不離開工作區的前提下，對 CSV / Parquet / JSON 等做聚合、過濾、JOIN。
• 希望零 Python、零外部 MCP 服務，僅依賴本機 duckdb CLI。
• 需要先 duckdb_schema 探表，再 duckdb_query 寫 SQL 的兩步工作流。

不適合依賴網絡數倉、或需要在插件內執行任意 DuckDB 擴展安裝（INSTALL / LOAD 被禁止）的場景。

結尾¶

dsh-duckdb 把 DuckDB 以 Cordis 工具形式接進 dsh：兩條工具、本地二進制、工作區與只讀策略內置。若你在 DSH 生態裏做本地數據分析工作流，可從目錄頁或 GitHub 安裝並在對話中直接掛載文件路徑使用。

• 目錄頁：https://www.skillhub.cn/plugins/alitrack/dsh-duckdb
• 倉庫：https://github.com/alitrack/dsh-duckdb

DSH 社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件由社區維護者 alitrack 發佈。