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 技能的两个非默认构建功能展开/graphify add url将外部 URL推文、arXiv、PDF、网页、图片、视频抓取进语料库并合入图谱以及--watch后台监听文件夹、在文件变化时自动重建graph.json与GRAPH_REPORT.md。读完后你可以直接在 Claude Code 等 Agent 中执行这两条指令并理解其底层实现URL 分类、frontmatter 落盘、watchdog 防抖、增量 reconcile 与并发锁是如何保证图谱在持续变化中保持正确的。这两个功能在技能中的位置/graphify add url和--watch都不属于 graphify 的默认构建流程。技能入口文件 skill-amp.md 明确列出了/graphify add的用法变体/graphify add url # fetch URL, save to ./raw, update graph /graphify add url --author Name # tag who wrote it /graphify add url --contributor Name # tag who added it to the corpus并规定当用户执行/graphify add url抓取 URL 入语料库或传入--watch让图谱在文件变化时自动重建时加载参考文档 references/add-watch.md本文的原始文档。也就是说它是 Agent 在特定触发条件下才读取的操作手册本文将其两条操作路径完整展开。两条命令都依赖同一个前置约定构建完成后graphify-out/.graphify_python中记录了当时使用的 Python 解释器路径命令一律以$(cat graphify-out/.graphify_python)开头来保证与构建时同一环境避免系统python3缺少 graphify 依赖导致导入失败。用 /graphify add 把一个 URL 变成图谱节点完整命令与参数原始文档给出的标准执行方式如下以graphify-out/.graphify_python指向的解释器运行内联脚本调用 ingest 模块 的ingest函数$(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替换为实际要抓取的地址AUTHOR与CONTRIBUTOR在用户提供了姓名时替换否则保留占位语义最终会落为unknown。命令如果以错误退出必须向用户说明出了什么问题不能静默继续——这是原始文档对 Agent 的硬性要求。保存成功后自动对./raw跑一次--update管道把新文件合入现有图谱。ValueError与RuntimeError分别对应参数/URL 校验失败和抓取失败两类错误源码中ingest函数正是这样抛出的URL 未通过validate_url时抛ValueError前缀ingest:网络层失败HTTPError/URLError/OSError时包装为RuntimeError。六种 URL 类型如何被自动识别原始文档列出 6 类受支持且自动检测的 URL。对照 ingest.py 中的 _detect_url_type检测逻辑是对 URL 做小写子串/后缀匹配URL 类型识别条件源码实现落盘结果YouTube / 视频含youtube.com或youtu.be通过 yt-dlp 下载音频下次运行时转写为.txt需要pip install graphifyy[video]Twitter/X含twitter.com或x.com通过 oEmbed 拉取保存为带推文正文与作者的.mdarXiv含arxiv.org摘要 元数据保存为.mdPDF路径以.pdf结尾直接下载为.pdf图片路径以.png/.jpg/.jpeg/.webp/.gif结尾下载保存Claude vision 在下次运行时提取任意网页以上均不匹配经 html2text/markdownify 转 markdown 保存为.md从源码结构看有两点值得注意它们让实际行为比文档表格更精细github.com 被识别但按网页处理。_detect_url_type中还有github.com分支返回github但 ingest 主函数 只对pdf/image/youtube/tweet/arxiv做了特判其余一律走_fetch_webpage的网页转换路径。落盘文件都带 YAML frontmatter。推文、arXiv、网页三类生成的.md头部都写入source_url、type、captured_at、contributor等字段arXiv 另有arxiv_id、paper_authors网页另有title这些字段会被 graphify 的文档提取器读作节点元数据。正文还做了截断网页正文取前 12000 字符文件名由域名路径清洗生成非单词字符替换为_最长 80 字符同名冲突时自动追加_1、_2计数器避免覆盖。安全边界。所有抓取都经过 security 模块 的validate_url/safe_fetch/safe_fetch_textURL 字符串进入 frontmatter 前还会经_yaml_str逐字符转义含 U2028/U2029 等 YAML 换行符防止恶意页面标题通过 frontmatter 注入额外键。成功后自动走 --update 管道原始文档要求“保存成功后自动对./raw运行--update管道”。这条管道本身的实现细节在姊妹参考文档 references/update.md 中先用detect_incremental对比 manifest 找出新增/变更/删除的文件再把变更子集写入.graphify_detect.json若变更文件全是代码则只跑 AST 提取、跳过 LLM 语义提取否则走完整的 3A–3C 管道含视频转写前置步骤最后用build_merge把新提取结果与现有graph.json合并并只把本轮真正产出内容的文件盖章进 manifest失败的 chunk 保留未盖章状态以便下次重排。因此一次/graphify add url的完整闭环是抓取 → 落盘带溯源 frontmatter→ 增量检测 → 提取 → 合并 → 图谱更新。视频摄入的依赖前提YouTube 一类 URL 只是先下载音频文件转写发生在下一次运行时。对应的依赖声明在 pyproject.toml 的可选依赖中video [faster-whisper; python_version 3.11, yt-dlp2026.6.9]即需要 Python 3.11 并安装graphifyy[video]扩展音频下载入口是 transcribe 模块 的download_audio。用 --watch 监听文件夹自动重建图谱命令与 debounce 参数原始文档给出的监听命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3INPUT_PATH替换为要监听的目录。入口在 watch.py 的main段path是位置参数默认.--debounce为浮点秒数默认 3 秒。Debounce 的语义是“等到文件活动停止后再触发”这样一波并行 Agent 写入不会每个文件都触发一次重建。对照 watch 函数 的实现可以确认这个机制主循环每 0.5 秒检查一次time.monotonic()只有当距最后一次事件 ≥ debounce 秒时才把累积的变更文件打包成一个 batch 触发后续动作。代码变更与非代码变更的分流原始文档描述了两类行为源码中的判定条件比文档更精确见 _batch_triggers_rebuild / _batch_needs_llm_flag代码文件变更.py、.ts、.go 等立即重跑 AST 提取 重建 社区聚类全程不需要 LLMgraph.json与GRAPH_REPORT.md自动更新。源码里的触发条件是“batch 中含代码文件或batch 中有已删除的文件”——任何被监听文件的删除同样会触发重建因为驱逐过期节点不需要 LLM。文档、论文、图片变更写入graphify-out/needs_update标志文件并打印提示要求运行/graphify --update做 LLM 语义重提取见 _notify_only。注意只有仍存在于磁盘上的非代码文件才写标志纯删除批次的节点驱逐已由重建完成不会留下过期标志。监听器本身还有一些保护性过滤避免自身触发风暴只关心代码/文档/论文/图片四类扩展名CODE | DOC | PAPER | IMAGE.graphifyignore模式在启动时一次性加载避免高频文件系统事件上反复解析跳过所有含点前缀路径段的文件和graphify-out目录自身在 Linux 上还会过滤 inotify 的opened/closed_no_write只读事件否则监视器自己读文件就会无限重触发macOS 上使用PollingObserver轮询观察者因为 FSEvents 可能漏掉快速保存。一次代码重建的内部过程代码变更触发的重建入口是 _rebuild_code。从源码结构看它远不止“重新提取”那么简单这是一条带并发保护和失败回滚的完整管道并发锁与排队。重建前后用fcntl.flock对graphify-out/.rebuild.lock加咨询锁_rebuild_lock进程被 kill 时锁自动释放无需清理残留锁文件持锁期间锁文件内写入持有者 PID 供外部轮询。若锁被占增量调用会先把变更路径追加进.pending_changes队列append 模式写POSIX 下小写入原子持锁方在重建前后各排空一次并合并变更集保证并发 commit 的变更不会丢失重建完成后还会做最多 20 轮“迟到排空”让提交风暴最终收敛。增量 reconcile。只重提取变更且仍存在的文件未变更文件的节点从现有graph.json保留删除文件对应的过期节点被驱逐。驱逐采取 fail-closed 策略文件仍存在于磁盘但离开扫描语料时必须有“活的忽略规则命中”.graphifyignore或持久化的--exclude模式才算有意排除并清理否则保守保留并打印警告防止过滤器回归导致节点被误杀。缩图守卫。写入前 _check_shrink 会对比新旧节点数如果新图节点变少且减少的节点无法全部归因于本轮重提取或删除的文件则拒绝覆盖并提示--force用来拦截“半截提取导致数千节点无声消失”的事故。合法的删除如重构删函数则通过rebuilt_sources/deleted_paths核算放行无需--force。落盘与派生物。原子替换先写.graph.tmp.json再 rename、生成GRAPH_REPORT.md、复用旧社区标签社区成员签名校验后按 hub 节点确定性重命名、必要时从graph.json中已存的社区信息重渲染graph.html最后清除needs_update标志——所以一次代码重建会把此前文档变更留下的语义更新提醒一并冲掉若那批文档确实要处理仍需手动跑/graphify --update。无变更时的幂等性如果一轮重建发现拓扑没有任何变化canonical 拓扑对比相等watch 会打印No code-graph changes detected; outputs left untouched.并不触碰磁盘上的产物只有当graph.html缺失或被标记 stale 时才会顺带重渲染 HTML。这保证了长时间开着 watcher 也不会产生无意义的文件写入。Agentic 工作流中的实践建议原始文档给出的使用姿势在后台终端运行--watchAgent 一波又一波的代码修改会在波次间隙被自动拾取并重建如果 Agent 同时还在写文档或笔记这些波次结束后需要一次手动/graphify --update做语义重提取按CtrlC停止源码中捕获KeyboardInterrupt打印Stopped.并优雅停止 observer 线程。关键文件索引路径作用graphify/skills/amp/references/add-watch.md本文原始参考文档add 与 watch 的 Agent 操作手册graphify/ingest.pyURL 分类、抓取、frontmatter 生成、落盘去重graphify/watch.py文件监听、防抖、锁与排队、增量 reconcile、缩图守卫graphify/skills/amp/references/update.mdadd 成功后自动执行的--update增量管道graphify/skill-amp.md技能入口/graphify add命令族与参考文档路由tests/test_watch.pywatch 相关行为的测试用例含 source_file 锚定、变更集合并等场景适用前提小结以上命令均在“已至少完成一次构建、graphify-out/存在.graphify_python指针”的前提下运行视频摄入额外要求 Python 3.11 与graphifyy[video]扩展--watch需要watchdog已安装缺失时会提示pip install watchdog。【免费下载链接】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），仅供参考 graphify 实战指南：用 /graphify add 摄入 URL、用 --watch 监听文件夹自动重建知识图谱
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 技能的两个非默认构建功能展开/graphify add url将外部 URL推文、arXiv、PDF、网页、图片、视频抓取进语料库并合入图谱以及--watch后台监听文件夹、在文件变化时自动重建graph.json与GRAPH_REPORT.md。读完后你可以直接在 Claude Code 等 Agent 中执行这两条指令并理解其底层实现URL 分类、frontmatter 落盘、watchdog 防抖、增量 reconcile 与并发锁是如何保证图谱在持续变化中保持正确的。这两个功能在技能中的位置/graphify add url和--watch都不属于 graphify 的默认构建流程。技能入口文件 skill-amp.md 明确列出了/graphify add的用法变体/graphify add url # fetch URL, save to ./raw, update graph /graphify add url --author Name # tag who wrote it /graphify add url --contributor Name # tag who added it to the corpus并规定当用户执行/graphify add url抓取 URL 入语料库或传入--watch让图谱在文件变化时自动重建时加载参考文档 references/add-watch.md本文的原始文档。也就是说它是 Agent 在特定触发条件下才读取的操作手册本文将其两条操作路径完整展开。两条命令都依赖同一个前置约定构建完成后graphify-out/.graphify_python中记录了当时使用的 Python 解释器路径命令一律以$(cat graphify-out/.graphify_python)开头来保证与构建时同一环境避免系统python3缺少 graphify 依赖导致导入失败。用 /graphify add 把一个 URL 变成图谱节点完整命令与参数原始文档给出的标准执行方式如下以graphify-out/.graphify_python指向的解释器运行内联脚本调用 ingest 模块 的ingest函数$(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替换为实际要抓取的地址AUTHOR与CONTRIBUTOR在用户提供了姓名时替换否则保留占位语义最终会落为unknown。命令如果以错误退出必须向用户说明出了什么问题不能静默继续——这是原始文档对 Agent 的硬性要求。保存成功后自动对./raw跑一次--update管道把新文件合入现有图谱。ValueError与RuntimeError分别对应参数/URL 校验失败和抓取失败两类错误源码中ingest函数正是这样抛出的URL 未通过validate_url时抛ValueError前缀ingest:网络层失败HTTPError/URLError/OSError时包装为RuntimeError。六种 URL 类型如何被自动识别原始文档列出 6 类受支持且自动检测的 URL。对照 ingest.py 中的 _detect_url_type检测逻辑是对 URL 做小写子串/后缀匹配URL 类型识别条件源码实现落盘结果YouTube / 视频含youtube.com或youtu.be通过 yt-dlp 下载音频下次运行时转写为.txt需要pip install graphifyy[video]Twitter/X含twitter.com或x.com通过 oEmbed 拉取保存为带推文正文与作者的.mdarXiv含arxiv.org摘要 元数据保存为.mdPDF路径以.pdf结尾直接下载为.pdf图片路径以.png/.jpg/.jpeg/.webp/.gif结尾下载保存Claude vision 在下次运行时提取任意网页以上均不匹配经 html2text/markdownify 转 markdown 保存为.md从源码结构看有两点值得注意它们让实际行为比文档表格更精细github.com 被识别但按网页处理。_detect_url_type中还有github.com分支返回github但 ingest 主函数 只对pdf/image/youtube/tweet/arxiv做了特判其余一律走_fetch_webpage的网页转换路径。落盘文件都带 YAML frontmatter。推文、arXiv、网页三类生成的.md头部都写入source_url、type、captured_at、contributor等字段arXiv 另有arxiv_id、paper_authors网页另有title这些字段会被 graphify 的文档提取器读作节点元数据。正文还做了截断网页正文取前 12000 字符文件名由域名路径清洗生成非单词字符替换为_最长 80 字符同名冲突时自动追加_1、_2计数器避免覆盖。安全边界。所有抓取都经过 security 模块 的validate_url/safe_fetch/safe_fetch_textURL 字符串进入 frontmatter 前还会经_yaml_str逐字符转义含 U2028/U2029 等 YAML 换行符防止恶意页面标题通过 frontmatter 注入额外键。成功后自动走 --update 管道原始文档要求“保存成功后自动对./raw运行--update管道”。这条管道本身的实现细节在姊妹参考文档 references/update.md 中先用detect_incremental对比 manifest 找出新增/变更/删除的文件再把变更子集写入.graphify_detect.json若变更文件全是代码则只跑 AST 提取、跳过 LLM 语义提取否则走完整的 3A–3C 管道含视频转写前置步骤最后用build_merge把新提取结果与现有graph.json合并并只把本轮真正产出内容的文件盖章进 manifest失败的 chunk 保留未盖章状态以便下次重排。因此一次/graphify add url的完整闭环是抓取 → 落盘带溯源 frontmatter→ 增量检测 → 提取 → 合并 → 图谱更新。视频摄入的依赖前提YouTube 一类 URL 只是先下载音频文件转写发生在下一次运行时。对应的依赖声明在 pyproject.toml 的可选依赖中video [faster-whisper; python_version 3.11, yt-dlp2026.6.9]即需要 Python 3.11 并安装graphifyy[video]扩展音频下载入口是 transcribe 模块 的download_audio。用 --watch 监听文件夹自动重建图谱命令与 debounce 参数原始文档给出的监听命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3INPUT_PATH替换为要监听的目录。入口在 watch.py 的main段path是位置参数默认.--debounce为浮点秒数默认 3 秒。Debounce 的语义是“等到文件活动停止后再触发”这样一波并行 Agent 写入不会每个文件都触发一次重建。对照 watch 函数 的实现可以确认这个机制主循环每 0.5 秒检查一次time.monotonic()只有当距最后一次事件 ≥ debounce 秒时才把累积的变更文件打包成一个 batch 触发后续动作。代码变更与非代码变更的分流原始文档描述了两类行为源码中的判定条件比文档更精确见 _batch_triggers_rebuild / _batch_needs_llm_flag代码文件变更.py、.ts、.go 等立即重跑 AST 提取 重建 社区聚类全程不需要 LLMgraph.json与GRAPH_REPORT.md自动更新。源码里的触发条件是“batch 中含代码文件或batch 中有已删除的文件”——任何被监听文件的删除同样会触发重建因为驱逐过期节点不需要 LLM。文档、论文、图片变更写入graphify-out/needs_update标志文件并打印提示要求运行/graphify --update做 LLM 语义重提取见 _notify_only。注意只有仍存在于磁盘上的非代码文件才写标志纯删除批次的节点驱逐已由重建完成不会留下过期标志。监听器本身还有一些保护性过滤避免自身触发风暴只关心代码/文档/论文/图片四类扩展名CODE | DOC | PAPER | IMAGE.graphifyignore模式在启动时一次性加载避免高频文件系统事件上反复解析跳过所有含点前缀路径段的文件和graphify-out目录自身在 Linux 上还会过滤 inotify 的opened/closed_no_write只读事件否则监视器自己读文件就会无限重触发macOS 上使用PollingObserver轮询观察者因为 FSEvents 可能漏掉快速保存。一次代码重建的内部过程代码变更触发的重建入口是 _rebuild_code。从源码结构看它远不止“重新提取”那么简单这是一条带并发保护和失败回滚的完整管道并发锁与排队。重建前后用fcntl.flock对graphify-out/.rebuild.lock加咨询锁_rebuild_lock进程被 kill 时锁自动释放无需清理残留锁文件持锁期间锁文件内写入持有者 PID 供外部轮询。若锁被占增量调用会先把变更路径追加进.pending_changes队列append 模式写POSIX 下小写入原子持锁方在重建前后各排空一次并合并变更集保证并发 commit 的变更不会丢失重建完成后还会做最多 20 轮“迟到排空”让提交风暴最终收敛。增量 reconcile。只重提取变更且仍存在的文件未变更文件的节点从现有graph.json保留删除文件对应的过期节点被驱逐。驱逐采取 fail-closed 策略文件仍存在于磁盘但离开扫描语料时必须有“活的忽略规则命中”.graphifyignore或持久化的--exclude模式才算有意排除并清理否则保守保留并打印警告防止过滤器回归导致节点被误杀。缩图守卫。写入前 _check_shrink 会对比新旧节点数如果新图节点变少且减少的节点无法全部归因于本轮重提取或删除的文件则拒绝覆盖并提示--force用来拦截“半截提取导致数千节点无声消失”的事故。合法的删除如重构删函数则通过rebuilt_sources/deleted_paths核算放行无需--force。落盘与派生物。原子替换先写.graph.tmp.json再 rename、生成GRAPH_REPORT.md、复用旧社区标签社区成员签名校验后按 hub 节点确定性重命名、必要时从graph.json中已存的社区信息重渲染graph.html最后清除needs_update标志——所以一次代码重建会把此前文档变更留下的语义更新提醒一并冲掉若那批文档确实要处理仍需手动跑/graphify --update。无变更时的幂等性如果一轮重建发现拓扑没有任何变化canonical 拓扑对比相等watch 会打印No code-graph changes detected; outputs left untouched.并不触碰磁盘上的产物只有当graph.html缺失或被标记 stale 时才会顺带重渲染 HTML。这保证了长时间开着 watcher 也不会产生无意义的文件写入。Agentic 工作流中的实践建议原始文档给出的使用姿势在后台终端运行--watchAgent 一波又一波的代码修改会在波次间隙被自动拾取并重建如果 Agent 同时还在写文档或笔记这些波次结束后需要一次手动/graphify --update做语义重提取按CtrlC停止源码中捕获KeyboardInterrupt打印Stopped.并优雅停止 observer 线程。关键文件索引路径作用graphify/skills/amp/references/add-watch.md本文原始参考文档add 与 watch 的 Agent 操作手册graphify/ingest.pyURL 分类、抓取、frontmatter 生成、落盘去重graphify/watch.py文件监听、防抖、锁与排队、增量 reconcile、缩图守卫graphify/skills/amp/references/update.mdadd 成功后自动执行的--update增量管道graphify/skill-amp.md技能入口/graphify add命令族与参考文档路由tests/test_watch.pywatch 相关行为的测试用例含 source_file 锚定、变更集合并等场景适用前提小结以上命令均在“已至少完成一次构建、graphify-out/存在.graphify_python指针”的前提下运行视频摄入额外要求 Python 3.11 与graphifyy[video]扩展--watch需要watchdog已安装缺失时会提示pip install watchdog。【免费下载链接】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），仅供参考