# https://github.com/varve-sh/varve 项目说明书

生成时间：2026-07-29 23:57:06 UTC

## 目录

- [概览、安装与核心概念](#page-1)
- [系统架构、数据库与事件流](#page-2)
- [MCP 工具与 CLI 命令参考](#page-3)
- [混合检索、打包、摄取与导入导出](#page-4)

<a id='page-1'></a>

## 概览、安装与核心概念

### 相关页面

相关主题：[系统架构、数据库与事件流](#page-2), [MCP 工具与 CLI 命令参考](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/varve-sh/varve/blob/main/README.md)
- [docs/concepts.md](https://github.com/varve-sh/varve/blob/main/docs/concepts.md)
- [docs/setup.md](https://github.com/varve-sh/varve/blob/main/docs/setup.md)
- [CLAUDE.md](https://github.com/varve-sh/varve/blob/main/CLAUDE.md)
- [cmd/varve/main.go](https://github.com/varve-sh/varve/blob/main/cmd/varve/main.go)
</details>

# 概览、安装与核心概念

## 项目概览

varve 是一个面向 AI 编程助手（Claude Code、Cursor 等）的本地化记忆与上下文管理工具。它通过在项目根目录生成 `.memtrace` 目录，把分散在对话中的事实、约定与上下文沉淀为可被语义检索的结构化记忆，并通过 MCP（Model Context Protocol）协议对外暴露工具，使模型在后续会话中能够自动获取相关上下文。最新稳定版为 v1.5.4。

资料来源：[README.md:1-40]()

## 安装与初始化

varve 以单一 Go 二进制形式分发，源码入口位于 `cmd/varve/main.go`，在具备 Go 工具链的环境中可通过标准方式编译：

```bash
go build -o varve ./cmd/varve
```

首次进入项目目录时执行 `varve memtrace setup`，CLI 会创建 `.memtrace/` 目录结构、注册项目到全局配置，并在项目根目录写入或更新 `CLAUDE.md` 与 Cursor 规则文件，使 Claude Code 与 Cursor 在打开项目时自动加载记忆工作流。v1.5.4 引入的关键修复是：若 `.memtrace` 目录已存在但全局配置中缺少项目条目，工具会自动重新注册，避免用户手工介入。`varve memtrace init` 用于补全目录与配置文件，而 `varve memtrace stats` 则可查看记忆数量与最近更新时间，便于维护。

资料来源：[cmd/varve/main.go:1-120]()、[docs/setup.md:1-80]()、[CLAUDE.md:1-60]()

## 核心概念

varve 的设计围绕几个互相依赖的概念展开，理解它们是使用后续命令与 MCP 工具的前提：

- **记忆单元（Memory）**：以 Markdown 形式持久化在 `.memtrace/memories/` 下的最小信息单元，可通过 `edit`、`import`、`export` 等命令进行增删改与跨项目迁移。v1.5.2 新增的 `markdown export/import` 即用于此场景。
- **项目注册（Project Registration）**：varve 维护一份全局项目清单，将项目路径与 `.memtrace` 目录绑定，从而在多项目环境下正确隔离检索范围。
- **语义索引（Semantic Index）**：每次写入或更新记忆时，工具会重新计算嵌入向量（v1.5.3 引入 "re-embed on memory update"），并存入本地向量存储，使 `memory_context` 与 `memory_get` 等 MCP 工具基于语义相似度而非纯关键字进行召回，召回结果被截断为摘要以控制上下文长度。
- **MCP 工具集**：通过 `memory_context`（上下文检索，带文件感知）、`memory_update`（写入或更新）、`memory_get`（按 ID 拉取）等工具与 AI 助手交互，实现"读写自动化"。
- **统计与可观测性**：`varve memtrace stats` 输出记忆数量、嵌入覆盖率与最近更新时间。

资料来源：[docs/concepts.md:1-120]()、[docs/concepts.md:120-200]()、[README.md:40-100]()

## 典型工作流

下面以"用户在 Claude Code 中提出需求"为例，说明一次完整的记忆生命周期：

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant V as varve (MCP)
    participant FS as .memtrace/

    U->>C: 提出新需求
    C->>V: 调用 memory_context
    V->>FS: 语义检索相关记忆
    FS-->>V: 返回 Top-K 摘要
    V-->>C: 注入上下文
    C->>V: 调用 memory_update
    V->>FS: 写入/更新 Markdown + 重新嵌入
    V-->>C: 确认
```

模型在回答前自动调用 `memory_context` 召回上下文；在产生新结论后调用 `memory_update` 写回，使记忆随项目演进持续累积。整个过程只需一次 `memtrace setup`，后续由 MCP 自动驱动。

**小结**：varve 通过"本地 Markdown + 语义索引 + MCP 工具"的组合，把 AI 助手的"短期对话上下文"转化为"长期项目知识库"。其安装门槛仅需一个 Go 二进制与一次 `memtrace setup`，核心抽象则是记忆单元、项目注册与语义索引三者之间的闭环。

资料来源：[README.md:100-160]()、[docs/concepts.md:200-260]()

---

<a id='page-2'></a>

## 系统架构、数据库与事件流

### 相关页面

相关主题：[概览、安装与核心概念](#page-1), [混合检索、打包、摄取与导入导出](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/kernel/kernel.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/kernel.go)
- [internal/kernel/schema.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/schema.go)
- [internal/kernel/schema_v2.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/schema_v2.go)
- [internal/kernel/migrate.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/migrate.go)
- [internal/kernel/migrate_v1.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/migrate_v1.go)
- [internal/kernel/decisions.go](https://github.com/varve-sh/varve/blob/main/internal/kernel/decisions.go)
</details>

# 系统架构、数据库与事件流

## 1. 总体架构概览

Varve 是一个面向 AI 代理与开发工作流的"记忆追踪"(memtrace) 系统，其核心由 `internal/kernel/` 目录下的若干模块构成。`kernel.go` 充当整个子系统的入口与协调者，负责注册项目、初始化本地 `.memtrace` 目录、加载模式(schema)以及分发命令与 MCP 调用请求。资料来源：[internal/kernel/kernel.go:1-120]()

整体架构可以划分为四个层次：CLI / MCP 接口层、Kernel 协调层、持久化与事件层、以及外部存储(向量索引与本地文件系统)。Kernel 通过一个统一的对象将 schema 迁移、决策日志、记忆条目与文件级元数据串联起来，从而在多个客户端(本地 CLI、Cursor、Claude 等)之间共享同一份"项目记忆"。

```mermaid
flowchart TD
    A[CLI / MCP 客户端] --> B[Kernel 入口]
    B --> C[Schema 管理<br/>schema.go / schema_v2.go]
    B --> D[迁移引擎<br/>migrate.go / migrate_v1.go]
    B --> E[决策与事件流<br/>decisions.go]
    C --> F[(本地数据库<br/>.memtrace)]
    E --> F
    D --> F
    C --> G[(向量索引<br/>语义检索)]
```

## 2. 数据库与模式管理

项目的持久化单元位于每个仓库根目录下的 `.memtrace` 目录中。Schema 由 `schema.go` 定义初版数据结构，并在 `schema_v2.go` 中引入 v2 字段(例如增强的元数据、文件级关联和语义摘要)，以支持文件感知检索(file-aware retrieval)等新功能。资料来源：[internal/kernel/schema.go:1-90]()、资料来源：[internal/kernel/schema_v2.go:1-140]()

迁移逻辑由两份文件协作完成：`migrate.go` 提供通用的版本探测与升级入口，`migrate_v1.go` 则具体执行从 v1 到 v2 的字段映射与索引重建。最新版本 v1.5.4 中新增的"如果 `.memtrace` 目录已存在但全局配置中缺少对应条目则自动重新注册项目"行为，正是由迁移入口在启动时检测并补齐缺失的配置项。资料来源：[internal/kernel/migrate.go:30-95]()、资料来源：[internal/kernel/migrate_v1.go:1-80]()

## 3. 事件流与决策记录

`decisions.go` 维护一条追加式的事件流(decision log)，用于记录每次记忆更新、嵌入重算、导入导出与人工编辑操作。每条事件至少包含时间戳、操作类型、涉及的 schema 版本以及可选的语义指纹，便于事后审计与回放。资料来源：[internal/kernel/decisions.go:1-110]()

在 v1.5.3 中引入的"记忆更新时自动重新嵌入(re-embed)"特性，会先写入一条 decision 事件，再触发向量索引的增量更新，确保事件流始终先于外部副作用生效，从而支持幂等回放。资料来源：[internal/kernel/decisions.go:60-130]()

## 4. MCP 集成与 CLI 命令

Kernel 向上暴露的工具集与 CLI 子命令通过统一调度器接入。MCP 工具包括 `memory_context`、`memory_get`、`memory_update`，分别用于按文件感知方式检索上下文、按 ID 取回条目以及更新记忆；CLI 侧则提供 `init`、`setup`、`edit`、`import`、`stats` 等命令。所有写操作最终都会经过 `decisions.go` 的事件流，再由 `migrate.go` 协调的存储层落地。资料来源：[internal/kernel/kernel.go:200-320]()

社区近期重点关注的"自动写入 Cursor 规则"以及"加强 memtrace 在 CLAUDE.md / init / setup 中的说明"功能，分别通过 `setup` 命令与项目模板注入实现，目的是让不同 AI 客户端在打开项目时即可读取到一致的上下文入口。资料来源：[internal/kernel/kernel.go:150-210]()

---

<a id='page-3'></a>

## MCP 工具与 CLI 命令参考

### 相关页面

相关主题：[概览、安装与核心概念](#page-1), [混合检索、打包、摄取与导入导出](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/mcp/server.go](https://github.com/varve-sh/varve/blob/main/internal/mcp/server.go)
- [internal/mcp/session.go](https://github.com/varve-sh/varve/blob/main/internal/mcp/session.go)
- [internal/mcp/tools.go](https://github.com/varve-sh/varve/blob/main/internal/mcp/tools.go)
- [internal/cli/root.go](https://github.com/varve-sh/varve/blob/main/internal/cli/root.go)
- [internal/cli/init.go](https://github.com/varve-sh/varve/blob/main/internal/cli/init.go)
- [internal/cli/setup.go](https://github.com/varve-sh/varve/blob/main/internal/cli/setup.go)
- [internal/cli/save.go](https://github.com/varve-sh/varve/blob/main/internal/cli/save.go)
- [internal/cli/edit.go](https://github.com/varve-sh/varve/blob/main/internal/cli/edit.go)
- [internal/cli/import.go](https://github.com/varve-sh/varve/blob/main/internal/cli/import.go)
- [internal/cli/export.go](https://github.com/varve-sh/varve/blob/main/internal/cli/export.go)
- [internal/cli/stats.go](https://github.com/varve-sh/varve/blob/main/internal/cli/stats.go)
</details>

# MCP 工具与 CLI 命令参考

varve（memtrace）项目提供两条主要交互通道：面向终端用户的 CLI 命令，以及面向 AI 助手（Claude、Cursor 等）的 MCP（Model Context Protocol）工具集。CLI 负责项目注册、数据落盘与人工干预，MCP 工具则在代理运行期间提供记忆读写能力。两者共用同一份持久化目录 `.memtrace`，从而保证 CLI 保存的记忆可被 MCP 工具即时检索 资料来源：[internal/cli/root.go:1-40]()。

## CLI 命令概览

CLI 通过 Cobra 风格的根命令 `memtrace` 统一调度，子命令按照生命周期分为三类：初始化、记忆管理与状态查询。

### 初始化类命令

- `init`：在当前目录创建 `.memtrace` 子目录并写入最小化配置文件；若目录已存在但配置项缺失（例如升级场景），v1.5.4 起会自动重新注册项目 资料来源：[internal/cli/init.go:1-60]()。
- `setup`：在初始化基础上额外注入 IDE 规则文件；v1.5.3 起会自动生成 Cursor 规则并强化 `CLAUDE.md` 中的 memtrace 提示，使代理能够识别 MCP 工具 资料来源：[internal/cli/setup.go:1-80]()。

### 记忆管理类命令

- `save`：将代理会话中的关键事实写入记忆库，触发向量化与索引刷新；v1.5.3 起在更新时会重新嵌入（re-embed）相关条目 资料来源：[internal/cli/save.go:1-90]()。
- `edit`：修改已有记忆条目的内容或标签，配合语义检索完成定位 资料来源：[internal/cli/edit.go:1-70]()。
- `import` / `export`：以 Markdown 格式批量迁移记忆；v1.5.2 引入，用于跨项目或跨机器同步 资料来源：[internal/cli/import.go:1-50]() 资料来源：[internal/cli/export.go:1-50]()。

### 状态查询类命令

- `stats`：自 v1.5.1 起提供，输出记忆库规模、索引状态与最近活动时间等聚合指标 资料来源：[internal/cli/stats.go:1-40]()。

## MCP 工具集

MCP 服务器以独立进程形式启动，向代理暴露三个核心工具，统一在 `internal/mcp/tools.go` 中注册 资料来源：[internal/mcp/tools.go:1-120]()。

| 工具名 | 主要用途 | 引入版本 |
| --- | --- | --- |
| `memory_context` | 按当前会话上下文检索相关记忆，支持文件感知过滤 | v1.5.0 |
| `memory_update` | 新增或修改记忆条目，写入后触发重新嵌入 | v1.5.0 |
| `memory_get` | 按 ID 或摘要读取单条记忆，召回时截断为摘要形式 | v1.5.2 |

服务器通过 `internal/mcp/server.go` 监听 stdio，遵循 MCP 协议进行能力声明与请求分发；会话状态由 `internal/mcp/session.go` 维护，记录代理身份与项目绑定关系 资料来源：[internal/mcp/server.go:1-100]() 资料来源：[internal/mcp/session.go:1-80]()。

## 协同工作流

CLI 与 MCP 工具共享同一配置文件和 `.memtrace` 存储目录，因此一次典型的代理会话遵循如下流程：

```mermaid
sequenceDiagram
    participant User
    participant CLI as memtrace CLI
    participant FS as .memtrace 目录
    participant MCP as MCP 服务器
    participant Agent as AI 代理

    User->>CLI: memtrace init / setup
    CLI->>FS: 写入配置与目录
    User->>Agent: 启动会话
    Agent->>MCP: 调用 memory_context
    MCP->>FS: 读取索引
    MCP-->>Agent: 返回相关记忆
    Agent->>MCP: 调用 memory_update
    MCP->>FS: 写入并触发 re-embed
    User->>CLI: memtrace stats / export
    CLI->>FS: 汇总或导出
```

CLI 用于初始化与离线维护，MCP 工具承担在线读写职责；v1.5.4 的项目重注册逻辑确保目录与配置一致，避免代理因配置缺失而无法访问记忆 资料来源：[internal/cli/init.go:30-60]()。

## 使用建议

- 首次接入项目时优先执行 `memtrace setup`，可同步获得 Cursor 规则与 `CLAUDE.md` 提示 资料来源：[internal/cli/setup.go:40-80]()。
- 在代理中频繁调用 `memory_context` 时，召回结果会被截断为摘要以节省上下文窗口 资料来源：[internal/mcp/tools.go:60-100]()。
- 跨环境迁移建议使用 `export` 生成 Markdown，再通过 `import` 导入目标项目，便于审计与版本管理 资料来源：[internal/cli/export.go:1-50]() 资料来源：[internal/cli/import.go:1-50]()。

---

<a id='page-4'></a>

## 混合检索、打包、摄取与导入导出

### 相关页面

相关主题：[系统架构、数据库与事件流](#page-2), [MCP 工具与 CLI 命令参考](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/retrieval/pipeline.go](https://github.com/varve-sh/varve/blob/main/internal/retrieval/pipeline.go)
- [internal/retrieval/scorer.go](https://github.com/varve-sh/varve/blob/main/internal/retrieval/scorer.go)
- [internal/retrieval/semantic.go](https://github.com/varve-sh/varve/blob/main/internal/retrieval/semantic.go)
- [internal/pack/pack.go](https://github.com/varve-sh/varve/blob/main/internal/pack/pack.go)
- [internal/pack/select.go](https://github.com/varve-sh/varve/blob/main/internal/pack/select.go)
- [internal/pack/estimator.go](https://github.com/varve-sh/varve/blob/main/internal/pack/estimator.go)
- [internal/pack/render.go](https://github.com/varve-sh/varve/blob/main/internal/pack/render.go)
- [internal/ingest/ingest.go](https://github.com/varve-sh/varve/blob/main/internal/ingest/ingest.go)
- [internal/ingest/embed.go](https://github.com/varve-sh/varve/blob/main/internal/ingest/embed.go)
- [internal/portable/markdown.go](https://github.com/varve-sh/varve/blob/main/internal/portable/markdown.go)
- [internal/portable/import.go](https://github.com/varve-sh/varve/blob/main/internal/portable/import.go)
- [internal/cli/recall.go](https://github.com/varve-sh/varve/blob/main/internal/cli/recall.go)
- [internal/cli/import_export.go](https://github.com/varve-sh/varve/blob/main/internal/cli/import_export.go)
</details>

# 混合检索、打包、摄取与导入导出

## 概述与边界

varve 的「混合检索、打包、摄取与导入导出」子系统负责把项目级记忆（`.memtrace` 目录中的事实、摘要与引用）在 LLM 上下文窗口内可靠地呈现。该子系统由四个相互衔接的阶段构成：

1. **混合检索**：在语义向量与结构化键值之间并行查询，并以可解释的相关度分数排序；
2. **上下文打包**：将命中条目按 token 预算裁剪、汇总并渲染为模型可消费的提示片段；
3. **摄取**：把外部文本或文件片段写回记忆库，并触发重新嵌入；
4. **导入/导出**：以 Markdown 等可读格式在仓库之间迁移记忆内容。

其作用是把「存什么」「怎么找」「怎么塞进 prompt」「怎么搬运」这四个关注点隔离，使上层的 MCP 工具（`memory_context`、`memory_get`、`memory_update`，自 v1.5.0 起陆续引入）以及 CLI 子命令（`recall`、`import`、`export`、`stats`）可以组合调用而不互相侵入。

## 混合检索

`internal/retrieval/pipeline.go` 中的流水线按顺序或并行执行三条通道：语义搜索、键值精确匹配、以及基于文件名/标签的文件感知过滤。每条通道返回候选条目与原始分数，`scorer.go` 中的混合打分器负责把异构分数归一化后线性加权。

- **语义通道**：`semantic.go` 读取嵌入索引，使用余弦相似度排序；自 v1.5.3 起，记忆更新时会自动重新嵌入（`feat: re-embed on memory update`），保证索引与原文同步。
- **结构化通道**：对 `key`/`tag` 进行精确与前缀匹配，适合确定性事实（API、配置项、文件路径）。
- **文件感知通道**：v1.5.0 引入（`feat: add memory_context MCP tool and file-aware retrieval`），当调用方传入当前文件上下文时，优先召回同目录或被同一变更触及的记忆。

混合打分公式形如 `final = α·sim + β·kv + γ·file`，三个权重在项目配置中可调；`scorer.go` 会丢弃低于阈值的候选，以减少下游打包阶段的工作量。

## 上下文打包

打包阶段（`internal/pack`）负责把检索结果变成 LLM 的提示片段，需要同时满足三项约束：

| 阶段 | 文件 | 输入 | 输出 | 关键关注点 |
|------|------|------|------|------------|
| 选择 | `select.go` | 候选条目、预算上限 | 子集 | 去重、优先级、文件归属平衡 |
| 估算 | `estimator.go` | 子集 | token 数 | 防止超出模型窗口 |
| 渲染 | `render.go` | 子集 | 提示片段 | 稳定的 Markdown/引用格式 |

当子集超过预算时，`select.go` 按 v1.5.2 引入的策略（`feat: add memory_get tool, truncate recall to summaries`）把较长条目截断为摘要，仅保留强相关条目的完整正文；`render.go` 使用稳定的分隔符与引用编号，使模型输出可反向追溯到原始记忆条目。

## 摄取与导入导出

摄取入口位于 `internal/ingest/ingest.go`，对外暴露统一的写入接口，接收来自 `memory_update` MCP 工具与 `import` CLI 命令的数据流。`embed.go` 在写入前对文本分块并触发嵌入更新，从而使下一次检索能立即看到新增内容。

`internal/portable/markdown.go` 提供 Markdown 序列化：每条记忆渲染为带 frontmatter 的小节，既可读也便于跨项目 diff（v1.5.2：`feat: add markdown export/import`）。`import.go` 在反向流程中解析 Markdown，按 frontmatter 重建键值与标签，并复用摄取管线完成嵌入落库。CLI 入口 `cli/import_export.go` 与 `cli/recall.go` 将上述能力暴露为命令行：

- `memtrace import <file.md>`：从 Markdown 重建记忆；
- `memtrace export`：把当前项目记忆输出为 Markdown；
- `memtrace recall <query>`：触发完整的「检索 + 打包」流程。

## 数据流与自愈

```mermaid
flowchart LR
    A[查询/触发] --> B[混合检索]
    B --> C[混合打分]
    C --> D[上下文打包]
    D --> E[提示片段]
    E --> F[LLM/MCP 响应]

    G[外部文本/Markdown] --> H[摄取]
    H --> I[重新嵌入]
    I --> J[(.memtrace 索引)]
    J --> B

    K[导出命令] --> L[Markdown 序列化]
    L --> M[跨项目迁移]
    M --> H
```

整个子系统都通过 `.memtrace` 目录持久化；当目录存在但全局配置缺少项目条目时，v1.5.4 引入的逻辑（`feat: re-register project if .memtrace dir exists but config entry is missing`）会主动重新注册项目，使数据流在克隆或迁移场景下自愈。

资料来源：[internal/retrieval/pipeline.go]()、[internal/retrieval/scorer.go]()、[internal/pack/select.go]()、[internal/pack/estimator.go]()、[internal/ingest/ingest.go]()、[internal/portable/markdown.go]()。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：varve-sh/varve

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

## 1. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/varve-sh/varve | Sandbox install result is missing.

## 2. 安装坑 · 可能需要本地编译工具链

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装入口或说明出现本地编译相关关键词：make install
- 对用户的影响：Windows/macOS 用户可能卡在编译依赖上。
- 复现命令：`make install`
- 证据：identity.distribution | https://github.com/varve-sh/varve | make install

## 3. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`make install`
- 证据：downstream_validation.install_status | https://github.com/varve-sh/varve | install_status=documented; command=make install

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/varve-sh/varve | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/varve-sh/varve | README/documentation is current enough for a first validation pass.

## 6. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/varve-sh/varve | quickstart_status=not_attempted; sandbox_quickstart_status=missing

## 7. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/varve-sh/varve | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/varve-sh/varve | no_demo; severity=medium

## 9. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/varve-sh/varve | No sandbox install has been executed yet; downstream must verify before user use.

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/varve-sh/varve | no_demo; severity=medium

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

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

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

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

<!-- canonical_name: varve-sh/varve; human_manual_source: deepwiki_human_wiki -->