graphify /graphify 技能全流程解析：从单条命令到可查询知识图谱的 Amp 平台执行手册

graphify 是一个把任意代码仓库、文档、SQL schema、配置文件乃至 PDF 变成可查询知识图谱的工具，其核心交付物之一就是分发给各 AI Agent 平台的 /graphify 技能文件。graphify/skill-amp.md 是面向 Amp 平台的技能定义（安装时展开为 graphify/skills/amp/ 目录），它不是普通 README，而是一份可执行的操作规程：规定了 Agent 被调用后必须按什么顺序检测文件、做什么样的双轨抽取、如何合并缓存、如何构建与校验图谱，以及构建完成后如何回答自然语言查询。读完本文，你能完整理解 graphify 全流水线每一步在做什么、产物文件（graphify-out/ 下的一批 sidecar）如何流转，以及背后的确定性 AST 抽取与 LLM 语义抽取是如何并行协作的。

这份技能文件在 graphify 中的位置

graphify 的仓库里，每个 Agent 平台（Claude Code、Cursor、Codex、Amp 等）都有一份技能模板，Amp 版本对应 skill-amp.md，其运行期引用的参考资料位于 skills/amp/references/ 目录：

• extraction-spec.md：语义抽取子 Agent 的完整提示词（JSON schema、节点 ID 规则、置信度评分标准）；
• query.md：query / path / explain 的遍历流程与查询词扩展规则；
• update.md：--update 增量重建与 --cluster-only 流程；
• github-and-merge.md：GitHub 仓库克隆与多路径合并流程；
• exports.md：wiki、Neo4j、FalkorDB、SVG、GraphML、MCP 等导出；
• add-watch.md：URL 摄取与 --watch 自动重建；
• hooks.md：commit hook 与 AGENTS.md 集成。

技能文件的定位是“Agent 的剧本”：它假设执行环境是一个能运行 bash、能派发子 Agent（Task 工具）、能读写本地文件的 AI 编程助手，所有步骤都以“替换占位符后执行代码块”的方式编写。

完整命令面：/graphify 支持什么

技能文件开头的 Usage 一节定义了全部调用形式，这也是 /graphify --help 必须原样打印的内容：

/graphify                                             # full pipeline on current directory (HTML viz; add --obsidian for a vault)
/graphify <path>                                      # full pipeline on specific path
/graphify https://github.com/<owner>/<repo>           # clone repo then run full pipeline on it
/graphify https://github.com/<owner>/<repo> --branch <branch>  # clone a specific branch
/graphify <url1> <url2> ...                           # clone multiple repos, build each, merge into one cross-repo graph
/graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
/graphify <path> --update                             # incremental - re-extract only new/changed files
/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
/graphify <path> --whisper-model medium                # use a larger Whisper model for better transcription accuracy
/graphify <path> --cluster-only                       # rerun clustering on existing graph
/graphify <path> --no-viz                             # skip visualization, just report + JSON
/graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
/graphify <path> --svg                                # also export graph.svg (embeds in Notion, GitHub)
/graphify <path> --graphml                            # export graph.graphml (Gephi, yEd)
/graphify <path> --neo4j                              # generate graphify-out/cypher.txt for Neo4j
/graphify <path> --neo4j-push bolt://localhost:7687   # push directly to Neo4j
/graphify <path> --falkordb                           # generate graphify-out/cypher.txt for FalkorDB
/graphify <path> --falkordb-push falkordb://localhost:6379   # push directly to FalkorDB
/graphify <path> --mcp                                # start MCP stdio server for agent access
/graphify <path> --watch                              # watch folder, auto-rebuild on code changes (no LLM needed)
/graphify <path> --wiki                               # build agent-crawlable wiki (index.md + one article per community)
/graphify <path> --obsidian --obsidian-dir ~/vaults/my-project  # write vault to custom path
/graphify add <url>                                   # fetch URL, save to ./raw, update graph
/graphify query "<question>"                          # BFS traversal - broad context
/graphify query "<question>" --dfs                    # DFS - trace a specific path
/graphify query "<question>" --budget 1500            # cap answer at N tokens
/graphify path "AuthModule" "Database"                # shortest path between two concepts
/graphify explain "SwinTransformer"                   # plain-language explanation of a node

几个值得注意的设计选择：

