前言

Graph Text Projection (GTP) 是面向 GPT/Codex 阅读的图查询结果文本投影规范族。GTP Core 是该规范族的核心语言,用于把 Neo4j、RDF 1.2 与 SPARQL 1.2 查询结果投影成稳定的一维文本表面,使语言模型能够读取节点、关系、路径、变量绑定、属性归属、陈述引用和结果完整性。

本书以 GTP Core 为中心,定义围绕 Core surface 的 projection requestAdapter contractSDK public objects、diagnostics and verification requirements。书中的规则面向实现者:读者应能够依据这些规则编写 GTP Core formatter、parser、validator、Neo4j Adapter、RDF 1.2 Adapter、SPARQL 1.2 Adapter、SDK binding 和验证 fixture。

SDK/API 章节规定实现必须满足的开发者表面,不替代语言绑定的完整参考手册。Projection request 和 SDK objects 不属于 GTP Core canonical surface;它们定义 Adapter 和开发者如何请求、验证和消费 GTP Core output。

GTP Core 不替代 Neo4j、Cypher、RDF、SPARQL、Turtle、JSON-LD、SPARQL Results 格式或图可视化语言。GTP Core 也不包含 Pretty Skin。颜色、box drawing、Unicode 图形符号、终端对齐和浏览器图布局属于相邻投影层,不参与 Core 语义。

第一部:问题世界与对象边界

本部定义 GTP 的问题世界、消费者、当前对象、非目标、设计纪律和项目层位。

1. 问题世界

GTP Core 的问题世界由 Codex 环境中的图查询工具、Neo4j 数据源、RDF 1.2/SPARQL 1.2 数据源、SDK/Adapter 实现和 GPT/Codex 消费者共同构成。查询工具从图数据系统取得结果;GPT/Codex 读取这些结果,并在随后的对话中执行解释、核对、归纳、路径追踪、代码生成或文档生成。

该问题世界中的摩擦不来自图数据本身存在,而来自查询结果进入语言模型上下文时的投影方式。机器交换格式能够准确承载查询结果,图形界面能够把查询结果渲染为可视化网络;这些表面并不自动成为适合 GPT/Codex 阅读的文本投影。

1.1. 查询结果消费者

GTP Core 的首要消费者是 GPT/Codex。人类工程师和轻量解析器是次级消费者。这个消费者次序决定了 GTP Core 的核心语义必须成立于一维文本序列中。

GPT/Codex 读取的是 token 序列。它能够稳定利用重复的行级模式、显式关键字、本地引用、括号、赋值、缩进和单行关系表达。它不能可靠依赖跨多行、多列的二维几何对齐来恢复图结构。人类读者凭肉眼追踪屏幕中的线条和排版位置;语言模型不通过这种方式判断关系归属。

轻量解析器是第三类消费者。GTP Core 不是只给模型看的自然语言说明;它的规范表面允许实现者编写 parser,检查 ID 引用、语句类型、属性归属、边方向和视图闭合。解析器不替代 GPT/Codex,但它提供可验证的结构边界。

1.2. Agent-hosted 查询工具

GTP 的主要产品位置是 Agent-hosted graph query tool 的 result surface。该工具调用环境通常能够同时提供 query text、source result 和 declared projection kind。Query text 和 source result 提供投影材料;declared projection kind 提供消费者观察动作。

GTP Core 不把裸 source result 当作完整投影前提。Adapter 也不从 query text + source result 自动猜测消费者观察意图。观察意图必须在 projection request 中以 projection kind 或上层映射后的等价字段进入 Adapter。

1.3. Neo4j 查询结果的投影摩擦

Neo4j 的核心对象包括 node、relationship 和 path。Cypher 查询返回节点、关系、路径、标量、列表、映射和记录。Neo4j relationship 具有方向、类型和属性;path 是节点与关系的有序交替序列。

这些对象进入表格时会失去阅读形状。一个 path 被拆成列或序列后,读者需要重建每一步的真实关系方向和遍历方向。一个 relationship 的属性如果嵌在 JSON 对象中,语言模型需要在多层键名中判断属性属于节点还是关系。一个 RETURN 记录包含多个节点和关系时,表格只显示值的并列关系,不显示它们在图中的拓扑关系。

GTP Core 不改变 Neo4j 的源语义。Neo4j Adapter 负责解释 Neo4j 查询结果;GTP Core 负责提供可读、可验证的一维文本表面。

1.4. RDF/SPARQL 查询结果的投影摩擦

RDF 1.2 使用 subject、predicate、object 三元组表达图。RDF graph 视为由节点和有向弧组成的图。RDF 1.2 引入 triple term,使一个 RDF triple 作为 RDF term 出现在另一个 triple 中。RDF 1.2 的 reification 机制允许一个 reifier 指称一个 triple term,并被其他 triple 继续陈述。

SPARQL 1.2 查询结果形态并不单一。SELECT 返回变量绑定,CONSTRUCT 返回 RDF graph,DESCRIBE 返回 RDF graph,ASK 返回布尔结果。CSV、TSV、JSON 和 XML 等结果格式服务机器交换;它们不是专门为 GPT/Codex 恢复图结构而设计。

RDF/SPARQL 查询结果中的长 IRI、blank node、literal datatype、language tag、triple term、reifier、named graph 和变量绑定都会增加投影复杂度。GTP Core 不直接解释这些 RDF/SPARQL 源语义。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 负责根据本书引用的 W3C RDF 1.2 与 SPARQL 1.2 文档归档源对象,并把需要进入语言模型上下文的结果投影到 GTP Core 表面。

1.5. 表格、交换格式和图形可视化的边界

表格适合显示行记录和标量结果。表格不适合表达路径顺序、关系方向、局部子图、环路和关系属性归属。图查询结果被表格化后,消费者必须在列名和值之间重建图结构。

JSON、XML、CSV、TSV 等交换格式适合程序间传递。它们的键名、嵌套层级、数组结构和序列化细节会占用语言模型上下文,并让消费者在交换结构和图结构之间进行额外转换。

图形可视化适合人眼检查拓扑布局。Graphviz、Mermaid、Neo4j Browser 等表面生成图形;图形布局不是 GPT/Codex 的原生输入。GTP Core 使用文本投影,而不是二维图布局。

1.6. 期望改变

GTP Core 的期望改变是:Neo4j 与 RDF/SPARQL 查询结果进入 GPT/Codex 上下文时,消费者能够直接读取对象类型、关系方向、属性归属、路径步骤、变量绑定、陈述引用和结果完整性,而不需要从表格、交换格式或二维图形布局中重新恢复结构。

该期望改变要求 GTP Core 提供稳定的规范表面、明确的适配器边界、可解析的语句结构和可验证的错误语义。

2. 当前对象与非目标

GTP Core 是 adapter output language。Neo4j Adapter、RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 接收 projection request,解释各自源系统中的 source result,并在 query-based source 中使用 query text 和 declared projection kind 把结果投影为 GTP Core 文本。GTP Core 规定该文本的规范表面、对象边界、视图结构、错误语义和完整性声明。

GTP Core 的首要消费者是 GPT/Codex。GTP Core 的核心语义不依赖颜色、字体、Unicode box drawing、列对齐、二维连线或浏览器图形布局。人类可读性是必要约束;语言模型可读性是主导约束。

2.1. 源承诺

GTP Core 的源承诺包括 Neo4j、RDF 1.2 与 SPARQL 1.2。

Neo4j Adapter 按 Neo4j/Cypher 当前语义解释 node、relationship、path、record、property、label、relationship type、null、list、map 和 scalar。它把这些源对象投影为 GTP Core 中的 node、edge、path、table、match、prop 或 scalar。

RDF 1.2 Adapter 按本书引用的 W3C RDF 1.2 文档解释 RDF term、triple、triple term、reifier、graph 和 dataset。SPARQL 1.2 Adapter 按本书引用的 W3C SPARQL 1.2 文档解释 SPARQL binding、CONSTRUCT graph、DESCRIBE graph 和 ASK result。它们把这些源对象投影为 GTP Core 中的 node、edge、stmt、prop、subgraph、profile、match、table 或 scalar。

Graphviz DOT、Mermaid、Rust diagnostics、Biome 和 Ruff 不是 GTP Core 的源承诺。它们作为符号设计、文本结构、reporter 分层或诊断输出的参考坐标;它们不构成 adapter 目标。

2.2. Core 与 Adapter 的边界

GTP Core 不解释源语言语义。GTP Core 只定义投影文本如何表达 adapter 已经归档的对象。

Adapter 负责源语义归档,并按 declared projection kind 生成对应 view。Neo4j Adapter 负责判断一个返回值是 node、relationship、path、record 还是 scalar。RDF 1.2 Adapter 负责判断一个值是 IRI、blank node、literal、triple term、reifier 或 graph member。SPARQL 1.2 Adapter 负责判断查询结果形态和 binding,并在需要解释 RDF term 时使用 RDF 1.2 Adapter 规则。各 Adapter 的共同职责在 Adapter 合约 中定义,source-specific 规则在 Neo4j AdapterRDF 1.2 AdapterSPARQL 1.2 Adapter 中定义。

GTP Core 负责公共表面。edge E1: N1 -[p]→ N2 表示当前投影视图中的有向关系投影。它不自动声称该关系来自 RDF triple、Neo4j relationship 或其他源系统对象。该判断由 source 声明和对应 adapter 规则提供。

2.3. 非目标

GTP Core 不替代 Neo4j、Cypher、RDF、SPARQL、Turtle、JSON-LD、SPARQL Results JSON、SPARQL CSV/TSV 或任何标准交换格式。

RDF/SPARQL 源语义以本书引用的 W3C RDF 1.2 与 SPARQL 1.2 文档为坐标;这些引用约束 Adapter 归档,不把 GTP Core 变成 RDF 或 SPARQL 的替代规范。

GTP Core 不定义图查询语言。它不执行查询,不优化查询,不描述查询计划,不表达索引选择、成本估计或数据库执行算子。

GTP Core 不做二维图布局。它不计算节点坐标,不最小化交叉边,不绘制跨行连线,不输出浏览器图形。

GTP Core 不包含 Pretty Skin。Pretty Skin 把 Core 渲染为有颜色、边框、Unicode 线条或终端分组的输出;这些表面不参与 Core 语义。

GTP Core 不定义 Agent runtime、tool call envelope、conversation-level evidence address、context packing 或 prompt wrapper。这些对象可以消费 GTP Core text 或 SDK 暴露的 structured Document API,但它们不进入 Core canonical surface。

GTP Core 不保证底层事实正确。它把方向、引用和属性归属暴露为可审查表面;它不能替数据源判断领域事实是否成立。

GTP Core 不承诺语言模型不会出错。它提供低歧义结构和可验证表面;消费者正确性仍需通过解析测试、adapter fixture 和语言模型抽取评估来判断。

2.4. 构成性条件

GTP Core 作为当前对象成立,依赖以下构成性条件。

每个公共表面单位必须声明对象类型。节点、关系、陈述、属性、视图、元信息、诊断和绑定不能依赖自然语言标题或视觉位置来识别。

关系方向必须显式表达。GTP Core 使用单一规范表面表达有向关系,避免同一方向关系出现多种等价写法。

属性必须声明归属者。属性不能依赖缩进、相邻行或上下文猜测归属。

引用必须使用局部 ID。图查询结果中的复用、环路、长标识符和跨段引用通过本地 ID 处理。

视图必须对应消费者动作。profilepathsubgraphmatchtablescalar 是不同阅读任务的投影形态,不是视觉模板。

Projection kind 必须在 Adapter 投影前确定。Adapter 不从裸 source result 或 query text + source result 猜测消费者观察意图。

完整性必须可见。截断、省略、adapter 损失和错误必须进入 metawarningerror 表面,不能隐藏在实现内部。完整性与错误语义在 错误与完整性语义 中定义。

3. 设计纪律

GTP Core 的规则进入规范之前,必须具备判断资格。一个规则能否进入当前对象,取决于它是否回应 Neo4j、RDF 1.2 或 SPARQL 1.2 查询结果中的事实,是否服务 GPT/Codex 的消费动作,是否改变投影规约,是否引入可审查成本,以及是否具有验证方式。

3.1. 事实、需求与规约

Neo4j 查询结果、RDF 1.2 graph/dataset 与 SPARQL 1.2 query result 是 GTP Core 的领域事实来源。GPT/Codex 对查询结果的阅读、解释、核对和推理是期望改变所在。GTP Core 能控制的是投影规约:文本中出现哪些语句、语句如何组合、引用如何建立、错误如何暴露。

GTP Core 不直接改变数据源,也不直接改变语言模型能力。它通过投影结构降低消费者恢复图结构的成本。

Projection kind 是 Adapter 进行投影的上游前提。Query text 和 source result 提供源材料;projection kind 声明消费者动作。缺少 projection kind 时,Adapter 缺少生成特定 view 的判断前提。

3.2. 表面单位准入

GTP Core 的每个表面单位都需要获得消费者行动授权。

