ns-graphrag

GraphRAG 流程

端到端的流程知识，用于在 ns-postgres-rag 设计的检索层上构建 GraphRAG。

分析。明确流水线。不要提及应用语言或产品名称。

存储、索引、混合排序、递归跳数上限、证据／提及 DDL，以及检索设计报告由 ns-postgres-rag 负责。本技能负责知识的提取、持久化、查询和引用方式。

核心规则

跳数指的是带有证据行的已存储类型化边。相似度只用于提出候选项。共现不会创建边。每个操作员的回答都必须引用原文来源片段（否则拒绝回答）。被拒绝的记录会被省略，绝不解释为“无权访问”。

规范跳数链（仅作示例）：company → contract → invoice → payment。在 P0 中推导语料库链。

与 ns-postgres-rag 的职责划分

问题	负责方
向量、混合还是 GraphRAG？DDL、HNSW、跳数 CTE、证据／提及表、返回字段	ns-postgres-rag
本体、提取器契约、文档类型、回答形态、引用、搜索前 ACL、发现门控	本技能

如果 Gate 2 不是关系型 GraphRAG，请停止。不要为了“以后使用”而凭空设计图表。

语言禁令

指令、报告和提取器契约只能命名概念（文本单元、存续身份、逻辑边、证据、提及、回答形态）。不要提及编程语言、框架、UI 工具包、容器运行时或供应商的模型 SKU。只使用模型角色：extract、embed、classify、summarize、compose。

SQL／DDL 结构应保留在 ns-postgres-rag 代码片段中。

启动（必需）

1. ../../ns-harness/references/session-boot.md — 会话启动（阻塞项）。
2. 阅读 ../ns-postgres-rag/SKILL.md 中的路由和 Gates 1–2。如果没有已批准的检索设计报告，且模式为 GraphRAG，先填写或要求提供该报告。
3. 检查语料格式、现有地籍键、权限模型和问题类型。
4. 继续本技能。

**成功：**完成清单盘点，并论证 GraphRAG 模式合理。**失败：**本体尚未确定就编写提取器提示词，或没有 N≥2 的拆分链路需求却构建图。

流程

启动 → P0 锁定本体 → P1 非结构化数据 → 文本单元 + 质量门控 → P2 按架构锁定提取 → P3 解析身份 → P4 持久化逻辑边 + 证据 + 提及 → P5 为单元 + 实体描述生成嵌入 → P6 回答形态 + 图契约 → P7 GraphRAG 流程报告 → 人工批准 → ns-spec-driven。

仅当已声明的问题类型不属于六种回答形态时，才可选择启用发现（引用假设，不回写）——references/discovery-layer.md。

交互式查询优先于摄取作业。摄取采用分阶段、幂等、按阶段重试的方式。

P0 — 锁定本体（阻塞项）

词汇表固定。提取器不得自行发明类型。推导流程（不是现成列表）：references/ontology.md。

任何提取批次开始前，必须锁定：

• 与宿主注册表架构对齐的实体类型（封闭列表）。
• 根据已声明的问题跳数链推导的关系类型（封闭列表，含方向定义）。
• 可选的声明／协变量类型（在提示词调优前默认关闭）。
• 每种类型的存续身份键（身份层级）；声明仅用于提及的类型。
• 每个提取批次都要包含本体版本 ID。

开放词汇会导致图碎片化，并破坏身份合并、遍历和引用完整性。

P1 — 非结构化数据 → 文本单元

从字节中进行确定性提取。每个文本单元保留 document_id、序号、页码／片段、字符偏移量、内容哈希和文本质量等级。优先按段落／章节边界切分，避免在句子中间切断。保留重叠部分，以便跨单元的关系仍能提取。禁止使用包含整个大文件的超大单元。文本质量降级时，应重新提取或放入故障队列——绝不允许静默索引。