• --directed 决定是否保留边方向。默认构建的是无向图，加该标志后底层会构建 DiGraph，源→目标方向在 graph.json 中得以保留；
• --mode deep 只影响语义抽取的激进度——要求子 Agent 更主动地产生 INFERRED 边，而不是改结构抽取；
• --obsidian 默认关闭，因为它会“每个节点生成一个 Markdown 文件”，成本与体量都大。

快速路径：已有图谱时先查询，不要重建

技能文件对 Agent 的第一条硬约束是：在被调用后先检查 graphify-out/graph.json 是否存在。如果存在，且用户请求是自然语言问题（“X 是怎么工作的？”“谁调用了 Y？”）而不是显式重建命令（--update、--cluster-only 或裸路径/URL），则跳过 Step 1–5，直接执行 graphify query "<question>"——不跑检测、不问语料规模、不让用户缩小范围。

这条“Fast path”设计解决了一个典型的 Agent 行为问题：模型倾向于重新跑完整流水线来“保险”，但对已构建的图这是纯粹的浪费。技能文件用“skip Steps 1–5 entirely”这种不留解释余地的措辞强制走查询路径。

未给路径时默认为当前目录 .，也不允许向用户反问路径。

Step 0/1：解析 URL 与锁定 Python 解释器

当路径参数是 https://github.com/... 时，Agent 先走 github-and-merge.md 描述的克隆与合并流程，多个 URL 则各自构建后合并成跨仓库图谱。

随后是解释器探测。技能文件内置了一段 bash，按优先级依次尝试：

1. uv tool run --from graphifyy python 取 sys.executable（现代 Mac/Linux 上最可靠的 uv tool 安装）；
2. 读取 which graphify 得到的二进制的 shebang 行，验证它能 import graphify（覆盖 pipx 与直接 pip 安装）；
3. 回退到 python3。

探测成功后做两件事并持久化：

"$PYTHON" -c "import sys; open('graphify-out/.graphify_python', 'w', encoding='utf-8').write(sys.executable)"
echo "$(cd INPUT_PATH && pwd)" > graphify-out/.graphify_root

.graphify_python 记录的是解释器的绝对路径，之后所有代码块都用 $(cat graphify-out/.graphify_python) 代替 python3；.graphify_root 记录扫描根的绝对路径，供无参的 graphify update 下次运行时定位语料。这两个文件就是技能文件里“解释器守护”一节的存在原因：子命令（--update、query、path、explain、add）执行前会检查 .graphify_python 是否存在，缺失（例如用户删了 graphify-out/）时按 shebang → python3 的顺序重新解析。

注意包名细节：PyPI 上的发行包名是 graphifyy（uv tool install graphifyy、pip install graphifyy），而 import 名是 graphify。这是安装章节最容易踩的坑。

Step 2：文件检测（detect）

Agent 用 Python 单行块调用 graphify.detect.detect(Path('INPUT_PATH'))，并把结果写到 graphify-out/.graphify_detect.json。技能文件特意要求由 Python 而不是 shell 重定向写这个 sidecar，原因是避免 PowerShell 宿主上的控制台编码漂移（注释中引用的 issue #2528）。

检测结果要给出人类可读摘要，0 文件的类别省略：

Corpus: 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 ...)

然后按三个分支处置，这套分支逻辑对应 detect.py 中 detect() 函数（第 1665 行起）的返回值结构：

• total_files 为 0：停止，报 “No supported files found in [path]”；
• skipped_sensitive 非空：报告跳过数量与文件名单，让用户能发现被误判为敏感的源码或文档，改名或移动即可（issue #2106）；
• total_words > 2,000,000 或 total_files > 500：必须警告，并计算一级子目录的 top 5 文件数分布（从 detect JSON 读 scan_root 绝对路径、合并所有类别的文件列表、剔除 scan_root/graphify-out/ 前缀、取 scan_root 之后的第一级路径组件，根目录直属文件记为 (root)），然后询问用户选哪个子目录跑。若所有文件都在 (root)，则改为建议 --no-cluster 跳过昂贵的聚类步骤；
• 否则：直接进入 Step 2.5（若有视频）或 Step 3。

有视频/音频时，Step 2.5 按 transcribe.md 先用 Whisper 转写（--whisper-model 就是在这一步生效的旋钮），转写文本随后作为文档类文件进入 Step 3。

Step 3：双轨抽取——AST 结构轨 + LLM 语义轨

这是整个流水线的核心，技能文件把它拆成 Part A、Part B、Part C，并要求 A 与 B 并行启动（“在同一消息里派发全部语义子 Agent 并启动 AST 抽取”），注释说明这在大语料上能省 5–15 秒，因为两轨操作的文件类型互不重叠。

