在 Kiro IDE/CLI 中部署 graphify 知识图谱技能：从安装到查询的完整实战指南

本指南以仓库中的 graphify/skill-kiro.md（与 graphify/skill.md 完全一致的 Kiro 平台技能定义文件）为核心主体，系统讲解 graphify 如何把任意代码库、文档、PDF、图片乃至视频转成可查询的知识图谱：从 Kiro 专属安装（.kiro/skills/ + .kiro/steering/）、逐步执行管线（检测 → 提取 → 建图 → 标注 → 导出），到图上的 query / path / explain 交互方式。读完你可以在 Kiro IDE/CLI 中直接使用 /graphify 命令构建并查询项目知识图谱，并理解其"无向量库、纯本地 AST、边带证据"的底层原理。

Kiro 平台的一键安装：skill 与 always-on 引导文件

在 Kiro IDE/CLI 中使用 graphify 之前，先通过 CLI 注册技能。安装命令来自 README.md 的平台支持表：

uv tool install graphifyy      # 安装 CLI（或 pipx install graphifyy）
graphify kiro install          # 注册到 Kiro IDE/CLI

graphify kiro install 实际写入两类文件，实现在 graphify/install.py 的 _kiro_install() 中：

文件	作用	写入位置
技能本体	/graphify 命令的完整执行协议（即本指南所依据的 skill-kiro.md 内容）	.kiro/skills/graphify/SKILL.md（项目级）
references/ 侧车	8 个配套参考文档（提取规范、查询、更新、导出等）与 .graphify_version 版本戳	.kiro/skills/graphify/references/
always-on 引导	每次会话自动注入的"先查图"指令	.kiro/steering/graphify.md

关键实现细节：源码注释指出，早期版本用裸 write_text 绕过 _copy_skill_file，导致 references/ 目录和版本戳从未写入（issue #1142）；修复后统一走共享的渐进披露助手。卸载同样简单：

graphify kiro uninstall        # 删除 .kiro/skills/graphify/ 与 .kiro/steering/graphify.md

对应的 _kiro_uninstall() 在 graphify/install.py 中逐项删除技能文件、references 侧车与 steering 文件。

steering 文件：让 Kiro "每次对话都先读图"

安装后写入 .kiro/steering/graphify.md 的内容来自仓库中的 graphify/always_on/kiro-steering.md，全文如下：

graphify: A knowledge graph of this project lives in graphify-out/. For codebase, architecture, or dependency questions, when graphify-out/graph.json exists, first run graphify query "<question>" (or graphify path "<A>" "<B>" / graphify explain "<concept>"). These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. Read GRAPH_REPORT.md only for broad architecture review or when those commands do not surface enough context.

这份文件是 Kiro 上的"查询优先"机制：它没有像 Claude Code / Gemini CLI 那样的 PreToolUse 钩子，而是通过 steering 文件在每个会话开头提醒 agent：一旦 graphify-out/graph.json 存在，代码库问题应优先用 graphify query 等命令获取局部子图，而不是通读报告或逐个 grep 文件。安装器会在内容相同时输出 already configured (no change)，升级时则整体覆盖（issue #580），避免旧版"先报告"措辞残留。

技能核心：把任意文件夹变成可查询的知识图谱

/graphify 的设计目标一句话概括：把任意一个文件夹里的文件变成带有社区检测、诚实审计轨迹和三种产物的可导航知识图谱——交互式 HTML（graph.html）、GraphRAG 就绪的 JSON（graph.json）、以及平实语言写的 GRAPH_REPORT.md。

完整命令速查

以下命令表原样继承自 graphify/skill-kiro.md，覆盖构建、更新、导出与查询全流程：

