PostgreSQL 专家 mirelconstantin/dsh-postgres-expert

dsh-postgres-expert

给 DeepSeek Harness 用的 PostgreSQL 专业知识。从 Tiger Data 的 pg-aiguide 精选出十一项技能，注册为原生技能，再加上公开的 MCP 服务，用来做版本精确的手册检索 ——这样模型就不会再凭记忆写出 2015 年那套 schema 了。

安装

谁都能装。只需要一个 DeepSeek Harness 配置档，别的什么都不用 ——不需要 API key，不需要数据库，也不需要账号，因为它唯一的网络请求只是可选的文档检索，打的是一个公开端点。

在 GUI 里，把下面这行粘进 Add plugin：

dsh-postgres-expert

或者在终端里：

dsh plugin add dsh-postgres-expert

这就是一次普通的 npm 安装。既不需要 git，也不需要 GitHub 账号。

不涉及任何构建步骤。 每个入口点都以源码形式提交，所以 pnpm 永远不必运行这个包的脚本，也不会有人要求你把某个构建加入白名单。装完重启配置档，就会多出三行。

改用智能体来装

你也可以直接说 「在这个配置档里装一下 dsh-postgres-expert 插件」，智能体会替你跑同样的安装 —— 它有个 plugin_manager install_bundle 工具，会帮你写好 bundle。
你并不需要走这条路，它也不更省事；之所以留着，是因为有时候从智能体安装是唯一可行的办法，比如在远程主机上。

用这条路的话有一点要知道：装一个包就意味着它的代码会在你机器上跑，所以智能体会先请求批准。这个提示才是重点，不是障碍。

其他安装途径

| 途径 | 命令 |
| npm，默认方式 | dsh plugin add dsh-postgres-expert |
| 锁定到某个版本 | dsh plugin add dsh-postgres-expert@1.0.0 |
| 锁定到某个 commit | dsh plugin add github:mirelconstantin/dsh-postgres-expert#<sha> |
| Tarball | dsh plugin add ./dsh-postgres-expert-1.0.0.tgz |
| 本地 checkout | dsh plugin add /absolute/path/to/dsh-postgres-expert |
| 作为配置档依赖 | 见下文 |
GitHub 方式只需要能访问这个仓库的 git。npm 方式既不需要 git，也不需要账号，上面那条命令用的就是它。

作为配置档依赖，把它加到 package.json 和 dsh.profile.bundles：

{
"dependencies": {
"dsh-postgres-expert": "1.0.0"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-postgres-expert"]
}
}
}

dsh plugin add 会替你完成这两处修改。

它添加了什么

| 行 | 作用 |
| postgres-expert-skills | 在 ctx.skills 上注册 11 个内置技能 |
| postgres-expert-prompt | 系统提示词段落，让这些指导被模型知晓 |
| postgres-expert-mcp | 通过 Streamable HTTP 连接公开的 pg-aiguide MCP 服务器 |

这些行彼此独立。只有 postgres-expert-mcp 会访问网络，所以禁用它之后，精选技能可以完全离线使用：

- id: postgres-expert-mcp
disabled: true

覆盖这一行会替换掉它整个 config 对象，所以仍然需要的字段都要重新声明。字段就是 @deepseek-ai/dsh-mcp-client 配置：transport、serverName、url、headers、toolCallTimeoutMs、failOnStartupError、maxInstructionBytes 和 reconnect。

技能

| 技能 | 覆盖内容 |
| postgres | 总线路由；为任何 PostgreSQL 任务指向合适的参考 |
| design-postgres-tables | 数据类型、约束、索引、JSONB、分区 |
| design-postgis-tables | 空间设计、geometry 与 geography、SRID、空间索引 |
| schema-exploration | 通过 pg_catalog 只读探索现有数据库 |
| postgres-database-migration | 零停机 DDL、锁级别、回填、回滚 |
| pgvector-semantic-search | 向量索引、过滤搜索、调优 |
| postgres-hybrid-text-search | BM25 与语义搜索用 RRF 融合 |
| setup-timescaledb-hypertables | 超表、压缩、保留策略、连续聚合 |
| find-hypertable-candidates | 为现有表评估超表转换可行性的 SQL |
| migrate-postgres-tables-to-hypertables | 分区列选择、原地与蓝绿、验证 |
| timescaledb-hyperfunctions | 用于聚合与分析的超函数 |

它们如何自行加载

你不需要调用技能，也不需要记住名字。harness 负责路由，而且发生在模型做出任何决定之前：

1. 每个技能都会自我声明。 会话的第一步，harness 会注入一份 <available_skills> 目录，包含每个技能的名称和描述——仅此而已，没有正文。每个会话都会自动获得它。
2. 描述就是路由表。 它们就是为此而写的：pg-aiguide 每个描述都塞满了触发短语和一行关键词（PostgreSQL, Postgres, schema, table design, indexes, constraints, hypertable, semantic search, …）。真正促成匹配的是这些内容，而不是这个插件做了什么。
3. 模型按需加载。 任务涉及 PostgreSQL 时，模型自己调用 skill({ name })。整个机制就这么简单。

