概述

Sverklo是一款面向代码代理（coding agents）的本地优先仓库记忆工具，通过Model Context Protocol（MCP）为Claude Code、Cursor、Windsurf和Codex CLI等主流AI编码工具提供代码智能服务。

Sverklo的核心价值在于解决AI编码代理在大型代码仓库中"上下文缺失"的问题——它为代理提供符号图谱、影响范围分析、差异感知审查和跨会话持久记忆能力，使其能够理解代码结构、评估变更风险、记住设计决策。

资料来源：package.json:1-40

核心功能

混合检索引擎

Sverklo采用三层混合检索架构，结合多种召回信号来提高搜索准确性：

1. BM25关键词检索 - 基于词频的稀疏检索，处理精确术语匹配
2. ONNX本地向量嵌入 - 使用本地运行的神经网络模型生成语义向量，支持语义相似度搜索
3. PageRank图排序 - 基于代码依赖关系图计算文件重要性，高PageRank的文件在检索中享有更高权重

这三种信号通过倒数排名融合（Reciprocal Rank Fusion）进行合并，优先展示多个检索器一致认可的高质量结果。

资料来源：package.json:25

持久记忆系统

Sverklo的记忆系统允许开发者和代理在代码仓库中保存跨会话的设计决策、架构笔记和开发约定。记忆分为不同的优先级层级（core/invariant等），核心项目上下文可在每次会话开始时自动注入。

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

工具集概览

Sverklo提供37个MCP工具，按功能分为以下类别：

核心工具详解

#### search - 语义搜索

Sverklo的首选搜索工具，融合BM25+向量+PageRank信号，返回多信号一致认可的结果。

// 使用示例
search query: "用户认证中间件"

#### lookup - 符号查找

精确查找代码中的符号定义，支持类型过滤：

资料来源：src/server/tools/lookup.ts:1-50

#### impact - 影响分析

分析变更或符号的"爆炸半径"，展示所有受影响的上游和下游依赖。

#### remember/recall - 记忆系统

• remember - 将决策、约定、架构笔记保存到仓库记忆
• recall - 根据查询检索相关记忆

#### review_diff - 差异审查

对Git diff进行结构化分析，输出风险评分和启发式问题列表。

预设工具配置

Sverklo支持通过SVERKLO_PROFILE环境变量选择预设的工具配置，减少代理看到的工具数量：

资料来源：src/server/tool-overrides.ts:1-80

MCP协议集成

Sverklo作为MCP服务器运行，支持标准的MCP协议接口：

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中直接调用：

资料来源：src/server/prompts.ts:1-60

安装与使用

快速开始

# 全局安装
npm install -g sverklo

# 在项目目录初始化
cd your-project
sverklo init

# 查看状态
sverklo status

CLI命令

资料来源：skill/README.md:1-30

技术架构

索引管道

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对比
• 提交历史的符号追踪

社区关注的问题

活跃讨论

已知问题

生态扩展

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

设计原则

1. 本地优先 - 所有处理在本地完成，无需API密钥或代码上传
2. 无状态协调 - MCP服务器无状态，状态存储在本地文件
3. 工具可配置 - 支持运行时禁用或重描述工具
4. Token高效 - 通过PageRank剪枝和token预算控制保持上下文精简
5. Git原生 - 深度集成Git而非替代其工作流

概述

Sverklo 是面向代码智能体的本地优先 MCP（Model Context Protocol）工具，专为 Claude Code、Cursor、Windsurf 和 Codex CLI 等开发环境设计。核心功能包括符号依赖图、代码变更影响分析（blast radius）、差异感知审查（diff-aware review）以及跨会话的持久化记忆。

资料来源：package.json:3-8

系统要求

安装

全局安装

npm install -g sverklo

安装完成后，CLI 工具 sverklo 将全局可用。

验证安装

sverklo --version

资料来源：package.json:14

项目初始化

基本初始化

在项目根目录运行：

sverklo init

init 命令执行以下操作：

1. 创建本地配置文件（CLAUDE.md 或 AGENTS.md）
2. 导入现有项目文档和决策记录
3. 建立本地索引

初始化选项

⚠️ 已知问题：在全新 git 仓库（无任何提交）中运行 sverklo init 会产生无害的 git 警告信息 "Use '--' to separate paths..."，但初始化本身会成功完成。

资料来源：skill/README.md:15-20

AGENTS.md 兼容性

