# https://github.com/sverklo/sverklo 项目说明书
生成时间：2026-05-31 02:34:42 UTC
## 目录
- [Sverklo简介](#introduction)
- [快速入门指南](#quick-start)
- [与其他工具的对比](#comparison)
- [系统架构](#system-architecture)
- [检索引擎原理](#retrieval-engine)
- [索引器系统](#indexer-system)
- [MCP工具集](#mcp-tools)
- [双时态记忆系统](#memory-system)
- [差异审计与质量门禁](#audit-diff)
- [存储层架构](#storage-layer)
## Sverklo简介
### 相关页面
相关主题：[快速入门指南](#quick-start), [系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sverklo/sverklo/blob/main/README.md)
- [package.json](https://github.com/sverklo/sverklo/blob/main/package.json)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/tools/lookup.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/lookup.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
- [skill/README.md](https://github.com/sverklo/sverklo/blob/main/skill/README.md)
- [src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
# Sverklo简介
## 概述
Sverklo是一款面向代码代理（coding agents）的本地优先仓库记忆工具，通过Model Context Protocol（MCP）为Claude Code、Cursor、Windsurf和Codex CLI等主流AI编码工具提供代码智能服务。
Sverklo的核心价值在于解决AI编码代理在大型代码仓库中"上下文缺失"的问题——它为代理提供符号图谱、影响范围分析、差异感知审查和跨会话持久记忆能力，使其能够理解代码结构、评估变更风险、记住设计决策。
| 属性 | 值 |
|------|-----|
| 当前版本 | v0.29.0 |
| 许可证 | MIT |
| 依赖要求 | Node.js >= 24.0.0 |
| API密钥 | 无需（完全本地运行） |
| 仓库地址 | github.com/sverklo/sverklo |
| 官方网站 | sverklo.com |
资料来源：[package.json:1-40](https://github.com/sverklo/sverklo/blob/main/package.json)
## 核心功能
### 混合检索引擎
Sverklo采用三层混合检索架构，结合多种召回信号来提高搜索准确性：
1. **BM25关键词检索** - 基于词频的稀疏检索，处理精确术语匹配
2. **ONNX本地向量嵌入** - 使用本地运行的神经网络模型生成语义向量，支持语义相似度搜索
3. **PageRank图排序** - 基于代码依赖关系图计算文件重要性，高PageRank的文件在检索中享有更高权重
这三种信号通过**倒数排名融合（Reciprocal Rank Fusion）**进行合并，优先展示多个检索器一致认可的高质量结果。
资料来源：[package.json:25](https://github.com/sverklo/sverklo/blob/main/package.json)
### 持久记忆系统
Sverklo的记忆系统允许开发者和代理在代码仓库中保存跨会话的设计决策、架构笔记和开发约定。记忆分为不同的优先级层级（core/invariant等），核心项目上下文可在每次会话开始时自动注入。
```mermaid
graph LR
A[开发者提出决策] --> B[remember 工具保存]
B --> C[memoryStore 存储]
C --> D[recall 查询记忆]
D --> E[会话开始时注入]
E --> A
```
### 代码影响分析
通过符号依赖图和blast-radius分析，Sverklo能够计算变更的影响范围：
- 哪些文件依赖被修改的模块
- 哪些上游变更会影响指定文件
- 环形依赖检测
- 高风险文件识别（高扇入、低测试覆盖）
### 差异感知审查
支持对Git diff进行结构化分析，基于启发式规则识别潜在问题：
- 无保护的流调用
- 未处理的Promise rejection
- 缺失的错误边界
- 类型安全问题
资料来源：[src/server/tools/review-format.ts:1-30](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
## 工具集概览
Sverklo提供37个MCP工具，按功能分为以下类别：
| 类别 | 工具 | 用途 |
|------|------|------|
| 搜索 | search, search_iterative, investigate | 混合检索、多轮搜索、深入调查 |
| 导航 | lookup, refs, overview | 符号查找、引用追踪、仓库概览 |
| 依赖 | deps, impact, context | 依赖分析、影响范围、上下文聚合 |
| 记忆 | remember, recall | 保存/查询持久记忆 |
| 审查 | review_diff, audit | 差异审查、代码健康评分 |
| 研究 | concepts, patterns, clusters | 概念提取、模式识别、聚类分析 |
### 核心工具详解
#### search - 语义搜索
Sverklo的首选搜索工具，融合BM25+向量+PageRank信号，返回多信号一致认可的结果。
```typescript
// 使用示例
search query: "用户认证中间件"
```
#### lookup - 符号查找
精确查找代码中的符号定义，支持类型过滤：
| 参数 | 类型 | 说明 |
|------|------|------|
| symbol | string | 符号名称（必填） |
| type | enum | 函数/类/类型/接口等过滤 |
| token_budget | number | 最大返回token数 |
资料来源：[src/server/tools/lookup.ts:1-50](https://github.com/sverklo/sverklo/blob/main/src/server/tools/lookup.ts)
#### impact - 影响分析
分析变更或符号的"爆炸半径"，展示所有受影响的上游和下游依赖。
#### remember/recall - 记忆系统
- `remember` - 将决策、约定、架构笔记保存到仓库记忆
- `recall` - 根据查询检索相关记忆
#### review_diff - 差异审查
对Git diff进行结构化分析，输出风险评分和启发式问题列表。
### 预设工具配置
Sverklo支持通过`SVERKLO_PROFILE`环境变量选择预设的工具配置，减少代理看到的工具数量：
| 配置名 | 包含工具数 | 适用场景 |
|--------|-----------|----------|
| core | 5个 | 基础搜索和导航 |
| nav | 8个 | 添加依赖导航 |
| lean | 11个 | 轻量级，包含记忆功能 |
| full | 全部37个 | 完整功能（默认） |
| research | 18个 | 代码研究和调查 |
| review | 9个 | PR/MR审查专用 |
资料来源：[src/server/tool-overrides.ts:1-80](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
## MCP协议集成
Sverklo作为MCP服务器运行，支持标准的MCP协议接口：
```mermaid
graph TD
A[IDE/客户端] -->|tools/list| B[Sverklo MCP Server]
A -->|tools/call| B
A -->|prompts/list| B
A -->|resources/list| B
B -->|工具定义| A
B -->|执行结果| A
subgraph "Sverklo内部"
C[indexer]
D[memoryStore]
E[graphStore]
F[fileStore]
B --> C
C --> D
C --> E
C --> F
end
```
### 资源（Resources）
Sverklo暴露一个标准资源` sverklo://context`，在每次会话开始时自动注入项目上下文：
- 核心项目记忆（tier='core'）
- 依赖图中的高PageRank文件
- 最近的记忆条目
### 提示模板（Prompts）
Sverklo提供多个预定义的MCP提示模板，可在IDE picker中直接调用：
| 模板名 | 功能 |
|--------|------|
| sverklo/map-feature | 跨仓库功能映射 |
| sverklo/architecture-map | 架构图生成 |
| sverklo/pre-merge | 合并前审查 |
资料来源：[src/server/prompts.ts:1-60](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
## 安装与使用
### 快速开始
```bash
# 全局安装
npm install -g sverklo
# 在项目目录初始化
cd your-project
sverklo init
# 查看状态
sverklo status
```
### CLI命令
| 命令 | 功能 |
|------|------|
| sverklo init | 初始化项目索引 |
| sverklo register | 注册仓库到全局registry |
| sverklo reindex | 重建索引 |
| sverklo list | 列出已注册仓库 |
| sverklo status | 显示索引状态 |
| sverklo doctor | 健康检查 |
| sverklo init --global | 全局初始化（跳过项目级配置） |
资料来源：[skill/README.md:1-30](https://github.com/sverklo/sverklo/blob/main/skill/README.md)
## 技术架构
### 索引管道
```mermaid
graph LR
A[源代码文件] --> B[fileStore]
A --> C[index-code]
C --> D[chunkStore]
C --> E[symbolStore]
C --> F[docEdgeStore]
D & E & F --> G[graphStore]
G --> H[PageRank计算]
H --> D & E
```
### 数据存储
Sverklo使用本地文件存储，支持以下数据结构：
- **fileStore** - 文件元数据（路径、语言、行数、PageRank）
- **chunkStore** - 代码分块及其向量嵌入
- **symbolStore** - 符号定义和引用
- **graphStore** - 文件间依赖关系图
- **memoryStore** - 持久记忆（分层级）
### Git感知
Sverklo与Git深度集成：
- 支持分支和工作树（worktree）管理
- 差异感知工具基于HEAD和WORKDIR对比
- 提交历史的符号追踪
## 社区关注的问题
### 活跃讨论
| Issue | 讨论点 |
|-------|--------|
| #29 | 评估ColBERT/PLAID式多向量重排序器 vs 当前双编码器+BM25+PageRank架构 |
| #72 | init --global 功能请求：一次设置后可直接register |
| #73 | unregister支持--by-path参数，方便代理驱动的工作树清理 |
| #71 | MCP工具名称双前缀问题（sverklo_sverklo_*） |
### 已知问题
| Issue | 描述 |
|-------|------|
| #74 | reindex后registry.json的lastIndexed时间戳未更新 |
| #20 | Windows平台路径处理问题 |
| #17 | 旧版二进制文件警告缺失 |
## 生态扩展
### Claude Code Skill
Sverklo提供完整的Claude Code Skill包，支持：
- `sverklo_search` - 语义搜索
- `sverklo_review_diff` - 风险评分PR审查
- `sverklo_audit` - 代码库健康评分
- `sverklo_remember/recall` - 持久记忆
### 子代理（Subagents）
sverklo-explore子代理替代Claude Code内置的Explore工具，单次调用仅消耗150-800 token即可定位目标，相比默认的14200 token有显著提升。
### GitHub Action
sverklo/action可在PR中自动发布AI审查评论，支持：
- 内联评论锚定到问题行
- 基于风险等级的构建失败控制
- 结构化的GitHub PR Review JSON输出
资料来源：[action/README.md:1-50](https://github.com/sverklo/sverklo/blob/main/action/README.md)
## 设计原则
1. **本地优先** - 所有处理在本地完成，无需API密钥或代码上传
2. **无状态协调** - MCP服务器无状态，状态存储在本地文件
3. **工具可配置** - 支持运行时禁用或重描述工具
4. **Token高效** - 通过PageRank剪枝和token预算控制保持上下文精简
5. **Git原生** - 深度集成Git而非替代其工作流
---
## 快速入门指南
### 相关页面
相关主题：[Sverklo简介](#introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/sverklo/sverklo/blob/main/package.json)
- [skill/README.md](https://github.com/sverklo/sverklo/blob/main/skill/README.md)
- [action/README.md](https://github.com/sverklo/sverklo/blob/main/action/README.md)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
# 快速入门指南
## 概述
Sverklo 是面向代码智能体的本地优先 MCP（Model Context Protocol）工具，专为 Claude Code、Cursor、Windsurf 和 Codex CLI 等开发环境设计。核心功能包括符号依赖图、代码变更影响分析（blast radius）、差异感知审查（diff-aware review）以及跨会话的持久化记忆。
资料来源：[package.json:3-8]()
## 系统要求
| 要求项 | 规格 |
|--------|------|
| Node.js | >= 24.0.0 |
| 系统 | macOS、Linux、Windows |
| 许可证 | MIT |
| API 密钥 | 无需 |
## 安装
### 全局安装
```bash
npm install -g sverklo
```
安装完成后，CLI 工具 `sverklo` 将全局可用。
### 验证安装
```bash
sverklo --version
```
资料来源：[package.json:14]()
## 项目初始化
### 基本初始化
在项目根目录运行：
```bash
sverklo init
```
`init` 命令执行以下操作：
1. 创建本地配置文件（`CLAUDE.md` 或 `AGENTS.md`）
2. 导入现有项目文档和决策记录
3. 建立本地索引
### 初始化选项
| 选项 | 说明 |
|------|------|
| `--global` | 全局设置模式，一次性配置后无需每个项目重复初始化 |
| `--by-path` | 通过路径注册项目（适用于 agent 驱动的 worktree 管理） |
> ⚠️ **已知问题**：在全新 git 仓库（无任何提交）中运行 `sverklo init` 会产生无害的 git 警告信息 "Use '--' to separate paths..."，但初始化本身会成功完成。
资料来源：[skill/README.md:15-20]()
### AGENTS.md 兼容性
如果项目使用 `AGENTS.md` 而非 `CLAUDE.md`，初始化命令会自动检测并尊重该偏好。确保项目根目录存在相应的文档文件。
## 注册与管理
### 注册项目
```bash
sverklo register .
```
将当前目录注册到本地 registry（位于 `~/.sverklo/registry.json`）。
### 列出已注册项目
```bash
sverklo list
```
显示所有已注册项目的名称、路径和最后索引时间。
### 注销项目
```bash
sverklo unregister <项目名称>
```
或按路径注销：
```bash
sverklo unregister --by-path /path/to/project
```
## 索引与更新
### 重建索引
```bash
sverklo reindex .
```
重新扫描项目文件并更新符号图和依赖关系。
> ⚠️ **已知问题**：`reindex` 命令完成后不会更新 `~/.sverklo/registry.json` 中的 `lastIndexed` 时间戳，导致 `list` 显示的时间信息可能不准确。
### 索引状态检查
```bash
sverklo doctor
```
运行健康检查，验证索引完整性、版本兼容性和依赖状态。
> ⚠️ **版本检查注意**：在某些环境下，`doctor` 命令可能执行 PATH 上的 sverklo 而非嵌入式版本，如遇版本不一致请手动确认。
## MCP 服务器
Sverklo 通过 MCP 协议与 IDE 集成，提供代码智能服务。
### 启动 MCP 服务器
```bash
sverklo serve
```
服务器将注册以下核心工具：
| 工具 | 功能 |
|------|------|
| `search` | 语义代码搜索（混合 BM25 + 向量检索） |
| `lookup` | 符号定义查找 |
| `overview` | 代码库概览 |
| `refs` | 符号引用追踪 |
| `impact` | 变更影响分析 |
| `deps` | 依赖图分析 |
| `context` | 上下文聚合查询 |
| `status` | 项目状态 |
| `remember` | 保存决策记忆 |
| `recall` | 检索记忆 |
| `review_diff` | 差异感知审查 |
| `audit` | 代码库健康评分 |
| `investigate` | 多信号联合调查 |
| `ask` | 自然语言问答 |
资料来源：[src/server/mcp-server.ts:15-40]()
### 工具预设模式
| 模式 | 包含工具 |
|------|----------|
| `default` | search, lookup, overview, refs, impact |
| `lean` | search, lookup, overview, refs, impact, deps, context, status, remember, recall, review_diff |
| `research` | search, search_iterative, investigate, ask, lookup, overview, refs, impact, deps, concepts, patterns, clusters, verify, critique, ctx_slice, ctx_grep, ctx_stats, status |
| `review` | review_diff, diff_search, test_map, impact, refs, lookup, search, investigate, verify, status |
资料来源：[src/server/tool-overrides.ts:1-50]()
### MCP 工具命名
所有工具自动带有 `sverklo_` 前缀（如 `sverklo_impact`、`sverklo_lookup`）。如在注册时使用 `"sverklo"` 作为服务器键名，会产生双重前缀（`sverklo_sverklo_impact`）。建议使用不同的注册键名避免此问题。
## 工作流程示例
### 工作流程一：日常开发上下文获取
```mermaid
graph TD
A[启动 IDE] --> B[sverklo MCP 服务器启动]
B --> C[自动读取 sverklo://context]
C --> D[获取 Core Memories 和项目概览]
D --> E[使用 context 工具获取任务相关上下文]
E --> F[开始编码任务]
```
首次启动时，服务器会自动注入项目核心记忆和概览信息，帮助智能体快速了解项目结构。
### 工作流程二：代码审查
```mermaid
graph TD
A[创建 PR] --> B[运行 sverklo review_diff]
B --> C[执行启发式检查]
C --> D[识别高风险文件]
D --> E[生成风险评分]
E --> F[输出审查报告]
F --> G{风险等级}
G -->|低| H[通过]
G -->|高| I[标记需关注]
```
使用 `review_diff` 工具获取变更影响分析和结构化审查报告。
### 工作流程三：持久化决策记忆
```mermaid
graph TD
A[发现重要决策] --> B[使用 remember 工具]
B --> C[指定 category 分类]
C --> D[保存至记忆存储]
D --> E[后续会话 recall 召回]
```
决策记忆支持分类标签，便于后续检索和上下文复用。
## GitHub Actions 集成
Sverklo 提供 GitHub Action 用于 PR 自动审查：
```yaml
name: Sverklo Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: sverklo/sverklo/action@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on: high
```
### Action 参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `github-token` | `${{ github.token }}` | GitHub 认证令牌 |
| `fail-on` | `none` | 风险超阈值时失败：critical/high/medium/low/none |
| `ref` | auto | Git 引用范围 |
| `max-files` | `25` | 最大审查文件数 |
| `inline-comments` | `true` | 是否发布内联审查注释 |
资料来源：[action/README.md:1-35]()
## Claude Skill 集成
安装 Claude Code 技能包：
```bash
cd your-project
sverklo init
```
这会自动配置以下技能：
- `sverklo_search` — 语义代码搜索
- `sverklo_lookup` — 符号定义查找
- `sverklo_overview` — 代码库概览
- `sverklo_impact` — 变更影响分析
- `sverklo_review_diff` — 风险评分 PR 审查
- `sverklo_audit` — 代码库健康评分
- `sverklo_remember` / `sverklo_recall` — 持久化记忆
资料来源：[skill/README.md:1-15]()
## 提示模板
Sverklo 提供内置提示模板，通过 MCP 协议的 prompts 接口调用：
| 模板名称 | 用途 |
|----------|------|
| `sverklo/map-feature` | 跨代码库映射功能特性 |
| `sverklo/investigate` | 多信号联合调查 |
| `sverklo/pre-merge` | 合并前审查 |
| `sverklo/onboard` | 新成员引导 |
资料来源：[src/server/prompts.ts:1-50]()
## 常见问题
### Q: Windows 系统路径问题
如遇路径处理问题，sverklo 内部已针对跨平台路径进行了处理，但部分边缘情况可能仍需注意。
### Q: MCP 工具名双重前缀
当服务器注册键名为 `"sverklo"` 时，会产生 `sverklo_sverklo_*` 格式的工具名。建议使用不同的服务器注册键名（如项目名）来避免。
### Q: 版本不一致警告
升级 npm 包后，如 IDE 中的 MCP 服务器子进程已运行，可能报告旧版本。请重启 IDE 或手动刷新 MCP 连接。
## 下一步
- 查看 [详细命令参考]() 了解所有工具的完整参数
- 查看 [记忆系统指南]() 学习决策持久化最佳实践
- 查看 [代码审查工作流]() 了解 PR 集成配置
---
## 与其他工具的对比
### 相关页面
相关主题：[Sverklo简介](#introduction), [检索引擎原理](#retrieval-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/sverklo/sverklo/blob/main/package.json)
- [src/server/tools/search.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/search.ts)
- [src/server/audit-analysis.ts](https://github.com/sverklo/sverklo/blob/main/src/server/audit-analysis.ts)
- [src/server/tools/impact.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/impact.ts)
- [src/server/tools/review-format.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
- [action/README.md](https://github.com/sverklo/sverklo/blob/main/action/README.md)
# 与其他工具的对比
## 概述
sverklo 是一个面向代码智能的本地优先 MCP（Model Context Protocol）工具，专为编码代理设计。与传统代码搜索或文档工具不同，sverklo 采用多信号检索架构，结合全文搜索（BM25）、语义向量搜索（ONNX 嵌入）、PageRank 重要性排序和图结构分析，提供深度的代码库理解能力。资料来源：[package.json:1-15]()
## 核心定位对比
### 传统代码搜索 vs sverklo
| 维度 | 传统工具（grep/ag/ripgrep） | sverklo |
|------|---------------------------|---------|
| 搜索方式 | 精确字符串匹配 | BM25 + 语义向量混合 |
| 上下文理解 | 无 | 符号图、依赖关系、PageRank |
| 记忆能力 | 无 | 跨会话持久化记忆 |
| 变更分析 | diff 视图 | blast-radius 影响分析 |
| API 形式 | CLI | MCP 协议，可集成 IDE |
资料来源：[src/server/tools/search.ts:80-95]()
### 通用 RAG 平台 vs sverklo
sverklo 与通用 RAG（检索增强生成）平台的核心差异在于其对代码结构的深度理解：
- **通用 RAG**：文档级别切分，丢失代码结构
- **sverklo**：AST 感知切分，保留符号边界、函数签名、导入关系
```mermaid
graph TD
A[用户查询] --> B{sverklo 多信号检索}
B --> C[BM25 全文搜索]
B --> D[ONNX 向量搜索]
B --> E[PageRank 排序]
B --> F[符号图分析]
C --> G[结果融合]
D --> G
E --> G
F --> G
G --> H[精排结果]
```
资料来源：[src/server/audit-analysis.ts:45-65]()
## 检索架构对比
### 当前架构：Bi-encoder + BM25 + PageRank
sverklo 当前采用 bi-encoder（双编码器）进行语义嵌入，配合 BM25 全文索引和 PageRank 重要性排序。资料来源：[package.json:31-32]()
**优势**：
- 本地运行，无需 API key
- 延迟低，可离线使用
- 多信号互补，覆盖精确和语义搜索
**局限性**（社区议题 #29）：
- Bi-encoder 对短查询的语义匹配能力有限
- 无法捕捉 token 级别的细粒度相似度
- 与 ColBERT/PLAID 多向量架构相比，精确度可能不足
资料来源：[GitHub Issue #29](https://github.com/sverklo/sverklo/issues/29)
### 潜在演进：ColBERT/PLAID 多向量架构
社区正在评估多向量 reranker 方案，其核心优势：
| 特性 | Bi-encoder | ColBERT/PLAID |
|------|-----------|---------------|
| 向量数量 | 每文档 1 个 | 每 token 多个 |
| 查询延迟 | O(1) | O(n) |
| 精度 | 中等 | 高 |
| 实现复杂度 | 低 | 高 |
资料来源：[GitHub Issue #29 评论区](https://github.com/sverklo/sverklo/issues/29)
## 代码审查工具对比
### sverklo Review vs 传统 CI 检查
sverklo 的 PR 审查能力与 GitHub Actions 原生检查形成互补：
| 功能 | GitHub Actions | sverklo Review |
|------|---------------|----------------|
| 静态分析 | ESLint/TSLint | 结构化启发式检查 |
| 风险评分 | 无 | 关键/高/中/低四级 |
| Blast Radius | 无 | 符号级影响分析 |
| 变更记忆 | 无 | 跨会话追踪 |
| 部署形式 | YAML workflow | GitHub Action |
资料来源：[action/README.md:1-30]()
### 审查输出格式
sverklo 生成结构化 PR Review JSON，包含：
```json
{
"ref": "main..HEAD",
"max_risk": "high",
"summary": "",
"inline": [
{ "path": "src/api.ts", "line": 42, "severity": "high", "body": "..." }
],
"high_risk_files": [
{ "path": "src/auth.ts", "score": 0.85, "reasons": ["公开接口", "无权限校验"] }
]
}
```
资料来源：[src/server/tools/review-format.ts:20-30]()
## MCP 协议集成对比
### sverklo MCP vs 其他 MCP 服务器
sverklo 通过 MCP 协议提供服务，与其他代码相关 MCP 的对比：
| 特性 | sverklo | 其他 MCP |
|------|---------|----------|
| 数据存储 | 本地 SQLite | 云端/混合 |
| 索引类型 | 符号图 + 向量 + BM25 | 通常单一 |
| 工具数量 | 15+ | 5-10 |
| 记忆系统 | 核心/普通/临时三层 | 通常无 |
| 工具前缀 | `sverklo_*` | `*` |
资料来源：[src/server/mcp-server.ts:50-80]()
### 工具配置集
sverklo 提供预设的工具配置集，适应不同工作场景：
```typescript
const PROFILES = {
// 最小化视图，仅核心导航
overview: ["search", "lookup", "overview", "refs", "impact"],
// 完整功能集
full: [...全部工具...],
// PR/MR 审查专注
review: ["review_diff", "diff_search", "test_map", "impact", "refs"],
// 代码研究/入职引导
research: ["search", "investigate", "ask", "lookup", "refs", "clusters"]
};
```
资料来源：[src/server/tools/tool-overrides.ts:1-50]()
## 影响分析能力对比
### sverklo Impact vs 简单引用计数
sverklo 的 `impact` 工具提供符号级 blast radius 分析：
| 能力 | 简单 grep 引用 | sverklo impact |
|------|---------------|----------------|
| 定义定位 | 需手动搜索 | 自动定位 |
| 多定义区分 | 无 | 按文件/类型分组 |
| 调用者分类 | 全部混排 | 重要性排序 |
| 导出能力 | 无 | partition plan 分区 |
资料来源：[src/server/tools/impact.ts:20-45]()
```mermaid
graph LR
A[符号查询] --> B{定义数量}
B -->|1| C[DIRECT ● 高置信]
B -->|多个| D[UNCERTAIN ◐ 需验证]
B -->|0| E[INFERRED ○ 外部符号]
C --> F[调用者列表]
D --> F
E --> F
F --> G[按 PageRank 排序]
G --> H[分区展示]
```
## 记忆系统对比
### sverklo Memory vs 通用笔记工具
sverklo 的记忆系统专为代码代理设计：
| 特性 | 通用笔记/Notion | sverklo Memory |
|------|----------------|---------------|
| 内容关联 | 手动标签 | 自动符号链接 |
| 会话加载 | 无 | 核心记忆自动加载 |
| 过期机制 | 无 | `is_stale` 标记 |
| 分类体系 | 扁平/树状 | 类别 + 层级 |
资料来源：[src/server/mcp-server.ts:120-145]()
**核心记忆（Core Memories）**：项目级不变量，在每个会话开始时自动注入上下文。
```typescript
const coreMemories = indexer.memoryStore.getCore(15);
// 自动加载到每个会话的 sverklo://context 资源
```
资料来源：[src/server/mcp-server.ts:125-130]()
## 性能与架构对比
### 本地优先 vs 云端方案
| 维度 | sverklo | Sourcegraph/Github Copilot |
|------|---------|---------------------------|
| 数据位置 | 本地 ~/.sverklo/ | 云端/第三方服务器 |
| API Key | 不需要 | 需要 |
| 代码上传 | 不上传 | 部分上传 |
| 离线能力 | 完全支持 | 部分支持 |
| 索引速度 | 中等 | 快（云端） |
| 隐私保证 | 强 | 依赖服务商 |
资料来源：[package.json:7-10]()
### 依赖项分析
sverklo 的轻量级依赖设计：
| 组件 | 用途 | 类型 |
|------|------|------|
| `onnxruntime-node` | 本地向量计算 | 必需 |
| `web-tree-sitter` | AST 解析 | 可选 |
| `@modelcontextprotocol/sdk` | MCP 协议 | 必需 |
| `chokidar` | 文件监听 | 必需 |
资料来源：[package.json:37-48]()
## 适用场景矩阵
```
短任务 长任务 团队协作
───── ───── ───────
代码搜索/导航 ●●● ●● ●●
PR 审查 ● ●●● ●●●
代码重构影响分析 ●● ●●● ●●
新人入职引导 ○ ●●● ●●
API 文档生成 ● ●● ●●
●●● 最佳选择 ●● 推荐 ● 可用 ○ 不适合
```
资料来源：[src/server/prompts.ts:1-20]()
## 局限性与已知问题
### 社区报告的局限
| 问题 | 状态 | 参考 |
|------|------|------|
| MCP 工具名双重前缀 | 已知 [#71](https://github.com/sverklo/sverklo/issues/71) | `sverklo_sverklo_*` 格式 |
| Windows 路径处理 | 已知 [#20](https://github.com/sverklo/sverklo/issues/20) | 反斜杠兼容 |
| 检索精度（bi-encoder） | 评估中 [#29](https://github.com/sverklo/sverklo/issues/29) | ColBERT 方案 |
| reindex 时间戳未更新 | Bug [#74](https://github.com/sverklo/sverklo/issues/74) | registry.json |
### 性能基准说明
社区基准测试发现某些场景下存在回归：
- Parser 的字符串/注释感知括号计数器修复后，P1 从 0.30 提升至 0.73
- 但 P2/P4 有轻微回归，需持续监控
资料来源：[GitHub Issue #28](https://github.com/sverklo/sverklo/issues/28)
## 总结
sverklo 在以下场景具有独特优势：
1. **隐私敏感环境**：数据不出本机，无需 API key
2. **深度代码理解**：符号图 + PageRank + 多信号检索
3. **代理工作流**：MCP 协议原生集成，记忆跨会话持久化
4. **变更影响评估**：blast radius 符号级分析
与传统工具相比，sverklo 更适合需要深度代码库理解、AI 代理协作和长期项目记忆的场景，而非简单的关键词搜索需求。
---
## 系统架构
### 相关页面
相关主题：[索引器系统](#indexer-system), [检索引擎原理](#retrieval-engine), [存储层架构](#storage-layer)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/search/hybrid-search.ts](https://github.com/sverklo/sverklo/blob/main/src/search/hybrid-search.ts)
- [src/indexer/index-files.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-files.ts)
- [src/indexer/index-code.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-code.ts)
- [src/indexer/index-graph.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-graph.ts)
- [src/indexer/index-memory.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-memory.ts)
- [src/server/tools/context.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/context.ts)
- [src/server/tools/review-format.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
- [src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
# 系统架构
## 项目概述
Sverklo 是一个面向 AI 编码代理的代码库记忆系统，为 Claude Code、Cursor、Windsurf 和 Codex CLI 提供本地优先的 MCP（Model Context Protocol）服务。其核心功能包括符号依赖图、代码变更影响分析（blast radius）、差异感知审查以及跨会话的持久化记忆功能。
资料来源：[package.json](https://github.com/sverklo/sverklo/blob/main/package.json)
## 整体架构
Sverklo 采用分层模块化架构，核心分为索引系统、存储系统、搜索系统和 MCP 服务层四个主要部分。
```mermaid
graph TB
subgraph 索引系统
IF[索引文件
index-files.ts]
IC[索引代码
index-code.ts]
IG[索引依赖图
index-graph.ts]
IM[索引记忆
index-memory.ts]
EMB[嵌入生成器
embedder.ts]
end
subgraph 存储系统
DB[(SQLite
数据库)]
REGISTRY[registry.json
项目注册表]
end
subgraph 搜索系统
BM25[BM25 搜索引擎]
EMB_SEARCH[向量搜索
ONNX embeddings]
PR[PageRank
图排序]
HYBRID[混合搜索
hybrid-search.ts]
end
subgraph MCP 服务层
SERVER[MCP Server
mcp-server.ts]
TOOLS[Tools 工具集]
PROMPTS[Prompts 提示模板]
RESOURCES[Resources 资源]
end
IF --> DB
IC --> DB
IG --> DB
IM --> DB
EMB --> DB
BM25 --> HYBRID
EMB_SEARCH --> HYBRID
PR --> HYBRID
HYBRID --> SERVER
TOOLS --> SERVER
PROMPTS --> SERVER
RESOURCES --> SERVER
SERVER <--> 外部IDE
```
## 索引系统
索引系统是 Sverklo 的数据采集核心，负责构建代码库的语义索引。该系统由四个专门的索引器组成，每个索引器处理特定维度的代码分析。
### 索引器职责
| 索引器 | 文件 | 职责描述 |
|--------|------|----------|
| IndexFiles | index-files.ts | 扫描文件系统，提取文件元数据、路径、语言类型 |
| IndexCode | index-code.ts | 解析 AST，提取符号定义、引用、导入关系 |
| IndexGraph | index-graph.ts | 构建依赖图，计算 PageRank 分数 |
| IndexMemory | index-memory.ts | 管理持久化记忆，包括分类和过期标记 |
资料来源：[src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
### 嵌入生成器
Sverklo 使用 ONNX Runtime 在本地运行嵌入模型，无需外部 API。嵌入生成器支持可配置的嵌入维度，并维护一个模型缓存以提高重复查询的效率。
```mermaid
graph LR
A[源代码片段] --> B[文本预处理]
B --> C[ONNX 模型推理]
C --> D[归一化向量]
D --> E[(向量数据库)]
```
关键特性：
- 支持 ONNX 格式的预训练嵌入模型
- 向量维度可配置（通过 embedding_dim 参数）
- 模型下载后本地缓存于 `~/.sverklo/models/`
资料来源：[src/indexer/embedder.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/embedder.ts)
## 存储系统
### 数据库架构
Sverklo 使用 SQLite 作为本地持久化存储，所有索引数据存储在项目目录的 `.sverklo/` 子目录中。
```mermaid
graph TB
subgraph 数据库表
T1[files
文件表]
T2[symbols
符号表]
T3[edges
依赖边表]
T4[doc_edges
文档关联表]
T5[memories
记忆表]
T6[chunks
代码块表]
end
T1 <--> T2
T2 <--> T3
T1 <--> T4
T1 <--> T6
```
数据库文件结构：
```
.sverklo/
├── sverklo.db # SQLite 数据库
├── registry.json # 全局项目注册表
└── models/ # 缓存的 ONNX 模型
```
### 项目注册表
`registry.json` 维护全局项目索引，记录每个已注册项目的基本信息和状态。
| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 项目名称（目录基名） |
| path | string | 项目绝对路径 |
| lastIndexed | timestamp | 最后索引时间 |
| language | string[] | 检测到的编程语言 |
| fileCount | number | 索引文件数量 |
资料来源：[src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
## 搜索系统
Sverklo 采用混合搜索策略，结合多种检索方法以提供高质量的代码搜索结果。
### 混合搜索架构
```mermaid
graph TB
Q[用户查询] --> FTS[全文搜索
BM25]
Q --> VEC[向量搜索
语义嵌入]
Q --> PR[PageRank 排序]
FTS --> RRF[Reciprocal Rank Fusion
倒数排名融合]
VEC --> RRF
PR --> RRF
RRF --> R[排名结果]
```
混合搜索的核心流程：
1. **BM25 检索**：基于词频的稀疏检索，对精确匹配关键词效果好
2. **向量检索**：使用 ONNX 嵌入模型进行语义相似度计算
3. **PageRank 加权**：结合图的中心性分数，优先返回高影响力的代码位置
4. **倒数排名融合（RRF）**：将多个排名结果按 `1/(k+rank)}` 公式融合
资料来源：[src/search/hybrid-search.ts](https://github.com/sverklo/sverklo/blob/main/src/search/hybrid-search.ts)
### 检索信号
Sverklo 的搜索系统追踪多种检索信号，用于评估结果质量：
| 信号类型 | 说明 | 权重来源 |
|----------|------|----------|
| found_by | 检索方法标识 | 区分 FTS/向量/符号/引用 |
| score | 相关性分数 | 各检索器独立计算 |
| confidence | 置信度 | 基于匹配一致性 |
| pagerank | 图排名分数 | 节点在依赖图中的重要性 |
资料来源：[src/server/tools/find-references.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/find-references.ts)
### 社区相关：检索架构讨论
社区成员在 issue #29 中提出评估 ColBERT/PLAID 风格的多向量重排序器的可能性，以替代当前的双编码器 + BM25 + PageRank 架构。这是未来搜索系统可能的演进方向。
资料来源：[GitHub Issue #29](https://github.com/sverklo/sverklo/issues/29)
## MCP 服务层
MCP（Model Context Protocol）服务层是 Sverklo 与外部 IDE 交互的接口层，提供工具、资源和提示模板三类功能。
### 工具集
MCP 服务器暴露的工具按照功能分为多个类别：
| 工具类别 | 工具名称 | 功能描述 |
|----------|----------|----------|
| 搜索 | search, search_iterative | 混合搜索查询 |
| 查找 | lookup, refs, investigate | 符号定义和引用查找 |
| 上下文 | context, ctx_slice, ctx_grep | 上下文管理 |
| 分析 | impact, verify, critique | 影响分析和代码审查 |
| 记忆 | remember, recall | 持久化记忆操作 |
| 审查 | review_diff, test_map | 差异审查和测试映射 |
| 状态 | status, deps, overview | 项目状态查询 |
资料来源：[src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
### 工具预设配置
为不同使用场景预配置的工具集：
```mermaid
graph LR
subgraph 使用场景
S1[lean 轻量]
S2[review 审查]
S3[research 研究]
end
S1 --> T1[search lookup overview refs impact deps context status remember recall review_diff]
S2 --> T2[review_diff diff_search test_map impact refs lookup search investigate verify status]
S3 --> T3[search search_iterative investigate ask lookup overview refs impact deps concepts patterns clusters verify critique ctx_slice ctx_grep ctx_stats status]
```
- **lean**：适合轻量级代码编辑，跳过记忆和审计功能
- **review**：适合 PR/MR 审查，差异工具优先
- **research**：适合代码研究和入职引导，包含记忆和审计
资料来源：[src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
### 资源和提示模板
#### 资源（Resources）
MCP 服务器通过 `sverklo://context` 资源提供自动注入的项目上下文：
```
sverklo://context
├── 项目核心记忆（tier='core'）
├── 最近活跃记忆
├── 项目概览摘要
└── 技术栈信息
```
资源在会话开始时自动读取，帮助 AI 代理快速了解项目上下文。
资料来源：[src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
#### 提示模板（Prompts）
Sverklo 提供结构化的工作流模板：
| 提示名称 | 用途 |
|----------|------|
| sverklo/review-pr | PR/MR 审查工作流 |
| sverklo/onboarding | 新开发者入职引导 |
| sverklo/pre-merge | 合并前检查清单 |
| sverklo/map-feature | 功能模块映射 |
| sverklo/architecture | 架构探索和分析 |
| sverklo/debug | 调试和问题定位 |
这些模板定义了在特定任务中调用 sverklo 工具的推荐顺序。
资料来源：[src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
## 工具系统详解
### Context 工具
`context` 是一个伞形工具，可在一次调用中返回完整的上下文束：
```typescript
contextTool = {
name: "context",
inputSchema: {
task: "任务描述",
detail_level: "minimal | normal | full",
scope: "路径前缀过滤",
budget: "PageRank 剪枝的 token 预算"
}
}
```
工作流程：
1. 接收任务描述
2. 调用混合搜索获取相关代码
3. 获取相关符号定义
4. 召回匹配的保存记忆
5. 组装成单一上下文束返回
资料来源：[src/server/tools/context.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/context.ts)
### 差异审查工具
差异审查生成两种输出格式：
1. **Markdown 摘要**：供人类阅读的 PR 评论
2. **结构化 JSON**：GitHub PR Review API 格式，可直接 POST 到 GitHub
```typescript
interface GitHubReviewPayload {
ref: "main..HEAD",
max_risk: "critical | high | medium | low",
summary: "markdown body",
inline: [{ path, line, severity, body }],
high_risk_files: [{ path, score, reasons }]
}
```
资料来源：[src/server/tools/review-format.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
### Critique 工具
`critique` 工具对 AI 代理的答案进行事后审查：
- 验证引用证据的时效性
- 检查遗漏的高 PageRank 节点
- 识别未定义的符号引用
- 检测缺乏文档引用的符号
资料来源：[src/server/tools/critique.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/critique.ts)
## 数据流
### 会话启动流程
```mermaid
sequenceDiagram
participant IDE as 外部 IDE
participant MCP as MCP Server
participant Indexer as 索引器
participant Store as 存储层
IDE->>MCP: 启动 MCP 会话
MCP->>Indexer: 等待索引完成
Indexer->>Store: 加载索引数据
Store-->>Indexer: 返回索引状态
MCP->>MCP: 获取核心记忆
MCP->>MCP: 获取项目概览
MCP->>IDE: 返回 sverklo://context 资源
IDE->>MCP: 请求工具调用
MCP->>Store: 查询数据
Store-->>MCP: 返回结果
MCP-->>IDE: 返回工具响应
```
### 搜索请求流程
```mermaid
sequenceDiagram
participant User as 用户/代理
participant MCP as MCP Server
participant Search as 混合搜索
participant DB as 数据库
User->>MCP: search(query="parse config")
MCP->>Search: 混合搜索请求
Search->>DB: BM25 查询
Search->>DB: 向量相似度查询
Search->>DB: PageRank 排序
DB-->>Search: BM25 结果
DB-->>Search: 向量结果
DB-->>Search: 图排名分数
Search->>Search: RRF 融合排序
Search-->>MCP: 融合结果
MCP-->>User: 搜索响应
```
## 已知限制与社区问题
### 平台兼容性
Windows 用户报告了路径处理问题。sverklo 在处理 Windows 反斜杠路径时存在兼容性问题，社区建议使用以下模式转换：
```javascript
path.replace(/\\/g, "/").split("/").pop()
```
资料来源：[GitHub Issue #20](https://github.com/sverklo/sverklo/issues/20)
### MCP 工具命名
当 MCP 服务器注册为 `"sverklo"` 键时，工具名会产生双重前缀（如 `sverklo_sverklo_impact`）。这是工具前缀与服务器注册键名冲突导致的。
资料来源：[GitHub Issue #71](https://github.com/sverklo/sverklo/issues/71)
### 索引时间戳更新
`reindex` 命令完成后未更新 `registry.json` 中的 `lastIndexed` 字段，导致 `list` 命令显示的索引年龄信息滞后。
资料来源：[GitHub Issue #74](https://github.com/sverklo/sverklo/issues/74)
## 技术栈
| 组件 | 技术选型 | 说明 |
|------|----------|------|
| 运行时 | Node.js >= 24.0.0 | ESM 模块系统 |
| 协议 | MCP SDK 1.12.0 | Model Context Protocol |
| 数据库 | SQLite | 本地持久化存储 |
| 嵌入模型 | ONNX Runtime | 本地向量计算 |
| 解析器 | tree-sitter | AST 解析（可选依赖） |
| 模式匹配 | picomatch | 文件过滤 |
| 监视 | chokidar | 文件系统监视 |
资料来源：[package.json](https://github.com/sverklo/sverklo/blob/main/package.json)
---
## 检索引擎原理
### 相关页面
相关主题：[系统架构](#system-architecture), [双时态记忆系统](#memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/tools/context.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/context.ts)
- [src/server/tools/find-references.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/find-references.ts)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
- [src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
# 检索引擎原理
Sverklo 的检索引擎是一个本地优先的多信号混合搜索系统，旨在为编码代理（coding agents）提供精准的代码智能搜索能力。本页面详细介绍其架构设计、搜索流程、排序机制以及与社区反馈相关的前沿探索方向。
## 核心定位
Sverklo 检索引擎的核心目标是解决代码库中的**语义搜索**问题。与传统的关键词匹配不同，Sverklo 通过多种检索信号的协同工作，理解代码的语义关联，使代理能够快速定位到与任务最相关的代码片段、符号定义和文档内容。
根据 `src/server/mcp-server.ts` 中的描述，检索引擎被定位为"sverklo `search` tool for semantic code search (preferred over grep)"，是代理进行代码探索时的首选工具。资料来源：[src/server/mcp-server.ts:100]()。
## 多信号混合检索架构
### 检索信号类型
Sverklo 采用多信号混合检索（Hybrid Search）架构，综合利用以下几种检索信号：
| 信号类型 | 说明 | 适用场景 |
|---------|------|---------|
| **全文搜索（FTS）** | 传统的关键词匹配，基于字符串相似度 | 精确函数名、变量名搜索 |
| **向量嵌入（Embeddings）** | 基于语义理解的相似度匹配 | 概念性查询、自然语言描述 |
| **BM25** | 改进的词袋模型，考虑词频和文档长度归一化 | 平衡精确性和相关性 |
| **PageRank** | 基于代码依赖图的重要性排序 | 优先返回高影响力的核心代码 |
根据 `package.json` 中的项目关键词定义，系统集成了 `embeddings`、`bm25`、`pagerank` 等核心依赖。资料来源：[package.json:8-17]()
### 信号融合策略
Sverklo 使用 **Reciprocal Rank Fusion (RRF)** 算法将多个检索信号的结果进行融合排序。RRF 的核心思想是：对每个检索信号的结果按相关性排名，对排名位置取倒数并求和，得到最终的融合分数。
这种策略的优势在于：
- 不同信号的优势互补，弥补单一检索模式的局限性
- 减少对某一信号偏差的敏感度
- 能够在语义和精确匹配之间取得平衡
项目在 `package.json` 中明确将 `reciprocal-rank-fusion` 列为关键词，表明该技术在整个检索系统中占据核心地位。资料来源：[package.json:11]()
## 搜索工具体系
### 工具层级结构
根据 `src/server/tool-overrides.ts` 的定义，Sverklo 提供了不同场景下的工具集合配置：
```typescript
const TOOL_SETS = {
// 核心搜索集：最小可用搜索功能集
core: ["search", "lookup", "overview", "refs", "impact"],
// 轻量级搜索集：包含记忆功能的完整工具链
lean: ["search", "lookup", "overview", "refs", "impact", "deps",
"context", "status", "remember", "recall", "review_diff"],
// 研究级搜索集：面向开放性代码研究的完整工具链
research: ["search", "search_iterative", "investigate", "ask", "lookup",
"overview", "refs", "impact", "deps", "concepts", "patterns",
"clusters", "verify", "critique", "ctx_slice", "ctx_grep", "ctx_stats", "status"],
};
```
资料来源：[src/server/tool-overrides.ts:1-35]()
### 核心搜索工具
| 工具名 | 功能描述 | 典型用例 |
|--------|---------|---------|
| `search` | 基础语义搜索入口 | 快速查找相关代码片段 |
| `investigate` | 单次调用完成多信号联合搜索 | 一次性获取全面搜索结果 |
| `search_iterative` | 迭代式搜索，支持逐步细化 | 需要多轮探索的复杂查询 |
| `lookup` | 符号定义查找 | 定位函数、类、变量的定义位置 |
| `refs` | 符号引用查找 | 查找某个符号的所有使用位置 |
| `concepts` | 概念模式识别 | 发现代码中的设计模式 |
| `patterns` | 代码模式检测 | 识别常见的代码结构模式 |
| `clusters` | 代码聚类分析 | 按语义相似性组织代码 |
资料来源：[src/server/tool-overrides.ts:17-28]()
## investigate 工具详解
### 功能概述
`investigate` 是 Sverklo 检索引擎的旗舰工具，它在单次调用中协调多个检索信号，对查询进行全面的语义分析。根据 `src/server/prompts.ts` 中的提示工程定义：
> "Map the `feature` feature across the codebase. Use sverklo's research tools in this order: 1. Call `investigate query:"${feature}"` for a single-pass fan-out over FTS, embeddings, symbols, and refs."
资料来源：[src/server/prompts.ts:48-50]()
### 搜索流程
`investigate` 工具的工作流程设计如下：
```mermaid
graph TD
A[用户查询] --> B[全文搜索 FTS]
A --> C[向量嵌入搜索]
A --> D[BM25 关键词匹配]
A --> E[符号索引查询]
B --> F[RRF 融合排序]
C --> F
D --> F
E --> F
F --> G[结果去重与过滤]
G --> H[返回排序结果]
```
### 结果解读
`investigate` 返回的结果包含 `found_by` 标签，标识每个结果被哪些检索器命中：
- **多信号一致命中**：结果同时被多个检索器认可，具有更高置信度
- **单信号命中**：结果仅被某一检索器匹配，可能需要进一步验证
根据项目提示工程的建议："Read the `found_by` tags — results agreed on by multiple retrievers are higher-signal than single-source hits."，代理应优先关注多信号一致的结果。
资料来源：[src/server/prompts.ts:52-53]()
## context 工具：检索与上下文打包
### 设计理念
`context` 是一个"伞形"工具（umbrella tool），它将多个原子操作打包成一次调用。根据 `src/server/tools/context.ts` 的设计注释：
> "Instead of forcing the model to chain 5-8 atomic calls (overview → search → lookup → recall → ...) for common code-intelligence questions, this returns a single curated bundle in one round trip."
资料来源：[src/server/tools/context.ts:35-38]()
### 详细级别控制
`context` 工具支持三种详细级别（detail_level），用于控制返回内容的深度：
| 级别 | 内容构成 | 适用场景 |
|------|---------|---------|
| `minimal` | 概述头 + Top 3 搜索结果 + Top 2 记忆 | 快速定向、初步了解 |
| `normal` | 概述头 + Top 5 搜索结果 + Top 5 记忆 + 符号表 | 常规任务处理 |
| `full` | normal + 依赖邻居节点 | 深入架构理解 |
| `budget` | PageRank 剪枝的贪心填充 | 大型代码库下的 token 预算控制 |
资料来源：[src/server/tools/context.ts:17-26]()
### 工具输入模式
```typescript
inputSchema: {
type: "object",
properties: {
task: {
type: "string",
description: "任务描述，如 'add rate limiting to the login endpoint'"
},
detail_level: {
type: "string",
enum: ["minimal", "normal", "full"],
default: "normal"
},
scope: {
type: "string",
description: "路径前缀约束，如 'src/api/'"
},
budget: {
type: "number",
description: "PageRank 剪枝的 token 预算上限"
}
}
}
```
资料来源：[src/server/tools/context.ts:8-30]()
## PageRank 在搜索排序中的应用
### 图计算与重要性评估
Sverklo 内置了基于依赖图的 PageRank 算法，用于评估代码文件中各节点的重要性。在 `src/server/tools/wakeup.ts` 中，核心文件按 PageRank 排序呈现：
```typescript
if (f.pagerank > 0) {
parts.push(`- \`${f.path}\``);
}
```
资料来源：[src/server/tools/wakeup.ts:27-29]()
### 搜索结果增强
PageRank 分数在搜索排序中作为 boost 因子参与 RRF 融合，使得：
1. **高 PageRank 文件**：在同等相关性条件下排名更靠前
2. **依赖密集文件**：往往是核心基础设施或关键业务逻辑
3. **入口文件**：通常被其他模块引用，具有较高的传播影响力
这种设计确保代理首先关注的是代码库的核心部分，而非边缘或实验性代码。
## 社区反馈与未来演进方向
### Issue #29：ColBERT/PLAID 多向量重排序评估
社区成员 Dmitry Balabka 在 LinkedIn 上针对 Sverklo 当前的双编码器（bi-encoder）+ BM25 + PageRank 架构提出了改进建议：
> "search: evaluate ColBERT/PLAID-style multi-vector reranker against current bi-encoder + BM25 + PageRank"
资料来源：[github.com/sverklo/sverklo/issues/29]()
#### 现有架构 vs 提议方案
| 维度 | 当前架构（Bi-encoder） | 提议架构（ColBERT/PLAID） |
|------|----------------------|--------------------------|
| **向量表示** | 每个文档一个向量 | 每个 token 位置独立向量 |
| **查询匹配粒度** | 文档级 | Token 级 late interaction |
| **计算成本** | 较低 | 较高 |
| **语义精度** | 中等 | 更高（尤其是长查询） |
| **适用场景** | 短查询、常见模式 | 复杂查询、细粒度匹配 |
ColBERT（ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction）是一种 late interaction 范式，它在编码阶段保留每个 token 的向量表示，在排序阶段允许查询词与文档词的细粒度交互，弥补了双编码器在查询-document 交互上的不足。
### 评估基准与性能回归
根据 Issue #28 的记录，项目维护者建立了 90 个任务的基准测试套件，并在优化过程中持续监控性能变化：
> "That recovered P1 from 0.30 → 0.73 on the 90-task bench. But two categories regressed slightly"
资料来源：[github.com/sverklo/sverklo/issues/28]()
这表明检索引擎的优化是一个持续迭代的过程，任何架构调整都需要在基准测试上进行充分验证。
## 检索引擎配置与调优
### 工具集环境变量
Sverklo 支持通过环境变量配置搜索相关的功能集。根据 `src/server/tool-overrides.ts` 中的 `normalizeEnvSuffix` 函数：
```typescript
function normalizeEnvSuffix(name: string): string {
// "sverklo_search" -> "SEARCH"
// "sverklo_review_diff" -> "REVIEW_DIFF"
}
```
这允许用户通过 `SVERKLO_SEARCH`、`SVERKLO_RESEARCH` 等环境变量控制可用的工具集。
### 搜索记忆整合
检索引擎与记忆系统深度整合，搜索结果中会自动包含相关的项目记忆：
- **Core Memories**：项目核心不变量的记忆，始终优先展示
- **Recent Memories**：最近保存的上下文记忆，与搜索查询进行关联匹配
在 `context` 工具中，记忆召回通过 `handleRecall` 函数实现，与搜索结果共同打包返回。
## 总结
Sverklo 的检索引擎是一个精心设计的混合搜索系统，其核心特点包括：
1. **多信号融合**：通过 RRF 算法融合全文搜索、向量嵌入、BM25 和 PageRank 多种检索信号
2. **工具层次化**：提供 core、lean、research 等不同复杂度的工具集，适应不同场景需求
3. **代理友好设计**：伞形工具（如 context、investigate）减少代理的调用次数，提升效率
4. **持续演进**：社区正在评估 ColBERT/PLAID 等更先进的重排序架构，以提升复杂查询的准确性
当前 v0.29.0 版本的检索引擎已经能够很好地满足大多数代码智能搜索场景，而未来可能的多向量重排序引入将进一步提升检索精度。
---
## 索引器系统
### 相关页面
相关主题：[系统架构](#system-architecture), [存储层架构](#storage-layer)
相关源码文件
以下源码文件用于生成本页说明：
- [src/indexer/parser.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/parser.ts)
- [src/indexer/parser-tree-sitter.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/parser-tree-sitter.ts)
- [src/indexer/symbol-extractor.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/symbol-extractor.ts)
- [src/indexer/graph-builder.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/graph-builder.ts)
- [src/indexer/embedder.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/embedder.ts)
- [src/indexer/file-discovery.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/file-discovery.ts)
- [src/indexer/grammars-install.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/grammars-install.ts)
# 索引器系统
Sverklo 的索引器系统是整个代码智能平台的核心基础设施，负责对代码仓库进行深度解析，构建符号图谱、依赖关系和语义嵌入，为后续的搜索、影响分析、代码审查等功能提供数据基础。
## 系统概述
索引器系统采用模块化架构，包含以下核心子模块：
| 模块 | 职责 | 关键依赖 |
|------|------|----------|
| 文件发现 | 递归扫描仓库，识别需要索引的源文件 | chokidar, picomatch |
| 语法解析 | 解析代码生成 AST，处理字符串/注释 | tree-sitter |
| 符号提取 | 从 AST 提取函数、类、变量等符号 | symbol-extractor.ts |
| 关系构建 | 构建导入/导出依赖图 | graph-builder.ts |
| 嵌入生成 | 生成代码片段的语义向量 | onnxruntime-node |
| 文档索引 | 索引 Markdown/文档文件 | index-doc.ts |
资料来源：[package.json:14-21](https://github.com/sverklo/sverklo/blob/main/package.json)
## 核心数据流
索引过程遵循标准的 ETL 模式：文件发现 → 解析 → 提取 → 存储。
```mermaid
graph TD
A[文件发现
file-discovery] --> B[语法解析
parser]
B --> C[符号提取
symbol-extractor]
C --> D[关系构建
graph-builder]
C --> E[嵌入生成
embedder]
D --> F[(Graph Store)]
E --> G[(Vector Store)]
C --> H[(File Store)]
C --> I[(Code Store)]
```
## 文件发现模块
`file-discovery.ts` 负责递归扫描项目目录，基于语言相关的文件模式过滤出需要索引的源文件。
### 关键配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 忽略模式 | node_modules, .git, dist | 排除的目录 |
| 文件扩展名 | 根据语言动态确定 | 如 .ts, .js, .py |
模块同时支持增量更新和全量重建，通过 `chokidar` 监听文件系统变化实现实时同步。
## 语法解析器
Sverklo 支持两种解析模式以确保最大的代码覆盖率：
### 1. Tree-sitter 解析器
`parser-tree-sitter.ts` 使用 tree-sitter 进行精确的 AST 解析：
```mermaid
graph LR
A[源代码] --> B[Tree-sitter Parser]
B --> C[Parse Tree]
C --> D[游标遍历]
D --> E[节点查询]
```
**优势：**
- 高精度语法分析
- 支持 30+ 编程语言
- 准确的节点位置信息
**限制：**
- 需要预装语言 grammar
- 首次解析需要下载 Wasm 模块
资料来源：[src/indexer/parser-tree-sitter.ts:1-20](https://github.com/sverklo/sverklo/blob/main/src/indexer/parser-tree-sitter.ts)
### 2. 回退解析器
`parser.ts` 实现了一个基于正则的回退解析器，用于处理 tree-sitter 无法处理的边界情况：
- 单行 IIFE 包装器检测
- 字符串感知的括号计数
- 注释内容排除
**特殊处理案例：** 处理 lodash.js 等库的单文件 IIFE 包装结构时，精确的括号计数对于正确解析代码块边界至关重要。
资料来源：[src/indexer/parser.ts:1-50](https://github.com/sverklo/sverklo/blob/main/src/indexer/parser.ts)
## 符号提取
`symbol-extractor.ts` 从 AST 中提取结构化符号信息：
### 提取的符号类型
| 符号类型 | 示例 |
|----------|------|
| 函数/方法 | `function foo() {}` |
| 类 | `class Foo {}` |
| 接口 | `interface Foo {}` |
| 变量声明 | `const x = ...` |
| 类型别名 | `type Foo = ...` |
| 导入/导出 | `import { x } from 'y'` |
### 符号元数据结构
```typescript
interface Symbol {
id: number;
name: string;
kind: SymbolKind;
file_id: number;
scope: string;
startLine: number;
endLine: number;
signature?: string;
}
```
符号提取器同时维护符号的位置信息，用于后续的引用查找和跳转功能。
资料来源：[src/indexer/symbol-extractor.ts:1-30](https://github.com/sverklo/sverklo/blob/main/src/indexer/symbol-extractor.ts)
## 关系图构建
`graph-builder.ts` 基于导入语句构建代码依赖图：
### 图的表示
```mermaid
graph TD
A[file-a.ts] -->|imports| B[file-b.ts]
A -->|imports| C[file-c.ts]
B -->|imports| D[file-d.ts]
C -->|imports| D
```
### 核心数据结构
| 数据结构 | 用途 |
|----------|------|
| File Store | 存储文件元数据 (路径、语言、PageRank) |
| Graph Store | 存储边 (source_file_id → target_file_id) |
| Doc Edge Store | 存储文档与符号的关联 |
```typescript
interface FileRecord {
id: number;
path: string;
language: string;
pagerank: number;
lineCount: number;
}
interface GraphEdge {
source_file_id: number;
target_file_id: number;
edge_type: 'import' | 'export' | 'call';
}
```
资料来源：[src/indexer/graph-builder.ts:1-40](https://github.com/sverklo/sverklo/blob/main/src/indexer/graph-builder.ts)
## 嵌入生成
`embedder.ts` 使用 ONNX Runtime Node 生成代码片段的语义嵌入向量：
### 技术栈
| 组件 | 版本 | 用途 |
|------|------|------|
| onnxruntime-node | ^1.21.0 | 本地推理引擎 |
| 模型 | e5-mistral-7b 或类似 | 嵌入向量生成 |
### 嵌入策略
```mermaid
graph LR
A[代码块] --> B[分词]
B --> C[ONNX 模型推理]
C --> D[512维向量]
D --> E[(向量索引)]
```
**嵌入粒度：**
- 按函数/方法级别切分
- 按文件级别汇总
- 支持上下文窗口扩展
嵌入向量用于语义搜索，与 BM25 全文搜索和 PageRank 图排序结合形成混合搜索能力。
资料来源：[src/indexer/embedder.ts:1-25](https://github.com/sverklo/sverklo/blob/main/src/indexer/embedder.ts)
## Grammar 安装管理
`grammars-install.ts` 负责管理 tree-sitter 语言 grammar 的安装和更新：
### 功能清单
| 功能 | 说明 |
|------|------|
| Grammar 下载 | 从官方源下载 Wasm grammar |
| 版本锁定 | 确保 grammar 版本与解析器兼容 |
| 缓存管理 | 避免重复下载 |
| 增量更新 | 只更新新增语言的 grammar |
```typescript
interface GrammarConfig {
language: string;
grammarVersion: string;
wasmUrl: string;
}
```
资料来源：[src/indexer/grammars-install.ts:1-20](https://github.com/sverklo/sverklo/blob/main/src/indexer/grammars-install.ts)
## 存储层设计
索引器使用四个独立的存储后端：
```mermaid
graph TD
subgraph Stores
F[(File Store)]
C[(Code Store)]
G[(Graph Store)]
V[(Vector Store)]
D[(Doc Edge Store)]
end
subgraph DataFlow
F --> |文件元数据| G
C --> |符号定义| G
F --> |代码内容| V
C --> |符号引用| D
end
```
| 存储 | 索引内容 | 查询模式 |
|------|----------|----------|
| File Store | 文件路径、语言、行数、PageRank | 按 ID/路径查找 |
| Code Store | 符号定义、签名、作用域 | 按名称模糊搜索 |
| Graph Store | 文件间导入关系 | 广度优先遍历 |
| Vector Store | 代码嵌入向量 | 近似最近邻搜索 |
| Doc Edge Store | 文档与符号关联 | 按符号聚合文档 |
## 索引状态管理
索引过程维护以下状态信息：
| 状态字段 | 类型 | 说明 |
|----------|------|------|
| lastIndexed | timestamp | 最后索引时间 |
| fileCount | number | 已索引文件数 |
| language | string[] | 支持的语言列表 |
| status | 'idle' \| 'indexing' | 索引状态 |
**已知问题：** `sverklo reindex` 完成后不会更新 `registry.json` 中的 `lastIndexed` 时间戳，导致 `sverklo list` 显示的索引年龄信息不准确。
资料来源：[GitHub Issue #74](https://github.com/sverklo/sverklo/issues/74)
## 性能考量
### 增量索引
系统采用增量索引策略，仅重新索引变更的文件：
1. 文件系统监控 (chokidar)
2. 变更检测与文件分类
3. 受影响符号的级联更新
4. 图结构的增量重计算
### 并行处理
| 阶段 | 并行策略 |
|------|----------|
| 文件发现 | 单线程 (I/O 密集) |
| 解析 | 多线程池 (CPU 密集) |
| 嵌入生成 | 批处理 + ONNX 多线程 |
### Benchmark 回归监控
社区曾发现解析器的字符串/注释感知括号计数器修复后，在某些基准测试上有轻微性能回归，需要持续监控 P2/P4 相关指标。
资料来源：[GitHub Issue #28](https://github.com/sverklo/sverklo/issues/28)
## 未来增强方向
### 搜索架构演进
社区正在评估引入 ColBERT/PLAID 风格的多向量重排序器，以改进当前的 bi-encoder + BM25 + PageRank 混合搜索架构。
资料来源：[GitHub Issue #29](https://github.com/sverklo/sverklo/issues/29)
### 增量嵌入更新
当前嵌入生成是全量重算，未来计划支持基于代码变更的增量嵌入更新，减少大型项目的索引时间。
## 命令行接口
| 命令 | 功能 |
|------|------|
| `sverklo index` | 全量索引仓库 |
| `sverklo reindex` | 重建索引 |
| `sverklo status` | 显示索引状态 |
## 总结
索引器系统是 Sverklo 的数据基础设施，通过组合使用 tree-sitter AST 解析、符号提取、图关系构建和语义嵌入技术，将原始代码转换为可查询的结构化数据。模块化设计使得各组件可以独立演进，同时通过标准化的存储接口保持数据一致性。
---
## MCP工具集
### 相关页面
相关主题：[系统架构](#system-architecture), [双时态记忆系统](#memory-system), [差异审计与质量门禁](#audit-diff)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/tools/context.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/context.ts)
- [src/server/tools/critique.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/critique.ts)
- [src/server/tool-overrides.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tool-overrides.ts)
- [src/server/tools/find-references.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/find-references.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
- [src/server/tools/wakeup.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/wakeup.ts)
- [src/server/tools/review-format.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
- [src/server/tools/rename-aliases.test.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/rename-aliases.test.ts)
# MCP工具集
## 概述
MCP工具集是sverklo作为本地优先MCP（Model Context Protocol）服务器的核心里程碑，为Claude Code、Cursor、Windsurf和Codex CLI等AI编码助手提供代码智能能力。Sverklo通过MCP协议暴露一套结构化的代码索引、搜索、记忆和审查工具，使AI代理能够理解代码库结构、追踪符号依赖、评估变更影响范围，并在会话间保持持久记忆。
当前版本v0.29.0的MCP服务器实现了完整的工具注册、资源注入、提示模板和工作流编排机制。所有工具均通过MCP SDK实现，遵循JSON-RPC规范进行通信，无需API密钥或代码上传，完全本地运行。
## MCP服务器架构
### 服务端组件结构
```mermaid
graph TD
A[MCP Client
Claude Code/Cursor] --> B[MCP Server
sverklo]
B --> C[工具注册表
Tool Handlers]
B --> D[资源处理器
Resource Handlers]
B --> E[提示处理器
Prompt Handlers]
C --> C1[search]
C --> C2[lookup]
C --> C3[impact]
C --> C4[review_diff]
C --> C5[context]
C --> C6[audit]
C --> C7[remember/recall]
C --> C8[refs/investigate]
D --> D1[sverklo://context
项目上下文资源]
E --> E1[工作流模板
map-feature/pre-merge等]
```
### 服务器初始化流程
MCP服务器在`mverklo-server.ts`中通过MCP SDK初始化，核心步骤包括：
1. 创建`Server`实例，配置功能声明
2. 注册所有MCP工具处理器
3. 配置资源端点用于会话启动时的上下文注入
4. 注册提示模板用于IDE工作流
5. 启动请求处理器循环
```typescript
// 资料来源：src/server/mcp-server.ts:1-50
const server = new Server(
{
name: "sverklo",
version: "0.29.0",
},
{
capabilities: {
tools: {},
resources: {},
prompts: {},
},
instructions:
"sverklo: code intelligence for this repo. Use it for exploratory search, " +
"refactor blast-radius, dependency graphs, diff-aware review, and persistent " +
"memory across sessions.",
}
);
```
### 工具名称规范与兼容性
**v0.28.0重要变更**：MCP工具名称从`vverklo_X`格式改为不带前缀的规范格式（如`search`、`lookup`），以避免MCP客户端双重前缀问题（参见问题#71）。旧版工具名通过别名机制保持向后兼容：
```typescript
// 资料来源：src/server/tools/rename-aliases.test.ts:1-30
describe("v0.28.0 #71 — legacy tool-name alias resolution", () => {
it("exports LEGACY_TOOL_ALIASES with ≥30 entries", () => {
expect(Object.keys(LEGACY_TOOL_ALIASES).length).toBeGreaterThanOrEqual(30);
});
});
```
别名系统在首次调用时输出弃用警告，后续调用不再重复警告，避免日志污染。
## 工具分类与功能矩阵
### 核心索引工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `search` | 混合语义搜索（FTS + 向量 + BM25 + PageRank融合） | `query`, `scope?`, `limit?` | 排序后的代码块列表 |
| `lookup` | 符号定义查找 | `symbol`, `scope?` | 定义位置、类型信息、文档引用 |
| `refs` | 符号引用追踪 | `symbol`, `scope?`, `include_defs?` | 引用位置列表，含文档提及 |
| `investigate` | 单一查询扇出搜索 | `query`, `scope?` | FTS/向量/符号/引用的聚合结果 |
### 图分析工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `impact` | 变更影响半径分析 | `path`, `depth?`, `partition?` | 受影响文件列表，按依赖层级分组 |
| `deps` | 依赖图查询 | `path`, `direction?`, `depth?` | 导入/导出关系可视化 |
| `overview` | 代码库概览 | `scope?` | 文件统计、语言分布、核心文件排名 |
| `clusters` | 代码语义聚类 | `pattern?`, `scope?` | 按功能分组的相关文件集合 |
### 记忆工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `remember` | 保存决策记忆 | `content`, `category?`, `tier?` | 确认消息 |
| `recall` | 检索相关记忆 | `query`, `limit?` | 匹配的持久化记忆列表 |
| `memories` | 记忆管理列表 | `category?`, `tier?` | 按类别/层级筛选的记忆 |
### 审查工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `review_diff` | PR/MR差异审查 | `ref?`, `max_files?` | 风险评分、flagged文件、内联评论 |
| `diff_search` | 变更集中搜索 | `query`, `ref?` | 在diff范围内搜索 |
| `test_map` | 测试覆盖映射 | `path?` | 变更与测试的映射关系 |
| `verify` | 符号验证 | `symbol?` | 定义存在性检查结果 |
| `critique` | AI答案批判性评估 | `evidence_ids`, `symbols`, `claim?` | 证据时效性、hub覆盖、文档引用分析 |
### 上下文工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `context` | 上下文聚合Bundle | `task`, `detail_level?`, `scope?`, `budget?` | 一站式代码库概览、相关代码、符号表、记忆 |
| `ctx_slice` | 上下文切片提取 | `path`, `lines?` | 指定文件/行范围的代码内容 |
| `ctx_grep` | 上下文内搜索 | `pattern`, `scope?` | 匹配结果含上下文 |
| `ctx_stats` | 上下文统计 | `scope?` | 文件数、行数、语言分布 |
### 审计工具
| 工具名 | 功能描述 | 输入参数 | 输出格式 |
|--------|----------|----------|----------|
| `audit` | 代码库健康度评分 | `format?` | 多维度评分（健康/安全/依赖/测试/文档）+ 可视化报告 |
## 资源注入机制
### sverklo://context 资源
MCP服务器通过资源订阅机制在每个会话启动时自动注入项目上下文：
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as sverklo MCP Server
participant Indexer as Index Engine
Client->>Server: ListResources
Server->>Client: [sverklo://context]
Client->>Server: ReadResource(sverklo://context)
Server->>Indexer: getCore(15)
Server->>Indexer: getTopFiles(5)
Server->>Indexer: getRecentChanges()
Indexer-->>Server: 项目数据
Server-->>Client: 格式化上下文文档
```
资源内容包含三个层级：
1. **核心项目上下文（Core）**：从`memoryStore`获取`tier='core'`的记忆，通常是项目不变量
2. **核心文件列表**：按PageRank排序的前5个文件，展示代码库依赖结构
3. **近期变更摘要**：未标记为陈旧的最新记忆和变更
```typescript
// 资料来源：src/server/mcp-server.ts:50-80
const coreMemories = indexer.memoryStore.getCore(15);
if (coreMemories.length > 0) {
parts.push("## Core Project Context");
parts.push("_These are project invariants to always keep in mind:_");
for (const m of coreMemories) {
const stale = m.is_stale ? " [STALE]" : "";
parts.push(`- [${m.category}]${stale} ${m.content}`);
}
}
```
## 提示模板（Prompts）
MCP服务器通过`ListPromptsRequestSchema`和`GetPromptRequestSchema`暴露预定义工作流模板，这些模板编码了工具调用顺序，指导AI完成常见代码智能任务。
### 可用模板列表
| 模板名称 | 用途 | 必需参数 |
|----------|------|----------|
| `sverklo/map-feature` | 功能映射：入口点、符号、测试、文档 | `feature`, `scope?` |
| `sverklo/pre-merge` | 合并前审查：测试覆盖、影响分析 | `ref` |
| `sverklo/onboarding` | 新人引导：架构、核心文件、决策记忆 | 无 |
| `sverklo/architecture` | 架构分析：模块关系、数据流、设计模式 | `focus?` |
| `sverklo/debug` | 调试追踪：日志、错误处理、边界情况 | `error_type?` |
### map-feature 工作流示例
```typescript
// 资料来源：src/server/prompts.ts:1-50
build: ({ feature, scope }) => {
const scopeArg = scope ? `, scope:"${scope}"` : "";
return `Map the \`${feature}\` feature across the codebase. Use sverklo's research tools in this order:
1. Call \`investigate query:"${feature}"${scopeArg}\` for a single-pass fan-out over FTS, embeddings, symbols, and refs.
2. Pick the top 3-5 symbols from the investigation and call \`refs\` on each.
3. For the two most-referenced symbols, call \`impact\` to see blast radius.
4. Call \`overview\` to get the high-level structure.`;
}
```
## 工具预设配置
### 工具配置文件
通过`tool-overrides.ts`可以定义工具预设（profiles），组合不同工具子集以适应特定使用场景：
```typescript
// 资料来源：src/server/tool-overrides.ts:1-50
export const PROFILES = {
// 最简配置：仅核心搜索能力
minimal: ["search", "lookup", "overview", "refs", "impact"],
// 轻量配置：添加上下文和状态
lean: [
"search", "lookup", "overview", "refs", "impact",
"deps", "context", "status",
"remember", "recall", "review_diff",
],
// 研究配置：完整调查工具集
research: [
"search", "search_iterative", "investigate", "ask",
"lookup", "overview", "refs", "impact",
"deps", "concepts", "patterns", "clusters",
"verify", "critique", "ctx_slice", "ctx_grep", "ctx_stats",
],
// 审查配置：diff工具优先
review: [
"review_diff", "diff_search", "test_map",
"impact", "refs", "lookup", "search",
"investigate", "verify", "status",
],
};
```
预设通过环境变量`SVERKLO_TOOL_PROFILE`激活，控制MCP服务器向客户端广播的工具列表。
## 上下文聚合工具（context）
`context`工具是sverklo MCP工具集的"前门"，设计理念是减少AI代理为理解任务而需要的工具调用链数量。
### 设计原理
传统工作流需要AI依次调用`overview` → `search` → `lookup` → `recall`等多个原子工具。`context`工具将这些操作聚合成单次调用，返回包含以下组件的bundle：
1. **代码库概览头**：项目名、文件统计、语言分布
2. **语义相关代码**：混合搜索结果（FTS + 向量 + PageRank融合）
3. **相关符号表**：从investigation推断的核心符号
4. **匹配记忆**：recall查询结果
### Token预算控制
```typescript
// 资料来源：src/server/tools/context.ts:1-40
interface ContextToolOptions {
detail_level?: "minimal" | "normal" | "full";
scope?: string;
budget?: number; // 当设置时，启用PageRank修剪的repo map
}
```
当`budget`参数设置时，`context`返回基于PageRank贪心填充的repo map，超出token预算时自动裁剪低权重节点。这是向AI代理提供陌生代码库完整心智模型的理想方式。
## 审查与批判工具
### critique 工具
`critique`工具对AI代理的答案进行批判性评估，无需服务器端LLM调用：
```mermaid
graph LR
A[evidence_ids] --> B[验证证据时效性]
A --> C[检查符号定义存在]
A --> D[分析PageRank Hub覆盖]
A --> E[检查文档引用完整性]
B --> F[格式化的批判报告]
C --> F
D --> F
E --> F
```
```typescript
// 资料来源：src/server/tools/critique.ts:1-50
interface CritiqueData {
claim: string | null;
verify: VerifyResult[]; // 证据时效性
stale: VerifyResult[]; // 陈旧证据
moved: VerifyResult[]; // 已迁移引用
hubsCited: string[]; // 引用的Hub
missedHubs: string[]; // 未覆盖的Hub
undefinedSymbols: string[]; // 未定义符号
undocumentedSymbols: string[];// 未文档化符号
}
```
### review_diff 与 review-format
`review_diff`工具执行差异感知审查，结合启发式规则识别高风险代码模式：
```typescript
// 资料来源：src/server/tools/review-format.ts:1-30
export type RiskLevel = "critical" | "high" | "medium" | "low";
export interface InlineComment {
path: string; // 仓库相对路径
line: number; // 1-based行号
severity: string;
body: string;
}
```
输出包含结构化GitHub PR Review JSON，可直接POST到`pulls.createReview` API：
```json
{
"ref": "main..HEAD",
"max_risk": "high",
"summary": "",
"inline": [{ "path", "line", "severity", "body" }],
"high_risk_files": [{ "path", "score", "reasons" }]
}
```
## Wakeup 生成
`sverklo wakeup`命令生成简化的会话启动文档，包含：
```typescript
// 资料来源：src/server/tools/wakeup.ts:1-50
export function generateWakeup(
indexer: IndexFiles & IndexMemory,
options: { maxTokens?: number; format?: "markdown" | "plain" }
): string {
// 输出结构：
// # project-name
// fileCount files · languages
//
// ## Core files (by dependency rank)
// - `high-pagerank-file.ts`
//
// ## Project invariants
// - [category] memory-content
}
```
## 已知问题与限制
### 问题#71：MCP工具名称双重前缀
当MCP服务器注册在`"sverklo"`键下时，MCP客户端会按惯例给所有工具添加`sverklo_`前缀，导致工具名变成`sverklo_sverklo_impact`。v0.28.0通过移除工具名前缀和建立别名映射来解决此问题。
### Windows平台路径问题
MCP工具中涉及文件路径处理时，Windows路径分隔符可能导致意外行为（参见问题#20）。当前实现使用`path.split("/")`和`path.replace(/\\/g, "/")`进行规范化。
### 版本同步警告缺失
运行中的MCP服务器子进程不会自动感知npm包升级。当用户通过`npm install -g sverklo@x.x.x`升级后，已运行的MCP服务器仍使用旧二进制文件，`sverklo doctor`也不会报告版本不一致（参见问题#17）。
## 与GitHub Action集成
sverklo提供独立的GitHub Action用于PR审查：
```yaml
# 资料来源：action/README.md
- uses: sverklo/sverklo/action@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on: high # 可选：critical/high/medium/low/none
inline-comments: true # 启用内联审查评论
```
Action利用`review-format.ts`输出的结构化JSON，通过GitHub API直接发布内联评论。
## 总结
MCP工具集是sverklo实现代码智能能力的核心接口层。它通过Model Context Protocol将代码库索引、语义搜索、依赖图分析、持久记忆和差异审查等功能暴露给AI编码代理。工具设计遵循单一职责原则，同时通过`context`等聚合工具降低AI的调用复杂度。资源注入机制确保每个会话启动时AI都能获得项目上下文，而提示模板则将最佳实践工具调用序列编码为可复用的工作流。
---
## 双时态记忆系统
### 相关页面
相关主题：[检索引擎原理](#retrieval-engine), [存储层架构](#storage-layer)
相关源码文件
以下源码文件用于生成本页说明：
- [src/storage/memory-store.ts](https://github.com/sverklo/sverklo/blob/main/src/storage/memory-store.ts)
- [src/memory/import.ts](https://github.com/sverklo/sverklo/blob/main/src/memory/import.ts)
- [src/memory/export.ts](https://github.com/sverklo/sverklo/blob/main/src/memory/export.ts)
- [src/memory/prune.ts](https://github.com/sverklo/sverklo/blob/main/src/memory/prune.ts)
- [src/memory/mine-chats.ts](https://github.com/sverklo/sverklo/blob/main/src/memory/mine-chats.ts)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/server/tools/recall.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/recall.ts)
# 双时态记忆系统
## 概述
Sverklo 的双时态记忆系统（Bitemporal Memory System）是一种持久化记忆框架，旨在为编码智能体跨越多个工作会话提供上下文连续性。该系统通过维护两套独立的时间维度来追踪每条记忆的状态：
- **创建时态（Creation Temporal）**：记忆首次创建的时间，记录会话上下文
- **索引时态（Index Temporal）**：记忆被注册到工作区索引的时间，用于检索和老化管理
双时态设计使得系统能够区分"记忆何时产生"与"记忆何时被纳入工作上下文"，从而支持更精细的记忆生命周期管理和智能检索。
资料来源：[src/storage/memory-store.ts:1-50]()
## 核心数据模型
### 记忆条目结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `string` | 记忆唯一标识符 |
| `content` | `string` | 记忆内容文本 |
| `category` | `string` | 分类标签（如 architecture、decision、todo） |
| `tier` | `"core" \| "normal"` | 层级：core 表示项目不变式，normal 为普通记忆 |
| `is_stale` | `boolean` | 是否过期标记 |
| `created_at` | `number` | 创建时间戳（毫秒） |
| `session_id` | `string` | 创建时的会话标识 |
| `repo_path` | `string` | 关联的仓库路径 |
| `tags` | `string[]` | 可选标签数组 |
### 双时态时间戳
| 时间戳字段 | 含义 | 用途 |
|-----------|------|------|
| `created_at` | 创建时态 | 追踪记忆最初产生的工作会话 |
| `last_accessed` | 访问时态 | 追踪最近一次被检索的时间 |
资料来源：[src/storage/memory-store.ts:20-45]()
## 记忆存储架构
### MemoryStore 类
`MemoryStore` 是核心存储抽象，提供记忆的增删改查和生命周期管理接口。
```typescript
class MemoryStore {
// 持久化读写
getAll(limit?: number): Memory[]
getCore(limit: number): Memory[]
add(memory: Omit): Memory
remove(id: string): void
// 访问追踪
touch(id: string): void
// 老化管理
markStale(id: string): void
unmarkStale(id: string): void
// 导入导出
import(memory: Memory): void
export(): Memory[]
}
```
资料来源：[src/storage/memory-store.ts:50-120]()
### 向量嵌入存储
`MemoryEmbeddingStore` 负责记忆的语义向量表示，支持基于相似度的检索：
```typescript
class MemoryEmbeddingStore {
// 按语义相似度检索
search(query: string, limit: number): Memory[]
// 嵌入管理
addEmbedding(memoryId: string, embedding: number[]): void
removeEmbedding(memoryId: string): void
}
```
资料来源：[src/storage/memory-embedding-store.ts:1-60]()
## 记忆生命周期
```mermaid
graph TD
A[会话开始] --> B[加载核心记忆]
B --> C[Agent 工作]
C --> D{是否有新决策?}
D -->|是| E[remember 工具保存]
E --> F[标记层级和分类]
F --> G[更新创建时态]
G --> H[持久化到存储]
D -->|否| I[继续工作]
I --> J{需要检索记忆?}
J -->|是| K[recall 工具查询]
K --> L[更新访问时态]
L --> M[返回记忆内容]
J --> N[会话结束]
M --> N
```
### 创建流程
1. Agent 通过 `remember` 工具提交记忆内容
2. 系统记录 `created_at` 和 `session_id` 作为创建时态
3. 根据内容自动推断或显式指定 `category`
4. 持久化到本地存储
### 访问追踪
每次通过 `recall` 工具检索记忆时，系统自动更新 `last_accessed` 时间戳：
```typescript
touch(id: string): void {
const memory = this.get(id);
if (memory) {
memory.last_accessed = Date.now();
this.persist();
}
}
```
资料来源：[src/storage/memory-store.ts:80-90]()
## 导入与导出
### 导入模块
`import.ts` 实现了从外部源导入记忆的能力，支持跨工作区迁移和全局记忆同步。
```typescript
export async function importExistingMemories(
sourcePath: string,
targetRepo: string
): Promise
```
关键特性：
- 扫描源目录下的现有记忆文件
- 验证记忆内容有效性
- 重新映射 `repo_path` 到目标仓库
- 合并去重（基于内容哈希）
资料来源：[src/memory/import.ts:1-80]()
### 导出模块
`export.ts` 支持将记忆导出为可移植格式：
```typescript
export function exportMemories(
repoPath: string,
options?: { includeStale?: boolean; category?: string }
): Memory[]
```
导出格式为 JSON Lines（.jsonl），每行一条记忆，便于版本控制和迁移。
资料来源：[src/memory/export.ts:1-50]()
### 全局记忆工作流
社区 issue #72 提出了对全局记忆导入的需求，允许用户一次性配置后，在每个新项目只注册即可复用：
```
用户配置 (一次性)
↓
sverklo init --global
↓
importExistingMemories() 扫描机器级记忆
↓
每个新项目注册
↓
sverklo register .
↓
自动继承全局记忆上下文
```
资料来源：[src/memory/import.ts:20-40]()
社区反馈：[Issue #72](https://github.com/sverklo/sverklo/issues/72)
## 记忆老化与修剪
### 老化机制
每条记忆可被标记为过期（`is_stale`），典型场景包括：
- 相关代码已被删除或重构
- 决策已被撤销
- 技术栈已升级
```typescript
markStale(id: string): void {
const memory = this.get(id);
if (memory) {
memory.is_stale = true;
this.persist();
}
}
```
资料来源：[src/storage/memory-store.ts:95-105]()
### 自动修剪
`prune.ts` 实现了记忆的自动清理策略：
| 策略 | 触发条件 | 行为 |
|------|----------|------|
| 过期清理 | 记忆被标记为 stale | 保留但降低检索权重 |
| 访问老化 | `last_accessed` 超过阈值 | 可选降级或删除 |
| 类别清理 | 特定分类记忆超限 | 按 LRU 淘汰 |
资料来源：[src/memory/prune.ts:1-60]()
## 会话上下文注入
### 核心记忆自动注入
在每次会话启动时，服务器通过 MCP 资源接口自动注入项目核心记忆：
```typescript
const coreMemories = indexer.memoryStore.getCore(15);
if (coreMemories.length > 0) {
parts.push("## Core Project Context");
parts.push("_These are project invariants to always keep in mind:_");
for (const m of coreMemories) {
const stale = m.is_stale ? " [STALE]" : "";
parts.push(`- [${m.category}]${stale} ${m.content}`);
}
}
```
资料来源：[src/server/mcp-server.ts:80-100]()
### 唤醒摘要生成
`generateWakeup` 函数生成会话起始的上下文摘要：
```typescript
export function generateWakeup(
indexer: IndexFiles & IndexMemory,
options: { maxTokens?: number; format?: "markdown" | "plain" } = {}
): string
```
输出包含：
- 项目基本信息（名称、文件数、语言）
- 核心文件列表（按依赖排名）
- 项目不变式（核心记忆）
- 最近活动记录
资料来源：[src/server/tools/wakeup.ts:30-80]()
## 聊天挖掘
`mine-chats.ts` 实现了从对话历史中自动提取记忆的能力：
```typescript
export async function mineChatMemories(
chatHistory: ChatMessage[],
options?: { minConfidence?: number }
): Promise
```
提取的记忆类型包括：
- 架构决策（"我们决定使用 X 而不是 Y"）
- 技术债务记录
- 已知问题说明
- TODO 和后续任务
资料来源：[src/memory/mine-chats.ts:1-50]()
## MCP 工具接口
### remember 工具
保存新的记忆条目：
```typescript
{
name: "remember",
description: "Save an important decision, context, or note...",
inputSchema: {
type: "object",
properties: {
content: { type: "string" },
category: { type: "string" },
tier: { type: "string", enum: ["core", "normal"] }
}
}
}
```
### recall 工具
检索相关记忆：
```typescript
{
name: "recall",
description: "Search saved memories...",
inputSchema: {
type: "object",
properties: {
query: { type: "string" },
category: { type: "string" },
includeStale: { type: "boolean" }
}
}
}
```
资料来源：[src/server/tools/recall.ts:1-100]()
## 模式配置
不同工作模式下的记忆工具可用性：
| 模式 | remember | recall | 适用场景 |
|------|----------|--------|----------|
| minimal | ✅ | ❌ | 最小化上下文 |
| lean | ✅ | ✅ | 常规编码 |
| research | ✅ | ✅ | 深度调研 |
| review | ✅ | ✅ | 代码审查 |
资料来源：[src/modes.ts:1-50]()
## 最佳实践
### 核心记忆 vs 普通记忆
- **core（核心）**：项目级不变式，如架构决策、重要约束、品牌规范
- **normal（普通）**：会话级上下文，如特定 bug 的解决方案
### 避免记忆过时
- 代码重构后及时标记相关记忆为 stale
- 使用 `unmarkStale` 工具在验证记忆仍有效时恢复
- 定期运行修剪脚本清理过期记忆
### 跨仓库记忆管理
- 使用全局配置建立机器级记忆库
- 项目级记忆仅存储仓库特有信息
- 利用导入导出功能在项目间迁移集体智慧
## 相关文档
- [CLI 参考 - sverklo init](../cli/init.md)
- [CLI 参考 - sverklo register](../cli/register.md)
- [MCP 服务器架构](./mcp-server.md)
- [混合搜索系统](./search/hybrid-search.md)
---
## 差异审计与质量门禁
### 相关页面
相关主题：[MCP工具集](#mcp-tools), [系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/audit-html.ts](https://github.com/sverklo/sverklo/blob/main/src/server/audit-html.ts)
- [src/server/audit-obsidian.ts](https://github.com/sverklo/sverklo/blob/main/src/server/audit-obsidian.ts)
- [src/server/tools/review-format.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/review-format.ts)
- [src/server/tools/critique.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/critique.ts)
- [src/server/tools/context.ts](https://github.com/sverklo/sverklo/blob/main/src/server/tools/context.ts)
- [src/server/prompts.ts](https://github.com/sverklo/sverklo/blob/main/src/server/prompts.ts)
# 差异审计与质量门禁
## 概述
差异审计与质量门禁是 sverklo 的核心功能模块，用于在代码变更（diff）中实施结构化质量检查。这些检查包括循环依赖检测、扇入/扇出分析、模块边界验证，并通过风险评分系统帮助开发团队在代码审查阶段发现潜在问题。
sverklo 提供两种差异审计输出格式：
| 输出格式 | 用途 | 特点 |
|---------|------|------|
| HTML 报告 | 独立分享、存档 | 暗色主题、SEO 元数据、社交分享优化 |
| Obsidian 笔记 | Obsidian 知识库集成 | Wikilink 可点击导航、依赖关系可视化 |
资料来源：[src/server/audit-html.ts:1-20]()
## 核心架构
差异审计系统由以下子模块组成：
```mermaid
graph TD
A[Diff 输入] --> B[审计分析引擎]
B --> C[循环依赖检测]
B --> D[扇入/扇出分析]
B --> E[模块边界检查]
B --> F[风险评分]
C --> G[报告生成器]
D --> G
E --> G
F --> G
G --> H[HTML/Obsidian 输出]
```
### 审计维度
sverklo 的代码质量审计从多个维度评估代码库健康状况：
- **循环依赖**：检测模块间的环形依赖关系，防止紧耦合导致的维护困难
- **扇入分析**：识别高被依赖的文件（核心模块），评估变更影响范围
- **边界完整性**：验证模块边界是否被尊重，防止不当的跨层调用
资料来源：[src/server/audit-html.ts:30-45]()
## HTML 审计报告生成
`audit-html.ts` 负责生成自包含的 HTML 审计报告，采用与 sverklo.com 品牌一致的暗色主题。
### 项目名称清理
报告生成器会自动清理项目名称，移除临时目录前缀（如 `report-`、`regen-`、`rpt-`、`final-`、`v12-`、`bench-`），防止基准测试目录名称泄露到发布的报告中：
```typescript
const displayName = cleanProjectName(projectName, projectPath);
```
资料来源：[src/server/audit-html.ts:11-18]()
### 评分等级
审计报告使用颜色编码的等级系统：
| 等级 | 颜色 | 含义 |
|-----|------|------|
| A | `#4c1` (绿色) | 优秀 |
| B | `#97...` | 良好 |
| C/D | 对应色调 | 需要改进 |
资料来源：[src/server/audit-html.ts:100-105]()
### SEO 与社交分享
生成的 HTML 包含完整的 Open Graph 和 Twitter Card 元数据，便于在社交平台分享：
```html
```
资料来源：[src/server/audit-html.ts:80-95]()
## Obsidian 集成报告
`audit-obsidian.ts` 生成与 Obsidian 兼容的 Markdown 格式报告，支持 `[[wikilinks]]` 实现依赖关系可点击导航。
### 构建流程
```mermaid
graph LR
A[索引数据] --> B[文件映射表]
B --> C[导入关系图]
C --> D[Wikilink 生成]
D --> E[单文件输出]
```
报告构建步骤：
1. 从索引数据获取所有文件和边
2. 构建 `id → path` 映射表
3. 构建 `imports` 和 `importedBy` 双向关系图
4. 生成包含 wikilink 的 Markdown
资料来源：[src/server/audit-obsidian.ts:1-40]()
## GitHub PR 审查集成
### 结构化审查载荷
`sverklo` 支持输出符合 GitHub PR Review API 的结构化 JSON，用于在 Pull Request 上发布内联审查评论：
```typescript
interface GitHubReviewPayload {
ref: string; // e.g., "main..HEAD"
max_risk: RiskLevel; // critical | high | medium | low
summary: string; // Markdown body for sticky comment
inline: InlineComment[];
high_risk_files: HighRiskFile[];
}
```
资料来源：[src/server/tools/review-format.ts:1-30]()
### 内联评论格式
每条内联评论包含：
| 字段 | 类型 | 说明 |
|-----|------|------|
| `path` | string | 仓库相对路径 |
| `line` | number | 1-based 行号 |
| `severity` | string | 严重程度 |
| `body` | string | 评论内容 |
资料来源：[src/server/tools/review-format.ts:32-40]()
## 风险评分系统
### 风险等级
| 等级 | 使用场景 |
|-----|---------|
| `critical` | 立即阻止合并 |
| `high` | 强烈建议修复后合并 |
| `medium` | 建议关注 |
| `low` | 可忽略 |
| `none` | 仅记录，不阻止 |
### 启发式检测
sverklo 使用启发式规则检测代码中的风险模式：
- 未捕获的流调用（如 `stream.on('data')` 无错误处理）
- 过于复杂的函数
- 违反模块边界的高扇入文件
资料来源：[src/server/tools/review-format.ts:50-80]()
## 批判性分析工具
`critique` 工具提供更深入的代码审查视角：
### 验证流程
1. **符号追踪**：验证声称引用的符号是否真实存在
2. **过时检查**：标记已被删除但仍被引用的符号
3. **迁移检测**：识别已移动到其他路径的符号
4. **文档覆盖**：检查符号是否在 `.md`/`.markdown`/`.mdx` 文件中被引用
```typescript
const docCited = verify.some(
(v) =>
v.file &&
(v.file.endsWith(".md") ||
v.file.endsWith(".markdown") ||
v.file.endsWith(".mdx"))
);
```
资料来源：[src/server/tools/critique.ts:1-30]()
### 未定义符号检测
```mermaid
graph TD
A[引用符号] --> B{符号存在?}
B -->|是| C[检查文档]
B -->|否| D[标记为未定义]
C --> E{有文档引用?}
E -->|是| F[正常]
E -->|否| G[标记为无文档]
```
资料来源：[src/server/tools/critique.ts:35-50]()
## 上下文感知审计
### 预算感知的上下文检索
`context` 工具支持按 Token 预算返回精简的审计上下文：
| 参数 | 说明 |
|-----|------|
| `budget` | 最大 Token 数，使用 PageRank 贪心填充 |
| `detail_level` | minimal/normal/full |
| `scope` | 路径前缀过滤 |
```typescript
description:
"PASS `budget` for a PageRank-pruned repo map fit to a token budget — " +
"the ideal way to give an agent a complete mental model of an unfamiliar codebase"
```
资料来源：[src/server/tools/context.ts:1-35]()
## 预定义工作流
### 审查配置
`tool-overrides.ts` 定义了针对不同场景的工具配置：
| 配置 | 工具集 | 适用场景 |
|-----|-------|---------|
| `core` | search, lookup, overview, refs, impact | 轻量级搜索 |
| `nav` | core + deps, context | 导航探索 |
| `lean` | nav + remember, recall, review_diff | 记忆增强 |
| `review` | review_diff, diff_search, test_map + impact | PR 审查 |
| `research` | 全套调查工具 | 深度研究 |
资料来源：[src/server/tool-overrides.ts:1-60]()
### 审查提示模板
```typescript
review: [
"review_diff",
"diff_search",
"test_map",
"impact",
"refs",
"lookup",
"search",
"investigate",
"verify",
"status",
]
```
资料来源：[src/server/tool-overrides.ts:25-35]()
## GitHub Actions 集成
### Action 配置
```yaml
name: Sverklo Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: sverklo/sverklo/action@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on: high
inline-comments: true
```
### Action 参数
| 参数 | 默认值 | 说明 |
|-----|-------|------|
| `github-token` | `${{ github.token }}` | GitHub 认证令牌 |
| `fail-on` | `none` | 风险阈值阻止合并 |
| `ref` | auto | Git 引用范围 |
| `max-files` | `25` | 最大审查文件数 |
| `inline-comments` | `true` | 启用内联评论 |
资料来源：[action/README.md:1-40]()
## 环境变量配置
### 工具覆盖
| 环境变量 | 作用 |
|---------|------|
| `SVERKLO_TOOL__DESCRIPTION` | 覆盖工具描述文本 |
| `SVERKLO_DISABLED_TOOLS` | 逗号分隔的禁用工具列表 |
| `SVERKLO_PROFILE` | 预定义工具配置 (core/nav/lean/full) |
```typescript
// 示例：禁用记忆工具
SVERKLO_DISABLED_TOOLS=remember,recall
// 示例：使用轻量配置
SVERKLO_PROFILE=lean
```
资料来源：[src/server/tool-overrides.ts:60-90]()
## 输出示例
### 健康评分输出
```
# 审计报告 — my-project
健康分数: 78/100
维度评估:
[ A ] 循环依赖: 无检测到问题
[ B ] 扇入分析: 2 个高扇入文件需关注
[ A ] 模块边界: 边界完整
```
### 差异审查评论
GitHub PR 上发布的评论结构：
```
## 🔍 代码审查摘要
**最大风险等级**: high
### 高风险文件
| 文件 | 风险评分 | 原因 |
|-----|---------|------|
| src/auth/manager.ts | 8.5 | 扇入=47, 跨层调用 |
| lib/stream-utils.ts | 7.2 | 未捕获错误处理 |
### 内联评论
- `src/auth/manager.ts:142` - 缺少错误边界
```
## 相关资源
- [GitHub Action 文档](https://github.com/sverklo/sverklo/tree/main/action)
- [差异审查工具](src/server/tools/review-diff.ts)
- [差异启发式规则](src/server/tools/diff-heuristics.ts)
- [批判性分析](src/server/tools/critique.ts)
---
## 存储层架构
### 相关页面
相关主题：[系统架构](#system-architecture), [双时态记忆系统](#memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/indexer/index-files.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-files.ts)
- [src/indexer/index-code.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-code.ts)
- [src/indexer/index-graph.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-graph.ts)
- [src/indexer/index-memory.ts](https://github.com/sverklo/sverklo/blob/main/src/indexer/index-memory.ts)
- [src/server/mcp-server.ts](https://github.com/sverklo/sverklo/blob/main/src/server/mcp-server.ts)
- [src/search/hybrid-search.ts](https://github.com/sverklo/sverklo/blob/main/src/search/hybrid-search.ts)
# 存储层架构
## 概述
Sverklo 的存储层采用多存储组件分离架构，通过统一的索引器接口（Indexer）聚合文件存储、代码存储、图存储和内存存储四个核心存储组件。这种设计实现了关注点分离，使每种数据类型都能采用最适合的存储策略。
所有存储组件均支持 JSON 文件持久化，存储位置默认为 `~/.sverklo/` 目录下的各子目录中。
## 核心组件
### 1. 文件存储 (IndexFiles / FileStore)
负责管理代码库的文件元数据，是整个索引系统的基础。
| 方法 | 说明 |
|------|------|
| `getAll()` | 获取所有文件记录 |
| `getById(id)` | 根据文件 ID 查询 |
| `getByPath(path)` | 根据文件路径查询 |
| `getByLanguage(lang)` | 按编程语言筛选文件 |
文件记录包含以下核心字段：
- `id`: 文件唯一标识符
- `path`: 相对于代码库根目录的文件路径
- `language`: 编程语言类型
- `size`: 文件大小（字节）
- `pagerank`: PageRank 分数，用于衡量文件在依赖图中的重要性
- `chunk_count`: 该文件的代码块数量
```mermaid
graph LR
A[代码库] --> B[index-files.ts]
B --> C[FileStore]
C --> D[files.json]
C --> E[file-lookup.json]
```
资料来源：[src/indexer/index-files.ts:1-50]()
### 2. 代码存储 (IndexCode)
代码存储负责管理代码块（Chunk）和符号信息，为语义搜索和符号查找提供数据基础。
**代码块 (CodeChunk)** 是代码分析的最小单元，通常对应函数、类或模块级别的代码片段。每个代码块包含：
| 字段 | 说明 |
|------|------|
| `file_id` | 所属文件的 ID |
| `path` | 文件路径 |
| `symbol` | 关联的符号名称（如函数名） |
| `start_line` | 代码块起始行号 |
| `end_line` | 代码块结束行号 |
| `content` | 代码内容 |
| `lang` | 编程语言 |
**符号表 (SymbolTable)** 记录代码中定义的标识符及其元信息：
```typescript
interface SymbolRecord {
name: string; // 符号名称
file_id: number; // 定义所在文件
kind: string; // 符号类型：function, class, const, etc.
line: number; // 定义行号
signature?: string; // 函数签名
}
```
资料来源：[src/indexer/index-code.ts:1-80]()
### 3. 图存储 (IndexGraph / GraphStore)
依赖图存储是 sverklo 架构的核心创新之一，用于支持影响分析（Impact Analysis）和 PageRank 计算。
图结构包含两种边：
| 边类型 | 说明 | 用途 |
|--------|------|------|
| `import` | 导入依赖关系 | 分析模块间的依赖方向 |
| `call` | 函数调用关系 | 追踪代码执行路径 |
| `reference` | 符号引用关系 | 定位符号使用位置 |
```mermaid
graph TD
A[File A] -->|import| B[File B]
B -->|call| C[Function foo]
C -->|reference| D[Symbol bar]
E[File D] -->|import| B
```
GraphStore 提供以下查询能力：
- `getAll()`: 获取所有边
- `getBySource(fileId)`: 获取某文件的所有出边
- `getByTarget(fileId)`: 获取指向某文件的所有入边
- `getNeighbors(fileId)`: 获取直接相连的节点
资料来源：[src/indexer/index-graph.ts:1-60]()
### 4. 内存存储 (IndexMemory / MemoryStore)
内存存储实现 sverklo 的持久化记忆功能，支持在会话之间保存上下文和决策。
**记忆层级：**
| 层级 | 说明 | 用途 |
|------|------|------|
| `core` | 核心项目不变式 | 会话开始时自动注入 |
| `default` | 普通记忆 | 按相关度检索 |
| `stale` | 过期标记的记忆 | 需要更新时标记 |
记忆记录结构：
```typescript
interface MemoryRecord {
id: string; // 记忆唯一标识
content: string; // 记忆内容
category: string; // 分类标签
tier: string; // 存储层级
is_stale: boolean; // 是否过期
created_at: string; // 创建时间
updated_at: string; // 更新时间
}
```
记忆存储支持：
- `getCore(limit)`: 获取核心记忆
- `getAll(limit)`: 获取最近记忆
- `search(query)`: 语义搜索记忆
- `add(memory)`: 添加新记忆
- `markStale(id)`: 标记记忆为过期
资料来源：[src/indexer/index-memory.ts:1-70]()
### 5. 文档边存储 (DocEdgeStore)
文档边存储追踪代码符号与文档文件之间的关联关系，支持"Doc mentions"功能。
```typescript
interface DocEdge {
doc_file_path: string; // 文档文件路径
symbol: string; // 关联的符号
doc_breadcrumb?: string; // 文档内位置
edge_kind: string; // 边类型
confidence: number; // 匹配置信度
}
```
关键方法：`getBySymbol(symbol, limit)` - 获取符号在文档中的所有引用。
资料来源：[src/server/tools/find-references.ts:1-40]()
## 统一索引器接口
Indexer 是四个存储组件的统一接口，定义如下：
```typescript
type Indexer = IndexFiles & IndexCode & IndexGraph & IndexMemory;
```
该接口被 MCP 服务器和所有工具处理器使用，确保数据访问的一致性。
```mermaid
graph TB
subgraph Indexer
A[FileStore]
B[CodeStore]
C[GraphStore]
D[MemoryStore]
end
E[MCP Server] --> F[handleSearch]
E --> G[handleLookup]
E --> H[handleImpact]
E --> I[handleRecall]
F -.->|uses| A & B
G -.->|uses| B & C
H -.->|uses| C
I -.->|uses| D
```
资料来源：[src/server/mcp-server.ts:1-100]()
## 持久化策略
### 存储位置
| 存储类型 | 文件路径 | 格式 |
|----------|----------|------|
| 文件元数据 | `~/.sverklo/data/{project}/files.json` | JSON |
| 代码块 | `~/.sverklo/data/{project}/chunks.json` | JSON |
| 依赖图 | `~/.sverklo/data/{project}/graph.json` | JSON |
| 记忆 | `~/.sverklo/data/{project}/memory.json` | JSON |
| 注册表 | `~/.sverklo/registry.json` | JSON |
### 索引状态追踪
索引器通过 `getStatus()` 方法返回项目的索引状态：
```typescript
interface IndexStatus {
projectName: string;
projectPath: string;
fileCount: number;
languages: string[];
lastIndexed?: string;
}
```
> ⚠️ **已知问题**：`sverklo reindex` 完成后不会更新 `registry.json` 中的 `lastIndexed` 时间戳，导致 `sverklo list` 显示的索引年龄信息可能过期。
> 相关 Issue: [#74](https://github.com/sverklo/sverklo/issues/74)
资料来源：[src/server/tools/wakeup.ts:1-50]()
## 搜索与检索
### 混合搜索 (Hybrid Search)
sverklo 采用混合搜索策略，结合多种检索信号：
| 检索信号 | 权重 | 说明 |
|----------|------|------|
| BM25 | ~0.3 | 关键词精确匹配 |
| 向量相似度 | ~0.5 | 语义相似性 |
| PageRank | ~0.2 | 基于依赖图的重要性 |
这种设计源于社区讨论——当前系统使用双编码器（bi-encoder）+ BM25 + PageRank 架构，未来可能评估 ColBERT/PLAID 风格的多向量重排序方案。
> 💬 **社区讨论**：Issue [#29](https://github.com/sverklo/sverklo/issues/29) 讨论了评估多向量重排序器的可能性。
资料来源：[src/search/hybrid-search.ts:1-50]()
### 搜索结果排序
使用 Reciprocal Rank Fusion (RRF) 算法融合多路检索结果：
```
RRF_score(d) = Σ 1 / (k + rank_i(d))
```
其中 `k` 为平滑因子（通常为 60），`rank_i(d)` 为第 i 路检索中文档 d 的排名。
## 与 MCP 工具的集成
所有 MCP 工具通过统一的 Indexer 接口访问存储层：
| 工具 | 主要存储依赖 | 功能 |
|------|-------------|------|
| `search` | FileStore, CodeStore | 语义+关键词搜索 |
| `lookup` | CodeStore | 符号详情查询 |
| `refs` | CodeStore, DocEdgeStore | 符号引用查找 |
| `impact` | GraphStore | 影响范围分析 |
| `overview` | FileStore, GraphStore | 项目概览 |
| `context` | 所有存储 | 上下文打包 |
| `recall` | MemoryStore | 记忆检索 |
| `remember` | MemoryStore | 记忆保存 |
| `critique` | CodeStore, DocEdgeStore | 代码审查批评 |
| `wakeup` | FileStore, MemoryStore | 会话初始化 |
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant Indexer as Indexer
participant Stores as File/Code/Graph/Memory
Client->>Server: tool_call: search
Server->>Indexer: hybridSearch(query)
Indexer->>Stores: multi-source query
Stores-->>Indexer: ranked results
Indexer-->>Server: aggregated results
Server-->>Client: tool response
```
资料来源：[src/server/mcp-server.ts:50-150]()
## 工具预设配置
存储层工具的可用性可通过工具预设（Tool Presets）控制：
```typescript
const TOOL_PRESETS = {
// 最小化配置
lean: ["search", "lookup", "overview", "refs", "impact", ...],
// 研究/代码分析
research: ["search", "investigate", "ask", "lookup", "refs", ...],
// PR 审查
review: ["review_diff", "diff_search", "test_map", "impact", ...],
};
```
这些预设通过环境变量 `SVERKLO_TOOLS` 选择，控制哪些存储组件需要被激活。
资料来源：[src/server/tool-overrides.ts:1-80]()
## 性能考量
### 内存占用
- FileStore：每文件约 200-500 字节
- GraphStore：每边约 50 字节（无向图）
- CodeStore：与代码库大小成正比
- MemoryStore：通常较小（< 1MB）
### 索引时间
| 代码库规模 | 预估索引时间 |
|-----------|-------------|
| 小型（< 500 文件） | < 5 秒 |
| 中型（500-5000 文件） | 5-30 秒 |
| 大型（> 5000 文件） | 30 秒 - 5 分钟 |
### 已知性能问题
> ⚠️ **回归问题**：Issue [#28](https://github.com/sverklo/sverklo/issues/28) 记录了修复解析器 brace-counter 后出现的 P2/P4 性能回归。
相关修复已通过 jcodemunch-mcp v1.80.9 版本处理 lodash.js 的 IIFE 包装问题，并新增 lodash 4.17.21 作为第三测试数据集。
## 扩展存储层
如需添加新的存储组件：
1. 创建新文件 `src/indexer/index-{name}.ts`
2. 实现相应的接口（如 `Index{Name}`）
3. 在 `src/indexer/index.ts` 中导出新组件
4. 更新 `Indexer` 类型联合
5. 在需要的地方注入新的存储依赖
```typescript
// 示例：新增 PatternStore
export interface IndexPatterns {
patternStore: PatternStore;
}
---
---
## Doramagic 踩坑日志
项目：sverklo/sverklo
摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 需要 API Key 或环境变量。
## 1. 配置坑 · 需要 API Key 或环境变量
- 严重度：high
- 证据强度：source_linked
- 发现：项目说明中出现 API Key / 环境变量相关需求。
- 对用户的影响：用户必须准备账号、额度或密钥；密钥配置错误会导致运行失败或泄漏风险。
- 建议检查：提取必需 env 列表，确认是否有最小无密钥试用路径。
- 防护动作：页面必须前置密钥/账号依赖，不能把需要密钥的项目包装成零配置。
- 证据：packet_text.keyword_scan | github_repo:1203034717 | https://github.com/sverklo/sverklo | matched api key / env var keyword
## 2. 安装坑 · 来源证据：MCP tool names double-prefixed (sverklo_sverklo_*) when server registered under 'sverklo' key
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP tool names double-prefixed (sverklo_sverklo_*) when server registered under 'sverklo' key
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7a50e3a046d2438db185ba21d580ec9e | https://github.com/sverklo/sverklo/issues/71 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Only ~49% of chunks receive embeddings, with no diagnostic explaining skipped chunks
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Only ~49% of chunks receive embeddings, with no diagnostic explaining skipped chunks
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_13e1bc9ab7fa41a0866eb6c4f814875c | https://github.com/sverklo/sverklo/issues/60 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：Semantic search observability: results always report `method: "fts"` and vector contribution is opaque
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Semantic search observability: results always report `method: "fts"` and vector contribution is opaque
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a8bdc3779b264243b8362d6e57096e25 | https://github.com/sverklo/sverklo/issues/61 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：`reindex --force` reports success after EBUSY and appears to reuse stale index on Windows
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`reindex --force` reports success after EBUSY and appears to reuse stale index on Windows
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c0c1f6a71a764af596178de506d0b2c3 | https://github.com/sverklo/sverklo/issues/58 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：fingerprintOf is defined but never called — provider-change auto-rebuild is unwired
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fingerprintOf is defined but never called — provider-change auto-rebuild is unwired
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6be83aacd98c4e3abb6ae6361bf81940 | https://github.com/sverklo/sverklo/issues/69 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：sverklo init --global: one-time setup with memory import, skip per-project boilerplate
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：sverklo init --global: one-time setup with memory import, skip per-project boilerplate
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fc3cc34d92454d5a92ab4a196b178799 | https://github.com/sverklo/sverklo/issues/72 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：sverklo reindex does not update registry.json lastIndexed timestamp
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：sverklo reindex does not update registry.json lastIndexed timestamp
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bf329d5553724c3281773c6aee96cae5 | https://github.com/sverklo/sverklo/issues/74 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：sverklo unregister should accept --by-path for agent-driven worktree teardown
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：sverklo unregister should accept --by-path for agent-driven worktree teardown
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_42920ecfbbc54f4f8b207e386dfc9ebd | https://github.com/sverklo/sverklo/issues/73 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 10. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1203034717 | https://github.com/sverklo/sverklo | host_targets=mcp_host, claude, claude_code, cursor
## 11. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1203034717 | https://github.com/sverklo/sverklo | README/documentation is current enough for a first validation pass.
## 12. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | last_activity_observed missing
## 13. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1203034717 | https://github.com/sverklo/sverklo | no_demo; severity=medium
## 14. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1203034717 | https://github.com/sverklo/sverklo | no_demo; severity=medium
## 15. 安全/权限坑 · 来源证据：Embedding vectors stored at 384 dimensions despite 1024-dim Ollama/custom ONNX config
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Embedding vectors stored at 384 dimensions despite 1024-dim Ollama/custom ONNX config
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6256d97c525b460c92ca9c7c5c3d6e70 | https://github.com/sverklo/sverklo/issues/59 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 16. 安全/权限坑 · 来源证据：MCP still failing on Windows in v0.23.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP still failing on Windows in v0.23.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1c794119f13c4355bc54d0cab37b3cf9 | https://github.com/sverklo/sverklo/issues/53 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 17. 安全/权限坑 · 来源证据：v0.25.1: Ollama reindex still stores 384d vectors despite 1024d config; Windows index lock may still persist after Clau…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.25.1: Ollama reindex still stores 384d vectors despite 1024d config; Windows index lock may still persist after Claude Code exit
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_690412bdd0374be1b2850ff4124171fd | https://github.com/sverklo/sverklo/issues/66 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 18. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | issue_or_pr_quality=unknown
## 19. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | release_recency=unknown