前言¶
在 DeepSeek Harness（DSH）裏做智能體開發，數據分析往往是繞不開的一環：業務同學想直接問「最近一個月哪個地區銷售額下滑最多」，工程師卻要反覆切到 BI 工具、手寫 SQL、再把結果貼回對話裏。DSH 的核心理念是「一切皆插件」——社區裏已經有人把「連庫查數」這件事做成了獨立插件。
今天要介紹的是 dsh-data-agent（倉庫 omdsh-dev/dsh-data-agent）。它在 GitHub 上已有 164 個 star、12 個 fork，在 SkillHub 插件庫 中歸類爲「聯網工具」。插件由社區組織 omdsh-dev 維護，採用 MIT 許可證；需要說明的是，SkillHub 與 dshfind 等目錄均爲社區運營的 DSH 插件索引，並非 DeepSeek 或幻方官方應用商店。
這是什麼¶
一句話概括：dsh-data-agent 是 DSH 的數據分析插件，把數據庫連接、SQL 執行與結果解讀串進同一次對話流程。
連接數據庫後，你可以直接用自然語言描述業務問題。DSH 會查看庫表結構、編寫並執行 SQL，再根據真實返回結果繼續調整查詢或深入分析，最終給出可讀的數據結論與商業洞察。插件同時支持 Web UI 與 dsh-tui，無需修改 DSH 源碼；npm 包名爲 @yejiming/dsh-data-agent。
核心功能與亮點¶
根據 GitHub README 與倉庫說明，已覈實的主要能力如下：
- 對話式數據分析：用自然語言提問，DSH 會拆解分析步驟、查詢真實數據並整理結論；支持在同一上下文中連續追問，逐步縮小範圍或比較維度。
- 自動 SQL 閉環：不是隻生成一段未經驗證的 SQL，而是根據表結構寫查詢、執行、結合報錯或結果繼續迭代，直到拿到可用答案。
- AI 驅動的數據治理（Catalog）：可用當前會話配置的模型掃描數據庫，爲表和字段生成業務含義候選；所有 AI 建議需人工確認，也可手工補充術語與指標定義。後續分析會通過
catalog-search、catalog-get、metric-get等工具讀取已確認的口徑。 - HTML 分析報告（render-analysis）：Agent 在判斷需要可視化時，可一次調用生成含 metric、折線、柱狀、餅圖、散點、表格等視圖的綜合報告，並保存到工作目錄
analysis-reports/下的離線 HTML 文件；Web UI 支持內聯預覽與「查看分析」彈窗。 - 多界面共享同一套工具協議：Web UI（推薦配合 dsh-web-ui）與 dsh-tui（推薦配合 dsh-TUI）共用數據庫服務與八工具協議；數據模式會保留
sql-query、sql-write、sql-cmd、render-analysis及 Catalog 相關工具，而不會混入describe_image、ssh_*等無關能力。 - 常見業務數據庫支持：MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris、SQL Server 等，覆蓋業務庫、分析庫、本地文件與數倉場景。
- 只讀保護與密碼處理：支持只讀模式與數據庫只讀賬號；TUI 中臨時密碼會被隱藏，且不會作爲表單草稿恢復。
Web UI 還提供「數據庫工作臺」：在輸入框右上角的數據庫按鈕中，可在同一彈窗裏完成連接配置、瀏覽庫表、數據治理與臨時 SQL 執行。
安裝與啓用¶
以下命令來自倉庫 README，安裝到 Web profile（推薦 npm 方式）：
dsh plugin --profile web add @yejiming/dsh-data-agent
也可從 GitHub 直接安裝：
dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
若主要在終端使用 dsh-tui，可安裝到對應 profile：
dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
插件會自動安裝「數據模式」預設，並在 profile 啓動時預加載相關數據庫工具。倉庫中 lib/ 已提交，通過 npm 或 GitHub 安裝時無需本地構建。
典型用法示例¶
在 Web UI 中使用¶
啓動 Web UI：
dsh --profile web
操作步驟：
- 新建會話並選擇「數據模式」。
- 點擊輸入框右上角的數據庫按鈕，在工作臺中填寫連接信息。
- 連接成功後，直接在對話框中提出分析問題。
- 根據第一輪結果繼續追問，讓 DSH 縮小範圍、比較維度或總結結論。
例如可以輸入：
分析最近30天訂單變化，找出銷售額下降最明顯的地區和商品，並解釋主要原因
DSH 會自行查看相關表、生成並執行查詢，再根據真實結果完成分析。
在 dsh-tui 中使用¶
啓動終端界面後，切換到數據模式並連接數據庫：
/preset data-agent
/database connect
連接成功後直接提問。常用數據庫命令還包括：
/database status 查看當前連接
/database test 測試當前連接
/database disconnect 斷開當前連接
/catalog scan 啓動 Catalog 掃描
/catalog status 查看掃描結果
爲獲得更有價值的分析，建議在問題中補充業務目標、時間範圍和關注維度，例如：
分析2026年第二季度各地區的銷售額和毛利率變化，找出表現異常的地區，
繼續拆解到品類和核心客戶，並給出三條可執行的業務建議。
使用前準備¶
DSH 執行查詢時，需要本機能夠訪問目標數據庫，並安裝相應的命令行客戶端（如 MySQL 的 mysql、PostgreSQL 的 psql 等）。ClickHouse 使用插件內置的 HTTP 適配器，無需單獨安裝 clickhouse-client。建議先準備一個只讀數據庫賬號，在不修改業務數據的前提下完成探索。
適用場景與注意事項¶
適合誰用：
- 需要在 DSH 對話中直接查庫、看數、做臨時分析的數據分析師或工程師；
- 希望用自然語言降低 SQL 門檻、又希望結果基於真實查詢數據的業務同學；
- 已在用 DSH Web UI 或 dsh-tui，想爲智能體補上「數據模式」工作流的開發者。
務必注意：
- 插件及其適配器運行在 DSH 進程內，以當前 dsh 進程的權限訪問數據庫與文件系統，並非操作系統級沙箱。安裝前應自行審閱源碼與 MIT 許可證，確認符合你的安全策略。
- 推薦使用數據庫只讀賬號，並在連接表單中開啓只讀模式。未開啓只讀時，Agent 可按你的要求執行更新或管理語句；連接生產庫前請確認賬號權限與備份策略。
- 不同會話的數據庫連接相互隔離，便於分別處理不同項目或客戶環境。
- Catalog 僅持久化脫敏後的元數據與人工確認的口徑，不保存密碼、查詢結果或樣例行；AI 候選的確認與刪除在 Web「數據治理」頁完成。
- 若出現
failed to mount或找不到@yejiming/dsh-data-agent，通常是當前 profile 尚未安裝插件或仍在使用舊版預設，需執行對應安裝命令後完全退出並重啓 DSH。
結尾¶
如果你希望把 DSH 從「寫代碼的智能體」擴展到「能連庫、能查數、能出報告的數據助手」，dsh-data-agent 是目前社區裏較完整的一條路徑：對話提問、自動 SQL、數據治理、HTML 報告與只讀保護都集成在「數據模式」預設裏，Web 與 TUI 也能共用同一套能力。
