Project Code Intelligence

面向编码智能体的仓库情报与变更安全证据。

Project Code Intelligence (PCI) 为 Git 仓库建立索引，并为编码智能体提供结构化证据，以支持研究、重构、维护和安全工作。智能体可以在编辑代码之前，按概念或标识符搜索、检查候选关系、评估变更的爆炸半径、发现重复的实现形态，并查询静态分析结果。

PCI 不是自主审查器，其图谱也不是编译器级别的调用图。它缩小发现范围并提供证据；智能体仍需在源码中验证重要结论。

它能帮助什么

研究与定位

• 搜索精确的标识符、文件名、配置键和已知字符串。

• 当相关名称未知时，按行为进行搜索。

• 检查仓库语言、文件角色、快照、解析器覆盖率和索引新鲜度。

• 获取包含路径、行范围、元数据和源码片段的受限记录。

• 通过命名集合和仓库过滤器在多个仓库之间开展工作。

更安全的变更

• 查找候选调用方、被调用方、引用、测试和模块级接线。

• 在移除、重命名或更改符号之前，检查爆炸半径证据。

• 呈现入口点、孤儿代码和测试覆盖率信号。

• 当定义被添加或移除时，向受支持的编码智能体注入附近的证据。

维护与冗余

• 查找重复同一调用形态模式的函数组。

• 按相似度、估算的抽象成本和可能的净价值对冗余候选进行排序。

• 运行仓库审计，以发现过期索引、重复名称、冗余候选和静态发现。

安全与静态分析

• 将 SARIF 报告与源码记录一起摄取。

• 按工具、规则、级别、基线状态或路径搜索规范化后的发现。

• 获取诊断信息、代码流和运行元数据，而无需让智能体解析原始 SARIF 工件。

Related MCP server: Graft

工作原理

pci index 将仓库文件解析为受限记录，提取元数据和候选关系，并将快照存储在 Postgres/pgvector 中。语义嵌入是可选的：使用 --no-embed 时，词法搜索和大多数结构证据仍然可用。

pci mcp 通过本地 stdio MCP 服务器暴露索引。编码智能体使用其面向过滤的工具来发现可能相关的代码，然后在行动之前阅读并验证实时源码。

默认的本地架构是：

• Postgres/pgvector： Docker 或 Podman Compose。

• Linux 嵌入服务： 由用户 systemd 管理的 Podman Quadlet 单元。

• Apple Silicon 嵌入： 原生 MLX 服务。

• 智能体集成： 一个 stdio MCP 服务器，带有可选的编辑证据钩子。

当这种取舍是刻意选择的结果时，支持远程 Postgres 和 OpenAI 兼容的嵌入端点。

快速开始

从检出目录安装 CLI：

uv tool install /path/to/project-code-intelligence
export PATH="$HOME/.local/bin:$PATH"

启动捆绑的数据库和最佳可用的本地嵌入后端：

pci doctor --start
pci doctor

为一个 Git 仓库建立索引：

cd /path/to/repo
pci index .

为你的编码智能体安装 MCP 配置：

pci mcp install --target codex

支持的目标包括 claude、codex、opencode、pi、vscode、copilot、cline 和 zed。有关客户端特定的设置、项目范围界定和凭据处理，请参阅 docs/MCP_SETUP.md。

如需不带嵌入的词法搜索：

pci doctor --start-db
pci index --no-embed .

核心智能体工具

运行 pci audit 获取整棵树的证据报告。

证据，而非裁决

PCI 刻意将较强的索引事实与近似的和启发式的证据区分开来。

• 候选关系边不是经过类型检查的调用图事实。

• 爆炸半径无法证明变更是否安全。

• 冗余分数无法决定两个函数是否应该共享抽象。

• 静态发现保留其原始分析器的局限。

• 在未提交或新近提交的变更之后，索引可能会过期。

• 语义检索可能遗漏相关代码，或返回看似合理的邻居。

在实时源码中验证重要的调用方和发现。对于已知路径和小型受限问题，使用直接的文件读取；当位置、名称或影响尚不可知时，PCI 最为有用。

安装

Python CLI

使用 uv 为当前用户安装：

uv tool install /path/to/project-code-intelligence

如需可编辑的开发安装：

cd /path/to/project-code-intelligence
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Nix

在 NixOS 或另一个启用了 flakes 的 Linux 主机上：

nix build
nix run . -- doctor --skip-db --embedding skip
nix develop

持久安装到用户 profile 中：

nix profile install .#project-code-intelligence

Nix 闭包包含 CLI、MCP 服务器、Python 依赖项以及捆绑的 Compose 和 Quadlet 资产。重量级的 Linux 嵌入运行时仍保留在 Podman 容器中，而不会成为主机原生的 Nix 依赖项。

本地数据库

仅启动捆绑的 Postgres/pgvector 数据库：

pci doctor --start-db

安装的 Compose 文件会被实例化到用户缓存中。如需改用自定义副本：

export PCI_COMPOSE_FILE=/path/to/docker-compose.yml
pci doctor --start-db

本地嵌入服务

CLI 包含服务模板；没有单独的 PCI 嵌入包。在 Linux 上，安装 Podman 并确保 systemctl --user 可用，然后运行：

pci doctor
pci doctor --start-embedding

PCI 检测可用硬件，仅在 ~/.config/containers/systemd/ 下实例化所选后端，重新加载用户 systemd，并将其启动。其他嵌入后端的过期 PCI 单元会被停止并移除。镜像和默认模型会在首次使用时下载。

如果需要，可显式选择后端：