详情：references/unstructured-to-units.md。Upsert 标识：../ns-postgres-rag/references/ingestion-pipeline.md。

P2 — 架构锁定的提取

每个文本单元执行一次结构化处理：

1. 实体：name、type（本体）、description、上下文中的角色、标识符字段（按类型区分；不得臆造）。
2. 关系：source、target、type（本体）、description、来源文本片段、溯源类别 EXPLICIT 或 INFERRED、confidence（0–1）。
3. 可选的文档级字段（标题、作者、日期）采用嵌套结构 { value, sources[], reasoning } —— 上下文信息不足时，拒绝填写该字段。
4. 文档类别 + 置信度分级（已分类／低／未分类；平局差距会降级）。
5. 词表外发现项 → 放入未映射候选项队列，而非强行归为最相近的类型。

提取器指令是根据已批准的本体组装的构建产物 —— references/structured-extraction.md、templates/extractor-instruction.template.md。

限制每个单元的三元组数量。依据本体校验类型；丢弃非法标签。描述会用于锚点映射和综合整理 —— 只有裸三元组会让内容组合缺少支撑。

P3 — 解析身份

先执行确定性规则，再生成向量候选项，最后确认 —— 每种类型均采用有序的身份判定阶梯；对于类人类型，规范化名称绝不是身份标识。模型提取标识符；确定性层解析标识符。

未解析的锚点会向调用方返回按排名排列的候选项 —— 不得静默猜测。

详情：references/graph-assembly.md、../ns-postgres-rag/references/entity-resolution.md。

P4 — 持久化逻辑边、证据和提及

1. 逻辑边由 source + type + target 唯一标识。执行 Upsert：保留置信度最高的值；溯源类别不降级；根据关系置信度映射设置 review_status —— references/structured-extraction.md § 关系置信度 → review_status（在报告中锁定数值）；冲突时只升级为 fact。
2. 证据：每条佐证均追加一条记录，包含文档、单元、引用片段和置信度。一条边可关联多条证据 —— 不要为每条佐证各建一行。
3. 提及：单元到实体的关联，包含上下文中的角色 —— 是筛选集合、计数和综合整理的基础；不是边。
4. 文件与业务记录：使用不同锚点；存储明确的文件到文件引用；共享实体 = 仅为发现到的路径。
5. 提案（拟议记录／链接）不是事实，不可遍历；在报告中声明确认策略。
6. 根据引用的映射持久化 review_status；遍历仅使用 fact。DERIVED 路径是查询结果 —— 绝不作为边持久化。

详情：references/graph-assembly.md。

P5 — 嵌入

执行嵌入，并在每一行记录模型 ID + 维度：

对象	用途
文本单元	向量／混合查找；本地证据
实体描述	用于路径和集合筛选的锚点映射

存在现有词法索引时，复用它进行混合排序 —— 无充分理由时，不要提议重建。

版本化重新嵌入：../ns-postgres-rag/references/ingestion-pipeline.md。

P6 — 答案形态 + 图契约

按答案形态路由，而不是使用单一的全局／局部开关。

形态	适用情况
单元 / 向量	主题位于一个单元中；无需跳转链
路径	有命名锚点；“A 如何到达 B”；N≥2 跳
筛选集	包含属性谓词的实体集 + 可选时间窗口
计数 / 聚合	分组或总计；逐行溯源
锚点综合	打开记录时生成限定范围的摘要
文档关联	新上传内容与注册表对比；包含未注册的提及

范围限制（集合、导入来源、文档类型）必须在排序之前与授权一并应用，不得在排序之后应用。

边的时段和记录时间上的时间谓词是一等筛选条件。

遍历：有上限的递归遍历（../ns-postgres-rag/references/multi-hop-traversal.md）。默认深度 ≤ 5。逐跳规范：每一步内部都要执行授权、类型／置信度筛选、top-N 和已访问集合；被拒绝的节点不能作为桥接节点。批量扩展：每跳对锚点集合只进行一次读取，绝不逐节点读取。每跳不调用模型——模型只用于提取和合成。

