AI导哈

代码语义图构建工具

ZCodePrism是一个Zig库、CLI和MCP服务器，用于构建和探索代码语义图，支持LLM和人类开发者使用。

  • by jaudiger
  • Zig
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jaudiger/zcodeprism

使用说明

ZCodePrism

A. 之字形 库、CLI和MCP服务器，它们接收本地代码库，构建语义代码图，通过LSP丰富它，并将其公开给LLM和人类进行探索。

图书馆是核心。CLI和MCP服务器是瘦用户。MCP服务器是只读的，只在图上显示读取查询。所有突变（索引、快照、差异）都通过CLI。

入门指南

构建

zig build

测试

zig build test

通过以下方式生成测试覆盖率 kcov:

zig build test -Dcoverage=true

结果已写入 kcov-output/.

命令行界面

这 zcodeprism 二进制是索引和检查代码库的主要入口点。

Usage: zcodeprism <command> [options]

命令

zcodeprism init 创建一个 .zcodeprism.zon 配置文件和a .zcodeprism/ 当前工作目录中的数据目录。使用 --force 以覆盖现有配置。通过 --workspace 创建a zcodeprism-workspace.zon 模板代替。

cd my-project
zcodeprism init

# or for a workspace
zcodeprism init --workspace

zcodeprism index 解析所有支持的源文件(.zig, .rs)under 当前目录，构建语义代码图，并将其保存到 .zcodeprism/graph.bin （以及可选 .zcodeprism/graph.jsonl 取决于 这 storage.format 设置）。通过 --full 以获得完整的重新索引。

zcodeprism index --full

zcodeprism export 以选定的格式呈现持久化图形，以及 将其写入stdout（或具有 --output).

# Compact Text Graph to stdout
zcodeprism export --ctg

# Mermaid flowchart restricted to the parser subtree
zcodeprism export --mermaid --scope src/parser/ --output parser.mmd

# JSONL (one JSON object per line, diffable with git)
zcodeprism export --jsonl --output graph.jsonl
标志 描述
--ctg 紧凑文本图形格式
--mermaid 美人鱼流程图格式
--jsonl 每个节点/边一行JSON
--scope <path> 将输出限制为文件路径以给定前缀开头的节点
--output <path> 写入文件而不是stdout
--test-nodes 包括测试节点（默认情况下不包括）
--external-nodes 包括外部/幻影节点（默认情况下排除）

zcodeprism snapshot 将当前图形的命名快照另存为 二进制文件 .zcodeprism/snapshots/<tag>.bin标签必须 字母数字、连字符或下划线（最多64个字符）。

zcodeprism snapshot --name v1

要以任何格式导出快照，请使用 export --snapshot:

zcodeprism export --ctg --snapshot v1

zcodeprism diff 计算两个命名快照之间的语义差异。 它检测添加、删除、修改（更改的结构哈希）和重命名 （相同的结构哈希，不同的名称）实体。

zcodeprism diff v1 v2

输出示例：

summary: +1 added, -1 removed, ~1 modified, >0 renamed
  + function newFunc (main.zig:16)
  - function oldFunc (main.zig:10)
  ~ function parse (parser.zig:5)

zcodeprism serve 启动MCP服务器（只读，JSON-RPC 2.0以上 stdio）。服务器公开了跨平台的工具 graph.*, explorer.*，以及 analysis.* 命名空间。通过 --workspace 为组装的统一图提供服务 来自多个项目。

zcodeprism serve

# serve a workspace (multiple projects as one graph)
zcodeprism serve --workspace zcodeprism-workspace.zon

zcodeprism status 加载持久化图并打印统计信息：node 按种类计数、边缘计数和a source_hash 从文件中提取指纹 内容哈希。通过 --workspace 用于工作空间级别的统计数据。

zcodeprism status

# workspace stats
zcodeprism status --workspace zcodeprism-workspace.zon

全局选项

选项 描述
--version 打印版本并退出
--help 显示使用帮助
--project-root <path> 设置项目根目录
--name <tag> 快照标记名称（带 snapshot)
--snapshot <tag> 加载快照而不是当前图形（使用 export)
--workspace <path> 工作区配置文件（含 init, serve, status)
-v, -vv, -vvv 增加日志的详细程度（信息、调试、跟踪）

配置

跑步 zcodeprism init 生成a .zcodeprism.zon 明智的文件 默认值。所有字段都是可选的。

.{
    .exclude_paths = .{ "zig-cache", "zig-out", ".git", "target" },
    .storage = .{
        .path = ".zcodeprism/",
        .format = .binary,   // .binary or .jsonl
    },
    .memory = .{
        .budget_mb = 512,
    },
}

工作区配置

工作区将多个独立索引的项目组合成一个 统一图。跑步 zcodeprism init --workspace 生成a zcodeprism-workspace.zon 文件。每个引用的项目都必须有自己的 .zcodeprism.zon 并单独索引。

.{
    .name = "my-workspace",
    .projects = .{
        .{ .name = "frontend", .path = "frontend/" },
        .{ .name = "backend", .path = "backend/" },
    },
}

项目名称必须唯一，最多64个字符，并且不得包含 :. 这 .path 字段与工作区文件目录有关。使用 "." 到 引用同一目录。

调试工具

命令 描述
zig build analyze-graph -- <dir> <cmd> 在索引目录上运行分析算法
zig build dump-ast -- <file> 将原始树形图AST转储为源文件
zig build parse-directory -- <dir> 索引所有支持的源文件并转储完整的代码图
zig build parse-file -- <file> 解析源文件并转储语义图
zig build query-graph -- <dir> <cmd> 在索引目录上运行查询引擎
zig build render-graph -- <path> 以CTG或Mermaid格式渲染代码图

相关 MCP