graph-it-live

Graph-It-Live

面向 AI 的代码库分析依赖智能 CLI。 可通过任何兼容 Agent 的 IDE 或 CLI 分析依赖、调用图、符号、影响和架构。

适用场景

• 分析文件依赖和导入
• 跨文件追踪函数执行
• 查找符号（函数、类、方法）的所有调用方
• 在重构前检测破坏性更改
• 查找未使用的导出项／死代码
• 为任意文件生成代码地图（结构概览）
• 分析文件内的调用层级和逻辑流程
• 从入口点遍历完整依赖树
• 查找导入给定文件的所有文件（反向查找）
• 检测循环依赖／环
• 检查更改函数签名的影响
• 获取工作区架构概览
• 审查 Git diff，检查破坏性签名、更改影响、循环依赖和测试候选项

快速开始 — 安装

需要 Node.js v22+。

# Install globally
npm install -g @magic5644/graph-it-live

# Or run without installing
npx @magic5644/graph-it-live <command>

全局安装后，graph-it 可在 PATH 中使用。验证：

graph-it --version

不要自动安装 CLI。仅根据下方的确认政策进行更新。如果 CLI 不可用，请提供文档中列出的安装选项，并等待明确请求。

CLI 和功能发现

在会话中首次激活任何 Graph-It 技能时，如果 CLI 和终端可用，请检查 graph-it --version。 如果可执行文件和终端可用，优先使用 CLI；仅当 CLI 不可用或不适用，且已连接的主机提供了 等效工具和架构时，才将 MCP 作为后备方案。仅使用 CLI 已有的新版本提示（如果有）；不要 查询 npm，也不要添加单独的更新检查。在同一会话中，各 Graph-It 技能应共享版本、工具清单 和更新决策，确保发现和任何提示最多只发生一次。使用 graph-it tool --list 发现工具； 仅在需要时查阅 graph-it --help 或命令帮助。除非 CLI／版本、MCP 服务或工作区上下文发生 变化，或请求的工具未知，否则重复使用该清单。以下示例仅供说明，不代表固定的功能清单。

如果 CLI 报告有新版本，在交互式使用中运行 graph-it update 前，必须先征得明确的肯定确认。沉默、超时、拒绝、非 TTY 执行和通用 Agent 模式均不代表同意。明确启用自动模式并预先授权时，默认将更新决策设为同意，并在不再 提示的情况下运行 graph-it update。成功后，重新检查 graph-it --version 和 graph-it tool --list； 使缓存的功能失效。如果 MCP 服务已经在运行，请告知用户，其主机必须授权重启，更新后的 CLI 才能 生效。失败时，仅当现有 CLI 仍可用，才继续使用；否则说明失败并停止 CLI 分析。简要警告，不要 升级处理，也不要循环重试。

这些说明要求 Graph-It-Live CLI 1.21.0 或更高版本（check-architecture、architecture --level units、--matrix 和 24 个 MCP 工具）。在同一次首次激活时，将报告的 graph-it --version 与 1.21.0 比较。如果版本较旧，只说明一次，列出缺少的命令，并根据上述确认 政策提供 graph-it update 选项；在更新之前，只使用该 CLI 的 --help 和 tool --list 中 列出的命令，绝不要将缺失命令的输出作为结果。如果无法读取版本，则视为版本较旧。

graph-it tool <name> 通过 CLI 直接调用分析工具；它不会通过 MCP 路由每个 CLI 命令。 graph-it serve 会启动 MCP 服务。使用 MCP 作为后备方案时，仅使用已连接主机当前工具架构中 公布的工具、命名空间和参数。CLI 的 --format 与 MCP 的 response_format 是不同的接口； 仅当 MCP 架构支持时才使用后者。

支持的语言

TypeScript、JavaScript、Python、Rust、C#、Go、Java、Vue、Svelte、GraphQL。

CLI 命令参考

首次全面代码库梳理（Agent 引导）

在开展广泛任务（功能开发、审计、重构、入门熟悉）时，请在开始时使用此工作流：

# 1) Build/refresh the index
graph-it scan

# 2) Generate the agent-optimized global map
graph-it architecture --format toon

