graphify

Graphify

Graphify 是一个 CLI。此技能处理的每个请求，主要都应通过真实的 graphify … 命令完成，而不是斜杠命令，也不是临时编写的 Python 脚本。

当核心问题是**“哪个 graphify 命令能回答这个问题、应针对什么范围，以及接下来该阅读什么？”**时，请使用此技能。

任务包括：

1. 将请求归类到一个图数据包，
2. 选择一种 CLI 模式，
3. 在运行时或令牌开销激增之前限定语料范围，
4. 如实报告产物及任何降级输出，
5. 将仅搜索、仅 Wiki 或项目记忆相关工作转交给合适的相邻技能。

如需查看包含真实标志的完整命令列表，请阅读 references/cli-command-map.md。 安装前请阅读 references/install-matrix.md——尤其是针对 jeo / jeopi / gjc / opencode。 遇到不熟悉的请求时，请阅读 references/mode-packets-and-route-outs.md；原生提取效果不佳时，请阅读 references/build-and-fallback-recipes.md。

CLI 快速入门

pip install graphifyy                       # PyPI package is graphifyy; the binary is graphify
graphify --version

graphify scope                              # what would actually be graphed?
graphify update .                           # build -> .graphify/graph.json + .graphify/GRAPH_REPORT.md
graphify summary                            # hubs, communities, representative nodes
graphify query "where is auth enforced?" --budget 1500
graphify explain <node>                     # one node, plain language
graphify path <source> <target>             # shortest path between two nodes
graphify tree <node> --depth 2              # local neighbourhood
graphify export html                        # -> .graphify/graph.html

以下三点有助于确保回答准确：

• graphify build 不存在。 构建命令是 graphify update。graphify build --help 会静默回退到根帮助信息。
• 状态存储在 .graphify/ 中，而不是 graphify-out/。graphify-out/ 是旧版布局； graphify migrate-state 会迁移该目录。所有 --graph <path> 标志默认指向 <cwd>/.graphify/graph.json。
• graph.html 并非由 graphify update 生成。 它由 graphify export html 生成。

何时使用此技能

• 用户明确需要 GRAPH_REPORT.md、graph.json、graph.html、代码库图谱或 持久化知识图谱
• 请求涉及代码库／语料结构、关系追踪、路径查询或架构发现，并且需要在当前会话结束后继续保留
• 语料混合了代码、文档、PDF、笔记或屏幕截图，而用户希望建立一个持久的 结构层
• 用户希望刷新、查询或说明现有图谱，而不是重新阅读原始文件
• 用户希望获得针对变更的审查上下文、受影响的执行流程，或对差异或 PR 进行风险评分
• 用户希望将 Graphify 安装到 jeo、jeopi、gjc、opencode、Claude、Codex、Gemini 或 其他受支持的 Agent 中

何时不使用此技能

• 只需查找符号、文件负责人、配置位置或引用链 → codebase-search
• 需要持久化的 Markdown 知识库或归档的研究笔记 → llm-wiki
• 需要项目／仓库记忆、清单或跨 Agent 交接数据包 → opencontext
• 只需要依赖项层面的 JS/TS 分析或快速绘制仓库树状图，而非持久化图谱
• 泛泛讨论 GraphRAG／文本知识图谱架构，且没有具体的 Graphify 需求

为 jeo / jeopi / gjc / opencode 安装

graphify install [platform] 只接受以下 ID：claude、codex、gemini、 opencode、aider、copilot、claw、droid、trae、trae-cn、hermes、kimi、kiro、 antigravity、antigravity-windows、vscode-copilot-chat、windows、vscode。

jeo、jeopi 和 gjc 不是平台 ID——graphify install jeo 会像 graphify install agents 一样失败（error: unknown platform）。根据此仓库中的 setup-all-skills-prompt.md，这三个工具会原生发现共享的 ~/.agents/skills 根目录， 而无条件的 universal ID 会填充该目录。因此：

# CLI for everyone
pip install graphifyy && graphify --version

# skill into the shared root that jeo, jeopi, gjc and sst/opencode all read
npx skills add https://github.com/akillness/jeo-skills --skill graphify -a universal
ls "${SKILLS_ROOT:-$HOME/.agents/skills}/graphify/SKILL.md"

# optional: opencode plugin + tool.execute.before hook (sst/opencode only)
graphify install opencode            # or: graphify install opencode --project