node 使消费者能够把局部 ID 与源对象显示项关联。没有 node,关系端点只能使用长 IRI、数据库内部值或自然语言标签,引用不稳定。

edge 使消费者能够在一行内读取 source、predicate 和 target。没有 edge,关系方向必须从表格列名、JSON 嵌套或图形位置中恢复。

stmt 使消费者能够读取可引用陈述。没有 stmt,RDF 1.2 reifier/triple term 相关结构会与普通节点属性或边属性混淆。

prop 使消费者能够判断属性归属。没有 owner 的属性会在节点、关系、陈述或结果之间漂移。

metawarningerror 使消费者能够判断结果完整性和可信范围。没有这些表面,截断和 adapter 损失会被误读为完整事实。

3.3. Adapter 归档纪律

Adapter 是源语言语义的归档位置。Core 不能替 Adapter 判断一个 Neo4j value 或 RDF term 的源语义。

Neo4j relationship property 不能被 Core 自动解释为 RDF reification。RDF reifier 不能被 Core 自动解释为 property graph relationship property。两者可以投影到相似的文本结构,但它们的来源语义由各自 Adapter 说明。

Adapter 必须声明 source。没有 source 的 GTP Core 文档缺少解释前提,消费者无法判断 stmt、literal、ID、relationship property 或 RDF reifier 的来源语义。

Adapter 必须按 declared projection kind 生成对应 view。Adapter 不能把未声明的消费者动作隐藏在实现内部,也不能在 projection kind 与 query/result 不匹配时静默选择另一个 view。

3.4. 过程语汇限制

GTP Core 规范不使用阶段词替代对象边界。规则不能写成“第一版支持”“后续支持”“先做”“默认轻量”。当前对象负责某个结构时,正文说明它回应的事实和消费者动作;当前对象不负责某个结构时,正文把它归档为相邻对象或 adapter 外部职责。

实施计划可以使用阶段安排。规范定义不能使用阶段安排说明对象本体。

autopreferbest effort 和 view guessing 不能替代 projection contract。Projection kind 是请求契约,不是 Adapter 的启发式偏好。

3.5. 引用坐标

引用坐标只在参与判断时出现。

W3C RDF 1.2 文档用于约束 RDF 1.2 Adapter。W3C SPARQL 1.2 文档用于约束 SPARQL 1.2 Adapter。Neo4j/Cypher 文档用于约束 Neo4j Adapter。Graphviz DOT 与 Mermaid 用于说明 、edge label 和文本图语料的参考地位。Rust diagnostics、Biome 和 Ruff 用于说明 reporter 分层和诊断输出的参考地位。参考坐标列于 [_参考资料]

引用不能替代规则。规则必须在 GTP Core 的对象边界内写明。

3.6. 完成声明

GTP Core 的完成声明依赖验证。规范存在不证明实现正确;formatter 能输出文本不证明消费者能正确读取;语言模型一次回答正确不证明投影满足需求。

完成判断至少需要 parser round-trip、projection request fixture、Neo4j fixture、RDF 1.2 fixture、SPARQL 1.2 fixture、错误诊断样例和语言模型抽取评估。验证规则在 验证方法 中定义。

4. 项目层位

本书区分 Core language、Projection request、Adapter contract、SDK/API、Verification and conformance 以及相邻对象。每一层负责不同公共对象。层位边界使 GTP Core 保持可解析的 canonical surface,同时允许上层工具围绕该 surface 构造开发者体验、显示层和 Agent runtime。

4.1. GTP Core language

GTP Core language 定义 canonical text surface。它规定 document structurelexical contract、statement、view、ID scope、Core semantics、error、warning、meta 和 ordering stability

GTP Core document 从 source 声明开始。Projection request、query text、tool call metadata、observation intent、conversation state 和 prompt wrapper 不属于 Core document body。

4.2. Projection request and Adapter contract

Projection request 是 Adapter 执行投影的输入对象。它包含 source、source result、declared projection kind,以及 projection kind 所需的 query text 或其他 source-specific materials。

Adapter 读取 projection request,按源系统规则归档源对象,验证 declared projection kind 是否被 query text、source result 和 projection parameters 支撑,并输出 GTP Core Document 或 diagnostics。Adapter 不从裸 source result 中猜测观察意图。

4.3. SDK/API layer

SDK/API layer 是开发者访问 GTP Core 和 Adapter 的公共表面。它提供 parser、formatter、validator、structured Document API、diagnostics API、projector APIfixture supportlanguage bindings

SDK/API layer 不改变 GTP Core canonical surface。它可以把 GTP Core text 解析为结构化 Document,也可以把合法 Document 格式化为 canonical text。

4.4. Verification and conformance layer

Verification and conformance layer 验证实现是否满足规范。它覆盖 parser round-trip、projection request fixtures、adapter fixtures、diagnostics fixtures、snapshot stability 和 language model extraction evaluation。

同一 source、query text、source result、projection kind 和 projection options 应产生稳定 GTP output。

4.5. 相邻对象

Pretty Skin、Inspector、context packer、Agent runtime、tool call envelope、conversation-level evidence address、prompt wrapper、query execution plan projection 和 graph layout 是相邻对象。它们可以消费 GTP Core text 或 SDK 暴露的 structured Document API。

相邻对象不进入 GTP Core 语义。它们不能改变 Core statement、ID scope、view boundary、diagnostic meaning 或 canonical surface。

第二部:GTP Core 语言规范

本部定义 GTP Core canonical surface、词法、语句、文法、语义、view、错误和完整性表面。

5. 文档结构与作用域

GTP Core 文档由必需 header 和一个或多个 view 构成。Header 声明 source、prefix 和其他适用于其后 view 的解释前提。View 承载 projection request 生成的一个投影表面,并使用 end 显式闭合。

GTP Core 文档不是自然语言段落集合。每个非空行都属于 header、view、section、statement、diagnostic 或闭合标记。实现者可以用行级 parser 读取 GTP Core 文档。

Projection request、query text、tool call metadata、observation intent、context packing instruction 和 evidence address 不属于 GTP Core document body。它们属于 SDK/API、Adapter 输入或上层相邻对象。

Header 出现在第一个 view 之前。Header 包含一个 source 声明和零个或多个 prefix 声明。

source 声明当前文档的源适配器。GTP Core 的源承诺包括 neo4jrdf12sparql12。一个 GTP Core 文档只包含一个 source;混合来源结果由查询工具拆分为多个 GTP Core 文档。

source neo4j

prefix 声明紧凑 IRI 前缀。前缀声明服务 RDF 1.2 Adapter 与 SPARQL 1.2 Adapter,也服务 Neo4j Adapter 生成的显示项。GTP Core 文档中出现 compact IRI term 或 QName predicate 时,对应 prefix 必须在 header 中声明。未声明 prefix 的冒号形式只允许出现在源适配器定义的 bare predicate 或 opaque display term 中。

prefix ex = <http://example.org/>
prefix rdf = <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

Header 不承载查询结果对象。节点、关系、属性、路径步骤和变量绑定必须出现在 view 中。

5.2. View

View 是 GTP Core 的结果投影单位。每个 view 使用 view 关键字开启,并使用 end 闭合。View 内允许出现 view-level meta 语句和该 view 类型允许的 section。

subgraph G1
nodes:
  node N1 <ex:Alice>
end

View 类型包括 profilepathsubgraphmatchtablescalar。每个 view 类型对应一种消费者动作。Projection request 声明 projection kind;Adapter 按该 projection kind 生成对应 view。

5.3. Section

Section 是 view 内部的同类语句分组。Section 名称以冒号结尾。GTP Core 允许的 section 由 view 类型限制。meta 是 view-level 语句,不需要放入 section。

nodes:
  node N1 <ex:Alice>
  node N2 <ex:Bob>
edges:
  edge E1: N1 -[ex:knows]-> N2

Section 只组织语句,不改变语句语义。edge 的方向由 edge 语句本身决定,不由 out:in: 的视觉位置决定。out:in: 只表示 profile view 中相对于 focus node 的分组。

5.4. 作用域

GTP Core 的局部 ID 作用域为单个 view。N1E1S1 等 ID 只在当前 view 内有效。另一个 view 中出现同名 ID 时,它指向另一个局部对象,除非该 view 重新声明相同显示项。

View-local scope 降低语言模型跨远距离维护 ID 表的成本。它也使每个 view 能够被独立复制、测试和解析。

Header 中的 prefix 作用于同一文档内所有 view。Source 声明同样作用于同一文档内所有 view。View 内不重新声明 source。

5.5. 闭合规则

每个 view 必须以 end 闭合。end 标记结束最近打开的 view。GTP Core 不使用缩进或空行闭合 view。

缺少 end 的文档不是完整 GTP Core 文档。Parser 报告 view 未闭合错误。

6. 词法与基本值

GTP Core 的词法使用 ASCII canonical surface。Core 语义不依赖 Unicode 图形符号、颜色、终端列宽或字体渲染。Token、term、predicate、string 和 value 的文本边界由 词法契约 定义。

6.1. 行与空白

GTP Core 是行级文本格式。每条语句占一行。空行只出现在 view 之间,用于人类阅读;空行不表达对象语义。

缩进用于提升扫描性。缩进不承担归属语义。属性归属由 owner ID 表达;关系方向由 edge 语句表达;view 边界由 view 关键字和 end 表达。

Core 输出不产生注释。注释容易让 GPT/Codex 混淆规范表面与解释性文字。解释属于文档,查询结果输出属于 Core。

6.2. ID

ID 是 GTP Core 文档中的局部引用。ID 不等于源数据库持久 ID。

节点 ID 使用 N 加正整数。

N1
N2
N37

关系 ID 使用 E 加正整数。

E1
E2

陈述 ID 使用 S 加正整数。

S1
S2

View ID 使用对应前缀加正整数。G 表示 subgraph,P 表示 path,M 表示 match,R 表示 table 或 scalar result。

G1
P1
M1
R1

ID 由 adapter 分配。Adapter 在同一 view 内保持 ID 唯一。ID 分配保持稳定,使同一输入在相同排序规则下产生相同输出。

6.3. Term

Term 是 GTP Core 中显示源对象或值的表面。Term 的边界规则由 词法契约 定义。

IRI term 使用 angle form。Angle form 内部可以是完整 IRI,也可以是已由 prefix 声明约束的 compact IRI display。

<http://example.org/Alice>
<ex:Alice>

Blank node 使用 RDF blank node 表面。

_:b1

Literal 保留源 lexical form。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 保留 datatype、language tag 和 directional language tag。Neo4j Adapter 保留标量、列表和映射的可读表面。

"Alice"@en
"1912-06-23"^^xsd:date
42
true
null
["Person", "Scientist"]
{name: "Alice", score: 0.98}

List 和 map 值是 value 表面,不是 GTP Core 的结构语句。Parser 把完整 list 或 map 作为单个 value 解析单元保留;源语义由 adapter 解释。List/map 的平衡边界和 row binding 中的 value 分隔规则见 词法契约

6.4. Predicate

Predicate 表示关系标签或属性键。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 可使用 QName 或 IRI。Neo4j Adapter 可使用 relationship type 或 property key。Predicate 的语句内边界由 词法契约 定义。

ex:knows
rdf:type
WORKED_AT
name

Predicate 出现在 edgeprop 语句中。GTP Core 不使用 #predicate 作为 Core 表面,避免与注释、fragment 和私有符号习惯混淆。

6.5. Variable

Variable 用于 match 和 table view 中的查询绑定。Variable 使用问号前缀。

?person
?relationship
?count

Variable 名称来自源查询或 adapter 生成的稳定名称。

7. 词法契约

GTP Core 的词法契约定义 canonical surface 中 token、term、predicate、string 和 value 的文本边界。它服务 parser round-trip、Adapter fixture、诊断表面和 GPT/Codex 行级读取。词法契约不解释源系统数据模型,也不把 RDF、SPARQL、Cypher、JSON、Turtle 或 Neo4j value 的完整词法纳入 Core。

词法契约处理的是 Core 结构如何在一维文本中保持可判定边界。源对象是什么,由 Adapter 归档;源值意味着什么,由源系统语义解释;Core 只规定这些对象进入公共投影表面时,哪些字符形成结构边界,哪些字符保留在 value 内部。

7.1. 行边界

Canonical GTP Core 输出中的每条语句占一行。String、term、list、map 和 diagnostic field 不跨越 structural newline。

源值包含换行时,Adapter 必须选择单行 value surface。该表面必须保留消费者判断源值身份所需的信息,同时不能让源换行产生新的 Core 语句。

Parser 把 newline 解释为当前语句结束。Formatter 不输出多行 string、多行 list 或多行 map。

7.2. 结构分隔符

GTP Core 的结构分隔符包括 space、colon、equals sign、arrow surface、square brackets、braces、angle brackets、double quote 和 comma。分隔符只有在对应结构层位中才承担 Core 语义。

