Vela

Vela 是一个 OpenCode-native 的 PM-to-PR 交付层。

它面向真实 Conduit 仓库，把产品经理的自然语言需求推进为可验证、可审计、可创建 PR 的代码变更。OpenCode 负责 coding-agent runtime，Vela 负责任务、worktree、交付协议、artifact、验证门槛和 PR 出口。

Vela Task
  = Conduit task worktree
  + OpenCode primary session
  + Vela Pilot agent
  + .vela/plan.md
  + .vela/pr.md
  + verification / commit / PR gate

产品边界

OpenCode 负责：

• primary session、模型循环、工具调用和 shell 执行。
• 文件编辑、测试命令、diff、abort。
• question、permission、subagent。
• OpenCode app shell 的基础交互体验。

Vela 负责：

• PM 需求入口、任务列表、task console。
• task state、event、artifact、runtime binding。
• Conduit worktree 创建和隔离。
• Vela-managed OpenCode profile、Pilot / Explorer / Reviewer agent。
• .vela/plan.md、.vela/pr.md、.vela/skill-proposal.md。
• artifact sync、verification、PR-ready gate。
• GitHub PR 创建入口。
• delivery skill 沉淀和 profile 投影。

Vela 不自研第二套 IDE，也不把 OpenCode 降级成“命令启动器”。Vela 的价值在于把 coding-agent runtime 包装成稳定的交付产品协议。

交付链路

PM 输入自然语言需求
  -> Vela 创建 task 和隔离 Conduit worktree
  -> 绑定 OpenCode primary session
  -> Vela Pilot 澄清需求
  -> Pilot 写 .vela/plan.md
  -> 用户批准执行计划
  -> Pilot 在同一 session 内改代码、补测试、跑验证、创建 commit
  -> Pilot 写 .vela/pr.md
  -> Vela 同步 artifact 并判断 pr_ready
  -> 用户点击 Create PR
  -> Vela API 创建 GitHub PR

pr_ready 不是模型自称完成，而是来自可观察证据：ready plan、真实 diff、验证记录、测试证据或用户豁免、本地 commit、PR handoff、pending question / permission 状态和 PR provider 返回结果。

快速启动

1. 准备目标仓库

Vela 需要一个本地 Conduit clone 或 fork 作为目标仓库。

git clone <your-conduit-repo> ../conduit-realworld-example-app

2. 安装依赖

pnpm install
cp .env.example .env

3. 配置 .env

最少需要配置：

VELA_SANDBOX_REPO_PATH=../conduit-realworld-example-app

VELA_OPENCODE_SERVER_URL=http://127.0.0.1:4096
VELA_OPENCODE_PROFILE_ROOT=.opencode/vela
VELA_OPENCODE_PROVIDER=your-provider-id
VELA_OPENCODE_MODEL=your-provider-id/your-model-id
VELA_LITELLM_BASE_URL=http://127.0.0.1:4000/v1
VELA_LITELLM_API_KEY=

VELA_GITHUB_PR_PROVIDER=gh
VELA_GITHUB_BASE_BRANCH=main

密钥只放在本地 .env、OpenCode profile secret file 或部署密钥系统中，不提交到仓库。

4. 初始化 OpenCode profile

pnpm run opencode:sync-env
pnpm run opencode:doctor

opencode:doctor 应能看到 Vela profile、provider、model、agent、plugin 配置。

5. 启动本地开发环境

pnpm dev

默认入口：

Vela Web:       http://127.0.0.1:5173
Vela API:       http://127.0.0.1:8787
OpenCode Shell: http://127.0.0.1:5174

先检查：

http://127.0.0.1:5173/api/runtime/status

返回 mode: "full_runtime" 时，才能创建真实可执行 task。

常用命令

pnpm run build
pnpm run test
pnpm run typecheck
pnpm run opencode:doctor

pnpm dev
pnpm run live
pnpm run live:status
pnpm run live:stop

pnpm run live 会启动隔离 live run，生成运行证据：

.vela-live-runs/<run-id>/
  runtime/vela-api.db
  worktrees/
  opencode-profile/
  evidence/
  playwright-report/index.html
  live-pr.log
  status.json

工作区结构

apps/api                 Vela API、状态机、artifact sync、PR gate、PR 入口
apps/web                 Vela home、task console、timeline、diff、verify、PR 面板
apps/opencode-shell      Vela 定制 OpenCode shell 与 Workspace 面板

packages/core            共享 schema、task stage、artifact、handoff、verify DTO
packages/storage         SQLite / Drizzle 存储
packages/opencode-runner OpenCode profile、agent、plugin、session 适配
packages/repo-runner     Conduit worktree、diff、git 能力
packages/verifier        验证命令发现和执行
packages/pr              GitHub PR provider

scripts/                 dev runtime、live run、quality gate、OpenCode profile 工具
docs/                    文档