graphify install opencode --project 会写入 .opencode/skills/graphify/SKILL.md、 .opencode/plugins/graphify.js、.opencode/opencode.json，以及 AGENTS.md 中的一个章节。 graphify install claude --project 会写入 .claude/skills/graphify/SKILL.md、 .claude/settings.json 中的 PreToolUse hooks，以及 CLAUDE.md 中的一个章节。

已归档的 Go opencode-ai/opencode TUI 没有技能加载器——graphify install opencode 不会在其中显示该技能；可将其作为命令文件接入，或直接使用 CLI。完整详情： references/install-matrix.md。

使用说明

第 1 步：将请求归一化为一个数据包

• repo-structure-packet — 在编辑前梳理代码库或子系统
• relationship-trace-packet — 基于现有图谱回答路径／查询／解释类问题
• mixed-corpus-memory-packet — 跨代码、文档和资源构建持久化结构
• review-diff-packet — 为变更文件生成审查上下文或受影响的流程
• install-packet — 将 Graphify 安装到 Agent 中，以便持续使用
• refresh-or-fallback-packet — 更新现有图谱、修复较差的输出，或进行回退

从用户已有的数据包开始。不要强行让每个请求都经过功能介绍。

第 2 步：选择一种 CLI 模式

模式	主要命令
cli-build	graphify scope → graphify update .
cli-query	graphify summary → query / explain / path / tree
cli-export	graphify export html|wiki|obsidian|svg|graphml|neo4j
incremental-refresh	graphify check-update → graphify update / watch / hook install
review-context	graphify review-context / affected-flows / detect-changes
agent-serve	graphify serve（用于 graph.json 的 stdio MCP 服务）
install	graphify install <platform> 或 ~/.agents/skills 路径
structural-fallback	当原生提取结果为空或有误导性时，构建最精简且准确的结构图谱

指定一种主要模式。至多提及一种备用模式。

第 3 步：先确定范围，再投入资源

对任何不熟悉的内容，先运行 graphify scope。建议的默认范围：

• 只有在确实需要了解整个仓库架构时才使用仓库根目录
• 实现相关工作使用 src/、app/、packages/<pkg>/ 或单个服务目录
• 语料图谱构建使用 raw/、docs/ 或混合研究文件夹
• 若任务是查询／刷新而非重建，则使用现有的 .graphify/

使用 --scope auto|committed|tracked|all 和 .graphifyignore，不要寄希望于运行时行为。 如果请求实质上是定位／引用内容，请转到 codebase-search。

第 4 步：运行最精简的命令集

只运行该模式所需的命令。用户只问一个问题时，不要串联构建、导出、生成 wiki 和 watch 循环。

第 5 步：如实报告降级输出

已验证的行为：未配置 LLM API 密钥时，graphify update . 仍会写入 graph.json 和 GRAPH_REPORT.md，但会打印：

[graphify label] warning: community labeling failed (...); using Community N placeholders.
[graphify describe] description generation failed (...); continuing without descriptions.

发生这种情况时，应说明图谱在结构上完整，但没有标签／描述；配置后端后，可提供 graphify update --fill-missing 作为后续操作。绝不要把占位名称 Community N 说成有意义的集群。

步骤 6：按顺序读取产物

1. .graphify/GRAPH_REPORT.md
2. graphify summary（对于 Agent 工作，比 HTML 更省资源、更有针对性）
3. .graphify/graph.html（执行 graphify export html 后，供人阅读）
4. 最后读取 .graphify/graph.json，并优先使用 graphify query --budget <n>，而不是直接粘贴文件内容

步骤 7：将相邻工作交由其他工具处理

• codebase-search — 精确文本、符号、配置归属，以及绘制图谱前的影响范围映射
• llm-wiki — 叙述性综合、Wiki 页面、长期维护的 Markdown 知识库
• opencontext — 可搜索的决策、清单、稳定链接、项目记忆交接
• survey — 在决定使用 Graphify 前对比工具和平台

对于明确的 Jevgrep 源码发现请求，应通过 jevgrep 搜索 .mex/context 或指定范围的源码树，并遵循其单独的远程内容／成本门槛。在这里使用 query / path / explain 查询图谱关系；Jevgrep 默认既不上传图谱产物，也不负责重建图谱。

如果用户要求“构建或查询图谱”，就留在这里。如果用户要求“快速找到文件”、“将此记录为 Wiki 笔记”或“将此存为项目记忆”，则交由其他工具处理。

步骤 8：返回一份简洁的图谱摘要