如果项目使用 AGENTS.md 而非 CLAUDE.md，初始化命令会自动检测并尊重该偏好。确保项目根目录存在相应的文档文件。

注册与管理

注册项目

sverklo register .

将当前目录注册到本地 registry（位于 ~/.sverklo/registry.json）。

列出已注册项目

sverklo list

显示所有已注册项目的名称、路径和最后索引时间。

注销项目

sverklo unregister <项目名称>

或按路径注销：

sverklo unregister --by-path /path/to/project

索引与更新

重建索引

sverklo reindex .

重新扫描项目文件并更新符号图和依赖关系。

⚠️ 已知问题：reindex 命令完成后不会更新 ~/.sverklo/registry.json 中的 lastIndexed 时间戳，导致 list 显示的时间信息可能不准确。

索引状态检查

sverklo doctor

运行健康检查，验证索引完整性、版本兼容性和依赖状态。

⚠️ 版本检查注意：在某些环境下，doctor 命令可能执行 PATH 上的 sverklo 而非嵌入式版本，如遇版本不一致请手动确认。

MCP 服务器

Sverklo 通过 MCP 协议与 IDE 集成，提供代码智能服务。

启动 MCP 服务器

sverklo serve

服务器将注册以下核心工具：

资料来源：src/server/mcp-server.ts:15-40

工具预设模式

资料来源：src/server/tool-overrides.ts:1-50

MCP 工具命名

所有工具自动带有 sverklo_ 前缀（如 sverklo_impact、sverklo_lookup）。如在注册时使用 "sverklo" 作为服务器键名，会产生双重前缀（sverklo_sverklo_impact）。建议使用不同的注册键名避免此问题。

工作流程示例

工作流程一：日常开发上下文获取

