graphify 在 Codex 平台上的并行语义抽取spawn_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 的/graphify技能在其 v8 代码库中把文档/论文/图片的语义抽取拆分成了可供多平台复用的片段体系。tools/skillgen/fragments/dispatch/codex-agenttask.md正是其中专为 OpenAI Codex 定制的Step B2 —— 单条消息内派发全部子代理执行片段Codex 不使用 Claude Code 式的 Agent 工具与磁盘 chunk 文件而是以spawn_agentwait_agentclose_agent三件套实现全并行语义抽取并把结果在内存中汇总。读完本文你将掌握如何开启 Codex 的multi_agent特性、如何按 chunk 构造带任务委托框架的子代理提示词、为什么 Codex 路径没有逐 chunk 落盘与磁盘成功检查、以及在纯代码语料corpus下为何整个 Part B 与抽取规范extraction-spec都永远不会被读取。一段代码片段在整个 skill 工程中的位置graphify 的 Skill 文案不是手写的单一大文件而是片段fragment为唯一编辑源、产物artifact为生成结果的构建式工程。核心模板 fragments/core/core.md 中有一个DISPATCH占位符它位于 Step 3 Part B 的Step B1 - 分块与Step B3 - 汇总、缓存与合并之间专门承载如何把语义子代理真正派发出去这一步的平台差异。生成器 gen.py 在渲染平台产物时按 platforms.toml 中每个[platform.key]声明的dispatch字段把对应片段替换进该占位符。例如[platform.codex]→dispatch codex-agenttask即读取 codex-agenttask.md[platform.claude]→dispatch agent-tool-disk使用 agent-tool-disk.md[platform.trae]→dispatch task-tool-disk-trae另有 manual-paste.md、opencode-mention.md 等。把七个 dispatch 片段并排看它们同目录于 fragments/dispatch/就得到一份各 AI 宿主如何并行抽取的平台对照表Claude 靠 Agent 工具写磁盘、Trae/Amp 靠 Task 工具、VS Code 靠手动粘贴、OpenCode 靠 提及而 Codex 靠本文的主角——原生子代理句柄 API。该片段的最终渲染产物可见 graphify/skill-codex.md 中 Step B2 整段仓库还通过 tools/skillgen/expected/graphify__skill-codex.md 的快照对渲染结果做字节级防漂移校验。Codex 与原版 Agent 工具的本质差异阅读本片段前先建立对照。Claude 风格平台的派发协议agent-tool-disk.md依赖两件事一是在同一响应里多次调用 Agent 工具让宿主把它们并行调度二是子代理把结果写入磁盘上每个 chunk 对应的.graphify_chunk_0N.json绝对路径主代理之后以文件是否存在作为成功信号。Codex 提供的是另一套更底层的句柄式 API。本片段第一段引用块就明确给出了三条铁律Codex platform:Usesspawn_agentwait_agentclose_agentinstead of the Agent tool. Requiresmulti_agent trueunder[features]in~/.codex/config.toml. Ifspawn_agentis unavailable, tell the user to add that config and restart Codex.要点可归纳为工具不同用spawn_agent生成子代理替代 Agent 工具配置前置必须在~/.codex/config.toml的[features]段开启multi_agent true故障定位前置若spawn_agent不可用不要自行降级而是明确告知用户补充该配置并重启 Codex 后重试。全并行派发同一响应内 spawn 全部 chunk片段正文给出的操作纪律与 Agent 工具版一脉相承但落地方式不同——把一次spawn_agent视为一个 chunk 的派出动作全部放在同一条响应里发出spawn_agent(agent_typeworker, messageYour task is to perform the following. Follow the instructions below exactly.\n\nagent-instructions\n[extraction prompt, with FILE_LIST, CHUNK_NUM, TOTAL_CHUNKS, DEEP_MODE substituted]\n/agent-instructions\n\nExecute this now. Output ONLY the structured JSON response.)逐项拆解这个模板要素含义agent_typeworker声明这是执行型 worker而非只读探查型代理message头尾框架Your task is to perform the following. Follow the instructions below exactly. 收尾 Execute this now. Output ONLY the structured JSON response.是任务委托task-delegation包裹层agent-instructions内层被逐字传入的抽取提示词本体即把抽取规范中需要按批次实例化的四个变量替换后的版本四个替换变量FILE_LIST本 chunk 文件清单、CHUNK_NUM第几块、TOTAL_CHUNKS总块数、DEEP_MODE是否--mode deep输出约束只输出结构化 JSON杜绝解释性文字与主技能Step 3入口的约定呼应--mode deep一旦在原始调用中出现就必须转换成DEEP_MODEtrue传递给每一个子代理且整个流程不能丢失该标记core.md Step 3 开头有专门提醒。为什么要强调同一响应片段的潜在逻辑是只有在同一响应中发起全部spawn_agentCodex 运行时才会把它们放进同一个并行批次若发一个等一个就退化成了串行使分块并行失去意义——这与 agent-tool-disk.md 中If you make one Agent call, wait, then make another, you are doing it sequentially and defeating the purpose的表达完全同构只是换成了 spawn 句法。内存收集wait_agent close_agent 顺序回收所有子代理被派出后主代理进入收集阶段同样是一行模式对每个句柄重复执行result wait_agent(handle); close_agent(handle) # repeat per handlewait_agent(handle)阻塞等待对应子代理产出结果取回resultclose_agent(handle)用完即关释放句柄资源每个句柄顺序处理随后把各结果中的nodes/edges/hyperedges跨结果累加汇总写入graphify-out/.graphify_semantic_new.json。这里有一个本片段反复强调、且最容易踩坑的平台架构性差异Codex collects in memory, so there are no per-chunk files on disk; the disk-based success checks in Step B3 do not apply — a chunk that returns invalid JSON is the failure signal instead.翻译成实操语言就是三条推论不要期待.graphify_chunk_NN.json出现。那是 Agent 工具版Claude/Windows 等的产物Codex 版子代理把 JSON 直接作为返回值带回磁盘上自始至终没有中间 chunk 文件成功信号的定义变了。Step B3 原文中检查文件在磁盘上存在的成功判据在 Codex 路径不适用Codex 以能否把wait_agent的返回解析为合法 JSON作为成败分界失败处理就落在 JSON 解析上——某个 chunk 返回非法 JSON 即为该块失败的信号应参照 Step B3 的通用策略警告并跳过该块而不是中止整个流程。这一设计还牵动下游的缓存与清单逻辑既然没有磁盘 chunk 文件后续.graphify_cached.json/.graphify_uncached.txt/缓存写入/清单盖章stamping都以.graphify_semantic_new.json为唯一数据来源因此该文件的字段结构含input_tokens/output_tokens占位零值必须与 Part C 合并代码期望的 schema 完全一致。抽取规范只在需要时才加载片段的最后一段回答了子代理的提示词正文从哪来、何时读Seereferences/extraction-spec.mdfor the compact subagent prompt (rules, node-ID format, confidence rubric, hyperedge and vision rules, JSON schema). Load it only here, only when at least one chunk holds a doc, paper, or image; a pure-code corpus has skipped Part B and never reads it. Pass each agent that prompt verbatim with FILE_LIST, CHUNK_NUM, TOTAL_CHUNKS, and DEEP_MODE substituted, and have it return the JSON inline.约束分三层路径提示词正文由与技能同目录的 graphify/skills/codex/references/extraction-spec.md 承载其源片段在 tools/skillgen/fragments/references/shared/extraction-spec-compact.mdCodex 平台在 platforms.toml 中声明了extraction compact取精简版时机仅在至少一个 chunk 包含文档doc、论文paper或图片image时才在此处读取纯代码语料已整段跳过 Part B永远不需要读它以省 token传递方式把提示词**逐字verbatim**喂给每个子代理仅替换四个批次变量并要求子代理把 JSON 内联inline返回不写文件。精简版抽取规范里到底约束了什么为了让读者理解传给 Codex worker 的这段紧凑指令分量几何下面按 extraction-spec-compact.md 原文归纳其核心契约Codex 渲染版与此字节一致置信度三段式confidence rubricEXTRACTED关系在源中显式存在import、call、citationconfidence_score 恒为1.0INFERRED合理推断共享结构、隐含依赖score 必须且只能从0.95 / 0.85 / 0.75 / 0.65 / 0.55五档中选一严禁用 0.5 作默认值都不贴切就转AMBIGUOUSAMBIGUOUS不确定也要标记而非省略score 取0.1–0.3。file_type 六值枚举code | document | paper | image | rationale | concept其余任何值都会被拒绝rationale用于承载为什么做此决策的概念类节点且决策理由优先存为节点属性而非独立节点。仓库在 gen.py 中把这六值枚举定义为唯一超集并通过schema-singleton守卫校验所有平台渲染产物字节一致。节点 ID 确定性规则仅用小写[a-z0-9_]格式{stem}_{entity}stem 是完整仓库相对路径去掉扩展名、各级目录以_拼接并逐段小写化的结果entity 是同样规范化的符号名例如src/auth/session.pyValidateToken→src_auth_session_validatetoken。规则要求与 AST 抽取器产生的 ID 完全一致、不附加任何 chunk/序号后缀——这是后续 AST语义两路结果能按 ID 去重合并Part C的前提。其他抽取纪律代码文件只补 AST 抓不到的语义边不得重抽 importcalls边 source 恒为调用方、target 恒为被调方且不跨语言语义相似无结构链接但同题同思路时添加semantically_similar_toINFERRED、score0.6–0.95只限非显然的跨文件链接超边hyperedge3 个以上节点共享某概念/流/模式且两两边无法表达时才建节制使用每 chunk 最多 3 条YAML frontmattersource_url、captured_at、author、contributor需拷贝到该文件产出的每个节点上图片走视觉理解明白这张图是什么而非只做 OCRsource_file必须逐字使用 FILE_LIST 中路径不缩短 basename、不改写相对化保证全量构建与--update共用一个基准避免合并替换失配造成重复节点输出只有 JSON禁止解释文字、markdown 围栏或前言。与磁盘版派发的对照一份双轨运维清单把本片段与其兄弟片段 agent-tool-disk.md 对照即可得到一份可直接用于排障的双轨清单维度Codexspawn_agent 版本文Claude 等Agent 工具版派发原语spawn_agent(agent_typeworker, ...)Agent tool 调用须general-purpose前置配置~/.codex/config.toml的[features]开启multi_agent true无但禁用只读 Explore 型并行手段同一响应内发出全部 spawn同一响应内发出全部 Agent 调用子代理落盘不落盘JSON 内联返回写入绝对路径.graphify_chunk_0N.json成功信号wait_agent返回可解析为合法 JSONchunk 文件在磁盘存在且含合法nodes/edges汇总方式内存累加后写.graphify_semantic_new.json磁盘 glob 合并后再写.graphify_semantic_new.json失败语义某 chunk 返回非法 JSON 即该块失败跳过不中止文件缺失提示子代理可能是只读型非法 JSON 跳过过半失败则中止并提示改用general-purpose可以看到两份协议在单消息全量派发、失败单块降级、最终数据归一进.graphify_semantic_new.json上完全一致分歧只发生在传输层——这也是为什么 gen.py 允许两者共享同一份 core 模板、仅以dispatch槽位隔离差异。从该生成结构可以推断若未来 Codex 改变子代理 API 形态改动点应收敛在这一个片段内而不必触碰 Step B0/B1/B3 的缓存与合并逻辑。生产建议与常见误区结合片段正文与仓库守卫机制实际接入或二次开发时值得注意先验配置后验可用。multi_agent true缺失时spawn_agent直接不可用——把配置 → 重启 Codex → 重试作为标准修复路径而不是临时改成串行 Agent 调用那会违背该技能的并行纪律并大幅拖慢大型语料。不要给 Codex 路径套磁盘检查。若在某 Codex 实现中沿用等待.graphify_chunk_NN.json的旧逻辑会因文件从不出现而误报 chunk 失败正确信号永远是对wait_agent返回值做 JSON 解析。提示词逐字传递宁可统一不要本地改写。四个占位变量的替换是唯一允许的差异同时注意 core.md 与缓存设计约定抽取提示文本本身是语义缓存条目的归属键prompt 变更会令旧缓存条目失效重抽逐字传递也是缓存正确性的保障。纯代码语料走快路径。无 doc/paper/image 时整个 Part B 被跳过自然也不会加载抽取规范与派发 worker——这正是免费 AST 按需 LLM架构的体现。回归防护由工程机制兜底。改完片段后需在仓库根目录运行python -m tools.skillgen --check验证渲染产物与 expected/ 快照无漂移生成入口与守卫实现见 gen.py。综上所述codex-agenttask.md以不到 30 行定义了一条完整、可执行、可与其它平台等价的Codex 语义抽取派发协议一处[features]配置、一轮同响应spawn_agent、一轮wait_agent/close_agent内存回收外加按需逐字加载的紧凑抽取规范——理解它也就理解了 graphify 如何在每种 AI 宿主 API 各不同的现实约束下让知识图谱的语义侧流水线保持行为一致与可审计。【免费下载链接】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），仅供参考