1. 概述与定位

Sverklo 是一个本地优先（local-first）的代码情报 MCP（Model Context Protocol）服务器，为 Claude Code、Cursor、Windsurf 和 Codex CLI 等编程代理提供代码库的语义检索、依赖图谱、影响域分析、差异审查和持久化记忆能力。根据 package.json 的描述，其核心理念是"代码仓库记忆"——通过本地索引、混合检索（BM25 + ONNX 嵌入 + PageRank）和 Git 固定决策，让代理在多次会话中保持对项目结构与上下文的理解。

系统的运行要求 Node.js >= 24.0.0，主要依赖包括 @modelcontextprotocol/sdk、onnxruntime-node（用于本地嵌入推理）、chokidar（文件监听）、ignore（.gitignore 解析）以及可选的 web-tree-sitter（多语言 AST 解析）。所有计算均在本地完成，无需 API Key 或代码上传（MIT 许可证）。

2. 整体架构

Sverklo 的运行时分为三层：MCP 协议适配层、工具与提示词层、以及底层索引存储层。

flowchart TB
    subgraph Client["MCP 客户端<br/>(Claude Code / Cursor / Codex CLI)"]
        Agent["编码代理"]
    end

    subgraph Server["MCP Server (src/server/mcp-server.ts)"]
        Tools["36 个工具<br/>(search/lookup/refs/impact/...)"]
        Prompts["Prompt 模板<br/>(map-feature / architecture-map)"]
        Resource["sverklo://context<br/>(自动注入核心记忆)"]
    end

    subgraph Indexer["索引与检索层"]
        Hybrid["hybridSearch<br/>(BM25 + ONNX 向量 + PageRank)"]
        Crit["critique / verify"]
        Wakeup["wakeup"]
        Context["context"]
    end

    subgraph Stores["存储层 (IndexFiles / IndexCode / IndexGraph / IndexMemory)"]
        FS["fileStore"]
        GS["graphStore"]
        MS["memoryStore"]
        DES["docEdgeStore"]
    end

    Agent -->|JSON-RPC| Server
    Tools --> Indexer
    Prompts --> Tools
    Indexer --> Stores

如 src/server/mcp-server.ts 所示，服务器在启动时声明 tools、resources 和 prompts 三类能力。其中 sverklo://context 资源会在每个会话开始时自动注入 tier='core' 的核心记忆，确保代理始终了解项目的不变约束。

3. 核心组件与数据流

3.1 索引存储层

底层数据通过四个核心 Store 暴露给上层工具：

例如在 audit-obsidian.ts 中，生成 Obsidian 风格的依赖审计报告时，会先从 fileStore.getAll() 构建 idToPath 映射，再遍历 graphStore.getAll() 的边构造 import / imported-by 索引，最终输出带 [[wikilinks]] 的可导航报告。类似地，audit-graph.ts 在生成交互式依赖图时会通过 isVendoredPath() 过滤掉第三方依赖，使可视化结果聚焦于项目自身代码。

3.2 工具与混合检索

Sverklo 暴露的 36 个工具按照预设场景分组。根据 tool-overrides.ts：

• nav（导航）：search、lookup、overview、refs、impact、deps、context、status
• lean（精简）：在 nav 之上加入 remember、recall、review_diff
• research（深度研究）：增加 search_iterative、investigate、ask、concepts、patterns、clusters、verify、critique、ctx_slice、ctx_grep、ctx_stats
• review（PR 审查）：以 review_diff、diff_search、test_map 为核心

context.ts 实现了"上下文聚合"工具，将 overview、search、recall、symbol 表合并为一次往返的精选包，支持 minimal / normal / full 三级详略度，并可指定 budget 参数触发 PageRank 剪枝的仓库地图。检索层面，hybridSearch 组合 BM25 全文检索、ONNX 双编码器向量相似度、以及 PageRank 中心性三路信号进行倒数排名融合（Reciprocal Rank Fusion）。

3.3 验证与审查

critique 工具（critique.ts）会检查代理输出的"声明"是否被代码证据支持、是否引用了被标记为 stale 的记忆、是否漏掉了高 PageRank 的"枢纽"文件，并通过 docEdgeStore 检测被引用的符号是否在文档中出现。review_diff 工具（review-format.ts）则在 CI/GitHub Action 场景下输出结构化 PR 评论载荷，包含行内 inline 注释与 high_risk_files 风险清单。

4. 关键设计权衡与社区讨论

检索架构的当前形态（双编码器 + BM25 + PageRank）在社区中引发了关于是否引入 ColBERT/PLAID 风格多向量重排器的讨论（参见 Issue #29）。支持者认为多向量重排能在代码搜索这种"精确符号匹配"场景中显著提升首位命中率；反对者则担心 ONNX 推理时延与本地显存占用。