String、angle term、list 和 map 内部的分隔符不改变外层语句结构。Parser 必须在 string state、angle state 和 bracket depth 之外识别 statement-level 分隔符。

7.3. String

String 使用 double-quoted surface。String 从未转义的 double quote 开始,到同一行内下一个未转义的 double quote 结束。

String 内部的 double quote、backslash、newline、tab 和控制字符必须使用 escape surface。Parser 不把 string 内部的 space、colon、equals sign、comma、arrow、ID-like text 或 section-like text 解释为 Core 结构。

Diagnostic messagewhere 使用 String。String 内部文本面向人类和 GPT/Codex,但不参与 Core 结构解析。

message = "edge E2 targets missing ref S1"
where = "subgraph G1 edges"

7.4. Angle term

Angle term 从 < 开始,到同一行内下一个 > 结束。Angle term 内部承载完整 IRI display 或 compact IRI display。

Compact IRI display 中的 prefix 必须由 header 中的 prefix 声明约束。Angle term 不承担 RDF/Turtle 语法解释;它只为 GTP Core 提供一个不被 space、colon 或 slash 破坏的 term boundary。

<http://example.org/Alice>
<ex:Alice>

缺少闭合 > 的 angle term 不是合法 term。Parser 必须把该输入归入词法错误,而不是猜测 term 边界。

7.5. Predicate

Predicate 是 edgeprop 语句中的关系标签或属性键。Edge predicate 由 -[]→ 定界。Prop predicate 由 owner 后的 space 与 ` = ` 前的 space 定界。

Canonical bare predicate 不包含未转义 space。QName predicate 的 prefix 必须可解释。需要承载会破坏 delimiter 的源 predicate 时,Adapter 必须使用 angle predicate 或 source-specific opaque predicate surface,并在 Adapter 规则中声明。

edge E1: N1 -[ex:knows]-> N2
prop N1 rdfs:label = "Alice"@en

Predicate 的源语义由 Adapter 解释。Core 只规定 predicate 在语句中的边界。

7.6. Value

Value 的外层边界由所在语句决定。

propmeta 和 scalar value 语句中的 value 从其 value 起始位置延伸到行尾。

prop N1 metadata = {source: "neo4j", score: 0.98}
meta result.complete = false
value true

row 语句中的 binding value 从 = 后的 space 开始,延伸到下一个 top-level comma 或行尾。String、angle term、list 和 map 内部的 comma 不分隔 row binding。Parser 必须以 string state、angle state 和 bracket depth 判断 top-level comma。

row 1: ?name = "Turing, Alan", ?aliases = ["A. Turing", "Alan Mathison Turing"]

Diagnostic messagewhere 不使用任意 value;它们使用 String。

7.7. List 与 map value

List value 使用 square bracket surface。Map value 使用 brace surface。Core parser 识别其外层平衡边界,并把完整 list 或 map 保留为单个 value surface。

List 和 map 的源语义由 Adapter 解释。Core parser 不把 list/map 内部键、元素或嵌套结构提升为 Core statement。

List/map 内部出现 String、angle term、nested list 或 nested map 时,其内部 delimiter 不改变外层 Core 结构。

prop N1 aliases = ["A. Turing", "Alan Mathison Turing"]
prop N1 metadata = {source: "neo4j", score: 0.98}

List 或 map 中包含需要局部 ID 的图对象时,Adapter 不把该对象藏入 value surface。Projection request 必须声明能够暴露这些图对象的 projection kind,例如 matchsubgraphpath 或多个明确授权的 view。

7.8. RDF literal suffix

RDF literal value 由 quoted lexical form 和可选 literal suffix 组成。Language tag、directional language tag 和 datatype marker 属于同一个 value surface。

"Alice"@en
"1912-06-23"^^xsd:date

Datatype 使用 QName 或 angle term 时,其 prefix 解释遵循 header prefix 规则。Core parser 保留 literal surface;RDF 1.2 Adapter 负责解释 datatype、language tag 和 directional language tag 的源语义。

7.9. Prefix reference

Prefix reference 出现在 compact IRI display 或 QName predicate 中。使用 prefix reference 的 surface 必须能在 header 中找到对应 prefix 声明。

未声明 prefix 的 colon form 只允许出现在源适配器定义的 bare predicate 或 opaque display term 中。Adapter 必须在 source-specific 规则中说明这种 surface 的解释方式。

Parser 对无法解释的 prefix reference 报告词法或 prefix 错误。它不能把未知 prefix 静默当作普通文本。

7.10. 词法错误

不能形成合法 token、String、Angle term、balanced value 或 prefix reference 的文本不是完整 GTP Core 文档。Parser 必须输出 error view 或结构化 parser error。

词法错误不由 formatter 或 parser 静默修复。错误表面应包含稳定 code、message 和 where,使消费者能够判断失败位置。

Core 词法错误使用 GTP010GTP014。错误码含义由 错误与完整性语义 统一定义。

8. 核心语句

GTP Core 的核心语句定义查询结果对象的公共表面。每条语句以对象关键字开头。关键字是语句类型的入口,不是自然语言标题。

8.1. source

source 声明文档的源适配器。

source neo4j
source rdf12
source sparql12

source neo4j 表示其后投影由 Neo4j Adapter 生成。source rdf12 表示其后投影由 RDF 1.2 Adapter 生成。source sparql12 表示其后投影由 SPARQL 1.2 Adapter 生成。

缺少 source 的文档缺少解释前提。规范输出必须包含 source;parser 对缺少 source 的文档报告 GTP006 source-missing

8.2. prefix

prefix 声明紧凑 IRI 前缀。

prefix ex = <http://example.org/>

使用 QName 表面时,对应 prefix 必须可解释。Prefix 声明只定义显示展开关系,不改变源数据。 Prefix reference 的词法边界和未声明 prefix 的错误语义见 词法契约

8.3. node

node 声明当前 view 中的节点投影单位。

node N1 <ex:Alice>

N1 是当前 view 中的局部节点 ID。<ex:Alice> 是节点显示 term。Node 语句建立 ID 与显示 term 的映射。Node 属性不写入 node 语句;属性使用 prop 语句表达。

8.4. edge

edge 声明当前 view 中的有向关系投影单位。

edge E1: N1 -[ex:knows]-> N2

E1 是当前 view 中的局部关系 ID。N1 是 source。ex:knows 是 predicate 或 relationship type。N2 是 target。 是唯一 directed edge canonical surface。 Predicate 的边界由 -[]→ 定界;完整规则见 词法契约

GTP Core 不使用反向 edge 表面表达同一关系。入边仍按真实方向书写,并由 view section 说明它相对于 focus node 的位置。

8.5. stmt

stmt 声明当前 view 中的可引用陈述投影单位。

stmt S1: N4 reifies E1

S1 是局部 statement ID。N4 是表示源陈述载体的节点投影。E1 是被该 statement 投影关联的关系投影。

source rdf12 下,RDF 1.2 Adapter 使用 stmt 表达 RDF 1.2 reifier 与被 reify triple 的投影关系。在 source sparql12 下,SPARQL 1.2 Adapter 通过 RDF 1.2 Adapter 规则生成同类 stmt 表面。在 source neo4j 下,普通 relationship property 不产生 stmt;Neo4j Adapter 仅在查询结果需要把 relationship value 作为可引用对象时使用 stmt

8.6. prop

prop 声明属性投影。

prop N1 rdfs:label = "Alice"@en
prop E1 since = 2020
prop S1 ex:confidence = 0.93

prop 的第一个参数是 owner。Owner 是 node、edge、statement、view 或 result 的局部 ID。属性归属由 owner ID 决定,不由缩进或相邻语句决定。 prop value 的边界由 ` = ` 后的位置和行尾决定;row binding 中的 value 分隔规则见 词法契约

8.7. meta

meta 声明投影完整性、限制或生成条件。meta 是 view-level 语句,出现在 view header 之后、section 之前或 section 之间。

meta result.complete = false
meta out.count = 327
meta out.shown = 50

meta 不是数据源事实。它描述投影结果本身的状态。消费者必须把 meta result.complete = false 解释为结果不完整,而不是图中存在一个名为 result.complete 的属性。完整性键的解释规则见 错误与完整性语义

8.8. warning

warning 开启非致命诊断 view。

warning GTP009 truncated-result
message = "out edges limited to 50 of 327"
where = "profile N1 out"
end

Warning 改变消费者对结果完整性的判断。Warning 不阻止文档被读取。Warning 使用 end 闭合,不出现在其他 view 的 section 内。

8.9. error

error 开启致命诊断 view。

error GTP001 unknown-ref
message = "edge E2 targets missing ref S1"
where = "edge E2"
end

Error 表示投影无法作为完整 GTP Core 结果使用。Parser、formatter 或 adapter 输出 error view 作为失败表面。Error 使用 end 闭合,不出现在其他 view 的 section 内。

9. 文法

本章给出 GTP Core 的抽象文法。文法用于实现 parser 和 formatter;解释规则仍由对象章节和语义章节定义。TermPredicateValueString 的文本边界由 词法契约 定义。

Document      ::= Header View+
Header        ::= SourceDecl (PrefixDecl | BlankLine)*

SourceDecl    ::= "source" Space SourceName Newline
PrefixDecl    ::= "prefix" Space PrefixName Space "=" Space IRI Newline

View          ::= ProfileView
                | PathView
                | SubgraphView
                | MatchView
                | TableView
                | ScalarView
                | DiagnosticView

ProfileView   ::= "profile" Space NodeID Space Term Newline
                  ViewBody*
                  "end" Newline

PathView      ::= "path" Space PathID Space "from" Space Ref Space "to" Space Ref Newline
                  PathBody
                  "end" Newline

SubgraphView  ::= "subgraph" Space GraphID Newline
                  ViewBody*
                  "end" Newline

MatchView     ::= "match" Space MatchID Newline
                  MatchBody
                  "end" Newline

TableView     ::= "table" Space ResultID Newline
                  (Row | MetaStmt)+
                  "end" Newline

ScalarView    ::= "scalar" Space ResultID Newline
                  MetaStmt*
                  "value" Space Value Newline
                  "end" Newline

DiagnosticView ::= ("warning" | "error") Space Code Space DiagnosticName Newline
                   DiagnosticBody
                   "end" Newline

ViewBody      ::= Section | MetaStmt
Section       ::= SectionName ":" Newline Statement+

Statement     ::= NodeStmt | EdgeStmt | StmtStmt | PropStmt

NodeStmt      ::= Indent "node" Space NodeID Space Term Newline
EdgeStmt      ::= Indent "edge" Space EdgeID ":" Space Ref Space "-[" Predicate "]->" Space Ref Newline
StmtStmt      ::= Indent "stmt" Space StmtID ":" Space NodeID Space "reifies" Space EdgeID Newline
PropStmt      ::= Indent "prop" Space OwnerRef Space Predicate Space "=" Space Value Newline
MetaStmt      ::= "meta" Space MetaKey Space "=" Space Value Newline

PathBody      ::= (PathStep | PathVia | Section | MetaStmt)+
PathStep      ::= "step" Space Integer ":" Space "node" Space NodeID (Space Term)? Newline
PathVia       ::= "via" Space EdgeID ":" Space NodeID Space "-[" Predicate "]->" Space Ref Space Direction Newline
Direction     ::= "forward" | "reverse"

MatchBody     ::= MetaStmt* PatternSection (MatchObjectSection | MetaStmt)* ResultSection+
PatternSection ::= "pattern:" Newline PatternStmt+
MatchObjectSection ::= Section
PatternStmt   ::= Indent "edge" Space Variable ":" Space VarOrRef Space "-[" Predicate "]->" Space VarOrRef Newline
                | Indent "prop" Space VarOrRef Space Predicate Space "=" Space VarOrValue Newline

ResultSection ::= "result" Space Integer ":" Newline Binding+
Binding       ::= Indent Variable Space "=" Space BindingValue Newline

Row           ::= "row" Space Integer ":" Space RowBinding ("," Space RowBinding)* Newline
RowBinding    ::= Variable Space "=" Space BindingValue

DiagnosticBody ::= (MessageLine | WhereLine | MetaStmt)*
MessageLine   ::= "message" Space "=" Space String Newline
WhereLine     ::= "where" Space "=" Space String Newline

Ref           ::= NodeID | StmtID | ViewID | Term
OwnerRef      ::= NodeID | EdgeID | StmtID | ViewID
BindingValue  ::= Ref | EdgeID | Value
VarOrRef      ::= Variable | Ref
VarOrValue    ::= Variable | Value

9.1. 文法解释

Ref 不包含 EdgeID。关系 target 需要引用可陈述关系时,adapter 使用 stmt 建立 StmtID,再把 StmtID 用作 target。BindingValue 单独允许 EdgeID,因为 match result 可以把关系变量绑定到当前 view 中已声明的 edge。prop 的 owner 使用 OwnerRefOwnerRef 包含 EdgeID,因为 Neo4j relationship property 和其他关系属性需要以 edge 作为属性 owner。

