graphify 语义抽取契约全解：extraction-spec.md 子代理提示词规范深度剖析

graphify 语义抽取契约全解extraction-spec.md 子代理提示词规范深度剖析【免费下载链接】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 仓库中的 extraction-spec.md 为唯一主体完整拆解这份语义抽取子代理提示词规范的全部规则三级置信度分类、离散置信度评分量表、节点 ID 确定性规则、source_file逐字路径约束与 JSON 输出 Schema。读完你将理解 graphify 如何让 LLM 子代理产出的图片段与 AST 抽取器严格对齐、并能被增量更新与提示词版本化缓存正确复用并能据此为自己的多代理抽取管线设计类似的输出契约。一、extraction-spec.md 在 graphify 管线中的位置graphify 的抽取分两条路Part A 用本地确定性 AST 解析器处理代码的结构性事实import、定义、跨文件引用Part B 用 LLM 子代理处理AST 找不到的语义关系——文档、论文、图片中的概念、引用、设计意图。extraction-spec.md 就是 Part B 发给每一个语义子代理的提示词本体。文档开头的定位说明非常明确Load this in Step 3 Part B when the corpus has at least one doc, paper, or image chunk. A pure-code corpus skips Part B and never reads this file.即只有当语料中存在至少一个文档/论文/图片 chunk 时主代理才在 Step 3 Part B 加载它纯代码语料会跳过 Part B永远不读这个文件。这与 skill-agents.md 中 Part B 的Fast path规则完全对应——检测到零文档、零论文、零图片时直接跳到 Part C 合并阶段且要先写一个空的.graphify_semantic.json占位否则合并阶段会因无条件读取该文件而抛FileNotFoundError。该提示词以**逐字verbatim**方式下发给每个子代理其中 5 个占位符由主代理替换FILE_LIST本 chunk 内子代理要读的文件清单CHUNK_NUM/TOTAL_CHUNKSchunk 编号与总数DEEP_MODE是否处于--mode deep模式CHUNK_PATH子代理必须把结果 JSON 写到的绝对路径。值得注意的工程事实这份规范并不是手写一份就完事。所有 18 个宿主claude、codex、opencode、kilo、copilot、claw、droid、trae、kiro、pi、antigravity、windows、kimi、amp、gemini 等的 skill 文件都由 tools/skillgen/ 下的单一源生成每份宿主的references/extraction-spec.md如 graphify/skills/agents/references/extraction-spec.md、graphify/skills/claude/references/extraction-spec.md都是同一契约的渲染副本避免多宿主各自漂移。二、提示词骨架三条置信度等级与三类文件的处理规则提示词正文第一句就立下输出铁律只输出符合 Schema 的合法 JSON——无解释、无 markdown 围栏、无前言。随后定义了每条边的三级置信度分类等级含义判定标准EXTRACTED关系在源中显式存在import、call、citation、see §3.2 这类明写关系INFERRED合理推断共享数据结构、隐含依赖AMBIGUOUS不确定标记待审不得省略AMBIGUOUS的定位很关键不确定不是丢弃的理由而是必须落图、供人工审查。这一条贯穿了后文的评分规则——拿不准的边宁可降级为AMBIGUOUS也不允许给出低于 0.4 的分数。2.1 代码文件只补 AST 的盲区绝不重复劳动对代码文件规范要求聚焦于AST 找不到的语义边调用关系、共享数据、架构模式并有一条明确的禁则不要重新抽取 import——AST 已经拿到了。这确立了 graphify确定性解析 LLM 补语义的分工边界。针对calls边规范给出了两条硬性方向规则方向不可反source必须是调用方发起调用的函数/类target必须是被调方calls边不得跨语言Python 函数不能callsJS/TS/Go/Rust/Java 符号反之亦然——跨语言调用边被定性为phantom artifacts幽灵产物严禁产出。2.2 文档/论文文件rationale 是属性不是节点对文档与论文规范要求抽取命名概念、实体与引用。其中最容易做错的点是rationale决策理由、权衡、设计意图的处理方式rationale 必须存为相关概念节点上的rationale属性不得单独创建 rationale 节点或 fragment 节点只有自身就是命名实体或概念的东西才建节点file_type是概念类节点思想、原则、机制、设计模式的类型标记file_type只允许恰好六个取值code、document、paper、image、rationale、concept其他值一律非法、会被拒绝。这条规则在原生后端提示词 graphify/llm.py_EXTRACTION_SYSTEM约 L478–L508中同样出现两条抽取路径共用同一套 Schema 约束。2.3 图片文件用视觉理解图是什么而不是 OCR图片文件必须用视觉能力理解图片本身是什么而不是做 OCR。规范按图片类型给出了六类抽取要点UI 截图布局模式、设计决策、关键元素、用途图表度量、趋势/洞察、数据来源推文/帖子主张作为节点、作者、提及的概念示意图组件与连接关系研究图它证明了什么、方法、结果手写/白板想法与箭头读不确定的部分标AMBIGUOUS。2.4 DEEP_MODE激进推断但仍受约束当以--mode deep运行时规范指示子代理对INFERRED边采取更激进的策略——间接依赖、共享假设、潜在耦合都可以提边但不确定的必须标AMBIGUOUS而不是省略。对比原生后端的 deep 后缀 graphify/llm.py_DEEP_EXTRACTION_SUFFIX约 L510–L516可以看到同一设计意图deep 模式只放行具体架构信号共享数据契约、显式生命周期耦合、多步流程依赖并抑制宽泛的概念相似边。2.5 semantically_similar_to无结构链接的跨切面相似若同一 chunk 内两个概念解决同一问题或表达同一思想但不存在任何结构链接无 import、无 call、无 citation应添加一条标记为INFERRED的semantically_similar_to边confidence_score反映相似程度0.6–0.95。规范给出了三个示例两个都校验用户输入却互不调用的函数代码中的类与论文中的概念描述同一算法两个以不同方式处理同一失败模式的错误类型。并强调克制只在相似性确实非显而易见且跨切面时才添加对显而易见相似的对象不要建边。2.6 超边hyperedges成组关系的一等公民当 3 个及以上节点共同参与一个仅靠成对边无法表达的共享概念、流程或模式时向顶层hyperedges数组添加超边。规范给出三类示例实现同一协议/接口的所有类认证流程中的全部函数即使它们并非两两互调论文章节中构成一个完整思想的全体概念。使用原则是 sparingly——只有当成组关系提供了成对边之外的信息时才加且每个 chunk 最多 3 条超边。2.7 YAML frontmatter 溯源字段透传若文件带 YAML frontmatter--- ... ---其中的source_url、captured_at、author、contributor必须复制该文件产出的每一个节点上。这是图谱级溯源provenance的基础一个概念节点最终能回答出自哪个 URL、谁采集的、何时。三、离散置信度评分量表为什么禁止 0.5规范对confidence_score的规定是全文最反直觉的部分——它是离散量表而非连续区间边等级分值规则EXTRACTED恒为1.0INFERRED从 {0.95,0.85,0.75,0.65,0.55} 中恰好选一个禁止 0.5AMBIGUOUS0.1–0.3五档 INFERRED 分值各有语义0.95直接结构证据共享数据结构、文件间命名字符引用0.85强推断清晰的功能对齐但无直接符号链接0.75合理推断共享问题域 形态相似需要解释;0.65弱推断主题相关无形态证据0.55推测但可信仅表面共现。规范还罕见地写入了为什么模型对离散量表的遵循度显著高于连续区间生产环境观测到双峰分布50% 集中在 0.540% 集中在 0.85说明区间式引导正在被坍缩成二值选择。最后一条兜底若没有一档合适把边标为AMBIGUOUS而不是选 0.4 或更低。这条规则在代码里被逐字执行并测试。graphify/export.py 中为缺失分数的边提供了回退值_CONFIDENCE_SCORE_DEFAULTS {EXTRACTED: 1.0, INFERRED: 0.55, AMBIGUOUS: 0.2}注释解释了历史旧版 INFERRED 默认 0.5恰恰是规范明文禁止的值且不在离散集合中现在改为取量表下限0.55——缺失分数代表关于强度的证据缺失诚实的回退应是量表允许的最弱值而不是读起来像抛硬币的中点。tests/test_inferred_confidence_rubric.py 进一步把这条契约焊死断言默认值 ≠ 0.5、默认值 ∈ 量表集合并扫描extract.py、symbol_resolution.py、extractors/engine.py、extractors/resolution.py四个 AST 发射点确保没有任何模块硬编码量表外的字面量如历史上的 0.8 和 0.5。也就是说LLM 子代理和确定性 AST 抽取器被要求遵守同一把评分尺测试保证两者不会漂移。四、节点 ID 确定性规则与 AST 抽取器逐字节对齐节点 ID 规则是整份规范中最长、最严苛的一段因为ID 是 LLM 片段与 AST 片段在合并时唯一能拼到一起的键。规则要点小写只允许[a-z0-9_]无点、无斜杠格式{stem}_{entity}stem是完整的仓库相对路径去掉扩展名保留每一级路径段、各段小写并把非字母数字替换为_后拼接entity是符号名做同样归一化顶层文件无父目录如setup.py只用文件名字干setup_my_func禁止追加 chunk 号、序号或任何后缀不允许_c1、_c2、_chunk2。ID 必须只由 label 确定性产生——同一实体无论落在哪个 chunk 处理必须产出同一 ID。规范给出四个 worked example测试会逐条解析并验证它们见下文文件 符号生成的 IDsrc/auth/session.pyValidateTokensrc_auth_session_validatetokenlib/utils/helpers.pyparse_urllib_utils_helpers_parse_urltests/test_foo.py_helpertests_test_foo_helperdocs/v1/api/README.mdgetUserdocs_v1_api_readme_getuser规范同时锁死了两个错误形态作为反例只用文件名session_validatetoken或只带直接父目录auth_session_validatetoken都会与 AST 抽取器产出的 ID 不一致从而制造孤儿幽灵重复节点。4.1 为什么必须是完整仓库相对路径CHANGELOG.md 记录了这次演进早期版本 ID 的 stem 只取直接父目录 文件名导致不同目录下的同名文件碰撞成同一个最后写入者赢的节点并静默丢图内容docs/v1/api/README.md与docs/v2/api/README.md都会坍缩成api_readme。修复后 stem 变为完整仓库相对路径docs_v1_api_readmevsdocs_v2_api_readme并且 AST 抽取器、LLM 系统提示、本规范文件与两处手写的 stem 辅助函数全部对齐到同一条规则——正是为了消灭 #1509 那类AST 与 LLM 两套 ID 各说各话的幽灵重复。规范还给了迁移建议若项目是在旧的直接父目录格式下构建的用户应运行graphify extract --force干净重建。4.2 源码层面的三方对齐与漂移守卫graphify/ids.py 是节点 ID 归一化的单一事实源模块 docstring 开宗明义三个独立的 ID 生产者必须达成一致否则同一个体会被裂解成互不相连的幽灵节点——① AST 抽取器extract._make_id② 语义子代理LLM遵循本规范③ 图构建器build._normalize_id当 LLM 输出的 ID 标点或大小写略有出入时重对齐边端点。normalize_idgraphify/ids.py的实现细节值得注意先对casefold NFKC迭代到不动点两者不可交换单趟不够例如土耳其语İslemYap会产生含组合字符 U0307 的中间结果再把[^\w]连续段替换为单个下划线re.UNICODE保证 CJK/西里尔/阿拉伯字母存活、折叠重复下划线、去首尾下划线并保证幂等。make_idgraphify/ids.py则把各段拼合后走同一归一化与构建器产出完全相同。更妙的是仓库为这份手写散文设置了自动化漂移守卫tests/test_extraction_spec_ids.py 用正则([^])\s*\\s*([^])\s*→\s*([^])从所有宿主的extraction-spec.md含graphify/skills/与tools/skillgen/fragments/中解析出每一个 worked example然后调用真实生产函数_make_id(_file_stem(Path(path)), entity)复现并断言一致tests/test_extraction_spec_ids.py。这意味着规范示例被改成错误值、或 ID 函数改动导致文档示例失效两种漂移都会让 CI 失败。测试还额外锁定反例_make_id(session, ValidateToken)仅文件名与_make_id(auth, session, ValidateToken)仅直接父目录都必须 ≠ 正确值tests/test_extraction_spec_ids.py确保警告过错的形态本身不会过期。五、source_file 逐字路径与 CHUNK_PATH 写入增量更新的最后一道细节5.1 source_file 必须逐字照抄 FILE_LIST规范要求每个节点、每条边、每个超边的source_file都设置为起源文件在 FILE_LIST 中出现时的路径——逐字、绝对不得缩短为 basename、不得重新相对化、不得剥离任何目录前缀、不得改动分隔符引擎会在下游归一化分隔符并相对化到构建根。这条看似苛刻的约束服务于增量更新全量构建与graphify extract --update必须落在同一套节点键基准上build_merge的replace-on-re-extract重抽取时替换既有节点而非累积重复才能匹配到已有节点。CHANGELOG.md 中的 #1366 正是这条契约的实战注脚曾因--update运行中source_file基准漂移变更文件的节点被误判为已删除文件的残留而遭剪除修复方案就是全量构建也传root给build_from_json且抽取规范把source_file钉死在逐字路径上使全量构建与增量更新永不漂移。5.2 CHUNK_PATH必须用 Write 工具写到绝对路径提示词结尾规定子代理用 Write 工具把 JSON 写到确切的绝对路径CHUNK_PATH并解释了原因——相对路径会被 Write 相对一个未定义的 cwd 解析文件会被静默丢失。skill-agents.md 给出了主代理侧的配套动作派单前PROJECT_ROOT$(pwd)为 chunk N 派生CHUNK_PATH${PROJECT_ROOT}/graphify-out/.graphify_chunk_0N.json。Step B3 的收集逻辑也把chunk 文件是否落盘当作子代理成功的唯一信号文件缺失通常意味着子代理被派成了只读类型此时应打印警告提示改用 general-purpose 代理而不是静默跳过若超过半数 chunk 失败则整体停摆并要求重跑。5.3 输出 Schema 全貌规范给出的完整 Schema原文骨架如下四个顶层键缺一不可{ 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 }注意两点工程细节tokens在子代理输出中恒为占位 0真实值由主代理从 Agent 工具结果的usage字段读回、合并前写回 chunk JSONskill-agents.md 的 Step B3 给出了合并脚本relation枚举中rationale_for与rationale 存属性不建节点并存——前者用于显式表达A 是 B 的理由这类关系边后者约束节点建模方式二者不冲突。六、提示词版本化规范文件本身就是缓存命名空间这份提示词还有第二个、隐藏的身份语义缓存的归属凭证。skill-agents.md 的 Step B0 要求把SPEC_PATH本规范文件的绝对路径同时传给缓存读取check_semantic_cache与写入save_semantic_cache。graphify/cache.py 的prompt_fingerprint对提示词文本做 CRLF→LF 归一化、逐行 rstrip、去尾部空白后取 sha256 前缀作为缓存命名空间cache/semantic/p{fingerprint}/。这带来两个可验证的性质源自 #1939升级 graphify改了提示词旧提示词产出的缓存条目全部失配被重新抽取而非静默重放——此前曾因缓存键只有sha256(内容路径)而缺少提示词分量导致跑完返回 0、cost.json 看起来便宜、图里却混着两代提示词的抽取结果升级未触碰提示词缓存条目跨版本存活不浪费重新计费。而 CRLF 归一化解决的是 Windows 检出与 LF 写缓存之间同一份规范、两个指纹的问题——否则每次 Windows 运行都会伪装成提示词变更而触发全量重抽。_resolve_prompt_fpgraphify/cache.py还刻意把提示词文本与含提示词的文件路径设计为两个独立参数因为把路径字符串本身当文本去哈希会得到稳定、可信、但什么都没跟踪到的错误指纹——对缓存而言静默错配比直接失败更危险不可读的规范文件会降级到无版本命名空间并显式警告而不是让一次抽取因缓存问题而中止。七、两条抽取路径的契约收敛graphify 存在第二条原生后端路径graphify extract --backend gemini|claude|claude-cli|openai|kimi|…直接由 Python 调用 LLM其系统提示是 graphify/llm.py 的_EXTRACTION_SYSTEM。对比两份提示词可以看到同一契约的多处镜像同样的只输出合法 JSON、同样的三级置信度定义、同样的六值file_type枚举、同样的rationale 存属性不建节点、同样的超边规则含每 chunk 最多 3 条、同样的节点 ID 规则与边方向规则calls的 source 恒为调用方。CHANGELOG.md 记录了两者曾漂移的代价原生提示词只给了hyperedges:[]的空 Schema 示例、从未解释什么是超边导致所有原生后端静默产出零超边而 skill 路径正常产出——修复方式就是把3 个及以上节点共同参与的指令与填充后的 Schema 示例同步进原生提示词使两条路径对同一语料给出一致的超边行为。从源码结构看这种一份契约、两条执行路径、测试保证不漂移的模式规范文件 ↔ 原生提示词 ↔ AST 抽取器 ↔ 构建器归一化 ↔ 缓存命名空间正是 graphify 能把 LLM 的不确定性关进笼子、让图谱结果可复现、可增量、可审计的核心机制。八、小结extraction-spec.md 表面上是一份子代理提示词实质是 graphify 语义抽取管线的输出契约其每条规则都对应一类真实事故三级置信度 AMBIGUOUS不省略 → 不确定性显式化进入图而非消失离散评分量表禁 0.5→ 对抗模型对连续区间的坍缩行为并被 graphify/export.py 与 tests/test_inferred_confidence_rubric.py 在 AST 侧同步执行完整仓库相对路径的节点 ID → 消灭同名文件碰撞与 AST/LLM 幽灵重复由 graphify/ids.py 实现、tests/test_extraction_spec_ids.py 用正则解析规范原文逐条验证source_file逐字路径 → 保证全量构建与--update增量运行共用同一节点键基准支撑 replace-on-re-extractCHUNK_PATH绝对路径落盘 → 以文件存在作为子代理成功的唯一信号杜绝静默丢失;提示词指纹命名空间 → 提示词一变缓存即失效未变则跨版本复用。如果你在设计自己的AST LLM 子代理混合抽取管线这份规范几乎是可直接抄录的契约模板把输出 Schema、ID 规则、评分量表、路径纪律与版本归属全部写进提示词再用测试把提示词散文和代码实现对账——graphify 的做法证明对 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），仅供参考