/graphify                                             # 对当前目录跑完整管线（HTML 可视化；加 --obsidian 生成 vault）
/graphify <path>                                      # 对指定路径跑完整管线
/graphify https://github.com/<owner>/<repo>           # 克隆仓库后跑完整管线
/graphify https://github.com/<owner>/<repo> --branch <branch>  # 克隆指定分支
/graphify <url1> <url2> ...                           # 克隆多个仓库，各自建图后合并成跨仓库图谱
/graphify <path> --mode deep                          # 深度提取，生成更丰富的 INFERRED 边
/graphify <path> --update                             # 增量更新 - 只重新提取新增/变更文件
/graphify <path> --directed                           # 构建有向图（保留边的方向 source→target）
/graphify <path> --whisper-model medium               # 使用更大的 Whisper 模型提升转写准确率
/graphify <path> --cluster-only                       # 在已有图上重跑聚类
/graphify <path> --no-viz                             # 跳过可视化，只出报告 + JSON
/graphify <path> --html                               # （HTML 默认生成 - 该 flag 是空操作）
/graphify <path> --svg                                # 额外导出 graph.svg（可嵌入 Notion、GitHub）
/graphify <path> --graphml                            # 导出 graph.graphml（Gephi、yEd）
/graphify <path> --neo4j                              # 生成 graphify-out/cypher.txt 供 Neo4j 使用
/graphify <path> --neo4j-push bolt://localhost:7687   # 直接推送到 Neo4j
/graphify <path> --falkordb                           # 生成 graphify-out/cypher.txt 供 FalkorDB 使用
/graphify <path> --falkordb-push falkordb://localhost:6379   # 直接推送到 FalkorDB
/graphify <path> --mcp                                # 启动 MCP stdio 服务器供 agent 访问
/graphify <path> --watch                              # 监听文件夹，代码变更时自动重建（无需 LLM）
/graphify <path> --wiki                               # 构建 agent 可爬取的 wiki（index.md + 每个社区一篇文章）
/graphify <path> --obsidian --obsidian-dir ~/vaults/my-project  # 写入自定义路径的 vault（如已有 vault）
/graphify add <url>                                   # 抓取 URL，存入 ./raw，更新图谱
/graphify add <url> --author "Name"                   # 标记作者
/graphify add <url> --contributor "Name"              # 标记语料贡献者
/graphify query "<question>"                          # BFS 遍历 - 获取宽泛上下文
/graphify query "<question>" --dfs                    # DFS - 沿特定路径追踪
/graphify query "<question>" --budget 1500            # 将答案限制在 N 个 token 内
/graphify path "AuthModule" "Database"                # 两个概念之间的最短路径
/graphify explain "SwinTransformer"                   # 对某个节点的平实语言解释

三类产物与诚实审计

运行一次 /graphify 后，graphify-out/ 目录下产生三个核心产物：

graphify-out/
├── graph.html       # 交互式图谱，浏览器打开即可点击、筛选、搜索
├── GRAPH_REPORT.md  # 亮点报告：关键概念、意外连接、建议问题
└── graph.json       # 完整图数据，随时可查而无需重读文件

与向量索引的本质区别是：图上的每条边都带有置信度标签——EXTRACTED（源码中显式存在）或 INFERRED（graphify 解析推断），不确定时使用 AMBIGUOUS。这就是"诚实的审计轨迹"：你可以随时分辨哪些连接是直接读出来的、哪些是推导出来的。项目描述中"no vector store"正是此意：不依赖 embedding 与向量库，而是用一棵可遍历的真实图结构承载语义。

被调用时的执行协议：快速路径与逐步管线

技能文件为 agent 定义了严格的调用协议（graphify/skill-kiro.md）：

• 帮助请求短路：若用户调用 /graphify --help 或 -h 且无其他参数，直接逐字打印上文 ## Usage 块并停止，不运行任何命令。
• 快速路径（已有图谱）：执行任何操作前先检查当前工作目录下 graphify-out/graph.json 是否存在。若存在且用户是自然语言提问（如 "X 是怎么工作的？""谁调用了 Y？"），且不是显式重建命令（--update、--cluster-only 或裸路径/URL），则跳过 Steps 1–5，直接跳到 graphify query "<question>"——不跑 detect、不检查语料规模、不要求用户缩小范围。
• 默认路径：未给路径时默认使用 .（当前目录），不向用户询问路径。
• GitHub URL 识别：路径以 https://github.com/ 或 http://github.com/ 开头时，先执行 Step 0 克隆，再用解析后的本地路径继续。

Step 0 - GitHub 仓库与多路径合并

仅当传入一个或多个 GitHub URL、或需要合并多个本地子文件夹时执行。克隆、跨仓库合并与 monorepo 流程见 graphify/skills/kiro/references/github-and-merge.md。普通本地路径直接跳过此步。

Step 1 - 确保 graphify 已安装

技能内置了一段解释器探测脚本（graphify/skill-kiro.md），按优先级处理 uv tool、pipx、venv、系统级安装：

