项目简介

Via 是由 Vektor Memory 开发的开源 AI Agent 工作流构建器，作为通用集成层连接 Claude、Cursor、Windsurf 和 ChatGPT 等主流 AI 工具。通过单一 CLI 接口，Via 实现跨工具的共享记忆、任务看板和上下文总线，确保用户的工作上下文在不同工具、不同会话、不同机器之间无缝流转。

资料来源：README.md

核心价值主张

当前 AI 工具各自为政：Claude 遗忘 Cursor 中的工作，Cursor 不了解 Windsurf 的构建成果。切换工具或开启新会话时，上下文重置为零。Via 作为工具间的"总线"（bus），解决这一碎片化问题。

资料来源：README.md:项目简介

系统架构

整体架构图

graph TB
    subgraph 用户层
        CLI[CLI 命令行]
        MCP[MCP Server]
    end
    
    subgraph 核心层
        subgraph 命令模块 commands/
            context[context.mjs]
            task[task.mjs]
            ingest[ingest.mjs]
            audit[audit.mjs]
            scaffold[scaffold.mjs]
            serve[serve.mjs]
            watch[watch.mjs]
            handoff[handoff.mjs]
            status[status.mjs]
            persona[persona.mjs]
            spend[spend.mjs]
            sync[sync.mjs]
            route[route.mjs]
        end
        
        subgraph 工具层 connectors/
            claude[claude.mjs]
            cursor[cursor.mjs]
            windsurf[windsurf.mjs]
            chatgpt[chatgpt.mjs]
            langchain[langchain.mjs]
            slipstream[slipstream.mjs]
        end
        
        subgraph 公共工具 utils/
            db[db.mjs]
            config[config.mjs]
            format[format.mjs]
            detect[detect.mjs]
        end
    end
    
    subgraph 存储层
        SQLite[(SQLite 本地存储)]
        GitHub[GitHub 私有仓库]
        SlipstreamAPI[Slipstream API]
    end
    
    CLI --> commands/
    MCP --> commands/
    commands/ --> connectors/
    commands/ --> utils/
    utils --> SQLite
    sync --> GitHub
    slipstream --> SlipstreamAPI

技术栈

资料来源：package.json:engines、package.json:dependencies

核心命令详解

1. 上下文管理

#### via context

多工具上下文格式化命令，将共享记忆转换为各 AI 工具可识别的格式输出。

via context [query] [--tool claude|cursor|windsurf|chatgpt]

支持的输出格式：

资料来源：SPEC.md:6.1 via context

#### via ingest

通用知识摄入接口，从 URL、文件或目录读取内容，分块存储到本地 SQLite。

via ingest <source> [--text "内容"] [--recursive]

支持的来源：

资料来源：SPEC.md:6.10 via ingest

2. 任务管理

#### via task

基于 SQLite 的持久化任务看板，任何 AI 工具均可通过 MCP 读写。

via task add "任务描述" [--high] [--medium] [--low]
via task list
via task start <id>
via task done <id>
via task delete <id>

任务字段结构：

资料来源：SPEC.md:6.3 via task

3. 工作状态交接

#### via handoff

导出或导入 .vstate.json 会话状态文件，实现跨工具、跨机器的工作状态迁移。

# 导出当前状态
via handoff --export [--task "任务描述"] [--tool <工具名>]

# 导入已有状态
via handoff --import <file> [--to claude|cursor|windsurf|chatgpt]

# 打印格式化上下文
via handoff --print --import <file>

.vstate.json 文件格式：

{
  "via_version": "0.1.0",
  "exported_at": "2026-05-10T12:00:00Z",
  "source_tool": "cursor",
  "current_task": "Refactor auth module",
  "open_questions": ["问题1", "问题2"],
  "decisions": [
    { "at": "2026-05-10T11:30:00Z", "decision": "选择 JWT 方案" }
  ]
}

资料来源：SPEC.md:5.1 .vstate.json、SPEC.md:6.2 via handoff

4. 审计与合规

#### via audit

追加式合规日志，记录每个决策的工具、时间戳和理由。

via audit log "决策内容" --tool <工具>
via audit list
via audit search <关键词>
via audit export [--format jsonl|csv|markdown]

导出格式支持：

资料来源：SPEC.md:6.8 via audit

5. 成本追踪

#### via spend

读取所有已连接 AI 工具的用量日志，无需 API 调用，直接读取本地 JSONL 文件。

via spend today
via spend session
via spend week
via spend month
via spend leaks

数据来源：

泄漏检测模式：

• 冗长的上下文重复注入
• 工具调用循环
• 大文件重复读取
• 冗余网络请求

资料来源：SPEC.md:6.5 via spend

6. 项目脚手架

#### via scaffold

自动检测已安装的 AI 工具，向当前项目部署完整的 Via 集成配置。

via scaffold [--preset solo-dev|startup-team|enterprise-audit|research]

生成的文件：

资料来源：SPEC.md:6.6 via scaffold

7. 事件监听

#### via watch

监听 AI 工具的完成事件并触发通知。

via watch [--source desktop|webhook|slack|discord]

事件来源：

• 文件监视器（工具 JSONL 日志）
• 任务看板状态变更
• Webhook 接收器

通知目标：

资料来源：SPEC.md:6.7 via watch

8. 状态同步

#### via sync

将 Via 全部状态备份到私有 GitHub 仓库，或从仓库恢复。

via sync backup
via sync restore
via sync status
via sync diff

备份内容：

• ~/.via/config.json — 用户配置
• tasks.db — 任务看板导出
• personas/ — 角色定义
• audit.db — 审计日志导出
• spend/ — 用量日志

资料来源：SPEC.md:6.9 via sync

9. 角色管理

#### via persona

命名式 AI 角色管理，每个角色拥有独立的系统提示词和记忆命名空间。

via persona create <名称> --system "系统提示词"
via persona use <名称> [--in claude|cursor]
via persona list
via persona delete <名称>
via persona show <名称>

资料来源：SPEC.md:6.4 via persona

10. 任务路由

#### via route

根据任务描述推荐合适的 AI 工具。

via route "任务描述" [--budget <最大费用>] [--tools <工具列表>]

路由逻辑（v0.1 规则版）：

资料来源：SPEC.md:6.11 via route

11. 状态检查

#### via status

单命令健康检查，输出生态系统整体状态。

via status

示例输出：

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf ✓   chatgpt –
  memory      local SQLite · 142 facts · last store 2h ago
  slipstream  not connected  →  npx via upgrade
  tasks       3 open · 1 in-progress · 12 done
  spend       today $0.43 · week $2.18
  audit       47 decisions logged

资料来源：SPEC.md:6.12 via status

MCP 服务器模式

Via 可作为 MCP 服务器运行，将全部 12 个命令暴露为 MCP 工具，供 Claude Code、Cursor 和其他 MCP 兼容工具原生调用。

启动方式

via serve              # stdio 模式（Claude Code 默认）
via serve --sse        # HTTP + SSE 模式（远程连接）

MCP 工具列表