信息包 · 主要模式 · 实际运行的命令 · 范围 · 写入的产物 · 输出是否降级或使用了回退方案 · 1–3 条后续命令 · 如果下一步工作应由其他工具负责，则指出一个交接方向。

输出格式

始终返回图谱构建摘要、图谱查询摘要、图谱刷新摘要、审查上下文摘要或Graphify 安装摘要，并包含：

• 当前使用的信息包和一个主要模式
• 实际运行的命令及其范围
• .graphify/ 下存在或已创建的文件
• 如实标明输出是否降级、为占位内容或使用了回退方案
• 先读取 GRAPH_REPORT.md / graphify summary，再读取原始 graph.json
• 如果下一步应由相邻工具负责，则指出一个交接方向

示例

示例 1：编辑前了解代码库

输入

为这个代码库绘制图谱，以便我在修改代码前了解其架构。

良好的输出方向

• repo-structure-packet，模式为 cli-build
• graphify scope → graphify update . → graphify summary
• 报告 .graphify/GRAPH_REPORT.md 和 .graphify/graph.json，并说明 graph.html 需要执行 graphify export html 才会生成

示例 2：追踪现有图谱中的关系

输入

我们已经有图谱了。认证控制器和账单之间有什么关联？

良好的输出方向

• relationship-trace-packet，模式为 cli-query
• graphify summary → graphify path <auth> <billing> → graphify explain <node>
• 不重建图谱

示例 3：审查差异

输入

这个 PR 实际改动了哪些内容？我想了解审查所需的上下文，而不是查看一大堆差异。

良好的输出方向

• review-diff-packet，模式为 review-context
• graphify review-context --base main --detail-level standard 和 graphify affected-flows --base main --json

示例 4：为我们的 Agent 安装

输入

为 jeo、jeopi、gjc 和 opencode 安装 graphify。

良好的输出方向

• install-packet
• 执行 pip install graphifyy，然后通过 -a universal 将技能安装到 ~/.agents/skills，供 jeo/jeopi/gjc 使用；还可选择执行 graphify install opencode
• 明确说明 graphify install jeo 不是有效的平台 ID

示例 5：请求实际是在搜索

输入

我只想找出这个配置定义在哪里，以及哪些地方引用了它。

良好的输出方向

• 交由 codebase-search 处理；不构建图谱

最佳实践

1. 以真实的 graphify 命令开头；切勿编造命令——不存在 graphify build。
2. 使用 .graphify/，而不是 graphify-out/；对于旧版仓库，使用 graphify migrate-state。
3. 在不熟悉的语料库上执行耗时的构建前，先运行 graphify scope。
4. 优先使用 GRAPH_REPORT.md 和 graphify summary，而不是原始的 graph.json；使用 graphify query --budget <n> 限制遍历范围。
5. 将构建、查询、导出、刷新、审查、服务、安装和回退视为彼此独立的模式。
6. 将占位符 Community N 标签和缺失的描述视为输出降级，而非成功。
7. 使用 graphify hook install 或 graphify watch 持续保持内容新鲜，而不是临时重建。
8. 提交 .graphify 产物前，运行 graphify portable-check。
9. 将结构化回退视为一种诚实且一等的模式，而不是隐瞒的失败。
10. 将搜索优先的任务交给 codebase-search，将叙事记忆交给 llm-wiki，将项目记忆交给 opencontext。
11. 构建 graphify wiki 后，或执行任何 pip install --upgrade graphifyy 后，如果 [[…]] 链接看起来有问题，请运行 scripts/patch_wikilink.py。graphify 的生成器会输出原始标签 [[Community 36]] 链接，这些链接无法指向其 slug 化的 Community_36.md 页面； 此修补脚本会将所有链接统一规范为 [[slug|label]]，且可幂等执行。请将其接入安装／升级步骤 （jeo：在 graphify update . 之前的 post-implementation 钩子），确保修复在升级后仍然生效。

参考资料

• CLI 命令索引 — 按任务分类的所有命令和标志
• 安装矩阵 — 平台 ID、jeo/jeopi/gjc/opencode 路由
• 模式说明包和路由出口
• 构建与回退方案
• scripts/patch_wikilink.py — 幂等的维基链接规范化修补脚本（--self-test、--check）
• ../codebase-search/SKILL.md · ../llm-wiki/SKILL.md · ../opencontext/SKILL.md
• Graphify 上游项目：https://github.com/Graphify-Labs/graphify
• Graphify PyPI：https://pypi.org/project/graphifyy/