1. uv tool 安装（现代 Mac/Linux 最可靠）：uv tool run --from graphifyy 探测实际解释器；
2. 读取 graphify 二进制的 shebang：兼容 pipx 与直接 pip 安装；
3. 回退 python3：若 import graphify 失败，优先 uv tool install --upgrade graphifyy，否则 pip install graphifyy（必要时加 --break-system-packages）。

随后把解释器路径写入 graphify-out/.graphify_python、把扫描根目录写入 graphify-out/.graphify_root。后续所有 bash 块都用 $(cat graphify-out/.graphify_python) 替换 python3，确保每次调用使用同一解释器；.graphify_root 则让无参的 graphify update 知道下次该去哪扫描。

Step 2 - 文件检测与语料摘要

调用 graphify.detect.detect()（源码见 graphify/detect.py），把结果以 UTF-8 写入 graphify-out/.graphify_detect.json（由 Python 写入而非 shell 重定向，避免 PowerShell 主机上的控制台编码漂移，issue #2528）。agent 不打印原始 JSON，而是呈现简洁摘要：

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

（数量为 0 的类别省略。）随后按结果分支：

• total_files 为 0：停止并提示 "No supported files found in [path]."；
• skipped_sensitive 非空：报告数量并列出行名，让被误判的敏感文件可见（issue #2106）；
• total_words > 2,000,000 或 total_files > 500：显示警告，按文件数统计顶层 5 个子目录（排除 graphify-out/ 侧车，根目录直属文件计入 (root)），请用户选择子文件夹再运行；若所有文件都在根目录、无子文件夹，则不询问，直接建议 --no-cluster 跳过昂贵的聚类步骤继续；
• 否则直接进入 Step 2.5（有视频时）或 Step 3。

Step 2.5 - 视频与音频转写

仅当 detect 返回了 video 文件才执行。按 graphify/skills/kiro/references/transcribe.md 先把视频/音频转成文本，随后在 Step 3 中按文档处理。--whisper-model 可切换更大的 Whisper 模型提升准确率。

Step 3 - 提取实体与关系：AST 与语义双轨并行

提取分两部分：结构化提取（确定性、免费）与语义提取（LLM、消耗 token）。技能在此强调一个反直觉原则（graphify/skill-kiro.md）：

graphify 不需要 API key，永远不要向用户索要，也永远不要因缺失而阻塞。 代码用 AST 结构化提取（无 LLM、无 key）；纯代码语料（最常见的 /graphify .）直接跳过语义提取。语义提取（仅针对文档、论文、图片）只在 GEMINI_API_KEY/GOOGLE_API_KEY 已设置时才调用 Gemini，否则由宿主 agent 自身充当 LLM。graphify 不读取 ANTHROPIC_API_KEY、OPENAI_API_KEY 或任何其他提供商 key。

若未设置 Gemini key，向用户打印一行提示后继续执行、不等待：

Tip: set GEMINI_API_KEY or GOOGLE_API_KEY to use Gemini for semantic extraction (pip install 'graphifyy[gemini]').

默认 Gemini 模型为 gemini-3-flash-preview，可用 GRAPHIFY_GEMINI_MODEL 环境变量或 --model 覆盖；语义提取对应 graphify.llm.extract_corpus_parallel(files, backend="gemini")（见 graphify/llm.py）。AST 与语义两条线并行启动（同一消息内同时分发全部语义 subagent 并启动 AST 提取），大语料可节省约 5–15 秒。

Part A - 结构化提取（代码）：遍历 detect 的 code 列表，调用 graphify.extract.collect_files + extract（graphify/extract.py），结果写入 .graphify_ast.json。无代码文件时写入空结构并打印 "No code files - skipping AST extraction"。

Part B - 语义提取（并行 subagent）：

