前言¶
在 DeepSeek Harness（DSH）裏寫智能體或日常排錯時，SQL 往往散落在聊天記錄、本地筆記或各業務倉庫的零散文件裏。換機器、換項目或讓 Agent 協助查數時，很難按「系統」維度快速找到那條曾經驗證過的語句。筆記裏只有自然語言描述時，也不便按表名、字段名反查。
SQL Manager 是 DSH 社區插件，由維護者 sijunmanyue 發佈，在目錄中歸類爲「記憶」。它把可複用 SQL 按業務系統分組保存，每個系統必須指定獨立的 JSON 存儲路徑；側邊欄與 Agent 工具都支持按備註、表名、字段名和原始 SQL 文本搜索。下文按安裝、用法與存儲結構說明如何落地使用。
這是什麼¶
SQL Manager（倉庫 sijunmanyue/dsh-plugin-sql-manager）面向需要在本地長期維護 SQL 片段的 DSH 用戶。與「整庫放在一個全局目錄」不同，插件要求每個系統各自綁定一個 JSON 文件路徑（或指向會自動生成 <system-id>.json 的文件夾），系統之間可以分佈在不同磁盤路徑。包名在 package.json 中爲 @local/sql-manager，當前版本 1.1.0，許可證 MIT。
核心功能¶
按系統管理 SQL¶
每個「系統」對應一份自包含的 JSON 文件，內含系統元數據（id、name、description 等）和 sqls 數組。單條 SQL 記錄包含名稱、remark（備註）、SQL 正文，以及從語句解析得到的 tables、fields（讀取文件時會根據 SQL 文本刷新，便於檢索）。
檢索維度¶
界面與工具支持用備註（例如 README 示例中的 客服）、表名（如 t_user）、字段名（如 user_id）以及 SQL 原文進行搜索。
Agent 工具 sql_manager¶
頁面能力同樣暴露爲 Agent 工具，操作包括：search、list_systems、add、update、delete、create_system、update_system、delete_system。智能體在對話中可直接查詢或維護庫內 SQL，而不僅依賴側邊欄。
路徑編輯與導入¶
修改系統的 Storage path 時，已有 JSON 會遷移到新位置；若新路徑已指向有效的系統 JSON，則導入該文件而非覆蓋。系統文件缺失或不可讀時，界面會標記爲損壞系統，可通過 Edit path 修復或移除。
本地 HTTP API¶
插件提供 /api/sql-manager，且僅接受 loopback 請求。刪除系統會同時刪除對應 JSON 與註冊表項。插件沒有全局存儲目錄類的統一配置項。
安裝與啓用¶
官方 README 的安裝方式爲克隆倉庫後，通過 DSH 插件管理器安裝本地 bundle。克隆命令如下：
git clone https://github.com/sijunmanyue/dsh-plugin-sql-manager.git
隨後在 Plugin Manager 中對克隆得到的目錄執行 bundle 安裝，或使用 plugin_manager install_bundle 並傳入該目錄的絕對路徑。若未自動啓用，請在插件列表中啓用 SQL Manager。
安裝前建議閱讀倉庫源碼與 MIT 許可證，並確認你願意以當前 DSH 進程的權限運行該插件（本地 API 與文件讀寫均在此權限下完成）。
典型用法¶
側邊欄四步¶
- 在側邊欄打開 SQL Manager。
- 新建系統並填寫必填項 Storage path：
- JSON 文件路徑，例如D:\SQL\crm.json；或
- 文件夾路徑，例如D:\SQL\crm（插件會在目錄內創建<system-id>.json）。 - 在該系統下添加 SQL 條目。
- 用備註、表名或字段名搜索，例如搜索
客服、t_user、user_id。
存儲佈局說明¶
系統路徑註冊表位於 $DSH_HOME/sql-manager/systems.json（僅索引各系統 JSON 的實際路徑，不是全局 SQL 倉庫）。DSH_HOME 默認爲 ~/.dsh。新建系統時，README 建議可選用 $DSH_HOME/sql-manager/sqls，但每個系統的路徑仍可單獨修改。
系統 JSON 結構示例如下（字段含義以 README 爲準）：
{
"schema": "dsh.sql-manager.system/v1",
"id": "crm",
"name": "CRM 訂單系統",
"description": "訂單域",
"path": "D:\\SQL\\crm.json",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z",
"sqls": [
{
"id": "sql-0123456789ab",
"name": "按手機號查用戶",
"remark": "客服常用；按手機號精確查詢",
"sql": "SELECT u.id, u.mobile FROM t_user u WHERE u.mobile = ?",
"tables": ["t_user"],
"fields": ["id", "mobile"],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
]
}
JSON 中的 path 爲描述性字段；以註冊表記錄的路徑爲準。若你從舊版「單一全局存儲目錄」升級，首次運行且尚無註冊表時，插件會掃描遺留的 settings.json 目錄、SQL_MANAGER_DIR 環境變量指向的位置以及上述建議目錄，並自動註冊其中的系統 JSON。
適用場景與注意¶
適合誰： 在多套業務庫之間切換、需要把「按系統 + 按表/字段可搜」的 SQL 庫掛在 DSH 側邊欄或 Agent 工作流裏的開發者；希望 SQL 以明文 JSON 落在自選路徑、便於備份與版本管理的團隊。
注意事項：
- 插件在本地 DSH 環境中讀寫你指定的路徑，安裝前應覈對源碼與權限範圍。
- 刪除系統會刪除對應 JSON 文件，操作前請確認備份。
- DSH 插件生態遵循「一切皆插件」思路；社區目錄站點 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係，本文事實以 GitHub README 與
package.json爲準。
經過上面的步驟，你可以把分散的 SQL 按系統歸檔到獨立 JSON，並在人和 Agent 兩側用同一套檢索方式複用這些語句。更多細節見 GitHub 倉庫 與 SkillHub 目錄頁。
