Perspica – 语义化代码审查工具 Vibe 项目

项目简介

Perspica 是一款面向 AI 编程时代的语义化代码审查工具，专注于帮助开发者理解代码变更的实际意图，而非逐行对比差异。传统 diff 只展示文本层面的增减，Perspica 则通过 tree-sitter 解析代码结构，自动识别重命名、函数签名变更、代码迁移等真实逻辑修改，过滤掉格式调整、注释变更等机械噪音，让审查者把精力集中在真正需要关注的地方。项目由独立开发者 sshah03 构建，代码以 MIT 许可证开源。

核心功能

1. 语义级变更识别

Perspica 不仅仅做文本 diff，而是解析代码的抽象语法树（AST），理解变量重命名、函数签名变化、方法迁移等真实代码结构变更。即使用户只改了变量名，相关调用点也会被关联展示，避免遗漏。

2. 机械噪音自动过滤

格式化变更、纯注释修改、仅因重命名产生的“伪变更”行，都会被自动标记折叠，真实变更一目了然。测试文件和文档单独成组，与业务逻辑变更清晰区隔。

3. 依赖与调用链分析

自动追踪变更函数的所有调用点，检查是否存在遗漏更新；找出变更后引用了已不存在名称的代码；标注被变更“落下”的废弃代码片段，确保每次变更的完整性和安全性。

4. LLM 意图分析与风险评级（可选）

在启用 LLM 分析后，Perspica 将变更按意图分组，并为每组标注风险等级，还能生成自然语言摘要。如果本地已配置 Claude Code、OpenAI API Key 或 Ollama 模型，LLM 分析完全在本地运行，数据不出机器。

5. AI 编程会话溯源

当代码变更是由 Claude Code 或 Codex 生成时，Perspica 能够读取用户的原始提示词，并标注哪些变更是“用户要求做的”、哪些是“AI 自主决定添加的”。这个功能帮助团队在审查 AI 辅助代码时，快速区分人工意图和 AI 行为，降低 AI 幻觉代码的审查漏网风险。

6. 多语言支持

内置对 TypeScript/JavaScript（含 TSX/JSX）、Python、Rust、Go、Java 和 C 的深度语义分析。其他语言文件以标准行 diff 展示，带语法高亮。

7. 多种使用方式

支持终端直接输出、Web 浏览器可视化查看，以及 GitHub PR 编号拉取审查（需安装 gh CLI）。支持分支对比、Staged 变更、提交区间等多种 diff 范围指定方式。

8. 阅读顺序导航

Perspica 会分析变更的调用路径，按“从入口到深处”的顺序排列变更组，并标注每个变更被哪些测试用例覆盖，帮助审查者按最优路径阅读代码，而不是被文件顺序牵着走。

技术实现

Perspica 的核心由 perspica-core 和 perspica-cli 两个 Rust crate 组成。

perspica-core 是纯计算库，不涉及任何 I/O 操作：接收源代码字符串，输出结构化分析结果。它的工作流程分为四个阶段——

解析阶段：使用 tree-sitter 对新旧两版代码分别解析，构建完整抽象语法树。

指纹阶段：对每个语法节点计算格式化无关的指纹（忽略空格、注释等不影响语义的差异），实现跨版本的节点精确匹配。

分类阶段：对比新旧两侧的指纹集合，识别七类变更：重命名、签名变更、新增参数、函数提取、代码迁移、逻辑变更、废弃代码。

跨文件阶段：在多文件之间追踪变量重命名传播（同一类型内的公共命名如 Flush 会做调用者限定以避免误报），查找受影响但未被更新的调用点，并构建调用图谱以确定阅读顺序。

perspica-cli 则负责与外部系统交互：调用 git diff 获取变更内容，通过 gh CLI 拉取 GitHub PR 信息，在终端或嵌入式 Web 查看器中渲染结果，以及驱动可选的 LLM 分析流程。LLM 分析的输出会与 perspica-core 自身分析结果交叉验证：未知的变更条目直接丢弃，“用户要求”类引用会逐词对照实际提示词文本。

隐私设计方面，所有数据处理均在本地执行；只有在用户明确启用 LLM 分析（perspica -s）时才会向外发送数据（便会如此也只发送变更列表和代码片段，不发送完整文件）；LLM 使用的模型优先顺序为：环境变量 API Key → Claude Code 认证 → Ollama 本地模型。

快速上手

安装方式

方式一：Rust 生态（一行命令）

cargo install perspica

方式二：下载预编译二进制 访问 GitHub Releases 页面（https://github.com/sshah03/perspica/releases），下载 macOS、Linux 或 Windows 对应版本，无需安装任何运行时。

方式三：源码构建

git clone https://github.com/sshah03/perspica && cd perspica
cargo build --release          # → target/release/perspica

基本使用

在任意 Git 仓库根目录执行：

perspica                 # 审查当前分支所有未 commit 的变更
perspica --web           # 在浏览器中以可视化界面审查
perspica --pr 123 --web  # 拉取 GitHub PR #123 并在浏览器中打开

指定变更范围

perspica --staged                        # 仅审查 staged 变更
perspica --branch develop                # 对比当前分支与 develop 的差异
perspica --git main...feature            # 指定任意两个 commit/tag 之间的变更
perspica old.ts new.ts                   # 直接对比两个文件
perspica --json                          # 输出 JSON 格式，供其他工具集成

启用 LLM 分析

perspica -s                              # 在终端中输出 LLM 分析结果
perspica --web -s                         # 在 Web 界面中展示，按意图分组变更
perspica --deep -s                        # 深度分析：LLM 可额外读取变更文件中的小文件
perspica --model claude-sonnet-5-5        # 指定使用某个模型

Web 查看器快捷键：j/k 上/下切换变更 · n/p 上/下切换文件 · f/i/r 按文件/意图/阅读顺序排序 · m 显示/隐藏机械变更 · u/s 统一/分栏视图。

适用人群

开发团队：当团队引入 AI 编程工具（Claude Code、Copilot、Codex）后，代码审查者面临大量“不知道要求了什么”的变更，Perspica 的会话溯源功能让 AI 辅助代码的审查有据可查。

代码审查者：需要处理大量 PR 的工程师，尤其是涉及复杂重构或跨文件变更的场景，Perspica 自动过滤噪音、按意图分组，让审查效率大幅提升。

AI 编程工具用户：使用 Claude Code 或 Codex 的开发者，可以用 Perspica 验证 AI 生成的变更是否符合预期，哪些是 AI 自主添加的，帮助保持对代码的掌控感。

开源项目维护者：通过阅读顺序导航和调用链分析，维护者可以快速判断一个外部贡献是否真正理解了项目的内部结构，还是只做了表面修改。

官方链接

• GitHub 仓库：https://github.com/sshah03/perspica
• crates.io 包：https://crates.io/crates/perspica
• 最新版本下载：https://github.com/sshah03/perspica/releases/latest