ns-postgres-rag

PostgreSQL 检索（RAG / GraphRAG）

Postgres 检索准则：pgvector、FTS、实体/边、多跳。

分析。提出建议。不编写应用代码。 必须先批准所需报告（检索设计报告；当模式为关系型 GraphRAG 且已安装 ns-graphrag 时，还需 GraphRAG 流程报告）→ ns-spec-driven（Specify / Tasks）。

核心规则

链接 = 查询结果，绝不是文本推断。向量 = 候选项。只有在确认键/规则并存储溯源信息后，才能建立边。路径始终包含 path + provenance + confidence。

规范跳转链（仅作示例，英文产物）：company → contract → invoice → payment。在 GraphRAG 流程报告中推导语料链。

必需：pgvector。Timescale：可选 — 适用于时间序列数据量、保留策略或时间分区。规模：1MM+ 文件、文档链接。

适用性

上下文	要求
在 Postgres 上从零开始构建检索	必须在 DDL 获批前通过门槛 1–3
现有架构 / 索引	必须先盘点 DDL；诊断将相似度当作链接的问题
所需报告已获批，用户想要代码	停止。 Specify / Tasks 由 ns-spec-driven 负责（GraphRAG 且已安装 ns-graphrag 时，必须先完成流程报告）

阅读代码仓库（DDL、迁移、Postgres 版本、扩展、源格式）。不要向用户询问代码树已显示的信息。

路由（先阅读）

信号	操作
现在就要实现应用	如果缺少所需报告，则填写（检索设计报告；GraphRAG 且已安装 ns-graphrag 时还需流程报告）；否则转到 ns-spec-driven。不要编写应用代码
将相似度用作已存储链接	阅读 references/anti-patterns.md + references/entity-resolution.md
答案需要 N≥2 次跳转；没有单份文档包含完整链路	GraphRAG 模式 — 阅读 references/retrieval-decision.md。若已安装 ns-graphrag：完成检索设计报告后，转到该工具，在转交 ns-spec-driven 前先完成本体 / 抽取 / 答案形状 / 引用或拒答（流程报告）
本体、架构锁定的抽取、答案形状路由、引用或拒答	若已安装 ns-graphrag，则使用它 — 不属于本技能
主题搜索、语料较小、没有跳转链	仅向量检索 — 拒绝创建图表
GitLab ISSUE_URL 或 SDD 版本范围	延后处理，参见 ../../ns-harness/references/code-skill-routing.md

启动（必需）

参见 ../../ns-harness/references/session-boot.md — 完成 Session boot（阻塞项）。然后扫描：

1. DDL / 迁移（表、索引、vector、tsvector、实体/边）
2. Postgres 版本；扩展（必需 pgvector；如果存在 Timescale 或触发门槛 2，则检查 Timescale）
3. 源格式、语料路径、可推断的数量
4. 继续使用本技能

**成功：**依据代码树和项目规则完成盘点。**失败：**臆造架构，或向用户询问代码仓库中已有的信息。

流程

启动。门槛 1：语料盘点。门槛 2：检索决策。在 Postgres 中选择纯向量检索 或 混合 RRF 或 GraphRAG。门槛 3：检索设计报告。由用户审批。如果模式为关系型 GraphRAG 且 已安装 ns-graphrag：先在那里完成并获批 GraphRAG 流程报告，再转到 ns-spec-driven。否则转到 ns-spec-driven（或返回盘点流程）。

门槛 1 — 语料盘点（阻塞项）

根据代码仓库和数据样本填写。只有代码树无法显示的信息才询问用户。字段见：templates/retrieval-design-report.md。方法见：references/corpus-assessment.md。

字段	原因
规模（文件数、字节数、分块估算）	1MM+ 时的索引和存储
增长 / 可变性	重新嵌入率、增量写入还是重建
实体密度	图表还是仅向量检索
问题类型	模式
延迟预算（p95）	HNSW / 筛选 / 跳转上限

不得跳过。缺少盘点 = 不得进入门槛 2。

Gate 2 — 检索决策（阻断性）

恰好选择一种基础模式。决策矩阵：references/retrieval-decision.md。

模式	适用场景
仅向量	主题 / 相似度；无需多跳链
混合（tsvector + 向量，排序融合）	关键词 + 语义；一个文档通常就能给出答案
关系型 GraphRAG	N≥2 跳，且没有任何单个文档包含完整链

