pi-sqlkb — Pi 的 SQL 知识注册表扩展

为 Pi（AI coding agent）提供渐进式披露的 SQL 知识检索，复用与 DSH dsh-sqlkb 插件完全相同的知识库（~/.agents/sqlkb，front-matter + 正文 markdown）：表结构、字段注释、已沉淀的查询示例，一套知识两处共享，无需重复维护。

能力

Pi 会话注入五个工具 + prompt 引导：

| 工具 | 用途 | |------|------| | sqlkb_list | 列出全部表/示例/坑点的紧凑清单（做 SQL 相关工作第一步先调用） | | sqlkb_search | 关键词检索：表匹配元数据 + 正文字段名/字段注释（「销售额」也能命中含 restore_sales_amt 字段的表）；词元拆分、量词后缀兜底、强匹配 ★ 排前；未命中自动附全量清单；命中表/示例自动附上相关坑点 | | sqlkb_get | 按表名/示例名/坑点名读取单个明细；读表/示例自动附带关联坑点 | | sqlkb_create | 写入：新增表/示例/坑点（遵循 front-matter 规范）。表/示例需 user_approved: true；坑点可直接记录（沉淀踩坑经验） | | sqlkb_update | 写入：更新已有表/示例/坑点的字段或正文（只更新传入字段）。表/示例需 user_approved: true；坑点可自行修订；删到缺必填被拦 |

引导约束（注入 pi system prompt）：

• 知识库权威：~/.agents/sqlkb（tables/examples/pitfalls）是表结构/字段注释/查询示例/踩坑经验的权威来源，做 SQL 相关工作以它为准，不凭印象写 SQL；
• 做 SQL 相关工作第一步必须先 sqlkb_list，不要凭印象写 SQL 或直接搜索；
• 标准链路：sqlkb_list（看全量）→ sqlkb_search（业务指标词/字段名/字段注释缩小范围）→ sqlkb_get（读单个明细）；
• 表和示例都要看：先 sqlkb_get 读相关示例（沉淀了口径红线/SQL，可复用），再读表字段清单，两者都读完再写 SQL；
• 坑点自动暴露：执行 SQL 前留意 sqlkb_search/sqlkb_get 结果里的「相关坑点」（按表/示例关联），先读坑点避免重复踩坑；
• 创建/更新知识：表/示例用 sqlkb_create/sqlkb_update 必须遵循 front-matter 规范、字段/口径正确，并先征得用户明确同意（user_approved: true）；执行 SQL 出错/踩坑后用 sqlkb_create(kind=pitfall, tables=相关表) 直接沉淀经验，无需用户同意。

安装

# 本地源码目录（改代码即生效，无需重装）
pi install /path/to/pi-sqlkb

# 或发布后
pi install npm:pi-sqlkb

查看：pi list；启用/停用单个资源：pi config。

配置

• 数据目录：默认 ~/.agents/sqlkb（与 DSH sqlkb 插件同一份知识库）。可用环境变量 PI_SQLKB_DATA_DIR 覆盖到其它路径。
• 知识文件（tables/<表名>.md / examples/<示例名>.md）由你在 ~/.agents/sqlkb 自行维护，新增后无需改扩展。

知识库格式（与 DSH sqlkb 一致）

表文件 front-matter：name / type / purpose / exec / engines / tags（related 可选）；正文放字段清单 + 补充。 示例文件 front-matter：name / purpose / tables / tags；正文放用途 + 口径 + SQL + 来源。 坑点文件 front-matter：name / type / tables / tags（related_examples / severity 可选）；正文放坑描述 + 错误示例 + 正确做法。

详见 ~/.agents/sqlkb/README.md。

开发

npm install          # 安装 typebox（工具 schema 依赖）
node --experimental-strip-types --check extensions/index.ts   # TS 语法
node test/*.test.mjs # 单元测试（mock pi 捕获工具 + 对真实知识库断言）

说明

• 读工具（list/search/get）为只读；写工具（create/update）直接改 ~/.agents/sqlkb。
• 创建/更新规范：sqlkb_create/sqlkb_update 遵循 front-matter 规范（表必填 name/type/purpose/exec/engines/tags，示例必填 name/purpose/tables/tags，坑点必填 name/type/tables/tags），正文字段名与实际表字段一致、口径写明唯一来源表/字段；表/示例必须先征得用户明确同意后以 user_approved: true 调用，坑点记录/修订可直接执行（纯追加经验）。
• 坑点沉淀：执行 SQL 出错/踩坑后，用 sqlkb_create(kind=pitfall, tables=相关表, type=坑类型, tags=标签) 记录；检索表/示例时自动暴露相关坑点，避免重复踩坑。
• 也建议先在 DSH 侧用 sqlkb_pending/sqlkb_create 管理待补与确认流程；本扩展直接读写同一份知识库。
• 知识库位置通过 os.homedir() 计算，不硬编码绝对路径。

许可

MIT