资料来源：SPEC.md:7. MCP server mode

Claude Desktop 配置

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

数据存储架构

本地数据目录

Via 在 ~/.via/ 目录下存储所有本地数据：

~/.via/
├── config.json             # 用户配置、连接工具、偏好设置
├── tasks.db                # SQLite：任务看板
├── audit.db                # SQLite：合规日志
├── personas/               # 每个角色的 .vpersona.json 文件
├── spend/                  # 各工具每日用量日志
└── handoffs/               # .vstate.json 导出文件

资料来源：SPEC.md:4. Data directory

安全与隐私

数据存储政策（关键声明）：

VEKTOR Memory 不会在服务器上存储您的任何数据——无论是开源还是闭源产品。您在本地机器上存储的记忆、凭证和保险库文件不会传输到任何服务器。

这适用于 Via 及所有 Vektor 产品：

• Vex（向量记忆迁移）
• Vek-Sync（MCP 配置同步、AES-256 凭证保险库）
• Via（CLI 集成层）
• Slipstream SDK

资料来源：SECURITY.md:数据存储政策

Slipstream 升级桥接

当配置 slipstream.mjs 连接器后（用户安装 Slipstream 并设置 VEKTOR_API_KEY），Via 自动将所有记忆操作路由到 Slipstream 而非 SQLite。升级透明无感——相同命令、相同格式、显著更好的效果。

功能对比

资料来源：SPEC.md:8. Slipstream upgrade bridge

快速入门

安装

Via 支持零安装使用：

npx via <命令>

或全局安装：

npm install -g @vektor/via

初始化

via init

该命令自动检测已安装的 AI 工具并写入相应配置。

资料来源：README.md:安装

版本历史

v0.1.0 (2026-05-10)

初始发布功能集：

• via ingest — URL、文件、文件夹、内联文本摄入
• via context — 多工具上下文格式化
• via task — SQLite 支撑的共享任务看板
• via audit — AI 决策合规日志
• via scaffold — 单命令项目初始化
• via serve — MCP 服务器（stdio + HTTP+SSE）
• via watch — 桌面和 Webhook 事件路由
• via handoff — 跨工具工作状态导出/导入
• via status — 生态系统健康仪表盘
• via persona — 命名 AI 角色管理
• via spend — AI 成本追踪
• via sync — 多机器状态同步
• via upgrade — Slipstream 升级桥接

已修复问题：

• ESM 兼容性：所有连接器替换 require() 为顶层 import
• Cursor scaffold：按 Cursor >=0.45 规范写入 .cursor/rules/via-context.mdc
• SSE 服务器：POST 处理器移除广播（响应作用域限定为调用方）
• Windows 桌面通知：替换阻塞 MessageBox 为非阻塞 BalloonTip
• 审计导出：成功日志移至 finish 事件内（刷新后触发）

资料来源：CHANGELOG.md

与 Vektor 生态的关系

┌─────────────────────────────────────────────────────────────┐
│                    Vektor 生态系统                          │
├──────────────┬──────────────────┬────────────────────────────┤
│    Vex       │     Vek-Sync    │           Via              │
│ Vector       │     Vektor      │           Vektor           │
│ Exchange     │     Sync        │           Memory           │
├──────────────┼──────────────────┼────────────────────────────┤
│ 向量存储      │     MCP 配置     │    AI 工具集成与上下文路由  │
│ 迁移工具      │     同步工具     │    跨工具记忆总线           │
└──────────────┴──────────────────┴────────────────────────────┘
                        ↓
              ┌─────────────────────┐
              │     Slipstream      │
              │    intelligence     │
              │    引擎（可选）       │
              └─────────────────────┘

资料来源：SPEC.md:10. Naming、README.md:Vektor 生态系统

社区反响

根据社交媒体和社区讨论，Via 受到以下关注：

社区用户特别指出 Via 的独特价值在于其"一个其他工具没有的功能"——能够连接多个 AI Agent 并通过 MCP 实现自我管理。

资料来源：社区上下文

总结

Via 作为开源 AI Agent 工作流构建器，通过 MCP 协议和本地 SQLite 存储实现了：

1. 上下文连续性 — 记忆在工具间无缝流转
2. 任务协同 — 共享任务看板供所有工具读写
3. 合规审计 — 完整决策追踪链
4. 成本透明 — 跨工具用量追踪
5. 灵活部署 — CLI 和 MCP 两种使用模式

作为 Vektor 生态系统的一部分，Via 可与 Vex、Vek-Sync 协同工作，并在升级到 Slipstream 后获得更强大的语义搜索和图遍历能力。

系统要求

Via 基于 Node.js 18+ 原生特性构建，依赖环境简单明确：

资料来源：package.json:28

Via 使用纯 JavaScript ESM 模块编写，无需编译步骤。所有命令均通过 via.mjs 主入口文件调用，代码结构清晰，调试友好。

安装方式

方式一：npx 零安装（推荐）

无需全局安装，直接使用 npx 命令运行：

npx via <command>

这种方式每次会拉取最新版本，适合快速试用和临时场景。资料来源：SPEC.md:4.9

方式二：npm 全局安装

对于频繁使用的场景，建议全局安装：

npm install -g @vektor/via

安装完成后，via 命令全局可用：

via --version
via --help

资料来源：README.md:安装

方式三：源码运行

克隆仓库后可直接运行源码：

git clone https://github.com/Vektor-Memory/Via.git
cd Via
node via.mjs <command>

源码运行方式便于调试和二次开发，Via 遵循与 Vex、Vek-Sync 相同的技术规范，入口文件为 .mjs 格式。资料来源：SPEC.md:4.9

初始配置

via init 命令

Via 的核心配置通过 via init 命令完成，该命令会自动完成以下工作：

1. 检测已安装的 AI 工具：自动识别 Claude Code、Cursor、Windsurf、ChatGPT
2. 配置 MCP 连接：为已检测到的工具生成 MCP 服务器配置
3. 创建本地数据目录：在 ~/.via/ 下初始化所需文件
4. 写入项目级配置：在当前目录生成 via.config.json 资料来源：README.md:via-init

via init

执行后，Via 会输出已连接的 AI 工具列表：

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf –   chatgpt –
  memory      local SQLite · 0 facts · last store never
  slipstream  not connected  →  npx via upgrade

资料来源：SPEC.md:6.12

数据目录结构

Via 将所有数据存储在用户主目录下的 ~/.via/ 目录中：

~/.via/
├── config.json             # 全局配置，包含连接的 AI 工具列表
├── tasks.db                # SQLite 数据库：任务看板数据
├── audit.db                # SQLite 数据库：合规审计日志
├── personas/               # AI 人设文件目录（.vpersona.json）
├── spend/                  # AI 工具使用日志（按工具/日期分类）
└── handoffs/               # 工作状态导出文件（.vstate.json）

资料来源：SPEC.md:4

本地安装使用 SQLite 存储，无嵌入向量、无 API 调用调用进行索引。当需要语义搜索或团队共享上下文时，可升级到 Vektor Slipstream。资料来源：README.html:Vektor ecosystem

