前言¶
在 DSH 里做智能体或本地工具开发时，经常需要对照 PostgreSQL 里的表结构、抽样看几页数据、试筛选和关联是否合理。常见做法是开 psql、写临时 SELECT，或在 IDE 里装数据库扩展。DSH PG Grid 是面向 Web 配置档的原生客户端插件：在侧边栏用表格和可视化规则完成浏览、筛选、排序、同库关联、计算列与透视，查询经受限的只读编译器下发，不提供任意 SQL 入口。下面介绍它是什么、能做什么，以及如何安装与使用。
这是什么¶
DSH PG Grid（仓库 HeShen-1/dsh-pg-grid）由维护者 HeShen-1 发布，分类为客户端插件。定位是「DSH 原生 PostgreSQL 数据工作区」：独立实现，不依赖 VS Code 扩展。目标是在本机回环地址上的 PostgreSQL 上，通过界面完成分析与导出，而不手写 SQL。
社区目录页：skillhub.cn 插件条目。目录为社区站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，安装前仍建议自行查看源码与 MIT 许可证。
核心功能¶
以下能力均来自项目 README 与 package.json 说明。
连接与浏览¶
- 仅支持本地回环：
127.0.0.1、localhost或::1；远程主机、隧道与跨库关联不在当前版本范围内。 - 发现表、schema、视图；服务端分页（每页 25–500 行）。
- 查询在 PostgreSQL
READ ONLY事务中执行，经受限、参数化查询编译器；无任意 SQL、DML 或 DDL 接口。
筛选、排序与表头操作¶
- 嵌套 AND/OR 筛选、多列排序，作用于完整匹配数据集，而非仅当前页。
- Excel 风格列头菜单：升序/降序、可搜索的分页取值、包含/排除勾选、条件与清除筛选；表头筛选可写入已保存视图并作用于导出；NULL 与空字符串区分对待。
- 普通列与聚合列支持筛选；透视支持行维度。
关联、计算与统计¶
- 同库 inner/left 等值关联，支持多列连接键；一对多关联会保留重复的父行（有意设计）。
- 基于字段的计算列：算术、舍入、条件、空值处理、拼接与日期部分；计算列不可引用其他计算列。
- 分组与 count/sum/average/min/max；透视表合计从源行重算。
- 单次查询计划上限：最多 8 张源表、20 个计算列；查询超时 15 秒。
表格交互与导出¶
- 列宽/顺序/隐藏/冻结，区域选择、键盘导航、剪贴板与 CSV 导出。
- 筛选、关联、聚合与完整导出针对整表关系；完整导出最多 100,000 行。透视最多 100 个列值、100,000 条分组记录；超限会明确失败而非静默截断。
- 大整数、decimal、JSON、日期时间保留文本表示；NULL、空串与零区分；CSV/剪贴板中 NULL 为
\N。
视图与刷新¶
- 本地保存分析视图（规则与列设置，非数据快照）；重新打开时拉取新数据。
- 当前可见视图每 30 秒自动刷新，可暂停/手动刷新，支持取消与过期响应保护。
界面与主题¶
- 接入 DSH 主题；不透明粘性表头、可见滚动条、可折叠分析设置。
可选 AI（默认关闭）¶
自然语言适配已实现，但发布配置中 aiEnabled: false（cordis.patch.yml）。普通浏览、刷新、导出与保存视图不会调用模型。启用后才会向 DSH 设置中的模型发送选定表结构、当前规则、请求及可选最多 20 行当前页数据；模型输出须通过同一封闭查询编译器与表范围检查。启用可能消耗提供商配额或产生费用。
安装与启用¶
README 写明在 DSH 0.2.1-rc.2、Node.js 22+ 下测试。Web 配置档安装预构建包：
dsh plugin --profile web add https://github.com/HeShen-1/dsh-pg-grid/releases/download/v0.1.0/dsh-pg-grid-0.1.0.tgz
刷新 DSH 后，在侧边栏打开 数据表。可在 DSH 插件管理器中启用或禁用。若入口未出现，可在方便时重启 DSH。README 注明：当前 DSH 版本在禁用宿主插件后可能仍保留已加载的侧边栏项，但 API 已注销，查询会停止。
源码检出可能包含比固定 v0.1.0 发布包更新的功能；需自行构建后从本地路径安装：
dsh plugin --profile web add /absolute/path/to/dsh-pg-grid
插件以当前 dsh 进程权限运行；安装前应检查仓库源码与许可证。固定发布包版本为 0.1.0（package.json）。
典型用法¶
- 在插件中配置本地 PostgreSQL 连接（仅回环地址）。可选 记住密码（仅保存在本机），密码写入
$DSH_HOME/pg-grid/credentials.json（默认~/.dsh/pg-grid/credentials.json），权限0600；元数据与已保存视图在views.json。这是本机明文存储，不能抵御同账户或 root 下的其他软件；勿提交或分享这些文件。 - 选择一张表，在 查询规则 中配置筛选、排序、关联、计算列或分组/透视。
- 点击 应用查询规则 查看结果；列宽等在 列设置 中调整。
- 需要复用分析时点击 保存视图（保存的是查询规则，不是数据快照）。
不勾选记住密码时，凭据仅在宿主插件存活期内有效；API 不会返回密码，也不会写入模型提示。
适用场景与注意¶
适合： 本机开发库上的只读探查、规则化筛选与导出、同库多表等值关联与简单透视、把分析规则保存为视图以便反复刷新。
不适合或当前不支持： 远程库、写回或改表、电子表格导入、A1 公式、XLSX、空白工作表；任意 SQL 或跨库 join。
资源与语义： 除零得 NULL 并警告；无效类型报错。最多 20 个连接。无源数据编辑能力。
AI： 默认关闭；若自行开启，需了解路由、计费与 ai-validation.json 等本地校验授权说明（见 README），勿将校验用的费用预留当作通用账单上限。
结尾¶
DSH PG Grid 把本地 PostgreSQL 的只读分析收进 DSH 侧边栏：可视化规则、同库关联、计算列与透视，配合保存视图与 CSV 导出，减少临时 SQL 与外部扩展依赖。查阅安装包与 issue 请用 GitHub 仓库；在社区目录浏览条目见 skillhub.cn。