graph TD
    A[启动 IDE] --> B[sverklo MCP 服务器启动]
    B --> C[自动读取 sverklo://context]
    C --> D[获取 Core Memories 和项目概览]
    D --> E[使用 context 工具获取任务相关上下文]
    E --> F[开始编码任务]

首次启动时，服务器会自动注入项目核心记忆和概览信息，帮助智能体快速了解项目结构。

工作流程二：代码审查

graph TD
    A[创建 PR] --> B[运行 sverklo review_diff]
    B --> C[执行启发式检查]
    C --> D[识别高风险文件]
    D --> E[生成风险评分]
    E --> F[输出审查报告]
    F --> G{风险等级}
    G -->|低| H[通过]
    G -->|高| I[标记需关注]

使用 review_diff 工具获取变更影响分析和结构化审查报告。

工作流程三：持久化决策记忆

graph TD
    A[发现重要决策] --> B[使用 remember 工具]
    B --> C[指定 category 分类]
    C --> D[保存至记忆存储]
    D --> E[后续会话 recall 召回]

决策记忆支持分类标签，便于后续检索和上下文复用。

GitHub Actions 集成

Sverklo 提供 GitHub Action 用于 PR 自动审查：

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 参数

资料来源：action/README.md:1-35

Claude Skill 集成

安装 Claude Code 技能包：

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 接口调用：

资料来源：src/server/prompts.ts:1-50

常见问题

Q: Windows 系统路径问题

如遇路径处理问题，sverklo 内部已针对跨平台路径进行了处理，但部分边缘情况可能仍需注意。

Q: MCP 工具名双重前缀

当服务器注册键名为 "sverklo" 时，会产生 sverklo_sverklo_* 格式的工具名。建议使用不同的服务器注册键名（如项目名）来避免。

Q: 版本不一致警告

升级 npm 包后，如 IDE 中的 MCP 服务器子进程已运行，可能报告旧版本。请重启 IDE 或手动刷新 MCP 连接。

下一步

• 查看 详细命令参考 了解所有工具的完整参数
• 查看 记忆系统指南 学习决策持久化最佳实践
• 查看 代码审查工作流 了解 PR 集成配置

概述

sverklo 是一个面向代码智能的本地优先 MCP（Model Context Protocol）工具，专为编码代理设计。与传统代码搜索或文档工具不同，sverklo 采用多信号检索架构，结合全文搜索（BM25）、语义向量搜索（ONNX 嵌入）、PageRank 重要性排序和图结构分析，提供深度的代码库理解能力。资料来源：package.json:1-15

核心定位对比

传统代码搜索 vs sverklo

资料来源：src/server/tools/search.ts:80-95

通用 RAG 平台 vs sverklo

sverklo 与通用 RAG（检索增强生成）平台的核心差异在于其对代码结构的深度理解：

• 通用 RAG：文档级别切分，丢失代码结构
• sverklo：AST 感知切分，保留符号边界、函数签名、导入关系

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

潜在演进：ColBERT/PLAID 多向量架构

社区正在评估多向量 reranker 方案，其核心优势：

资料来源：GitHub Issue #29 评论区

代码审查工具对比

sverklo Review vs 传统 CI 检查

sverklo 的 PR 审查能力与 GitHub Actions 原生检查形成互补：

资料来源：action/README.md:1-30

审查输出格式

sverklo 生成结构化 PR Review JSON，包含：

{
  "ref": "main..HEAD",
  "max_risk": "high",
  "summary": "<markdown body>",
  "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 的对比：

资料来源：src/server/mcp-server.ts:50-80

工具配置集

sverklo 提供预设的工具配置集，适应不同工作场景：

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 分析：

资料来源：src/server/tools/impact.ts:20-45

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 的记忆系统专为代码代理设计：

资料来源：src/server/mcp-server.ts:120-145

核心记忆（Core Memories）：项目级不变量，在每个会话开始时自动注入上下文。

const coreMemories = indexer.memoryStore.getCore(15);
// 自动加载到每个会话的 sverklo://context 资源

资料来源：src/server/mcp-server.ts:125-130

性能与架构对比

本地优先 vs 云端方案

资料来源：package.json:7-10

依赖项分析

sverklo 的轻量级依赖设计：

资料来源：package.json:37-48

适用场景矩阵

                    短任务      长任务       团队协作
                    ─────      ─────       ───────
代码搜索/导航        ●●●         ●●          ●●
PR 审查             ●           ●●●         ●●●
代码重构影响分析     ●●          ●●●         ●●
新人入职引导         ○           ●●●         ●●
API 文档生成         ●           ●●          ●●

●●● 最佳选择   ●● 推荐   ● 可用   ○ 不适合

资料来源：src/server/prompts.ts:1-20

局限性与已知问题

社区报告的局限

性能基准说明

社区基准测试发现某些场景下存在回归：

• Parser 的字符串/注释感知括号计数器修复后，P1 从 0.30 提升至 0.73
• 但 P2/P4 有轻微回归，需持续监控

资料来源：GitHub Issue #28

总结

sverklo 在以下场景具有独特优势：

1. 隐私敏感环境：数据不出本机，无需 API key
2. 深度代码理解：符号图 + PageRank + 多信号检索
3. 代理工作流：MCP 协议原生集成，记忆跨会话持久化
4. 变更影响评估：blast radius 符号级分析

与传统工具相比，sverklo 更适合需要深度代码库理解、AI 代理协作和长期项目记忆的场景，而非简单的关键词搜索需求。

项目概述

Sverklo 是一个面向 AI 编码代理的代码库记忆系统，为 Claude Code、Cursor、Windsurf 和 Codex CLI 提供本地优先的 MCP（Model Context Protocol）服务。其核心功能包括符号依赖图、代码变更影响分析（blast radius）、差异感知审查以及跨会话的持久化记忆功能。

资料来源：package.json

整体架构

Sverklo 采用分层模块化架构，核心分为索引系统、存储系统、搜索系统和 MCP 服务层四个主要部分。

graph TB
    subgraph 索引系统
        IF[索引文件<br/>index-files.ts]
        IC[索引代码<br/>index-code.ts]
        IG[索引依赖图<br/>index-graph.ts]
        IM[索引记忆<br/>index-memory.ts]
        EMB[嵌入生成器<br/>embedder.ts]
    end
    
    subgraph 存储系统
        DB[(SQLite<br/>数据库)]
        REGISTRY[registry.json<br/>项目注册表]
    end
    
    subgraph 搜索系统
        BM25[BM25 搜索引擎]
        EMB_SEARCH[向量搜索<br/>ONNX embeddings]
        PR[PageRank<br/>图排序]
        HYBRID[混合搜索<br/>hybrid-search.ts]
    end
    
    subgraph MCP 服务层
        SERVER[MCP Server<br/>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 的数据采集核心，负责构建代码库的语义索引。该系统由四个专门的索引器组成，每个索引器处理特定维度的代码分析。

索引器职责

资料来源：src/server/mcp-server.ts

嵌入生成器

Sverklo 使用 ONNX Runtime 在本地运行嵌入模型，无需外部 API。嵌入生成器支持可配置的嵌入维度，并维护一个模型缓存以提高重复查询的效率。

graph LR
    A[源代码片段] --> B[文本预处理]
    B --> C[ONNX 模型推理]
    C --> D[归一化向量]
    D --> E[(向量数据库)]

关键特性：

• 支持 ONNX 格式的预训练嵌入模型
• 向量维度可配置（通过 embedding_dim 参数）
• 模型下载后本地缓存于 ~/.sverklo/models/

资料来源：src/indexer/embedder.ts

存储系统

数据库架构

Sverklo 使用 SQLite 作为本地持久化存储，所有索引数据存储在项目目录的 .sverklo/ 子目录中。

graph TB
    subgraph 数据库表
        T1[files<br/>文件表]
        T2[symbols<br/>符号表]
        T3[edges<br/>依赖边表]
        T4[doc_edges<br/>文档关联表]
        T5[memories<br/>记忆表]
        T6[chunks<br/>代码块表]
    end
    
    T1 <--> T2
    T2 <--> T3
    T1 <--> T4
    T1 <--> T6

数据库文件结构：

.sverklo/
├── sverklo.db          # SQLite 数据库
├── registry.json       # 全局项目注册表
└── models/             # 缓存的 ONNX 模型

项目注册表

registry.json 维护全局项目索引，记录每个已注册项目的基本信息和状态。

资料来源：src/server/mcp-server.ts

搜索系统

Sverklo 采用混合搜索策略，结合多种检索方法以提供高质量的代码搜索结果。

混合搜索架构

graph TB
    Q[用户查询] --> FTS[全文搜索<br/>BM25]
    Q --> VEC[向量搜索<br/>语义嵌入]
    Q --> PR[PageRank 排序]
    
    FTS --> RRF[Reciprocal Rank Fusion<br/>倒数排名融合]
    VEC --> RRF
    PR --> RRF
    
    RRF --> R[排名结果]

混合搜索的核心流程：

1. BM25 检索：基于词频的稀疏检索，对精确匹配关键词效果好
2. 向量检索：使用 ONNX 嵌入模型进行语义相似度计算
3. PageRank 加权：结合图的中心性分数，优先返回高影响力的代码位置
4. 倒数排名融合（RRF）：将多个排名结果按 1/(k+rank)} 公式融合

资料来源：src/search/hybrid-search.ts

检索信号

Sverklo 的搜索系统追踪多种检索信号，用于评估结果质量：

资料来源：src/server/tools/find-references.ts

社区相关：检索架构讨论

社区成员在 issue #29 中提出评估 ColBERT/PLAID 风格的多向量重排序器的可能性，以替代当前的双编码器 + BM25 + PageRank 架构。这是未来搜索系统可能的演进方向。

资料来源：GitHub Issue #29

MCP 服务层

MCP（Model Context Protocol）服务层是 Sverklo 与外部 IDE 交互的接口层，提供工具、资源和提示模板三类功能。

工具集

MCP 服务器暴露的工具按照功能分为多个类别：

资料来源：src/server/tool-overrides.ts

工具预设配置

为不同使用场景预配置的工具集：

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

资源和提示模板

#### 资源（Resources）

MCP 服务器通过 sverklo://context 资源提供自动注入的项目上下文：

sverklo://context
├── 项目核心记忆（tier='core'）
├── 最近活跃记忆
├── 项目概览摘要
└── 技术栈信息

资源在会话开始时自动读取，帮助 AI 代理快速了解项目上下文。

资料来源：src/server/mcp-server.ts

#### 提示模板（Prompts）

Sverklo 提供结构化的工作流模板：

这些模板定义了在特定任务中调用 sverklo 工具的推荐顺序。

资料来源：src/server/prompts.ts

工具系统详解

Context 工具

context 是一个伞形工具，可在一次调用中返回完整的上下文束：

contextTool = {
  name: "context",
  inputSchema: {
    task: "任务描述",
    detail_level: "minimal | normal | full",
    scope: "路径前缀过滤",
    budget: "PageRank 剪枝的 token 预算"
  }
}

工作流程：

1. 接收任务描述
2. 调用混合搜索获取相关代码
3. 获取相关符号定义
4. 召回匹配的保存记忆
5. 组装成单一上下文束返回

资料来源：src/server/tools/context.ts

差异审查工具

差异审查生成两种输出格式：

1. Markdown 摘要：供人类阅读的 PR 评论
2. 结构化 JSON：GitHub PR Review API 格式，可直接 POST 到 GitHub

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

Critique 工具

critique 工具对 AI 代理的答案进行事后审查：

• 验证引用证据的时效性
• 检查遗漏的高 PageRank 节点
• 识别未定义的符号引用
• 检测缺乏文档引用的符号

资料来源：src/server/tools/critique.ts

数据流

会话启动流程

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: 返回工具响应

搜索请求流程

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 反斜杠路径时存在兼容性问题，社区建议使用以下模式转换：

path.replace(/\\/g, "/").split("/").pop()

资料来源：GitHub Issue #20

MCP 工具命名

当 MCP 服务器注册为 "sverklo" 键时，工具名会产生双重前缀（如 sverklo_sverklo_impact）。这是工具前缀与服务器注册键名冲突导致的。

资料来源：GitHub Issue #71

索引时间戳更新

reindex 命令完成后未更新 registry.json 中的 lastIndexed 字段，导致 list 命令显示的索引年龄信息滞后。

资料来源：GitHub Issue #74

技术栈

资料来源：package.json

核心定位

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）架构，综合利用以下几种检索信号：

根据 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 提供了不同场景下的工具集合配置：

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

核心搜索工具

资料来源：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 工具的工作流程设计如下：

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），用于控制返回内容的深度：

资料来源：src/server/tools/context.ts:17-26

工具输入模式

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 排序呈现：

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 提议方案

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 函数：

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 版本的检索引擎已经能够很好地满足大多数代码智能搜索场景，而未来可能的多向量重排序引入将进一步提升检索精度。

系统概述

索引器系统采用模块化架构，包含以下核心子模块：

资料来源：package.json:14-21

核心数据流

索引过程遵循标准的 ETL 模式：文件发现 → 解析 → 提取 → 存储。

graph TD
    A[文件发现<br>file-discovery] --> B[语法解析<br>parser]
    B --> C[符号提取<br>symbol-extractor]
    C --> D[关系构建<br>graph-builder]
    C --> E[嵌入生成<br>embedder]
    D --> F[(Graph Store)]
    E --> G[(Vector Store)]
    C --> H[(File Store)]
    C --> I[(Code Store)]

文件发现模块

file-discovery.ts 负责递归扫描项目目录，基于语言相关的文件模式过滤出需要索引的源文件。

关键配置

模块同时支持增量更新和全量重建，通过 chokidar 监听文件系统变化实现实时同步。

语法解析器

Sverklo 支持两种解析模式以确保最大的代码覆盖率：

1. Tree-sitter 解析器

parser-tree-sitter.ts 使用 tree-sitter 进行精确的 AST 解析：

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

2. 回退解析器

parser.ts 实现了一个基于正则的回退解析器，用于处理 tree-sitter 无法处理的边界情况：

• 单行 IIFE 包装器检测
• 字符串感知的括号计数
• 注释内容排除

特殊处理案例： 处理 lodash.js 等库的单文件 IIFE 包装结构时，精确的括号计数对于正确解析代码块边界至关重要。

资料来源：src/indexer/parser.ts:1-50

符号提取

symbol-extractor.ts 从 AST 中提取结构化符号信息：

提取的符号类型

符号元数据结构

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

关系图构建

graph-builder.ts 基于导入语句构建代码依赖图：

图的表示

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

核心数据结构

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

嵌入生成

embedder.ts 使用 ONNX Runtime Node 生成代码片段的语义嵌入向量：

技术栈

嵌入策略

graph LR
    A[代码块] --> B[分词]
    B --> C[ONNX 模型推理]
    C --> D[512维向量]
    D --> E[(向量索引)]

嵌入粒度：

• 按函数/方法级别切分
• 按文件级别汇总
• 支持上下文窗口扩展

嵌入向量用于语义搜索，与 BM25 全文搜索和 PageRank 图排序结合形成混合搜索能力。

资料来源：src/indexer/embedder.ts:1-25

Grammar 安装管理

grammars-install.ts 负责管理 tree-sitter 语言 grammar 的安装和更新：

功能清单

interface GrammarConfig {
  language: string;
  grammarVersion: string;
  wasmUrl: string;
}

资料来源：src/indexer/grammars-install.ts:1-20

存储层设计

索引器使用四个独立的存储后端：

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

索引状态管理

索引过程维护以下状态信息：

已知问题： sverklo reindex 完成后不会更新 registry.json 中的 lastIndexed 时间戳，导致 sverklo list 显示的索引年龄信息不准确。

资料来源：GitHub Issue #74

性能考量

增量索引

系统采用增量索引策略，仅重新索引变更的文件：

1. 文件系统监控 (chokidar)
2. 变更检测与文件分类
3. 受影响符号的级联更新
4. 图结构的增量重计算

并行处理

Benchmark 回归监控

社区曾发现解析器的字符串/注释感知括号计数器修复后，在某些基准测试上有轻微性能回归，需要持续监控 P2/P4 相关指标。

资料来源：GitHub Issue #28

未来增强方向

搜索架构演进

社区正在评估引入 ColBERT/PLAID 风格的多向量重排序器，以改进当前的 bi-encoder + BM25 + PageRank 混合搜索架构。

资料来源：GitHub Issue #29

增量嵌入更新

当前嵌入生成是全量重算，未来计划支持基于代码变更的增量嵌入更新，减少大型项目的索引时间。

命令行接口

总结

索引器系统是 Sverklo 的数据基础设施，通过组合使用 tree-sitter AST 解析、符号提取、图关系构建和语义嵌入技术，将原始代码转换为可查询的结构化数据。模块化设计使得各组件可以独立演进，同时通过标准化的存储接口保持数据一致性。

概述

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服务器架构

服务端组件结构

graph TD
    A[MCP Client<br/>Claude Code/Cursor] --> B[MCP Server<br/>sverklo]
    B --> C[工具注册表<br/>Tool Handlers]
    B --> D[资源处理器<br/>Resource Handlers]
    B --> E[提示处理器<br/>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<br/>项目上下文资源]
    
    E --> E1[工作流模板<br/>map-feature/pre-merge等]

服务器初始化流程

MCP服务器在mverklo-server.ts中通过MCP SDK初始化，核心步骤包括：

1. 创建Server实例，配置功能声明
2. 注册所有MCP工具处理器
3. 配置资源端点用于会话启动时的上下文注入
4. 注册提示模板用于IDE工作流
5. 启动请求处理器循环

// 资料来源：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）。旧版工具名通过别名机制保持向后兼容：

// 资料来源：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);
  });
});