配置文件详解

#### config.json 全局配置

~/.via/config.json 存储 Via 的全局配置：

{
  "via_version": "0.1.0",
  "slipstream": {
    "connected": false,
    "endpoint": null
  },
  "tools": {
    "claude": { "enabled": true, "path": "~/.claude" },
    "cursor": { "enabled": true, "path": "~/.cursor" },
    "windsurf": { "enabled": false },
    "chatgpt": { "enabled": false }
  },
  "preferences": {
    "notifications": true,
    "autoSync": false
  }
}

#### via.config.json 项目级配置

在项目根目录生成的 via.config.json 定义项目级 Via 配置：

{
  "project": "./",
  "preset": "solo-dev",
  "mcp": {
    "via": { "command": "via", "args": ["serve"] }
  }
}

支持的 Preset 预设值：solo-dev（个人开发）、startup-team（创业团队）、enterprise-audit（企业审计）、research（研究场景）。资料来源：SPEC.md:6.6

MCP 服务器配置

Via 可作为 MCP 服务器运行，向连接的 AI 工具暴露其全部命令作为 MCP 工具。

启动 MCP 服务器

via serve           # stdio 模式（适用于 Claude Desktop、Cursor）
via serve --sse     # HTTP+SSE 模式（适用于 Windsurf 和 Web 集成）

资料来源：README.md:via serve

Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加 Via：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

资料来源：README.md:Claude Desktop 配置

Cursor 配置

Cursor 的 MCP 配置位于 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "via": {
      "command": "npx",
      "args": ["via", "serve"]
    }
  }
}

Via scaffold 命令会为 Cursor >= 0.45 版本自动写入 .cursor/rules/via-context.mdc 规则文件。资料来源：CHANGELOG.md:Fixed

MCP 工具列表

当 Via 作为 MCP 服务器运行时，可用的 MCP 工具包括：

资料来源：README.md:MCP Tools

工具集成

via scaffold 命令

scaffold 命令用于为已检测到的 AI 工具部署完整的 Via 集成配置：

via scaffold

该命令会写入以下文件：

• .cursor/rules/via-context.mdc — Cursor 上下文注入规则
• .claude/CLAUDE.md — Claude 上下文块
• ~/.via/config.json — 更新项目配置
• via.config.json — 项目级 Via 配置

资料来源：SPEC.md:6.6

支持的工具

Via 当前支持与以下 AI 工具集成：

资料来源：SPEC.md:6.12, README.html:via init

验证安装

via status 命令

使用 via status 命令检查 Via 生态系统健康状态：

via status

输出示例：

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf ✓   chatgpt –
  memory      local SQLite · 142 facts · last store 2h ago
  slipstream  not connected  →  npx via upgrade
  tasks       3 open · 1 in-progress · 12 done
  spend       today $0.43 · week $2.18
  audit       47 decisions logged

资料来源：SPEC.md:6.12

快速功能测试

安装完成后，可通过以下命令验证各模块功能：

# 验证任务管理
via task add "测试任务" --high
via task

# 验证记忆存储
via memory add --file ./src/
via memory list

# 验证审计日志
via audit log "测试决策" --tool cursor
via audit list

安全注意事项

Via 的数据存储策略遵循「数据不上云」原则：

• 所有数据存储在本地 ~/.via/ 目录
• 不向外部服务器发送任何用户数据
• 配置文件和数据库文件由用户完全控制

资料来源：SECURITY.md:数据存储策略

重要提醒：Vektor Memory 团队永远不会通过任何渠道要求用户提供：

• 个人身份信息
• AES-256 凭证库文件或密码
• API 密钥、令牌或许可证密钥
• 任何 VEKTOR 工具存储或生成的文件

资料来源：SECURITY.md:重要提示

升级到 Slipstream

Via 本地模式使用 SQLite 进行关键词搜索。如需语义搜索、图遍历或团队共享上下文，可升级到 Vektor Slipstream：

npx via upgrade

Slipstream 是 Vektor 生态的智能引擎，提供图记忆、向量搜索和多模态能力。资料来源：README.html:Vektor ecosystem

常见问题

MCP 连接失败

如果 AI 工具无法连接 Via MCP 服务器，检查：

1. via serve 是否正在运行
2. MCP 配置文件是否正确写入
3. via status 是否显示工具已连接

数据同步问题

跨机器使用时，可使用 via sync 命令备份和恢复 Via 状态：

via sync backup    # 备份到 GitHub 私有仓库
via sync restore   # 从备份恢复

该功能与 Vek-Sync 采用相同的方案，支持冲突检测。资料来源：SPEC.md:6.9

系统要求与安装

环境要求

Via 采用零依赖设计，核心仅依赖 sql.js。不支持 CommonJS 的旧版 Node 环境。

安装方式

Via 提供两种使用方式：

方式一：直接运行（推荐）

npx via <command>

此方式无需全局安装，每次自动获取最新版本。

方式二：全局安装

npm install -g @vektor/via
# 或
yarn global add @vektor/via

安装完成后，可直接使用 via 命令：

via --version

初始化配置

首次使用需要运行初始化命令，Via 将自动检测已安装的 AI 工具并完成配置。

自动初始化

via init

初始化过程执行以下操作：

1. 检测已安装的 AI 编程工具（Claude Code、Cursor、Windsurf）
2. 创建用户配置文件 ~/.via/config.json
3. 为每个检测到的工具生成上下文注入规则
4. 配置 MCP 服务器连接

初始化参数

示例：使用团队预设初始化

via init --preset startup-team

初始化完成后，Via 显示连接状态：

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf ✓   chatgpt –
  memory      local SQLite · 0 facts · last store never
  tasks       0 open · 0 done

核心命令速查

命令概览

代码索引与搜索

关系感知索引

Via 的 memory 命令从代码中提取符号定义和导入关系，构建本地 SQLite 图数据库。与传统关键词搜索不同，它能够追踪依赖链。

基本用法

# 索引整个源码目录
via memory add --file ./src/

# 搜索符号及其依赖
via memory search "auth"

# 查看索引统计
via memory list

搜索结果示例

┌─ MEMORY — SEARCH: auth ───────────────────────
│
│  Direct matches (2 files)
│    ● auth.js       ./src/auth.js
│    ● config.js     ./src/config.js
│
│  Related via imports (3 files)
│    ○ server.js     ./src/server.js
│    ○ middleware.js ./src/middleware.js
│    ○ routes.js     ./src/routes/auth.js
└───────────────────────────────────────────────

支持的语言

Via 支持从以下语言的代码中提取符号和导入关系：

• JavaScript / TypeScript
• Python
• Go
• Rust
• Java
• C / C++

索引数据存储在 ~/.via/memory.db 中，采用无服务器架构，所有查询在本地完成。

任务看板

概述

via task 提供 SQLite 后端的持久化任务看板，支持所有连接的 AI 工具通过 MCP 访问。

任务生命周期

