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（写入自动带 updated 日期）；示例需 user_approved: true；坑点可直接记录（沉淀踩坑经验）
sqlkb_update	写入：更新已有表/示例/坑点的字段或正文（只更新传入字段）。表更新自动记录、无需 user_approved（刷新自动重置 updated 日期）；示例需 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=相关表) 直接沉淀经验，无需用户同意。
• 表缓存过期自动更新（30 天）：表结构缓存超 30 天未更新会标 ⚠️缓存N天未更新（list/search）或在读表时醒目提示（get）；先重新 DESCRIBE/探查与线上核对，再用 sqlkb_update(kind=table) 自动刷新（无需同意），刷新即重置过期时钟。只提示不替探查。

安装

# 本地源码目录（改代码即生效，无需重装）
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、updated 可选——updated 为结构记录/刷新日期，sqlkb_create/sqlkb_update kind=table 自动带当天，缺省回退文件修改时间）；正文放字段清单 + 补充。 示例文件 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），正文字段名与实际表字段一致、口径写明唯一来源表/字段；表信息（结构/字段）创建/更新自动记录、无需用户同意（表缓存 >30 天自动刷新），示例创建/更新必须先征得用户明确同意后以 user_approved: true 调用，坑点记录/修订可直接执行（纯追加经验）。
• 表缓存过期自动更新：表文件 front-matter 可带 updated（结构记录/刷新日期，sqlkb_create/sqlkb_update kind=table 时自动带当天；缺省回退文件 mtime）。缓存日期距今 > 30 天 判过期：list/search 行尾标 ⚠️缓存N天未更新，sqlkb_get 读表时在字段清单前醒目提示；过期后先 DESCRIBE/探查核对，用 sqlkb_update(kind=table) 自动刷新（无需同意）重置过期时钟。
• 坑点沉淀：执行 SQL 出错/踩坑后，用 sqlkb_create(kind=pitfall, tables=相关表, type=坑类型, tags=标签) 记录；检索表/示例时自动暴露相关坑点，避免重复踩坑。
• 也建议先在 DSH 侧用 sqlkb_pending/sqlkb_create 管理待补与确认流程；本扩展直接读写同一份知识库。
• 知识库位置通过 os.homedir() 计算，不硬编码绝对路径。

许可

MIT