别名系统在首次调用时输出弃用警告，后续调用不再重复警告，避免日志污染。

工具分类与功能矩阵

核心索引工具

图分析工具

记忆工具

审查工具

上下文工具

审计工具

资源注入机制

sverklo://context 资源

MCP服务器通过资源订阅机制在每个会话启动时自动注入项目上下文：

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. 近期变更摘要：未标记为陈旧的最新记忆和变更

// 资料来源：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完成常见代码智能任务。

可用模板列表

map-feature 工作流示例

// 资料来源：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），组合不同工具子集以适应特定使用场景：

// 资料来源：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预算控制

// 资料来源：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调用：

graph LR
    A[evidence_ids] --> B[验证证据时效性]
    A --> C[检查符号定义存在]
    A --> D[分析PageRank Hub覆盖]
    A --> E[检查文档引用完整性]
    
    B --> F[格式化的批判报告]
    C --> F
    D --> F
    E --> F

// 资料来源：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工具执行差异感知审查，结合启发式规则识别高风险代码模式：

// 资料来源：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：

{
  "ref": "main..HEAD",
  "max_risk": "high",
  "summary": "<markdown body>",
  "inline": [{ "path", "line", "severity", "body" }],
  "high_risk_files": [{ "path", "score", "reasons" }]
}