StmtStmt 的 reifier 位置使用 NodeID。该限制保留 RDF 1.2 reifier 作为资源的投影形态,也避免把 edge ID 直接冒充可陈述对象。需要引用关系陈述时,adapter 先声明 stmt,再引用 StmtID

MetaStmt 是 view-level 语句。它不属于 nodes:edges:props: 或其他 section。该规则使完整性声明与源对象声明分离。

PathBody 允许 Section,因为 path view 可以包含 path 中涉及的 node、edge、prop 或 statement 声明。stepvia 表达路径顺序;section 表达补充对象表。

MatchBody 允许 nodes:edges:statements:props: section,因为 match binding 可以绑定到当前 view 中声明的局部对象。

DiagnosticView 使用 end 闭合,使 warning 和 error 与普通 view 拥有相同边界规则。

文法不定义源语言语义。source 声明和 adapter 章节定义源对象如何进入这些语句。源语义归档职责见 Adapter 合约

10. Core 语义

GTP Core 的语义是投影语义。它描述文本表面如何建立当前 view 内的引用、关系、属性、陈述、完整性和诊断。它不替源语言定义数据模型。

10.1. ID 绑定

nodeedgestmt 语句建立局部 ID 绑定。ID 绑定只在当前 view 内有效。重复 ID 是错误。

node N1 <ex:Alice>
edge E1: N1 -[ex:knows]-> N2

上例中,N1 由 node 语句绑定。E1 由 edge 语句绑定。N2 必须在当前 view 中由 node 语句绑定,或者由 adapter 规则允许作为前向引用并在 view 结束前声明。

10.2. 关系方向

edge 语句表达真实投影方向。N1 -[ex:knows]→ N2 表示该投影关系从 N1 指向 N2in:out: section 不改变该方向。

Profile view 中的入边必须仍以真实方向书写。

in:
  edge E2: N3 -[ex:namedAfter]-> N1

该语句表示 N3 指向 focus node N1。它不使用反向箭头表面。

10.3. Statement 语义

stmt 语句把一个可引用陈述投影单位与一个关系投影关联起来。

stmt S1: N4 reifies E1

S1 是 statement projection ID。N4 是代表源系统中可陈述对象的 node projection。E1 是被该对象 reify 或指称的关系投影。

在 RDF 1.2 Adapter 中,N4 reifies E1 对应 RDF 1.2 reifier 与 triple term 的投影关系。SPARQL 1.2 Adapter 在投影 RDF term 或 graph result 时使用同一 RDF 1.2 归档规则。在 Neo4j Adapter 中,普通 relationship property 不产生 stmt;Neo4j Adapter 只有在查询结果需要把 relationship value 作为可引用对象时使用 stmt

10.4. 属性归属

prop 的 owner 决定属性归属。

prop N1 rdfs:label = "Alice"@en
prop E1 since = 2020
prop S1 ex:confidence = 0.93

这些语句分别把属性归属于 node、edge 和 statement。缩进、section 名称和相邻语句不改变 owner。

10.5. 完整性语义

meta 语句描述投影状态。它不描述源图事实。

meta result.complete = false
meta out.count = 327
meta out.shown = 50

消费者读取 result.complete = false 后,不能把当前 view 当作完整查询结果。out.countout.shown 描述投影范围,而不是图中的关系。

10.6. 诊断语义

warning 表示投影可读但存在限制。error 表示投影不可作为完整结果使用。

Warning 和 error 的 message 面向人类与语言模型;where 指向产生诊断的投影位置。诊断不改变源数据,只改变消费者对当前投影的信任范围。

10.7. 源语义边界

source 声明决定 adapter 解释规则。相同 Core 表面在不同 source 下可来自不同源对象。

source neo4j 下,prop E1 since = 2020 表示 Neo4j Adapter 投影的 relationship property。

source rdf12 下,prop N1 rdfs:label = "Alice"@en 表示 RDF Adapter 将 literal-valued triple 投影为 node property 表面。该投影不把 RDF graph 改写为 property graph;它只为消费者提供更直接的阅读表面。

11. View 语义与 Projection Kind

View 是消费者动作的投影结构。Projection request 使用 projection kind 声明当前 source result 应进入哪一种 view。Adapter 按 declared projection kind 生成对应 view,并验证 query text、source result 和 projection parameters 是否支撑该 view。

GTP Core 定义六种 view:profilepathsubgraphmatchtablescalar

Projection kind 不是偏好、启发式提示或 fallback 顺序。缺少 projection kind 时,Adapter input 不足以生成规范投影。Projection kind 与 query text 或 source result 不匹配时,Adapter 报告 diagnostics。

11.1. profile

profile projection kind 服务焦点节点阅读。消费者动作是理解一个节点的标识、属性、出边、入边和邻居摘要。

profile 需要 focus node、focus term 或 focus variable。Adapter 无法唯一确定 focus 时报告 diagnostics。

11.2. path

path projection kind 服务路径阅读。消费者动作是按顺序追踪节点与关系,判断每一步的真实边方向和遍历方向。

path 需要 path value、path variable 或 source-specific path result。结果中没有可投影 path 时,Adapter 报告 diagnostics。

11.3. subgraph

subgraph projection kind 服务局部网络阅读。消费者动作是理解一组节点、关系、陈述和属性组成的局部图,包括环路、复用和交叉引用。

subgraph 需要可归档为局部图的 source objects,例如 node/relationship collection、RDF graph、dataset fragment 或 source-specific graph result。

11.4. match

match projection kind 服务模式匹配阅读。消费者动作是理解一个图模式及其一组变量绑定。

match 需要 query pattern 或等价 pattern source,以及 result bindings。无法获得 pattern 时,Adapter 报告 diagnostics。

11.5. table

table projection kind 服务普通记录阅读。消费者动作是读取一组行和列,而不需要恢复图拓扑。

聚合结果、分组统计、literal-only SELECT 或 Cypher scalar RETURN 可以支撑 declared table projection。

11.6. scalar

scalar projection kind 服务单值阅读。消费者动作是读取一个布尔值、计数值或单个标量结果。

SPARQL ASK、单值 count、exists-like 查询或只返回一个 scalar 的 Neo4j 查询可以支撑 declared scalar projection。

11.7. Projection mismatch

同一 query text 和 source result 可能支撑多个消费者动作。Adapter 不从这些材料猜测当前动作。Projection request 必须声明 projection kind。

Declared projection kind 与 query text、source result 或 required parameters 不一致时,Adapter 必须报告 diagnostics。Adapter 不得静默选择另一个 view,不得 fallback 到 table,也不得把 mismatch 伪装为空结果。

同一 projection request 可以输出多个同 kind view,例如多条 path result 对应多个 path view。一个 GTP Core 文档包含多个 view kind 时,request 必须显式包含多个 projection entries 或等价 source-specific request structure。每个 view 独立闭合,拥有自己的 ID scope。

12. Profile View

profile view 以一个 focus node 为中心,投影该节点的属性、出边、入边和相关节点声明。

profile N1 <ex:Alan_Turing>
props:
  prop N1 rdf:type = <ex:Scientist>
  prop N1 ex:birthDate = "1912-06-23"^^xsd:date
out:
  edge E1: N1 -[ex:invented]-> N2
in:
  edge E2: N3 -[ex:namedAfter]-> N1
nodes:
  node N1 <ex:Alan_Turing>
  node N2 <ex:Turing_Machine>
  node N3 <ex:ACM_Turing_Award>
end

12.1. Focus node

Profile header 声明 focus node。

profile N1 <ex:Alan_Turing>

Header 中的 N1 必须在 nodes: section 中声明。Header term 与 node statement 的 term 应一致。

12.2. props

props: section 包含归属于 focus node 的属性投影。Neo4j Adapter 把 node properties 投影为 prop N1 …​。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 把适合属性阅读的 literal-valued triples 投影为 prop N1 …​

Profile view 中的 props: 不承载关系属性。关系属性必须使用对应 edge 或 statement owner。

12.3. out

out: section 包含 source 为 focus node 的关系。

out:
  edge E1: N1 -[ex:invented]-> N2

out: 不改变 edge 语义。它只说明这些 edge 从 focus node 出发。

12.4. in

in: section 包含 target 为 focus node 的关系。入边仍按真实方向书写。

in:
  edge E2: N3 -[ex:namedAfter]-> N1

GTP Core 不使用反向箭头表面表达入边。该规则避免消费者把 predicate 的 subject/object 方向读反。

12.5. nodes

nodes: section 声明 profile 中出现的节点 ID。Focus node、出边 target 和入边 source 都必须在 nodes: 中声明。

12.6. statements

statements: section 声明与当前 profile 相关的可引用陈述投影。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 在 profile 中需要表达 reifier 与被 reify triple 的关系时使用该 section。

statements:
  stmt S1: N4 reifies E1

statements: 不改变 focus node。它只为 profile 中出现的 stmt ID 建立局部绑定。

Adapter 省略未显示邻居的属性时,必须通过 metawarning 声明省略行为。

12.7. 截断

Profile view 容易遇到高出度或高入度节点。Adapter 限制边数时,必须输出完整性信息。

meta out.count = 327
meta out.shown = 50
meta result.complete = false

消费者看到 result.complete = false 后,不能把当前 profile 解释为节点的完整邻域。

13. Path View

path view 投影节点与关系的有序行走。它同时表达真实关系方向和路径遍历方向。

path P1 from N1 to N4
step 0: node N1 <ex:Alice>
via E1: N1 -[ex:knows]-> N2 forward
step 1: node N2 <ex:Bob>
via E2: N2 -[ex:worksAt]-> N3 forward
step 2: node N3 <ex:Lab>
via E3: N4 -[ex:memberOf]-> N3 reverse
step 3: node N4 <ex:Carol>
end

Path view 中由 step 声明的 node ID 与由 via 声明的 edge ID 具有绑定效力。补充 props:statements: section 引用这些 ID 时,不需要重复声明相同 node 或 edge。

13.1. Header

Path header 声明 path ID、起点和终点。

path P1 from N1 to N4

fromto 表示遍历序列的起点和终点。它们不改变任何 edge 的真实方向。

13.2. Step

step 语句声明路径中的节点位置。Step index 从 0 开始,按路径顺序递增。

step 2: node N3 <ex:Lab>

Step index 是路径坐标。消费者可以用它回答“第几步发生反向遍历”或“某节点位于路径第几步”。

13.3. Via

via 语句声明相邻 step 之间使用的关系。

via E3: N4 -[ex:memberOf]-> N3 reverse

Edge expression 表示真实关系方向。forward 表示路径行走方向与 edge 方向一致。reverse 表示路径行走方向与 edge 方向相反。

reverse 不改变 edge。它只描述 path traversal。

13.4. Path 中的属性

Path view 可以包含 props: section,用于声明路径中 node、edge 或 statement 的属性。

props:
  prop E1 since = 2020
  prop E3 confidence = 0.87

属性归属仍由 owner ID 决定。

13.5. 多路径结果

一个查询返回多条路径时,Adapter 输出多个 path view,或在 match view 中绑定多个 path ID。每个 path view 拥有独立 ID scope。

14. Subgraph View

subgraph view 投影局部图网络。它适合包含多个节点、关系、陈述、属性、环路和交叉引用的查询结果。

subgraph G1
nodes:
  node N1 <ex:Alan_Turing>
  node N2 <ex:Bletchley_Park>
  node N3 <ex:Winston_Churchill>
  node N4 <ex:employment_1939>
edges:
  edge E1: N1 -[ex:workedAt]-> N2
  edge E2: N3 -[ex:authorized]-> N4
statements:
  stmt S1: N4 reifies E1
props:
  prop N4 ex:startYear = 1939
end

14.1. 节点与关系分离

Subgraph view 不嵌套展开节点。所有节点在 nodes: 中声明,所有关系在 edges: 中声明。环路和复用通过 ID 引用表达。

这种结构避免把图伪装成树。图中同一节点出现多次时,输出只声明一次 node,并在 edge 中引用其 ID。

14.2. Statements

statements: section 声明可引用陈述投影。RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 使用该 section 表达 RDF 1.2 reifier 与被 reify triple 的投影关系。

statements:
  stmt S1: N4 reifies E1

N4 是当前 view 中的 node。E1 是当前 view 中的 edge。S1 是 statement projection ID。

14.3. Properties

props: section 可包含 node、edge 或 statement 的属性。

props:
  prop N1 rdfs:label = "Alan Turing"@en
  prop E1 role = "cryptanalyst"
  prop S1 ex:confidence = 0.93

Adapter 必须按源语义决定属性 owner。Core 不根据 section 位置推断 owner。

14.4. 完整性

Subgraph view 常由 CONSTRUCT、DESCRIBE 或局部网络查询产生。Adapter 如果限制节点数、边数、属性数或 statement 数,必须输出 metawarning

meta nodes.shown = 100
meta edges.shown = 250
meta result.complete = false

15. Match View