• 快速路径：纯代码语料（零文档/论文/图片）直接跳过 Part B——但必须先写一个空的 .graphify_semantic.json，否则 Part C 的合并会因文件缺失抛 FileNotFoundError；
• B0 缓存检查：用 graphify.cache.check_semantic_cache（graphify/cache.py）按 references/extraction-spec.md 的绝对路径作为 prompt 指纹，只对未缓存文件（写入 .graphify_uncached.txt）分发 subagent；命中则直接跳到 Part C。缓存条目以 prompt 为归属：graphify 升级改变提取 prompt 时，旧条目会被重新提取而非回放（issue #1939）；
• B1 分块：每 20–25 个文件一块，每张图片独占一块（视觉需要独立上下文），同一目录文件尽量归入同块以利于跨文件关系提取；
• B2 并行分发：必须在同一条消息内多次调用 Agent 工具（每块一次），这是唯一能并行执行的方式；必须用 subagent_type="general-purpose"（有 Write/Bash 权限），禁止用只读的 Explore——它无法把分块结果写盘，会静默丢失提取结果。每个 subagent 收到 graphify/skills/kiro/references/extraction-spec.md 中的提取提示词（JSON schema、节点 ID 规则、置信度 rubric、frontmatter、超边与视觉规则），把结果写到绝对路径 CHUNK_PATH；
• B3 收集合并：以 .graphify_chunk_NN.json 是否存在于磁盘作为成功信号；缺失则警告"chunk N missing from disk — subagent may have been read-only"，失败或 JSON 无效则警告并跳过该块；超过一半块失败则停止并让用户用 general-purpose 重跑。合并到 .graphify_semantic_new.json，把 Agent 结果 usage 字段里的真实 token 数回填到块 JSON，再经 save_semantic_cache 入缓存（同一 SPEC_PATH 写入，保证下次读取命中），最后把缓存 + 新增结果按节点 id 去重合并为 .graphify_semantic.json。

Part C - AST + 语义合并：AST 节点优先、语义节点按 id 去重，边直接拼接，超边取语义侧，token 计数只计语义侧，产出最终的 .graphify_extract.json。

Step 4 - 建图、聚类、分析、导出

调用链清晰对应源码模块（graphify/build.py、graphify/cluster.py、graphify/analyze.py、graphify/report.py、graphify/export.py）：

1. build_from_json(extraction, root=INPUT_PATH, directed=IS_DIRECTED) 构建 NetworkX 图：--directed 时传 True（DiGraph，保留 source→target 方向），否则默认无向 Graph；
2. 空图守卫：建图后立即检查 number_of_nodes() == 0，为空则打印错误并 SystemExit(1)，防止空提取覆盖已有成果（issue #1392）；
3. cluster(G) 做社区检测（Leiden），score_all 计算凝聚度，god_nodes 找"上帝节点"（连接最多的概念），surprising_connections 找跨社区的意外连接，suggest_questions 生成建议问题（占位标签，Step 5 用真实标签重生成）；
4. 导出优先 + shrink 守卫：先 to_json 写 graphify-out/graph.json——若新图节点数小于已存在的 graph.json，to_json 返回 False 且什么都不写（issue #479），此时打印 "refused to shrink" 提示并终止；只有真正写入后才生成 GRAPH_REPORT.md 与 .graphify_analysis.json 侧车，保证报告永远描述的是 graph.json 实际包含的图；
5. root= 参数与 --update 增量流程保持一致基准（issue #1361），避免全量构建与增量重提取在 source_file 相对化上漂移。

Step 4.5 - 图健康检查

这是一个只读的完整性门禁（graphify/diagnostics.py），对提取结果做非破坏诊断，暴露边塌缩、悬空/缺失端点与自环——这些是增量更新和 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: ...，但不中止——图仍可用，只是必须让完整性隐患在最终摘要里可见（诚实规则）。无问题时输出 Graph health: OK。

Step 5 - 社区标注

读取 .graphify_analysis.json，为每个社区写 2–5 个词的平实名称（如 "Attention Mechanism"、"Training Pipeline"、"Data Loading"），替换 LABELS_DICT 后重建报告、写入 .graphify_labels.json，并带 community_labels= 重新导出 graph.json，让节点携带人工校订的社区名（issue #2490）。

Step 6 - Obsidian vault 与 HTML

• HTML 默认总是生成（除非 --no-viz）：graphify export html，图谱超过 5000 节点时自动聚合到社区视图；
• Obsidian 仅当显式传 --obsidian（否则跳过——它会为每个节点生成一个文件）：graphify export obsidian，默认输出到 graphify-out/obsidian，--obsidian-dir <path> 可通过 --dir 指定自定义 vault 路径。

Steps 6b-8 - 可选导出