所以「当话题是 postgres 时」本来就是它的行为：你要一个 schema，模型会自己加载 postgres 或 design-postgres-tables。问 React 则什么都不加载，因为提示词里只有目录。

这个插件自带的 postgres-expert-prompt 段落点名了这些技能和 MCP 工具，进一步强化了这一点，模型不必自己推断工具存在。

唯一做不到的是覆盖刻意的限制：预设的 tools.restrict({ allow: [...] })、子代理的 toolFilter，或者被禁用的 postgres-expert-skills 行，都会把技能从对应作用域里移除，提示词段落也随之撤下，不会去宣传它够不到的工具。

正文按需加载，所以从不碰 PostgreSQL 的会话不会为此付出任何代价。

MCP 连接

harness 连接到 https://mcp.tigerdata.com/docs，协商协议，发现工具，并把每个工具暴露成普通的 harness 工具，带取消、权限检查和结果记录。它不托管也不监管服务器——Tiger Data 负责运行。

上游只暴露两个工具：

| 工具 | 参数 |
| mcp__pg-aiguide__search_docs | source、query，可选 limit（默认 20）和 semanticWeight（0 关键词 → 1 语义，默认 0.7） |
| mcp__pg-aiguide__view_skill | name，可选 path |

source 把语料库和版本合在一个值里——tiger、postgres_14 … postgres_18、postgis_3.3 … postgis_3.6。没有单独的版本参数。

view_skill 与这里内置的技能有重叠，所以这些技能是原生注册的，而不是通过 MCP 读回来。

发现是异步的：重启之后，先等 mcp__pg-aiguide__* 工具就绪，再发送第一个需要它们的提示词。如果端点不可达，bundle 仍会加载，failOnStartupError: false 保持这一行为，重连策略会退避重试。

保持同步

插件提供的是 assets/skills/ 下内置的技能，所以没同步的副本就是一个提供过时建议的包。

assets/upstream.json 是来源凭证。 它记录上游 commit、每个文件的 SHA-256 摘要，以及这份副本所依据的许可证——所以这个包对应哪个确切的上游状态，无需拉取任何东西就能审查。

npm run sync # rewrite assets/skills/ and the pin from upstream
npm run sync:check # fail if the vendored tree differs from what upstream gives
npm test # behaviour tests over the catalogue and the sync helpers
GitHub Actions 工作流每天运行一次 sync，上游有变动时就开一个 pull request。每次 push 和 pull request 时，CI 都会在 Linux 和 Windows 上运行 sync:check，所以包不可能基于过期的镜像发布。

发布

只合并上游同步还不够：registry 提供的是固定 tarball，所以上游有了新状态，必须先出一个新的 npm 版本，别人才拿得到。

npm run prepublish # every gate, without publishing
npm version patch # 1.0.0 -> 1.0.1
npm publish
git push --follow-tags

npm publish 会先运行 scripts/prepublish.mjs，任何一项失败就拒绝发布。已发布的名称和版本永远不能复用，即使 unpublish 之后也不行，所以这道关卡会检查版本在 registry 上是否空闲、工作区是否已提交、tag 是否指向 HEAD——否则 registry 和仓库会在同一个版本号下描述不同的代码。

同步如何读取上游

只取一个仓库 tarball，sha 由 git ls-remote 解析——所以不需要 GitHub token，定时运行也不会耗尽 API 速率限制。上游树里有两个细节要专门处理：

- 符号链接会被实体化。 pg-aiguide 的 postgres 总括技能用相对符号链接把 references/ 指向同级技能。这些链接在有些 checkout 或 npm publish 流程中会丢失，所以把内容复制到位，让 vendored 树在每个平台上都完全一致。
- 只复制 skills/ 下的 markdown，这样产物始终可审阅。

许可与署名

vendored 技能按 Apache License 2.0 原样再分发，来自 timescale/pg-aiguide。见 LICENSE 和 NOTICE；上游版权声明按该许可要求逐字保留。

本插件配置的是连接 Tiger Data 运营的公共 MCP 服务器。它不 vendored 任何服务器代码，也不发送遥测。

icon.svg 是 Pazalo 的 logo。

目录结构

cordis.patch.yml the bundle: three independent rows
icon.svg the plugin panel's row image
src/catalog.js reads the vendored skills and their frontmatter
src/entry-skills.js loader entry registering the skills
src/entry-prompt.js loader entry publishing the guidance section
src/prompt.js the guidance text and its visibility check
assets/skills/ the vendored pg-aiguide skills (synced, not edited)
assets/upstream.json the upstream commit and a digest per file
scripts/sync-upstream.mjs the vendoring tool
scripts/check-patch.mjs CI gate: bundle patch, exports and icon
test/plugin.test.js behaviour tests

绝不要手动编辑 assets/skills/ 下的任何内容：下一次同步会覆盖它，sync:check 也会因差异而失败。要改就改上游，或者改本插件自己的源码。

插件 © 2026 dsh-postgres-expert contributors 技能 © 2025 Timescale, Inc., d/b/a Tiger Data — Apache-2.0