Wakeup 生成

sverklo wakeup命令生成简化的会话启动文档，包含：

// 资料来源：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 [email protected]升级后，已运行的MCP服务器仍使用旧二进制文件，sverklo doctor也不会报告版本不一致（参见问题#17）。

与GitHub Action集成

sverklo提供独立的GitHub Action用于PR审查：

# 资料来源：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都能获得项目上下文，而提示模板则将最佳实践工具调用序列编码为可复用的工作流。

概述

Sverklo 的双时态记忆系统（Bitemporal Memory System）是一种持久化记忆框架，旨在为编码智能体跨越多个工作会话提供上下文连续性。该系统通过维护两套独立的时间维度来追踪每条记忆的状态：

• 创建时态（Creation Temporal）：记忆首次创建的时间，记录会话上下文
• 索引时态（Index Temporal）：记忆被注册到工作区索引的时间，用于检索和老化管理

双时态设计使得系统能够区分"记忆何时产生"与"记忆何时被纳入工作上下文"，从而支持更精细的记忆生命周期管理和智能检索。

资料来源：src/storage/memory-store.ts:1-50

核心数据模型

记忆条目结构

双时态时间戳

资料来源：src/storage/memory-store.ts:20-45

记忆存储架构

MemoryStore 类

MemoryStore 是核心存储抽象，提供记忆的增删改查和生命周期管理接口。