另一项与流水线稳定性相关的已知问题是 Issue #74：sverklo reindex 完成后未刷新 ~/.sverklo/registry.json 的 lastIndexed 字段，导致 sverklo list 显示陈旧时间戳。Issue #71 则反映 MCP 客户端约定以服务器名为前缀（如 sverklo_sverklo_impact），与现有工具名自带 sverklo_ 前缀产生双重前缀冲突——这是工具命名层与协议约定层耦合的一个典型问题。

最后，audit-arch.ts 中的 LAYER_PATTERNS（Frontend、API、Storage、Indexer、Auth、Config、Utils、Tests、Types、Memory）说明系统通过目录名启发式识别架构分层，进而在 audit-graph 与 audit-html 中生成可解释的层次视图，弥补了纯 PageRank 排名缺乏语义分层的不足。

See Also

• 检索机制详解：BM25 + 向量 + PageRank 三路融合
• MCP 工具参考：36 个工具的输入输出 schema
• 持久化记忆：memoryStore 的 tier 模型与 recall/remember 语义
• GitHub Action 集成：PR 自动审查与风险评分

检索原语与 MCP 工具参考

概述

Sverklo 通过本地优先的 MCP（Model Context Protocol）服务器向编码代理（Claude Code、Cursor、Windsurf、Codex CLI 等）暴露一组以检索原语（Retrieval Primitives）为中心的代码智能工具。package.json 中声明的核心依赖仅包含 ONNX Runtime、Chokidar、picomatch、YAML 与 MCP SDK，表明 BM25、向量与 PageRank 计算完全在本地进程内完成，不依赖任何云端 API 或代码外传。资料来源：package.json:31-40

整套检索系统被组织为原子工具与聚合入口两层：原子工具（如 search、lookup、refs、impact）直接调用底层的混合检索（hybrid search）、PageRank 重排与上下文增强；聚合入口（如 context、investigate、wakeup）则把多个原子结果捆绑成单一往返响应，节省代理的 tool-call 轮次。资料来源：src/server/mcp-server.ts:1-25

MCP 工具集与命名

工具总览

服务器通过 server.setRequestHandler 暴露 tools、resources、prompts 三类能力，并在 instructions 中明确告知宿主代理在使用 Grep/Read 之前优先调用 sverklo_search 等工具；同时通过 ListResourcesRequestSchema 注册一个 sverklo://context 资源，在会话开始时自动注入"核心记忆（tier='core'） + 代码库概览"。资料来源：src/server/mcp-server.ts:13-56

工具名默认带 sverklo_ 前缀（如 sverklo_impact、sverklo_lookup、sverklo_search）。社区 issue #71 指出：当 MCP 客户端再叠加一次服务端键名（sverklo）作为命名空间时，会形成 sverklo_sverklo_impact 这种双前缀，破坏下游模型对工具名的解析预期，是当前命名约定的已知边界。资料来源：src/server/tool-overrides.ts:1-12

工具配置集（profiles）

src/server/tool-overrides.ts 的 TOOL_PROFILES 字典为不同场景预定义白名单：navigation 仅暴露 5 个核心导航工具，lean 加入 remember / recall / review_diff，research 保留多信号检索面与 ctx-handle 切片操作，review 则把 review_diff / diff_search / test_map 顶到首位。这些 profile 通常经 SVERKLO_* 环境变量归一化后下发到 MCP 客户端配置。资料来源：src/server/tool-overrides.ts:5-58

核心检索原语

混合检索

search 是入口级原语，在底层调用 hybridSearch 把 BM25 关键词匹配、ONNX 嵌入语义相似度与 PageRank 图权重做倒数秩融合（Reciprocal Rank Fusion），再可选地用 rerank.ts 中的交叉编码器重排。社区 issue #29 讨论了用 ColBERT/PLAID 多向量重排器替代当前双编码器的可行性，但截至 v0.29.1 仍是单向量路线。资料来源：package.json:18-30

上下文聚合

context 工具（src/server/tools/context.ts）是"前端入口"：接受 task 自由文本描述 + 可选 detail_level ∈ {minimal, normal, full} 与 budget（token 预算）。detail_level 越小，返回的搜索命中与记忆数越少；budget 模式输出按 PageRank 贪心剪枝的仓库地图，是给代理快速建立陌生代码库心智模型的标准做法。资料来源：src/server/tools/context.ts:18-30

引用与文档协同

