尧图网站建设 
Graphify 语义抽取 Subagent 规范解析将文档、论文与图像语料转换为确定性知识图谱的 JSON 提取协议【免费下载链接】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本指南围绕 Graphify 语义管线中的核心契约——语义抽取 subagent 提示词规范即仓库 skills 各平台 variants 共用的extraction-spec.md展开讲解当语料包含文档、论文或图像时Agent 如何把人类可读语料转译为结构化的知识图谱 JSON 片段。读完本文你将掌握 Graphify 抽取子代理的完整行为约束节点 ID 的确定性生成规则、边方向与语言边界、EXTRACTED/INFERRED/AMBIGUOUS三级置信度模型、离散置信度评分阶梯、超边hyperedge适用条件以及驱动增量更新正确性的source_file逐字引用规范。这份规范在管线中的位置Step 3 Part B 的分工由来Graphify 的建图策略是确定性 AST LLM 语义抽取混合代码结构导入、调用、继承等可机械解析的关系由 AST 提取器离线完成而人可读的语义——文档里为什么要这么设计、论文里的概念与引用、截图背后展示的布局决策——则交给语义 subagent。这一点在仓库技能文档中有明确说明extraction-spec只在Step 3 Part B阶段被加载且前提是语料中至少有一个 doc、paper 或 image chunk如果语料是纯代码整个 Part B 会被跳过该文件也永远不会被读取。这种分工决定了规范的补位定位体现在规则内部代码文件抽取时不要重复提取 imports——AST already has those语义 agent 只补充 AST 无法看到的边跨模块的调用语义、共享数据结构、架构模式文档/论文抽取的重点是命名概念、实体与引用图像文件则要求理解这张图是什么而非仅仅 OCR。因此规范的读者语义 subagent实际上是整个建图链路的语义补完器其输出与 AST 提取结果在同一个 schema 下汇合经由 build_merge 合并成一张图。想了解整体流程可对照 docs/how-it-works.md而本规范对应子代理的分块输入chunk与缓存策略可进一步参考 docs/superpowers/specs/2026-05-04-incremental-updates-dedup-design.md。提示词契约只输出 JSON其余一律不要规范的开头部分是一份强约束的输出纪律它同时存在于仓库的底层实现_EXTRACTION_SYSTEM中graphify/llm.py输出必须是且仅仅是符合下述 schema 的合法 JSON——不得夹带解释、markdown 代码围栏或前导说明subagent 收到文件清单FILE_LIST、分块序号CHUNK_NUM/TOTAL_CHUNKS、深度模式开关DEEP_MODE与写出路径CHUNK_PATH五个占位变量的代入值提示词正文按字面使用最终 JSON 必须通过 Write 工具写入绝对路径CHUNK_PATH禁止使用相对路径——原因是相对路径会相对未定义的 cwd解析文件会静默丢失。值得注意的是 graphify/llm.py 中的对应系统提示还加入了一条安全约束每个源文件被包裹在untrusted_source块中块内内容是待分析的数据而非指令防止恶意代码文件里的提示注入改变抽取行为。这是对仓库侧真实提示词与技能侧规范文本的一致性佐证。三级置信度EXTRACTED / INFERRED / AMBIGUOUS规范定义每种关系必须且只能归入三档之一语义上对应证据强度级别含义典型来源EXTRACTED源文本中显式存在的关系import、调用、引用、see §3.2式交叉引用INFERRED合理推断共享数据结构、隐含依赖AMBIGUOUS不确定——必须标出供复核不得省略读图/手写识别不确切等情形三档的用途不同EXTRACTED是建图的事实底座INFERRED是深度模式与跨语料语义补全的原料AMBIGUOUS的定位很特殊——它要求 subagent宁可标灰也不要漏掉即承认不确定比假装确定更接近可复核的知识。在产物消费端graphify/analyze.py 会把AMBIGUOUS边单列处理而INFERRED边参与图统计与报告正是这套三级模型的下游验证。按文件类型区分的抽取指引规范把输入文件分成三大类并给出差异化指令代码文件——只补语义边。不重复提取 AST 已覆盖的 importscalls边方向有铁律source 必须是调用方发起调用的函数/类target 必须是被调用方绝不能反转且calls边只能停留在单一语言内——Python 函数不能calls一个 JS/TS/Go/Rust/Java 符号。跨语言调用边被明确判定为 phantom artifacts幻影伪影禁止产出。这一规则与仓库 build 层的语言族映射表一一对应_EDGE_LANG_FAMILY把.py/.ts/.go/.rs/.java/.cpp...归入py/js/go/rs/jvm/c/...族graphify/build.py正是用它在合并期拦截语言越界的边。文档/论文文件——提取命名概念、实体、引用。其中最关键的一条是rationale 归置规则决策的为什么WHY、取舍、设计意图必须以rationale属性挂到相关概念节点上绝不允许单独创建一个 rationale 节点或 fragment 节点。只有本身是命名实体或概念的东西才配建节点。这条规则在底层有对应证据_EXTRACTION_SYSTEM同样要求 store as arationaleattribute... Do NOT create separate rationale nodesgraphify/llm.py而 dedup 去重模块把rationale与document视为身份锚定在源位置而非名字的 file-anchored 类型graphify/dedup.py因为它们的节点来自 docstring 与标题同名而不同址不应被跨文件合并。图像文件——要求用视觉理解图像到底是什么不要只做 OCR。规范按图类给出了期望产出UI 截图布局模式、设计决策、关键元素、用途图表指标、趋势/洞察、数据来源推文/帖子以主张为节点加上作者、提到的概念示意图组件及其连接研究插图它演示了什么、方法、结果手写/白板想法与箭头不确定的解读标记为AMBIGUOUS。file_type六值白名单任何节点只能取code、document、paper、image、rationale、concept之一任何其他值都会非法并被拒绝。仓库实现印证了这并非虚张声势graphify/build.py 内置了_FILE_TYPE_SYNONYMS同义映射markdown→document、tool→code、pattern/principle/tech→concept等并在校验时把缺失值默认补为concept、未知值经同义映射后兜底成conceptgraphify/build.py——也就是说 subagent 如果任性输出非法类型会被归一到 concept 而不是让整次抽取作废这是工程上对 LLM 漂移的容错设计。DEEP_MODE深度模式的激进推断开关当用户以--mode deep运行graphify extract时DEEP_MODE变量生效要求 subagent更激进地给出 INFERRED 边间接依赖、共享假设、潜在耦合都要纳入拿不准的一律标AMBIGUOUS而不是省略。这正好对应 graphify/cli.py 中deep_mode extract_mode deep的参数解析以及 graphify/llm.py 中_DEEP_EXTRACTION_SUFFIX的实现文本只为具体的架构信号共享数据契约、显式生命周期耦合、多步流程依赖补充 INFERRED 边避免宽泛的概念相似边。两条证据共同说明deep 不是放开纪律而是提高推断档位的同时收窄推断的形态范围。缓存侧同样为 deep 模式做了命名空间隔离cache/semantic-deep/与普通cache/semantic/互不污染见 graphify/cache.py 与 graphify/cli.py避免 deep 结果遮蔽普通抽取、也避免普通运行误命中 deep 缓存。semantically_similar_to跨结构的语义相似边规范允许在没有任何结构性链接无 import、无调用、无引用的前提下为解决同一问题或表达同一思想的两个概念添加semantically_similar_to边标记为INFERRED并携带反映相似程度的confidence_score区间 0.6–0.95。规范给出的三类典例两个都做用户输入校验、但从不互相调用的函数代码里的一个类与论文里描述同一算法的概念用不同方式处理同一失败模式的两个错误类型。规范同时强调克制Only add these when the similarity is genuinely non-obvious and cross-cutting平凡相似trivial similarity一律不加。换言之这类边是给跨代码/文档/论文的潜在洞见留的通道不是凑数的工具。Hyperedges三人及以上的小组关系当 ≥3 个节点明显共同参与某个仅靠两两成对边无法表达的共享概念、流程或模式时才把组关系写进顶层hyperedges数组。规范示例实现同一协议/接口的所有类认证流程里的所有函数即使它们并非互相调用论文某一节构成同一连贯思想的所有概念。两个使用边界一是克制使用仅在组关系提供了超出两两边的额外信息时才加二是硬上限每个 chunk 最多 3 条 hyperedge。schema 里 hyperedge 的relation限定为participate_in | implement | form。这一上限在 graphify/llm.py 的实现文本中同样出现Maximum 3 hyperedges per chunk说明规范文本与库内提示词是同一套约束的两个载体。前端元数据YAML frontmatter 的逐节点搬运规范要求若某文件带 YAML frontmatter--- ... ---须把其中的source_url、captured_at、author、contributor复制到该文件产出的每一个节点上。这解释了为什么 schema 的 node 对象里预留了这四个可空字段——它们既可由在线抓取源回填也可在增量更新时保留谱系信息。confidence_score离散阶梯而非连续区间规范对每条边强制confidence_score两条硬规则永不省略永不把 0.5 当默认值。EXTRACTED边恒为1.0INFERRED边只能取以下五档之一任何情况下不得取 0.5分值含义0.95直接结构证据共享数据结构、具名的跨文件引用0.85强推断明确的功能对齐无直接符号链接0.75合理推断共享问题域 相似形态需解读0.65弱推断主题相关无形态证据0.55推测但合理仅表面共现AMBIGUOUS边取 0.1–0.3。规范还给出了一个难得的生产侧解释模型对离散 rubrics 的遵循度优于连续区间生产环境观测到的双峰分布50% 集中在 0.5、40% 集中在 0.85说明连续区间指导正被压平成二元选择。因此如果上面没有一档适用正确动作是标记AMBIGUOUS而不是擅自填 0.4 或更低——宁可降级为待复核也不要污染 0.5 这个伪中值。这五档在库内_EXTRACTION_SYSTEM与 build 层的confidence_score↔confidence双向补全逻辑graphify/build.py中被共同消费。Node ID确定性优先于一切节点 ID 是整份规范里技术含量最高、也是最容易踩坑的部分。规则可拆成五条字符白名单全小写只允许[a-z0-9_]不得出现点号与斜杠格式{stem}_{entity}。其中stem去掉扩展名的完整仓库相对路径每一层目录都参与、以_连接每段小写、非字母数字字符替换为_entity为符号名同样归一化必须使用每一级目录而非只取最近父目录——这是同名文件在不同目录下保持可区分的关键顶层文件无父目录如setup.py只用文件名 stemsetup_my_funcCRITICAL绝不追加 chunk 序号、流水号或任何后缀_c1、_chunk2均非法。ID 必须能仅凭 label 确定性推导——无论哪个 chunk 处理它同一实体必须产出同一 ID。规范给出了四个权威示例src/auth/session.py ValidateToken → src_auth_session_validatetoken lib/utils/helpers.py parse_url → lib_utils_helpers_parse_url tests/test_foo.py _helper → tests_test_foo_helper docs/v1/api/README.md getUser → docs_v1_api_readme_getuser为什么如此苛刻因为这套 ID 必须与AST 提取器生成的 ID 完全一致。如果 subagent 图省事用裸文件名session_validatetoken或只取最近父目录auth_session_validatetoken就会制造孤儿幽灵重复节点orphan ghost-duplicate nodes——同一实体会以两个 ID 出现在图中语义边与 AST 边对不上号。若是对旧版仅最近父目录格式构建的项目做重提取用户应执行graphify extract --force全量重建clean rebuild而不是指望增量修补。这条规则的意图与整个项目确定性抽取的路线一致语义结果必须能在多次运行、分块处理之间稳定对合才能支撑增量--update。仓库中 tests/test_extraction_spec_ids.py 正是对这套 ID 契约的专项验证。JSON schema 全字段解读规范的 schema 只有一个顶层对象含三张内容表与两个记账字段graphify/llm.py 的实现文本保持一致{nodes:[{id:auth_session_validatetoken,label:Human Readable Name,file_type:code|document|paper|image|rationale|concept,source_file:FILE_LIST path verbatim,source_location:null,source_url:null,captured_at:null,author:null,contributor:null}],edges:[{source:node_id,target:node_id,relation:calls|implements|references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for,confidence:EXTRACTED|INFERRED|AMBIGUOUS,confidence_score:1.0,source_file:FILE_LIST path verbatim,source_location:null,weight:1.0}],hyperedges:[{id:snake_case_id,label:Human Readable Label,nodes:[node_id1,node_id2,node_id3],relation:participate_in|implement|form,confidence:EXTRACTED|INFERRED,confidence_score:0.75,source_file:FILE_LIST path verbatim}],input_tokens:0,output_tokens:0}逐块拆解nodes——id按上文规则确定性生成label是人类可读名file_type六值白名单source_file遵循下文专述的逐字规则source_location通常为 null 或行号引用source_url / captured_at / author / contributor承接 YAML frontmatter。边列表里出现了第 8 种关系rationale_for用于表达该节点是那个概念的 rationale这类关系配合规范rationale 作为属性而非独立节点的规则说明它主要在展示/导出层还原解释关系——graphify/callflow_html.py 中rationale_for的中文标注为说明英文为 explains正是这一语义的可视化出口。edges——source/target指向节点 IDrelation是八选一枚举calls|implements|references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for它比 AST 的机械边如 imports更强调语义侧关系confidence三级 confidence_score离散评分source_file逐字引用source_location通常可空weight默认 1.0。hyperedges——id为 snake_caselabel人类可读nodes数组列出参与成员relation三选一confidence只允许EXTRACTED|INFERRED无 AMBIGUOUS示例分值为 0.75。input_tokens / output_tokens——记录本 chunk 抽取消耗的 token 量供成本核算与缓存判断使用。source_file 逐字规则增量更新的地基schema 里每个节点、边、超边的source_file都被要求与该文件在FILE_LIST中出现的形式逐字一致verbatim and absolute。禁止缩减为 basename、禁止重新相对化、禁止剥掉任何目录前缀、禁止改动分隔符——引擎会在下游统一做分隔符规范化并相对化到 build root。规范的注释点明了动机这让完整构建与增量--update处于同一基线上使 build_merge 的 replace-on-re-extract 能匹配到既有节点而不是不断累积重复。换言之source_file是增量更新的对合键之一。仓库侧的增量文档印证了这一点build_merge 采用replace-on-re-extract语义——每次合并前把new_chunks中出现的每个source_file从底图中先剔除再合入从而保证改动文件的旧/过期节点不会残留在图上见 graphify/skills/windows/references/update.mdissue #1344。由此反推如果 subagent 把source_file写成了 basename 或经过改写增量--update就会把同一个文件的新旧版本当成两个来源处理逐步累积重复节点。tests/test_incremental.py、tests/test_affected_cli.py 等测试文件覆盖了这条链路上的场景。写出为什么必须是绝对路径规范的最后一步指令看似琐碎却性命攸关用 Write 工具把 JSON 写到这个精确的绝对路径CHUNK_PATH。不用相对路径——Write 会相对未定义的 cwd 解析相对路径文件会被静默丢弃。这对 Agent 工程是一个普遍适用的经验产物写出必须显式锚定不能依赖环境当前目录的隐式状态。随后各 chunk 的 JSON 碎片在同一输出目录汇合交给 merge 步骤拼装成最终graph.json。与整体语义抽取设计的呼应把规范放到 Graphify 全局来看它的若干约束恰好折射出项目对LLM 语义产物的整体工程态度这部分可由源码交叉印证确定性对合节点 ID 与source_file的双重确定性让LLM 语义与确定性 AST在同一 key 空间里不产生幽灵重复支撑跨 chunk、跨语言、跨运行的稳定合并宽容入、严格出file_type即便写错也会被 build 层同义映射兜底而非整包丢弃graphify/build.pyhyperedge 成员即使被 LLM 写成对象也会被归约成合法 ID见_coerce_hyperedge_member_refsgraphify/build.py边界意识跨语言calls边被语言族映射拦截graphify/build.py正是项目多次标记为 phantom artifacts 的已知陷阱理性记账input_tokens/output_tokens、confidence_score、AMBIGUOUS档位共同构成可审计的知识让图上的每条边都带着可解释的证据强度这与项目every edge explained, no vector store的定位一致全平台同构这份extraction-spec.md以同一内容存在于 Claude、Cursor、Codex、Gemini、Kiro、Trae、Copilot、VSCode、Windows 等全部 skill 目录的references/下tools/skillgen/expected/中的生成物如本文件graphify__skills__windows__references__extraction-spec.md与 graphify/skills/windows/references/extraction-spec.md 互为镜像即一份契约、多端复用的设计。实践要点速查先判断是否该读本文件纯代码语料跳过 Part B只有含 doc/paper/image 时才加载输出纪律裸 JSON无围栏、无解释绝对路径落盘代码语义边 vs 文档概念边分开处理代码补语义、不重复 imports文档建概念节点、rationale 一律作属性方向与语言calls的 source 恒为调用方且永不出跨语言调用边评分用离散阶梯EXTRACTED1.0INFERRED 五档0.95/0.85/0.75/0.65/0.55不取 0.5兜底标 AMBIGUOUS 打 0.1–0.3ID 严格对合 AST完整路径 stem entity、全小写下划线、不加任何 chunk 后缀旧格式项目用--force重建source_file逐字照抄 FILE_LIST它是增量 replace-on-re-extract 对合、避免重复节点累积的生命线。读懂并遵守这份规范是让 Graphify 语义抽取在多 chunk 并行、跨平台复用与增量--update场景下保持图不脏、边可信的前提。【免费下载链接】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 语义抽取 Subagent 规范解析：将文档、论文与图像语料转换为确定性知识图谱的 JSON 提取协议
Graphify 语义抽取 Subagent 规范解析将文档、论文与图像语料转换为确定性知识图谱的 JSON 提取协议【免费下载链接】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本指南围绕 Graphify 语义管线中的核心契约——语义抽取 subagent 提示词规范即仓库 skills 各平台 variants 共用的extraction-spec.md展开讲解当语料包含文档、论文或图像时Agent 如何把人类可读语料转译为结构化的知识图谱 JSON 片段。读完本文你将掌握 Graphify 抽取子代理的完整行为约束节点 ID 的确定性生成规则、边方向与语言边界、EXTRACTED/INFERRED/AMBIGUOUS三级置信度模型、离散置信度评分阶梯、超边hyperedge适用条件以及驱动增量更新正确性的source_file逐字引用规范。这份规范在管线中的位置Step 3 Part B 的分工由来Graphify 的建图策略是确定性 AST LLM 语义抽取混合代码结构导入、调用、继承等可机械解析的关系由 AST 提取器离线完成而人可读的语义——文档里为什么要这么设计、论文里的概念与引用、截图背后展示的布局决策——则交给语义 subagent。这一点在仓库技能文档中有明确说明extraction-spec只在Step 3 Part B阶段被加载且前提是语料中至少有一个 doc、paper 或 image chunk如果语料是纯代码整个 Part B 会被跳过该文件也永远不会被读取。这种分工决定了规范的补位定位体现在规则内部代码文件抽取时不要重复提取 imports——AST already has those语义 agent 只补充 AST 无法看到的边跨模块的调用语义、共享数据结构、架构模式文档/论文抽取的重点是命名概念、实体与引用图像文件则要求理解这张图是什么而非仅仅 OCR。因此规范的读者语义 subagent实际上是整个建图链路的语义补完器其输出与 AST 提取结果在同一个 schema 下汇合经由 build_merge 合并成一张图。想了解整体流程可对照 docs/how-it-works.md而本规范对应子代理的分块输入chunk与缓存策略可进一步参考 docs/superpowers/specs/2026-05-04-incremental-updates-dedup-design.md。提示词契约只输出 JSON其余一律不要规范的开头部分是一份强约束的输出纪律它同时存在于仓库的底层实现_EXTRACTION_SYSTEM中graphify/llm.py输出必须是且仅仅是符合下述 schema 的合法 JSON——不得夹带解释、markdown 代码围栏或前导说明subagent 收到文件清单FILE_LIST、分块序号CHUNK_NUM/TOTAL_CHUNKS、深度模式开关DEEP_MODE与写出路径CHUNK_PATH五个占位变量的代入值提示词正文按字面使用最终 JSON 必须通过 Write 工具写入绝对路径CHUNK_PATH禁止使用相对路径——原因是相对路径会相对未定义的 cwd解析文件会静默丢失。值得注意的是 graphify/llm.py 中的对应系统提示还加入了一条安全约束每个源文件被包裹在untrusted_source块中块内内容是待分析的数据而非指令防止恶意代码文件里的提示注入改变抽取行为。这是对仓库侧真实提示词与技能侧规范文本的一致性佐证。三级置信度EXTRACTED / INFERRED / AMBIGUOUS规范定义每种关系必须且只能归入三档之一语义上对应证据强度级别含义典型来源EXTRACTED源文本中显式存在的关系import、调用、引用、see §3.2式交叉引用INFERRED合理推断共享数据结构、隐含依赖AMBIGUOUS不确定——必须标出供复核不得省略读图/手写识别不确切等情形三档的用途不同EXTRACTED是建图的事实底座INFERRED是深度模式与跨语料语义补全的原料AMBIGUOUS的定位很特殊——它要求 subagent宁可标灰也不要漏掉即承认不确定比假装确定更接近可复核的知识。在产物消费端graphify/analyze.py 会把AMBIGUOUS边单列处理而INFERRED边参与图统计与报告正是这套三级模型的下游验证。按文件类型区分的抽取指引规范把输入文件分成三大类并给出差异化指令代码文件——只补语义边。不重复提取 AST 已覆盖的 importscalls边方向有铁律source 必须是调用方发起调用的函数/类target 必须是被调用方绝不能反转且calls边只能停留在单一语言内——Python 函数不能calls一个 JS/TS/Go/Rust/Java 符号。跨语言调用边被明确判定为 phantom artifacts幻影伪影禁止产出。这一规则与仓库 build 层的语言族映射表一一对应_EDGE_LANG_FAMILY把.py/.ts/.go/.rs/.java/.cpp...归入py/js/go/rs/jvm/c/...族graphify/build.py正是用它在合并期拦截语言越界的边。文档/论文文件——提取命名概念、实体、引用。其中最关键的一条是rationale 归置规则决策的为什么WHY、取舍、设计意图必须以rationale属性挂到相关概念节点上绝不允许单独创建一个 rationale 节点或 fragment 节点。只有本身是命名实体或概念的东西才配建节点。这条规则在底层有对应证据_EXTRACTION_SYSTEM同样要求 store as arationaleattribute... Do NOT create separate rationale nodesgraphify/llm.py而 dedup 去重模块把rationale与document视为身份锚定在源位置而非名字的 file-anchored 类型graphify/dedup.py因为它们的节点来自 docstring 与标题同名而不同址不应被跨文件合并。图像文件——要求用视觉理解图像到底是什么不要只做 OCR。规范按图类给出了期望产出UI 截图布局模式、设计决策、关键元素、用途图表指标、趋势/洞察、数据来源推文/帖子以主张为节点加上作者、提到的概念示意图组件及其连接研究插图它演示了什么、方法、结果手写/白板想法与箭头不确定的解读标记为AMBIGUOUS。file_type六值白名单任何节点只能取code、document、paper、image、rationale、concept之一任何其他值都会非法并被拒绝。仓库实现印证了这并非虚张声势graphify/build.py 内置了_FILE_TYPE_SYNONYMS同义映射markdown→document、tool→code、pattern/principle/tech→concept等并在校验时把缺失值默认补为concept、未知值经同义映射后兜底成conceptgraphify/build.py——也就是说 subagent 如果任性输出非法类型会被归一到 concept 而不是让整次抽取作废这是工程上对 LLM 漂移的容错设计。DEEP_MODE深度模式的激进推断开关当用户以--mode deep运行graphify extract时DEEP_MODE变量生效要求 subagent更激进地给出 INFERRED 边间接依赖、共享假设、潜在耦合都要纳入拿不准的一律标AMBIGUOUS而不是省略。这正好对应 graphify/cli.py 中deep_mode extract_mode deep的参数解析以及 graphify/llm.py 中_DEEP_EXTRACTION_SUFFIX的实现文本只为具体的架构信号共享数据契约、显式生命周期耦合、多步流程依赖补充 INFERRED 边避免宽泛的概念相似边。两条证据共同说明deep 不是放开纪律而是提高推断档位的同时收窄推断的形态范围。缓存侧同样为 deep 模式做了命名空间隔离cache/semantic-deep/与普通cache/semantic/互不污染见 graphify/cache.py 与 graphify/cli.py避免 deep 结果遮蔽普通抽取、也避免普通运行误命中 deep 缓存。semantically_similar_to跨结构的语义相似边规范允许在没有任何结构性链接无 import、无调用、无引用的前提下为解决同一问题或表达同一思想的两个概念添加semantically_similar_to边标记为INFERRED并携带反映相似程度的confidence_score区间 0.6–0.95。规范给出的三类典例两个都做用户输入校验、但从不互相调用的函数代码里的一个类与论文里描述同一算法的概念用不同方式处理同一失败模式的两个错误类型。规范同时强调克制Only add these when the similarity is genuinely non-obvious and cross-cutting平凡相似trivial similarity一律不加。换言之这类边是给跨代码/文档/论文的潜在洞见留的通道不是凑数的工具。Hyperedges三人及以上的小组关系当 ≥3 个节点明显共同参与某个仅靠两两成对边无法表达的共享概念、流程或模式时才把组关系写进顶层hyperedges数组。规范示例实现同一协议/接口的所有类认证流程里的所有函数即使它们并非互相调用论文某一节构成同一连贯思想的所有概念。两个使用边界一是克制使用仅在组关系提供了超出两两边的额外信息时才加二是硬上限每个 chunk 最多 3 条 hyperedge。schema 里 hyperedge 的relation限定为participate_in | implement | form。这一上限在 graphify/llm.py 的实现文本中同样出现Maximum 3 hyperedges per chunk说明规范文本与库内提示词是同一套约束的两个载体。前端元数据YAML frontmatter 的逐节点搬运规范要求若某文件带 YAML frontmatter--- ... ---须把其中的source_url、captured_at、author、contributor复制到该文件产出的每一个节点上。这解释了为什么 schema 的 node 对象里预留了这四个可空字段——它们既可由在线抓取源回填也可在增量更新时保留谱系信息。confidence_score离散阶梯而非连续区间规范对每条边强制confidence_score两条硬规则永不省略永不把 0.5 当默认值。EXTRACTED边恒为1.0INFERRED边只能取以下五档之一任何情况下不得取 0.5分值含义0.95直接结构证据共享数据结构、具名的跨文件引用0.85强推断明确的功能对齐无直接符号链接0.75合理推断共享问题域 相似形态需解读0.65弱推断主题相关无形态证据0.55推测但合理仅表面共现AMBIGUOUS边取 0.1–0.3。规范还给出了一个难得的生产侧解释模型对离散 rubrics 的遵循度优于连续区间生产环境观测到的双峰分布50% 集中在 0.5、40% 集中在 0.85说明连续区间指导正被压平成二元选择。因此如果上面没有一档适用正确动作是标记AMBIGUOUS而不是擅自填 0.4 或更低——宁可降级为待复核也不要污染 0.5 这个伪中值。这五档在库内_EXTRACTION_SYSTEM与 build 层的confidence_score↔confidence双向补全逻辑graphify/build.py中被共同消费。Node ID确定性优先于一切节点 ID 是整份规范里技术含量最高、也是最容易踩坑的部分。规则可拆成五条字符白名单全小写只允许[a-z0-9_]不得出现点号与斜杠格式{stem}_{entity}。其中stem去掉扩展名的完整仓库相对路径每一层目录都参与、以_连接每段小写、非字母数字字符替换为_entity为符号名同样归一化必须使用每一级目录而非只取最近父目录——这是同名文件在不同目录下保持可区分的关键顶层文件无父目录如setup.py只用文件名 stemsetup_my_funcCRITICAL绝不追加 chunk 序号、流水号或任何后缀_c1、_chunk2均非法。ID 必须能仅凭 label 确定性推导——无论哪个 chunk 处理它同一实体必须产出同一 ID。规范给出了四个权威示例src/auth/session.py ValidateToken → src_auth_session_validatetoken lib/utils/helpers.py parse_url → lib_utils_helpers_parse_url tests/test_foo.py _helper → tests_test_foo_helper docs/v1/api/README.md getUser → docs_v1_api_readme_getuser为什么如此苛刻因为这套 ID 必须与AST 提取器生成的 ID 完全一致。如果 subagent 图省事用裸文件名session_validatetoken或只取最近父目录auth_session_validatetoken就会制造孤儿幽灵重复节点orphan ghost-duplicate nodes——同一实体会以两个 ID 出现在图中语义边与 AST 边对不上号。若是对旧版仅最近父目录格式构建的项目做重提取用户应执行graphify extract --force全量重建clean rebuild而不是指望增量修补。这条规则的意图与整个项目确定性抽取的路线一致语义结果必须能在多次运行、分块处理之间稳定对合才能支撑增量--update。仓库中 tests/test_extraction_spec_ids.py 正是对这套 ID 契约的专项验证。JSON schema 全字段解读规范的 schema 只有一个顶层对象含三张内容表与两个记账字段graphify/llm.py 的实现文本保持一致{nodes:[{id:auth_session_validatetoken,label:Human Readable Name,file_type:code|document|paper|image|rationale|concept,source_file:FILE_LIST path verbatim,source_location:null,source_url:null,captured_at:null,author:null,contributor:null}],edges:[{source:node_id,target:node_id,relation:calls|implements|references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for,confidence:EXTRACTED|INFERRED|AMBIGUOUS,confidence_score:1.0,source_file:FILE_LIST path verbatim,source_location:null,weight:1.0}],hyperedges:[{id:snake_case_id,label:Human Readable Label,nodes:[node_id1,node_id2,node_id3],relation:participate_in|implement|form,confidence:EXTRACTED|INFERRED,confidence_score:0.75,source_file:FILE_LIST path verbatim}],input_tokens:0,output_tokens:0}逐块拆解nodes——id按上文规则确定性生成label是人类可读名file_type六值白名单source_file遵循下文专述的逐字规则source_location通常为 null 或行号引用source_url / captured_at / author / contributor承接 YAML frontmatter。边列表里出现了第 8 种关系rationale_for用于表达该节点是那个概念的 rationale这类关系配合规范rationale 作为属性而非独立节点的规则说明它主要在展示/导出层还原解释关系——graphify/callflow_html.py 中rationale_for的中文标注为说明英文为 explains正是这一语义的可视化出口。edges——source/target指向节点 IDrelation是八选一枚举calls|implements|references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for它比 AST 的机械边如 imports更强调语义侧关系confidence三级 confidence_score离散评分source_file逐字引用source_location通常可空weight默认 1.0。hyperedges——id为 snake_caselabel人类可读nodes数组列出参与成员relation三选一confidence只允许EXTRACTED|INFERRED无 AMBIGUOUS示例分值为 0.75。input_tokens / output_tokens——记录本 chunk 抽取消耗的 token 量供成本核算与缓存判断使用。source_file 逐字规则增量更新的地基schema 里每个节点、边、超边的source_file都被要求与该文件在FILE_LIST中出现的形式逐字一致verbatim and absolute。禁止缩减为 basename、禁止重新相对化、禁止剥掉任何目录前缀、禁止改动分隔符——引擎会在下游统一做分隔符规范化并相对化到 build root。规范的注释点明了动机这让完整构建与增量--update处于同一基线上使 build_merge 的 replace-on-re-extract 能匹配到既有节点而不是不断累积重复。换言之source_file是增量更新的对合键之一。仓库侧的增量文档印证了这一点build_merge 采用replace-on-re-extract语义——每次合并前把new_chunks中出现的每个source_file从底图中先剔除再合入从而保证改动文件的旧/过期节点不会残留在图上见 graphify/skills/windows/references/update.mdissue #1344。由此反推如果 subagent 把source_file写成了 basename 或经过改写增量--update就会把同一个文件的新旧版本当成两个来源处理逐步累积重复节点。tests/test_incremental.py、tests/test_affected_cli.py 等测试文件覆盖了这条链路上的场景。写出为什么必须是绝对路径规范的最后一步指令看似琐碎却性命攸关用 Write 工具把 JSON 写到这个精确的绝对路径CHUNK_PATH。不用相对路径——Write 会相对未定义的 cwd 解析相对路径文件会被静默丢弃。这对 Agent 工程是一个普遍适用的经验产物写出必须显式锚定不能依赖环境当前目录的隐式状态。随后各 chunk 的 JSON 碎片在同一输出目录汇合交给 merge 步骤拼装成最终graph.json。与整体语义抽取设计的呼应把规范放到 Graphify 全局来看它的若干约束恰好折射出项目对LLM 语义产物的整体工程态度这部分可由源码交叉印证确定性对合节点 ID 与source_file的双重确定性让LLM 语义与确定性 AST在同一 key 空间里不产生幽灵重复支撑跨 chunk、跨语言、跨运行的稳定合并宽容入、严格出file_type即便写错也会被 build 层同义映射兜底而非整包丢弃graphify/build.pyhyperedge 成员即使被 LLM 写成对象也会被归约成合法 ID见_coerce_hyperedge_member_refsgraphify/build.py边界意识跨语言calls边被语言族映射拦截graphify/build.py正是项目多次标记为 phantom artifacts 的已知陷阱理性记账input_tokens/output_tokens、confidence_score、AMBIGUOUS档位共同构成可审计的知识让图上的每条边都带着可解释的证据强度这与项目every edge explained, no vector store的定位一致全平台同构这份extraction-spec.md以同一内容存在于 Claude、Cursor、Codex、Gemini、Kiro、Trae、Copilot、VSCode、Windows 等全部 skill 目录的references/下tools/skillgen/expected/中的生成物如本文件graphify__skills__windows__references__extraction-spec.md与 graphify/skills/windows/references/extraction-spec.md 互为镜像即一份契约、多端复用的设计。实践要点速查先判断是否该读本文件纯代码语料跳过 Part B只有含 doc/paper/image 时才加载输出纪律裸 JSON无围栏、无解释绝对路径落盘代码语义边 vs 文档概念边分开处理代码补语义、不重复 imports文档建概念节点、rationale 一律作属性方向与语言calls的 source 恒为调用方且永不出跨语言调用边评分用离散阶梯EXTRACTED1.0INFERRED 五档0.95/0.85/0.75/0.65/0.55不取 0.5兜底标 AMBIGUOUS 打 0.1–0.3ID 严格对合 AST完整路径 stem entity、全小写下划线、不加任何 chunk 后缀旧格式项目用--force重建source_file逐字照抄 FILE_LIST它是增量 replace-on-re-extract 对合、避免重复节点累积的生命线。读懂并遵守这份规范是让 Graphify 语义抽取在多 chunk 并行、跨平台复用与增量--update场景下保持图不脏、边可信的前提。【免费下载链接】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），仅供参考