技能文件在此处还有一段关于 API key 的强约束，值得单独强调：graphify 不需要 API key，Agent 永远不应向用户索要或阻塞于某个 key。代码走纯 AST 结构抽取，零 LLM、零 key——纯代码语料（最常见的 /graphify . 场景）直接跳过语义抽取。文档/论文/图片的语义抽取只在 GEMINI_API_KEY/GOOGLE_API_KEY 已设置时使用 Gemini（pip install 'graphifyy[gemini]'，默认模型 gemini-3-flash-preview，可用 GRAPHIFY_GEMINI_MODEL 或 --model 覆盖）；否则 LLM 就是宿主 Agent 本身。技能文件明确 graphify 不读取 ANTHROPIC_API_KEY、OPENAI_API_KEY 或任何其他 provider key，Agent 若发现自己准备索要这些 key，属于误读了技能文档。

Part A：代码文件的结构抽取

从 .graphify_detect.json 取出 files.code 列表，调用 graphify.extract 的 collect_files + extract：

code_files = []
detect = json.loads(Path('graphify-out/.graphify_detect.json').read_text(encoding="utf-8"))
for f in detect.get('files', {}).get('code', []):
    code_files.extend(collect_files(Path(f)) if Path(f).is_dir() else [Path(f)])

if code_files:
    result = extract(code_files, cache_root=Path('INPUT_PATH'))
    Path('graphify-out/.graphify_ast.json').write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")

产物 .graphify_ast.json 包含 nodes、edges、input_tokens、output_tokens；没有代码文件时写一个空结构并打印 “No code files - skipping AST extraction”。这一步的确定性由 extract.py 及其 extractors/ 目录下的多语言解析器保证——graphify 的卖点之一正是“本地确定性 AST 解析，每条边都有解释”。

Part B：语义抽取（并行子 Agent）

纯代码语料的快速路径：检测到 0 个文档/论文/图片时跳过 Part B，但必须先写空语义文件——因为 Part C 会无条件读 .graphify_semantic.json，缺了会在纯代码运行里抛 FileNotFoundError：

Path('graphify-out/.graphify_semantic.json').write_text(json.dumps(
    {'nodes':[],'edges':[],'hyperedges':[],'input_tokens':0,'output_tokens':0}), encoding='utf-8')

有内容文件时的强制流程（B0–B3）：

1. B0 缓存检查：调用 graphify.cache.check_semantic_cache(all_files, root=..., prompt_file=SPEC_PATH)（实现在 cache.py 第 1233 行起）。注意两点细节：

   • 只有 document/paper/image 三类进语义抽取，代码已被 AST 轨覆盖，把全部类别拍平会让子 Agent 重读所有源码文件（issue #1392）；
   • prompt_file 参数把 extraction-spec.md 的路径作为 key 的一部分盖章——当 graphify 升级修改了提示词，旧提示词产生的缓存条目会被重新抽取而不是重放（issue #1939）。B0 读取和 B3 写入必须传同一个 SPEC_PATH，否则条目会写进下次运行找不到它的位置。
   • 命中缓存时写 .graphify_cached.json，没有命中时删除任何遗留的旧文件，保证 Part C 不会合并到过期的缓存；未命中文件清单写入 .graphify_uncached.txt。

2. B1 分块：从 .graphify_uncached.txt 读文件，每块 20–25 个；每个图片单独成块（视觉理解需要独立上下文）；同目录文件归入同一块，提高跨文件关系的抽取概率。派发前先打印耗时估算：agents = ceil(uncached_non_code_files / 22)，每批约 45 秒，总量 ≈ 45s × ceil(agents / parallel_limit)。

3. B2 单条消息派发全部子 Agent：技能文件用大写强调必须使用 Task 工具（Amp 平台的子 Agent 派发机制），一次响应里对每个 chunk 各调一次以并行运行，“逐个自己读文件禁止——慢 5–10 倍”。每个子 Agent 收到的提示词是 extraction-spec.md 的逐字内容，替换其中的 FILE_LIST、CHUNK_NUM、TOTAL_CHUNKS、DEEP_MODE、CHUNK_PATH 五个占位符，并把结果写到绝对路径的 graphify-out/.graphify_chunk_NN.json。技能文件特别警告 CHUNK_PATH 必须是绝对路径——相对路径会按未定义的 cwd 解析导致文件静默丢失，且这个路径基准是当前工作目录（Part C 从 graphify-out/ 取块文件的地方），而不是 .graphify_root 指向的扫描目录。