此 TOON 结果是 Agent 的主要上下文：nodes、edges、failedFiles、nodeCount、edgeCount。

完成后，再运行针对性分析：

# Illustrative tool names; verify the installed inventory and parameters first
graph-it tool generate_codemap --filePath=/abs/path/to/file.ts
graph-it tool query_call_graph --filePath=/abs/path/to/file.ts --symbolName=mySymbol --depth=3
graph-it explain /abs/path/to/file.ts

对于开放式架构问题，请使用自然语言查询：

graph-it query "how does authentication flow through this project"

如果全局图太大：

graph-it architecture --maxFiles 300 --format toon

供人类使用的可视化选项（不用于大模型上下文）：

graph-it architecture --format mermaid            # flat file graph
graph-it architecture --groups --format mermaid   # one subgraph (or node) per folder group, edges labelled with file-pair counts

如需生成经过整理的图表，请运行 graph-it architecture --groups --format json，并将 groups、 groupEdges 和 context 以及准确的计数交给图表技能（architecture-diagram、archify）。 角色说明和规则属于人工注释；运行时流程来自 graph-it trace，是静态分析结果，而非实际执行观测。

如需逐步探索相同的分组，而不是阅读整张图，请调用 graph-it tool explore_architecture（摘要），然后调用 --group=<key>（文件和边界），再调用 --from=<key> --to=<key>（分组边背后的文件对，可通过 --limit/--offset 分页）。

其他架构层级（json/toon）：

graph-it architecture --level units --format toon              # packages (else top-level folders), layers, unit edges, cycles
graph-it architecture --folder "(root)/src" --format toon      # one level below a unit or folder key
graph-it architecture --level units --matrix --format toon     # dependency structure matrix (also --format csv)

当工作区在 graphit.architecture.json 中声明规则时，graph-it check-architecture 会针对每条静态导入检查这些规则。若存在未列于 graphit.architecture.baseline.json 中的 error 级违规，该命令会以状态码 1 退出；--update-baseline 则接受当前违规。

为工作区编制索引

请先运行 scan，再运行分析命令，以构建依赖索引。大多数分析命令都依赖此索引。 review-pr 命令是个例外：它会自动编制索引，因此除非需要为其他命令刷新索引，否则不要先单独运行 scan。

graph-it scan

文件发生重大变更后，请重新运行以刷新索引。

工作区根目录。 解析到工作区根目录之外的导入会被跳过。如果未指定 --workspace， CLI 会使用最近的、包含 package.json 或 tsconfig.json 的目录；graph-it -w <dir> 会严格使用给定路径，并在该目录下创建 .graph-it/（索引 + 缓存）。对于单体仓库中的影响分析、依赖者和跨包问题，请传入单体仓库根目录：使用 graph-it -w <monorepoRoot> ...， 而不是先 cd 进入某个包。如果 scan 警告导入解析到了工作区根目录之外， 则答案仅涵盖该根目录（get_index_status 会报告 outOfRootImports 和 monorepoRoot）： 请使用它指定的 --workspace 重新运行，或说明这一限制。

工作区概览

graph-it summary                   # Full workspace overview
graph-it summary src/api.ts        # Per-file codemap

每个文件的代码图会返回：导出项、内部结构、依赖项、依赖者、调用流程、循环依赖。

追踪执行流程

从某个函数开始，追踪完整调用链：

graph-it trace src/index.ts#main
graph-it trace src/auth.ts#validateToken

格式：<filePath>#<functionName>。可使用绝对路径或相对路径。

分析文件逻辑

显示文件内的调用层级——各函数之间的调用关系及调用顺序：

graph-it explain src/server.ts

返回入口点、调用树和内部循环依赖。

依赖关系图

从入口文件开始，遍历完整依赖树：

graph-it path src/index.ts

显示所有传递导入，并检测循环依赖。

查找未使用的导出项

检测死代码——没有被其他文件导入的导出符号：

graph-it check src/api.ts

如果已安装工具清单提供了等效工具，则可执行工作区范围内的死代码扫描：

graph-it tool scan_dead_code

根据调用图关系生成 Markdown 维基：

graph-it wiki

审查 Pull Request 或差异