仅根据检索到的单元／路径／证据合成答案。若缺少证据：拒绝回答。每项陈述的事实都必须附带引用。

规范图查询（英文线名）：

query_knowledge_graph
{ anchor_ids[], anchor_type, edge_types[], max_depth (≤ 5), period?, scope?, limit?, include_evidence? }
→ { nodes[], edges[], paths[], candidates[]?, telemetry }

遥测信封：已执行的跳数、检查数与返回数、截断原因、各阶段延迟、缓存命中情况。

禁止事项：自由 SQL/Cypher 风格工具；无界深度；将 pending_review 当作事实；将被拒绝的节点作为桥接节点；每跳调用模型。

运维可视化展示查询路径，而非整张图。

详情：references/query-modes.md、references/access-and-citation.md。

角色划分

实现必须拆分身份解析器、遍历执行器、实体／边／证据／提及存储库、授权服务、缓存和遥测——详情：references/graph-assembly.md。类／模块布局 = ns-spec-driven。

P7 — GraphRAG 流程报告

复制 templates/graphrag-process-report.md。填写所有章节。在 ns-spec-driven 之前由人工审批。

参考资料索引

参考资料	阅读时机
references/ontology.md	P0；推导；未映射队列
references/unstructured-to-units.md	P1；质量门禁；偏移量
references/structured-extraction.md	P2；提取器契约
templates/extractor-instruction.template.md	P2；构建产物形态
references/graph-assembly.md	P3–P4；证据；提及
references/discovery-layer.md	仅限选择启用的分析
references/query-modes.md	P6；六种形态
references/access-and-citation.md	ACL、不可信输入、缓存
references/process-eval.md	黄金集、指标
references/anti-patterns.md	标记报告完成前
../ns-postgres-rag/references/*	模式、解析、跳数、规模

移交给 ns-spec-driven

在人工审批 Retrieval Design Report 和 GraphRAG Process Report 后：

## GraphRAG implementation planning
- Retrieval report: path (approved)
- Process report: path (approved)
- Ontology: entity types / relation types / version id
- Extract stages: units → extract → resolve → persist (edge+evidence+mention) → embed
- Answer shapes: unit | path | filtered set | count | synthesis | document correlation
- Discovery: off | on (archetype + gate)
- Graph query: query_knowledge_graph; max_depth cap; telemetry envelope
- Eval: evidence precision, path accuracy, set completeness, citation faithfulness, refuse-when-empty
- Out of scope for this skill: application source code

停止条件

条件	操作
模式不是 GraphRAG	保持使用 ns-postgres-rag；不构建提取器图
提议将相似度或共现作为存储的边	拒绝
本体尚未锁定	阻止 P2
使用自由图查询语言	拒绝
将另一个向量存储设为默认存储	保持使用 ns-postgres-rag 存储
人工现在就要应用代码	先生成报告；之后仅使用 ns-spec-driven

禁止事项

• 应用语言、框架、供应商、模型 SKU
• 将共现或嵌入距离作为 edge
• 未声明发现范式就将模块化分组作为流水线阶段
• 每条证明对应一行边（应使用逻辑边 + 证据追加）
• 将规范化名称作为类人类型的持久身份
• 将派生的遍历路径持久化为边
• 仅靠沿路径遍历来回答筛选集合或计数问题
• 将发现结果当作事实呈现，或将其写回为边
• 排名后再限制范围
• 将被拒绝的节点作为中间桥接节点
• 每遍历一个图跳就调用一次模型
• 批量扩展时逐节点读取
• 未标注质量等级就索引质量下降的文本
• 未声明确认策略就提交拟议记录
• 缓存键缺少授权上下文或图版本
• 将整份文档倾倒到生成上下文中
• 断言事实时不提供引文
• 向调用方泄露授权失败信息