4. B3 收集、缓存、合并：以“graphify-out/.graphify_chunk_NN.json 出现在磁盘上”为成功信号。文件缺失多半是子 Agent 被派成了只读类型，要显式警告（“chunk N missing from disk — subagent may have been read-only”）而不是静默跳过；超过半数 chunk 失败则停止，提示用户确认 subagent_type="general-purpose"。另一个容易被忽略的细节：chunk JSON 里的 token 数永远是占位零，真实 token 数要从每次 Agent 调用的 usage 字段读出来，在合并前写回 chunk JSON。随后用 glob 合并所有块为 .graphify_semantic_new.json，再用 save_semantic_cache(..., prompt_file=SPEC_PATH) 落缓存，最后把缓存部分与新结果按节点 id 去重合并成最终的 .graphify_semantic.json，并清理三个临时文件（.graphify_cached.json、.graphify_uncached.txt、.graphify_semantic_new.json）。

抽取规范本身（extraction-spec.md 定义的内容）是理解产物质量的关键。其中与图谱完整性直接相关的规则包括：

• 边置信度三档：EXTRACTED（源码中显式存在，置信度恒为 1.0）、INFERRED（合理推断，只能从离散值 0.95 / 0.85 / 0.75 / 0.65 / 0.55 中取一个，禁止 0.5 默认值）、AMBIGUOUS（0.1–0.3，标记待审而非丢弃）；
• 节点 ID 确定性：格式 {stem}_{entity}，stem 是去掉扩展名的完整仓库相对路径（每段小写、非字母数字转下划线），例如 src/auth/session.py + ValidateToken → src_auth_session_validatetoken。必须与 AST 抽取器生成的 ID 一致，用文件名或仅父目录会产生孤儿重复节点；也绝不能给 ID 追加 chunk 编号之类的后缀——同一实体无论在哪个 chunk 处理都必须得到同一 ID；
• file_type 六值枚举：code / document / paper / image / rationale / concept，其他值会被拒；
• source_file 逐字规则：节点、边、超边上的 source_file 必须照抄 FILE_LIST 中的绝对路径，不做任何缩短或重新相对化——这是全量构建与增量 --update 使用同一基准、让重新抽取时“替换”而非“叠加”的前提；
• 超边（hyperedge）：3 个及以上节点共同参与的、成对边无法表达的关系（如共同实现某协议的所有类），每块最多 3 条；
• calls 边方向与同语言约束：source 必须是调用方，且不允许跨语言（Python 函数 calls JS 符号属于幻影边）。

Part C：合并双轨

Part C 是一段纯 JSON 拼接：先读 .graphify_ast.json 与 .graphify_semantic.json，AST 节点在前，语义节点按 id 去重后追加，边与超边直接相加，token 数沿用语义轨的值，写出 .graphify_extract.json。合并规则刻意简单——确定性轨拥有 ID 命名权，语义轨只做增量补充。

Step 4：构建图谱、聚类、分析与产出

这一步把所有 Python 分析函数串起来，对应的 import 全部指向仓库内的实现模块：

from graphify.build import build_from_json
from graphify.cluster import cluster, score_all
from graphify.analyze import god_nodes, surprising_connections, suggest_questions
from graphify.report import generate
from graphify.export import to_json

G = build_from_json(extraction, root='INPUT_PATH', directed=IS_DIRECTED)
communities = cluster(G)
cohesion = score_all(G, communities)
gods = god_nodes(G)
surprises = surprising_connections(G, communities)
questions = suggest_questions(G, communities, labels)

各函数的实现位置：build_from_json 在 build.py（directed=True 时构建保留方向的 DiGraph，这也是 --directed 标志的唯一落点）；cluster（社区检测）与 score_all（社区凝聚度打分）在 cluster.py；god_nodes（枢纽节点）、surprising_connections（跨社区的意外桥接）、suggest_questions（建议问题）在 analyze.py。

技能文件在这一步植入了两道“防静默损坏”闸门，都是从生产事故（issue 编号可见）中沉淀下来的：