match view 投影图模式和结果绑定。Declared match projection 适合 SPARQL SELECT、Cypher MATCH …​ RETURN 和 motif 查询结果。

match M1
pattern:
  edge ?employmentEdge: ?employee -[ex:employedBy]-> ?employer
  edge ?authorization: ?guarantor -[ex:authorized]-> ?employment
nodes:
  node N1 <ex:Alan_Turing>
  node N2 <ex:MI6>
  node N3 <ex:Winston_Churchill>
  node N4 <ex:employment_1939>
edges:
  edge E1: N1 -[ex:employedBy]-> N2
  edge E2: N3 -[ex:authorized]-> N4
statements:
  stmt S1: N4 reifies E1
result 1:
  ?employee = N1
  ?employer = N2
  ?guarantor = N3
  ?employment = N4
  ?employmentEdge = E1
  ?authorization = E2
end

15.1. Pattern

pattern: section 描述结果绑定对应的图形状。Pattern 中的变量使用 ? 前缀。

Pattern 不是源查询的完整语法。它是结果解释模板。Adapter 不在 pattern 中投影 FILTER、ORDER、LIMIT 等查询操作;这些操作影响结果完整性或排序时,必须通过 metawarning 声明。

15.2. Result

result n: section 声明第 n 个匹配结果。每行 binding 使用 ?var = value

Binding value 的取值域包括 node ID、edge ID、statement ID、literal、IRI、list 和 map。绑定值对应当前 view 中已声明对象时,Adapter 必须绑定到局部 ID,使消费者可以继续追踪对象。

当 binding 对应 RDF reifier resource 时,Adapter 绑定该 resource 的 node projection。Statement projection ID 表达 reifier 与被 reify edge 的投影关系,不替代 source binding。

Match view 在 pattern:result 之间允许声明 nodes:edges:statements:props: section。这些 section 为 result binding 提供局部对象表。Binding 不得在同一行重复声明对象 term。

15.3. Match 与 Table 的区别

match 用于结果行对应某个图模式的情况。table 用于普通记录、聚合、统计或 literal-only 结果。

如果 projection request 声明 table,并且查询返回 ?person ?project ?score 这类不需要恢复图模式的记录,Adapter 输出 table。如果 projection request 声明 match,并且 query pattern 与 result bindings 支撑 ?a -[?r]→ ?b 这类图模式阅读,Adapter 输出 match

15.4. 多模式结果

一个查询结果包含多个不同模式时,Adapter 输出多个 match view,或把模式差异明确放入 pattern:。同一个 match view 中的所有 result 必须满足同一 pattern。

16. Table 与 Scalar View

tablescalar view 投影非拓扑查询结果。它们防止普通记录或单值结果被强行伪装成图结构。

16.1. Table View

table view 表示一组记录。

table R1
row 1: ?type = <ex:Scientist>, ?count = 42
row 2: ?type = <ex:Engineer>, ?count = 17
end

Table row 使用变量绑定表面。Row 不表达图关系。若行内变量之间存在需要消费者恢复的图模式,projection request 应声明 match projection kind。

table view 允许 view-level meta。空结果使用 meta result.empty = true 表达。

16.2. Scalar View

scalar view 表示单个结果值。

scalar R2
value true
end

scalar view 允许 view-level meta 出现在 value 之前。

SPARQL ASK、单值 count、exists-like 查询和只返回一个标量的 Cypher 查询可以支撑 declared scalar projection。

16.3. 聚合结果

聚合结果可以支撑 declared tablescalar projection。如果聚合按组返回多行,projection request 声明 table。如果聚合返回单值,projection request 声明 scalar

scalar R3
value 42
end

16.4. 空结果

空结果必须显式表示。

table R4
meta result.empty = true
end

空结果不是缺失输出。消费者看到 result.empty = true 后,应理解查询成功但没有结果行。

17. 错误与完整性语义

GTP Core 的错误与完整性语义用于限制消费者对投影结果的信任范围。查询结果不完整、源语义未投影、引用损坏或语法错误时,输出必须显式暴露这些状态。

17.1. meta result.complete

meta result.complete 表示当前 view 是否完整覆盖 Adapter 所声明的结果范围。

meta result.complete = true
meta result.complete = false

false 表示消费者不能把当前 view 当作完整结果。Adapter 必须同时说明限制来源,例如 shown/count、limit、paging 或 source omission。

17.2. 截断

截断是非致命完整性限制。Adapter 截断节点、关系、属性、路径或行记录时,必须输出 metawarning

meta edges.count = 327
meta edges.shown = 50
meta result.complete = false

17.3. Warning

Warning 表示当前 view 可读,但存在影响解释的限制。

warning GTP009 truncated-result
message = "edges limited to 50 of 327"
where = "subgraph G1 edges"
end

Warning 不阻止消费者继续读取结果。消费者必须把 warning 纳入回答范围。

17.4. Error

Error 表示当前投影无法作为完整 GTP Core 结果使用。

error GTP001 unknown-ref
message = "edge E2 targets missing ref S1"
where = "edge E2"
end

Error view 是查询工具失败输出或 parser 对无效文档的诊断输出。

17.5. 错误码

GTP001 unknown-ref

语句引用了当前 view 中未声明的 ID。

GTP002 duplicate-id

同一 view 内重复声明同一 ID。

GTP003 invalid-edge-surface

edge 语句不符合 edge E1: N1 -[predicate]→ N2

GTP004 prop-owner-missing

prop owner 不存在或无法解释。

GTP005 view-missing-end

View 未使用 end 闭合。

GTP006 source-missing

文档缺少 source 声明。

GTP007 adapter-loss

Adapter 发现源语义无法完整投影。

GTP008 unsupported-source-feature

源结果包含当前 Adapter 合约外的对象。

GTP009 truncated-result

结果被截断或分页。

GTP010 invalid-token

输入包含不能进入当前语句位置的 token。

GTP011 unterminated-string

String 缺少同一行内的闭合 double quote。

GTP012 unterminated-angle-term

Angle term 缺少同一行内的闭合 >

GTP013 unbalanced-value-surface

List、map 或 nested value surface 的 bracket/brace 不平衡。

GTP014 invalid-prefix-ref

Compact IRI display 或 QName predicate 使用了无法解释的 prefix reference。

Adapter 允许定义 source-specific 错误码。Source-specific 错误码不得覆盖 Core 错误码含义。

17.6. Projection request diagnostics

Projection request diagnostics 表示 Adapter 无法按 declared projection kind 生成对应 view。

GTP015 projection-kind-missing

Projection request 缺少 projection kind。调用者必须补充 projection kind 或由上层 observation intent 映射出 projection kind。

GTP016 projection-result-mismatch

Declared projection kind 与 query text 或 source result 不兼容。调用者必须修改 projection kind 或修改查询。

GTP017 projection-parameter-missing

Projection kind 所需参数缺失,例如 profile focus、path variable 或 pattern source。

GTP018 projection-focus-ambiguous

Profile projection 无法唯一确定 focus。调用者必须声明 focus。

GTP019 projection-pattern-unavailable

Match projection 需要 pattern,但 query text 或 query parse result 不可用。

GTP020 projection-path-unavailable

Path projection 需要 path value 或可明确恢复的 path result,但 source result 不提供该对象。

Projection request diagnostics 可以作为 error view 输出,也可以作为 SDK structured diagnostics 返回。它们不得被静默修复。

18. 排序、稳定性与快照

GTP Core 输出进入 GPT/Codex 上下文,也进入测试 fixture 和快照。相同 source、query text、source result、projection kind 和 projection options 产生不稳定输出会增加审查成本,并使语言模型在重复上下文中读取不同 ID。

18.1. 稳定 ID 分配

Adapter 按稳定顺序分配局部 ID。稳定顺序来自源结果顺序、查询工具排序规则或 canonical 排序规则。Adapter 必须在自身规范中声明使用哪一种。

同一 view 内,先出现的节点获得较小 NodeID。先出现的关系获得较小 EdgeID。该规则只在 Adapter 未声明更强排序时使用。

18.2. Section 顺序

同一 view 类型使用稳定 section 顺序。

Profile view section 顺序:

props:
out:
in:
nodes:
statements:

Profile view 中的 view-level meta 不写成 meta: section。约束整个 view 的 meta 出现在第一个 section 之前;约束局部分组的 meta 出现在被约束 section 之前或之后,但不得破坏 section 内语句连续性。

Subgraph view section 顺序:

nodes:
edges:
statements:
props:

Subgraph view 中的 view-level meta 遵循同一规则,不作为 section 名称出现。

Path view 顺序由 path 步骤决定。补充 section 出现在 path steps 之后。

18.3. 保留源顺序

当源系统返回有意义顺序时,Adapter 保留源顺序。Path step 顺序、SPARQL ordered result、Cypher ordered result 都属于有意义顺序。

当源顺序无意义或不稳定时,Adapter 使用 canonical 排序。Canonical 排序按显示 term、predicate、source ID、target ID 或 property key 组合排序。

18.4. 快照测试

GTP Core 实现使用快照测试验证输出稳定性。快照测试不替代语义测试,但它能暴露 ID 分配、section 顺序、属性排序和诊断输出的漂移。

快照输入必须记录 projection kind。快照内容必须包含 source、view、node、edge、prop、stmt、meta 和 warning/error 表面。缺少这些表面的快照不能验证完整投影。

第三部:投影请求与 Adapter 合约

本部定义 projection request、projection kind、Adapter 输入职责和 source-specific projection rules。

19. Projection Request

Projection request 是 Adapter 生成 GTP Core Document 的输入边界。它声明当前源结果应被投影成哪一种 GTP Core view,并提供生成该 view 所需的 source result、query text 或其他 source-specific materials 以及投影参数。

Projection request 不属于 GTP Core canonical surface。它属于 SDK/API 与 Adapter contract 层。

19.1. 必需字段

Projection request 必须包含 source、source result 和 projection kind。Query-based source 的 projection request 还必须包含 query text。某些 projection kind 需要 focus、path variable、pattern source 或其他 projection parameters。

source

声明源适配器。当前源承诺包括 neo4jrdf12sparql12

source result

源系统返回或提供的结果对象。Source result 提供 Adapter 归档 node、edge、statement、property、binding、table row 或 scalar value 所需的源对象和值。Neo4j 和 SPARQL projection request 的 source result 是 query result;RDF 1.2 projection request 的 source result 可以是 RDF graph 或 dataset。

projection kind

声明 source result 应投影为哪一种 GTP Core view。Projection kind 是请求契约,不是偏好、启发式提示或 fallback 顺序。

query text

Query-based source 的源查询原文,例如 Cypher 或 SPARQL。Query text 提供 variable、RETURN item、path variable、pattern、prefix、query form、CONSTRUCT template 和 DESCRIBE target 等投影材料。Direct RDF graph projection 可以没有 query text;需要 pattern、focus 或 query form 的 projection kind 必须提供等价 source-specific material。

19.2. Projection kind

Projection kind 是闭合枚举。当前取值与 GTP Core view 类型一致:

  • profile

  • path

  • subgraph

  • match

  • table

  • scalar

Adapter 必须按 declared projection kind 生成对应 view,或在 query text、source result 或 projection parameters 不支撑该 projection kind 时输出 diagnostics。

19.3. 条件参数

某些 projection kind 需要附加参数。

profile

需要 focus node、focus term 或 focus variable。无法唯一确定 focus 时,Adapter 报告 projection focus diagnostic。

path

需要 path value、path variable 或 source-specific path result。结果中没有可投影 path 时,Adapter 报告 path unavailable diagnostic。

match

需要 query pattern 或等价 pattern source,以及 result bindings。无法获得 pattern 时,Adapter 报告 pattern unavailable diagnostic。

subgraph

需要可归档为局部图的 node、edge、statement、RDF graph、dataset fragment 或 source-specific graph result。

table

用于普通 record、aggregate、statistics、literal-only rows 或不需要恢复 graph topology 的记录。

scalar

用于 ASK result、single count、exists-like result 或单个 scalar value。

19.4. Query text and source result

Query text 和 source result 是投影材料。它们帮助 Adapter 构造和验证 declared projection kind。

Query text 和 source result 不替代 projection kind。Adapter 不把裸 source result 或 query text + source result 当作消费者观察意图的充分来源。

19.5. Mismatch

Projection kind 与 query text、source result 或 required parameters 不一致时,Adapter 必须输出 diagnostics。Adapter 不得静默选择另一个 view,不得 fallback 到 table,也不得把 mismatch 伪装成 empty result。

19.6. Observation intent

Agent-facing tool schema 可以使用 observation intent 表达消费者动作。Observation intent 可以由工具层映射为 projection kind。

Observation intent 不属于 GTP Core canonical surface。Adapter 接收 projection request 时,projection kind 必须已经确定。

20. Adapter 合约

Adapter 是 projection request 到 GTP Core 的语义入口。Adapter 读取 source、source result、declared projection kind、projection parameters,以及 query-based source 所需的 query text,按源系统标准解释对象,按 declared projection kind 生成对应 view,分配局部 ID,并输出规范表面或 diagnostics。