class MemoryStore {
  // 持久化读写
  getAll(limit?: number): Memory[]
  getCore(limit: number): Memory[]
  add(memory: Omit<Memory, "id" | "created_at">): 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 负责记忆的语义向量表示，支持基于相似度的检索：

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

记忆生命周期

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 时间戳：

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 实现了从外部源导入记忆的能力，支持跨工作区迁移和全局记忆同步。

export async function importExistingMemories(
  sourcePath: string,
  targetRepo: string
): Promise<Memory[]>

关键特性：

• 扫描源目录下的现有记忆文件
• 验证记忆内容有效性
• 重新映射 repo_path 到目标仓库
• 合并去重（基于内容哈希）

资料来源：src/memory/import.ts:1-80

导出模块

export.ts 支持将记忆导出为可移植格式：

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

记忆老化与修剪

老化机制

每条记忆可被标记为过期（is_stale），典型场景包括：

• 相关代码已被删除或重构
• 决策已被撤销
• 技术栈已升级

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 实现了记忆的自动清理策略：

资料来源：src/memory/prune.ts:1-60

会话上下文注入

核心记忆自动注入

在每次会话启动时，服务器通过 MCP 资源接口自动注入项目核心记忆：

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 函数生成会话起始的上下文摘要：

export function generateWakeup(
  indexer: IndexFiles & IndexMemory,
  options: { maxTokens?: number; format?: "markdown" | "plain" } = {}
): string

输出包含：

• 项目基本信息（名称、文件数、语言）
• 核心文件列表（按依赖排名）
• 项目不变式（核心记忆）
• 最近活动记录

资料来源：src/server/tools/wakeup.ts:30-80

聊天挖掘

mine-chats.ts 实现了从对话历史中自动提取记忆的能力：

export async function mineChatMemories(
  chatHistory: ChatMessage[],
  options?: { minConfidence?: number }
): Promise<Memory[]>

提取的记忆类型包括：

• 架构决策（"我们决定使用 X 而不是 Y"）
• 技术债务记录
• 已知问题说明
• TODO 和后续任务

资料来源：src/memory/mine-chats.ts:1-50

MCP 工具接口

remember 工具

保存新的记忆条目：

{
  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 工具

检索相关记忆：

{
  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

模式配置

不同工作模式下的记忆工具可用性：

资料来源：src/modes.ts:1-50

最佳实践

核心记忆 vs 普通记忆

• core（核心）：项目级不变式，如架构决策、重要约束、品牌规范
• normal（普通）：会话级上下文，如特定 bug 的解决方案

避免记忆过时

• 代码重构后及时标记相关记忆为 stale
• 使用 unmarkStale 工具在验证记忆仍有效时恢复
• 定期运行修剪脚本清理过期记忆

跨仓库记忆管理

• 使用全局配置建立机器级记忆库
• 项目级记忆仅存储仓库特有信息
• 利用导入导出功能在项目间迁移集体智慧

相关文档

• CLI 参考 - sverklo init
• CLI 参考 - sverklo register
• MCP 服务器架构
• 混合搜索系统

概述

差异审计与质量门禁是 sverklo 的核心功能模块，用于在代码变更（diff）中实施结构化质量检查。这些检查包括循环依赖检测、扇入/扇出分析、模块边界验证，并通过风险评分系统帮助开发团队在代码审查阶段发现潜在问题。

sverklo 提供两种差异审计输出格式：

资料来源：src/server/audit-html.ts:1-20

核心架构

差异审计系统由以下子模块组成：

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-），防止基准测试目录名称泄露到发布的报告中：

const displayName = cleanProjectName(projectName, projectPath);

资料来源：src/server/audit-html.ts:11-18

评分等级

审计报告使用颜色编码的等级系统：

资料来源：src/server/audit-html.ts:100-105

SEO 与社交分享

生成的 HTML 包含完整的 Open Graph 和 Twitter Card 元数据，便于在社交平台分享：

<meta property="og:title" content="项目审计报告">
<meta property="og:type" content="article">
<meta name="twitter:card" content="summary_large_image">

资料来源：src/server/audit-html.ts:80-95

Obsidian 集成报告

audit-obsidian.ts 生成与 Obsidian 兼容的 Markdown 格式报告，支持 [[wikilinks]] 实现依赖关系可点击导航。

构建流程

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 上发布内联审查评论：

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

内联评论格式

每条内联评论包含：

资料来源：src/server/tools/review-format.ts:32-40

风险评分系统

风险等级

启发式检测

sverklo 使用启发式规则检测代码中的风险模式：

• 未捕获的流调用（如 stream.on('data') 无错误处理）
• 过于复杂的函数
• 违反模块边界的高扇入文件

资料来源：src/server/tools/review-format.ts:50-80

批判性分析工具

critique 工具提供更深入的代码审查视角：

验证流程

1. 符号追踪：验证声称引用的符号是否真实存在
2. 过时检查：标记已被删除但仍被引用的符号
3. 迁移检测：识别已移动到其他路径的符号
4. 文档覆盖：检查符号是否在 .md/.markdown/.mdx 文件中被引用

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

未定义符号检测

graph TD
    A[引用符号] --> B{符号存在?}
    B -->|是| C[检查文档]
    B -->|否| D[标记为未定义]
    C --> E{有文档引用?}
    E -->|是| F[正常]
    E -->|否| G[标记为无文档]

资料来源：src/server/tools/critique.ts:35-50

上下文感知审计

预算感知的上下文检索

context 工具支持按 Token 预算返回精简的审计上下文：

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 定义了针对不同场景的工具配置：

资料来源：src/server/tool-overrides.ts:1-60

审查提示模板

review: [
  "review_diff",
  "diff_search",
  "test_map",
  "impact",
  "refs",
  "lookup",
  "search",
  "investigate",
  "verify",
  "status",
]

资料来源：src/server/tool-overrides.ts:25-35

GitHub Actions 集成

Action 配置

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 参数

资料来源：action/README.md:1-40

环境变量配置

工具覆盖

// 示例：禁用记忆工具
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 文档
• 差异审查工具
• 差异启发式规则
• 批判性分析

概述

Sverklo 的存储层采用多存储组件分离架构，通过统一的索引器接口（Indexer）聚合文件存储、代码存储、图存储和内存存储四个核心存储组件。这种设计实现了关注点分离，使每种数据类型都能采用最适合的存储策略。

所有存储组件均支持 JSON 文件持久化，存储位置默认为 ~/.sverklo/ 目录下的各子目录中。

核心组件

1. 文件存储 (IndexFiles / FileStore)

负责管理代码库的文件元数据，是整个索引系统的基础。

文件记录包含以下核心字段：

• id: 文件唯一标识符
• path: 相对于代码库根目录的文件路径
• language: 编程语言类型
• size: 文件大小（字节）
• pagerank: PageRank 分数，用于衡量文件在依赖图中的重要性
• chunk_count: 该文件的代码块数量

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) 是代码分析的最小单元，通常对应函数、类或模块级别的代码片段。每个代码块包含：

符号表 (SymbolTable) 记录代码中定义的标识符及其元信息：

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 计算。

图结构包含两种边：

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 的持久化记忆功能，支持在会话之间保存上下文和决策。

记忆层级：

记忆记录结构：

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"功能。

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 是四个存储组件的统一接口，定义如下：

type Indexer = IndexFiles & IndexCode & IndexGraph & IndexMemory;

该接口被 MCP 服务器和所有工具处理器使用，确保数据访问的一致性。

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

持久化策略

存储位置

索引状态追踪

索引器通过 getStatus() 方法返回项目的索引状态：

interface IndexStatus {
  projectName: string;
  projectPath: string;
  fileCount: number;
  languages: string[];
  lastIndexed?: string;
}

⚠️ 已知问题：sverklo reindex 完成后不会更新 registry.json 中的 lastIndexed 时间戳，导致 sverklo list 显示的索引年龄信息可能过期。

相关 Issue: #74

资料来源：src/server/tools/wakeup.ts:1-50

搜索与检索

混合搜索 (Hybrid Search)

sverklo 采用混合搜索策略，结合多种检索信号：

这种设计源于社区讨论——当前系统使用双编码器（bi-encoder）+ BM25 + PageRank 架构，未来可能评估 ColBERT/PLAID 风格的多向量重排序方案。

💬 社区讨论：Issue #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 接口访问存储层：

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）控制：

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）

索引时间

已知性能问题

⚠️ 回归问题：Issue #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. 在需要的地方注入新的存储依赖

// 示例：新增 PatternStore
export interface IndexPatterns {
  patternStore: PatternStore;
}

Pitfall Log / 踩坑日志

项目：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