# AMD GPU
pci doctor --start-embedding --embedding-backend rocm

# NVIDIA GPU
pci doctor --start-embedding --embedding-backend cuda

# Portable CPU fallback
pci doctor --start-embedding --embedding-backend fastembed

# AMD Ryzen AI NPU (experimental)
pci doctor --start-embedding --embedding-backend lemonade

可用的选择器有 auto、fastembed、lemonade、rocm、cuda 和 apple。当请求的后端所需的硬件或运行时不可用时，PCI 会拒绝该后端。apple 原生运行，而非通过 Quadlet。

要同时启动数据库和一个显式后端：

pci doctor --start --embedding-backend rocm

容器化后端默认在 http://127.0.0.1:18081/v1/embeddings 上发布一个 OpenAI 兼容的端点。由于它们共享此端点，请一次只运行一个本地后端。

停止嵌入服务而不触碰数据库：

pci doctor --stop-embedding

移除生成的本地服务、缓存和捆绑的数据库卷：

pci doctor --clean

--clean 具有破坏性，并会在移除数据前提示确认。

远程嵌入

仅启动数据库，然后配置一个受信任的 OpenAI 兼容提供商：

pci doctor --start-db
export PCI_ALLOW_REMOTE_EMBEDDING=1
export PCI_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
export PCI_EMBEDDING_ENDPOINT_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
pci doctor

远程端点会接收源自源码的文本。仅当这对被索引的仓库来说可以接受时，才启用它们。

为仓库建立索引

为一个仓库建立索引：

pci index /path/to/repo

将多个仓库作为一个工作区建立索引：

cd /path/to/workspace
pci index service-api web-ui shared-lib

PCI 从路径中推断集合和仓库名称。MCP 客户端按这些逻辑名称（而非绝对文件系统路径）进行过滤。索引是增量的：当存在兼容的快照时，未更改的文件会被复用。

在索引仓库路径下发现的 SARIF 报告会被自动摄取。使用以下命令重置并重建一个仓库：

pci index --reset /path/to/repo

使用 pci status 检查索引运行情况，使用 pci index --help 查看解析器、嵌入、集合和数据库选项。

MCP 与智能体钩子

创建项目范围的只读数据库凭据，并打印 MCP 配置：

pci index --init-db --mcp-config codex .

在不重新索引的情况下安装或移除 MCP 配置：

pci mcp install --target codex
pci mcp install --target codex --uninstall

生成的客户端配置不包含数据库密码。凭据以模式 0600 存储在用户的 PCI 配置目录下。Pi 使用项目本地的 .pi/extensions/ MCP 桥接。Cline 需要 --config-path，因为其设置文件是用户范围的。

可选的钩子可以提醒智能体使用索引，并在添加或移除定义的编辑附近注入证据：

pci hook install --target codex

钩子支持和安装细节因客户端而异。钩子是一种辅助手段，而非强制执行或正确性机制。请参阅 docs/MCP_SETUP.md 和 docs/SYSTEM_PROMPT.md。

隐私与安全

本地默认配置将源自源码的记录和嵌入保留在机器上。但这并不意味着每个工件都可以安全发布。

不要提交或分发数据库转储、恢复工件、SARIF 输出、嵌入缓存、模型文件、向量索引、来自私有仓库的生成数据或本地 MCP 凭据文件。它们可能包含派生自源码的源码片段、路径、符号、发现、元数据和嵌入。

集合用于组织仓库，但并非安全边界。当仓库需要更强的隔离时，请使用单独的数据库或数据库用户。项目范围的 MCP 凭据限制了常规访问，但不能替代主机和数据库安全。

何时 PCI 是合适的选择

PCI 在以下情况下往往会有帮助：

• 仓库或工作区很大或不熟悉；

• 任务开始时标识符未知；

• 生成的文件使广泛读取成本高昂或噪声很大；

• 重构需要调用方、测试和接线证据；

• 维护工作需要重复模式发现；

• 静态发现需要与源码相关联；

• 必须通过一个界面搜索多个仓库。

对于一个小型且熟悉的仓库、已知的文件和行范围，或一个通过一次受限的 rg 或文件读取就能回答的问题，它可能价值不大。目标不是取代标准开发者工具，而是改进围绕它们的不确定发现和变更规划步骤。

降低 token 和成本消耗可以是一个有用的附带效果，但 PCI 并不对此作出承诺。使用 docs/EVALUATING_VALUE.md 和 会话回顾提示词 来衡量索引是否改善了真实会话。

开发

MCP 服务器使用 stdio；Docker Compose 用于本地数据库，而非用于托管 MCP 进程。使用以下命令运行完整的开发门禁：

nix develop
make check

对于涉及摄取、数据库或 MCP 行为的变更，还请运行：

docker compose up -d pgvector
make integration-smoke

有关项目约定和发布保障措施，请参阅 CONTRIBUTING.md 和 AGENTS.md。

文档

• docs/MCP_SETUP.md — MCP 客户端、作用域、凭据和安全模型

• docs/PUBLIC_API.md — CLI、环境、MCP 和 Python 兼容性接口

• docs/EVALUATING_VALUE.md — 在真实编码会话中评估 PCI

• docs/SYSTEM_PROMPT.md — 使用 PCI 的代理指令

• docs/SYSTEM_PROMPT_RATIONALE.md — 提示词设计原理

• docs/SESSION_RETROSPECTIVE_PROMPT.md — 会话结束时的评估提示词

• .env.example — 环境配置参考

• CONTRIBUTING.md — 开发工作流

许可证

MIT。参见 LICENSE。