GTP Core 不替 Adapter 解释源语义。Adapter 不把源语义隐含在实现内部。源对象进入投影时,Adapter 必须使消费者能够判断对象类型、引用、方向、属性归属和完整性。

20.1. 输入职责

Adapter 接收 projection request。Projection request 至少包含 source、source result 和 declared projection kind;query-based source 还必须包含 query text。Neo4j Adapter 接收 Neo4j/Cypher query text 与 result。RDF 1.2 Adapter 接收 RDF graph 或 RDF dataset 以及 projection kind。SPARQL 1.2 Adapter 接收 SPARQL query text 与 query result,并在需要解释 RDF term、graph 或 dataset 时调用 RDF 1.2 Adapter 的归档规则。

Adapter 必须知道结果来源和 declared projection kind。缺少 source 或 projection kind 的 request 不能生成规范 GTP Core 文档。

20.2. 归档职责

Adapter 负责把源对象归档为 GTP Core 可投影对象。

Neo4j Adapter 归档 node、relationship、path、record、scalar、list、map、null、label、relationship type 和 property。

RDF 1.2 Adapter 归档 IRI、blank node、literal、triple、triple term、reifier、graph 和 dataset。SPARQL 1.2 Adapter 归档 SELECT binding、CONSTRUCT graph、DESCRIBE graph、ASK result 和 scalar/table result。

归档不是转换为通用图本体。归档只决定当前投影中哪些源对象进入 node、edge、stmt、prop、binding 或 meta。

20.3. Projection fulfillment responsibility

Adapter 按 projection request 中声明的 projection kind 生成对应 view。Projection kind 与 view 的关系在 View 语义与 Projection KindProjection Request 中定义。

节点邻域由 profile projection kind 表达。路径结果由 path projection kind 表达。局部网络由 subgraph projection kind 表达。模式匹配结果由 match projection kind 表达。普通记录由 table projection kind 表达。单值结果由 scalar projection kind 表达。

Adapter 不能把所有结果输出为 table。表格是非拓扑记录的投影,不是 graph result 的默认表面。

Adapter 不从裸 source result 或 query text + source result 猜测观察意图。Declared projection kind 与 query text、source result 或 projection parameters 不匹配时,Adapter 必须输出 diagnostics。

20.4. ID 分配职责

Adapter 分配 view-local ID。ID 必须在 view 内唯一。Adapter 使用稳定顺序分配 ID,使相同输入在相同排序规则下产生相同输出。稳定性规则见 排序、稳定性与快照

Adapter 不把源系统内部 ID 直接当作 GTP Core ID。源系统内部 ID 可以出现在显示 term 或 property 中。

20.5. 完整性职责

Adapter 必须声明投影完整性。查询限制、分页、截断、属性省略、未投影 named graph、未投影 relationship property 或无法表达的源对象都必须进入 metawarningerror

Adapter 不能把不完整投影伪装成完整结果。

20.6. 输出职责

Adapter 输出必须包含 source。输出必须使用 GTP Core canonical surface。Adapter 不输出 Pretty Skin。 Adapter 输出的 string、term、predicate、list、map 和 literal surface 必须满足 词法契约。源值包含会破坏行边界或结构分隔符的内容时,Adapter 负责选择合法 value surface。

Adapter 允许输出多个 view。每个 view 独立闭合,并拥有自己的 ID scope。

20.7. 损失声明职责

Adapter 对源语义的省略、折叠或改写必须进入投影表面。源结果中存在对象而当前 view 不投影该对象时,Adapter 使用 metawarning 说明省略范围。源结果中存在当前 Adapter 无法归档的对象时,Adapter 输出 error 或 source-specific warning。

损失声明不是实现日志。它是消费者判断回答边界的公共契约。

21. Neo4j Adapter

Neo4j Adapter 将 Neo4j/Cypher projection request 投影为 GTP Core。它按本书引用的 Neo4j Cypher Manual 解释 node、relationship、path、record、property、label、relationship type、list、map、null 和 scalar。

Neo4j Adapter 输出使用:

source neo4j

21.1. Projection request

Neo4j Adapter 接收 Neo4j query text、Neo4j query result、declared projection kind 和 projection parameters。Projection kind 必须在 Adapter 投影前确定。

path projection 要求 Neo4j path value、path variable 或可明确恢复的 path result。profile projection 要求 focus node 或 focus variable。subgraph projection 要求 node/relationship collection 或可归档为局部网络的 result。match projection 要求 query pattern 和 result bindings。table projection 用于普通 records、aggregates 或 scalar collections。scalar projection 用于 single scalar。

Projection kind 与 query text 或 query result 不匹配时,Neo4j Adapter 输出 diagnostics。Adapter 不 fallback 到另一个 view。

21.2. Node 映射

Neo4j node 映射为 node。Node 的显示 term 必须能稳定标识源 node。Adapter 使用查询工具选择的 Neo4j node identity 表面;该表面可以来自 elementId、内部 id 或工具生成的 URI-like display term。Adapter 必须在实现文档中固定一种 identity 选择规则。

node N1 <neo4j:node/123>

Node labels 映射为属性。

prop N1 labels = ["Person", "Scientist"]

Labels 的顺序必须稳定。源结果提供稳定 label 顺序时,Adapter 保留源顺序;源顺序不稳定时,Adapter 使用字典序。

Node properties 映射为 prop N…​

prop N1 name = "Alan Turing"
prop N1 born = 1912

21.3. Relationship 映射

Neo4j relationship 映射为 edge。Relationship type 映射为 edge predicate。

edge E1: N1 -[WORKED_AT]-> N2

Relationship properties 映射为 prop E…​

prop E1 startYear = 1939
prop E1 role = "cryptanalyst"

Neo4j relationship property 不需要 stmt。Relationship 在 Neo4j 中已经是可拥有属性的源对象,GTP Core 用 edge owner 表达该属性归属。

Relationship direction 使用源 relationship 的真实方向。Cypher pattern 使用无向匹配时,Adapter 仍按 source relationship direction 输出 edge,并在 path view 的 via 行使用 forwardreverse 表达遍历方向。

21.4. Path 映射

Declared path projection 将 Neo4j path 映射为 path view。Path 中的 node 映射为 step。Path 中的 relationship 映射为 via

path P1 from N1 to N3
step 0: node N1 <neo4j:node/1>
via E1: N1 -[KNOWS]-> N2 forward
step 1: node N2 <neo4j:node/2>
via E2: N3 -[MEMBER_OF]-> N2 reverse
step 2: node N3 <neo4j:node/3>
end

forward 表示 path traversal 与 relationship 方向一致。reverse 表示 path traversal 与 relationship 方向相反。

Path 中每个 relationship 必须在相邻两个 step 之间出现一次。Path 中重复出现的 node 或 relationship 保持同一 view-local ID。Path 为空时,Adapter 输出只有 step 0 的 path view,并使用相同 node 作为 fromto

如果 projection kind 是 path,但 query result 不包含 Neo4j path value 或可明确恢复的 path result,Adapter 报告 path unavailable diagnostic。

21.5. Record 映射

Cypher RETURN record 可以支撑 declared matchtable projection。

当 projection kind 是 match 时,Adapter 使用 query text 中的 pattern 和 result bindings 生成 match view。

match M1
pattern:
  edge ?r: ?a -[KNOWS]-> ?b
nodes:
  node N1 <neo4j:node/1>
  node N2 <neo4j:node/2>
edges:
  edge E1: N1 -[KNOWS]-> N2
result 1:
  ?a = N1
  ?r = E1
  ?b = N2
end

当 projection kind 是 table 时,Adapter 将聚合、统计或普通标量集合投影为 table view。

table R1
row 1: ?label = "Person", ?count = 42
end

21.6. Scalar、List、Map 和 Null

Neo4j scalar 直接映射为 GTP Core value。List 使用 bracket 表面。Map 使用 brace 表面。Null 使用 null

prop N1 aliases = ["A. Turing", "Alan Mathison Turing"]
prop N1 metadata = {source: "neo4j", score: 0.98}
prop N1 nickname = null

Map 和 list 是 value 表面,不是 Core statement。Adapter 负责保证其中值满足 Core 词法契约,并保留消费者判断源值身份所需的信息。

List 中包含 node、relationship 或 path value 时,Adapter 不把该 list 压成不可追踪字符串。Projection request 必须声明能够暴露这些图对象的 projection kind,例如 matchsubgraphpath。Map 中包含图对象时同样适用。

21.7. Statement 使用边界

Neo4j Adapter 不为普通 relationship property 生成 stmt。只有当查询结果需要把 relationship 本身作为可引用对象参与另一个投影关系时,Adapter 才生成 stmt

这种情况属于查询工具的显式结果设计,不是 relationship property 的默认投影。

21.8. 完整性

Neo4j Adapter 如果省略 labels、properties、relationship properties、path segment 或 record values,必须输出 metawarning

meta result.complete = false
warning GTP201 neo4j-property-omitted
message = "relationship properties were not requested by the query tool"
where = "edge E1"
end

22. RDF 1.2 Adapter

RDF 1.2 Adapter 将 RDF projection request 投影为 GTP Core。它按本书引用的 W3C RDF 1.2 文档解释 RDF term、triple、triple term、reifier、graph 和 dataset。

RDF 1.2 Adapter 输出使用:

source rdf12

22.1. Projection request

RDF 1.2 Adapter 接收 RDF graph 或 dataset、declared projection kind 和 projection parameters。subgraph projection 用于 RDF graph 或 dataset fragment。profile projection 需要 focus term。Projection kind 与 RDF input 不匹配时,Adapter 输出 diagnostics。

RDF Adapter 不从 graph 形状猜测观察意图。同一个 graph fragment 可以被投影为 profilesubgraph;projection request 必须声明当前 projection kind。

22.2. IRI

IRI 映射为 angle term。Adapter 使用 prefix 生成 compact IRI 时,必须在 header 中声明 prefix。

prefix ex = <http://example.org/>
node N1 <ex:Alice>

使用 compact IRI 时,prefix 必须声明。

22.3. Blank node

Blank node 映射为 node,显示 term 使用 blank node surface。

node N1 _:b1

Blank node scope 由 RDF Adapter 保证。跨 view 复制 blank node 时,Adapter 必须重新声明,不能要求消费者跨 view 推断同一 blank node。

22.4. Literal

Literal 保留 lexical form、datatype、language tag 和 directional language tag。Literal surface 必须满足 Core 的 RDF literal suffix 规则。

prop N1 rdfs:label = "Alice"@en
prop N1 ex:birthDate = "1912-06-23"^^xsd:date

RDF Adapter 把适合属性阅读的 literal-valued triple 投影为 prop。该投影只是阅读表面,不把 RDF graph 改写为 property graph。

22.5. Ordinary triple

当 object 是资源型 term 时,ordinary triple 映射为 edge

edge E1: N1 -[ex:knows]-> N2

当 object 是 literal 且 view 适合属性阅读时,ordinary triple 映射为 prop

prop N1 ex:age = 42

Adapter 必须稳定决定哪些 literal-valued triples 进入 prop。查询工具需要保留三元组形态时,把 literal 作为 edge target value 投影;该选择必须在 Adapter 规则中保持一致并进入实现文档。

22.6. Triple term 与 reifier

RDF 1.2 中,triple term 使 RDF triple 可以作为 RDF term。Reifier 是通过 RDF 1.2 reification 机制指称 triple term 的资源。

RDF Adapter 使用 stmt 表达 reifier 与被 reify triple 的投影关系。

nodes:
  node N1 <ex:Alan_Turing>
  node N2 <ex:Bletchley_Park>
  node N3 <ex:employment_1939>
edges:
  edge E1: N1 -[ex:workedAt]-> N2
statements:
  stmt S1: N3 reifies E1
props:
  prop N3 ex:startYear = 1939

N3 是 RDF reifier resource 的 node projection。E1 是被 reify triple 的 edge projection。S1 是 GTP Core statement projection ID。

stmt 不把 RDF reifier 改写为 Neo4j relationship property。它只把 RDF 1.2 reification 关系投影为 GPT/Codex 可读表面。

Reifier resource 同时保留 node 身份。关于 reifier resource 的 RDF triples 继续按普通 triple 规则投影;literal-valued triples 可以进入 prop N3 …​,resource-valued triples 进入 edgestmt S1: N3 reifies E1 只声明 reifier 与被 reify triple 的投影关系,不吞并 reifier 的其他 RDF 关系。

当 source binding 返回 reifier resource 时,binding 应指向该 reifier resource 的 node projection。Statement projection ID 不冒充 source variable。需要观察 reifier 与被 reify triple 的关系时,消费者读取 stmt 语句。

22.7. Named graph 与 dataset

RDF dataset 中的 named graph 如果进入投影,Adapter 必须声明 graph provenance。GTP Core 使用 view-level meta graph.term = <…​> 记录当前 view 的 graph term。一个 view 同时包含多个 named graph 时,Adapter 必须拆分 view,或使用 source-specific meta key 明确每个投影对象的 graph provenance。

