Vela
文档 English
使用场景 产品对比 文档 发行记录 数据隐私 English GitHub 仓库 ↗

Vela 使用指南与技术文档

Vela 是专为 coding agents 打造的本地工程沉淀与实证层。本文档涵盖从系统环境、安装运行、核心工作台、CLI/MCP 集成到本地存储与信任边界的全部技术说明。

系统要求与安全签名说明

Vela 遵循本地优先（local-first）与系统原生技术栈设计，以 Swift、AppKit 原生宿主配合 WebKit 隔离，由内置 SQLite 提供存储支撑，不依赖 Node.js 或 Chromium 运行时。

  • 操作系统支持：macOS 13.0 (Ventura) 或更高版本。
  • 硬件架构：Apple Silicon (arm64) 原生架构。
  • 系统权限：标准用户权限运行。连接工程时需要对目标项目目录具备常规读写权限。
安全签名与放行指引：当前开发者预览版采用 ad-hoc 签名，尚无 Developer ID 签名和 Apple 公证。首次在 macOS 上启动时，系统 Gatekeeper 会弹出安全提示。

正确放行方式：打开 macOS 「系统设置 ➔ 隐私与安全性」，滑动到底部安全性区域，核对应用名称后点击 “仍要打开 (Open Anyway)” 即可完成针对本应用的单次系统授权。切勿使用全局禁用 Gatekeeper（如 spctl 禁用）等破坏系统安全防护的指令。

下载与安装

推荐从官方代码仓库 Release 页面获取已编译的应用压缩包并核对 SHA256 校验和：

  1. 前往 GitHub Releases (v0.1.0-preview.2)，将安装包 Vela-macOS-arm64.zip 与校验文件 SHA256SUMS 下载至同一目录。
  2. 在终端该目录下运行校验命令：shasum -a 256 -c SHA256SUMS，确认校验输出为 OK。
  3. 解压后将 Vela.app 拖拽至系统的 /Applications 应用程序文件夹中。
  4. 打开应用，在「系统设置」中核对并点击“仍要打开”后，应用即初始化本地运行环境。

从源码构建运行

Vela 项目完全开源，支持直接使用 Xcode 命令行工具链进行本地编译、测试与调试： 

# 1. 克隆代码仓库
git clone https://github.com/Atingaii/Vela.git
cd Vela

# 2. 编译项目 (Swift Package Manager)
swift build

# 3. 本地直接运行桌面宿主
swift run VelaDesktop

# 4. 打包生成独立的 macOS 应用程序包
bash scripts/package-macos.sh

打包脚本执行完毕后，生成的产物将放置于 releases/Vela.app、releases/Vela-macOS-arm64.zip 与 releases/SHA256SUMS，包含完整的 AppKit 原生宿主程序与嵌入式命令行工具。

接入首个工程

Vela 围绕具体代码仓库组织经验数据。当前开发者预览版默认使用 dev 通道及数据目录 ~/.vela-dev。接入项目后，系统将自动发现该项目关联的本地智能体会话日志：

  • 图形界面操作：点击桌面窗口左上角项目切换器旁的 + 号图标，在系统目录对话框中选择你的本地代码仓库根目录。
  • CLI 命令行添加：通过内嵌命令行向预览版数据目录注册工程： 
    /Applications/Vela.app/Contents/MacOS/vela call projects.add '{"path":"/Users/yourname/Projects/my-app"}' --home "$HOME/.vela-dev"

会话接入与格式说明 (0.1.0-preview.2 已提供)

会话工作台汇总已接入项目的 Coding Agent 调用记录。Vela 通过本地文件系统监听自动发现与解析日志流：

  • Claude Code 日志：自动读取用户主目录中的 ~/.claude/projects/ JSONL 会话文件，解析每条用户消息、助手回复以及工具调用事件（如 file.write、bash）。
  • Codex 会话：自动识别 ~/.codex/sessions/ 下的会话记录与状态流转。
  • Cursor 导入：支持只读导入 Cursor 导出的 JSON 会话文件。因 Cursor 内部日志结构随版本快速变化，目前采用防御性有界解析。
  • 有界读取与资源保护：初次扫描各 Provider 时限制最多读取 60 个日志文件，采用 256 KB 尾窗与 32 KB 文件头探测策略，以控制内存与 I/O 占用。
  • 推断状态原则：会话状态（Running、Idle、Needs Approval）完全由本地日志中最后记录的时间戳与工具事件推断得出，非系统进程存活性探针，缺失证据时明确标为未知。
  • 导出 Checkpoint：支持将当前 Git HEAD、已完成事项与测试结果导出为 Markdown 格式的交接快照文件。

项目记忆与生命周期 (0.1.0-preview.2 已提供)

项目记忆（Project Memory）用于沉淀开发规范与环境约束。系统严格遵循“已保存不等于已被模型采纳”原则：

  • 状态流转模型：
    • Candidate（候选）：从会话提取或手动录入的初始状态，包含来源会话 ID，不参与上下文召回。
    • Active（生效中）：经工程师人工审查确认并批准的状态，唯一参与 Token 预算 Recall 检索的状态。
    • Superseded（已替代）：当出现新规范时显式标记替代旧条目，保留审计追溯链条。
    • Archived（已归档）：不再适用或已废弃的条目，完全移出检索空间。
  • 7 种工程 Scope：记忆必须归属于明确的作用域：workspace-rules、build-system、lint-and-typecheck、test-practices、provider-constraints、environment-setup、debugging-playbook。
  • 预算词面召回 (Recall)：纯本地 SQLite 驱动，无远程 Embedding 服务。CLI 默认按 1000 Token 上限检索 Active 记忆；智能体启动时不自动拉取，须经由显式调用。
  • Private Library 严格隔离：私密库仅用于本地敏感笔记与个人凭据，底层硬隔离在 Agent 检索与模型 Prompt 之外。