• 空图守卫：build_from_json 之后在任何写盘之前检查 G.number_of_nodes() == 0，是则直接 SystemExit(1) 并报可能原因（文件全部被跳过、纯二进制备料库、抽取失败）。目的是防止一次空抽取把健康的 graph.json / GRAPH_REPORT.md 覆盖掉（issue #1392）；
• 缩小守卫（shrink-guard，issue #479）：to_json 返回 False 表示新图比既有 graph.json 节点更少、拒绝写入。从 export.py 中 to_json 的实现（第 266 行起，force: bool = False 参数）可以看到该守卫的语义：无法证明新图不是静默缩小时，宁拒写。技能文件要求只在 to_json 真的写入成功时才写报告与分析 sidecar，保证它们描述的永远是 graph.json 里真实存在的图。若缩小是有意为之（用户删了文件），需带 --force 重跑全量构建。

root='INPUT_PATH' 参数同样有讲究：它与增量 --update 的 runbook 使用同一基准（issue #1361），把 source_file 相对化到同一 base，保证全量构建与增量重建在节点 key 上永远一致，不会漂移出重复节点。

Step 4.5：图谱健康检查（只读完整性闸门）

在打标签之前跑一次非破坏性诊断，实现是 diagnostics.py 的 diagnose_extraction + format_diagnostic_report，针对增量更新与 AST/LLM ID 不匹配这两类场景最易出现的“静默损坏模式”：

• dangling_endpoint_edges：悬挂端点（边指向不存在的节点）；
• missing_endpoint_edges：缺失端点；
• self_loop_edges：自环；
• directed_same_endpoint_collapsed_edges / undirected_same_endpoint_collapsed_edges：同端点边坍缩（多张语义不同的边被折叠成一条）。

诊断是只读的、永不中断流水线；若打印出 GRAPH HEALTH WARNING，必须在最终总结里原样呈现——“图仍可用，但完整性问题必须可见”，这是技能文件 Honesty Rules 的一部分。

Step 5：社区标签——Agent 亲手写名字

cluster(G) 产出的是数字 ID 的社区。技能文件要求 Agent 自己读 .graphify_analysis.json，为每个社区根据其中节点标签起一个 2–5 个词的白话名（“Attention Mechanism”“Training Pipeline”），然后把 labels 字典替换进代码块重新生成报告：

labels = LABELS_DICT  # 例：{0: "Attention Mechanism", 1: "Training Pipeline"}
questions = suggest_questions(G, communities, labels)   # 标签影响问题措辞，要重新生成
report = generate(G, communities, cohesion, labels, analysis['gods'], analysis['surprises'],
                  detection, tokens, 'INPUT_PATH', suggested_questions=questions)

同时写 .graphify_labels.json 供可视化使用，并用 to_json(..., community_labels=labels) 重新导出，让 graph.json 的节点携带审校过的 community_name（issue #2490）。由于使用的是同一份 extraction，缩小守卫在节点数上必然通过；万一仍被拒，按守卫消息处理而不是强行绕过。

Step 6 及之后的条件导出

• HTML 总是生成（除非 --no-viz）：graphify export html，节点数超过 5000 时自动聚合到社区视图；
• Obsidian vault 仅在显式 --obsidian 时生成：graphify export obsidian，可用 --dir 指定已有 vault 路径；
• Steps 6b–8（wiki、Neo4j/FalkorDB 的 cypher.txt 生成或直推、SVG、GraphML、MCP stdio 服务、token 缩减基准测试）全部是标志驱动的，默认运行不带任何导出标志时全部跳过；total_words 超 5000 会额外触发基准测试。各导出的具体参数见 exports.md，且 --wiki 要在 Step 9 清理前执行，因为 wiki 生成依赖 .graphify_labels.json 还在。

Step 9：manifest、成本记账与清理

收尾步骤做三件事，其中 manifest 逻辑是整个增量能力（--update）的地基：

1. 保存 manifest 供 --update 使用：调用 detect.py 的 save_manifest(_manifest_files, root=..., scan_corpus=..., clear_semantic=...)。三个参数各有对应的事故编号：
   • root= 把 manifest key 相对化到扫描根，使 manifest 跨克隆/机器可移植，之后的 --update 能匹配到缓存文件而不是全部当新文件处理（#1417）；
   • 文件清单由 graphify.cli._stamped_manifest_files 计算：只有真正产出节点/边的语义文件才盖章。某个文档的 chunk 失败或被遗漏时必须不盖章，否则下次 --update 会把它标记为已完成、内容永久丢失（#2015）。代码文件无条件盖章，因为 AST 是确定性的；
   • 本次派发但未盖章的文件要清除旧 semantic_hash（clear_semantic），否则 detect_incremental 会误判为未变化而不重新排队（#1948）；scan_corpus 传原始全量语料而非盖章子集，这样上次运行后新被排除的根内文件是被“移除”而非伪装成“删除”，未动文件的既有行仍保留（#1908）。