如果 named graph 信息被省略,Adapter 必须输出 warning。

warning GTP301 rdf-named-graph-omitted
message = "named graph provenance was not projected"
where = "subgraph G1"
end

22.8. 完整性

RDF Adapter 如果省略 triple、literal datatype、language tag、reifier、named graph 或 dataset 信息,必须输出 metawarningerror。源语义损失不能隐藏。

23. SPARQL 1.2 Adapter

SPARQL 1.2 Adapter 将 SPARQL projection request 投影为 GTP Core。它按 SPARQL 1.2 query forms 区分 SELECTCONSTRUCTDESCRIBEASK,并按 declared projection kind 生成对应 view。

SPARQL 1.2 Adapter 输出使用:

source sparql12

23.1. Projection request

SPARQL 1.2 Adapter 接收 SPARQL query text、SPARQL query result、declared projection kind 和 projection parameters。Query form 提供投影材料;projection kind 提供消费者动作。

Adapter 不把 SELECTCONSTRUCTDESCRIBEASK 自动解释为唯一 view。Projection kind 与 query form 或 query result 不兼容时,Adapter 输出 diagnostics。

23.2. SELECT

SELECT 返回变量绑定。Declared projection kind 决定 SELECT result 进入 match 还是 table

当 projection kind 是 match 时,Adapter 使用 query text 中的 graph pattern 和 SELECT bindings 生成 match view。

match M1
pattern:
  edge ?match: ?s -[ex:knows]-> ?o
nodes:
  node N1 <ex:Alice>
  node N2 <ex:Bob>
edges:
  edge E1: N1 -[ex:knows]-> N2
result 1:
  ?s = N1
  ?o = N2
end

当 projection kind 是 table 时,Adapter 将聚合、统计或普通记录投影为 table view。

SELECT binding 中的 RDF term 由 RDF 1.2 Adapter 解释。Binding value 对应当前 match pattern 中的 node、edge 或 statement 时,Adapter 生成局部 ID 并绑定该 ID。Binding value 只是 literal 或 scalar 时,Adapter 直接使用 value 表面。match binding 的可用值域由 文法 约束。

table R1
row 1: ?type = <ex:Scientist>, ?count = 42
end

23.3. CONSTRUCT

CONSTRUCT 返回 RDF graph。CONSTRUCT 支撑 declared subgraph projection。Adapter 使用 RDF 1.2 Adapter 解释 graph,并输出 subgraph view。

subgraph G1
nodes:
  node N1 <ex:Alice>
  node N2 <ex:Bob>
edges:
  edge E1: N1 -[ex:knows]-> N2
end

CONSTRUCT 结果的 RDF term、triple term、reifier 和 literal 规则由 RDF 1.2 Adapter 章节定义。

23.4. DESCRIBE

DESCRIBE 返回 RDF graph。Declared projection kind 可以是 profilesubgraph

profile projection 需要 focus term。subgraph projection 将 DESCRIBE graph 作为局部网络阅读。缺少 focus 或 declared projection kind 与 result 不兼容时,Adapter 输出 diagnostics。

23.5. ASK

ASK 返回布尔结果。ASK 支撑 declared scalar projection。

scalar R1
value true
end

23.6. Binding value

SPARQL binding value 可以是 IRI、blank node、literal、triple term 或 SPARQL 1.2 结果格式允许的其他 RDF term。Adapter 必须按 RDF 1.2 Adapter 规则投影这些 value。

Variable 名称来自 SPARQL 查询结果。Adapter 不重命名变量,除非源变量名无法作为 GTP Core variable 表面表示。重命名时必须输出 meta。

23.7. Result completeness

SPARQL result 可能受 LIMITOFFSET、query tool paging 或 endpoint policy 影响。Adapter 知道结果被限制时,必须输出完整性声明。

meta result.complete = false
meta result.limit = 100

第四部:SDK 与开发者体验合约

本部定义 GTP SDK 的公共对象、Document API、Projector API、diagnostics API、语言绑定、CLI 和 fixture support。

24. SDK Surface

GTP SDK 是开发者访问 GTP Core 和 Adapter 的公共表面。SDK 提供 parser、formatter、validator、diagnostics、projectorstructured Document APIfixture supportlanguage bindings

SDK 不定义 Agent runtime、context packing、conversation-level evidence address、prompt wrapper、graph layout、query execution plan projection、database connection lifecycle 或 transaction retry policy。

24.1. Public responsibilities

SDK 必须支持以下职责:

  • parse GTP Core text into structured Document;

  • format structured Document into canonical GTP Core text;

  • validate Document and text against Core invariants;

  • expose diagnostics as structured objects;

  • project source query/result through declared projection kind;

  • support projection request fixtures and snapshot tests;

  • preserve Core semantics across language bindings。

24.2. Developer experience principles

Explicit projection

Projection kind 是请求契约。SDK 不使用 auto view guessing。

Structured first

SDK 返回 Document 和 Diagnostics。Canonical string 是 Document 的输出表面之一。

Canonical output

所有语言绑定必须输出同一 GTP Core surface。

Diagnostics as objects

错误和 warning 必须可由程序读取。

Layered composition

SDK 提供 GTP Core text 与 structured Document API,使上层 context packer、Pretty Skin、Inspector 或 Agent runtime 能够消费 GTP 输出;SDK 不定义这些相邻层。

Fixture first

SDK 和 Adapter 应支持 projection request fixtures、snapshot tests 和 conformance tests。

24.3. Non-goals

SDK 可以提供 source driver convenience integration,但 GTP SDK 的核心职责不是执行查询。Database connection、authentication、transaction management、retry policy 和 query execution plan 属于源系统或上层工具。

SDK 可以提供 Pretty Skin 或 Inspector support,但这些显示层不改变 Core canonical surface。

25. Structured Document API

Structured Document API 是 SDK 暴露的解析后对象模型。它使开发者、fixture runner、Pretty Skin、Inspector、context packer 和 Agent runtime 能够基于结构化对象工作,而不是基于字符串搜索工作。

25.1. Core objects

Document API 至少应表达以下对象:

  • Document;

  • Header;

  • Source declaration;

  • Prefix declaration;

  • View;

  • Section;

  • Node statement;

  • Edge statement;

  • Statement statement;

  • Property statement;

  • Meta statement;

  • Warning diagnostic;

  • Error diagnostic。

这些对象对应 GTP Core canonical surface。API 名称可以随语言习惯变化,但对象边界不得改变。

25.2. Required operations

Document API 必须支持 parse、format、validate、traverse 和 inspect。

Parse

Parser 读取 GTP Core text,并生成 structured Document 或 structured diagnostics。

Format

Formatter 把合法 Document 输出为 canonical GTP Core text。

Validate

Validator 检查 view boundary、ID uniqueness、unknown reference、edge direction surface、prop owner、stmt reifies relation、prefix reference、meta/warning/error surface 和 lexical contract。

Traverse

API 允许调用者遍历 view、node、edge、statement、property、meta 和 diagnostic。

Inspect

API 允许调用者读取 source、prefix、view kind、view ID、section、local IDs 和 diagnostics。

25.3. Mutation

SDK 可以提供合法 mutation API。Mutation 必须保持 Core invariants。非法 mutation 不得产生 canonical GTP Core text。

SDK 不应鼓励调用者通过字符串拼接修改 GTP Core surface。

25.4. Source location

Parser 可以保留 source span、line number 或 column information。Source location 服务 diagnostics、Inspector 和 editor tooling。Source location 不进入 GTP Core canonical surface。

26. Projector API

Projector API 把 projection request 投影为 GTP Core Document。它是 SDK 面向 Adapter 使用者的主要入口。

26.1. Input contract

Projector 接收 source、source result、projection kind、projection options,以及 query-based source 所需的 query text。

project(source, source_result, projection_kind, options) -> Document | Diagnostics
project_query(source, query_text, query_result, projection_kind, options) -> Document | Diagnostics

该接口形状是对象契约说明,不是 GTP Core syntax。

26.2. Projection kind

Projection kind 必填。Projector 不使用 preferautoguess 或 best-effort view selection。

View-specific convenience API 可以存在:

project_path(query_text, query_result, options) -> Document | Diagnostics
project_profile(query_text, query_result, focus, options) -> Document | Diagnostics
project_subgraph(query_text, query_result, options) -> Document | Diagnostics
project_match(query_text, query_result, options) -> Document | Diagnostics
project_table(query_text, query_result, options) -> Document | Diagnostics
project_scalar(query_text, query_result, options) -> Document | Diagnostics

View-specific API 仍必须验证 query text 和 source result 是否支撑对应 projection。

26.3. Projection parameters

Projection options 可以包含 focus、path variable、pattern source、budget、limit、prefix policy 和 loss policy。

Projection options 不改变 Core grammar。它们只影响 Adapter 如何从 source query/result 生成 declared projection kind 的 Document。

26.4. Diagnostics

Projector 遇到 projection mismatch 时必须返回 structured diagnostics。它不能静默选择另一个 projection kind,也不能把 mismatch 表示为空结果。

Diagnostics 至少应能表达 missing projection kind、missing parameter、focus ambiguity、path unavailable、pattern unavailable、unsupported source feature 和 adapter loss。

26.5. Output

Projector 输出 structured Document 或 diagnostics。Canonical GTP Core text 是 Document 的格式化表面。

27. Language Bindings

Language bindings 把 GTP Core 和 Adapter contract 暴露给不同开发生态。各语言 binding 必须保持同一 Core semantics 和 canonical output。

27.1. Rust core

Rust core 是 parser、formatter、validator、AST、diagnostics、projection request types、adapter contract 和 conformance support 的规范实现中心。

Rust core 不应绑定单一数据库 driver 作为 Core 前提。Source-specific driver integration 可以由 feature、adapter crate 或上层 binding 提供。

27.2. Python binding

Python binding 服务 Neo4j Python driver、RDF/SPARQL Python ecosystem、Jupyter、data workflow 和 Agent tool integration。

Python binding 应复用 Rust core 或通过 conformance suite 保持语义一致。Python binding 不应独立发明 Core grammar。

27.3. TypeScript binding

TypeScript binding 服务 Node.js、MCP server、Web Inspector、Pretty Skin 和 frontend tooling。

TypeScript binding 应复用 Rust core、WASM/native binding 或通过 conformance suite 保持输出一致。TypeScript binding 不应独立发明 Core grammar。

27.4. Binding boundary

Language bindings 可以提供 idiomatic API。它们不得改变 projection request 的必要性、projection kind 的闭合枚举、Core ID scope、diagnostic meaning 或 canonical surface。

完整语言 SDK 参考手册属于工程发布层,不属于本章。

28. CLI and Fixtures

CLI 和 fixture support 是 GTP SDK 的开发者验证表面。它们使实现者能够检查 canonical output、diagnostics、projection request handling 和 snapshot stability。

28.1. CLI responsibilities

GTP CLI 可以提供以下能力:

  • validate GTP Core text;

  • format GTP Core text;

  • inspect Document structure;

  • diff canonical outputs;

  • run projection request fixtures;

  • report diagnostics with stable code, message and where。

CLI 不改变 Core semantics。CLI 输出的 Pretty Skin 或 human-readable report 属于显示层,不是 Core canonical surface。

28.2. Fixture input

Adapter fixture 的输入边界是 projection request

Fixture 至少应包含:

  • source;

  • query text;

  • projection kind;

  • projection parameters;

  • source result;

  • expected GTP output;

  • expected diagnostics。

28.3. Snapshot stability

Snapshot tests 验证 canonical surface 稳定性。Snapshot input 必须包含 source、query text、query result、projection kind 和 projection options。

Snapshot tests 不替代 semantic validation,但它们能暴露 ID assignment、section order、property ordering、diagnostic output 和 formatting drift。

第五部:验证、示例与发布边界

本部定义 conformance、fixture、LLM extraction evaluation、end-to-end examples、project identity 和 adjacent objects。

29. 验证方法

GTP Core 的完成声明依赖验证。规范存在、formatter 能运行、样例能输出,都不能单独证明投影满足需求。

29.1. Parser round-trip

Parser round-trip 验证 GTP Core 文本能被解析为结构对象,并能重新输出等价文本。

Round-trip 检查:

  • view 边界;

  • string、angle term、predicate 和 value 边界;

  • ID 唯一性;

  • edge direction;

  • prop owner;

  • stmt reifies 关系;

  • meta、warning 和 error 表面。

29.2. Adapter fixture

Adapter fixture 验证 projection request 到 GTP Core 的映射。

Neo4j fixture 覆盖 node、relationship、relationship property、path、record、scalar、list、map 和 null。

RDF 1.2 fixture 覆盖 IRI、blank node、literal、ordinary triple、triple term、reifier、graph 和 dataset。SPARQL 1.2 fixture 覆盖 SELECT binding、CONSTRUCT graph、DESCRIBE graph 和 ASK result。