工作流编排与审批机制 (0.1.0-preview.2 已提供)

用于编排软件工程中频繁出现的自动化检查与验证步骤。工作流文件采用 Markdown 格式组织（带 YAML/JSON frontmatter 规范头，*.md）。

  • 只读工具与变更工具分离：内置工具区分为无害只读项（git.status, git.diff, git.log）与需审批项（shell.test, shell.typecheck, file.write, agent.run）。
  • Dry Run 试运行：只读 Git 指令在当前工作区真实执行；写入和测试步骤由安全 stub 拦截，帮助你在不改变任何工作区文件的前提下验证环境与参数。注意：预演成功仅表示校验通过，不代表底层测试已被真实执行。
  • Inbox 待办把关与参数冻结：进入队列时立即计算冻结参数哈希（Frozen Argument Hash）。工程师批准该操作仅对已核对的具体参数生效一次，不针对未知副作用自动重试。
  • 本地文件写入事务与 Undo：写入前校验允许的根路径与哈希，并在本地 SQLite 记录 Undo 事务快照，支持无损还原。

Agent Lab 对照与复用机制 (当前开发分支专属特性)

版本说明：本节所描述的 Agent Lab 配对评估、双工作树隔离、SessionStart Hook 与 SafeApply/Undo 属于当前源码仓库开发分支，尚未包含在已发布的 0.1.0-preview.2 安装包中。

Agent Lab 用于系统性检验规则、记忆或提示词改动对模型输出的客观影响，拒绝盲目相信“每次调优都能自动提升质量”：

  • 配对 Git Worktree 隔离：在基于相同起点 Git Commit 的两个完全独立工作树中分别运行 Baseline 与 Candidate 配置，避免相互写入争用。
  • 三类真实客观判定：由项目独立的任务验收脚本（Verifier）进行判定，严格依据输出划分为：
    • Improved：候选配置带来确证的测试或产出改进。
    • Worse：候选配置导致了确证的指标回退或错误。
    • Inconclusive：结论不明确或证据不足。因大模型固有随机性，把 Inconclusive 视为最普遍且正常的工程现实。
  • 受限显式晋升：仅符合条件的 Memory-only 候选允许工程师手动确认晋升；证据不足或平局严禁自动激活。
  • SessionStart Hook 生成与 SafeApply / Undo：确定性生成 Hook 注入配置，经工程师在 Codex 中审阅信任后应用；每次应用附带哈希快照，支持精确 Undo。配置就绪不保证模型完全遵循。

CLI 命令行与 stdio MCP 集成

Vela 内置只读 stdio MCP 服务与丰富的命令行工具，可供外部智能体（如 Claude Desktop、Claude Code、Cursor 等）安全调用。

stdio MCP 配置

在你的智能体 MCP 配置文件（如 claude_desktop_config.json）中添加如下配置。注意：JSON 参数不支持 Shell 变量展开，请将 /Users/YOUR_USERNAME/.vela-dev 替换为你实际的用户主目录绝对路径： 

{
  "mcpServers": {
    "vela": {
      "command": "/Applications/Vela.app/Contents/MacOS/vela",
      "args": [
        "mcp",
        "--home",
        "/Users/YOUR_USERNAME/.vela-dev"
      ]
    }
  }
}

常用 CLI 指令

# 检查环境健康
/Applications/Vela.app/Contents/MacOS/vela doctor --home "$HOME/.vela-dev"

# 扫描并刷新本地日志
/Applications/Vela.app/Contents/MacOS/vela refresh --home "$HOME/.vela-dev"

# 按 1000 Token 预算显式召回记忆
/Applications/Vela.app/Contents/MacOS/vela recall "SQLite 并发" --project /path/to/project --home "$HOME/.vela-dev"

# 检索本地工程证据库
/Applications/Vela.app/Contents/MacOS/vela search "worktree 清理" --project /path/to/project --home "$HOME/.vela-dev"

数据存储与信任边界

当前开发者预览版桌面端使用 dev 分支通道，默认存储在用户主目录的 ~/.vela-dev/。 

~/.vela-dev/
├── vela.sqlite3           # SQLite 数据库（会话索引、运行台账、审批快照）
└── assets/
    ├── memory/            # 项目记忆文件 (*.md)
    ├── workflow/          # 工作流定义 (*.md，含 YAML/JSON 规范头)
    ├── guideline/         # 规约规范文件 (*.md)
    ├── library/           # 本地知识库文档 (Private 条目严格阻断在 Agent 之外)
    └── checkpoint/        # 跨模型交接总结文件
联网与信任边界：Vela 自身不包含任何第三方商业遥测或云端账户同步服务。但必须注意：当工程师显式触发基于 URL 的外部规约导入，或是批准执行包含网络调用的第三方 CLI 工具时，进程仍将发起正常的系统网络请求。请勿将本地优先误读为物理断网保证。