在 Trae 中使用 graphify把任意代码库一键构建成可查询知识图谱的完整运行手册【免费下载链接】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 仓库提供的 AI 编码代理技能Skill其目标是把任意文件夹——包括代码、文档、论文、图片乃至音视频——变成一个跨会话持久化的可查询知识图谱。本文以仓库为 Trae 平台生成的/graphify技能定义即 skill-trae.md 及黄金校验文件 graphify__skill-trae.md为核心逐段拆解该技能的完整运行手册从调用入口的决策逻辑、解释器自举、语料检测、AST 与语义双通道提取、社区发现与诚实审计报告到 graph 就绪后的查询、增量更新与 AGENTS.md 常驻集成。读完你将理解一个Agent 应当如何把 graphify 跑起来并当导游带用户探索图谱的完整协议以及每个环节背后的源码实现。这份文档是什么文档开头是典型的 Skill 元信息YAML frontmattername: graphify description: Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists, where the question should be treated as a graphify query first. Turns any input (code, docs, papers, images, videos) into a persistent knowledge graph with god nodes, community detection, and query/path/explain tools.这告诉宿主 Agent只要用户询问代码库的结构、架构或文件关系尤其是当graphify-out/目录已存在时就应优先把问题当作一次 graphify 图谱查询而不是重新读文件。仓库内真实投放给 Agent 的版本位于 graphify/skill-trae.md同一文件会按宿主平台生成多份变体Claude Code、Codex、Gemini CLI、Trae 等本文档Trae 变体由 tools/skillgen/gen.py 从共享片段tools/skillgen/fragments与平台槽位拼接生成。技能核心能力一句话概括把任意文件夹变成可导航的知识图谱配套社区检测、诚实的审计追踪并产出三类成果——交互式 HTML、GraphRAG 就绪的 JSON、以及通俗易懂的GRAPH_REPORT.md。代码通过本地确定性 AST 解析提取不需要任何向量数据库。/graphify 命令全览一次调用能做什么技能要求 Agent 在收到--help/-h时原样打印## Usage并停止执行任何命令。完整命令面如下这也是本文所有后续章节的索引/graphify # 全流程处理当前目录含 HTML 可视化加 --obsidian 产出笔记库 /graphify path # 全流程处理指定路径 /graphify https://github.com/owner/repo # 先 clone 仓库再对本地副本跑全流程 /graphify https://github.com/owner/repo --branch branch # clone 指定分支 /graphify url1 url2 ... # clone 多个仓库各自建图后合并成一张跨仓库图 /graphify path --mode deep # 深度提取产出更丰富的 INFERRED 边 /graphify path --update # 增量模式只对新增/变更文件重提取 /graphify path --directed # 构建有向图保留 source→target 边方向 /graphify path --whisper-model medium # 使用更大的 Whisper 模型提升转写精度 /graphify path --cluster-only # 基于已有图谱重跑聚类 /graphify path --no-viz # 跳过可视化只出报告 JSON /graphify path --html # HTML 默认生成此参数为空操作 /graphify path --svg # 额外导出 graph.svg可嵌入 Notion、GitHub /graphify path --graphml # 导出 graph.graphmlGephi、yEd /graphify path --neo4j # 为 Neo4j 生成 graphify-out/cypher.txt /graphify path --neo4j-push bolt://localhost:7687 # 直接推送到 Neo4j /graphify path --falkordb # 为 FalkorDB 生成 graphify-out/cypher.txt /graphify path --falkordb-push falkordb://localhost:6379 # 直接推送到 FalkorDB /graphify path --mcp # 启动 MCP stdio 服务供 Agent 访问 /graphify path --watch # 监听文件夹代码变更后自动重建无需 LLM /graphify path --wiki # 构建可供 Agent 爬取的 wikiindex.md 每个社区一篇文章 /graphify path --obsidian --obsidian-dir ~/vaults/my-project # 把笔记库写到自定义路径 /graphify add url # 抓取 URL 存入 ./raw 并更新图谱 /graphify add url --author Name # 标记作者 /graphify add url --contributor Name # 标记贡献者 /graphify query question # BFS 遍历广度上下文 /graphify query question --dfs # DFS追踪特定链路 /graphify query question --budget 1500 # 把回答截断到 N token /graphify path AuthModule Database # 两个概念间的最短路径 /graphify explain SwinTransformer # 对某个节点的通俗解释参数可按语义分组记忆构建模式--mode deep、--directed、--update、--cluster-only、输出物--html、--no-viz、--svg、--graphml、--neo4j/--neo4j-push、--falkordb/--falkordb-push、--wiki、--obsidian、运行形态--watch、--mcp与查询工具query/path/explain/add。调用时的首要决策逻辑技能在What You Must Do When Invoked里定义了三条硬性规则任何一次调用都必须先过这几道闸--help短路收到/graphify --help或-h且无其他参数时原样打印 Usage 块并返回不运行任何命令、不做文件检测、不把路径默认成.。Fast path——图谱已存在调用前先检查当前工作目录下是否存在graphify-out/graph.json。若存在且用户请求是对代码库的自然语言提问如X 怎么工作的谁调用了 Y追踪 Z 的数据流而不是显式重建命令--update、--cluster-only、裸路径/URL则完全跳过 Steps 1–5直接执行graphify query question。文档明确要求不要跑 detect、不要检查语料大小、不要要求用户缩小问题范围——图谱已经建好直接用。路径缺省与 URL 识别未给路径默认用当前目录.不得反问用户路径以https://github.com/或http://github.com/开头时先执行 Step 0clone再对解析出的本地路径继续。Fast path 之所以成立在于图的持久化知识图谱产物落在graphify-out/下跨会话保留查询不需要重建。仓库中 worked/ 目录保留了多个真实语料的产物示例如graph.json、GRAPH_REPORT.md、review.md可直观看到图就绪后的形态。Step 0GitHub clone 与多路径合并仅当输入是 GitHub URL 或需要合并的多个本地子目录时执行。该步骤指导 Agent 读取 github-and-merge.md按其中的 clone、跨仓库合并与 monorepo 流程处理再回到解析后的本地路径继续。普通本地路径直接跳过本步。这正是graphify https://github.com/owner/repo与多 URL 一键生成跨仓库图的能力入口。Step 1解释器自举环境探测协议在真实终端环境里graphify 装在哪是最容易翻车的一环uv tool、pipx、venv、系统安装都可能是宿主。技能为此设计了解释器探测脚本按优先级依次尝试uv tool 安装现代 Mac/Linux 上最可靠uv tool run --from graphifyy python -c import sys; print(sys.executable)从 graphify 二进制 shebang 读取覆盖 pipx 与直接 pip 安装head -1 $(which graphify)并对提取出的解释器做一次import graphify自检回退python3。探测失败则按顺序执行uv tool install --upgrade graphifyy或pip install graphifyy必要时加--break-system-packages。随后把选定的解释器路径写入graphify-out/.graphify_python把扫描根目录绝对路径写入graphify-out/.graphify_root——这两个 sidecar 文件贯穿全流程后续所有 bash 块都用$(cat graphify-out/.graphify_python)替换裸python3保证每次子进程使用同一个解释器.graphify_root让无参的graphify update能找回上次扫描的根目录文档还提供了Interpreter guard在跑--update、--cluster-only、query、path、explain、add等子命令前若发现.graphify_python缺失例如用户删了graphify-out/先用同样的三段探测逻辑重新解析并写回。从源码看这类运行时把正确解释器喂给子进程的模式在 cli.py、install.py 中贯穿始终sidecar 是让多步骤流水线复用同一环境的约定。Step 2语料检测与规模预警检测阶段调用 detect.py 的detect(Path(INPUT_PATH))返回按类型分组的文件清单与规模统计。技能规定结果要写进graphify-out/.graphify_detect.json通过 Python 而非 shell 重定向写入以保证在 PowerShell 宿主上控制台编码不漂移随后向用户展示简洁摘要而非原始 JSONCorpus: X files · ~Y words code: N files (.py .ts .go ...) docs: N files (.md .txt ...) papers: N files (.pdf ...) images: N files video: N files (.mp4 .mp3 ...)为 0 的类别直接省略。之后按三种情形分支total_files为 0 → 停止并提示 No supported files found in [path].skipped_sensitive非空 → 报告数量并列出声明的文件名让被误判为敏感文件的源码/文档可以被发现并改名或移走total_words 2,000,000或total_files 500→ 展示预警并按文件数统计 Top 5 一级子目录把scan_root前缀剥掉取首个路径分量scan_root直属文件记为(root)自动剔除scan_root/graphify-out/下的转换 sidecar然后请用户选择要处理的子目录。特例若所有文件都在(root)下、根本不存在子目录则不要求收窄改为建议--no-cluster跳过昂贵的聚类步骤继续。仓库测试 test_detect.py 覆盖了该函数的分组与统计行为文档对不许跳过语料规模检查的坚持也写入结尾的 Honesty Rules。Step 2.5音视频转写仅当detect返回了 video 类文件才执行按 transcribe.md 先把视频/音频转成文本再把转写稿当作 doc 文件进入 Step 3。--whisper-model medium即用于此步选择更大的 Whisper 模型提升准确率。Step 3实体与关系提取——双通道并行这是全手册最核心的步骤明确分为两条通道结构化提取Structural确定性、免费对代码做 AST 解析无 LLM、无 API Key语义提取SemanticLLM、消耗 token仅面向文档、论文与图片。关于 API Key 的铁律技能用加粗注释强调graphify 不需要 API Key永远不要向用户索取也永远不要因为缺 Key 而阻塞。具体语义纯代码语料最常见的/graphify .完全跳过语义通道Part A 后直接进 Part C语义提取只在已设置GEMINI_API_KEY/GOOGLE_API_KEY时使用 Gemini否则由宿主 Agent 自己充当 LLMgraphify不读ANTHROPIC_API_KEY、OPENAI_API_KEY或任何其他供应商 Key——若你发现自己正要为缺 Key 而停顿那是对本技能的误读若两个 Key 都未设置只打印一次提示Tip: set GEMINI_API_KEY or GOOGLE_API_KEY to use Gemini for semantic extraction (pip install graphifyy[gemini])然后继续不等待用户设置 Key 后语义通道改走 llm.py 的extract_corpus_parallel(files, backendgemini)。默认 Gemini 模型为gemini-3-flash-preview可用GRAPHIFY_GEMINI_MODEL或命令行--model覆盖。技能还要求Part AAST与 Part B语义并行启动——两类通道处理不同文件类型互不干扰文档注明大语料上并行可节省约 5–15 秒。Part A代码的结构化提取对detect结果中 code 类文件逐一展开目录调用 extract.py 的collect_files再调用extract(code_files, cache_root...)做 AST 提取结果写graphify-out/.graphify_ast.json。无代码文件则写入空结果并打印 No code files - skipping AST extraction。从源码结构看extractors/ 目录为每种语言提供解析器base.py 定义统一基类engine.py 调度extraction-spec.md 则定义节点/边 schema 与 node-ID 规则。Part B语义提取并行子代理 缓存先看Fast path若检测到零个 doc/paper/image纯代码语料整段跳过但要先写一个空的 semantic 文件.graphify_semantic.json——因为 Part C 的合并无条件读取它缺了纯代码运行会抛FileNotFoundError。有语义文件时的流程分四小步且有一个强制性要求必须使用 Task/Agent 工具做并行分派禁止 Agent 自己逐文件阅读文档称这样慢 5–10 倍。分派前先打印耗时预估约ceil(未缓存非代码文件数 / 22)个代理每批约 45 秒。B0 查缓存对 document/paper/image 三类文件调用 cache.py 的check_semantic_cache(...)参数含prompt_file即 extraction-spec.md 的绝对路径。缓存条目以提示词为归属graphify 升级改了提示词旧提示词产出的条目会被重提取未变的提示词保留条目。命中结果写.graphify_cached.json未命中列表写.graphify_uncached.txt。只对未缓存文件分派子代理全部命中则直接跳到 Part C。B1 分块把未缓存文件按每块 20–25 个分组每张图片独占一块视觉需要独立上下文尽量把同目录文件放同一块以提高跨文件关系被提取的概率。B2 单条消息内并发分派所有子代理Trae 平台使用 Task 工具所有 chunk 在同一条回复里全部下发以实现并行。此处特别注明了一条 Trae 平台差异Trae 不支持 PreToolUse hooksAGENTS.md 规则才是常驻机制。子代理各自把结果写入graphify-out/.graphify_chunk_NN.json路径必须是绝对路径并携带抽取提示词含 FILE_LIST、CHUNK_NUM、TOTAL_CHUNKS、DEEP_MODE 替换。B3 收集、缓存、合并以chunk_NN.json是否落盘作为成功信号文件缺失说明子代理可能是只读Explore类型需打印警告并建议改用 general-purpose 类型重跑超过一半 chunk 失败/缺失则停止并提示用户确保subagent_typegeneral-purpose。随后把各 chunk 的真实 token 用量来自 Agent 调用的 usage 字段chunk JSON 里占位为 0回写合并成.graphify_semantic_new.json再经save_semantic_cache(...)写缓存、与 cached 结果按节点 id 去重合并成.graphify_semantic.json并清理临时文件。Part CAST 语义合并合并逻辑很直白AST 节点在前语义节点按id去重追加边直接拼接最终写入graphify-out/.graphify_extract.json并打印Merged: X nodes, Y edges (A AST S semantic)。Step 4建图、聚类、分析与产出本步把抽取结果喂给 build.py 的build_from_json(extraction, rootINPUT_PATH, directedIS_DIRECTED)--directed时IS_DIRECTEDTrue建 NetworkXDiGraph保留 source→target 方向否则默认无向Graph随后依次cluster(G)cluster.py做社区发现score_all(G, communities)计算每个社区的 cohesion 分数god_nodes(G)、surprising_connections(G, communities)、suggest_questions(...)均来自 analyze.py产出枢纽节点、跨社区惊喜连接与候选问题to_json(G, communities, graphify-out/graph.json)export.py先导出图谱再写GRAPH_REPORT.mdreport.py 的generate与.graphify_analysis.json。代码里内嵌了两道数据完整性守卫值得单独说明空图守卫build_from_json之后立刻检查number_of_nodes() 0为空则报ERROR: Graph is empty并SystemExit(1)绝不写盘——防止一次空的抽取把已有的好graph.json覆盖掉。缩水守卫shrink-guardto_json在新图节点数小于已存在 graph.json 时会拒绝写入并返回 False对应文档中 #479 号行为。此时不得继续写报告与 sidecar避免报告描述的图并不存在于 graph.json的不一致若确属有意删文件导致的缩水需带--force全量重建。Step 4.5只读的图谱健康检查在建图后、标注前插入一个非破坏性诊断门diagnostics.py 的diagnose_extractionformat_diagnostic_report专门暴露三类静默损坏模式边端点悬挂/缺失、自环边、同端点坍缩边有向/无向各一组计数。有告警则打出GRAPH HEALTH WARNING并在最终摘要中呈现不中止——图仍可用但按 Honesty Rules 必须让问题可见。Step 5社区标注与二次生成读取.graphify_analysis.json为每个社区 key 结合节点标签写 2–5 个词的通俗名字如 Attention Mechanism、Training Pipeline、Data Loading然后把LABELS_DICT代入重新生成用真实标签重新生成建议问题标签影响提问措辞重写GRAPH_REPORT.md并保存.graphify_labels.json供可视化器使用带社区名重新导出to_json(..., community_labelslabels)让graph.json的节点携带最终社区标签。由于使用与 Step 4 相同的抽取节点数相同shrink-guard 可通过若仍拒绝则呈现守卫信息而不是强行绕过。Step 6 与 Step 6b–8Obsidian、HTML 与各导出通道HTML 默认总是生成除非--no-vizObsidian 仅当显式给--obsidian它会为每个节点生成一个文件默认落在graphify-out/obsidian/--obsidian-dir自定义graphify export obsidian # 或graphify export obsidian --dir ~/vaults/my-project graphify export html # 图超过 5000 节点时自动聚合为社区视图随 flag 触发的导出通道汇总如下详见 exports.mdFlag行为目标工具/消费方--wikigraphify export wiki产出index.md 每社区一篇文章供 Agent 爬取的 wiki须在 Step 9 清理前运行--neo4j生成graphify-out/cypher.txtNeo4j 手工导入--neo4j-push uri直推 Neo4j默认bolt://localhost:7687、默认用户neo4j使用 MERGE 可安全重跑Neo4j--falkordb生成cypher.txtOpenCypherFalkorDB 无批量脚本导入故更推荐 pushFalkorDB--falkordb-push uri直推默认falkordb://localhost:6379目标图名默认graphifyMERGE 语义FalkorDB--svggraphify export svggraph.svgNotion、GitHub 内嵌--graphmlgraphify export graphmlGephi、yEd--mcppython -m graphify.serve graphify-out/graph.json启动 stdio MCP 服务暴露query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path等工具Claude Desktop 等任意 MCP Agent此外当语料total_words超过 5,000 时还会自动运行 token 削减基准benchmark。无导出 flag 的默认运行会跳过上述全部步骤。Step 9manifest、成本追踪与收尾汇报收尾阶段做四件事保存 manifest 供增量更新经 cli.py 的_stamped_manifest_files计算应打戳的文件集——只有实际产出语义结果的 doc/paper/image 文件才打戳chunk 失败或遗漏的文件保持未打戳下次--update会重新排队避免内容永久丢失代码文件因 AST 确定性总是打戳。同时清除本轮回派但未打戳文件的陈旧semantic_hash防止被误判为未变更。最终调用 detect.py 的save_manifest以root把 manifest 键相对化到扫描根保证其在克隆/换机间可移植。更新累计成本追踪把本次 input/output token 数与文件数追加到graphify-out/cost.json累积 total 与逐次 runs并打印This run/All time两行。清理临时 sidecar删除.graphify_detect.json、.graphify_extract.json、.graphify_ast.json、.graphify_semantic.json、.graphify_analysis.json及各 chunk 文件仅保留最终产物与 manifest、cost、labels 等长命文件。向用户汇报并只粘贴报告中的三节God Nodes、Surprising Connections、Suggested Questions不贴全文。随后基于最跨越社区边界/桥接节点最意外的那条建议问题主动发起探索邀请The most interesting question this graph can answer: ... Want me to trace it?。用户同意即跑graphify query并从图结构讲解回答且每次回答以自然追问结尾——文档原话The graph is the map. Your job after the pipeline is to be the guide.图就绪之后query / path / explain / update / watch / hooks查询类Fast path 的展开graphify query question之前必须先做约束式查询扩展query.md因为queryCLI 只做 case-folded 子串 IDF 匹配没有词干化、同义词或跨语言匹配用户问authentication而图里叫 Guardian 时字面匹配会返回 0 命中。正确做法是从图的真实词表出发先从graph.json节点标签抽取 token 词表写.vocab.txt再从词表里挑最多 12 个语义匹配的 token 构造扩展查询串并先把选择打印给用户以保证可审计。硬性约束只能选自词表、绝不臆造 token查无概念对应 token 就跳过全无匹配则直说并停止。若 CLI 不可用则回退为内联 NetworkX 遍历networkx.readwrite.json_graph.node_link_graph载入。两种遍历模式按问题类型选择模式Flag适用场景BFS默认—X 连接着什么——广度上下文先看最近邻DFS--dfsX 如何到达 Y——追踪特定依赖链回答只依据图内内容引用具体事实时标注source_location图里信息不足就明说不臆造边。path两概念间最短路径与explain节点的通俗解释同见此参考文档。维护类--update 与 --cluster-only两者均为非默认子命令详见 update.md。--update先经 detect.py 的detect_incremental找出新增/变更/删除文件纯代码变更时跳过语义通道直跑 AST含 doc/paper/image/video 变更时按需先转写再走全量 3A–3C只删不改时写空抽取让合并去剪枝。合并用 build.py 的build_merge直接读 graph.json不经 NetworkX 往返保证边方向不丢失以replace-on-re-extract语义替换重提取内容、只对真正删除的文件做prune_sources。--cluster-only则基于既有图重跑聚类。常驻类add、--watch 与 AGENTS.md 集成/graphify add url把 URL 抓入语料与--watch文件变更自动重建见 add-watch.md。把 graphify 变成项目的常驻机制见 hooks.md——这正是 Trae 平台的特殊之处graphify trae install # 或graphify trae-cn install该命令向项目本地AGENTS.md写入## graphify一节指示 Trae 在回答代码库问题前先查图谱、代码变更后重建图未来会话无需手动/graphify。卸载用graphify trae uninstall或trae-cn。需要特别强调的是Trae 变体的说明明示与 Claude Code 不同Trae 不支持 PreToolUse hooksAGENTS.md 规则是唯一常驻机制——不存在工具调用时自动重建代码变更后需要手动/graphify --update刷新图谱。参考片段在 tools/skillgen/fragments/dispatch/task-tool-disk-trae.md 与对应平台槽位中均有体现tools/skillgen/gen.py的注释也记录了这一 per-host 差异的生成逻辑。Honesty Rules不可妥协的诚实底线技能文档以五条规则收束这些约束既写给 Agent也定义了 graphify 产出物的可信基线绝不臆造边不确定就用AMBIGUOUS审计追踪里 EXTRACTED / INFERRED / AMBIGUOUS 三档真实可见绝不小规模检测预警2,000,000词或500文件的收窄询问报告里始终展示 token 成本不把 cohesion 分数藏在符号背后展示原始数值超过 5,000 节点的图谱运行 HTML 可视化前必须警告用户HTML 导出会自动聚合为社区视图也是出于此考虑。与 Trae 平台的契合点小结把这份技能放到 Trae 的具体使用语境中可以提炼出四条实操要点任务分派走 Task 工具语义提取强制使用并行子代理全部 chunk 在同一条消息内下发子代理必须是可写盘的 general-purpose 类型只读 Explore 类型会导致 chunk 文件缺失。常驻集成靠 AGENTS.md 而非 hooksTrae 没有 PreToolUse hooks安装后手动--update刷新是预期工作方式。不需要任何 LLM API Key 也能起步纯代码语料全程 AST带文档时若没设 Gemini Key宿主 Agent 自己就是语义引擎。诚实的中间态是产品特性从 AST/INFERRED/AMBIGUOUS 边标注、Graph health 检查到拒绝缩水的 shrink-guard 与每次都展示的 token 成本整条流水线把图是怎么来的、花了多少、哪里不确定全程透明。延伸阅读技能原始文档graphify/skill-trae.md生成黄金文件tools/skillgen/expected/graphify__skill-trae.md技能携带的参考手册Trae 变体均在 graphify/skills/trae/references 下github-and-merge.md、transcribe.md、extraction-spec.md、update.md、query.md、add-watch.md、hooks.md、exports.md流水线对应源码detect.py语料检测与 manifest、cache.py语义缓存、extract.py 与 extractors/AST 提取、build.py建图/合并、cluster.py社区发现、analyze.pygod nodes/惊喜连接/问题生成、report.py报告、export.pyJSON/HTML 导出、diagnostics.py健康检查、serve.pyMCP 服务生成体系片段库 tools/skillgen/fragments 与生成器 tools/skillgen/gen.py实拍语料产物示例见 worked/含graph.json、GRAPH_REPORT.md、review.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考