find_references 既返回结构性 import 边，又通过 docEdgeStore.getBySymbol 拉取符号在 Markdown / README / ADR 中的反向引用，区分"被包含"（includes）和"关联提及"（reference），并按 (doc_file_path, breadcrumb, match_kind) 去重，避免外层代码块与内层围栏产生近重复行。资料来源：src/server/tools/find-references.ts:1-25

批判性验证

critique 接收代理已引用的证据 id 与已讨论的符号名，逐条检查证据是否仍 current、是否被移动、是否引用了未定义符号，并对比是否有高 PageRank 枢纽文件被遗漏、所有被讨论符号是否有 Markdown 文档覆盖。整个流程不在服务器端调用任何 LLM，纯静态图查询。资料来源：src/server/tools/critique.ts:1-25

工具组合与提示模板

src/server/prompts.ts 把常见代码智能任务编码为有序 tool-call 序列，在 IDE prompt 选择器中暴露（Claude Code、Cursor、Antigravity）。例如 sverklo/map-feature 给出四步走：investigate → refs → impact → ctx_slice，把"先广撒网、再局部钻取"的范式直接教给宿主模型。资料来源：src/server/prompts.ts:1-35

src/server/hints.ts 的 HintEngine 实现意图感知的"下一步建议"：用有界 ring buffer（HISTORY_LIMIT = 10）记录最近 N 次调用，仅基于调用名 + 参数做意图分类（exploring / reviewing-diff / tracing-impact / debugging / onboarding / memory-curating / unknown），并在每次响应尾部追加一句 next-steps 提示。它不读取工具输出，因此不会因额外 DB 查询阻塞响应。资料来源：src/server/hints.ts:1-50

在 GitHub PR 自动化场景下，action/README.md 描述的 sverklo-review Action 在 CI 中调用 review_diff / diff_search，把结构化 JSON 风险评分 + 最多 30 条行内评审评论直接 POST 到 pulls.createReview，由 fail-on 阈值控制构建是否失败。资料来源：action/README.md:1-30

已知限制与社区反馈

See Also

• 评审差异与风险评分：src/server/tools/review-diff.ts 与启发式规则 src/server/tools/diff-heuristics.ts
• 代码库健康审计：src/server/audit-analysis.ts、src/server/audit-html.ts、src/server/audit-obsidian.ts
• 记忆持久层：src/indexer/index-memory.ts 与 ~/.sverklo/registry.json 状态管理
• CLI 入口与项目注册：src/bin/sverklo.ts（register / reindex / unregister 子命令）

双时态记忆层与 Git 感知决策

概览与设计目标

Sverklo 的记忆子系统为编码代理（Claude Code、Cursor、Windsurf、Codex CLI 等）提供跨会话持久化的项目知识。它在本地 SQLite 中维护一组"决策、偏好、模式、上下文、待办、过程性规则、纠正"等类型的记忆条目，并把它们绑定到 Git 状态之上，以实现"决策随代码演化而自动失效"的语义。

package.json 中将该能力概括为「Repo memory for coding agents」与「git-pinned decisions」，强调"local-first、无 API Key、不上传代码"的部署原则（package.json:1-10）。src/server/mcp-server.ts 在 instructions 字段中进一步指示代理"使用 sverklo_search 进行语义检索，使用 sverklo_remember 持久化重要决策"（src/server/mcp-server.ts:instructions），把记忆层定位为检索、依赖图、Diff 评审之外的第四条腿。

记忆模型：分类、时态与 Git 锚定

分类与置信度

src/server/tools/remember.ts 中定义了 MemoryCategory 与 MemoryTier 枚举，覆盖七类语义：decision / preference / pattern / context / todo / procedural / correction。其中 procedural 表示"总是做 X"的规则，correction 用来纠正模型历史错误（"不要再用 em-dash"、"永远不要调用此方法"），与 AI Edge 记忆分类体系保持一致（src/server/tools/remember.ts:categories）。每条记忆可携带 tags、related_files、confidence（0.0–1.0）等元数据。

双时态与 Git 锚定

remember.ts 顶部导入 getGitState 来自 src/memory/git-state.ts，并通过 track 调用埋点写入遥测（src/server/tools/remember.ts:imports）。这意味着每条记忆在写入时会同时记录两类时间：

• 有效时间（Valid Time）：通过 related_files 关联文件并锚定到当时的 Git SHA。文件后续被修改，记忆即可判定为过时。
• 事务时间（Transaction Time）：本地存储写入时刻，由 SQLite 的 created_at / updated_at 维护。

冲突检测与陈旧化