使用专用命令进行确定性的本地差异分析。该命令需要 Git 基准引用，并会自动建立索引。不带 --head 时，会比较基准与当前工作树，包括已暂存和未暂存的内容。传入 --head <ref> 可比较两个已提交的本地或远程引用：

graph-it review-pr --base origin/main --format markdown
graph-it review-pr --base origin/main --head feature/my-change --depth 3 --max-files 200 --format toon

在给出合并建议前，先查看 risk、score、limitations 和 isPartial：

• low、medium、high、critical 表示更改符号中的最高风险等级。
• isPartial: true 表示文件、解析器或影响深度限制导致结果不完整。
• 没有破坏性签名变更 并不 能证明行为变更是安全的；请检查测试和受影响的流程。

如果已连接的 MCP 主机公布了结构等效的审查工具，请使用其准确名称和输入架构。不要假设 CLI 选项与 MCP 参数一一对应。VS Code Branch Watch 的置信度标签属于 UI 上下文，不属于 CLI 合约。

使用 pr-review 技能执行完整的审查工作流和 GitHub Actions 门禁。

输出格式

对于在 graph-it --help 或命令帮助中提供 --format 的 CLI 命令：

格式	最适用场景
text	在终端中快速阅读（默认）
json	程序化处理、脚本
toon	AI 使用——与 JSON 数据相同，但令牌数减少 30–60%
markdown	将结构化输出嵌入文档
mermaid	向人展示可视化图表——在 VS Code、GitHub、Obsidian 或任何 Markdown 预览器中渲染为流程图。仅 trace 和 path 支持。

选择合适的格式：

• 在 Agent 或脚本中处理输出 → --format toon
• 在聊天或预览窗格中向人展示调用图或依赖树 → --format mermaid
• 其他所有程序化用途 → --format json

graph-it summary src/api.ts --format toon          # AI reads it
graph-it trace src/index.ts#main --format mermaid  # human sees the diagram
graph-it path src/index.ts --format mermaid        # dependency tree as flowchart

# Analyze a single file's dependencies
graph-it tool analyze_dependencies --filePath=/abs/path/to/file.ts

# Find all files importing a specific file
graph-it tool find_referencing_files --targetPath=/abs/path/to/file.ts

# Illustrative: query call sites only if this tool and parameters are advertised
graph-it tool query_call_graph --filePath=/abs/path/to/file.ts --symbolName=myFunction --direction=callers --depth=1

# Full impact analysis
graph-it tool get_impact_analysis --filePath=/abs/path/to/file.ts --symbolName=myFunction

# Detect breaking changes (use --args JSON for large content payloads)
graph-it tool analyze_breaking_changes --args '{"filePath":"/abs/path/to/file.ts","symbolName":"myFunction","oldContent":"...old source...","newContent":"...new source..."}'

# Generate codemap
graph-it tool generate_codemap --filePath=/abs/path/to/file.ts

# Illustrative: verify the installed tool's supported parameters first
graph-it tool query_call_graph --filePath=/abs/path/server.ts --symbolName=handleRequest --depth=3

# Workspace-wide dead code scan (across all files, unlike find_unused_symbols which is per-file)
graph-it tool scan_dead_code

# Natural-language architecture question
graph-it query "what calls the MCP worker and how"

# Generate wiki docs from call graph
graph-it wiki --output docs/wiki

CLI 工具参数应遵循已安装工具的帮助信息／架构；参数要求绝对路径时，请使用绝对路径。CLI --format 仅控制 CLI 输出。

关键规则（绝不可违反）

• 绝不可 在运行 graph-it scan 前执行分析，review-pr 除外，因为它会自动建立索引。
• 绝不可 因为示例中出现某个工具名称或参数，就假设该名称或参数存在；请确认当前 CLI 清单／帮助信息或 MCP 架构。
• 绝不可 将 CLI 标志或输出设置传给 MCP，除非其公布的输入架构支持这些内容。

MCP 服务模式

以 MCP 服务模式启动，以便与 AI 客户端集成（无需 VS Code）：

graph-it serve

