jaudiger/zcodeprism

# ZCodePrism 一个 [Zig](https://ziglang.org) 库、CLI 和 MCP 服务器，用于摄取本地代码库，构建语义代码图，通过 LSP 对其进行丰富，并将其暴露给 LLM 和人类进行探索。 该库是核心。CLI 和 MCP 服务器是轻量级消费者。MCP 服务器是只读的，仅暴露对图的读取查询。所有变更（索引、快照、diff）都通过 CLI 进行。 ## 开始使用 ### 构建 ``` zig build ``` ### 测试 ``` zig build test ``` 使用 [kcov](https://github.com/SimonKagworths/kcov) 生成测试覆盖率： ``` zig build test -Dcoverage=true ``` 结果写入 `kcov-output/`。 ## CLI `zcodeprism` 二进制文件是索引和检查代码库的主要入口点。 ``` Usage: zcodeprism [options] ``` ### 命令 **`zcodeprism init`** 在当前工作目录中创建 `.zcodeprism.zon` 配置文件和 `.zcodeprism/` 数据目录。使用 `--force` 覆盖现有配置。传递 `--workspace` 以创建 `zcodeprism-workspace.zon` 模板。 ``` cd my-project zcodeprism init # 或用于 workspace zcodeprism init --workspace ``` **`zcodeprism index`** 解析当前目录下所有受支持的源文件（`.zig`、`.rs`）， 构建语义代码图，并将其保存到 `.zcodeprism/graph.bin`（根据 `storage.format` 设置，可选择保存为 `.zcodeprism/graph.jsonl`）。 传递 `--full` 以进行完整的重新索引。 ``` zcodeprism index --full ``` **`zcodeprism export`** 以选定格式渲染持久化的图，并将其 写入标准输出（或使用 `--output` 写入文件）。 ``` # Compact Text Graph 输出到 stdout zcodeprism export --ctg # Mermaid flowchart 限制在 parser subtree 内 zcodeprism export --mermaid --scope src/parser/ --output parser.mmd # JSONL (每行一个 JSON object，可使用 git 进行 diff) zcodeprism export --jsonl --output graph.jsonl ``` | 标志 | 描述 | |------|-------------| | `--ctg` | 紧凑文本图 格式 | | `--mermaid` | Mermaid 流程图格式 | | `--jsonl` | 每个节点/边对应一行 JSON | | `--scope ` | 将输出限制为文件路径以给定前缀开头的节点 | | `--output ` | 写入文件而不是标准输出 | | `--test-nodes` | 包含测试节点（默认排除） | | `--external-nodes` | 包含外部/幻象节点（默认排除） | **`zcodeprism snapshot`** 将当前图的命名快照保存为 `.zcodeprism/snapshots/.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 服务器（只读，基于 stdio 的 JSON-RPC 2.0）。该服务器暴露了跨 `graph.*`、`explorer.*` 和 `analysis.*` 命名空间的工具。传递 `--workspace` 以提供从多个项目组装的统一图。 ``` zcodeprism serve # serve 一个 workspace (将多个 project 作为单个 graph) zcodeprism serve --workspace zcodeprism-workspace.zon ``` **`zcodeprism status`** 加载持久化的图并打印统计信息：按类型划分的节点 计数、边计数以及从文件内容哈希派生的 `source_hash` 指纹。传递 `--workspace` 获取工作区级别的统计信息。 ``` zcodeprism status # workspace 统计信息 zcodeprism status --workspace zcodeprism-workspace.zon ``` ### 全局选项 | 选项 | 描述 | |--------|-------------| | `--version` | 打印版本并退出 | | `--help` | 显示使用帮助 | | `--project-root ` | 设置项目根目录 | | `--name ` | 快照标签名称（与 `snapshot` 一起使用） | | `--snapshot ` | 加载快照而不是当前图（与 `export` 一起使用） | | `--workspace ` | 工作区配置文件（与 `init`、`serve`、`status` 一起使用） | | `-v`, `-vv`, `-vvv` | 增加日志详细程度（info, debug, trace） | ### 配置 运行 `zcodeprism init` 会生成一个具有合理 默认值的 `.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` 会生成一个 `zcodeprism-workspace.zon` 文件。每个被引用的项目必须有其自己的 `.zcodeprism.zon` 并单独进行索引。 ``` .{ .name = "my-workspace", .projects = .{ .{ .name = "frontend", .path = "frontend/" }, .{ .name = "backend", .path = "backend/" }, }, } ``` 项目名称必须唯一，最多 64 个字符，且不得包含 `:`。 `.path` 字段相对于工作区文件目录。使用 `"."` 引用 相同的目录。 ### 调试工具 | 命令 | 描述 | |---------|-------------| | `zig build analyze-graph -- ` | 在已索引的目录上运行分析算法 | | `zig build dump-ast -- ` | 转储源文件的原始 tree-sitter AST | | `zig build parse-directory -- ` | 索引所有受支持的源文件并转储完整的代码图 | | `zig build parse-file -- ` | 解析源文件并转储语义图 | | `zig build query-graph -- ` | 在已索引的目录上执行查询引擎 | | `zig build render-graph -- ` | 以 CTG 或 Mermaid 格式渲染代码图 |

标签：DLL 劫持, LLM集成, LSP, MCP服务器, Mermaid, Rust, SOC Prime, ZCodePrism, Zig, Zig语言, 云安全监控, 人工智能辅助编程, 代码可视化, 代码图谱, 代码审查, 代码搜索, 代码索引, 代码解析, 大语言模型, 开发工具, 源码解析, 网络流量审计, 静态分析