graph LR
    A[add] --> B[open]
    B --> C[start]
    C --> B
    C --> D[done]
    D --> E[归档]
    B --> F[blocked]
    F --> B

常用操作

# 添加任务
via task add "实现用户认证模块" --high

# 列出所有任务
via task

# 标记进行中
via task start <task-id>

# 完成任务
via task done <task-id>

# 删除任务
via task delete <task-id>

任务字段说明

MCP 服务器模式

Via 可作为 MCP 服务器运行，使 Claude Desktop、Cursor 和 Windsurf 能够直接调用 Via 工具。

启动方式

# 标准 I/O 模式（适用于 Claude Desktop 和 Cursor）
via serve

# HTTP + SSE 模式（适用于远程连接）
via serve --sse

Claude Desktop 配置

在 ~/.claude.json 中添加：

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

可用 MCP 工具

SSE 模式参数

工作状态传递

Handoff 功能

使用 via handoff 导出当前工作状态，在切换 AI 工具时保持上下文连续性。

使用流程

graph TD
    A[在 Claude Code 中工作] --> B[via handoff --export]
    B --> C[生成 .vstate.json]
    C --> D[切换到 Cursor]
    D --> E[via handoff --import ./xxx.vstate.json]
    E --> F[恢复完整上下文]

命令示例

# 导出当前状态
via handoff --export

# 导入状态文件
via handoff --import ./sprint3.vstate.json

# 列出可用的handoff文件
via handoff --list

# 打印格式化上下文（用于手动粘贴）
via handoff --import ./handoff.vstate.json --print

导出的状态文件格式

{
  "via_version": "0.1.0",
  "exported_at": "2026-05-10T12:00:00Z",
  "source_tool": "cursor",
  "current_task": "重构认证模块 — 提取令牌验证",
  "open_questions": [
    "刷新令牌应存储在 Redis 还是 PostgreSQL？",
    "是否需要与 v1 令牌向后兼容？"
  ],
  "decisions": [
    {
      "at": "2026-05-10T11:30:00Z",
      "decision": "使用 JWT 作为访问令牌"
    }
  ]
}

工具对比与路由

智能路由

via ask 根据任务描述推荐合适的 AI 工具：

# 自动推荐并打开工具
via ask "解释这个微服务架构"

# 强制使用指定工具
via ask "重构认证模块" --tool cursor

# 仅推荐，不打开
via ask "总结这段代码" --no-open

路由规则（v0.1）

响应对比

via diff 允许你将同一问题提交给多个工具并比较回答：

# 记录问题
via diff "解释微服务"

# 添加各工具的回答
via diff add claude "微服务将应用拆分为小型独立服务..."
via diff add cursor "微服务是小型专注的服务，通过 API 通信..."

# 显示对比结果
via diff show

数据存储位置

Via 在本地存储所有数据，不上传至任何服务器。

~/.via/
├── config.json          # 用户配置、连接的工具列表
├── memory.db            # SQLite：代码索引数据
├── tasks.db             # SQLite：任务看板
├── audit.db             # SQLite：合规日志
├── personas/            # AI 人设配置文件（.vpersona.json）
├── spend/               # 各工具每日使用日志
└── handoffs/            # 导出的状态文件（.vstate.json）

数据隐私说明

根据项目 SECURITY.md 的承诺，Vektor Memory 不会存储任何用户数据。所有配置文件、记忆数据和任务记录均保存在本地机器上，永不离开用户的设备。

常见问题

初始化时检测不到工具

确保目标工具已正确安装并首次运行过。以下是检测逻辑：

1. Claude Code：检查 ~/.claude/ 目录是否存在
2. Cursor：检查 ~/.cursor/ 目录是否存在
3. Windsurf：检查 ~/.windsurf/ 目录是否存在

手动指定工具：

via init --force --no-detect
# 然后手动编辑 ~/.via/config.json 添加工具

MCP 服务器连接失败

1. 确认 Via 已安装：via --version
2. 检查 Claude Desktop 配置是否正确
3. 重启 Claude Desktop 以加载更新后的配置
4. 使用 via status 检查 MCP 服务器状态

索引搜索无结果

索引数据可能不存在或过期：

# 重新索引
via memory add --file ./src/

# 清空并重建
via memory clear
via memory add --file ./src/

下一步

• 查看 SPEC.md 了解完整的命令规范
• 查看 CHANGELOG.md 了解版本更新
• 访问 Vektor Memory 官网 了解更多产品信息
• 如遇问题，发送邮件至 [email protected]

设计理念

本地优先架构

Via 记忆系统采用纯本地存储策略，不依赖任何云端 API 或外部服务：

资料来源：SPEC.md

关系感知索引

传统代码搜索仅匹配文本，而 Via 记忆系统构建代码的导入图（Import Graph），支持关系感知的智能检索：

graph TD
    A[搜索关键词: auth] --> B[直接匹配文件]
    A --> C[导入关系追踪]
    B --> D[auth.js / config.js]
    C --> E[server.js]
    C --> F[middleware.js]
    C --> G[routes/auth.js]
    D --> H[返回完整依赖链]

这种设计使得搜索 "auth" 不仅返回包含该词的文档，还能返回所有通过导入关系连接到 auth 模块的文件。

资料来源：README.md - via memory

核心组件

1. memory 命令模块

commands/memory.mjs 是记忆系统的主入口，处理所有内存相关的操作：

支持的编程语言：

• JavaScript / TypeScript (.js, .jsx, .ts, .tsx)
• Python (.py)
• Go (.go)
• Rust (.rs)
• 其他主流语言

资料来源：commands/memory.mjs

2. SQLite 数据库适配器

utils/db.mjs 封装了所有数据库操作，提供统一的存储接口：

// 核心功能
- SQLite 连接管理
- 索引表创建与迁移
- 符号（Symbol）CRUD 操作
- 导入边（Import Edge）存储
- 全文搜索支持

数据存储位置：~/.via/memory.db

资料来源：utils/db.mjs

3. 知识摄取模块

commands/ingest.mjs 处理非代码类知识的摄入：

所有摄入内容会被分块（Chunked）后存入本地 SQLite，供后续检索使用。

资料来源：commands/ingest.mjs

数据模型

符号表（Symbols Table）

