前言¶
在 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 目录页。
