ZCodePrism
A. 之字形 库、CLI和MCP服务器,它们接收本地代码库,构建语义代码图,通过LSP丰富它,并将其公开给LLM和人类进行探索。
图书馆是核心。CLI和MCP服务器是瘦用户。MCP服务器是只读的,只在图上显示读取查询。所有突变(索引、快照、差异)都通过CLI。
入门指南
构建```sh
zig build
### 测试```sh
zig build test
通过以下方式生成测试覆盖率 kcov:```sh
zig build test -Dcoverage=true
结果已写入 `kcov-output/`.
## 命令行界面
这 `zcodeprism` 二进制是索引和检查代码库的主要入口点。```
Usage: zcodeprism [options]
命令
zcodeprism init 创建一个 .zcodeprism.zon 配置文件和a
.zcodeprism/ 当前工作目录中的数据目录。使用 --force
以覆盖现有配置。通过 --workspace 创建a
zcodeprism-workspace.zon 模板代替。```sh
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` 以获得完整的重新索引。```sh
zcodeprism index --full
zcodeprism export 以选定的格式呈现持久化图形,以及
将其写入stdout(或具有 --output).```sh
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 ` |将输出限制为文件路径以给定前缀开头的节点|
| `--output ` |写入文件而不是stdout|
| `--test-nodes` |包括测试节点(默认情况下不包括)|
| `--external-nodes` |包括外部/幻影节点(默认情况下排除)|
**`zcodeprism snapshot`** 将当前图形的命名快照另存为
二进制文件 `.zcodeprism/snapshots/.bin`标签必须
字母数字、连字符或下划线(最多64个字符)。```sh
zcodeprism snapshot --name v1
要以任何格式导出快照,请使用 export --snapshot:```sh
zcodeprism export --ctg --snapshot v1
**`zcodeprism diff`** 计算两个命名快照之间的语义差异。
它检测添加、删除、修改(更改的结构哈希)和重命名
(相同的结构哈希,不同的名称)实体。```sh
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` 为组装的统一图提供服务
来自多个项目。```sh
zcodeprism serve
# serve a workspace (multiple projects as one graph)
zcodeprism serve --workspace zcodeprism-workspace.zon
zcodeprism status 加载持久化图并打印统计信息:node
按种类计数、边缘计数和a source_hash 从文件中提取指纹
内容哈希。通过 --workspace 用于工作空间级别的统计数据。```sh
zcodeprism status
workspace stats
zcodeprism status --workspace zcodeprism-workspace.zon
### 全局选项
|选项|描述|
|--------|-------------|
| `--version` |打印版本并退出|
| `--help` |显示使用帮助|
| `--project-root ` |设置项目根目录|
| `--name ` |快照标记名称(带 `snapshot`) |
| `--snapshot ` |加载快照而不是当前图形(使用 `export`) |
| `--workspace ` |工作区配置文件(含 `init`, `serve`, `status`) |
| `-v`, `-vv`, `-vvv` |增加日志的详细程度(信息、调试、跟踪)|
### 配置
跑步 `zcodeprism init` 生成a `.zcodeprism.zon` 明智的文件
默认值。所有字段都是可选的。```zig
.{
.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 并单独索引。zig
.{
.name = "my-workspace",
.projects = .{
.{ .name = "frontend", .path = "frontend/" },
.{ .name = "backend", .path = "backend/" },
},
}
项目名称必须唯一,最多64个字符,并且不得包含 :.
这 .path 字段与工作区文件目录有关。使用 "." 到
引用同一目录。
调试工具
| 命令 | 描述 |
|---|---|
zig build analyze-graph -- |
在索引目录上运行分析算法 |
zig build dump-ast -- |
将原始树形图AST转储为源文件 |
zig build parse-directory -- |
索引所有支持的源文件并转储完整的代码图 |
zig build parse-file -- |
解析源文件并转储语义图 |
zig build query-graph -- |
在索引目录上运行查询引擎 |
zig build render-graph -- |
以CTG或Mermaid格式渲染代码图 |