CREATE TABLE symbols (
  id INTEGER PRIMARY KEY,
  file_path TEXT NOT NULL,
  symbol_name TEXT NOT NULL,
  symbol_type TEXT,        -- function, class, const, var, etc.
  line_number INTEGER,
  definition TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

导入边表（Import Edges Table）

CREATE TABLE import_edges (
  id INTEGER PRIMARY KEY,
  source_file TEXT NOT NULL,
  target_file TEXT NOT NULL,
  import_statement TEXT,
  import_type TEXT,        -- direct, wildcard, relative, absolute
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

知识块表（Knowledge Chunks Table）

CREATE TABLE chunks (
  id INTEGER PRIMARY KEY,
  source_type TEXT,        -- url, file, text, directory
  source_path TEXT,
  content TEXT NOT NULL,
  chunk_index INTEGER,
  metadata JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

使用流程

基本索引操作

# 索引单个文件
via memory add --file ./src/auth.js

# 索引整个目录
via memory add --file ./src/

# 索引并跟踪所有导入关系
via memory add --file ./src/ --recursive

关系感知搜索

via memory search "auth"

输出示例：

┌─ MEMORY — SEARCH: auth ───────────────────────
│
│  Direct matches (2 files)
│    ● auth.js       ./src/auth.js
│    ● config.js     ./src/config.js
│
│  Related via imports (3 files)
│    ○ server.js     ./src/server.js
│    ○ middleware.js ./src/middleware.js
│    ○ routes.js     ./src/routes/auth.js
└───────────────────────────────────────────────

知识摄取

# 从 URL 摄取
via ingest https://docs.example.com/api-guide

# 从文件摄取
via ingest ./docs/architecture.md

# 从目录递归摄取
via ingest ./docs/ --recursive

# 直接文本
via ingest --text "JWT token should expire in 24 hours"

资料来源：README.md - via ingest

上下文检索

通过 commands/context.mjs，记忆内容可以格式化为各 AI 工具可消费的上下文格式：

# 获取当前记忆上下文
via context

# 指定工具格式
via context --tool cursor

# 包含特定搜索结果
via context --include "auth middleware"

资料来源：commands/context.mjs

状态同步

commands/sync.mjs 支持跨设备同步记忆状态：

# 备份记忆到 GitHub 私有仓库
via sync backup

# 恢复记忆状态
via sync restore

# 查看同步状态
via sync status

# 比较本地与远程差异
via sync diff

同步内容包括：

• memory.db 完整数据库
• ~/.via/config.json 配置
• personas/ 角色定义
• audit.db 审计日志

资料来源：commands/sync.mjs

MCP 工具接口

当 Via 以 MCP 服务器模式运行时（via serve），记忆系统暴露以下工具：

// MCP 工具调用示例
{
  "name": "via_memory_search",
  "arguments": {
    "query": "authentication flow",
    "limit": 10
  }
}

Claude Desktop / Cursor 配置示例：

{
  "mcpServers": {
    "via": { "command": "via", "args": ["serve"] }
  }
}

配置选项

记忆系统行为通过 ~/.via/config.json 配置：

{
  "memory": {
    "indexLanguages": ["js", "ts", "py", "go", "rs"],
    "excludePatterns": ["node_modules/**", "dist/**", ".git/**"],
    "chunkSize": 1000,
    "dbPath": "~/.via/memory.db"
  },
  "slipstream": {
    "enabled": false,
    "endpoint": null,
    "apiKey": null
  }
}

升级路径：Slipstream

本地 SQLite 记忆系统可通过 Slipstream 升级获得高级能力：

升级命令：

via upgrade
# 或
npx via upgrade

资料来源：SPEC.md - Slipstream

性能特性

索引性能

• 增量索引：仅处理自上次索引后变更的文件
• 并行处理：支持多核 CPU 并发解析
• 流式写入：大批量索引时使用批量 INSERT

查询性能

• 索引加载时间：< 100ms（通常 < 50ms）
• 搜索响应时间：< 200ms（千级文件规模）
• 内存占用：约 10-50MB（取决于项目规模）

安全与隐私

所有记忆数据严格本地存储：

• 数据位置：~/.via/ 目录
• 传输加密：同步到 GitHub 使用 HTTPS
• 密钥管理：通过 via vault 使用 AES-256 加密敏感信息
• 零云存储：Via 服务器不存储任何用户数据

资料来源：SECURITY.md

故障排除

最佳实践

1. 定期索引：在重要代码变更后执行 via memory add
2. 增量更新：避免频繁全量重建索引
3. 关键词优化：搜索时使用准确的函数/变量名
4. 上下文注入：切换工具前执行 via context 确保记忆传递
5. 定期备份：使用 via sync backup 防止数据丢失

功能概述

任务看板提供以下核心能力：

• 持久化存储：所有任务存储在本地 SQLite 数据库 (~/.via/tasks.db)，不依赖云服务
• 跨工具访问：通过 MCP 服务器暴露任务操作，任何连接的 AI 工具都能读写同一任务列表
• 状态流转：支持完整的工作流状态（open → in-progress → done/blocked）
• 元数据跟踪：记录任务创建时间、更新时间、关联工具和 AI 角色

架构设计

数据模型

任务看板使用 SQLite 作为存储后端，数据表结构如下：

模块依赖

graph TD
    A[CLI via task] --> B[commands/task.mjs]
    B --> C[utils/db.mjs]
    C --> D[~/.via/tasks.db]
    E[MCP Server] --> B
    F[其他 AI 工具] --> E

任务命令模块依赖底层的数据库工具类，该类封装了 SQLite 的初始化和 CRUD 操作。资料来源：utils/db.mjs:1-50

命令接口

子命令列表

任务状态流转

stateDiagram-v2
    [*] --> open: add
    open --> in_progress: start/update
    in_progress --> done: done
    in_progress --> blocked: update --blocked
    blocked --> in_progress: start/update
    open --> blocked: update --blocked
    done --> [*]

使用示例

#### 创建任务

via task add "实现用户认证模块" --high
via task add "修复登录页面样式问题"
via task add "编写 API 文档" --tool cursor --persona developer

#### 查看任务

via task              # 默认列出所有任务
via task list         # 显式列出任务
via task list --open  # 仅显示 open 状态任务

#### 更新任务状态

via task start <id>   # 开始处理任务 (in-progress)
via task done <id>    # 标记完成
via task update <id> --title "新标题"  # 修改标题
via task update <id> --blocked  # 标记为阻塞状态

#### 删除任务

via task delete <id>

MCP 工具接口

当 Via 以 MCP 服务器模式运行时 (via serve)，任务看板暴露以下 MCP 工具供 AI 代理调用：

资料来源：README.md:100-120

MCP 配置示例

在 Claude Desktop 或 Cursor 中配置 Via MCP 服务器：

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

数据存储

存储路径

任务数据存储在用户主目录下的 Via 配置目录：

~/.via/
├── tasks.db    # SQLite 数据库文件
├── audit.db    # 审计日志数据库
├── personas/   # AI 角色配置
└── ...

数据库初始化

首次运行任何任务命令时，Via 会自动创建数据库文件和必要的表结构。资料来源：utils/db.mjs:20-40

与其他模块的集成

与 Watch 模块集成

via watch 命令可以监听任务看板的状态变化，当任务被创建、更新或完成时触发通知。

支持的通知目标：

• desktop：系统桌面通知
• slack：通过 Webhook 发送到 Slack
• discord：通过 Webhook 发送到 Discord
• webhook：任意自定义 URL

与 Audit 模块集成

任务操作会自动记录到审计日志中，便于追踪决策历史和任务变更轨迹。

与 Slipstream 升级集成

常见问题

Q: 任务数据是否跨设备同步？

当前版本任务数据仅存储在本地。如需多设备同步，可使用 via sync 命令将状态备份到私有 GitHub 仓库。

Q: 如何查看任务历史？

使用 via audit log --task <id> 可查看特定任务的所有变更记录。

Q: 支持批量操作吗？

当前 CLI 不支持批量操作，但通过 MCP 接口可以编写脚本实现批量任务管理。

版本历史

• v0.1.0 (2026-05-10)：初始发布，完整的任务看板功能
• 修复了任务状态更新时的时区问题
• 优化了任务列表的显示格式

资料来源：CHANGELOG.md:1-20

相关文档

• Via 主文档
• MCP 服务器配置
• 审计日志
• Slipstream 升级

功能概述

via diff 是 Via 提供的"比较 AI 工具侧边差异"功能，号称是其他工具不具备的特性。用户可以向 Claude 和 Cursor 提出相同问题，然后精确地观察它们在哪些方面达成共识、在哪些方面产生分歧，以及每个工具带来了哪些独特的概念和术语。

资料来源：README.md:1-50

工作原理

命令流程

via diff "your prompt"          # 注册一个新的对比任务
via diff add claude "..."       # 存储 Claude 的响应
via diff add cursor "..."       # 存储 Cursor 的响应
via diff show                   # 展示并排对比 + 独有术语
via diff list                   # 列出所有已保存的对比

资料来源：README.md:45-60

对比输出格式

执行 via diff show 后，系统输出如下格式的对比结果：

┌─ DIFF — explain microservices ────────────────
│ claude          12 words
│ cursor          14 words
│ similarity      21% word overlap
│
│  claude                          |  cursor
│  ──────────────────────────────  |  ──────────────────────────────
│  Microservices split apps into   |  Microservices are small focused
│  small independent services...   |  services that communicate via...
│
│ claude unique terms  independent, database
│ cursor unique terms  focused, communicate, deployed
└───────────────────────────────────────────────

资料来源：README.md:30-45

技术实现

架构设计

Via 作为统一的 AI 工具集成层，通过标准化的接口连接不同的 AI 助手。via diff 功能依赖于底层的连接器架构：

资料来源：SPEC.md:1-30

数据存储

对比结果存储在 Via 的本地数据目录中：

~/.via/
├── config.json             # 用户配置
├── diff/                   # diff 对比结果存储
└── handoffs/               # 会话状态导出

核心特性

相似度计算

系统通过词重叠率（word overlap）计算两个 AI 工具响应的相似度：

独有术语提取

系统自动识别并提取每个工具的独有术语（unique terms），帮助用户快速发现两个工具在表达同一概念时的差异。

并排展示

将两个响应以表格形式并排展示，左侧为 Claude 输出，右侧为 Cursor 输出，便于垂直对比。

使用场景

代码审查

当不确定某个代码修改应该采用哪种方案时，可以同时询问两个工具，对比它们的实现思路：

via diff "refactor auth module with JWT"
via diff add claude "方案A：使用 passport.js..."
via diff add cursor "方案B：使用自定义中间件..."
via diff show

架构设计讨论

对于系统设计问题，不同工具可能提供不同视角：

via diff "explain microservices"
via diff add claude "Microservices split apps into small independent services..."
via diff add cursor "Microservices are small focused services that communicate via APIs..."

学习对比

通过对比学习不同工具对同一概念的解释，扩展知识视野：

与其他 Via 命令的集成

与 `via context` 集成

对比完成后，可以将差异分析添加到共享上下文中供后续会话使用：

via context add --from diff "microservices-comparison-2026"

与 `via handoff` 集成

对比结果可以包含在工作状态导出中：

via handoff --export --task "compare auth approaches"

资料来源：SPEC.md:30-60

MCP 工具支持

当 Via 以 MCP 服务器模式运行时，via diff 功能也可通过 MCP 工具调用：

{
  "mcpServers": {
    "via": { "command": "via", "args": ["serve"] }
  }
}

支持的 MCP 工具包括：

版本信息

v0.1.0 发布特性

via diff 在 Via 0.1.0 版本中作为核心功能发布：

资料来源：CHANGELOG.md:1-20

路线图

v0.4 规划中：

• via diff --live 实时对比模式
• 支持更多 AI 工具接入
• 增强的相似度算法

资料来源：README.md:120-140

社区反馈

根据社区讨论，Via 的 MCP 通用集成特性和 via diff 功能受到开发者关注：

• Reddit 用户评价 Via 为"MCP 通用集成层 CLI 工具"，认为其具有其他工具不具备的功能
• 社区讨论涉及 MCP 工具选择、跨工具上下文共享等话题

资料来源：社区上下文 - Reddit LocalLLaMA

限制与注意事项

当前限制

1. 相似度计算简单：目前仅基于词重叠率，未使用语义向量相似度
2. 本地存储：对比结果仅存储在本地 SQLite 中
3. 工具支持有限：当前主要支持 Claude 和 Cursor

升级路径

通过升级到 Slipstream，可以获得更高级的对比能力：

资料来源：SPEC.md:80-100

核心设计理念

文件转换管道是 Via 生态系统中的重要组成部分，它解决了 AI Agent 工作流中常见的数据格式兼容问题。在多工具协作场景下，不同的 AI 工具可能对输入格式有不同的要求，Via 的转换管道能够在不离开本地环境的情况下完成格式转换。

该管道的核心特点包括：

• 本地化处理：所有文件转换都在用户本地机器上执行，不存在云端传输
• 可选的记忆集成：转换完成后可自动将内容摄入 Via 的知识库
• 广泛的格式支持：覆盖图像、音频、视频、文档、办公文件、PDF 和压缩包等主流格式
• 工具依赖管理：提供工具检查功能，帮助用户确认所需的外部依赖是否已安装

资料来源：README.md - via convert

支持的格式矩阵

Via 的转换管道支持多种输入输出格式组合，以下是详细的格式支持表：

图像格式

音频格式

视频格式

文档格式

办公文档格式

PDF 格式

压缩包格式

资料来源：README.md - Supported formats

外部工具依赖

Via 的文件转换管道依赖一系列外部命令行工具来处理不同类型的格式转换。这些工具需要用户手动安装，Via 提供了检查命令来帮助用户确认依赖状态。

用户可以通过以下命令检查已安装的工具：

via convert --check

该命令会扫描系统PATH，检测上述工具是否可用，并报告缺失的依赖项。

资料来源：README.md - External tools required

命令行接口

基本用法

via convert 命令提供了直观易用的命令行接口，支持单文件转换和批量处理：

# 转换单个文件
via convert <file> --to <format>

# 转换并摄入到记忆系统
via convert <file> --to md --ingest

# 检查已安装的转换工具
via convert --check

# 列出所有支持的格式
via convert --formats

参数说明

资料来源：README.md - via convert

转换流程架构

graph TD
    A[用户输入] --> B[文件类型检测]
    B --> C{检测结果}
    C -->|图像| D[ImageMagick 处理]
    C -->|音频/视频| E[FFmpeg 处理]
    C -->|文档| F[Pandoc 处理]
    C -->|Office| G[LibreOffice 处理]
    C -->|PDF| H[Poppler 处理]
    C -->|压缩包| I[7-Zip 处理]
    D --> J[输出文件]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K{是否 --ingest?}
    K -->|是| L[摄入到记忆系统]
    K -->|否| M[完成]
    L --> M

与记忆系统的集成

via convert 命令的一个重要特性是与 Via 记忆系统的深度集成。通过 --ingest 标志，转换后的文件内容会自动摄入到 Via 的知识库中，使后续的 via memory search 等命令能够检索到这些内容。

这种集成的典型使用场景包括：

1. 文档数字化：将 PDF 转换为 Markdown 后摄入知识库
2. 格式标准化：将各类文档转换为统一的 Markdown 格式
3. 内容提取：从 Office 文档或 PDF 中提取文本并建立索引

集成记忆系统的转换管道遵循以下流程：

via convert ./report.pdf --to md --ingest
# → 1. 使用 Poppler 提取 PDF 文本
# → 2. 转换为 Markdown 格式
# → 3. 自动调用 via ingest 将内容存储到 SQLite 知识库
# → 4. 内容可被 via memory search 检索

资料来源：README.md - via ingest 和 SPEC.md - via ingest

在 AI Agent 工作流中的角色

在 Via 的多工具协作生态系统中，文件转换管道承担着关键的桥接角色。用户和社区反馈表明，跨工具工作时经常遇到格式兼容问题，而 Via 的转换管道提供了一种统一的解决方案。

根据社区讨论，Via 作为一个 MCP 通用集成层，能够连接 Qwen、Claude Code、Codex 等多种 AI 工具。在这种多工具协作场景下，文件格式的兼容性尤为重要：

• Claude Code 可能生成某种格式的输出
• Cursor 需要另一种格式的输入
• Via 的转换管道可以在工具之间建立无缝的数据流

资料来源：Reddit - MCP universal integration layer

版本历史

v0.1.0 (2026-05-10)

初始版本发布，包含完整的文件转换功能：

• 支持图像、音频、视频、文档、办公文件、PDF 和压缩包格式
• 提供 --check 工具检查功能
• 提供 --formats 格式列表功能
• 支持 --ingest 选项与记忆系统集成

资料来源：CHANGELOG.md - Initial release

技术实现细节

Via 的文件转换管道基于 Node.js 18+ 的原生模块实现，不依赖外部的 node-fetch 库，使用内置的 fetch API 进行必要的网络操作。

依赖项管理方面，转换管道仅依赖 sql.js（版本 ^1.14.1）用于 SQLite 知识库的读写操作，所有格式转换本身由外部工具完成。

资料来源：package.json - dependencies

故障排除

常见问题

Q: 转换命令提示工具未找到怎么办？

A: 使用 via convert --check 检查缺失的外部工具，然后按照系统包管理器安装相应工具。

Q: 某些格式转换失败？

A: 确认目标格式在支持矩阵中，检查输入文件是否损坏，确保对应工具已正确安装并位于系统 PATH 中。

Q: --ingest 选项不生效？

A: 确认 Via 的 SQLite 数据库可正常读写，检查文件内容是否为空或格式异常。

概述

MCP 服务器模式是 Via 的核心功能之一，允许 Via 作为 Model Context Protocol (MCP) 服务器运行，使 Claude Code、Cursor、Windsurf 等支持 MCP 协议的 AI 工具能够直接调用 Via 的全部功能。通过标准化的 MCP 接口，Via 将其 12 个命令以原生工具的形式暴露给 AI 代理，实现跨工具的上下文共享、任务管理和记忆同步。资料来源：SPEC.md:7-12

核心能力

Via 的 MCP 服务器模式提供以下核心能力：

• 标准化接口：将 Via 的所有命令转换为符合 MCP 协议的工具定义
• 双向通信：支持 stdio 和 HTTP+SSE 两种通信模式
• 跨工具集成：Claude Desktop、Cursor、Windsurf 等工具均可通过 MCP 调用 Via
• 透明升级：本地 SQLite 模式与 Slipstream 智能引擎模式自动切换

资料来源：SPEC.md:7-12

通信模式

Via MCP 服务器支持两种通信模式，适用于不同的部署场景：

stdio 模式是默认模式，专为 Claude Code 设计，进程通过标准输入输出与父进程通信。SSE 模式则通过 HTTP 服务器和 Server-Sent Events 实现实时推送，适用于需要远程调用 Via 的场景。

资料来源：SPEC.md:7-12

可用 MCP 工具列表

Via 通过 MCP 服务器暴露以下 8 个核心工具：

MCP 工具命名遵循 Via 命令名称的映射规则，例如 via_task_list 对应 CLI 命令 via task list，保持命名一致性便于记忆。

资料来源：README.md:189-202

工作流程架构

graph TD
    A[Claude Code / Cursor / Windsurf] -->|MCP Protocol| B[Via MCP Server]
    B --> C[via serve]
    C --> D{通信模式}
    D -->|stdio| E[标准输入/输出]
    D -->|SSE| F[HTTP + SSE]
    E --> G[commands/serve.mjs]
    F --> G
    G --> H[Via 核心命令]
    H --> I[SQLite 本地存储]
    H --> J[Slipstream 智能引擎]
    I --> K[~/.via/]
    J --> K
    
    subgraph MCP 工具层
        L[via_task_*]
        M[via_memory_*]
        N[via_log]
        O[via_context]
        P[via_status]
    end
    
    G --> L
    G --> M
    G --> N
    G --> O
    G --> P

配置指南

Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加 Via 服务器：

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

配置完成后重启 Claude Desktop，即可使用 Via 提供的所有 MCP 工具。

资料来源：README.md:168-175

初始化命令

Via 提供了自动配置命令 via init，可自动检测已安装的 AI 工具并生成相应的 MCP 配置：

via init

该命令会执行以下操作：

• 检测系统中安装的 Claude Code、Cursor、Windsurf 等工具
• 生成符合各工具规范的配置文件
• 更新 ~/.via/config.json 全局配置

资料来源：SPEC.md:6.6

SSE 模式配置

对于需要远程访问的场景，使用 SSE 模式启动 Via 服务器：

via serve --sse

服务器默认监听本地端口，AI 工具通过 HTTP 请求与 Via 通信。

资料来源：SPEC.md:7-12

数据存储结构

MCP 服务器模式下，Via 在 ~/.via/ 目录下管理以下数据：

这些数据由 MCP 服务器直接访问，为 AI 工具提供持久化的上下文支持。

资料来源：SPEC.md:4

与 Slipstream 的集成

MCP 服务器模式下，Via 支持与 Slipstream 智能引擎的无缝升级：

当配置了 Slipstream 连接（设置 VEKTOR_API_KEY）后，MCP 服务器自动将记忆操作路由到 Slipstream，升级对 AI 工具透明。

资料来源：SPEC.md:8

典型使用场景

跨工具任务延续

1. 在 Cursor 中使用 via_task_add 添加任务
2. 切换到 Claude Code，通过 via_task_list 查看同一任务
3. 完成任务后用 via_task_done 更新状态
4. 任务状态变更自动同步到所有连接的 AI 工具

统一记忆访问

1. 在任一工具中使用 via_memory_add 存储重要信息
2. 任何连接的 AI 工具通过 via_memory_search 检索
3. 上下文通过 via_context 命令格式化输出

决策审计追踪

1. AI 工具使用 via_log 记录关键决策
2. 通过 via audit 命令搜索和导出审计日志
3. 合规团队可通过导出的 CSV/JSONL 文件进行审查

资料来源：SPEC.md:6.8

技术实现要点

MCP 协议兼容性

Via MCP 服务器实现遵循 MCP 规范，支持以下协议特性：

• 工具发现：自动暴露所有可用工具及其参数模式
• 工具调用：通过 JSON-RPC 格式处理工具调用请求
• 结果返回：结构化返回执行结果或错误信息

响应隔离机制

HTTP+SSE 模式下，POST 请求的响应仅返回给调用者，不会广播到其他连接。这一设计确保了多客户端环境下的数据隔离和安全。

资料来源：CHANGELOG.md:23-24

快速入门

# 全局安装 Via
npm install -g @vektor/via

# 启动 MCP 服务器（stdio 模式，默认）
via serve

# 或使用 SSE 模式
via serve --sse

# 初始化所有工具的 MCP 配置
via init

相关资源

• 命令参考：SPEC.md — 完整命令规格
• 变更日志：CHANGELOG.md — 版本更新记录
• 开源地址：github.com/Vektor-Memory/Via — GitHub 仓库
• Slipstream 升级：vektormemory.com — 智能引擎介绍

概述

连接器系统（Connector System）是 Via 的核心抽象层，负责与各类 AI 工具和外部服务进行集成交互。Via 作为通用集成层，需要连接 Claude Code、Cursor、Windsurf、ChatGPT 等多个 AI 工具，而连接器正是实现这一目标的关键组件。

连接器系统的设计理念是统一接口，统一行为——无论底层工具的 API 或数据格式如何差异，Via 通过标准化的连接器接口提供一致的访问方式。这种设计使得 Via 能够：

• 检测已安装的 AI 工具
• 读取工具的会话日志和用量数据
• 格式化上下文供工具使用
• 通过 MCP（Model Context Protocol）与工具进行双向通信

资料来源：SPEC.md | README.md

快速开始

安装方式

Via 支持零安装运行，无需全局安装即可使用：

npx via <command>

或全局安装：

npm install -g @vektor/via
via <command>

环境要求

• Node.js >= 18
• 原生 fetch API（Node 18+ 内置）
• 无需额外依赖

资料来源：package.json:18

命令概览

Via CLI 提供 12 个核心命令，涵盖上下文管理、任务追踪、代码索引、工具路由等功能：

资料来源：SPEC.md:1-30

核心命令详解

via init

初始化 Via 并将其连接到检测到的所有 AI 工具。

via init

功能说明：

• 自动检测系统中已安装的 AI 开发工具（Claude Code、Cursor、Windsurf、ChatGPT）
• 生成项目级配置文件 via.config.json
• 更新全局配置 ~/.via/config.json
• 为支持 MCP 的工具写入 MCP 服务器配置

输出示例：

检测到工具: claude ✓  cursor ✓  windsurf ✓  chatgpt –
配置完成

资料来源：README.md:40-50

Pitfall Log / 踩坑日志

项目：Vektor-Memory/Via

摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to AM4 CPU。

1. 安装坑 · 社区讨论暴露的待验证问题：Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to AM4 CPU

• 严重度：medium
• 证据强度：source_linked
• 发现：Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to AM4 CPU nvidia-smi topo -m is showing the both GPU as PHB (i.e. via CPU) connected as expected but I cannot get NCCL all\_reduce\_perf to run at all, it always hangs after starting up. It seems that vllm won't work with TP=2 until I can fix this.…
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_95e79adcac9e42dcb6f9d43a46c10fd7 | https://www.reddit.com/r/LocalLLaMA/comments/1tkmh89/cannot_get_nccl_test_to_run_in_docker_with_2_x/ | Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to AM4 CPU

2. 安装坑 · 社区讨论暴露的待验证问题：marx: review GitHub PRs with multiple agents, post a merged review

• 严重度：medium
• 证据强度：source_linked
• 发现：marx: review GitHub PRs with multiple agents, post a merged review 28 Jan 2026 · Written in Python, installable via uv. Feedback welcome. What else would you want from a multi-agent review tool? GitHub: https://github.com/ ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_9423afda27ed41728b1d7813f2facca0 | https://www.reddit.com/r/ClaudeAI/comments/1qpfzjz/marx_review_github_prs_with_multiple_agents_post/ | marx: review GitHub PRs with multiple agents, post a merged review

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | host_targets=claude, cursor, chatgpt

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | README/documentation is current enough for a first validation pass.

5. 运行坑 · 社区讨论暴露的待验证问题：Claude Sharing Option

• 严重度：medium
• 证据强度：source_linked
• 发现：Claude Sharing Option Hi! I want to set up for both me and my assistant, but Claude Teams has a 5-user minimum. What's the best workaround? What we need - shared projects with uploaded files, voice/style guides, Asana integration, Workarounds via project sharing or export/import Two separate Claude Pro accounts, what…
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_a4b5801eee4b44908731af66e31f7599 | https://www.reddit.com/r/ClaudeAI/comments/1tkex6y/claude_sharing_option/ | Claude Sharing Option

6. 运行坑 · 社区讨论暴露的待验证问题：MCP for JUST Writing Github issues? : r/ClaudeAI - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：MCP for JUST Writing Github issues? : r/ClaudeAI - Reddit 8 Jul 2025 · r/ClaudeAI - Built an MCP server that turns Claude Code into a full agent ... Best note-taking tool for use with Claude Code via MCP? (PM ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_7523d654c76a4f45ab12bcde212d9d07 | https://www.reddit.com/r/ClaudeAI/comments/1lujlfq/mcp_for_just_writing_github_issues/ | MCP for JUST Writing Github issues? : r/ClaudeAI - Reddit

7. 运行坑 · 社区讨论暴露的待验证问题：[Bug]: RayExecutorV2 multi-node DP hangs on shm_broadcast — cross-node ranks can't share single-host shared memory

• 严重度：medium
• 证据强度：source_linked
• 发现：[Bug]: RayExecutorV2 multi-node DP hangs on shm_broadcast — cross-node ranks can't share single-host shared memory ## Summary RayExecutorV2 (introduced via PR #36836, "[Feat][Executor] Introduce RayExecutorV2") inherits from MultiprocExecutor and uses shm_broadcast for inter-rank communication. shm_broadcast i…
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:github | ssig_03e0c85cb7cd44dca332c0dd836a8409 | https://github.com/vllm-project/vllm/issues/43420 | [Bug]: RayExecutorV2 multi-node DP hangs on shm_broadcast — cross-node ranks can't share single-host shared memory

8. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme | release_recency=unknown