graphify 增量内容接入指南/graphify add拉取 URL 与--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 内置 Skill 参考文档 add-watch.md 为核心骨架展开其同名生成快照位于 tools/skillgen/expected/graphify__skills__windows__references__add-watch.md。graphify 会把「代码 文档 SQL Schema 配置 PDF」转化为可查询的知识图谱而在默认构建流程之外它还提供两条把新内容持续喂进图谱的通道/graphify add url用于抓取一个远程 URL 并写入语料库--watch用于让后台进程监控某个目录并在文件变化时自动重建图谱。读完本文你将掌握add支持哪几类 URL、每种类型如何落盘成可被提取的语料文件watch对代码文件与文档/图片分别走什么更新策略以及如何把两者接进 Agent 工作流让图谱始终跟上语料的变化。一、定位这两条路径都不是默认构建的一部分graphify 的标准工作流是三步流水线AST 确定性解析 → 视频/音频本地转写 → LLM 语义抽取最终产出graph.json、GRAPH_REPORT.md、可交互的graph.html等产物。参考文档开篇就划清了边界Load this when the user ran/graphify add urlor passed--watch. Neither is part of the default build.也就是说add与watch属于向已有图谱持续补充内容的增量接入能力只有在用户显式发出/graphify add url或带--watch参数时才需要读取这份参考文档并执行相应流程。二者的本质差异在于/graphify add一次性、显式地把「一个 URL 指向的远程资源」抓取进./raw语料目录随后跑增量--update让新文件并入图谱--watch持续地、事件驱动地监控本地目录一旦检测到受支持的文件变化就自动重建图谱或提醒用户去做需要 LLM 的语义更新。两条路径都依赖 Skill 引导生成的解释器路径文件graphify-out/.graphify_python通过$(cat graphify-out/.graphify_python)拿到那个能 import graphify 的 Python 解释器再调用-c一段内联脚本或-m模块方式完成具体动作。这与仓库中所有 Skill 文件的引导方式一致安装后.graphify_python里记录的是隔离环境中的解释器绝对路径例如 Windows 下 uv 工具环境中的graphifyy\Scripts\python.exe参见 graphify/skill-windows.md 中的$py解析逻辑。二、/graphify add url把远程内容抓进语料库参考文档给出的核心命令如下URL、AUTHOR、CONTRIBUTOR为占位符需按实际情况替换$(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) 它做了三件事调用ingest()抓取 URL → 打印保存路径 → 出错时把错误写到 stderr 并以非零码退出。规则是命令报错就必须把原因告诉用户不能静默继续保存成功之后还要自动在./raw上运行--update增量管线把新文件合并进已有图谱。2.1 命令行入口graphify add这条 Skill 流程在 CLI 上有一个功能等价的原生命令见 graphify/cli.pygraphify add url [--author Name] [--contributor Name] [--dir ./raw]各参数含义如下参数作用默认值url要抓取的远程地址必填--author用户姓名作为节点元数据写入 YAML frontmatter无--contributor贡献者姓名面向团队图谱无--dir语料目录./rawCLI 分支的出错处理更直接——except Exception捕获一切异常打印error: ...后sys.exit(1)成功后提示Run /graphify --update in your AI assistant to update the graph.。也就是说无论走 Skill 参考脚本还是 CLI 原生命令成功的终点都指向同一个动作触发--update增量语义再提取。2.2 底层实现graphify/ingest.pySkill 脚本 import 的graphify.ingest是整条add能力的实现模块graphify/ingest.py 的入口函数def ingest(url: str, target_dir: Path, author: str | None None, contributor: str | None None) - Path:它返回已保存文件的Path核心执行顺序graphify/ingest.pytarget_dir.mkdir(parentsTrue, exist_okTrue)确保目录存在_detect_url_type(url)依据主机名与路径扩展名判断 URL 类型见 2.3 节validate_url(url)校验 URL非法则抛ValueError(ingest: ...)按类型走对应抓取分支网络异常HTTPError/URLError/OSError统一包装为RuntimeError生成内容/二进制文件落盘并打印Saved type: name返回路径。抓取的 URL 来源页面标题等外部文本会被写进 YAML frontmatter因此模块用了一个手写的_yaml_str()graphify/ingest.py做严格转义——覆盖\t、\0、U2028/U2029 这类 YAML 视作换行的字符防止恶意页面内容把source_url:/title:等字段撑破而注入额外 YAML 键对应仓库注释中的 F-009/F-019 防护且刻意不引入 PyYAML 依赖。文件名则由_safe_filename()graphify/ingest.py把 URL 的netlocpath规整成 ≤80 字符的安全名再追加后缀。2.3 URL 自动识别六类资源各有落盘策略参考文档列出的 URL 类型及处理方式如下类型由 graphify/ingest.py 的_detect_url_type()自动判定URL 类型判定依据抓取/落盘行为后续处理YouTube / 任意视频 URL主机含youtube.com/youtu.be经 yt-dlp 下载音频graphify.transcribe.download_audio下一次运行时转写成.txt需pip install graphifyy[video]Twitter/X主机含twitter.com/x.com经publish.twitter.comoEmbed 抓取存为.md含推文正文与作者oEmbed 失败则保存 URL 占位 stub下次--update作为文档抽取arXiv主机含arxiv.org正文匹配\d{4}\.\d{4,5}抓取 abstract 页标题/作者/摘要写入 frontmatter存为arxiv_id.md作为 paper 类型语义抽取PDF路径以.pdf结尾二进制直接下载为.pdf_download_binary下次运行 PDF 抽取图片.png/.jpg/.webp路径扩展名命中图片后缀实现里含.gif二进制下载为图片文件下次运行时由 Claude vision 语义提取任意网页以上都不命中抓取 HTML抽取title转 Markdown优先markdownify否则基础 tag strip 兜底正文截断到 12000 字符后存.md作为 webpage 文档抽取几点来自源码的补充事实_detect_url_type()实际还识别github.com返回github类型与arxiv.org但ingest()分支只对 pdf / image / youtube / tweet / arxiv 特判其余全部落到通用_fetch_webpage()——因此 GitHub 仓库页等 URL 最终按通用网页转 Markdown处理。Tweet 抓取会把x.com规整为twitter.com再调 oEmbed抓取失败不致命会写一条Tweet at url (could not fetch content)占位记录并标记author: unknown保证流程不中断、内容可追溯。YouTube 分支在 graphify/ingest.py 延迟导入graphify.transcribe.download_audio若未装yt-dlp其内部会抛出带指引的ImportError提示先执行pip install graphifyy[video]见 graphify/transcribe.py 的报错文案。video这个可选 extra 在包元数据中声明了yt-dlp与faster-whisper依赖见 pyproject.toml 与 uv.lock 的provides-extras其中也包含watch。图片/PDF 二进制走safe_fetch()graphify/security.py 提供与文本抓取共用同一套安全出口。落盘前还有防覆盖逻辑目标文件已存在时自动追加_1、_2……计数器上限 1000避免同名 URL 反复 add 时互相覆盖graphify/ingest.py。2.4 保存之后接入--update增量管线参考文档特别强调add 成功 ≠ 建图完成。抓取下来的.md/.pdf/图片/音频还只是语料只有跑增量更新才会让它们成为图谱节点与边。--update的完整流程由 update.md 描述先用detect_incremental找出变化文件纯代码变化跳过 LLM 只跑 ASTcode_only分支混有文档/论文/图片/视频时则先对new_files[video]里的媒体做转写把产物并入files[document]见 graphify/skills/windows/references/update.md 第 66 行的处理再走完整语义管线最后由build_merge把新抽取结果与原graph.json合并、按prune_sources清理真正删除的文件并重跑聚类与报告。这解释了文档里transcribed to.txton next run / Claude vision extracts on next run这类说法的机制下载是 add 的活语义理解是 update 的活两者由--update串联。三、--watch后台目录监听文件一改图就动参考文档给出的 watch 启动命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3把INPUT_PATH换成要监控的目录即可。等价地CLI 也提供graphify watch [path]入口默认.见 graphify/cli.py。模块自身带命令行解析--debounce是浮点数、默认 3.0 秒graphify/watch.py。watch 依赖第三方库watchdog——若未安装graphify.watch.watch()会抛ImportError(watchdog not installed. Run: pip install watchdog)仓库的包元数据同时提供watchextra可统一通过安装graphifyy[watch]或pip install watchdog解决。3.1 变化内容不同响应策略不同参考文档把 watch 的行为按改了什么分成两条路只有代码文件变化.py、.ts、.go等立刻重跑 AST 抽取 构建 聚类全程不需要 LLMgraph.json与GRAPH_REPORT.md自动更新文档 / 论文 / 图片变化写入graphify-out/needs_update标志文件并打印提示——让你去跑/graphify --update语义再提取需要 LLM。分层动机来自成本与正确性代码结构类、函数、调用边由 tree-sitter AST 确定性提取无 LLM 也能重建所以可以无脑自动跑而 Markdown 文档、论文、图片的概念与关系抽取需要 LLM 语义理解不能由 watcher 私自触发避免每个 Agent 写一段注释就烧一次 token所以只用标志位记账等显式的--update来消费。3.2 源码实现事件过滤、防自触发与批判定真正的监听循环在 graphify/watch.py 的watch()中实现值得展开的细节包括watchdog Observer非 macOS 用Observer()inotify 等原生事件macOS 用PollingObserver()规避 FSEvents 丢失快速连续保存的问题recursiveTrue递归监控整棵目录树。启动即加载忽略规则.graphifyignore模式在启动时只解析一次并缓存_load_graphifyignore 持久化的--exclude/.gitignore开关见 graphify/watch.py 与 graphify/watch.py避免对每次文件系统事件都重解析命中忽略的文件直接丢弃。只监听受支持扩展名事件处理器先过滤目录事件与只读事件opened、closed_no_write再把src_path扩展名与_WATCHED_EXTENSIONSCODE_EXTENSIONS | DOC_EXTENSIONS | PAPER_EXTENSIONS | IMAGE_EXTENSIONS各集合定义见 graphify/detect.py比对同时排除路径中任一段以.开头dotfiles以及落在graphify-out输出目录内的文件——这一条至关重要它防止 watcher 自己重建图谱时读取全树、又把自己的产物事件当新变化而无限自触发。Debounce 消抖事件到来只记录last_trigger并把pending置真主循环每 0.5s 轮询一次直到「距最后一次事件 ≥debounce秒」才把积累的变更路径合成一个批次处理graphify/watch.py。默认 3s 的意义正如参考文档所言Agent 多写并发落盘会激起一波文件事件若逐文件触发重建一次 Agent wave 能烧掉几十次全量 AST 重建消抖让这波事件聚合成一次。批次级决策函数拿到一个 debounce 批次后是否立即重建由_batch_triggers_rebuild()graphify/watch.py判定——批次含代码文件或含任何被删除的文件就立即_rebuild_code()删除文件的图谱驱逐同样不需要 LLM纯删除批次若一直坐等needs_update标志图谱会留脏到下次代码事件是否写 LLM 标志由_batch_needs_llm_flag()graphify/watch.py判定——只统计仍然存活的非代码文件纯删除批次不会留下过期的needs_update。输出落盘_rebuild_code()graphify/watch.py支持只重提取changed_paths的增量模式未变文件从旧图保留、已删路径从保留集驱逐并在重建前通过 flock 拿graphify-out/.rebuild.lock这把仓库级咨询锁锁被占用时变更集写入.pending_changes排队append 原子写拿到锁的一方把排队内容_drain回来与自己合并最多循环 20 次_PENDING_DRAIN_MAX_PASSES保证并发 post-commit hook / 多终端 watch 之间既不死锁也不丢变更详见 graphify/watch.py 的排队/排空实现。停止方式前台按CtrlC主循环捕获KeyboardInterrupt打印[graphify watch] Stopped.并优雅observer.stop()/join()。3.3needs_update标志与配套轮询非代码文件变化时_notify_only()graphify/watch.py会在watch_path/graphify-out/needs_update写一个内容为1的标记文件并打印三段提示检测到文件变化 / 语义再提取需要 LLM / 在 Claude Code 里跑/graphify --update。这个标志本身还可以被无 LLM 的轻量工具轮询graphify check-update path对应 graphify/cli.py 与 graphify/watch.py 的check_update()仅当标志存在时打印Pending non-code changes...任何情况下都返回Truecron 友好不会触发告警。这为定时任务定期检查是否有待办语义更新提供了安全通道。四、Agentic 工作流的最佳姿势参考文档最后给出两条与 Agent 编排强相关的实践建议把--watch跑在后台终端。Agent 的多轮代码修改wave会自然落在两次变更之间被 watcher 消抖成批并自动重建——你在前台对话图谱在后台持续跟新代码侧的 AST 重建零 LLM 成本不需要你手动干预。Agent 若也在写文档/笔记wave 结束后需手动/graphify --update一次。因为文档/图片的语义抽取要 LLMwatcher 只会写needs_update标志并提示不会自作主张触发由你在 Agent 完成一轮文档产出后统一消费该标志既省 token 又不丢内容。结合 2.4 节可以看到这两条能力与--update参考文档一起构成闭环add解决外部内容怎么进来watch解决本地内容变了怎么跟上update解决新语料怎么并入图谱。三者配合就能让 graphify 的知识图谱在代码演进、资料补充、Agent 协作写文件的多重扰动下始终可查询、可追溯。五、验证与测试佐证仓库测试集中覆盖了上述两条路径的行为tests/test_watch.py验证 watcher 的 debounce 语义、needs_update标志写入/清理、锁与 pending 队列、source_file重定位等tests/test_ingest.py覆盖 URL 类型识别、抓取内容与文件名安全规整增量合并与图谱驱逐的边界则由tests/test_incremental.py、tests/test_stale_prune.py、tests/test_incremental_mtime_collision.py等守护。本文对行为细节的描述均可回溯到 graphify/ingest.py、graphify/watch.py、graphify/detect.py、graphify/cli.py 对应实现如需深挖可进一步阅读这些文件及其测试。六、快速参考清单场景命令/操作说明抓取一个 URL 进语料/graphify add url或graphify add url [--author A] [--contributor C] [--dir ./raw]成功后自动跑./raw的--update增量管线视频 URL 支持pip install graphifyy[video]提供 yt-dlp faster-whisper音频先下载、下次运行时转写图片语义抽取无需额外命令图片落盘后由/graphify --update触发 vision 提取启动目录监听$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3或graphify watch [path]依赖 watchdog代码变化自动 AST 重建文档/图片写needs_update调整消抖窗口--debounce float默认 3.0s数值越小响应越快越大越抗批量写入风暴检查是否有待办语义更新graphify check-update pathcron 安全有标志才提示去跑/graphify --updateAgent 写完文档后收尾手动/graphify --update消费needs_update合并语义抽取结果并更新图与报告一句话收束add把互联网变成语料来源watch把编辑器/Agent 的落盘变成建图触发器而两者共享的代码走 AST、文档走 LLM分层策略正是 graphify 在 token 成本与图谱新鲜度之间取得平衡的设计核心。【免费下载链接】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），仅供参考