MCP 是否可用取决于已连接主机当前公布的工具及输入架构；它们可能与已安装的 CLI 清单不同。不要假设本文档中提到的工具名称、命名空间、参数或输出选项都可用。response_format 不是 CLI 的 --format 标志，仅当主机架构公布该选项时才应使用。

调用 MCP 工具

• 如果主机公布了 graph_context，可考虑将其用于开放式问题；只能使用其公布的架构和响应格式。否则，请从主机实际提供的工具中选择。
• MCP 输出选项和响应元数据因工具／架构而异。除非当前主机架构或响应中提供了 response_format 或元数据字段，否则不要假设它们存在。

MCP 客户端配置

VS Code / Cursor（.vscode/mcp.json 或 .cursor/mcp.json）：

{
  "servers": {
    "graph-it-live": {
      "type": "stdio",
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

Claude Desktop（~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "/path/to/project" }
    }
  }
}

Claude Code CLI：

claude mcp add graph-it -- graph-it serve

Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code 扩展（替代方案）

Graph-It-Live 也提供 VS Code 扩展，可为 Copilot Agent 模式提供原生 LM 工具（无需设置 MCP）。

从 Marketplace 安装：在扩展中搜索“Graph-It-Live”（Ctrl+Shift+X）。

在扩展中启用 MCP 服务：在 VS Code 设置中将 graph-it-live.enableMcpServer 设为 true。

常见工作流

“如果我修改这个函数，会有哪些东西出问题？”

graph-it scan
graph-it tool get_impact_analysis --filePath=/abs/path/src/auth/index.ts --symbolName=myFunction

“概述一下这个模块”

# Outgoing: what this file imports and calls
graph-it summary src/auth/index.ts --format toon

# Incoming: who depends on this file
graph-it tool find_referencing_files --targetPath=/abs/path/src/auth/index.ts

务必检查两个方向：了解模块调用了什么（出站），以及哪些模块会调用它（入站），才能全面了解它的作用和影响范围。

“找出项目中的无用代码”

# Outgoing: symbols this file exports that nobody imports
graph-it check src/utils.ts
graph-it tool find_unused_symbols --filePath=/abs/path/src/utils.ts

# Incoming: confirm the file itself is not orphaned (nothing imports it)
graph-it tool find_referencing_files --targetPath=/abs/path/src/utils.ts

两个方向都不可或缺：某个文件导出的符号可能看似在内部有使用，但实际上从项目的其余部分完全无法访问。

“追踪从 main() 开始的执行过程”

graph-it trace src/index.ts#main --format mermaid

“是否存在循环依赖？”

graph-it path src/index.ts

系统会自动检测并报告循环依赖。

“整个项目中哪些地方调用了这个函数？”

# If advertised by the installed CLI, query_call_graph can report call sites
graph-it tool query_call_graph --filePath=/abs/path/src/utils/formatDate.ts --symbolName=formatDate --direction=callers --depth=1

对于 MCP，先检查宿主是否公布了等效的调用图工具，并使用该工具的确切 架构。调用点不能替代对所有符号引用的检查。

“用自然语言回答架构问题”

graph-it query "how does the dependency index get rebuilt"

“生成用于新人入职的 Wiki”

graph-it wiki --output wiki

“合并前审查拉取请求”

graph-it review-pr --base origin/main --format markdown

对于每个高危／严重级别的符号，都应使用已公布的影响分析功能进行深入检查。将报告的任何限制视为需要人工审查的事项。

更新

仅在遵循上述确认策略的情况下运行 graph-it update；成功后，刷新版本和清单，并与宿主协调重启 MCP 服务。

相关技能

• dead-code-hunter — 在底层使用 Graph-It-Live，生成涵盖整个项目的无用代码删除计划并提供安全性评级。需要删除代码而不只是检查时使用。
• onboarding-express — 为新开发者提供结构化的 Graph-It-Live 代码库导览：入口点、业务逻辑、最复杂的模块和关键路径图。
• pr-review — 在本地或 GitHub Actions 中审查 Git 差异，然后将 Graph-It-Live 的证据转化为可直接用于合并决策的发现。
• skill-manager — 以交互方式管理已安装的技能（列出／卸载）。适用于整理或清理本地技能栈。