Fixture 必须包含错误与截断样例。

Projection request fixture 至少包含 source、query text、projection kind、projection parameters、source result、expected GTP output 和 expected diagnostics。

29.3. 语言模型抽取评估

语言模型抽取评估用于判断 GTP Core 是否降低结构误读。

评估任务包括:

  • 抽取所有 edge 的 source、predicate 和 target;

  • 判断 profile 的入边和出边;

  • 判断 path 中哪一步为 reverse;

  • 判断属性归属 node、edge 还是 statement;

  • 判断 RDF reifier 对应的 statement;

  • 判断结果是否完整。

评估把 GTP Core 与表格、JSON 或源结果格式进行比较。GTP 样本必须来自 declared projection kind。比较结果用于判断投影收益,不用于替代 parser 测试。

29.4. Bad data diagnostics

Bad data diagnostics 验证错误表面。测试构造 missing ref、duplicate id、invalid edge surface、missing source 和 adapter loss。

词法诊断 fixture 覆盖 unterminated string、unterminated angle term、unbalanced list/map value、invalid prefix reference 和不能进入当前语句位置的 token。

Projection diagnostics fixture 覆盖 projection-kind-missing、projection-result-mismatch、projection-parameter-missing、projection-focus-ambiguous、projection-pattern-unavailable 和 projection-path-unavailable。

实现输出稳定错误码、message 和 where。

29.5. 完成判断

实现满足以下条件时,可以声明 GTP Core 实现完成:

  • Core parser round-trip 通过;

  • projection request model validation 通过;

  • Neo4j projection request fixture 通过;

  • RDF 1.2 projection request fixture 通过;

  • SPARQL 1.2 projection request fixture 通过;

  • 错误诊断 fixture 通过;

  • snapshot stability tests 通过;

  • 语言模型抽取评估显示 GTP Core 在目标任务上降低结构误读。

30. 端到端示例

本章给出 projection request 与 GTP Core output 的组合示例。示例用于展示规则组合,不替代前文规则。

30.1. Neo4j Profile

Projection request:

source: neo4j
projection kind: profile
focus: n
query text: MATCH (n {id: $id})-[r]-(m) RETURN n, r, m

GTP output:

source neo4j

profile N1 <neo4j:node/1>
props:
  prop N1 labels = ["Person"]
  prop N1 name = "Alan Turing"
out:
  edge E1: N1 -[WORKED_AT]-> N2
in:
  edge E2: N3 -[INFLUENCED_BY]-> N1
nodes:
  node N1 <neo4j:node/1>
  node N2 <neo4j:node/2>
  node N3 <neo4j:node/3>
end

30.2. Neo4j Path

Projection request:

source: neo4j
projection kind: path
query text: MATCH p = ... RETURN p

GTP output:

source neo4j

path P1 from N1 to N3
step 0: node N1 <neo4j:node/1>
via E1: N1 -[KNOWS]-> N2 forward
step 1: node N2 <neo4j:node/2>
via E2: N3 -[MEMBER_OF]-> N2 reverse
step 2: node N3 <neo4j:node/3>
props:
  prop E1 since = 1940
end

30.3. RDF 1.2 Reifier Subgraph

Projection request:

source: rdf12
projection kind: subgraph
source result: RDF graph fragment containing reifier <ex:employment_1939>

GTP output:

source rdf12
prefix ex = <http://example.org/>

subgraph G1
nodes:
  node N1 <ex:Alan_Turing>
  node N2 <ex:Bletchley_Park>
  node N3 <ex:Winston_Churchill>
  node N4 <ex:employment_1939>
edges:
  edge E1: N1 -[ex:workedAt]-> N2
  edge E2: N3 -[ex:authorized]-> N4
statements:
  stmt S1: N4 reifies E1
props:
  prop N4 ex:startYear = 1939
end

If a source binding returns the reifier resource, the binding points to N4. S1 identifies the statement projection and does not replace the source variable.

30.4. SPARQL SELECT Match

Projection request:

source: sparql12
projection kind: match
query text: SELECT ?s ?o WHERE { ?s ex:knows ?o }

GTP output:

source sparql12
prefix ex = <http://example.org/>

match M1
pattern:
  edge ?match: ?s -[ex:knows]-> ?o
nodes:
  node N1 <ex:Alice>
  node N2 <ex:Bob>
  node N3 <ex:Carol>
edges:
  edge E1: N1 -[ex:knows]-> N2
  edge E2: N3 -[ex:knows]-> N2
result 1:
  ?s = N1
  ?o = N2
result 2:
  ?s = N3
  ?o = N2
end

30.5. SPARQL SELECT Table

Projection request:

source: sparql12
projection kind: table
query text: SELECT ?type (COUNT(?s) AS ?count) WHERE { ?s a ?type } GROUP BY ?type

GTP output:

source sparql12
prefix ex = <http://example.org/>

table R1
row 1: ?type = <ex:Scientist>, ?count = 42
row 2: ?type = <ex:Engineer>, ?count = 17
end

30.6. SPARQL ASK Scalar

Projection request:

source: sparql12
projection kind: scalar
query text: ASK { ?s ex:knows ?o }

GTP output:

source sparql12

scalar R1
value true
end

30.7. Truncated Subgraph

Projection request:

source: neo4j
projection kind: subgraph
query text: MATCH (a)-[r]->(b) RETURN a, r, b LIMIT 50

GTP output:

source neo4j

subgraph G1
meta result.complete = false
meta edges.count = 327
meta edges.shown = 50
nodes:
  node N1 <neo4j:node/1>
  node N2 <neo4j:node/2>
edges:
  edge E1: N1 -[RELATED_TO]-> N2
end

warning GTP009 truncated-result
message = "edges limited to 50 of 327"
where = "subgraph G1 edges"
end

30.8. Projection Mismatch Error

Projection request:

source: neo4j
projection kind: path
query text: MATCH (n) RETURN count(n)

GTP output:

source neo4j

error GTP020 projection-path-unavailable
message = "path projection requires a path value, but source result contains a single scalar"
where = "RETURN count(n)"
end

Appendix A: 术语表

Graph Text Projection (GTP)

面向 GPT/Codex 阅读的图查询结果文本投影规范族。它以 GTP Core 为核心语言,并通过 Adapter 把 Neo4j、RDF 1.2 和 SPARQL 1.2 查询结果投影到 canonical text surface。

GTP Core

Graph Text Projection 的核心语言。它定义 canonical surface、view、statement、lexical contract、adapter contract、错误语义和验证方式。

Adapter

读取 projection request、归档源对象、验证 declared projection kind 并输出 GTP Core 文本或 diagnostics 的组件。Neo4j Adapter、RDF 1.2 Adapter 与 SPARQL 1.2 Adapter 是当前源承诺。

Projection

查询结果面向消费者的可见表达。GTP Core 是文本投影,不是源数据格式。

Canonical surface

GTP Core 规定的规范书写表面。

Text surface

查询结果进入 GPT/Codex 上下文时的线性文本承载面。Text surface 是 Projection 的具体输出表面,不等于源数据格式。

View

服务特定消费者动作的投影结构,例如 profilepathsubgraphmatchtablescalar

Projection request

Adapter 执行投影的输入对象。它至少包含 source、source result 和 declared projection kind;query-based source 还必须包含 query text。

Projection kind

声明当前源查询结果应投影为哪一种 GTP Core view 的闭合枚举。当前取值为 profilepathsubgraphmatchtablescalar

Observation intent

Agent-facing tool schema 可选使用的动作化意图。它可以映射到 projection kind,但不属于 GTP Core canonical surface。

Node

当前投影视图中的节点投影单位。

Edge

当前投影视图中的有向关系投影单位。

Statement

当前投影视图中的可引用陈述投影单位。

Property

归属于 node、edge、statement、view 或 result 的 key-value 投影单位。

Pretty Skin

Core 之外的显示层。它添加颜色、Unicode 线条、box drawing 或终端分组,但不改变 Core 语义。

Structured Document API

SDK 暴露的解析后对象模型。它允许上层工具遍历、验证和格式化 Document、View、Node、Edge、Statement、Property、Meta 和 Diagnostic。

Context packer

上层相邻对象。它把 GTP Core 文本、自然语言说明、tool call metadata、token budget、citation instruction 或其他上下文组合成发送给 Agent 的消息。

Evidence address

上层 runtime 或 context packer 对工具调用结果、文档、view 和局部 ID 的组合引用方式。它不属于 GTP Core 语义。

31. 项目公共身份与发布边界

Graph Text Projection (GTP) 是本项目的公共名称。GTP Core 是 Graph Text Projection 的核心语言名称。公共叙述首次出现时使用全名 Graph Text Projection (GTP);上下文已经建立后,可以使用 GTP 指称该规范族。

对外文档、README、仓库描述和发布说明使用 Graph Text Projection 建立对象边界。GTP Core 用于指称核心语言、canonical surface、view、statement、lexical contract、错误语义和验证规则。Projection request、Adapter contract、SDK/API 和 conformance 属于围绕 GTP Core 的规范层对象。

31.1. 规范层与工程发布层

公共身份层负责项目如何被外部识别。规范层负责 GTP Core 的对象边界和语义规则。工程发布层负责 Rust crate、SDK、CLI、adapter implementation、fixture package 和 generated documentation。

规范层名称与工程发布层名称可以对应,但不能互相替代。Rust crate 存在不证明 GTP Core 实现完成;仓库存在不扩大 GTP Core 的语义边界。

31.2. GitHub 命名

在没有独立 organization 的发布形态中,仓库名使用完整公共名称的 kebab-case surface:graph-text-projection

如果项目使用 GitHub organization,organization 名称可以使用 compact surface graphtextprojection。组织名已经提供公共身份时,子仓库使用职责名,例如 rust-sdkconformanceadaptersexamples

graphtextprojection/graphtextprojection 是组织化发布时的可用主仓库形态。该名称属于工程发布层,不属于 GTP Core 语义。

31.3. Rust crate 命名

工程发布层的 Rust 主 crate 名称使用 graph-text-projection。Rust module path 为 graph_text_projection。主 crate 可承载 GTP Core AST、parser、formatter、validator、diagnostics、lexical contract、projection request types、adapter contract 和 fixture support。

gtp 不作为 Rust 主 crate 名。该缩写在 Rust 生态中已有其他协议含义,不能稳定建立 Graph Text Projection 的对象边界。GTP 可以在 Graph Text Projection 已经出现后的上下文中作为缩写使用。

公开 crate 拆分时使用 graph-text-projection-* 前缀。后缀描述工程职责,而不是源对象愿望。可用后缀包括 coreneo4jrdf12sparql12cliconformance。Source-specific crates 可以使用 graph-text-projection-neo4jgraph-text-projection-rdf12graph-text-projection-sparql12。这些后缀只保留命名空间,不改变当前源承诺、Adapter contract 或完成判断。

31.4. Python 与 TypeScript package

Python 与 TypeScript package naming 属于工程发布层。它们可以提供 language binding、driver bridge、Document API、Projector API、CLI integration 或 Inspector support,但不扩大 GTP Core canonical surface。

31.5. 非承诺

公共身份和发布命名不改变 GTP Core 的语义边界。命名空间中出现 clisdkadapterconformance 或 source-specific 后缀,不表示对应实现已经完成,也不表示 Core 承诺执行查询、提供图布局、替代源格式或保证语言模型正确性。

Pretty Skin、Graphviz DOT Adapter、Mermaid Adapter、查询执行计划投影和图形布局仍属于相邻对象。它们可以在工程发布层拥有独立仓库或 crate,但不进入 GTP Core 语义。

32. 相邻对象

Pretty Skin 是 GTP Core 的相邻对象。它负责人类终端视觉效果,不参与 Core 语义。

Inspector 是 GTP Core 的相邻对象。它可以解析 GTP Document 并提供 Web、Jupyter、VS Code 或终端检查界面,但不改变 Core canonical surface。

Graphviz DOT 与 Mermaid 是参考坐标。它们提供文本图语料和符号参考,不是当前 Adapter 承诺。

Neo4j Browser、Graphviz layout 和 Mermaid renderer 是图形投影工具。它们服务人类视觉检查,不服务 GPT/Codex 的一维文本读取。

查询执行计划投影是相邻对象。GTP Core 表达查询结果,不表达数据库执行算子、索引使用、成本估计或优化器计划。

Agent runtime 是相邻对象。它负责工具调用调度、对话状态、重试、memory 和跨轮证据管理,不参与 Core 语义。

Context packer 是相邻对象。它负责把 GTP Core text、tool call metadata、自然语言提示、citation instruction、token budget 或其他上下文组合成发送给 Agent 的消息。

Tool call envelope 和 conversation-level evidence address 是相邻对象。它们可以引用 GTP view-local ID,但不改变 GTP Core 的 view-local scope。

Prompt wrapper 是相邻对象。它可以根据 GTP diagnostics 生成自然语言说明,但不能替代 metawarningerror

参考资料