2. 成本记账：把本次运行的 input/output token 追加进 graphify-out/cost.json 的 runs 数组并累加总量，对应报告里“always show token cost”的诚实规则。
3. 清理：删除 .graphify_detect.json、.graphify_extract.json、.graphify_ast.json、.graphify_semantic.json、.graphify_analysis.json 与所有 .graphify_chunk_*.json。

最终向用户报告产物清单（graph.html、GRAPH_REPORT.md、graph.json，可选 obsidian/），并把报告中的三个章节——God Nodes、Surprising Connections、Suggested Questions——贴进对话（不贴全量报告），然后挑出“跨社区边界最多或桥接节点最意外”的那条建议问题主动邀请用户探索。技能文件对此的定调是一句话：“The graph is the map. Your job after the pipeline is to be the guide.”

子命令流：--update、query、add、--watch 与 hooks

技能文件把非默认子命令指向各自的 reference 文档，这里概括其要点：

• --update / --cluster-only：见 update.md。--update 只重新抽取新增或变更的文件（依据正是 Step 9 的 manifest），--cluster-only 在现有图上重跑聚类。二者执行前都要走“解释器守护”检查。
• query / path / explain：见 query.md。其核心机制值得展开，因为它解释了为什么查询要“先扩展再遍历”：graphify query CLI 在节点匹配上用的是大小写折叠的子串 + IDF，二进制内部没有词干还原、没有同义词、没有跨语言匹配。用户说 “authentication” 而图里叫 “Guardian” 时，字面匹配直接 0 命中。query reference 的解法是先从 graph.json 的节点标签里抽出真实词表（.vocab.txt），然后只从词表中选出最多 12 个语义对应的 token 拼成扩展查询串——禁止发明 token、禁止凭训练记忆替换近义词、词表完全不匹配时如实告知语料中没有相关词汇而不是编造检索。遍历分两种模式：默认 BFS（“X 都连着什么”，宽上下文）与 --dfs（“X 如何到达 Y”，追链路），--budget N 限制答案 token 上限；CLI 不可用时回退为对 graph.json 的内联 NetworkX 遍历。回答只依据图内容，引用具体事实时必须引用 source_location。
• add <url> / --watch：见 add-watch.md。add 抓取 URL 存入 ./raw（支持 --author/--contributor 元数据标签，extraction-spec 里要求子 Agent 把 frontmatter 的 author/contributor 抄到该文件的所有节点上）；--watch 监听目录、代码变更自动重建，且不需要 LLM。
• commit hook 与 AGENTS.md 集成：见 hooks.md，用于安装 post-commit 自动重建钩子或把 graphify 写进项目的 AGENTS.md。

Honesty Rules：技能文件的诚实约束

skill-amp.md 末尾的五条规则定义了 graphify 输出风格的底线，也是理解“每条边都有解释”这一产品承诺最直接的窗口：

• 绝不虚构边；不确定就用 AMBIGUOUS（而不是丢弃）；
• 绝不跳过语料规模检查的警告；
• 报告里必须展示 token 成本；
• 凝聚度分数不许藏在符号后面——显示原始数字；
• 超过 5000 节点的图跑 HTML 可视化前必须警告用户。

小结：这套技能文件教会 Agent 的三件事

graphify/skill-amp.md 与其说是文档，不如说是一份经过 issue 编号打磨过的运行手册，它向宿主 Agent 传递了三层约束：

1. 确定性优先：代码走 AST、缓存按提示词版本失效、manifest 只对产出过内容的文件盖章、空图与缩小都有写盘前的守卫——所有“静默损坏”路径都被显式拦截（build.py、export.py、diagnostics.py、cache.py 是对应的实现证据）；
2. 并行与成本意识：AST 与语义抽取并行、子 Agent 按 20–25 文件分块并行派发、token 成本累计记账，且明确“不读任何宿主 key、不为 key 阻塞”；
3. 诚实与导航：EXTRACTED/INFERRED/AMBIGUOUS 三档置信度全程贯穿到 graph.json，查询时先对图自己的词表做受控扩展再遍历，构建完成后主动引导用户沿图探索——这正是 graphify “本地确定性 AST 解析、每条边可解释、无向量库”这一设计定位在 Agent 交互层的完整落地。