仅在对应 flag 出现时执行：--wiki（agent 可爬取的 wiki，index.md + 每个社区一篇文章）、--neo4j/--neo4j-push、--falkordb/--falkordb-push、--svg、--graphml、--mcp（MCP stdio 服务器），以及 total_words 超过 5,000 时的 token 缩减基准。默认无导出 flag 的运行全部跳过。详见 graphify/skills/kiro/references/exports.md。注意任何 --wiki 导出都要在 Step 9 清理前执行，以保证 .graphify_labels.json 仍可用。

Step 9 - manifest、成本追踪、清理与汇报

• manifest：调用 graphify.cli._stamped_manifest_files 与 graphify.detect.save_manifest（graphify/detect.py）——只给实际产生输出的语义文件打戳（未产生输出的文件保持未戳状态，下次 --update 会重新入队，issue #2015）；代码文件总是打戳（AST 确定性）；根基准与扫描语料参数保证 manifest 跨克隆/跨机器可移植（issue #1417）；
• 成本追踪：把本轮与累计 token 写入 graphify-out/cost.json；
• 清理：删除 .graphify_detect.json、.graphify_extract.json、.graphify_ast.json、.graphify_semantic.json、.graphify_analysis.json 及各分块文件；
• 汇报：向用户展示产物清单，并从 GRAPH_REPORT.md 粘贴三个章节（God Nodes、Surprising Connections、Suggested Questions），不粘贴全文。

图上提问：query / path / explain

图谱构建完成后的使用方式是"查询而非 grep"。技能文档规定（graphify/skill-kiro.md）：当 graphify-out/graph.json 已存在且用户询问语料相关问题时，直接：

graphify query "<question>"

遍历前会先用图谱自身的词汇表做查询扩展，避免措辞不匹配导致答案塌缩为噪音；CLI 不可用时回退到对 graph.json 的内联 NetworkX 遍历。回答只使用图输出中的内容，引用具体事实时标注 source_location。BFS/DFS 两种遍历模式、--budget token 上限、NetworkX 回退、save-result 反馈以及 path/explain 流程的完整细节见 graphify/skills/kiro/references/query.md。

README 展示了真实输出样例：graphify explain "APIRouter" 返回节点的 Source（routing.py L2210）、Community（2）、Degree（47）及全部 47 条连接（每条标注 [uses]/[imports]/[method] 与 EXTRACTED/INFERRED）；graphify path "FastAPI" "ModelField" 返回 3 跳最短路径（FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField）。汇报结束后，agent 应主动选出最能跨越社区边界的建议问题，邀请用户沿图结构继续探索——"图谱是地图，你的角色是向导"。

增量更新与其他非默认流程

• --update 与 --cluster-only：均为非默认子命令。前者只重新提取新增/变更文件（参考 graphify/skills/kiro/references/update.md），后者在已有图上重跑聚类。两者运行前都要先检查 .graphify_python 是否存在，缺失时（如用户删除了 graphify-out/）先按"解释器守卫"脚本重新解析解释器；
• /graphify add 与 --watch：add <url> 把 URL 抓入语料并更新图，--watch 监听文件夹、代码变更时自动重建（无需 LLM）。参考 graphify/skills/kiro/references/add-watch.md；
• commit hook 与 CLAUDE.md 集成：安装 post-commit 自动重建钩子或把 graphify 接入项目 CLAUDE.md，见 graphify/skills/kiro/references/hooks.md。

Honesty Rules：不可妥协的诚实规则

技能文件以五条铁律收尾（graphify/skill-kiro.md），这也是整条管线设计（审计标签、健康检查、成本披露）的价值底座：

• 绝不编造边；不确定时使用 AMBIGUOUS；
• 绝不跳过语料规模检查警告；
• 报告里必须展示 token 成本；
• 绝不用符号掩盖凝聚度分数——展示原始数字；
• 超过 5,000 节点的图在运行 HTML 可视化前必须警告用户。

从管线到向导：把图谱用起来

在 Kiro IDE/CLI 中，完整工作流是：graphify kiro install 写入技能与 always-on 引导 → /graphify <path> 跑完 Step 0–9 的管线得到 graphify-out/ 三件套 → 之后任何代码库问题都由 steering 文件引导走 query/path/explain 快速路径 → 代码变更后用 --update 增量重建。整个过程代码提取零 LLM、全本地确定性 AST 解析，语义提取可选 Gemini 或宿主 agent，边与边之间永远带着证据与置信度——这正是"图是地图，agent 是向导"这一交互范式的落地实现。