CONFLICT_THRESHOLD = 0.85 用来在写入时检测与既有记忆的语义重叠：超过该阈值即认为冲突，并自动使旧记忆失效（src/server/tools/remember.ts:CONFLICT_THRESHOLD）。critique.ts 在对模型回答做事实核验时，会读取 is_stale 标记并将其作为 stale 维度单独输出，提醒代理该决策可能已不再适用（src/server/tools/critique.ts:stale）。

MCP 集成：会话注入与工作流

启动期核心记忆注入

mcp-server.ts 注册了 sverklo://context 资源，在每个会话开始时由代理主动读取。ReadResourceRequestSchema 处理器在索引就绪后，从 indexer.memoryStore.getCore(15) 拉取至多 15 条 tier='core' 的记忆（项目不变量），并把它们拼装为「Core Project Context」段注入到响应中；同时附加 [STALE] 标签标识已失效条目（src/server/mcp-server.ts:ReadResourceRequestSchema）。该机制保证每次新会话都能立即获得稳定的项目约束。

上下文聚合与 recall 串联

src/server/tools/context.ts 是「面向任务的一站式聚合器」，在 normal 级别下默认附带 top 5 memories。其内部直接复用 handleRecall，把记忆搜索结果与代码片段、依赖图一并返回（src/server/tools/context.ts:handleRecall）。当 budget 设定时，它会切换为 PageRank 剪枝的仓库地图模式，把记忆替换为纯粹的代码拓扑。

引用与文档联动

find-references.ts 在查符号时额外查询 indexer.docEdgeStore.getBySymbol(symbol, 20)，把 README、ADR 中对该符号的「包含/引用」边回填到回复里（src/server/tools/find-references.ts:docMentions）。这让代理在阅读 decision 类记忆时，能顺着文档反向验证"这条决策还写在哪些 Markdown 里"，与 critique 工具的「未引用文档的符号」检查互为补集。

