graphify 增量内容接入指南/graphify addURL 抓取与--watch目录监听自动更新全解析【免费下载链接】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 参考文档 add-watch 展开系统讲解两条「非默认构建」的增量数据接入路径/graphify add url把远程 URL 抓取为语料文件并入图与--watch后台监听目录、文件变化自动触发重建。读完你可以掌握完整的调用命令、URL 类型自动识别规则、防重名写入与错误处理约定以及「纯代码变更走 AST 重建、文档/图片变更写 needs_update 标记等待语义化更新」的分层触发机制并将其嵌入到 Agent 多轮写入的工作流中。背景提示graphify 的目标是把任意代码库连同文档、SQL Schema、配置与 PDF转化为可查询的知识图谱add与watch正是持续喂养该语料的两个入口前者把外部网页收进raw/后者让语料变化自动回流到graph.json与GRAPH_REPORT.md。一、何时加载此参考文档此参考文档的加载触发条件是用户在对话中执行了/graphify add url或传入了--watch参数。二者都不属于默认构建流程default build属于显式请求的扩展能力因此 Agent如 AMP、Claude Code、Cursor 等场景下的技能实现需要单独加载该文档来获取精确的调用配方。/graphify add url抓取一个 URL 并把它加入语料corpus随后更新图--watch path启动后台守护进程监控目录并在文件变化时自动更新图。二、/graphify add把远程 URL 接入语料2.1 标准调用脚本参考文档给出的核心执行片段依赖 graphify 输出的解释器定位文件graphify-out/.graphify_pythongraphify 将构建用的 Python 解释器路径记录于此整段命令在独立解释器中运行$(cat graphify-out/.graphify_python) -c import sys from graphify.ingest import ingest from pathlib import Path try: out ingest(URL, Path(./raw), authorAUTHOR, contributorCONTRIBUTOR) print(fSaved to {out}) except ValueError as e: print(ferror: {e}, filesys.stderr) sys.exit(1) except RuntimeError as e: print(ferror: {e}, filesys.stderr) sys.exit(1) 字段替换约定占位符含义来源URL实际要抓取的地址用户在/graphify add后给出的参数AUTHOR用户本人名称用户提供时填写可空CONTRIBUTOR贡献者名称团队图场景用用户提供时填写可空错误处理硬性约定当命令以异常退出ValueError/RuntimeError时Agent 必须把出错原因告诉用户绝不能静默继续。成功保存后还要自动在./raw上执行--update管线把新文件合并进既有图——这正是「add」与「update」的分工ingest只负责把远程内容落到磁盘合并语义仍由增量更新完成。2.2 底层实现ingest()到底做了什么入口函数位于 graphify/ingest.py流程如下target_dir.mkdir(parentsTrue, exist_okTrue)确保./raw存在通过_detect_url_type(url)见 graphify/ingest.py对 URL 分类先执行validate_url(url)做安全校验失败抛ValueError(ingest: ...)按类型分派抓取与落盘并返回Path作为“保存到哪”的答案。安全前置校验SSRF 防护validate_urlgraphify/security.py只放行http/https协议拒绝file://、ftp://、data:等可用于 SSRF 或读取本地文件的 scheme同时拦截云元数据端点主机名如169.254.169.254相关以及解析结果落入私网/保留段的 IP并对 DNS 解析与连接之间可能出现的 DNS-rebind 攻击做了专门的连接级防护。也就是说ingest拉取任何外部 URL 之前都会先过一次 SSRF 安全检查。防覆盖写入文本类内容保存时若文件名已存在会以_1、_2… 后缀追加计数器上限 1000 次保证同源 URL 重复抓取也不会覆盖旧语料见 graphify/ingest.py。输出文件的通用形态除二进制PDF/图片/音频外保存的文件一律是带 YAML frontmatter 的 Markdown其中source_url、type、captured_atUTC ISO 时间、contributor等元数据会作为后续图抽取的节点元信息。值得注意的是frontmatter 中的所有外来字符串都经过_yaml_str()graphify/ingest.py转义它会处理\\、、\n、\r、\t、\0、U2028/U2029 及各类控制字符防止从网页标题等不可信内容注入 YAML 兄弟键注释中编号 F-009 / F-019 的安全问题而该项目刻意不依赖 PyYAML改为手工生成安全的双引号标量。2.3 支持的 URL 类型自动识别_detect_url_type依据域名或路径后缀自动分类下表将文档描述与源码判定规则graphify/ingest.py对齐文档描述判定特征源码处理行为产出YouTube / 任意视频 URL命中youtube.com/youtu.be走 graphify/transcribe.py 的download_audio()用 yt-dlp 下载音轨音频文件下一次运行转写为.txtTwitter / X命中twitter.com/x.com通过publish.twitter.com/oembed拉取推文失败时保存 URL 桩文本.md含推文正文与作者arXiv命中arxiv.org进一步提取形如\d{4}\.\d{4,5}的论文 ID走 arXiv 摘要页解析标题/作者/摘要.md含 abstract 元数据PDF路径以.pdf结尾safe_fetch二进制下载.pdf图片.png/.jpg/.webp 等路径以.png/.jpg/.jpeg/.webp/.gif结尾二进制下载保留下载后缀缺失时回退.jpg图片文件下一次运行时由视觉模型抽取任意网页其余情况含github.com会被先归为github类再落入网页分支HTML→Markdown 转换.md关于「通用网页转 Markdown」的实现细节参考文档表述为 html2text 转换从源码看graphify/ingest.py_html_to_markdown会先无条件剥除script/style防止其文本泄漏随后优先使用markdownify进行转换仅当该库未安装时才回退到基础的 HTML 标签剥离截断 8000 字符。文本型网页内容整体还会被截断到 12000 字符以内再写入。关于「视频转写」有一个前置条件文档明确指出需要先安装视频扩展pip install graphifyy[video]对应源码中缺少 yt-dlp 时会抛出包含安装提示的异常见 graphify/transcribe.py且音频文件名基于 URL 哈希生成而非视频标题避免标题含怪异字符破坏文件系统。抓取到的音频.txt、图片等会在下一次语义化运行/graphify --update时被抽取入图——这也解释了为何add成功后要紧接着跑一次--update。2.4 独立命令行用法ingest.py同时提供__main__入口graphify/ingest.py便于脱离 Agent 环境直接测试python -m graphify.ingest URL [target_dir] [--author NAME] [--contributor NAME]target_dir默认./raw--author/--contributor会作为节点元数据写入 frontmatter成功时打印Saved 类型: 文件名与Ready for graphify: 路径。三、--watch目录监听与自动重建3.1 启动命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3把INPUT_PATH替换为要监控的目录。底层实现在 graphify/watch.py 的watch(watch_path, debounce3.0)中基于watchdog建立递归事件监听macOS 上出于 FSEvents 会漏报编辑器快速保存的考虑改用轮询观察器PollingObserver其余平台默认用 inotify 类Observer主循环每 0.5 秒检查一次当有变化且距最后一次事件已超过debounce秒时才触发批处理。按 CtrlC 即优雅停止KeyboardInterrupt分支会打印Stopped.并释放 observer。debounce默认 3 秒语义是「等到文件活动停止后再触发」——这正是为 Agent 并行写入场景设计的一批 Agent 连续落盘时不会每个文件都触发一次重建而是攒成一个变更批batch统一处理。3.2 事件过滤什么才会被算作“变化”处理器在入队变更前会做多层过滤避免自触发与噪音graphify/watch.py目录事件与只读事件Linux 上 inotify 的opened、closed_no_write直接忽略——否则监听器自己重建时的读盘、编辑器/Agent 的只读打开都会导致无限自触发变更文件扩展名必须属于受监控集合CODE_EXTENSIONS | DOC_EXTENSIONS | PAPER_EXTENSIONS | IMAGE_EXTENSIONS扩展名全集定义见 graphify/detect.py如.py/.ts/.go等代码、.md/.txt等文档、.pdf、.png/.jpg等图片位于.graphifyignore规则、以.开头的隐藏路径或属于graphify-out输出目录自身的路径都会被丢弃ignore 规则只在启动时加载一次并缓存避免在繁忙卷上为每个事件重解析。3.3 两条触发路径核心分层机制变更批产生后按文件类型走完全不同的处理路径纯代码变更.py、.ts、.go 等立即触发_rebuild_code()——重新执行 AST 抽取 构建 聚类全程无需 LLM。graph.json与GRAPH_REPORT.md自动更新。这是 graphify “本地确定性 AST 解析”理念在增量链路上的直接体现代码结构变化可以完全确定性地重算。文档 / 论文 / 图片变更写入graphify-out/needs_update标记文件并打印通知提示用户运行/graphify --update——因为这类内容的语义重抽取依赖 LLM监听器不越权自动执行。需要注意两类边界情形均有对应实现与测试删除总是触发重建无论删除的是代码还是文档删除事件都会立即触发一次 rebuild因为逐出eviction不需要 LLM——由全量调和reconcile阶段把磁盘上已消失源文件对应的节点/边/超边剔除参见_batch_triggers_rebuild注释中的 issue 引用。needs_update标记只为仍存活于磁盘的非代码文件写入纯删除批不会留下陈旧标记避免用户运行一次无意义的--update。对应测试见 tests/test_watch.py 中test_batch_doc_only_deletion_skips_llm_flag等用例。3.4 标记文件的检查入口check_updatecheck_update(watch_path)graphify/watch.py用于轮询或 cron 场景若watch_path/graphify-out/needs_update存在则打印提示“存在待处理的非代码变更请运行/graphify --update进行语义重抽取”。该函数cron 安全——无论标记是否存在都返回True不会触发报警且它只提示、绝不擅自清除标记清除是后续 LLM 更新的职责相关行为有test_check_update_*系列测试覆盖。3.5 重建过程的工程保障源码层面把文件变化安全地并到既有图上是 watch 链路最复杂的一环源码提供多项保障可概括为重建锁_rebuild_lock()graphify/watch.py基于fcntl.flock提供进程级互斥非阻塞获取失败即让出避免两进程并发重建锁文件中记录持有者 PID进程被杀时内核自动释放无陈旧锁残留Windows无 fcntl回退为 no-op。资源限制_apply_resource_limits()会nice(10)并支持环境变量GRAPHIFY_REBUILD_MEMORY_LIMIT_MB对重建进程做 RSS 级内存上限macOS 用RLIMIT_DATA、Linux 用RLIMIT_AS。持久化构建配置初始extract的--exclude与 gitignore 偏好会被持久化到graphify-out/.graphify_build.jsongraphify/watch.py使后续update/watch重建不会把被排除的路径悄悄重新纳入。调和与保留_reconcile_existing_graph()会把新抽取结果与既有图合并区分 AST 层与语义层来源_origin字段删除才逐出、过滤变化不做盲删对真实存在于磁盘但离开扫描语料的文件采取 fail-closed保留并大声提示策略防止过滤回归导致的大规模误删节点。pending 队列无法取得重建锁的提交进程会把变更路径追加到graphify-out/.pending_changes由持锁进程在重建前后排空drain并合并保证并发提交的变更集不被静默丢弃。四、Agentic 工作流中的实践建议参考文档为多 Agent 协作场景给出了明确的操作指引与上面的机制相互印证在一个后台终端中运行--watch。Agent 多波次产生的代码变更会在波次之间被自动拾取。若 Agent 同时也在写文档或笔记则这些波次之后需要手动执行一次/graphify --update。要点拆解代码归代码Agent 写代码的过程可以完全放手——每次波次结束debounce 窗口过后都会自动完成 AST 重建与聚类图始终反映最新代码结构不需要 LLM 参与。文档归语义Agent 产出的 markdown/PDF/图片属于语义层watcher 只负责写入needs_update标记。合适时机例如所有 Agent 波次全部收敛后统一执行一次/graphify --update让 LLM 一次性重抽取这批非代码内容避免每篇文档各跑一次造成重复消耗。debounce 就是天然批处理器3 秒默认值吸收了 Agent 并行写入的“写盘风暴”把连续事件收敛成单个重建批既省资源也避免图文件在重建中被反复改写。五、与既有 pipeline 的衔接小结add产出的文件落在./raw是后续--update的扫描范围其 YAML frontmatter 中type如tweet/webpage/paper会被抽取器读取为节点元信息。watch与update共享同一套调和逻辑与构建配置持久化因此监听期间的代码变更、后续手动update、甚至 git hook 触发的重建都遵循一致的“保留 逐出”语义保证图的一致性。两个能力都默认关闭属于需要显式请求的增量功能文档中强调出错必须上报用户而不是静默继续——这保证了add/watch链路在无人值守的 Agent 循环里具备可诊断性。如需进一步阅读可参考 add-watch 参考文档原文、抓取实现 graphify/ingest.py、监听实现 graphify/watch.py、安全校验 graphify/security.py以及监听行为的测试套件 tests/test_watch.py。【免费下载链接】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），仅供参考