# https://github.com/Vektor-Memory/Via 项目说明书
生成时间：2026-06-01 00:26:09 UTC
## 目录
- [Via 概述](#overview)
- [安装与配置](#installation)
- [快速入门指南](#quick-start)
- [记忆系统](#memory-system)
- [任务看板](#task-board)
- [AI 工具对比](#ai-comparison)
- [文件转换管道](#file-conversion)
- [MCP 服务器模式](#mcp-server)
- [连接器系统](#connectors)
- [CLI 命令参考](#cli-reference)
## Via 概述
### 相关页面
相关主题：[安装与配置](#installation)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
# Via 概述
## 项目简介
Via 是由 Vektor Memory 开发的开源 AI Agent 工作流构建器，作为通用集成层连接 Claude、Cursor、Windsurf 和 ChatGPT 等主流 AI 工具。通过单一 CLI 接口，Via 实现跨工具的共享记忆、任务看板和上下文总线，确保用户的工作上下文在不同工具、不同会话、不同机器之间无缝流转。
资料来源：[README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 核心价值主张
当前 AI 工具各自为政：Claude 遗忘 Cursor 中的工作，Cursor 不了解 Windsurf 的构建成果。切换工具或开启新会话时，上下文重置为零。Via 作为工具间的"总线"（bus），解决这一碎片化问题。
资料来源：[README.md:项目简介](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 系统架构
### 整体架构图
```mermaid
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
```
### 技术栈
| 组件 | 技术选型 | 说明 |
|------|---------|------|
| 运行时 | Node.js >= 18 | 原生 fetch API，无需 node-fetch |
| 数据库 | SQLite (sql.js) | 本地存储，无服务器依赖 |
| 模块格式 | ESM (.mjs) | 全面兼容现代 JavaScript |
| 许可协议 | Apache 2.0 | 永久免费 |
资料来源：[package.json:engines](https://github.com/Vektor-Memory/Via/blob/main/package.json)、[package.json:dependencies](https://github.com/Vektor-Memory/Via/blob/main/package.json)
## 核心命令详解
### 1. 上下文管理
#### `via context`
多工具上下文格式化命令，将共享记忆转换为各 AI 工具可识别的格式输出。
```bash
via context [query] [--tool claude|cursor|windsurf|chatgpt]
```
**支持的输出格式：**
| 工具 | 输出格式 |
|------|---------|
| Claude | `~/.claude/CLAUDE.md` 格式 |
| Cursor | `.cursor/rules/via-context.mdc` 规则文件 |
| Windsurf | 自定义剪贴板格式 |
| ChatGPT | Markdown 块 |
资料来源：[SPEC.md:6.1 via context](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
#### `via ingest`
通用知识摄入接口，从 URL、文件或目录读取内容，分块存储到本地 SQLite。
```bash
via ingest [--text "内容"] [--recursive]
```
**支持的来源：**
| 来源类型 | 实现方式 |
|---------|---------|
| URL | 原生 fetch |
| 文件 | txt、md、pdf (通过 pdftotext) |
| 目录 | 递归扫描，遵循 .gitignore |
资料来源：[SPEC.md:6.10 via ingest](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 2. 任务管理
#### `via task`
基于 SQLite 的持久化任务看板，任何 AI 工具均可通过 MCP 读写。
```bash
via task add "任务描述" [--high] [--medium] [--low]
via task list
via task start
via task done
via task delete
```
**任务字段结构：**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 自增主键 |
| title | TEXT | 任务标题 |
| status | TEXT | open / in-progress / done / blocked |
| tool | TEXT | 来源工具 |
| persona | TEXT | 关联角色 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
| notes | TEXT | 备注信息 |
资料来源：[SPEC.md:6.3 via task](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 3. 工作状态交接
#### `via handoff`
导出或导入 `.vstate.json` 会话状态文件，实现跨工具、跨机器的工作状态迁移。
```bash
# 导出当前状态
via handoff --export [--task "任务描述"] [--tool <工具名>]
# 导入已有状态
via handoff --import [--to claude|cursor|windsurf|chatgpt]
# 打印格式化上下文
via handoff --print --import
```
**`.vstate.json` 文件格式：**
```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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)、[SPEC.md:6.2 via handoff](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 4. 审计与合规
#### `via audit`
追加式合规日志，记录每个决策的工具、时间戳和理由。
```bash
via audit log "决策内容" --tool <工具>
via audit list
via audit search <关键词>
via audit export [--format jsonl|csv|markdown]
```
**导出格式支持：**
| 格式 | 适用场景 |
|------|---------|
| jsonl | 程序化处理 |
| csv | 电子表格分析 |
| markdown | 文档存档 |
资料来源：[SPEC.md:6.8 via audit](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 5. 成本追踪
#### `via spend`
读取所有已连接 AI 工具的用量日志，无需 API 调用，直接读取本地 JSONL 文件。
```bash
via spend today
via spend session
via spend week
via spend month
via spend leaks
```
**数据来源：**
| 工具 | 日志路径 |
|------|---------|
| Claude Code | `~/.claude/projects/*.jsonl` |
| Cursor | `~/.cursor/usage/*.jsonl` |
| OpenAI | `OPENAI_LOG_DIR` 环境变量 |
**泄漏检测模式：**
- 冗长的上下文重复注入
- 工具调用循环
- 大文件重复读取
- 冗余网络请求
资料来源：[SPEC.md:6.5 via spend](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 6. 项目脚手架
#### `via scaffold`
自动检测已安装的 AI 工具，向当前项目部署完整的 Via 集成配置。
```bash
via scaffold [--preset solo-dev|startup-team|enterprise-audit|research]
```
**生成的文件：**
| 文件 | 工具 | 说明 |
|------|------|------|
| `.cursor/rules/via-context.mdc` | Cursor | 上下文注入规则 |
| `.claude/CLAUDE.md` | Claude | 上下文块 |
| `via.config.json` | 项目级 | 项目级 Via 配置 |
| `~/.via/config.json` | 全局 | 更新项目注册 |
资料来源：[SPEC.md:6.6 via scaffold](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 7. 事件监听
#### `via watch`
监听 AI 工具的完成事件并触发通知。
```bash
via watch [--source desktop|webhook|slack|discord]
```
**事件来源：**
- 文件监视器（工具 JSONL 日志）
- 任务看板状态变更
- Webhook 接收器
**通知目标：**
| 目标 | 实现 |
|------|------|
| desktop | node-notifier |
| slack | Webhook |
| discord | Webhook |
| 自定义 | 任意 URL |
资料来源：[SPEC.md:6.7 via watch](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 8. 状态同步
#### `via sync`
将 Via 全部状态备份到私有 GitHub 仓库，或从仓库恢复。
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 9. 角色管理
#### `via persona`
命名式 AI 角色管理，每个角色拥有独立的系统提示词和记忆命名空间。
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 10. 任务路由
#### `via route`
根据任务描述推荐合适的 AI 工具。
```bash
via route "任务描述" [--budget <最大费用>] [--tools <工具列表>]
```
**路由逻辑（v0.1 规则版）：**
| 任务类型 | 推荐工具 |
|---------|---------|
| 深度研究 | Claude |
| 代码补全 | Cursor |
| 廉价摘要 | 最低价模型 |
资料来源：[SPEC.md:6.11 via route](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 11. 状态检查
#### `via status`
单命令健康检查，输出生态系统整体状态。
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## MCP 服务器模式
Via 可作为 MCP 服务器运行，将全部 12 个命令暴露为 MCP 工具，供 Claude Code、Cursor 和其他 MCP 兼容工具原生调用。
### 启动方式
```bash
via serve # stdio 模式（Claude Code 默认）
via serve --sse # HTTP + SSE 模式（远程连接）
```
### MCP 工具列表
| MCP 工具名 | 对应命令 | 功能 |
|-----------|---------|------|
| via_context | `via context` | 获取格式化上下文 |
| via_task_list | `via task list` | 列出开放任务 |
| via_task_add | `via task add` | 添加任务 |
| via_task_done | `via task done` | 完成任务 |
| via_memory_add | `via ingest` | 存储知识 |
| via_memory_search | `via context` | 搜索记忆 |
| via_log | `via audit log` | 记录决策 |
| via_status | `via status` | 健康检查 |
资料来源：[SPEC.md:7. MCP server mode](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Claude Desktop 配置
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 安全与隐私
**数据存储政策（关键声明）：**
> VEKTOR Memory 不会在服务器上存储您的任何数据——无论是开源还是闭源产品。您在本地机器上存储的记忆、凭证和保险库文件不会传输到任何服务器。
这适用于 Via 及所有 Vektor 产品：
- Vex（向量记忆迁移）
- Vek-Sync（MCP 配置同步、AES-256 凭证保险库）
- Via（CLI 集成层）
- Slipstream SDK
资料来源：[SECURITY.md:数据存储政策](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
## Slipstream 升级桥接
当配置 `slipstream.mjs` 连接器后（用户安装 Slipstream 并设置 `VEKTOR_API_KEY`），Via 自动将所有记忆操作路由到 Slipstream 而非 SQLite。升级透明无感——相同命令、相同格式、显著更好的效果。
### 功能对比
| 功能 | Via（免费） | Via + Slipstream |
|------|------------|-----------------|
| 记忆搜索 | SQLite FTS | BM25 + 语义 + 图遍历 |
| 上下文组装 | 关键词匹配 | 时间相关性 + 图关联 |
| 任务链接 | 扁平 SQLite | 因果链接到记忆图 |
| 知识摄入 | 分块关键词存储 | 向量嵌入 |
| 审计追踪 | 扁平日志 | 因果决策图 |
| 团队共享 | 仅本地 | 共享命名空间 |
资料来源：[SPEC.md:8. Slipstream upgrade bridge](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 快速入门
### 安装
Via 支持零安装使用：
```bash
npx via <命令>
```
或全局安装：
```bash
npm install -g @vektor/via
```
### 初始化
```bash
via init
```
该命令自动检测已安装的 AI 工具并写入相应配置。
资料来源：[README.md:安装](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
## 与 Vektor 生态的关系
```
┌─────────────────────────────────────────────────────────────┐
│ Vektor 生态系统 │
├──────────────┬──────────────────┬────────────────────────────┤
│ Vex │ Vek-Sync │ Via │
│ Vector │ Vektor │ Vektor │
│ Exchange │ Sync │ Memory │
├──────────────┼──────────────────┼────────────────────────────┤
│ 向量存储 │ MCP 配置 │ AI 工具集成与上下文路由 │
│ 迁移工具 │ 同步工具 │ 跨工具记忆总线 │
└──────────────┴──────────────────┴────────────────────────────┘
↓
┌─────────────────────┐
│ Slipstream │
│ intelligence │
│ 引擎（可选） │
└─────────────────────┘
```
| 产品 | 含义 | 功能 |
|------|------|------|
| Vex | Vector Exchange | 向量存储间迁移记忆 |
| Vek-Sync | Vektor Sync | 保持 MCP 配置同步 |
| Via | 拉丁语：路径、道路 | 跨工具路由上下文和执行 |
| Slipstream | — | 底层 intelligence 引擎 |
资料来源：[SPEC.md:10. Naming](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)、[README.md:Vektor 生态系统](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 社区反响
根据社交媒体和社区讨论，Via 受到以下关注：
| 平台 | 反馈类型 | 要点 |
|------|---------|------|
| Twitter | 项目推广 | 开源 AI Agent 工作流构建器 |
| Reddit | 功能讨论 | MCP 通用集成层，连接 Qwen、Claude Code、Codex 等 |
| Reddit | 使用场景 | 作为编码 Agent 会话管理器，通过 MCP 自我管理 |
| Reddit | 技术对比 | 探讨 MCP 与 CLI 调用的优劣 |
社区用户特别指出 Via 的独特价值在于其"一个其他工具没有的功能"——能够连接多个 AI Agent 并通过 MCP 实现自我管理。
资料来源：[社区上下文](file:///community_context)
## 总结
Via 作为开源 AI Agent 工作流构建器，通过 MCP 协议和本地 SQLite 存储实现了：
1. **上下文连续性** — 记忆在工具间无缝流转
2. **任务协同** — 共享任务看板供所有工具读写
3. **合规审计** — 完整决策追踪链
4. **成本透明** — 跨工具用量追踪
5. **灵活部署** — CLI 和 MCP 两种使用模式
作为 Vektor 生态系统的一部分，Via 可与 Vex、Vek-Sync 协同工作，并在升级到 Slipstream 后获得更强大的语义搜索和图遍历能力。
---
## 安装与配置
### 相关页面
相关主题：[快速入门指南](#quick-start), [CLI 命令参考](#cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [README.html](https://github.com/Vektor-Memory/Via/blob/main/README.html)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
# 安装与配置
Via 是 Vektor Memory 推出的开源 AI Agent 工作流构建工具，通过统一的 CLI 接口连接 Claude Code、Cursor、Windsurf、ChatGPT 等多种 AI 工具，实现跨工具的上下文共享、任务管理和记忆同步。本页详细介绍 Via 的系统要求、安装方式、初始配置以及 MCP 服务器的部署方法。
## 系统要求
Via 基于 Node.js 18+ 原生特性构建，依赖环境简单明确：
| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | >= 18 | 使用原生 `fetch` API，无需 `node-fetch` |
| 包管理器 | npm / npx | 支持 `npx` 零安装运行 |
| 操作系统 | macOS / Linux / Windows | 需支持 Node.js 原生模块 |
资料来源：[package.json:28]()
Via 使用纯 JavaScript ESM 模块编写，无需编译步骤。所有命令均通过 `via.mjs` 主入口文件调用，代码结构清晰，调试友好。
## 安装方式
### 方式一：npx 零安装（推荐）
无需全局安装，直接使用 `npx` 命令运行：
```bash
npx via
```
这种方式每次会拉取最新版本，适合快速试用和临时场景。资料来源：[SPEC.md:4.9]()
### 方式二：npm 全局安装
对于频繁使用的场景，建议全局安装：
```bash
npm install -g @vektor/via
```
安装完成后，`via` 命令全局可用：
```bash
via --version
via --help
```
资料来源：[README.md:安装]()
### 方式三：源码运行
克隆仓库后可直接运行源码：
```bash
git clone https://github.com/Vektor-Memory/Via.git
cd Via
node via.mjs
```
源码运行方式便于调试和二次开发，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]()
```bash
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 的全局配置：
```json
{
"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 配置：
```json
{
"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 服务器
```bash
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`
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
资料来源：[README.md:Claude Desktop 配置]()
### Cursor 配置
Cursor 的 MCP 配置位于 `~/.cursor/mcp.json`：
```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 工具包括：
| MCP 工具 | 功能描述 |
|----------|----------|
| `via_task_list` | 列出所有打开的任务 |
| `via_task_add` | 添加新任务 |
| `via_task_done` | 标记任务完成 |
| `via_memory_add` | 存储事实到记忆库 |
| `via_memory_search` | 关系感知的记忆搜索 |
| `via_log` | 记录决策或事件 |
| `via_context` | 获取格式化的记忆上下文 |
| `via_status` | 生态系统健康检查 |
资料来源：[README.md:MCP Tools]()
## 工具集成
### via scaffold 命令
`scaffold` 命令用于为已检测到的 AI 工具部署完整的 Via 集成配置：
```bash
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 工具集成：
| 工具 | 支持状态 | 集成方式 | 说明 |
|------|----------|----------|------|
| Claude Code | ✓ | MCP | 完整集成 |
| Cursor | ✓ | MCP | 支持 >= 0.45 版本规则 |
| Windsurf | ✓ | MCP | SSE 模式推荐 |
| ChatGPT | 部分 | MCP | 功能有限 |
资料来源：[SPEC.md:6.12](), [README.html:via init]()
## 验证安装
### via status 命令
使用 `via status` 命令检查 Via 生态系统健康状态：
```bash
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]()
### 快速功能测试
安装完成后，可通过以下命令验证各模块功能：
```bash
# 验证任务管理
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：
```bash
npx via upgrade
```
Slipstream 是 Vektor 生态的智能引擎，提供图记忆、向量搜索和多模态能力。资料来源：[README.html:Vektor ecosystem]()
## 常见问题
### MCP 连接失败
如果 AI 工具无法连接 Via MCP 服务器，检查：
1. `via serve` 是否正在运行
2. MCP 配置文件是否正确写入
3. `via status` 是否显示工具已连接
### 数据同步问题
跨机器使用时，可使用 `via sync` 命令备份和恢复 Via 状态：
```bash
via sync backup # 备份到 GitHub 私有仓库
via sync restore # 从备份恢复
```
该功能与 Vek-Sync 采用相同的方案，支持冲突检测。资料来源：[SPEC.md:6.9]()
---
Via 的安装与配置设计简洁高效，通过 `via init` 一键完成主要配置，同时支持细粒度的手动调整。推荐从 `npx via init` 开始，根据实际需求逐步配置 MCP 服务器和 AI 工具集成。
---
## 快速入门指南
### 相关页面
相关主题：[MCP 服务器模式](#mcp-server), [记忆系统](#memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs) - CLI 入口点
- [commands/init.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/init.mjs) - 初始化命令
- [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs) - 内存索引命令
- [commands/task.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs) - 任务管理命令
- [commands/serve.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/serve.mjs) - MCP 服务器
- [utils/detect.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/detect.mjs) - 工具检测
- [utils/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs) - 配置管理
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json) - 项目依赖
# 快速入门指南
Via 是 Vektor Memory 生态系统中的通用 AI 工具集成层。它通过统一的 CLI 接口连接 Claude Code、Cursor、Windsurf 和 ChatGPT，实现跨工具的上下文共享、任务管理和工作状态传递。本指南将帮助你在 5 分钟内完成安装、初始化和基础使用。
## 系统要求与安装
### 环境要求
| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | >= 18 | 使用原生 fetch API |
| npm/yarn/pnpm | 最新稳定版 | 用于全局安装 |
| SQLite | 自动嵌入 | 通过 sql.js 封装 |
Via 采用零依赖设计，核心仅依赖 `sql.js`。不支持 CommonJS 的旧版 Node 环境。
### 安装方式
Via 提供两种使用方式：
**方式一：直接运行（推荐）**
```bash
npx via
```
此方式无需全局安装，每次自动获取最新版本。
**方式二：全局安装**
```bash
npm install -g @vektor/via
# 或
yarn global add @vektor/via
```
安装完成后，可直接使用 `via` 命令：
```bash
via --version
```
## 初始化配置
首次使用需要运行初始化命令，Via 将自动检测已安装的 AI 工具并完成配置。
### 自动初始化
```bash
via init
```
初始化过程执行以下操作：
1. 检测已安装的 AI 编程工具（Claude Code、Cursor、Windsurf）
2. 创建用户配置文件 `~/.via/config.json`
3. 为每个检测到的工具生成上下文注入规则
4. 配置 MCP 服务器连接
### 初始化参数
| 参数 | 说明 | 示例 |
|------|------|------|
| `--preset` | 预设配置方案 | `solo-dev`、`startup-team`、`enterprise-audit`、`research` |
| `--force` | 强制重新初始化 | 覆盖现有配置 |
| `--no-detect` | 跳过工具检测 | 仅创建基础配置 |
**示例：使用团队预设初始化**
```bash
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 init` | 初始化配置 | 首次使用或重置配置 |
| `via memory` | 代码索引与搜索 | 理解项目结构、查找相关文件 |
| `via task` | 任务看板管理 | 跨工具任务跟踪 |
| `via log` | 活动日志 | 记录决策、追踪会话 |
| `via ask` | 智能路由 | 选择合适的 AI 工具 |
| `via diff` | 对比分析 | 比较不同工具的回答 |
| `via handoff` | 状态导出/导入 | 切换工具时传递上下文 |
| `via serve` | MCP 服务器模式 | 供 Claude Desktop、Cursor 调用 |
| `via status` | 健康检查 | 查看系统状态 |
## 代码索引与搜索
### 关系感知索引
Via 的 `memory` 命令从代码中提取符号定义和导入关系，构建本地 SQLite 图数据库。与传统关键词搜索不同，它能够追踪依赖链。
### 基本用法
```bash
# 索引整个源码目录
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 访问。
### 任务生命周期
```mermaid
graph LR
A[add] --> B[open]
B --> C[start]
C --> B
C --> D[done]
D --> E[归档]
B --> F[blocked]
F --> B
```
### 常用操作
```bash
# 添加任务
via task add "实现用户认证模块" --high
# 列出所有任务
via task
# 标记进行中
via task start
# 完成任务
via task done
# 删除任务
via task delete
```
### 任务字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 自动递增的任务标识符 |
| title | 字符串 | 任务描述 |
| status | 枚举 | `open` \| `in-progress` \| `done` \| `blocked` |
| priority | 枚举 | `low` \| `medium` \| `high` |
| tool | 字符串 | 创建任务的工具名称 |
| created_at | 时间戳 | 创建时间 |
| updated_at | 时间戳 | 最后更新时间 |
## MCP 服务器模式
Via 可作为 MCP 服务器运行，使 Claude Desktop、Cursor 和 Windsurf 能够直接调用 Via 工具。
### 启动方式
```bash
# 标准 I/O 模式（适用于 Claude Desktop 和 Cursor）
via serve
# HTTP + SSE 模式（适用于远程连接）
via serve --sse
```
### Claude Desktop 配置
在 `~/.claude.json` 中添加：
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
### 可用 MCP 工具
| 工具名称 | 功能 |
|----------|------|
| `via_task_list` | 列出开放任务 |
| `via_task_add` | 添加新任务 |
| `via_task_done` | 标记任务完成 |
| `via_memory_add` | 存储事实 |
| `via_memory_search` | 搜索记忆（关系感知） |
| `via_log` | 记录决策或事件 |
| `via_context` | 获取格式化的记忆上下文 |
| `via_status` | 生态系统健康检查 |
### SSE 模式参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--port` | HTTP 监听端口 | 3456 |
| `--host` | 绑定地址 | localhost |
| `--cors` | 启用 CORS | false |
## 工作状态传递
### Handoff 功能
使用 `via handoff` 导出当前工作状态，在切换 AI 工具时保持上下文连续性。
### 使用流程
```mermaid
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[恢复完整上下文]
```
### 命令示例
```bash
# 导出当前状态
via handoff --export
# 导入状态文件
via handoff --import ./sprint3.vstate.json
# 列出可用的handoff文件
via handoff --list
# 打印格式化上下文（用于手动粘贴）
via handoff --import ./handoff.vstate.json --print
```
### 导出的状态文件格式
```json
{
"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 工具：
```bash
# 自动推荐并打开工具
via ask "解释这个微服务架构"
# 强制使用指定工具
via ask "重构认证模块" --tool cursor
# 仅推荐，不打开
via ask "总结这段代码" --no-open
```
### 路由规则（v0.1）
| 任务类型 | 推荐工具 | 原因 |
|----------|----------|------|
| 深度研究、复杂分析 | Claude | 强大的推理能力 |
| 代码补全、快速修改 | Cursor | 实时 IDE 集成 |
| 大型重构、架构设计 | Claude Code | 长上下文窗口 |
### 响应对比
`via diff` 允许你将同一问题提交给多个工具并比较回答：
```bash
# 记录问题
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/` 目录是否存在
手动指定工具：
```bash
via init --force --no-detect
# 然后手动编辑 ~/.via/config.json 添加工具
```
### MCP 服务器连接失败
1. 确认 Via 已安装：`via --version`
2. 检查 Claude Desktop 配置是否正确
3. 重启 Claude Desktop 以加载更新后的配置
4. 使用 `via status` 检查 MCP 服务器状态
### 索引搜索无结果
索引数据可能不存在或过期：
```bash
# 重新索引
via memory add --file ./src/
# 清空并重建
via memory clear
via memory add --file ./src/
```
## 下一步
- 查看 [SPEC.md](SPEC.md) 了解完整的命令规范
- 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新
- 访问 [Vektor Memory 官网](https://vektormemory.com) 了解更多产品信息
- 如遇问题，发送邮件至 hello@vektormemory.com
---
## 记忆系统
### 相关页面
相关主题：[CLI 命令参考](#cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs)
- [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
- [commands/context.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/context.mjs)
- [commands/ingest.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/ingest.mjs)
- [commands/sync.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/sync.mjs)
# 记忆系统
Via 的记忆系统是跨 AI 工具的共享知识层，负责存储、索引和检索代码上下文信息。它解决了 AI 工具之间"上下文孤岛"的问题——当用户在 Claude Code、Cursor、Windsurf 或 ChatGPT 之间切换时，记忆系统确保工作状态和代码理解可以无缝衔接。
## 设计理念
### 本地优先架构
Via 记忆系统采用纯本地存储策略，不依赖任何云端 API 或外部服务：
| 特性 | 本地模式 | Slipstream 升级模式 |
|------|----------|---------------------|
| 存储引擎 | SQLite | 向量数据库 + 图数据库 |
| 搜索方式 | 关键词 + 导入关系图遍历 | BM25 + 语义向量双通道召回 |
| API 调用 | 无 | 可选远程语义搜索 |
| 数据保留 | 仅本地 | 支持团队共享命名空间 |
资料来源：[SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 关系感知索引
传统代码搜索仅匹配文本，而 Via 记忆系统构建代码的**导入图（Import Graph）**，支持关系感知的智能检索：
```mermaid
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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 核心组件
### 1. memory 命令模块
`commands/memory.mjs` 是记忆系统的主入口，处理所有内存相关的操作：
| 子命令 | 功能描述 |
|--------|----------|
| `via memory add --file ` | 索引文件或目录，提取符号和导入关系 |
| `via memory search ` | 关系感知搜索，返回直接匹配和关联文件 |
| `via memory list` | 列出所有已索引的文件和事实 |
| `via memory graph` | 可视化显示导入关系图 |
支持的编程语言：
- JavaScript / TypeScript (.js, .jsx, .ts, .tsx)
- Python (.py)
- Go (.go)
- Rust (.rs)
- 其他主流语言
资料来源：[commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs)
### 2. SQLite 数据库适配器
`utils/db.mjs` 封装了所有数据库操作，提供统一的存储接口：
```javascript
// 核心功能
- SQLite 连接管理
- 索引表创建与迁移
- 符号（Symbol）CRUD 操作
- 导入边（Import Edge）存储
- 全文搜索支持
```
数据存储位置：`~/.via/memory.db`
资料来源：[utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
### 3. 知识摄取模块
`commands/ingest.mjs` 处理非代码类知识的摄入：
| 摄取源 | 处理方式 |
|--------|----------|
| URL | 原生 fetch 抓取网页内容 |
| 文件 | txt, md 直接读取；pdf 调用 pdftotext 转换 |
| 目录 | 递归遍历，遵守 .gitignore 规则 |
| 内联文本 | `--text` 参数直接指定内容 |
所有摄入内容会被分块（Chunked）后存入本地 SQLite，供后续检索使用。
资料来源：[commands/ingest.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/ingest.mjs)
## 数据模型
### 符号表（Symbols Table）
```sql
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）
```sql
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）
```sql
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
);
```
## 使用流程
### 基本索引操作
```bash
# 索引单个文件
via memory add --file ./src/auth.js
# 索引整个目录
via memory add --file ./src/
# 索引并跟踪所有导入关系
via memory add --file ./src/ --recursive
```
### 关系感知搜索
```bash
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
└───────────────────────────────────────────────
```
### 知识摄取
```bash
# 从 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 上下文检索
通过 `commands/context.mjs`，记忆内容可以格式化为各 AI 工具可消费的上下文格式：
| 工具 | 输出格式 | 文件路径 |
|------|----------|----------|
| Claude | 纯文本块 | `.claude/CLAUDE.md` |
| Cursor | Cursor Rules 格式 | `.cursor/rules/via-context.mdc` |
| Windsurf | Waldo 格式 | `.windsurf/` |
| ChatGPT | Custom Instructions | API 写入 |
```bash
# 获取当前记忆上下文
via context
# 指定工具格式
via context --tool cursor
# 包含特定搜索结果
via context --include "auth middleware"
```
资料来源：[commands/context.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/context.mjs)
## 状态同步
`commands/sync.mjs` 支持跨设备同步记忆状态：
```bash
# 备份记忆到 GitHub 私有仓库
via sync backup
# 恢复记忆状态
via sync restore
# 查看同步状态
via sync status
# 比较本地与远程差异
via sync diff
```
同步内容包括：
- `memory.db` 完整数据库
- `~/.via/config.json` 配置
- `personas/` 角色定义
- `audit.db` 审计日志
资料来源：[commands/sync.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/sync.mjs)
## MCP 工具接口
当 Via 以 MCP 服务器模式运行时（`via serve`），记忆系统暴露以下工具：
| MCP 工具 | 功能 |
|----------|------|
| `via_memory_add` | 存储事实或索引代码 |
| `via_memory_search` | 关系感知搜索 |
| `via_context` | 拉取格式化记忆上下文 |
```json
// MCP 工具调用示例
{
"name": "via_memory_search",
"arguments": {
"query": "authentication flow",
"limit": 10
}
}
```
Claude Desktop / Cursor 配置示例：
```json
{
"mcpServers": {
"via": { "command": "via", "args": ["serve"] }
}
}
```
## 配置选项
记忆系统行为通过 `~/.via/config.json` 配置：
```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 升级获得高级能力：
| 升级特性 | 本地 SQLite | Slipstream |
|----------|-------------|------------|
| 搜索精度 | 关键词匹配 | BM25 + 语义向量双通道 |
| 关系推理 | 单层导入追踪 | 图遍历 + 因果链 |
| 团队协作 | 本地独占 | 共享命名空间 |
| 时序感知 | 无 | 时间衰减 + 热度权重 |
升级命令：
```bash
via upgrade
# 或
npx via upgrade
```
资料来源：[SPEC.md - Slipstream](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 性能特性
### 索引性能
- 增量索引：仅处理自上次索引后变更的文件
- 并行处理：支持多核 CPU 并发解析
- 流式写入：大批量索引时使用批量 INSERT
### 查询性能
- 索引加载时间：< 100ms（通常 < 50ms）
- 搜索响应时间：< 200ms（千级文件规模）
- 内存占用：约 10-50MB（取决于项目规模）
## 安全与隐私
所有记忆数据严格本地存储：
- 数据位置：`~/.via/` 目录
- 传输加密：同步到 GitHub 使用 HTTPS
- 密钥管理：通过 `via vault` 使用 AES-256 加密敏感信息
- 零云存储：Via 服务器不存储任何用户数据
资料来源：[SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
## 故障排除
| 问题 | 解决方案 |
|------|----------|
| 索引不完整 | 检查文件是否在排除模式中（`excludePatterns`） |
| 搜索结果不准确 | 运行 `via memory add --file .` 重建索引 |
| 导入关系缺失 | 确认语言解析器支持该导入语法 |
| 数据库损坏 | 删除 `~/.via/memory.db` 后重新索引 |
## 最佳实践
1. **定期索引**：在重要代码变更后执行 `via memory add`
2. **增量更新**：避免频繁全量重建索引
3. **关键词优化**：搜索时使用准确的函数/变量名
4. **上下文注入**：切换工具前执行 `via context` 确保记忆传递
5. **定期备份**：使用 `via sync backup` 防止数据丢失
---
*Via 记忆系统 — 构建于 SQLite 之上，无需 API 调用，保护数据隐私*
---
## 任务看板
### 相关页面
相关主题：[CLI 命令参考](#cli-reference), [MCP 服务器模式](#mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [commands/task.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs)
- [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
- [utils/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
# 任务看板
Via 的任务看板是一个持久化的任务管理模块，允许用户通过 CLI 创建、跟踪和管理任务。该模块的核心特性是通过 SQLite 数据库实现本地存储，并支持通过 MCP 协议供 Claude Code、Cursor、Windsurf 等 AI 工具访问，实现跨工具的任务共享。
## 功能概述
任务看板提供以下核心能力：
- **持久化存储**：所有任务存储在本地 SQLite 数据库 (`~/.via/tasks.db`)，不依赖云服务
- **跨工具访问**：通过 MCP 服务器暴露任务操作，任何连接的 AI 工具都能读写同一任务列表
- **状态流转**：支持完整的工作流状态（open → in-progress → done/blocked）
- **元数据跟踪**：记录任务创建时间、更新时间、关联工具和 AI 角色
## 架构设计
### 数据模型
任务看板使用 SQLite 作为存储后端，数据表结构如下：
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 自增主键 |
| title | TEXT | 任务标题 |
| status | TEXT | 任务状态：open、in-progress、done、blocked |
| tool | TEXT | 创建任务的 AI 工具（如 claude、cursor） |
| persona | TEXT | 关联的 AI 角色名称 |
| created_at | TEXT | ISO 8601 格式创建时间 |
| updated_at | TEXT | ISO 8601 格式更新时间 |
| notes | TEXT | 任务备注和描述 |
### 模块依赖
```mermaid
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]()
## 命令接口
### 子命令列表
| 子命令 | 功能 | 示例 |
|--------|------|------|
| add | 创建新任务 | `via task add "任务描述"` |
| list | 列出所有任务 | `via task` 或 `via task list` |
| update | 更新任务信息 | `via task update ` |
| done | 标记任务完成 | `via task done ` |
| next | 获取下一个待办任务 | `via task next` |
| delete | 删除任务 | `via task delete ` |
### 任务状态流转
```mermaid
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 --> [*]
```
### 使用示例
#### 创建任务
```bash
via task add "实现用户认证模块" --high
via task add "修复登录页面样式问题"
via task add "编写 API 文档" --tool cursor --persona developer
```
#### 查看任务
```bash
via task # 默认列出所有任务
via task list # 显式列出任务
via task list --open # 仅显示 open 状态任务
```
#### 更新任务状态
```bash
via task start # 开始处理任务 (in-progress)
via task done # 标记完成
via task update --title "新标题" # 修改标题
via task update --blocked # 标记为阻塞状态
```
#### 删除任务
```bash
via task delete
```
## MCP 工具接口
当 Via 以 MCP 服务器模式运行时 (`via serve`)，任务看板暴露以下 MCP 工具供 AI 代理调用：
| MCP 工具 | 功能 |
|----------|------|
| via_task_list | 列出所有任务 |
| via_task_add | 添加新任务 |
| via_task_done | 标记任务完成 |
资料来源：[README.md:100-120]()
### MCP 配置示例
在 Claude Desktop 或 Cursor 中配置 Via MCP 服务器：
```json
{
"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 升级集成
| 功能层级 | 本地模式 | Slipstream 模式 |
|----------|----------|-----------------|
| 任务列表 | 扁平列表 | 链接到记忆图谱 |
| 关联分析 | 无 | 因果连接决策 |
## 常见问题
### Q: 任务数据是否跨设备同步？
当前版本任务数据仅存储在本地。如需多设备同步，可使用 `via sync` 命令将状态备份到私有 GitHub 仓库。
### Q: 如何查看任务历史？
使用 `via audit log --task ` 可查看特定任务的所有变更记录。
### Q: 支持批量操作吗？
当前 CLI 不支持批量操作，但通过 MCP 接口可以编写脚本实现批量任务管理。
## 版本历史
- **v0.1.0** (2026-05-10)：初始发布，完整的任务看板功能
- 修复了任务状态更新时的时区问题
- 优化了任务列表的显示格式
资料来源：[CHANGELOG.md:1-20]()
## 相关文档
- [Via 主文档](../README.md)
- [MCP 服务器配置](./MCP服务器.md)
- [审计日志](./审计日志.md)
- [Slipstream 升级](./Slipstream升级.md)
---
## AI 工具对比
### 相关页面
相关主题：[CLI 命令参考](#cli-reference), [连接器系统](#connectors)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [README.html](https://github.com/Vektor-Memory/Via/blob/main/README.html)
# AI 工具对比
Via 的核心差异化功能之一是通过 `via diff` 命令实现跨 AI 工具的响应对比分析。该功能使用户能够针对同一问题向多个 AI 助手获取答案，并直观地展示它们在回答风格、术语使用和概念理解上的异同。
## 功能概述
`via diff` 是 Via 提供的"比较 AI 工具侧边差异"功能，号称是**其他工具不具备的特性**。用户可以向 Claude 和 Cursor 提出相同问题，然后精确地观察它们在哪些方面达成共识、在哪些方面产生分歧，以及每个工具带来了哪些独特的概念和术语。
资料来源：[README.md:1-50](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 工作原理
### 命令流程
```
via diff "your prompt" # 注册一个新的对比任务
via diff add claude "..." # 存储 Claude 的响应
via diff add cursor "..." # 存储 Cursor 的响应
via diff show # 展示并排对比 + 独有术语
via diff list # 列出所有已保存的对比
```
资料来源：[README.md:45-60](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### 对比输出格式
执行 `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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 技术实现
### 架构设计
Via 作为统一的 AI 工具集成层，通过标准化的接口连接不同的 AI 助手。`via diff` 功能依赖于底层的连接器架构：
| 组件 | 职责 |
|------|------|
| `via.mjs` | CLI 入口点，路由 diff 命令 |
| `commands/diff.mjs` | diff 命令的具体实现 |
| `connectors/` | 各 AI 工具的适配器 |
| `utils/` | 共享的内部工具 |
资料来源：[SPEC.md:1-30](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 数据存储
对比结果存储在 Via 的本地数据目录中：
```
~/.via/
├── config.json # 用户配置
├── diff/ # diff 对比结果存储
└── handoffs/ # 会话状态导出
```
## 核心特性
### 相似度计算
系统通过**词重叠率（word overlap）**计算两个 AI 工具响应的相似度：
| 指标 | 说明 |
|------|------|
| `claude` | Claude 响应的词数统计 |
| `cursor` | Cursor 响应的词数统计 |
| `similarity` | 词重叠百分比 |
### 独有术语提取
系统自动识别并提取每个工具的**独有术语（unique terms）**，帮助用户快速发现两个工具在表达同一概念时的差异。
### 并排展示
将两个响应以表格形式并排展示，左侧为 Claude 输出，右侧为 Cursor 输出，便于垂直对比。
## 使用场景
### 代码审查
当不确定某个代码修改应该采用哪种方案时，可以同时询问两个工具，对比它们的实现思路：
```bash
via diff "refactor auth module with JWT"
via diff add claude "方案A：使用 passport.js..."
via diff add cursor "方案B：使用自定义中间件..."
via diff show
```
### 架构设计讨论
对于系统设计问题，不同工具可能提供不同视角：
```bash
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..."
```
### 学习对比
通过对比学习不同工具对同一概念的解释，扩展知识视野：
| 工具 | 优势 | 劣势 |
|------|------|------|
| Claude | 深度分析、逻辑严谨 | 可能过于冗长 |
| Cursor | 实践导向、代码优先 | 解释可能较简洁 |
## 与其他 Via 命令的集成
### 与 `via context` 集成
对比完成后，可以将差异分析添加到共享上下文中供后续会话使用：
```bash
via context add --from diff "microservices-comparison-2026"
```
### 与 `via handoff` 集成
对比结果可以包含在工作状态导出中：
```bash
via handoff --export --task "compare auth approaches"
```
资料来源：[SPEC.md:30-60](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## MCP 工具支持
当 Via 以 MCP 服务器模式运行时，`via diff` 功能也可通过 MCP 工具调用：
```json
{
"mcpServers": {
"via": { "command": "via", "args": ["serve"] }
}
}
```
支持的 MCP 工具包括：
| MCP 工具名 | 功能 |
|------------|------|
| `via_diff_register` | 注册新的对比任务 |
| `via_diff_add` | 添加响应 |
| `via_diff_show` | 展示对比结果 |
## 版本信息
### v0.1.0 发布特性
`via diff` 在 Via 0.1.0 版本中作为核心功能发布：
资料来源：[CHANGELOG.md:1-20](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
### 路线图
**v0.4 规划中：**
- `via diff --live` 实时对比模式
- 支持更多 AI 工具接入
- 增强的相似度算法
资料来源：[README.md:120-140](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 社区反馈
根据社区讨论，Via 的 MCP 通用集成特性和 `via diff` 功能受到开发者关注：
- Reddit 用户评价 Via 为"MCP 通用集成层 CLI 工具"，认为其**具有其他工具不具备的功能**
- 社区讨论涉及 MCP 工具选择、跨工具上下文共享等话题
资料来源：[社区上下文 - Reddit LocalLLaMA](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/a_mcp_universal_integration_layer_cli_tool_it/)
## 限制与注意事项
### 当前限制
1. **相似度计算简单**：目前仅基于词重叠率，未使用语义向量相似度
2. **本地存储**：对比结果仅存储在本地 SQLite 中
3. **工具支持有限**：当前主要支持 Claude 和 Cursor
### 升级路径
通过升级到 Slipstream，可以获得更高级的对比能力：
| 功能 | Via (免费) | Via + Slipstream |
|------|------------|------------------|
| 上下文组装 | 关键词匹配 | 时间相关性 + 知识图谱 |
| 内存搜索 | SQLite FTS | BM25 + 语义 + 图搜索 |
资料来源：[SPEC.md:80-100](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## 文件转换管道
### 相关页面
相关主题：[CLI 命令参考](#cli-reference), [记忆系统](#memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [README.html](https://github.com/Vektor-Memory/Via/blob/main/README.html)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
# 文件转换管道
Via 的 `via convert` 命令提供了一套完整的本地文件格式转换管道。该功能的设计理念是**所有转换操作均在本地执行，不上传任何数据到远程服务器**，确保用户数据的隐私和安全。
## 核心设计理念
文件转换管道是 Via 生态系统中的重要组成部分，它解决了 AI Agent 工作流中常见的数据格式兼容问题。在多工具协作场景下，不同的 AI 工具可能对输入格式有不同的要求，Via 的转换管道能够在不离开本地环境的情况下完成格式转换。
该管道的核心特点包括：
- **本地化处理**：所有文件转换都在用户本地机器上执行，不存在云端传输
- **可选的记忆集成**：转换完成后可自动将内容摄入 Via 的知识库
- **广泛的格式支持**：覆盖图像、音频、视频、文档、办公文件、PDF 和压缩包等主流格式
- **工具依赖管理**：提供工具检查功能，帮助用户确认所需的外部依赖是否已安装
资料来源：[README.md - via convert](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 支持的格式矩阵
Via 的转换管道支持多种输入输出格式组合，以下是详细的格式支持表：
### 图像格式
| 输入格式 | 输出格式 |
|---------|---------|
| PNG | JPG, WebP, GIF, BMP, TIFF, ICO, PDF |
| JPG | PNG, WebP, GIF, BMP, TIFF, ICO, PDF |
| WebP | PNG, JPG, GIF, BMP, TIFF, ICO, PDF |
| GIF | PNG, JPG, WebP, BMP, TIFF, ICO, PDF |
| BMP | PNG, JPG, WebP, GIF, TIFF, ICO, PDF |
| TIFF | PNG, JPG, WebP, GIF, BMP, ICO, PDF |
| ICO | PNG, JPG, WebP, GIF, BMP, TIFF, PDF |
| SVG | PNG, JPG, WebP, GIF, BMP, TIFF, ICO, PDF |
### 音频格式
| 输入格式 | 输出格式 |
|---------|---------|
| MP3 | WAV, OGG, M4A, AAC, FLAC, AIFF, WMA |
| WAV | MP3, OGG, M4A, AAC, FLAC, AIFF, WMA |
| OGG | MP3, WAV, M4A, AAC, FLAC, AIFF, WMA |
| M4A | MP3, WAV, OGG, AAC, FLAC, AIFF, WMA |
| AAC | MP3, WAV, OGG, M4A, FLAC, AIFF, WMA |
| FLAC | MP3, WAV, OGG, M4A, AAC, AIFF, WMA |
| AIFF | MP3, WAV, OGG, M4A, AAC, FLAC, WMA |
| WMA | MP3, WAV, OGG, M4A, AAC, FLAC, AIFF |
### 视频格式
| 输入格式 | 输出格式 |
|---------|---------|
| MP4 | MKV, MOV, AVI, WebM, FLV, WMV, GIF, MP3 |
| MKV | MP4, MOV, AVI, WebM, FLV, WMV, GIF, MP3 |
| MOV | MP4, MKV, AVI, WebM, FLV, WMV, GIF, MP3 |
| AVI | MP4, MKV, MOV, WebM, FLV, WMV, GIF, MP3 |
| WebM | MP4, MKV, MOV, AVI, FLV, WMV, GIF, MP3 |
| FLV | MP4, MKV, MOV, AVI, WebM, WMV, GIF, MP3 |
| WMV | MP4, MKV, MOV, AVI, WebM, FLV, GIF, MP3 |
### 文档格式
| 输入格式 | 输出格式 |
|---------|---------|
| Markdown (MD) | HTML, TXT, PDF, EPUB, DOCX, ODT |
| reStructuredText (RST) | MD, HTML, TXT, PDF, EPUB, DOCX, ODT |
| HTML | MD, HTML, TXT, PDF, EPUB, DOCX, ODT |
| TXT | MD, HTML, TXT, PDF, EPUB, DOCX, ODT |
| LaTeX (TEX) | MD, HTML, TXT, PDF, EPUB, DOCX, ODT |
| Org-mode (ORG) | MD, HTML, TXT, PDF, EPUB, DOCX, ODT |
| EPUB | MD, HTML, TXT, PDF, DOCX, ODT |
### 办公文档格式
| 输入格式 | 输出格式 |
|---------|---------|
| DOCX | PDF, TXT, HTML, ODT, DOCX |
| DOC | PDF, TXT, HTML, ODT, DOCX |
| ODT | PDF, TXT, HTML, DOCX, ODT |
| RTF | PDF, TXT, HTML, ODT, DOCX |
| XLSX | PDF, TXT, HTML, ODT |
| PPTX | PDF, TXT, HTML, ODT |
### PDF 格式
| 输入格式 | 输出格式 |
|---------|---------|
| PDF | TXT, MD, HTML, DOCX |
### 压缩包格式
| 输入格式 | 输出格式 |
|---------|---------|
| 任意文件或文件夹 | ZIP, TAR.GZ, 7Z |
资料来源：[README.md - Supported formats](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 外部工具依赖
Via 的文件转换管道依赖一系列外部命令行工具来处理不同类型的格式转换。这些工具需要用户手动安装，Via 提供了检查命令来帮助用户确认依赖状态。
| 工具名称 | 用途 |
|---------|------|
| FFmpeg | 音频和视频格式转换、GIF 提取 |
| ImageMagick | 图像格式转换和缩放处理 |
| Pandoc | 文档格式转换（Markdown、LaTeX、reStructuredText 等） |
| LibreOffice | Office 文档（DOCX、XLSX、PPTX）和 PDF 处理 |
| Poppler | PDF 文本提取（pdftotext） |
| 7-Zip | 压缩包格式转换（ZIP、TAR.GZ、7Z） |
用户可以通过以下命令检查已安装的工具：
```bash
via convert --check
```
该命令会扫描系统PATH，检测上述工具是否可用，并报告缺失的依赖项。
资料来源：[README.md - External tools required](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 命令行接口
### 基本用法
`via convert` 命令提供了直观易用的命令行接口，支持单文件转换和批量处理：
```bash
# 转换单个文件
via convert --to
# 转换并摄入到记忆系统
via convert --to md --ingest
# 检查已安装的转换工具
via convert --check
# 列出所有支持的格式
via convert --formats
```
### 参数说明
| 参数 | 说明 | 示例 |
|-----|------|-----|
| `` | 要转换的输入文件路径 | `./document.docx` |
| `--to ` | 目标输出格式 | `--to pdf` |
| `--ingest` | 转换后自动摄入到 Via 记忆系统 | `--ingest` |
| `--check` | 检查已安装的外部工具 | `--check` |
| `--formats` | 列出所有支持的格式 | `--formats` |
资料来源：[README.md - via convert](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 转换流程架构
```
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 中提取文本并建立索引
集成记忆系统的转换管道遵循以下流程：
```bash
via convert ./report.pdf --to md --ingest
# → 1. 使用 Poppler 提取 PDF 文本
# → 2. 转换为 Markdown 格式
# → 3. 自动调用 via ingest 将内容存储到 SQLite 知识库
# → 4. 内容可被 via memory search 检索
```
资料来源：[README.md - via ingest](https://github.com/Vektor-Memory/Via/blob/main/README.md) 和 [SPEC.md - via ingest](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 在 AI Agent 工作流中的角色
在 Via 的多工具协作生态系统中，文件转换管道承担着关键的桥接角色。用户和社区反馈表明，跨工具工作时经常遇到格式兼容问题，而 Via 的转换管道提供了一种统一的解决方案。
根据社区讨论，Via 作为一个 MCP 通用集成层，能够连接 Qwen、Claude Code、Codex 等多种 AI 工具。在这种多工具协作场景下，文件格式的兼容性尤为重要：
- Claude Code 可能生成某种格式的输出
- Cursor 需要另一种格式的输入
- Via 的转换管道可以在工具之间建立无缝的数据流
资料来源：[Reddit - MCP universal integration layer](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/a_mcp_universal_integration_layer_cli_tool_it/)
## 版本历史
### v0.1.0 (2026-05-10)
初始版本发布，包含完整的文件转换功能：
- 支持图像、音频、视频、文档、办公文件、PDF 和压缩包格式
- 提供 `--check` 工具检查功能
- 提供 `--formats` 格式列表功能
- 支持 `--ingest` 选项与记忆系统集成
资料来源：[CHANGELOG.md - Initial release](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
## 技术实现细节
Via 的文件转换管道基于 Node.js 18+ 的原生模块实现，不依赖外部的 `node-fetch` 库，使用内置的 fetch API 进行必要的网络操作。
依赖项管理方面，转换管道仅依赖 `sql.js`（版本 ^1.14.1）用于 SQLite 知识库的读写操作，所有格式转换本身由外部工具完成。
资料来源：[package.json - dependencies](https://github.com/Vektor-Memory/Via/blob/main/package.json)
## 故障排除
### 常见问题
**Q: 转换命令提示工具未找到怎么办？**
A: 使用 `via convert --check` 检查缺失的外部工具，然后按照系统包管理器安装相应工具。
**Q: 某些格式转换失败？**
A: 确认目标格式在支持矩阵中，检查输入文件是否损坏，确保对应工具已正确安装并位于系统 PATH 中。
**Q: --ingest 选项不生效？**
A: 确认 Via 的 SQLite 数据库可正常读写，检查文件内容是否为空或格式异常。
---
## MCP 服务器模式
### 相关页面
相关主题：[连接器系统](#connectors), [安装与配置](#installation)
相关源码文件
以下源码文件用于生成本页说明：
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md) — 详细规格定义
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md) — 版本更新记录
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md) — 快速入门指南
- [README.html](https://github.com/Vektor-Memory/Via/blob/main/README.html) — HTML 版文档
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json) — npm 包配置
# MCP 服务器模式
## 概述
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 | `via serve` | Claude Desktop、Claude Code、Cursor 本地集成 | 标准输入/输出 |
| HTTP+SSE | `via serve --sse` | 远程连接、多客户端访问、Webhook 集成 | HTTP + Server-Sent Events |
stdio 模式是默认模式，专为 Claude Code 设计，进程通过标准输入输出与父进程通信。SSE 模式则通过 HTTP 服务器和 Server-Sent Events 实现实时推送，适用于需要远程调用 Via 的场景。
资料来源：[SPEC.md:7-12]()
## 可用 MCP 工具列表
Via 通过 MCP 服务器暴露以下 8 个核心工具：
| MCP 工具名 | 功能描述 | 对应命令 |
|------------|----------|----------|
| `via_task_list` | 列出所有开放任务 | `via task list` |
| `via_task_add` | 添加新任务 | `via task add` |
| `via_task_done` | 标记任务完成 | `via task done` |
| `via_memory_add` | 存储记忆/事实 | `via memory add` |
| `via_memory_search` | 关系感知的记忆搜索 | `via memory search` |
| `via_log` | 记录决策或事件 | `via log` |
| `via_context` | 拉取格式化的记忆上下文 | `via context` |
| `via_status` | 生态系统健康检查 | `via status` |
MCP 工具命名遵循 Via 命令名称的映射规则，例如 `via_task_list` 对应 CLI 命令 `via task list`，保持命名一致性便于记忆。
资料来源：[README.md:189-202]()
## 工作流程架构
```mermaid
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 服务器：
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
配置完成后重启 Claude Desktop，即可使用 Via 提供的所有 MCP 工具。
资料来源：[README.md:168-175]()
### 初始化命令
Via 提供了自动配置命令 `via init`，可自动检测已安装的 AI 工具并生成相应的 MCP 配置：
```bash
via init
```
该命令会执行以下操作：
- 检测系统中安装的 Claude Code、Cursor、Windsurf 等工具
- 生成符合各工具规范的配置文件
- 更新 `~/.via/config.json` 全局配置
资料来源：[SPEC.md:6.6]()
### SSE 模式配置
对于需要远程访问的场景，使用 SSE 模式启动 Via 服务器：
```bash
via serve --sse
```
服务器默认监听本地端口，AI 工具通过 HTTP 请求与 Via 通信。
资料来源：[SPEC.md:7-12]()
## 数据存储结构
MCP 服务器模式下，Via 在 `~/.via/` 目录下管理以下数据：
| 文件/目录 | 用途 |
|-----------|------|
| `config.json` | 用户配置、已连接工具列表 |
| `tasks.db` | SQLite 任务看板数据库 |
| `audit.db` | 合规日志数据库 |
| `personas/` | AI 人格定义文件 |
| `spend/` | 各工具使用日志 |
| `handoffs/` | 会话状态导出文件 |
这些数据由 MCP 服务器直接访问，为 AI 工具提供持久化的上下文支持。
资料来源：[SPEC.md:4]()
## 与 Slipstream 的集成
MCP 服务器模式下，Via 支持与 Slipstream 智能引擎的无缝升级：
| 功能 | Via 本地模式 | Via + Slipstream |
|------|--------------|------------------|
| 记忆搜索 | SQLite FTS 全文搜索 | BM25 + 语义向量 + 图遍历 |
| 上下文组装 | 关键词匹配 | 时间相关性 + 知识图谱 |
| 任务关联 | 扁平 SQLite | 因果链接到记忆图谱 |
| 审计追踪 | 扁平日志 | 因果决策图谱 |
当配置了 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]()
## 快速入门
```bash
# 全局安装 Via
npm install -g @vektor/via
# 启动 MCP 服务器（stdio 模式，默认）
via serve
# 或使用 SSE 模式
via serve --sse
# 初始化所有工具的 MCP 配置
via init
```
## 相关资源
- **命令参考**：[SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md) — 完整命令规格
- **变更日志**：[CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md) — 版本更新记录
- **开源地址**：[github.com/Vektor-Memory/Via](https://github.com/Vektor-Memory/Via) — GitHub 仓库
- **Slipstream 升级**：[vektormemory.com](https://vektormemory.com) — 智能引擎介绍
---
## 连接器系统
### 相关页面
相关主题：[MCP 服务器模式](#mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [connectors/claude.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/claude.mjs)
- [connectors/cursor.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/cursor.mjs)
- [connectors/windsurf.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/windsurf.mjs)
- [connectors/chatgpt.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/chatgpt.mjs)
- [connectors/langchain.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/langchain.mjs)
- [connectors/slipstream.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/slipstream.mjs)
# 连接器系统
## 概述
连接器系统（Connector System）是 Via 的核心抽象层，负责与各类 AI 工具和外部服务进行集成交互。Via 作为通用集成层，需要连接 Claude Code、Cursor、Windsurf、ChatGPT 等多个 AI 工具，而连接器正是实现这一目标的关键组件。
连接器系统的设计理念是**统一接口，统一行为**——无论底层工具的 API 或数据格式如何差异，Via 通过标准化的连接器接口提供一致的访问方式。这种设计使得 Via 能够：
- 检测已安装的 AI 工具
- 读取工具的会话日志和用量数据
- 格式化上下文供工具使用
- 通过 MCP（Model Context Protocol）与工具进行双向通信
资料来源：[SPEC.md](SPEC.md) | [README.md](README.md)
---
## 系统架构
### 架构概览
```
┌─────────────────────────────────────────────────────────────────┐
│ Via CLI / MCP Server │
├─────────────────────────────────────────────────────────────────┤
│ commands/ │ connectors/ │ utils/ │ core/ │
│ ───────── │ ─────────── │ ────── │ ───── │
│ context │ ├── claude.mjs │ config │ db │
│ task │ ├── cursor.mjs │ format │ cache │
│ spend │ ├── windsurf │ detect │ mcp │
│ ... │ ├── chatgpt │ │ │
│ │ ├── langchain │ │ │
│ │ └── slipstream │ │ │
└──────────────┴──────────────────┴──────────────┴──────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Claude Code Cursor Windsurf
────────── ────── ────────
~/.claude/ ~/.cursor/ ~/.windsurf/
projects/ usage/ ...
```
### 连接器职责分层
```mermaid
graph TD
A[连接器接口层] --> B[工具特定适配器]
B --> C[文件系统读取]
B --> D[日志解析]
B --> E[上下文格式化]
F[detect.mjs] -->|检测工具| B
G[format.mjs] -->|输出格式化| B
H[config.json] -->|存储配置| B
I[SQLite DB] -->|存储数据| B
```
每个连接器承担以下职责：
| 职责 | 描述 |
|------|------|
| 工具检测 | 检查目标 AI 工具是否已安装并可用 |
| 数据读取 | 读取工具的会话日志、用量文件、项目信息 |
| 上下文格式化 | 将 Via 的共享上下文转换为目标工具可接受的格式 |
| 状态同步 | 读写 Via 的共享状态（任务板、记忆等） |
| MCP 适配 | 提供 MCP 工具定义，使 Via 能被目标工具调用 |
资料来源：[SPEC.md:目录结构](SPEC.md)
---
## 可用连接器
### 连接器列表
| 连接器 | 文件 | 支持的工具 | 主要功能 |
|--------|------|-----------|----------|
| Claude | `claude.mjs` | Claude Code | 会话日志读取、CLAUDE.md 写入、MCP 服务 |
| Cursor | `cursor.mjs` | Cursor | 用量日志读取、规则文件写入、MCP 服务 |
| Windsurf | `windsurf.mjs` | Windsurf | 工具集成 |
| ChatGPT | `chatgpt.mjs` | ChatGPT | 用量读取、OPENAI_LOG_DIR 支持 |
| LangChain | `langchain.mjs` | LangChain | 外部集成适配 |
| Slipstream | `slipstream.mjs` | Vektor Slipstream | 升级桥接、智能引擎连接 |
资料来源：[SPEC.md:连接器目录](SPEC.md)
---
## Claude Code 连接器
### 功能概述
Claude 连接器是 Via 与 Anthropic Claude Code 之间的桥梁，负责：
1. **会话捕获**：读取 `~/.claude/projects/*.jsonl` 中的会话日志
2. **上下文注入**：写入 `.claude/CLAUDE.md` 文件供 Claude Code 使用
3. **MCP 工具暴露**：通过 MCP 协议暴露 Via 的所有命令
### 数据源
Claude 连接器读取以下位置的数据：
```
~/.claude/
├── projects/
│ └── *.jsonl # Claude Code 会话日志
└── settings/
```
### 上下文格式化
Claude 连接器将 Via 的上下文格式化为 Claude Code 可读的 Markdown 格式：
```markdown
# Via Context
## Current Task
[当前任务描述]
## Recent Decisions
[最近的决策记录]
## Open Questions
[待解决的问题]
## Relevant Memory
[相关记忆/知识]
```
资料来源：[README.md:via init](README.md)
---
## Cursor 连接器
### 功能概述
Cursor 连接器实现与 Cursor 编辑器的深度集成：
1. **用量追踪**：读取 `~/.cursor/usage/*.jsonl` 文件
2. **规则注入**：写入 `.cursor/rules/via-context.mdc` 文件
3. **MCP 服务**：通过 stdio 提供 Via 工具访问
### Cursor 规则格式
根据 Cursor >= 0.45 规范，Via 写入的规则文件结构如下：
```markdown
# Cursor Rules - Via Context
# via-context.mdc
---
description: Via integration context
---
## Current Project
[项目上下文]
## Shared Task Board
[Via 任务板内容]
## Memory Context
[相关记忆]
```
### 版本兼容性
| Cursor 版本 | 支持的功能 |
|-------------|-----------|
| < 0.45 | 基础上下文读取 |
| >= 0.45 | 完整 .mdc 规则文件支持 |
资料来源：[CHANGELOG.md:0.1.0 Fixed](CHANGELOG.md)
---
## Windsurf 连接器
### 功能概述
Windsurf 连接器提供与 Codeium Windsurf 的集成支持，与 Claude 和 Cursor 连接器遵循相同的架构模式：
- 检测 Windsurf 安装状态
- 读取相关配置和日志
- 提供上下文格式化接口
资料来源：[SPEC.md:目录结构](SPEC.md)
---
## ChatGPT 连接器
### 功能概述
ChatGPT 连接器负责与 OpenAI ChatGPT 相关的集成：
1. **用量读取**：通过 `OPENAI_LOG_DIR` 环境变量读取用量日志
2. **无 API 调用**：仅读取本地日志文件，不调用 OpenAI API
3. **统一格式**：将用量数据转换为 Via 的标准格式
### 环境变量配置
```bash
export OPENAI_LOG_DIR="/path/to/openai/logs"
```
资料来源：[SPEC.md:via spend](SPEC.md)
---
## LangChain 连接器
### 功能概述
LangChain 连接器提供与 LangChain 生态系统的外部集成能力，允许 Via 与基于 LangChain 构建的应用进行互操作。
### 集成模式
```mermaid
graph LR
A[Via CLI] -->|命令| B[LangChain 连接器]
B -->|适配| C[LangChain 应用]
C -->|结果| B
B -->|格式化| A
```
资料来源：[SPEC.md:目录结构](SPEC.md)
---
## Slipstream 连接器
### 功能概述
Slipstream 连接器是 Via 升级到 Vektor Slipstream 智能引擎的桥接组件。当用户需要更高级的功能时，此连接器提供平滑的升级路径。
### 功能对比
| 功能 | Via 本地版 | Slipstream 升级版 |
|------|-----------|-------------------|
| 记忆存储 | SQLite 关键词存储 | 向量嵌入 + 图遍历 |
| 上下文搜索 | 关键词匹配 | 语义相似度搜索 |
| 任务关联 | 扁平任务列表 | 记忆图因果连接 |
| 团队共享 | 本地单机 | 共享命名空间 |
| 审计日志 | 平面日志 | 因果决策图 |
### 升级命令
```bash
via upgrade
# 或
npx via upgrade
```
资料来源：[SPEC.md:6.10 via ingest](SPEC.md) | [SPEC.md:Slipstream](SPEC.md)
---
## 工具检测机制
### detect.mjs 工具
Via 使用统一的检测机制识别已安装的 AI 工具：
```javascript
// 伪代码示例
const detectTools = async () => {
return {
claude: checkPath('~/.claude'),
cursor: checkPath('~/.cursor'),
windsurf: checkPath('~/.windsurf'),
chatgpt: checkOpenAILogDir()
}
}
```
### 检测结果应用
工具检测结果用于：
- `via init` - 确定需要配置哪些工具
- `via status` - 显示连接状态仪表板
- `via scaffold` - 为检测到的工具生成配置文件
资料来源：[SPEC.md:utils/detect.mjs](SPEC.md)
---
## MCP 服务模式
### 服务模式
Via 连接器支持两种 MCP 服务模式：
| 模式 | 命令 | 用途 |
|------|------|------|
| stdio | `via serve` | Claude Desktop、Cursor 本地连接 |
| HTTP+SSE | `via serve --sse` | 远程访问、Web 界面集成 |
### MCP 工具列表
当作为 MCP 服务器运行时，以下工具可通过协议暴露：
```
via_task_list # 列出任务
via_task_add # 添加任务
via_task_done # 完成任务
via_memory_add # 添加记忆
via_memory_search # 搜索记忆
via_log # 记录日志
via_context # 获取上下文
via_status # 状态检查
```
### 配置示例
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
资料来源：[README.md:MCP 服务模式](README.md) | [SPEC.md:7. MCP 服务器模式](SPEC.md)
---
## 社区关注点与已知问题
### MCP 集成热度
根据社区讨论，MCP 集成是用户最关注的功能之一：
> "Built an MCP tool that connects Qwen, Claude Code, Codex... This one has a feature no other tool has"
> — Reddit r/LocalLLaMA
> "MCP + an agent-friendly component API feels like the right abstraction"
> — Reddit r/ClaudeAI
### 常见问题
#### 1. 工具检测失败
**问题**：Via 无法检测到已安装的 AI 工具
**解决方案**：
- 确认工具已正确安装并产生日志文件
- 检查配置文件 `~/.via/config.json` 中的工具路径
- 手动指定工具位置
#### 2. MCP 连接不稳定
**问题**：MCP stdio 连接偶尔断开
**建议**：
- 使用 `--sse` 模式替代 stdio 模式
- 确保 Node.js 版本 >= 18
- 检查系统资源是否充足
#### 3. 上下文格式不匹配
**问题**：工具无法正确读取 Via 提供的上下文
**原因**：不同工具对上下文格式的要求不同
**解决**：Via 连接器自动处理格式转换，但需确保工具版本兼容
资料来源：[社区上下文:Reddit 讨论](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/)
---
## ESM 兼容性
### 修复历史
v0.1.0 版本修复了重要的 ESM 兼容性问题：
| 问题 | 修复方案 |
|------|----------|
| `require()` 在 ESM 中不可用 | 替换为顶层 `import` 语句 |
| `node-fetch` 冗余依赖 | 使用 Node.js 18+ 原生 `fetch` |
| SSE 服务器响应作用域错误 | POST 请求响应仅返回给调用者 |
资料来源：[CHANGELOG.md:0.1.0 Fixed](CHANGELOG.md)
---
## 最佳实践
### 1. 初始化工作流
```bash
# 推荐首次使用流程
via init # 自动检测并配置所有工具
via status # 验证连接状态
via scaffold --preset solo-dev # 根据场景生成配置
```
### 2. 多工具环境
在同时使用多个 AI 工具时：
- 使用 `via task` 维护跨工具共享的任务列表
- 使用 `via context` 获取格式化后的上下文
- 使用 `via handoff` 在切换工具时传递工作状态
### 3. 性能考虑
- 连接器读取本地文件系统，无需网络请求
- SQLite 数据库提供高效的本地存储
- 避免频繁的上下文重新格式化操作
---
## 相关命令参考
| 命令 | 连接器相关功能 |
|------|---------------|
| `via init` | 检测并配置所有已安装工具 |
| `via status` | 显示各工具连接状态 |
| `via scaffold` | 为项目生成工具特定配置 |
| `via serve` | 启动 MCP 服务器模式 |
| `via context` | 格式化共享上下文 |
| `via spend` | 汇总所有工具的用量数据 |
---
## 扩展连接器
### 添加新连接器
如需为新的 AI 工具添加连接器支持：
1. 在 `connectors/` 目录创建新文件（如 `newtool.mjs`）
2. 实现标准连接器接口：
```javascript
// connectors/newtool.mjs
export const connectorName = 'newtool';
export async function detect() {
// 检测工具是否安装
}
export async function readUsage() {
// 读取用量数据
}
export async function formatContext(context) {
// 格式化上下文
}
```
3. 在 `via.mjs` 中注册新连接器
资料来源：[SPEC.md:目录结构](SPEC.md)
---
## CLI 命令参考
### 相关页面
相关主题：[快速入门指南](#quick-start), [MCP 服务器模式](#mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
# CLI 命令参考
Via 是 Vektor Memory 生态系统中的通用 AI 工具集成层，通过统一的命令行接口连接 Claude、Cursor、Windsurf 和 ChatGPT 等多个 AI 开发工具。本页详细说明 Via v0.1.0 版本提供的所有 CLI 命令及其使用方法。
## 快速开始
### 安装方式
Via 支持零安装运行，无需全局安装即可使用：
```bash
npx via
```
或全局安装：
```bash
npm install -g @vektor/via
via
```
### 环境要求
- Node.js >= 18
- 原生 fetch API（Node 18+ 内置）
- 无需额外依赖
资料来源：[package.json:18]()
## 命令概览
Via CLI 提供 12 个核心命令，涵盖上下文管理、任务追踪、代码索引、工具路由等功能：
| 命令 | 功能 | 核心用途 |
|------|------|----------|
| `via init` | 初始化配置 | 自动检测并连接所有已安装的 AI 工具 |
| `via memory` | 记忆管理 | 存储事实、索引代码库、关系感知搜索 |
| `via task` | 任务看板 | 跨工具共享的持久化任务管理 |
| `via log` | 活动日志 | 统一记录操作决策和事件 |
| `via ask` | 智能路由 | 将问题路由到最合适的 AI 工具 |
| `via diff` | 差异对比 | 比较不同 AI 工具对同一问题的回答 |
| `via handoff` | 状态交接 | 跨工具、跨会话导出/导入工作状态 |
| `via serve` | MCP 服务器 | 以 MCP 协议提供服务，支持 Claude Desktop/Cursor |
| `via ingest` | 知识摄取 | 通用知识入库，支持 URL、文件、目录 |
| `via context` | 上下文格式化 | 输出适配各工具格式的上下文块 |
| `via scaffold` | 项目脚手架 | 一键生成 Via 集成配置 |
| `via status` | 健康检查 | 查看整个生态系统的运行状态 |
资料来源：[SPEC.md:1-30]()
## 核心命令详解
### via init
初始化 Via 并将其连接到检测到的所有 AI 工具。
```bash
via init
```
**功能说明：**
- 自动检测系统中已安装的 AI 开发工具（Claude Code、Cursor、Windsurf、ChatGPT）
- 生成项目级配置文件 `via.config.json`
- 更新全局配置 `~/.via/config.json`
- 为支持 MCP 的工具写入 MCP 服务器配置
**输出示例：**
```
检测到工具: claude ✓ cursor ✓ windsurf ✓ chatgpt –
配置完成
```
资料来源：[README.md:40-50]()
---
### via memory
关系感知的代码索引和事实存储系统。
```bash
via memory add "JWT tokens expire in 1h"
via memory add --file ./src/
via memory search "auth"
via memory graph
via memory list
```
**子命令：**
| 子命令 | 参数 | 说明 |
|--------|------|------|
| `add` | `--file ` 或文本 | 存储事实或索引代码文件 |
| `search` | `` | 搜索相关事实和文件 |
| `graph` | - | 显示导入关系图 |
| `list` | - | 列出所有已索引文件和事实 |
**工作原理：**
Via 从代码文件中提取符号（symbols）、导入语句和函数定义，在 SQLite 中构建导入图。搜索时会遍历关系，而不仅仅是文本匹配。
```mermaid
graph TD
A[memory add --file ./src/] --> B[解析源码]
B --> C[提取符号和导入关系]
C --> D[构建导入图]
D --> E[存储到 SQLite]
E --> F[memory search 可遍历关系图]
```
**搜索结果示例：**
```
┌─ 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
└───────────────────────────────────────────────
```
**支持的编程语言：**
JavaScript、TypeScript、Python、Go、Rust 等 10+ 语言。
资料来源：[README.md:60-80]()
---
### via task
跨工具共享的持久化任务看板。
```bash
via task add "refactor auth module" --high
via task
via task done
via task start
via task list
```
**子命令：**
| 子命令 | 参数 | 说明 |
|--------|------|------|
| `add` | `` | 添加新任务 |
| `list` | - | 列出所有任务 |
| `done` | `<id>` | 标记任务完成 |
| `start` | `<id>` | 开始处理任务 |
| `delete` | `<id>` | 删除任务 |
| `update` | `<id>` | 更新任务 |
| `next` | - | 获取下一个待处理任务 |
**任务状态：**
- `open` - 开放
- `in-progress` - 进行中
- `done` - 已完成
- `blocked` - 已阻塞
**任务字段：**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | integer | 唯一标识 |
| title | text | 任务标题 |
| status | enum | 当前状态 |
| tool | text | 来源工具 |
| persona | text | 关联的 AI 人设 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
| notes | text | 备注信息 |
**数据存储：**
任务数据存储在 `~/.via/tasks.db`（SQLite 数据库），所有连接的工具都能访问同一个任务看板。
资料来源：[SPEC.md:1-20]()
---
### via log
统一的活动日志系统，自动捕获 Claude Code 会话。
```bash
via log "decided to use postgres" --tool claude
via log --scan # 一次性捕获所有 Claude Code 会话
via log --watch # 实时捕获会话完成事件
via log --today # 查看今日日志
via log search "postgres"
```
**子命令：**
| 子命令 | 说明 |
|--------|------|
| `search` | 搜索日志内容 |
| `--scan` | 扫描现有会话 |
| `--watch` | 监听新会话 |
**日志记录的信息：**
- 决策内容
- 工具来源
- 时间戳
- 上下文关联
资料来源：[README.md:90-95]()
---
### via ask
智能路由命令，根据问题类型将用户导向最合适的 AI 工具。
```bash
via ask "should I use postgres or sqlite?"
via ask "refactor auth module" --tool cursor
via ask "explain this architecture" --no-open
```
**路由逻辑（v0.1）：**
- 长时间研究任务 → Claude
- 代码补全任务 → Cursor
- 廉价摘要任务 → 最便宜的模型
**未来规划：**
基于花费和结果历史进行 ML 路由优化。
资料来源：[SPEC.md:1-10]()
---
### via diff
对比两个 AI 工具对同一问题的回答差异。
```bash
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 diff show
via diff list
```
**输出示例：**
```
┌─ 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:50-70]()
---
### via handoff
导出或导入工作会话状态。
```bash
via handoff --export
via handoff --import ./sprint3.vstate.json
via handoff --list
```
**功能：**
- 导出当前工作状态到 `~/.via/handoffs/<timestamp>.vstate.json`
- 跨工具、跨机器共享工作上下文
- 支持指定目标工具格式
**导出参数：**
| 参数 | 说明 |
|------|------|
| `--export` | 导出当前状态 |
| `--task` | 当前任务描述 |
| `--tool` | 来源工具（自动检测如省略） |
**导入参数：**
| 参数 | 说明 |
|------|------|
| `--import <file>` | 导入指定文件 |
| `--to` | 输出格式（目标工具） |
| `--print` | 打印格式化上下文块 |
**vstate.json 格式：**
```json
{
"via_version": "0.1.0",
"exported_at": "2026-05-10T12:00:00Z",
"source_tool": "cursor",
"current_task": "Refactor auth module — extract token validation",
"open_questions": [
"Should refresh tokens be stored in Redis or PostgreSQL?"
],
"decisions": [
{ "at": "2026-05-10T11:30:00Z", "decision": "..." }
]
}
```
资料来源：[SPEC.md:1-25]()
---
### via serve
以 MCP 服务器模式运行 Via，支持通过 MCP 协议调用所有命令。
```bash
via serve # stdio 模式（Claude Desktop、Cursor）
via serve --sse # HTTP + SSE 模式
```
**MCP 服务器配置（Claude Desktop）：**
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
**通过 `via init` 自动配置：**
运行 `via init` 会自动写入上述配置到用户 MCP 配置文件中。
**可用的 MCP 工具：**
| MCP 工具 | 功能 |
|----------|------|
| `via_task_list` | 列出开放任务 |
| `via_task_add` | 添加任务 |
| `via_task_done` | 标记任务完成 |
| `via_memory_add` | 存储事实 |
| `via_memory_search` | 关系感知搜索 |
| `via_log` | 记录决策或事件 |
| `via_context` | 获取格式化上下文 |
| `via_status` | 生态系统健康检查 |
资料来源：[README.md:120-140]()
---
### via ingest
通用知识摄取系统。
```bash
via ingest <url>
via ingest <file>
via ingest <directory>
```
**支持的数据源：**
| 来源 | 实现方式 |
|------|----------|
| URL | 原生 fetch |
| 文件 (txt, md, pdf) | pdftotext 转换 |
| 目录 | 递归处理，遵守 .gitignore |
**工作流程：**
```mermaid
graph LR
A[URL/文件/目录] --> B[内容提取]
B --> C[分块处理]
C --> D[存储到本地 SQLite]
D --> E[via context 可访问]
```
**本地模式限制（v0.1）：**
- 仅支持关键词分块存储
- 无向量嵌入
- 无语义搜索
**Slipstream 升级后：**
- 语义搜索
- 向量嵌入
- 图链接
资料来源：[SPEC.md:1-15]()
---
### via context
为不同 AI 工具格式化输出上下文块。
```bash
via context
via context --tool cursor
via context --format claude
```
**支持的输出格式：**
- Claude
- Cursor
- Windsurf
- ChatGPT
资料来源：[CHANGELOG.md:5-10]()
---
### via scaffold
一键生成项目脚手架，自动部署完整的 Via 集成配置。
```bash
via scaffold
via scaffold --preset solo-dev
via scaffold --preset startup-team
```
**生成的配置文件：**
| 工具 | 生成文件 |
|------|----------|
| Cursor | `.cursor/rules/via-context.mdc` |
| Claude | `.claude/CLAUDE.md` |
| 项目 | `via.config.json` |
| 全局 | `~/.via/config.json` |
**可用预设：**
| 预设 | 适用场景 |
|------|----------|
| `solo-dev` | 单人开发 |
| `startup-team` | 初创团队 |
| `enterprise-audit` | 企业审计 |
| `research` | 研究项目 |
资料来源：[SPEC.md:1-10]()
---
### via status
单命令生态系统健康检查。
```bash
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
```
---
### via audit
AI 决策合规日志，记录所有决策及其关联信息。
```bash
via audit log "使用 Redis 缓存 session"
via audit list
via audit search "postgres"
via audit export --format jsonl
```
**子命令：**
| 子命令 | 说明 |
|--------|------|
| `log` | 记录新决策 |
| `list` | 列出所有记录 |
| `search` | 搜索记录 |
| `export` | 导出日志 |
**导出格式：**
- `jsonl` - JSON Lines
- `csv` - 逗号分隔值
- `markdown` - Markdown 格式
**本地模式限制（v0.1）：**
- 扁平搜索
**Slipstream 升级后：**
- 决策因果图
- 与记忆图谱关联
资料来源：[SPEC.md:1-8]()
---
### via persona
命名 AI 角色管理，每个角色有独立的系统提示词和记忆命名空间。
```bash
via persona create cto "You are a CTO with 20 years of experience..."
via persona use cto --in cursor
via persona list
via persona delete cto
via persona show cto
```
**子命令：**
| 子命令 | 说明 |
|--------|------|
| `create` | 创建新角色 |
| `use` | 使用角色 |
| `list` | 列出所有角色 |
| `delete` | 删除角色 |
| `show` | 显示角色详情 |
**使用示例：**
`via persona use cto --in cursor` 输出针对 Cursor 格式化的系统提示块。
**存储位置：**
角色文件存储在 `~/.via/personas/` 目录，格式为 `.vpersona.json`。
资料来源：[SPEC.md:1-12]()
---
### via spend
读取并统计所有已连接 AI 工具的使用日志。
```bash
via spend today
via spend session
via spend week
via spend month
via spend leaks
via spend export
```
**数据来源：**
- Claude Code: `~/.claude/projects/*.jsonl`
- Cursor: `~/.cursor/usage/*.jsonl`
- OpenAI: `OPENAI_LOG_DIR` 环境变量
**泄露检测模式：**
- 冗长的上下文重注入
- 工具调用循环
- 大文件重复读取
- 冗余的网络请求
**注意：** 不发起 API 调用，仅读取本地 JSONL 文件。
资料来源：[SPEC.md:1-12]()
---
### via watch
监听 AI 工具的完成事件并触发通知。
```bash
via watch
```
**事件来源：**
- 文件监视器（监控工具的 JSONL 日志）
- 任务看板状态变更
- Webhook 监听器
**通知目标：**
| 目标 | 实现 |
|------|------|
| `desktop` | node-notifier |
| `slack` | Webhook |
| `discord` | Webhook |
| `webhook` | 任意 URL |
资料来源：[SPEC.md:1-8]()
---
### via sync
多机器状态同步，将 Via 状态备份到私有 GitHub 仓库。
```bash
via sync backup
via sync restore
via sync status
via sync diff
```
**备份内容：**
- `~/.via/config.json` - 用户配置
- `tasks.db` 导出 - 任务数据库
- `personas/` - 角色目录
- `audit.db` 导出 - 审计数据库
- `spend/` 日志 - 使用记录
**实现模式：**
遵循 Vek-Sync 的模式，使用相同的 GitHub 私有仓库方法和冲突检测机制。
资料来源：[SPEC.md:1-10]()
---
### via route
根据任务描述推荐使用哪个 AI 工具。
```bash
via route "研究这篇论文"
via route "写一个排序算法" --budget 0.5
via route "重构登录模块" --tools claude,cursor
```
**参数：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `<task>` | string | 任务描述 |
| `--budget` | float | 最大成本（USD） |
| `--tools` | list | 候选工具列表 |
**当前实现：** 基于规则的路由。
**未来规划：** 基于花费/结果历史的机器学习路由。
资料来源：[SPEC.md:1-8]()
---
### via upgrade
Slipstream 升级桥接命令。
```bash
via upgrade
```
用于从本地 SQLite 模式升级到 Slipstream 云端智能引擎。
**Slipstream 提供的能力：**
| 本地 SQLite | Slipstream |
|-------------|------------|
| 关键词搜索 | BM25 + 语义双通道召回 |
| 扁平任务列表 | 链接到记忆图谱的任务 |
| 简单日志 | 决策因果图 |
| 本地索引 | 向量嵌入 + 图遍历 |
| 单机使用 | 时间相关性 + 团队共享 |
资料来源：[SPEC.md:1-8]()
---
## 全局参数
所有命令支持以下全局参数：
| 参数 | 说明 |
|------|------|
| `--json` | 输出机器可读的 JSON 格式 |
| `--help` 或 `-h` | 显示帮助信息 |
| `--version` 或 `-v` | 显示版本号 |
## 数据目录结构
Via 在用户主目录 `~/.via/` 下存储所有数据：
```
~/.via/
├── config.json # 用户配置，已连接工具
├── tasks.db # SQLite：任务看板
├── audit.db # SQLite：合规日志
├── personas/ # .vpersona.json 角色文件
├── spend/ # 每日工具使用日志
└── handoffs/ # .vstate.json 状态导出
```
---
## MCP 模式集成
Via 作为 MCP 服务器运行时，连接的 AI 工具可以直接调用 Via 的所有命令。配置方式：
1. **自动配置：** 运行 `via init`
2. **手动配置：** 在 Claude Desktop 配置中添加：
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
支持的客户端：
- Claude Desktop
- Cursor
- Windsurf
- 任何兼容 MCP 的工具
---
## 常见使用场景
### 场景一：跨工具切换
```bash
# 在 Cursor 中完成部分工作后
via handoff --export --task "重构认证模块"
# 切换到 Claude Code
via handoff --import ./latest.vstate.json
via context --tool claude
```
### 场景二：代码库索引与搜索
```bash
# 索引整个项目
via memory add --file ./src/
# 搜索相关代码
via memory search "auth"
```
### 场景三：团队协作
```bash
# 同步状态到 GitHub
via sync backup
# 在另一台机器恢复
via sync restore
```
---
## 相关链接
- [Via 官方仓库](https://github.com/Vektor-Memory/Via)
- [Vektor Memory 官网](https://vektormemory.com)
- [Vex（向量存储迁移）](https://github.com/Vektor-Memory/Vex)
- [Slipstream（智能引擎）](https://vektormemory.com)
---
<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->
---
## Doramagic 踩坑日志
项目：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
<!-- canonical_name: Vektor-Memory/Via; human_manual_source: deepwiki_human_wiki -->