flowchart LR
  A[代理调用 remember] --> B[git-state 捕获<br/>SHA / dirty 状态]
  B --> C[SQLite 写入<br/>valid + transaction time]
  C --> D{与既有相似度 > 0.85?}
  D -- 是 --> E[旧记忆 is_stale = true]
  D -- 否 --> F[持久化为新条目]
  F --> G[下次会话]
  G --> H[ReadResource sverklo://context]
  H --> I[注入 tier=core 记忆]
  I --> J[context 工具聚合代码 + 记忆]
  J --> K[critique 校验<br/>is_stale 标签]

已知限制与社区反馈

• Git 状态校验：src/utils/git-validation.ts 对所有进入子进程的 ref 实施严格白名单（分支、标签、SHA、A..B 区间、HEAD~N），拒绝 ; ` ` | $ 等 shell 元字符（src/utils/git-validation.ts:validateGitRef）。这保护了"git-pinned"机制的注入路径，但若用户传入 HEAD@{2} 这类带大括号的 ref 仍会通过正则，存在被 git reflog` 解析为命令注入的边角风险，社区正在讨论更严格的语义解析（GitHub #29 讨论）。
• lastIndexed 漂移：社区报告 sverklo reindex 不更新 ~/.sverklo/registry.json 的 lastIndexed，导致 sverklo list 显示陈旧年龄（GitHub #74）。该问题影响记忆的"事务时间"可观察性，建议在重索引流程末尾同步回写时间戳。
• 单租户全局导入：initExistingMemories() 仍嵌套在 sverklo init 的项目级流程中；社区要求新增 --global 一次性配置，复用 importExistingMemories 扫描能力（GitHub #72）。
• 意图感知提示：src/server/hints.ts 维护最近 10 次工具调用的环形缓冲，对 memory-curating 意图追加下一步建议（src/server/hints.ts:history），但当前不读取 is_stale 字段，建议在下一版本把陈旧率纳入提示。

See Also

• 检索架构：双编码器 + BM25 + PageRank 与多向量重排（参见 issue #29）
• Diff-aware 评审：参见 src/server/tools/diff-search.ts 与 action/README.md
• 上下文聚合：src/server/tools/context.ts
• 工具集预设：src/server/tool-overrides.ts

CLI 工作流、注册表、审计门禁与失败模式

1. 概览：本地优先的代理式代码智能体

Sverklo 是一个面向 AI 编码代理（Claude Code、Cursor、Windsurf、Codex CLI）的本地优先 MCP 服务器。它将符号图谱、爆炸半径分析、差异感知评审、PageRank 排序以及 git 钉选的"决策记忆"整合在一起，并且不向云端上传任何代码或 API Key。CLI 是该系统的入口：所有项目都需要先经过 sverklo init 或 sverklo register 才能进入全局注册表，后续的 reindex、list、unregister、audit 等子命令都建立在这个注册表之上（资料来源：package.json:1-40）。

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

2. CLI 工作流与典型调用链

2.1 单项目初始化流程

官方推荐的五步流程为：

1. npm install -g sverklo —— 全局安装 CLI 入口 dist/bin/sverklo.js。
2. cd your-project && sverklo init —— 在项目目录内执行一次性初始化。
3. 编辑器/代理通过 sverklo://context 资源自动拉取项目记忆（资料来源：src/server/mcp-server.ts:1-50）。
4. 代理按需调用 sverklo_search、sverklo_impact、sverklo_review_diff 等工具。
5. 结束会话时由 sverklo remember 把决策写入 SQLite 索引。

2.2 工具配置文件与 profile 机制

通过环境变量可以在不修改代码的情况下裁剪工具面：

这种"profile + 黑名单 + 描述覆写"的三层机制解决了代理上下文窗口有限时工具过载的问题（资料来源：src/server/tool-overrides.ts:1-60）。

2.3 内置 prompt 模板

prompts.ts 中预置了 sverklo/map-feature、sverklo/pre-merge 等工作流模板，强制代理按"调用 investigate → refs → impact"的固定顺序探索代码（资料来源：src/server/prompts.ts:1-30）。

3. 全局注册表与项目生命周期

所有已注册的项目都写入 ~/.sverklo/registry.json，其中关键字段包括项目路径、lastIndexed 时间戳以及派生出的"项目年龄"展示。sverklo list 与 sverklo reindex 共享这份注册表。

flowchart LR
  A[sverklo register] --> B[registry.json]
  C[sverklo reindex] --> B
  D[sverklo list] --> B
  E[sverklo unregister] --> B
  B --> F[IndexerPool]
  F --> G[(SQLite 索引)]

资料来源：src/server/mcp-server.ts:1-50, package.json:1-40

4. 审计门禁与生成器

4.1 三种审计产物

• generateAuditHtml(markdown, projectName, projectPath) —— 产出与 sverklo.com 品牌一致的深色主题自包含 HTML，并清洗 report-、regen-、rpt-、final-、v12-、bench- 等基准测试残留前缀（资料来源：src/server/audit-html.ts:1-40, src/server/audit-html.test.ts:1-30）。
• generateAuditObsidian(indexer, analysis, projectName) —— 输出 Obsidian 兼容的 markdown，利用 [[wikilinks]] 实现跨文件依赖导航（资料来源：src/server/audit-obsidian.ts:1-40）。
• audit-arch.ts —— 依据目录命名模式自动识别 Frontend / API / Storage / Search / Indexer 等分层，渲染确定性布局的依赖图（资料来源：src/server/audit-arch.ts:1-50）。

4.2 评审门禁

GitHub Action 在每次 PR 中会调用 review_diff + 启发式规则，发出风险评分最高的内联评论；fail-on 阈值决定是否阻塞合并（资料来源：action/README.md:1-30, src/server/tools/review-format.ts:1-30）。

5. 常见失败模式与社区反馈

以下问题在社区讨论与 issue tracker 中出现频率最高，新用户最容易踩坑：

资料来源：src/server/mcp-server.ts:1-50, src/server/tool-overrides.ts:1-60, package.json:1-40

6. 使用建议

• 多 worktree 场景：以 path 而非 name 作为不可变标识，结合脚本预解析 list 输出（应对 #73）。
• 检索质量调优：先用 sverklo_status 确认索引覆盖率，再决定是否升级到 ColBERT 风格的多向量重排（应对 #29）。
• 工具过载：在 .mcp.json 中设置 SVERKLO_PROFILE=lean 或 core，可显著减少 token 消耗。

7. 参见

• package.json —— 包元数据与依赖
• src/server/mcp-server.ts —— MCP 服务器与资源注入
• src/server/tool-overrides.ts —— profile 与运行时覆写
• action/README.md —— GitHub Action 评审门禁

Pitfall Log / 踩坑日志

项目：sverklo/sverklo

摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 需要 API Key 或环境变量。

1. 配置坑 · 需要 API Key 或环境变量

• 严重度：high
• 证据强度：source_linked
• 发现：项目说明中出现 API Key / 环境变量相关需求。
• 对用户的影响：用户必须准备账号、额度或密钥；密钥配置错误会导致运行失败或泄漏风险。
• 证据：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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：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 | 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 | 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 | https://github.com/sverklo/sverklo/issues/66 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

18. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | issue_or_pr_quality=unknown

19. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1203034717 | https://github.com/sverklo/sverklo | release_recency=unknown