graphify 节点摘要 RFC为 AI Agent 设计有界的文件级节点摘要【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphifygraphify 将代码库、文档、SQL 模式与 PDF 转为可查询的知识图谱后AI 编码 Agent 仍要打开原始文件才能回答这个文件是干什么的。本文基于仓库中的 RFC 文档 docs/node-summaries-rfc.md完整解析文件级节点摘要这一提案的问题定义、字段设计、两种存储方案graph.json内嵌summary属性 vs 独立node-summaries.jsonsidecar及其取舍并结合 graphify/cli.py、graphify/serve.py 的现有实现说明摘要最终会落在explain与 MCP 节点查询链路的哪些位置。读完你能理解该提案如何在保持图谱离线、确定性与降低 Agent 重复读文件之间取得平衡。问题图谱已经省了 token但 Agent 仍要打开文件graph.json为 Agent 提供了图结构、源文件、节点标签和关系帮助其避免读取整个仓库。但 Agent 经常仍需检查原始文件才能回答一个基本的导航问题这个文件或节点负责什么RFC 指出的核心矛盾在于图谱回答谁和谁有关联很高效但不直接回答这个文件做什么。而像graphify query、graphify explain、MCP 节点查询、图导航这类高频操作恰恰都卡在这一点上——Agent 被迫为一次简单的职责判断付出整文件读取消耗。在 docs/how-it-works.md 中对现有图格式的定义可以佐证这个信息缺口每个节点只有id稳定标识符、label人类可读名称、file_typecode、document、paper、image、rationale、source_file来源路径四类属性每条边携带relation动词短语如calls、imports、implements、confidenceEXTRACTED/INFERRED/AMBIGUOUS与source_file。结构信息完备语义信息缺位——这正是节点旁边放一句简短摘要要填补的空隙。RFC 的动机与项目整体设计哲学一致首次运行提取建图、后续查询只读紧凑图谱docs/how-it-works.md 给出的实测对比显示语料越大、相对直接读原始文件的 token 节省越明显。文件级摘要是在这一机制上再往前推一步——让 Agent 在是否值得读这个文件这个决策点就拿到足够信号。目标与非目标RFC 对提案边界做了显式约束这是理解整个设计取舍的前提。目标帮助 Agent 用更少的上下文选出相关文件默认情况下保持 graphify 离线、确定性的行为保持首个实现小且可评审不向GRAPH_REPORT.md塞入长段落散文为未来可选的 LLM 生成摘要后端预留空间。非目标第一版明确不做不为每个函数、方法或局部符号生成摘要默认不调用 LLM 或远程 API不替代graphify explain——摘要应该让explain更实用而非取代它不把GRAPH_REPORT.md变成逐文件索引。从源码结构看GRAPH_REPORT.md由 graphify/report.py 生成定位为人类可读的审计轨迹围绕社区community标签组织内容把逐文件散文塞进去确实会与它的报告定位冲突这正是非目标第 4 条的由来。两种方案的共同约束无论摘要最终存放在哪里RFC 要求两个选项遵循同一组约束只从文件级节点开始不下探到符号级每条摘要有界约一句话大致 200–300 字符首先生成确定性摘要仅使用已有的本地信号模块 docstring、顶部注释、导出的符号、import、关系计数、社区/上下文数据存储模型未达成一致前默认不输出摘要graphify explain node中存在摘要时展示摘要graphify serve/ MCP 节点查询中存在摘要时一并返回。值得注意的是默认不输出这一条它意味着摘要功能在设计上是纯增量、纯可选的未开启时graph.json的字节内容与今天完全一致不会引入任何兼容性风险。摘要应该包含什么RFC 给出的设计原则是摘要要给 Agent 足够的信号来判断是否要打开这个文件既不替代文件本身也不让图产物膨胀。推荐字段字段对 Agent 的帮助summary一句有界的话描述文件的职责。这是主要的省 token 字段source_file让 Agent 无需手动解析节点 ID 就能跳到正确的文件label保证摘要在 CLI、MCP 和 UI 各上下文中保持可读generated_by区分确定性摘要与未来 LLM 生成的摘要summary_version让格式可以演进而不用猜测旧摘要是如何生成的generated_bysummary_version的组合值得单独说明它把摘要是怎么来的作为一等元数据。这样未来若引入 LLM 后端消费者可以按generated_by过滤或降级信任度summary_version则保证旧摘要在新格式下仍可被识别与弃用而不需要猜。摘要句子内推荐的信号来源信号为什么属于这句话模块 docstring 或顶部注释通常是质量最高的人类撰写的目的陈述导出的类/函数/符号告诉 Agent 该文件提供什么 API 面重要的 import 或依赖揭示文件属于 auth、数据库、UI、CLI、测试等哪一类占主导的图关系表明文件主要是调用、导入、定义、包含还是引用其他节点社区或邻近 hub 标签提供架构上下文而不必读整份社区报告源位置覆盖情况如可用帮助区分文件级摘要与符号级解释示例RFC 给出的目标形态以 graphify 自己的extract.py为例{ label: extract.py, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships; defines language parsers and import/call extraction helpers., generated_by: deterministic, summary_version: 1 }同时 RFC 划定了摘要不该包含的内容长调用链、完整依赖列表、原始代码、文件内每个符号。这些细节本来就属于图必要时可以通过graphify explain、graphify query或直接读文件获取。这实际上是一套信息分层策略摘要负责路由决策图谱负责结构遍历原始文件负责细节核实。方案 Agraph.json中加summary属性做法是在文件级节点上新增可选summary字段{ id: graphify_extract, label: extract.py, file_type: code, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships using language-specific parsers. }RFC 设想的用户流程graphify . --summarize-nodes graphify explain extract.py优点图消费方只需面对单一产物与 NetworkX 节点属性和既有节点元数据模型一致explain、serve、可视化器和 MCP 工具消费起来容易不存在 sidecar 的新鲜度问题也不需要按节点 ID 做 join。缺点向核心图产物里添加了文本扩大了图 schema 的面把整个graph.json倒进 LLM 上下文的消费方会一次性为所有摘要付费。结合仓库源码看方案 A 的落地点非常自然graphify/extract.py 中构造文件级节点时已经在统一写入file_type、source_file、label等属性例如提取器为 Python 文件创建节点处节点字典中固定包含file_type: code与source_file字段新增一个可选属性与现有节点构造模式完全同构不需要改变任何节点创建调用链。方案 B独立 sidecarnode-summaries.json做法是把摘要写入一个按节点 ID 索引的独立产物{ version: 1, generator: deterministic, nodes: { graphify_extract: { label: extract.py, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships using language-specific parsers. } } }RFC 设想的用户流程graphify summarize graphify explain extract.py优点让graph.json保持精简易读、专注于拓扑摘要的可选性变得显式可以独立重新生成为未来的生成器元数据提供了天然位置。缺点消费方必须发现并加载第二个产物引入新鲜度与同步问题每个想要摘要的消费方都要按节点 ID 做 join。仓库中其实已经存在一个 sidecar 模式的先例graphify explain命令在展示节点信息时会尝试读取graph.json旁边的.graphify_learning.json由graphify reflect产生的工作记忆层对命中该层的节点追加一行 Lesson 提示且这是纯展示层合并——sidecar 缺失或出错时静默跳过绝不写回主图见 graphify/cli.py 中load_learning_overlay的调用与except兜底。这套主图 可选展示层 sidecar的机制验证了方案 B 的技术可行性同时它的尽力而为、缺失即降级语义也正是摘要 sidecar 处理新鲜度问题时可以复用的模式。摘要在现有命令链路上的插入点RFC 要求摘要在graphify explain与graphify serve/ MCP 节点查询中展示。对照当前实现这两个插入点都已经存在清晰的承载位置。graphify explain命令实现位于 graphify/cli.py。当前它打印节点的 label、ID、Source、Type、Community可选的 Lesson 覆盖层Degree以及按度数排序的 Connections最多 20 条超出部分按方向 文件分组统计最后通过 graphify/querylog.py 记录一次查询日志。如果摘要落地summary行最合理的插入位置正是在 Node: 头部与 Connections 之间——这与 Lesson 行的处理方式一致存在即打印不存在则不占位。节点解析explain与 MCP 工具共享同一套节点解析逻辑 graphify/serve.py。_find_node按四级优先序返回匹配source 精确匹配 → 标签/ID 精确 → 前缀 → 子串find_node_ambiguity则在获胜匹配层横跨多个源文件时返回竞争者列表提示调用方改用仓库相对路径或完整节点 ID 重试。这意味着摘要展示天然继承了一整套成熟的歧义处理Agent 用graphify explain extract.py命中多文件时不会拿到错误文件的摘要而是先被要求消歧。MCP / serve 侧graphify/serve.py 的查询类工具已经带有token_budget参数默认 2000 token输出按预算截断。RFC 的follow-up部分提到允许graphify query在预算内为返回节点附带摘要——从这套既有的 token 预算机制看摘要作为高信息密度、低成本的节点属性恰好适合在截断预算中优先保留。状态核对这是一个尚未落地的提案需要明确的是就当前仓库而言该 RFC 仍处于设计评审阶段全库搜索不存在summarize子命令也没有--summarize-nodes标志graphify/cli.py 的命令分支中没有对应实现graph.json的现有节点 schema 中没有任何summary字段docs/how-it-works.md 描述的节点属性也仅列出id、label、file_type、source_file四项因此graphify . --summarize-nodes与graphify summarize两条命令示例目前都是 RFC 的目标形态不是当前可用命令。这不影响 RFC 作为技术文档的价值——它已经把做什么、不做什么、存哪里、怎么演进论证到可以直接开工的程度。存储方案选定后的首版实施步骤RFC 给出了一条最小实施路径实现确定性的文件级摘要生成按选定方案存储摘要在graphify explain中展示摘要在graphify serve/ MCP 节点查询中展示摘要为以下行为补充测试默认行为未开启时输出不变、生成的摘要内容、摘要缺失时的降级路径、摘要长度上界200–300 字符约束。其中第 5 步的测试点值得注意把未开启时graph.json逐字节不变列为测试对象而不是仅仅测摘要生成了什么说明 RFC 把对现有消费方的零侵入视为验收标准之一而非隐含假设。后续方向与开放问题后续想法RFC 原文列出的演进方向增加可选的 LLM 生成摘要且要求显式的 provider / 后端选择若文件级摘要被证明有用再扩展到类或模块级节点允许graphify query在预算内为返回节点附带摘要若摘要与主图分离生成则补充缓存/新鲜度元数据。留给维护者与用户的问题graphify 应该偏好单一产物graph.json还是把生成文本放在 sidecar确定性文件级摘要应该在建图时生成还是只通过graphify summarize这样的显式命令生成summary是不是合适的命名还是synopsis更能传达短而有界的含义对大型仓库可接受的摘要长度预算是多少这四个问题分别对应存储模型、生成时机、API 命名与规模成本恰好覆盖了此类功能落地前必须拍板的全部决策点。小结这份 RFC 的价值在于把一个看似简单的需求——给文件节点加一句描述——拆解成了明确的约束体系只用本地确定性信号、摘要有界、默认不输出、explain与 MCP 双通道展示、为 LLM 后端预留generated_by/summary_version元数据。对照仓库现状explain命令的展示层、sidecar 覆盖层先例、_find_node的歧义处理与 MCP 的 token 预算机制都为两个候选方案提供了现成的承载点与先例。对于研究图谱 Agent 协作接口设计的人这是一个很好的样本先用最小、可回退、零侵入的确定性实现把通道打通再把生成质量LLM 摘要作为显式可选的后续增量。【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 graphify 节点摘要 RFC：为 AI Agent 设计有界的文件级节点摘要
graphify 节点摘要 RFC为 AI Agent 设计有界的文件级节点摘要【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphifygraphify 将代码库、文档、SQL 模式与 PDF 转为可查询的知识图谱后AI 编码 Agent 仍要打开原始文件才能回答这个文件是干什么的。本文基于仓库中的 RFC 文档 docs/node-summaries-rfc.md完整解析文件级节点摘要这一提案的问题定义、字段设计、两种存储方案graph.json内嵌summary属性 vs 独立node-summaries.jsonsidecar及其取舍并结合 graphify/cli.py、graphify/serve.py 的现有实现说明摘要最终会落在explain与 MCP 节点查询链路的哪些位置。读完你能理解该提案如何在保持图谱离线、确定性与降低 Agent 重复读文件之间取得平衡。问题图谱已经省了 token但 Agent 仍要打开文件graph.json为 Agent 提供了图结构、源文件、节点标签和关系帮助其避免读取整个仓库。但 Agent 经常仍需检查原始文件才能回答一个基本的导航问题这个文件或节点负责什么RFC 指出的核心矛盾在于图谱回答谁和谁有关联很高效但不直接回答这个文件做什么。而像graphify query、graphify explain、MCP 节点查询、图导航这类高频操作恰恰都卡在这一点上——Agent 被迫为一次简单的职责判断付出整文件读取消耗。在 docs/how-it-works.md 中对现有图格式的定义可以佐证这个信息缺口每个节点只有id稳定标识符、label人类可读名称、file_typecode、document、paper、image、rationale、source_file来源路径四类属性每条边携带relation动词短语如calls、imports、implements、confidenceEXTRACTED/INFERRED/AMBIGUOUS与source_file。结构信息完备语义信息缺位——这正是节点旁边放一句简短摘要要填补的空隙。RFC 的动机与项目整体设计哲学一致首次运行提取建图、后续查询只读紧凑图谱docs/how-it-works.md 给出的实测对比显示语料越大、相对直接读原始文件的 token 节省越明显。文件级摘要是在这一机制上再往前推一步——让 Agent 在是否值得读这个文件这个决策点就拿到足够信号。目标与非目标RFC 对提案边界做了显式约束这是理解整个设计取舍的前提。目标帮助 Agent 用更少的上下文选出相关文件默认情况下保持 graphify 离线、确定性的行为保持首个实现小且可评审不向GRAPH_REPORT.md塞入长段落散文为未来可选的 LLM 生成摘要后端预留空间。非目标第一版明确不做不为每个函数、方法或局部符号生成摘要默认不调用 LLM 或远程 API不替代graphify explain——摘要应该让explain更实用而非取代它不把GRAPH_REPORT.md变成逐文件索引。从源码结构看GRAPH_REPORT.md由 graphify/report.py 生成定位为人类可读的审计轨迹围绕社区community标签组织内容把逐文件散文塞进去确实会与它的报告定位冲突这正是非目标第 4 条的由来。两种方案的共同约束无论摘要最终存放在哪里RFC 要求两个选项遵循同一组约束只从文件级节点开始不下探到符号级每条摘要有界约一句话大致 200–300 字符首先生成确定性摘要仅使用已有的本地信号模块 docstring、顶部注释、导出的符号、import、关系计数、社区/上下文数据存储模型未达成一致前默认不输出摘要graphify explain node中存在摘要时展示摘要graphify serve/ MCP 节点查询中存在摘要时一并返回。值得注意的是默认不输出这一条它意味着摘要功能在设计上是纯增量、纯可选的未开启时graph.json的字节内容与今天完全一致不会引入任何兼容性风险。摘要应该包含什么RFC 给出的设计原则是摘要要给 Agent 足够的信号来判断是否要打开这个文件既不替代文件本身也不让图产物膨胀。推荐字段字段对 Agent 的帮助summary一句有界的话描述文件的职责。这是主要的省 token 字段source_file让 Agent 无需手动解析节点 ID 就能跳到正确的文件label保证摘要在 CLI、MCP 和 UI 各上下文中保持可读generated_by区分确定性摘要与未来 LLM 生成的摘要summary_version让格式可以演进而不用猜测旧摘要是如何生成的generated_bysummary_version的组合值得单独说明它把摘要是怎么来的作为一等元数据。这样未来若引入 LLM 后端消费者可以按generated_by过滤或降级信任度summary_version则保证旧摘要在新格式下仍可被识别与弃用而不需要猜。摘要句子内推荐的信号来源信号为什么属于这句话模块 docstring 或顶部注释通常是质量最高的人类撰写的目的陈述导出的类/函数/符号告诉 Agent 该文件提供什么 API 面重要的 import 或依赖揭示文件属于 auth、数据库、UI、CLI、测试等哪一类占主导的图关系表明文件主要是调用、导入、定义、包含还是引用其他节点社区或邻近 hub 标签提供架构上下文而不必读整份社区报告源位置覆盖情况如可用帮助区分文件级摘要与符号级解释示例RFC 给出的目标形态以 graphify 自己的extract.py为例{ label: extract.py, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships; defines language parsers and import/call extraction helpers., generated_by: deterministic, summary_version: 1 }同时 RFC 划定了摘要不该包含的内容长调用链、完整依赖列表、原始代码、文件内每个符号。这些细节本来就属于图必要时可以通过graphify explain、graphify query或直接读文件获取。这实际上是一套信息分层策略摘要负责路由决策图谱负责结构遍历原始文件负责细节核实。方案 Agraph.json中加summary属性做法是在文件级节点上新增可选summary字段{ id: graphify_extract, label: extract.py, file_type: code, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships using language-specific parsers. }RFC 设想的用户流程graphify . --summarize-nodes graphify explain extract.py优点图消费方只需面对单一产物与 NetworkX 节点属性和既有节点元数据模型一致explain、serve、可视化器和 MCP 工具消费起来容易不存在 sidecar 的新鲜度问题也不需要按节点 ID 做 join。缺点向核心图产物里添加了文本扩大了图 schema 的面把整个graph.json倒进 LLM 上下文的消费方会一次性为所有摘要付费。结合仓库源码看方案 A 的落地点非常自然graphify/extract.py 中构造文件级节点时已经在统一写入file_type、source_file、label等属性例如提取器为 Python 文件创建节点处节点字典中固定包含file_type: code与source_file字段新增一个可选属性与现有节点构造模式完全同构不需要改变任何节点创建调用链。方案 B独立 sidecarnode-summaries.json做法是把摘要写入一个按节点 ID 索引的独立产物{ version: 1, generator: deterministic, nodes: { graphify_extract: { label: extract.py, source_file: graphify/extract.py, summary: Extracts source files into graph nodes and relationships using language-specific parsers. } } }RFC 设想的用户流程graphify summarize graphify explain extract.py优点让graph.json保持精简易读、专注于拓扑摘要的可选性变得显式可以独立重新生成为未来的生成器元数据提供了天然位置。缺点消费方必须发现并加载第二个产物引入新鲜度与同步问题每个想要摘要的消费方都要按节点 ID 做 join。仓库中其实已经存在一个 sidecar 模式的先例graphify explain命令在展示节点信息时会尝试读取graph.json旁边的.graphify_learning.json由graphify reflect产生的工作记忆层对命中该层的节点追加一行 Lesson 提示且这是纯展示层合并——sidecar 缺失或出错时静默跳过绝不写回主图见 graphify/cli.py 中load_learning_overlay的调用与except兜底。这套主图 可选展示层 sidecar的机制验证了方案 B 的技术可行性同时它的尽力而为、缺失即降级语义也正是摘要 sidecar 处理新鲜度问题时可以复用的模式。摘要在现有命令链路上的插入点RFC 要求摘要在graphify explain与graphify serve/ MCP 节点查询中展示。对照当前实现这两个插入点都已经存在清晰的承载位置。graphify explain命令实现位于 graphify/cli.py。当前它打印节点的 label、ID、Source、Type、Community可选的 Lesson 覆盖层Degree以及按度数排序的 Connections最多 20 条超出部分按方向 文件分组统计最后通过 graphify/querylog.py 记录一次查询日志。如果摘要落地summary行最合理的插入位置正是在 Node: 头部与 Connections 之间——这与 Lesson 行的处理方式一致存在即打印不存在则不占位。节点解析explain与 MCP 工具共享同一套节点解析逻辑 graphify/serve.py。_find_node按四级优先序返回匹配source 精确匹配 → 标签/ID 精确 → 前缀 → 子串find_node_ambiguity则在获胜匹配层横跨多个源文件时返回竞争者列表提示调用方改用仓库相对路径或完整节点 ID 重试。这意味着摘要展示天然继承了一整套成熟的歧义处理Agent 用graphify explain extract.py命中多文件时不会拿到错误文件的摘要而是先被要求消歧。MCP / serve 侧graphify/serve.py 的查询类工具已经带有token_budget参数默认 2000 token输出按预算截断。RFC 的follow-up部分提到允许graphify query在预算内为返回节点附带摘要——从这套既有的 token 预算机制看摘要作为高信息密度、低成本的节点属性恰好适合在截断预算中优先保留。状态核对这是一个尚未落地的提案需要明确的是就当前仓库而言该 RFC 仍处于设计评审阶段全库搜索不存在summarize子命令也没有--summarize-nodes标志graphify/cli.py 的命令分支中没有对应实现graph.json的现有节点 schema 中没有任何summary字段docs/how-it-works.md 描述的节点属性也仅列出id、label、file_type、source_file四项因此graphify . --summarize-nodes与graphify summarize两条命令示例目前都是 RFC 的目标形态不是当前可用命令。这不影响 RFC 作为技术文档的价值——它已经把做什么、不做什么、存哪里、怎么演进论证到可以直接开工的程度。存储方案选定后的首版实施步骤RFC 给出了一条最小实施路径实现确定性的文件级摘要生成按选定方案存储摘要在graphify explain中展示摘要在graphify serve/ MCP 节点查询中展示摘要为以下行为补充测试默认行为未开启时输出不变、生成的摘要内容、摘要缺失时的降级路径、摘要长度上界200–300 字符约束。其中第 5 步的测试点值得注意把未开启时graph.json逐字节不变列为测试对象而不是仅仅测摘要生成了什么说明 RFC 把对现有消费方的零侵入视为验收标准之一而非隐含假设。后续方向与开放问题后续想法RFC 原文列出的演进方向增加可选的 LLM 生成摘要且要求显式的 provider / 后端选择若文件级摘要被证明有用再扩展到类或模块级节点允许graphify query在预算内为返回节点附带摘要若摘要与主图分离生成则补充缓存/新鲜度元数据。留给维护者与用户的问题graphify 应该偏好单一产物graph.json还是把生成文本放在 sidecar确定性文件级摘要应该在建图时生成还是只通过graphify summarize这样的显式命令生成summary是不是合适的命名还是synopsis更能传达短而有界的含义对大型仓库可接受的摘要长度预算是多少这四个问题分别对应存储模型、生成时机、API 命名与规模成本恰好覆盖了此类功能落地前必须拍板的全部决策点。小结这份 RFC 的价值在于把一个看似简单的需求——给文件节点加一句描述——拆解成了明确的约束体系只用本地确定性信号、摘要有界、默认不输出、explain与 MCP 双通道展示、为 LLM 后端预留generated_by/summary_version元数据。对照仓库现状explain命令的展示层、sidecar 覆盖层先例、_find_node的歧义处理与 MCP 的 token 预算机制都为两个候选方案提供了现成的承载点与先例。对于研究图谱 Agent 协作接口设计的人这是一个很好的样本先用最小、可回退、零侵入的确定性实现把通道打通再把生成质量LLM 摘要作为显式可选的后续增量。【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考