Note
项目处于 Nightly 阶段，尚无正式版。正式版发布前，协议、数据格式和 API 会直接改成最终形态，不做向后兼容。
- 🤖 聊天驱动的 bot。创建有名称、职责和项目目录的 bot，在它的长期聊天里提要求。协调 Agent 用自己的 Shell 和文件工具读写本机，把改代码的任务派给本机或其他设备的 Agent。
- 🌐 个人设备网络。所有设备运行同一个
vibefaceNode，经 iroh QUIC 直连或经 relay 互通。A 设备上的 bot 可以把任务派给 B 设备执行。 - 🔁 换设备接着干。任务、进度、审批和结果写进签名事件日志并同步到每台 Node。A 离线时，在 C 打开同一会话就能接手，已执行的副作用不会重放。
- 🔐 端到端加密入口。浏览器用不可导出的设备密钥与 Node 建立 Noise 通道。公网入口只转发密文，不加入网络、不存数据。
- 📦 单个二进制。网页是 React + TanStack Start 静态 SPA，内嵌在 Rust 程序里，生产环境不需要 Node.js Web 服务。
flowchart LR
U[本人的网页或手机浏览器]
G[公共入口<br>网页、relay 与密文转发]
A[Node A<br>协调 Agent]
B[Node B<br>协调 Agent 与本机工具]
C[Node C<br>协调 Agent 与历史副本]
U -->|HTTPS 内的 Noise| G
U -->|本机或 LAN| A
U -->|切换入口| C
A <-->|iroh QUIC，经 relay| G
A <-->|iroh QUIC，直连或经 relay| B
A <-->|iroh QUIC，直连或经 relay| C
| 层 | 职责 |
|---|---|
| Node（Rust） | 认证、路由、签名日志同步、写入保护、SQLite 存储、任务调度、去重和通知。 |
| 协调 Agent | Codex、Claude Code、pi、opencode 或 Cursor SDK 驱动。Cursor 用 SDK 原生自定义工具，其余经本机 vibeface tool 命令回调 Node，不需要 MCP。 |
| 执行 | 宿主命令和文件操作直接用 Agent 自己的工具。任务在本机 Codex App Server、Claude Code、pi 或 opencode 的会话里运行。 |
| 网页 | 内嵌静态 SPA。浏览器设备密钥签名，经 Noise 通道访问指定 Node。 |
几条设计约束值得先知道：
- 每个人管理自己的设备网络，网络之间完全隔离。公网服务器只是 Node 的一种部署方式，可以作为成员加入网络，也可以只当公共入口。
- bot 定义和共享聊天历史独立于本机 SDK 缓存。创建 bot 不会启动模型。
- 写操作结果未知时先核对实际结果，不换 ID 或设备重发。
- 数据目录带数据格式 epoch，程序只打开同一 epoch 的目录，不升级数据库。同一网络里的节点使用同一版本。
| 依赖 | 版本 | 用途 |
|---|---|---|
| macOS Apple Silicon、Linux x64 或 Linux ARM64（glibc） | 运行平台 | |
| Node.js | 22+ | 仅 npm 安装入口需要 |
| Codex CLI | 已安装并登录 | 可选，Codex bot 与执行任务 |
| Claude Code | 已安装并登录 | 可选，Claude Code bot 与执行任务 |
| pi | 已安装并登录 | 可选，pi bot 与执行任务 |
| opencode | 已安装并登录 | 可选，opencode bot 与执行任务 |
| Cursor SDK Bridge | v1.0.37 | 可选，用 Cursor 作为协调 Agent 时需要 |
npm Nightly 分发已配置，包尚未公开发布。首次发布后可以这样安装：
npm install -g @leaperone/vibeface@nightly
vibeface --versionnpm 包内含完整平台程序和服务脚本，不在 postinstall 阶段下载、初始化或启动服务。在此之前，可从 Releases 下载 GitHub 完整包，步骤见 安装说明。
先按部署配置选择本机目录和要启用的集成。
export VIBEFACE_DATA_DIR='<数据目录的绝对路径>'
vibeface --data-dir "$VIBEFACE_DATA_DIR"首次运行只在指定的空数据目录初始化，并监听 127.0.0.1:4790。然后：
- 在本机浏览器打开
http://localhost:4790（保存密钥需要安全上下文，请固定用localhost）。 - 填写浏览器名称和恢复包口令，下载并保存加密恢复包，创建个人网络。
- 在设备页的 AI 中打开某个服务的 Bot 开关，在 可用文件夹 里添加项目目录。
- 创建 bot，进入它的聊天开始提要求。
日常配置可在网页里完成。也可以在初始化时用参数写入所选数据目录的 config.json：
vibeface init \
--data-dir "$VIBEFACE_DATA_DIR" \
--root /absolute/path/to/projects \
--manager codex \
--codex-socket '<App Server socket 的绝对路径>' \
--workspace /absolute/path/to/manager-workspace| 参数 | 说明 |
|---|---|
--root |
允许 Agent 访问的项目目录，可重复。 |
--manager |
运行协调 Agent 的产品，取值 codex、cursor、claude、pi 或 opencode。 |
--workspace |
协调 Agent 的工作目录，须与项目目录分开。 |
--model |
模型名。省略时用该产品的默认模型，Cursor 默认 auto。 |
--listen |
监听地址，默认 127.0.0.1:4790。 |
--no-web |
启动时关闭网页和浏览器访问，保留节点传输及本地工具。 |
--relay / --relay-listen |
连接其他 Node 的 relay，或在本机运行 relay。 |
--relay-mode discovery-only |
公共服务只协助发现和直连，不转发业务数据。 |
--discovery |
配置钉住身份的公共发现服务，Node 自动选择连接路径。 |
--public-entry |
不加入个人网络的公共入口或发现服务。 |
使用 Cursor SDK 时，在运行 Node 的环境中设置 CURSOR_API_KEY。不要把密钥写进命令行、URL、Git 或聊天记录。Claude Code、pi 和 opencode 见 使用 Claude Code、pi 或 opencode。全部字段见 本机配置。
在新设备上初始化后加入网络：
vibeface init
vibeface join '<加入链接>' --name '<设备显示名称>'加入链接由管理设备的 添加设备 生成。终端会显示 6 位安全码，在管理设备上核对一致后批准。不要在新设备上另建个人网络。详见 添加自己的设备。
- 在 A 的 bot 聊天里让它把任务交给 B。进度和结果会回到原聊天，协调 Agent 汇报后可继续派发。
- A 离线时，在已同步的 C 打开同一会话，点 交给这台设备处理，由 C 的协调 Agent 接着回复。
- 普通进度和通知不调用模型。客户端离线时保留未读通知，重连后补发。
- 执行任务的 Agent 默认 bypass。会话发起的请求由协调 Agent 处理，需要本人拍板时才在 bot 聊天里提问，也可经 webhook 转发给 Grok Bot。
| 命令 | 作用 |
|---|---|
vibeface |
在明确配置的数据目录初始化（如需要）并启动节点。 |
vibeface serve |
按已有配置启动节点。 |
vibeface status |
通过本机维护 socket 检查节点状态。 |
vibeface access |
显示本机浏览器入口。 |
vibeface service |
管理后台服务与更新定时器。 |
vibeface update |
选择更新渠道、检查或应用受管更新。 |
vibeface hooks |
安装、移除或测试 Codex、Claude Code hooks 与 pi、opencode 扩展。 |
vibeface logs |
读取本机 Node 日志。 |
完整说明运行 vibeface --help，或见 安装与 CLI 管理。
有公网地址的服务器有两种用法。用 init --public-entry 运行公共入口，本地 Node 用 --entry 指向它。或者作为成员用 init --relay-listen 为个人网络运行 relay，其他 Node 用 --relay 指向它。见 配置公共入口 和 Node 之间的连接。
需要 Rust 1.91+、Node.js 22.12+、pnpm 11.9.0 和 wasm-bindgen-cli 0.2.129。
rustup target add wasm32-unknown-unknown
bash scripts/build-web-crypto.sh
bash scripts/build-web.sh
bash scripts/package-node.sh
./target/release/vibeface init \
--data-dir "$VIBEFACE_DATA_DIR" \
--root /absolute/path/to/projects
./target/release/vibeface serve --data-dir "$VIBEFACE_DATA_DIR"init 要求数据目录为空或不存在。它写入 identity.json、config.json、一次性 bootstrap.json、data-epoch.json 和 node.sqlite3，运行日志写在 node.log。serve 和 join 用目录锁独占数据目录。
bash scripts/package-node.sh 生成当前平台的压缩包和 SHA256 文件，输出到 .artifacts/packages/。
.
├── crates/
│ ├── node/ # vibeface 主程序：CLI、Node 运行时、存储、同步、调度
│ │ └── web/ # React + TanStack Start 网页，构建后内嵌进二进制
│ ├── bridge/ # Codex App Server 与 Agent 客户端
│ ├── protocol/ # 共享 RPC 与消息类型
│ └── secure/ # 设备签名、成员关系、浏览器到 Node 的 Noise 通道（含 wasm 构建）
├── npm/ # npm 分发包
├── scripts/ # 网页构建、打包、CI 与验收脚本
├── docs/ # 用户文档、协议参考与设计文档
└── install.sh # GitHub 完整包安装脚本
| 文档 | 内容 |
|---|---|
| 安装说明 | npm Nightly、GitHub 完整包、初始化、状态和后台服务。 |
| 部署与使用 Node | 局域网、公共入口、relay、SDK、后台运行、更新渠道、备份恢复。 |
| Node 协议参考 | 配置、HTTP 与浏览器通道、业务 RPC、事件 DAG、写入保护、iroh 传输。 |
| 排障 | status、node.log、诊断包，只读与分叉处理。 |
| 构建与发布 | 三个平台包、SHA256、Stable 与 Nightly 渠道、tag 规则。 |
| CI | PR 核心检查与本地专项检查。 |
- 报告问题：在 Issues 附上
vibeface --version、平台和vibeface status输出。诊断方法见 排障。请勿粘贴密钥或恢复包。 - 提交 PR：从
main拉独立分支，使用 Conventional Commits。PR 由 CI 执行核心检查。改动同步、恢复、调度或工具执行时，按 docs/ci.md 补跑本地专项并在 PR 中记录结果。
提交前可在仓库根目录运行：
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked仓库尚未包含 LICENSE 文件，开源协议待定。在协议确定前，代码默认保留所有权利。