graphify add 与 --watch把外部 URL 增量纳入语料库并用文件监听实时同步知识图谱【免费下载链接】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 的 Pi skill 提供了一条默认构建流程之外的旁路能力/graphify add url可以把网页、论文、推特、视频等外部内容抓取为图谱语料--watch则启动一个后台监听器在文件变化时自动重建代码图谱或提示语义重抽取。本文基于 add-watch 参考文档 与 ingest.py、watch.py 的源码实现完整讲解这两条命令的用法、支持的内容类型以及 watch 底层的事件过滤、增量重建与安全护栏机制。文档定位旁路能力不在默认构建路径中add-watch.md 是 Pi 智能体技能包中的一份“按需加载”参考文档开头明确说明Load this when the user ran/graphify add urlor passed--watch. Neither is part of the default build.也就是说只有当用户显式触发这两个动作时智能体才会读取该文档并按其中的指令执行。这与 update.md增量更新、transcribe.md视频转写等参考文档共同构成了 Pi 技能下/graphify命令族的完整操作手册。一、/graphify add url抓取 URL 并写入语料库1. 标准调用命令文档给出的执行模板如下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) 其中$(cat graphify-out/.graphify_python)是 graphify 构建产物里记录的 Python 解释器路径保证命令与构建该图谱时使用的环境一致。参数语义与 ingest.py 中ingest()的签名一一对应target_dir语料落盘目录文档中固定为./raw即后续--update管道的输入根目录author/contributor写入文件 frontmatter 的署名元数据用于团队协作图谱的溯源。两者省略时 frontmatter 的contributor回退为unknownValueErrorURL 未通过graphify.security.validate_url校验如非法地址、内网地址命令以非零码退出RuntimeError网络抓取失败HTTP 错误、DNS 失败、OSError 等。文档特别强调命令报错时必须把原因告诉用户不得静默继续。成功落盘后应自动对./raw执行--update管道见 update.md 的增量流程把新文件合并进已有图谱。2. 支持的 URL 类型自动检测文档列出了六类 URL其判定逻辑与 ingest.py 中_detect_url_type()的实现一致——按域名或路径后缀顺序分类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 抽取内容任意网页以上皆不匹配转换为 markdown 后存为.md源码中有几个值得注意的实现细节推文_fetch_tweetx.com链接会被归一化为twitter.com后请求publish.twitter.com/oembed接口oEmbed 失败时不报错而是落一个包含“could not fetch content”占位文本的 stub 文件保证语料不丢失。arXiv_fetch_arxiv从 URL 中用正则提取论文编号转而请求export.arxiv.org/abs/页面抽取标题、作者与摘要文件名固定为arxiv_{编号}.md。网页_fetch_webpage先剔除script/style再转 markdown正文截断到 12000 字符以内防止超大页面撑爆语义抽取。安全所有抓取都经过graphify.security的safe_fetch/safe_fetch_text/validate_url且写入 frontmatter 前用_yaml_str()转义控制字符——源码注释明确指出这是为了防止恶意页面标题注入 YAML 兄弟键对应安全项 F-009/F-019。视频能力依赖可选依赖组pyproject.toml 中video [faster-whisper; python_version 3.11, yt-dlp2026.6.9]即graphifyy[video]额外安装 Whisper 转写模型要求 Python 3.11与 yt-dlp。音频下载本身由graphify.transcribe.download_audio()完成转写动作发生在下一次--update运行时对应 transcribe.md 的流程。3. 落盘格式frontmatter 防冲突命名所有文本类抓取结果都写成带 YAML frontmatter 的 markdown字段包括source_url、typetweet/paper/webpage、captured_atUTC ISO 时间戳、contributor论文还带arxiv_id、title、paper_authors。这些字段会被 graphify 的 markdown 抽取器读取为节点元数据。文件名由_safe_filename()从 URL 的 hostpath 清洗生成非字符合法字符替换为_截断到 80 字符。若目标文件已存在ingest()会自动追加_1、_2… 后缀避免覆盖直到第 1000 次为止。二、--watch后台监听目录并自动更新图谱1. 标准调用命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3把INPUT_PATH替换为要监听的目录。watch.py 的__main__入口定义了两个参数path位置参数监听目录默认值为.当前目录--debounce最后一次文件活动后等待的秒数默认 3.0 秒。文档对 debounce 的解释是等待文件活动停止后再触发避免并行 agent 批量写入时每个文件都触发一次重建。源码中watch()的主循环每 0.5 秒检查一次只有time.monotonic() - last_trigger debounce且有待处理变更时才把本批变更清空并提交处理。按CtrlC停止监听进程会打印Stopped.并停止 observer。2. 行为分叉代码文件 vs 文档/论文/图片文档给出的行为规则与 watch.py 中_batch_triggers_rebuild()/_batch_needs_llm_flag()完全对应仅代码文件变化.py、.ts、.go 等立即重跑 AST 抽取 重建 社区聚类不需要 LLMgraph.json与GRAPH_REPORT.md自动更新文档、论文或图片变化写入graphify-out/needs_update标志文件并打印提示要求手动运行/graphify --update语义重抽取需要 LLM任意被监听文件的删除也会触发立即重建——因为把已删源文件的节点剔除eviction同样不需要 LLM全量语料调和会丢弃磁盘上已不存在的源对应的节点。“代码文件”的判定来自 detect.py 中的扩展名集合CODE_EXTENSIONS约 100 余个扩展名覆盖 Python/TS/Go/Rust/Java/C/C#/Swift/Scala/SQL/Terraform/Pascal 等监听器实际关注的扩展名是CODE_EXTENSIONS | DOC_EXTENSIONS | PAPER_EXTENSIONS | IMAGE_EXTENSIONS的并集.pdf归 paper.png/.jpg/.webp/.svg等归 image。3. Agent 工作流建议文档结尾给出针对 agentic 工作流的两条建议在后台终端运行--watchagent 波次之间的代码改动会被自动拾取如果 agent 同时还在写文档或笔记那些波次结束后需要手动执行一次/graphify --update来补上语义重抽取。配套的check_update()函数cron 安全恒返回 True会在标志文件存在时打印“Run/graphify --updateto apply semantic re-extraction”的提示方便定时任务把待办暴露给用户。三、源码纵深watch 的一次完整重建到底做了什么_rebuild_code()watch.py 核心函数是上述“代码变更立即重建”的执行体其调用链可概括为目录稳定化_stabilize_rebuild_cwd()处理 git hook 继承的临时工作目录已被删除的情况通过GRAPHIFY_REPO_ROOT环境变量恢复 CWD加锁_rebuild_lock()用fcntl.flock做每仓库咨询锁Windows 上退化为直通锁文件.rebuild.lock写入持有者 PID 供外部轮询拿不到锁时增量变更会先写入.pending_changes排队锁持有者重建前后各清空一次队列并合并变更集对应并发 post-commit hook 场景源码标注为 issue #1059检测与抽取重新detect()出代码语料并复用上次的--exclude持久化配置.graphify_build.json对已有语义层的文档跳过 AST 快扫然后extract()只解析变更/全量文件增量重建时还会从已有graph.json中借来未重建文件的 AST 节点作为跨文件解析上下文避免“改 A 文件导致 A→B 的调用边消失”与已有图谱调和_reconcile_existing_graph()把新抽取与保留的旧节点/边/超边合并驱逐已删源文件的内容并做 fail-closed 的“排除存活文件”保护——文件仍在磁盘但被过滤掉时不会当成删除而误清节点而是保留并大声提示聚类与报告cluster() 社区标签复用校验 generate()报告 to_json()原子写盘先写.graph.tmp.json再replace若候选图谱与现有图谱规范化后完全相同则不写任何文件打印No code-graph changes detected收缩护栏_check_shrink()拒绝“节点数变少且损失无法被本次重建/删除来源解释”的写盘防语义 chunk 丢失导致的静默塌陷除非损失全部归属本次重建过的源文件或已声明的删除路径收尾更新manifest.json、清掉陈旧的needs_update标志、按需重生成graph.html与已存在的*-callflow.html。监听侧的事件过滤同样有讲究.graphifyignore模式在启动时一次性加载避免高频文件系统事件下反复解析opened/closed_no_write这类“只读”事件被显式过滤Linux inotify 会对每次打开文件产生事件不过滤会导致监听器自我触发、空转烧 CPUmacOS 上使用PollingObserverFSEvents 对快速保存可能漏报graphify-out目录自身与含.开头的路径分量一律忽略。四、实操注意事项与适用前提执行环境两个命令都通过graphify-out/.graphify_python记录的解释器运行前提是已经有一次完整的/graphify构建在该目录下产生了graphify-out/视频 URL必须额外安装pip install graphifyy[video]依赖 yt-dlp 与 faster-whisper转写要求 Python 3.11否则ingest()在 youtube 分支的download_audio导入会失败并抛RuntimeError失败即报告ingest()对非法 URL 抛ValueError、对抓取失败抛RuntimeError且 watch.py 的重建路径对“读不懂的既有 graph.json”采取 fail-closed——宁可拒绝覆写也不吞错删除语义文件纯删除批次由 watch 的 reconcile 扫描直接处理不会留下陈旧的needs_update标志但新增/修改文档仍需一次手动/graphify --update验证参考watch 的并发排队、锁定与收缩护栏行为在 tests/test_watch.py 中有大量用例覆盖ingest 的抓取逻辑可在 tests/test_ingest.py 中对照阅读。小结/graphify add url与--watch补齐了 graphify “代码图谱之外”的两块拼图前者把网页、论文、推文、视频等异构外部内容以统一的 frontmatter-markdown/二进制格式纳入./raw语料库后者让代码变更在毫秒级被监听器捕获后零 LLM 成本地刷新graph.json与GRAPH_REPORT.md而把需要语义理解的文档变更明确交给/graphify --update。两者合在一起构成了 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/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 graphify add 与 --watch：把外部 URL 增量纳入语料库，并用文件监听实时同步知识图谱
graphify add 与 --watch把外部 URL 增量纳入语料库并用文件监听实时同步知识图谱【免费下载链接】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 的 Pi skill 提供了一条默认构建流程之外的旁路能力/graphify add url可以把网页、论文、推特、视频等外部内容抓取为图谱语料--watch则启动一个后台监听器在文件变化时自动重建代码图谱或提示语义重抽取。本文基于 add-watch 参考文档 与 ingest.py、watch.py 的源码实现完整讲解这两条命令的用法、支持的内容类型以及 watch 底层的事件过滤、增量重建与安全护栏机制。文档定位旁路能力不在默认构建路径中add-watch.md 是 Pi 智能体技能包中的一份“按需加载”参考文档开头明确说明Load this when the user ran/graphify add urlor passed--watch. Neither is part of the default build.也就是说只有当用户显式触发这两个动作时智能体才会读取该文档并按其中的指令执行。这与 update.md增量更新、transcribe.md视频转写等参考文档共同构成了 Pi 技能下/graphify命令族的完整操作手册。一、/graphify add url抓取 URL 并写入语料库1. 标准调用命令文档给出的执行模板如下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) 其中$(cat graphify-out/.graphify_python)是 graphify 构建产物里记录的 Python 解释器路径保证命令与构建该图谱时使用的环境一致。参数语义与 ingest.py 中ingest()的签名一一对应target_dir语料落盘目录文档中固定为./raw即后续--update管道的输入根目录author/contributor写入文件 frontmatter 的署名元数据用于团队协作图谱的溯源。两者省略时 frontmatter 的contributor回退为unknownValueErrorURL 未通过graphify.security.validate_url校验如非法地址、内网地址命令以非零码退出RuntimeError网络抓取失败HTTP 错误、DNS 失败、OSError 等。文档特别强调命令报错时必须把原因告诉用户不得静默继续。成功落盘后应自动对./raw执行--update管道见 update.md 的增量流程把新文件合并进已有图谱。2. 支持的 URL 类型自动检测文档列出了六类 URL其判定逻辑与 ingest.py 中_detect_url_type()的实现一致——按域名或路径后缀顺序分类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 抽取内容任意网页以上皆不匹配转换为 markdown 后存为.md源码中有几个值得注意的实现细节推文_fetch_tweetx.com链接会被归一化为twitter.com后请求publish.twitter.com/oembed接口oEmbed 失败时不报错而是落一个包含“could not fetch content”占位文本的 stub 文件保证语料不丢失。arXiv_fetch_arxiv从 URL 中用正则提取论文编号转而请求export.arxiv.org/abs/页面抽取标题、作者与摘要文件名固定为arxiv_{编号}.md。网页_fetch_webpage先剔除script/style再转 markdown正文截断到 12000 字符以内防止超大页面撑爆语义抽取。安全所有抓取都经过graphify.security的safe_fetch/safe_fetch_text/validate_url且写入 frontmatter 前用_yaml_str()转义控制字符——源码注释明确指出这是为了防止恶意页面标题注入 YAML 兄弟键对应安全项 F-009/F-019。视频能力依赖可选依赖组pyproject.toml 中video [faster-whisper; python_version 3.11, yt-dlp2026.6.9]即graphifyy[video]额外安装 Whisper 转写模型要求 Python 3.11与 yt-dlp。音频下载本身由graphify.transcribe.download_audio()完成转写动作发生在下一次--update运行时对应 transcribe.md 的流程。3. 落盘格式frontmatter 防冲突命名所有文本类抓取结果都写成带 YAML frontmatter 的 markdown字段包括source_url、typetweet/paper/webpage、captured_atUTC ISO 时间戳、contributor论文还带arxiv_id、title、paper_authors。这些字段会被 graphify 的 markdown 抽取器读取为节点元数据。文件名由_safe_filename()从 URL 的 hostpath 清洗生成非字符合法字符替换为_截断到 80 字符。若目标文件已存在ingest()会自动追加_1、_2… 后缀避免覆盖直到第 1000 次为止。二、--watch后台监听目录并自动更新图谱1. 标准调用命令$(cat graphify-out/.graphify_python) -m graphify.watch INPUT_PATH --debounce 3把INPUT_PATH替换为要监听的目录。watch.py 的__main__入口定义了两个参数path位置参数监听目录默认值为.当前目录--debounce最后一次文件活动后等待的秒数默认 3.0 秒。文档对 debounce 的解释是等待文件活动停止后再触发避免并行 agent 批量写入时每个文件都触发一次重建。源码中watch()的主循环每 0.5 秒检查一次只有time.monotonic() - last_trigger debounce且有待处理变更时才把本批变更清空并提交处理。按CtrlC停止监听进程会打印Stopped.并停止 observer。2. 行为分叉代码文件 vs 文档/论文/图片文档给出的行为规则与 watch.py 中_batch_triggers_rebuild()/_batch_needs_llm_flag()完全对应仅代码文件变化.py、.ts、.go 等立即重跑 AST 抽取 重建 社区聚类不需要 LLMgraph.json与GRAPH_REPORT.md自动更新文档、论文或图片变化写入graphify-out/needs_update标志文件并打印提示要求手动运行/graphify --update语义重抽取需要 LLM任意被监听文件的删除也会触发立即重建——因为把已删源文件的节点剔除eviction同样不需要 LLM全量语料调和会丢弃磁盘上已不存在的源对应的节点。“代码文件”的判定来自 detect.py 中的扩展名集合CODE_EXTENSIONS约 100 余个扩展名覆盖 Python/TS/Go/Rust/Java/C/C#/Swift/Scala/SQL/Terraform/Pascal 等监听器实际关注的扩展名是CODE_EXTENSIONS | DOC_EXTENSIONS | PAPER_EXTENSIONS | IMAGE_EXTENSIONS的并集.pdf归 paper.png/.jpg/.webp/.svg等归 image。3. Agent 工作流建议文档结尾给出针对 agentic 工作流的两条建议在后台终端运行--watchagent 波次之间的代码改动会被自动拾取如果 agent 同时还在写文档或笔记那些波次结束后需要手动执行一次/graphify --update来补上语义重抽取。配套的check_update()函数cron 安全恒返回 True会在标志文件存在时打印“Run/graphify --updateto apply semantic re-extraction”的提示方便定时任务把待办暴露给用户。三、源码纵深watch 的一次完整重建到底做了什么_rebuild_code()watch.py 核心函数是上述“代码变更立即重建”的执行体其调用链可概括为目录稳定化_stabilize_rebuild_cwd()处理 git hook 继承的临时工作目录已被删除的情况通过GRAPHIFY_REPO_ROOT环境变量恢复 CWD加锁_rebuild_lock()用fcntl.flock做每仓库咨询锁Windows 上退化为直通锁文件.rebuild.lock写入持有者 PID 供外部轮询拿不到锁时增量变更会先写入.pending_changes排队锁持有者重建前后各清空一次队列并合并变更集对应并发 post-commit hook 场景源码标注为 issue #1059检测与抽取重新detect()出代码语料并复用上次的--exclude持久化配置.graphify_build.json对已有语义层的文档跳过 AST 快扫然后extract()只解析变更/全量文件增量重建时还会从已有graph.json中借来未重建文件的 AST 节点作为跨文件解析上下文避免“改 A 文件导致 A→B 的调用边消失”与已有图谱调和_reconcile_existing_graph()把新抽取与保留的旧节点/边/超边合并驱逐已删源文件的内容并做 fail-closed 的“排除存活文件”保护——文件仍在磁盘但被过滤掉时不会当成删除而误清节点而是保留并大声提示聚类与报告cluster() 社区标签复用校验 generate()报告 to_json()原子写盘先写.graph.tmp.json再replace若候选图谱与现有图谱规范化后完全相同则不写任何文件打印No code-graph changes detected收缩护栏_check_shrink()拒绝“节点数变少且损失无法被本次重建/删除来源解释”的写盘防语义 chunk 丢失导致的静默塌陷除非损失全部归属本次重建过的源文件或已声明的删除路径收尾更新manifest.json、清掉陈旧的needs_update标志、按需重生成graph.html与已存在的*-callflow.html。监听侧的事件过滤同样有讲究.graphifyignore模式在启动时一次性加载避免高频文件系统事件下反复解析opened/closed_no_write这类“只读”事件被显式过滤Linux inotify 会对每次打开文件产生事件不过滤会导致监听器自我触发、空转烧 CPUmacOS 上使用PollingObserverFSEvents 对快速保存可能漏报graphify-out目录自身与含.开头的路径分量一律忽略。四、实操注意事项与适用前提执行环境两个命令都通过graphify-out/.graphify_python记录的解释器运行前提是已经有一次完整的/graphify构建在该目录下产生了graphify-out/视频 URL必须额外安装pip install graphifyy[video]依赖 yt-dlp 与 faster-whisper转写要求 Python 3.11否则ingest()在 youtube 分支的download_audio导入会失败并抛RuntimeError失败即报告ingest()对非法 URL 抛ValueError、对抓取失败抛RuntimeError且 watch.py 的重建路径对“读不懂的既有 graph.json”采取 fail-closed——宁可拒绝覆写也不吞错删除语义文件纯删除批次由 watch 的 reconcile 扫描直接处理不会留下陈旧的needs_update标志但新增/修改文档仍需一次手动/graphify --update验证参考watch 的并发排队、锁定与收缩护栏行为在 tests/test_watch.py 中有大量用例覆盖ingest 的抓取逻辑可在 tests/test_ingest.py 中对照阅读。小结/graphify add url与--watch补齐了 graphify “代码图谱之外”的两块拼图前者把网页、论文、推文、视频等异构外部内容以统一的 frontmatter-markdown/二进制格式纳入./raw语料库后者让代码变更在毫秒级被监听器捕获后零 LLM 成本地刷新graph.json与GRAPH_REPORT.md而把需要语义理解的文档变更明确交给/graphify --update。两者合在一起构成了 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/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考