增强项（叠加使用，不改变基础模式）：none | multi-index | agentic | both。每个非 none 选项都需要有经测量确认、足以证明其合理性的症状。原则：references/retrieval-augmentations.md。默认选择 none。没有症状时，拒绝叠加使用。

扩展：始终使用 pgvector。Timescale 仅限 references/operations-and-scale.md 中的情况——不是默认选项。

在继续完整报告之前，先提交基础模式、增强项锁定结果，以及一段话说明理由。模式错误 = 重写 Gate 2，不要试图用 DDL 掩盖问题。

Gate 3 — 检索设计报告

复制 templates/retrieval-design-report.md。填写所有部分。不要编写应用代码。SQL = 目标 DDL / 查询形态，不是要发布的迁移。

由人工审批。若被拒绝：返回 Gate 1 或 Gate 2。

如果模式为关系型 GraphRAG，且已安装 ns-graphrag：不要立即进入 ns-spec-driven——先通过 ns-graphrag 完成 GraphRAG 流程报告（本体、提取、持久化模型、答案形态、引用或拒答）。两份报告均获批后，再进入 ns-spec-driven。如果未安装 ns-graphrag，请说明这一点，并以仅涵盖检索的范围进行交接（流程缺口仍未解决）。

参考资料索引

按需加载。

参考资料	阅读时机
references/corpus-assessment.md	Gate 1；1MM+ 预测
references/retrieval-decision.md	Gate 2 基础模式 + 分区 / Timescale
references/retrieval-augmentations.md	Gate 2 增强项（multi-index、agentic）；症状锁定
references/schema-and-indexes.md	目标 DDL、HNSW、筛选器、分区
references/entity-resolution.md	合并、别名、没有证据时不得创建边
references/ingestion-pipeline.md	提取、分块、嵌入、幂等 upsert
references/multi-hop-traversal.md	递归 SQL 上限；公司 / 合同 / 发票 / 付款
references/retrieval-contract.md	返回形态；path / provenance / confidence
references/evaluation-and-gates.md	黄金问题、召回率、错误链接、EXPLAIN
references/operations-and-scale.md	1MM+ 构建、存储、保留策略、Timescale
references/anti-patterns.md	将报告标记为完成之前

代码片段（示意性 SQL / 一种返回类型）：templates/snippets/。

交接给 ns-spec-driven

检索设计报告经人工审批后——如果模式为关系型 GraphRAG 且已安装 ns-graphrag，则还需 GraphRAG 流程报告经人工审批后：

## Retrieval implementation planning
- Report: path/to/retrieval-design-report.md (approved)
- GraphRAG Process Report: path/to/graphrag-process-report.md (approved | N/A if not GraphRAG or skill absent)
- Mode: vector-only | hybrid | relational GraphRAG
- Target DDL: [tables]
- Indexes: [HNSW / GIN / partition]
- Ingestion: [idempotent key + hash]
- Eval gates: [recall@k, path precision, false-link, p95]
- Out of scope for this skill: application code; GraphRAG process when ns-graphrag owns it

ns-spec-driven 负责 Specify / Tasks。此技能不编写任何应用代码。不要将 ns-graphrag 添加到此技能的 depends 中。

停止条件

条件	操作
人工要求实现应用	先完成必需报告（GraphRAG + ns-graphrag 时，包括流程报告）；然后仅进入 ns-spec-driven
将相似度提议为存储的边	拒绝；应使用候选 + 确认 + 来源信息
无 N≥2 跳的需求却采用图模式	拒绝图模式；使用向量或混合模式
将其他向量存储作为默认选项	坚持使用 Postgres + pgvector
递归遍历不设上限	限制深度、分支数、循环，并按分数剪枝
没有时间触发因素却使用 Timescale	不要推荐
跳过清单盘点	阻止进入 Gate 2

禁止事项

• 实现检索层（使用方迁移、工作进程、HTTP）
• 将嵌入距离当作链接
• 将外部图存储设为默认选项
• 未经 P0 推导，就把规范的多跳示意图视为唯一允许的语料链
• 指定应用语言或框架（允许 SQL / DDL；允许一个示意性返回类型片段）