Stack-Cairn/LiveAgent · 上手攻略

仓库：Stack-Cairn/LiveAgent
链接：https://github.com/Stack-Cairn/LiveAgent
分类：agent / 桌面客户端（Tauri 2 + React 19 + Rust；Gateway 用 Go 1.25）
作者：spark
更新：2026-11-02

一、它是什么

LiveAgent 是一个本地优先（local-first）的 AI Agent 桌面客户端。它不是一个"套壳聊天框"，而是把大模型的推理能力和本地系统工具真正焊在一起：模型可以直接读写你的文件、执行 Bash 命令、托管长驻进程（dev server 等）、管理定时任务，你不在电脑前时还可以通过 Gateway 从浏览器远程操控它。

技术栈上分成三层，README 的架构图很清晰：

层	技术	职责
Agent GUI（桌面端）	Tauri 2 + React 19 + TypeScript 6 + Vite 8 + Tailwind CSS 4	对话、文件/命令执行、MCP 桥接、Skills、记忆
桌面端后端	Rust + Tokio + SQLite（rusqlite）+ tokio-tungstenite	本地工具执行、进程管理、SQLite FTS 全文检索
Agent Gateway	Go 1.25 + WebSocket + Protobuf + HTTP	远程协议中继 + 内嵌 React WebUI
LLM 运行时	内置 K-brain 可执行文件	走 canonical HTTP / SSE 协议接入模型

仓库同时产出桌面安装包和 Gateway 容器镜像，是目前少见的"桌面客户端 + 远程网关"一体化的开源 Agent 应用。

二、解决什么问题

只会聊天、不会干活：多数 AI 桌面端停在对话框层面，LiveAgent 给了完整的本地工具集——Read / Write / Edit / Delete 精确文件操作，Glob / Grep 模式与正则搜索，非交互 Bash 执行（可设 cwd / timeout），以及 ManagedProcess 托管 dev server 这类长驻任务。
工具生态封闭：Tauri 侧原生桥接任意 stdio / http MCP server，工具名规范化为 mcp_<server>_<tool> 避免冲突；同时支持 Skills 技能包按需加载（渐进式披露），接入 ClawHub 商店。
上下文丢失：桌面端用 Segment + Summary Checkpoint 双层持久化完整历史；Gateway 侧用有界 seq window 补齐短时断线，重连后自动收敛。
人不在电脑前：Gateway 提供 WebUI，浏览器里就能指挥本地 Agent。
跨项目并行：Sub-agent 委托支持 worktree 隔离 + 自动合并。

模型侧内置 Claude（Anthropic）、Codex（OpenAI）、Gemini 三套协议，并支持自定义 Base URL 接入任何兼容的第三方服务。

三、快速安装

桌面端（推荐路径，零配置）

安装包由 GitHub Actions 自动构建、签名并发布，直接去 Releases 下载。

⚠️ 版本锚点：本文核验时最新 release 为 v2.0.0（tag v2.0.0，发布于 2026-11-02，指向 main 分支），文件名形如 LiveAgent-2.0.0-<platform>。版本推进很快（README 中仍有 v1.1.8 等旧 tag 的搜索快照），下载前请以 Releases 页实际 tag 为准。

平台	要求	安装
macOS	Intel x64 / Apple Silicon aarch64 均支持	下载对应 DMG 拖入 Applications；已 Apple 签名+公证，无需手动绕过安全提示
Windows	x64，需要 WebView2 运行时（Win11 自带）	`Setup.exe`（普通用户）/ `.msi`（企业静默安装）/ `portable.zip`（免安装）
Linux	x86_64，需要 WebKitGTK 4.1（Ubuntu 22.04+ / Debian 12+）	AppImage（`chmod +x` 后直跑）/ `.deb`（`sudo dpkg -i ...`）/ `.rpm`（`sudo rpm -i ...`）

Linux 装不上 WebKitGTK 是最常见的翻车点，Ubuntu 22.04 以下建议直接换 macOS/Windows 或用 AppImage。

Gateway（只有需要浏览器远程访问时才装）

# 拉取镜像（GitHub Actions 构建，multi-arch: amd64 / arm64）
docker pull ghcr.io/stack-cairn/liveagent-gateway:latest

# 后台运行（HTTP/WebSocket → 宿主机 3000）
docker run -d \
  --name liveagent-gateway \
  --restart unless-stopped \
  -p 3000:8080 \
  -v liveagent-gateway-data:/var/lib/liveagent \
  -e LIVEAGENT_GATEWAY_TOKEN=your-token \
  ghcr.io/stack-cairn/liveagent-gateway:latest

命名卷 liveagent-gateway-data 持久化 Gateway 数据库与独立签发的 Agent Token，重建容器不丢。升级 = 拉新镜像 → 删旧容器 → 同参数重建：

docker pull ghcr.io/stack-cairn/liveagent-gateway:latest \
  && docker rm -f liveagent-gateway \
  && docker run -d \
    --name liveagent-gateway \
    --restart unless-stopped \
    -p 3000:8080 \
    -v liveagent-gateway-data:/var/lib/liveagent \
    -e LIVEAGENT_GATEWAY_TOKEN=your-token \
    ghcr.io/stack-cairn/liveagent-gateway:latest \
  && docker image prune -f

从源码构建（开发者）

pnpm install --frozen-lockfile   # 仓库根目录安装前端依赖

make dev                # 启动 Tauri 开发模式（带 Session Workbench）
make build              # 构建桌面应用
make dev-gateway        # 启动 Gateway 开发服务
make gateway-docker-build   # 构建 Gateway 镜像
make proto              # 重新生成 Protobuf 代码
make clean              # 清理构建产物

CI 门禁（提 PR 前要全绿）：pnpm build:gui、pnpm lint:ui && pnpm lint:gui、pnpm test:gui、Rust 侧 cargo check --manifest-path crates/agent-gui/src-tauri/Cargo.toml --tests；改了 Gateway 还要 go test ./...。

四、核心用法

4.1 模型接入

桌面端在设置里填 Anthropic / OpenAI / Gemini 协议任一，或填第三方兼容服务的 Base URL。密钥只存在桌面端本地——Gateway 是纯协议中继，不碰文件系统、不存任何凭据（README FAQ 明确承诺这一点）。

4.2 MCP 桥接

在「设置 → 资源与自动化」中统一管理 Skills、MCP、定时任务、记忆与 Hooks。MCP Hub 支持 stdio / http / sse 三种 transport：

添加 server → 勾选 enabled + selected → Rust runtime 拉起 server 并 tools/list → 前端把工具名规范化为 mcp_<server>_<tool> 暴露给模型 → 模型调用 mcp_call_tool，结果进入 tool trace。
MCP Registry 聚合了官方 registry（registry.modelcontextprotocol.io）、Smithery、Glama 三个来源，统一归一化为 McpRegistryCard。
典型 stdio 配置形如：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@some/mcp-server"]
    }
  }
}

4.3 Skills 技能包

运行时根目录：~/.liveagent/skills；内置 skills-creator（教模型造新 Skill）与 skills-installer（教模型装 Skill），always enabled。
SkillsManager 支持 read / list / install（本地目录、.zip/.skill、HTTP(S)、GitHub repo/tree/blob）/ create / validate / package / clawhub_search / clawhub_install。
写侧由进程级 skills_write_guard() 串行化（agent 调用、gateway 转发、UI 后台安装、builtin seeding 四路写者），安装走 stage-then-swap：内容先在 <root>/.staging/ 完整构建，再原子 rename 入位，读者永远看不到半成品。

4.4 本地工具与长驻进程

日常对话里直接说需求即可触发 Read/Write/Edit/Glob/Grep/Bash。Bash 支持非交互执行与 cwd / timeout；dev server 之类长驻进程交给 ManagedProcess 监督。Sub-agent 可并行执行，用 worktree 隔离后自动合并。

4.5 定时任务

「设置 → 资源与自动化 → 定时任务」支持三种 cron job 类型：bash / http / prompt，后台自动执行。

4.6 远程访问（Nginx 反代）

协议 v2 起，WebUI、HTTP API、浏览器与桌面端的 WebSocket 全部走同一个 HTTP 端口（默认 3000）。WebSocket 升级路径有 /ws/v2、/ws/v2/agent、/ws/v2/terminal 以及 /t/ 下的隧道，最省事的做法是整个 vhost 都开 upgrade：

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # Gateway 的同源校验会比对浏览器 Origin 与 X-Forwarded-Proto + Host
    proxy_set_header Host $host;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Gateway 每 15s ping 一次 WebSocket，超时给足但别无限
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_buffering off;
}

server 块需 listen 443 ssl;，client_max_body_size 要够大（如 100m）以支持附件上传。反代后必须把设置 → Remote 页的 Gateway 地址改成 HTTPS URL、端口填 443，这是最容易漏的一步。

4.7 记忆

Markdown + SQLite FTS 全文检索双层持久化，跨会话知识管理。侧栏快捷入口的可见性保存在 customSettings.sidebarShortcuts（skills/mcp/cron/memory），并经 Gateway 在桌面端与 WebUI 间双向同步。

五、典型适用场景

本地代码库重构/批量改造：让 Agent 真的去改文件、跑 pnpm test、修到测试通过，而不是只给代码建议。
起服务并自检：ManagedProcess 拉起 dev server，Agent 自己 curl 检查页面、修报错、迭代。
离开工位后仍能指挥：Gateway + WebUI，手机/另一台电脑浏览器里继续派活。
定时自动化：每天定时跑脚本、抓接口、汇总报告（bash / http / prompt 三类 job）。
多任务并行：Sub-agent + worktree 隔离，同时推进几条独立改造线。
私有化/合规：模型密钥不出本机，Gateway 不存凭据，适合对数据外传敏感的团队。

六、坑与注意

Linux 依赖 WebKitGTK 4.1：Ubuntu 22.04 / Debian 12 起才有，24.04 可用；更老的发行版建议走 AppImage 或换平台。Windows 需 WebView2（Win11 自带，Win10 可能要单独装）。
macOS 架构要选对：Apple Silicon 选 -aarch64.dmg，Intel 选 -x64.dmg，选错无法启动。
Nginx 反代后地址必须改成 HTTPS + 443：Gateway 有同源校验（比对 Origin 与 X-Forwarded-Proto + Host），不按 README 提示改会导致浏览器端连不上。
Gateway 容器端口映射别搞混：容器内 HTTP 实际监听 PORT=8080，映射到宿主机 3000，Nginx proxy_pass 要写 127.0.0.1:3000。
Gateway 每 15s ping 一次 WebSocket：proxy_read_timeout 太短（如默认 60s 尚可但余量小）会周期性断连，README 建议 300s。
升级 Gateway 一定要用同参数重建容器：docker rm -f 后忘记带 -v liveagent-gateway-data 或改了 -e LIVEAGENT_GATEWAY_TOKEN，会导致 Gateway 数据库或 Agent Token 丢失，需要重新签发。
API Key 只在桌面端：不要指望 Gateway 侧能替换密钥；第三方中转服务的 Base URL 会在本机直连，介意的话自建代理。
MCP server 只在 enabled AND selected 时才加载：只勾一边的常见结果是"配了但模型看不到工具"，先在 MCP Hub 里 tools/list 验证。
ClawHub 同名 slug 会 409：ClawHub 以 ownerHandle + slug 为唯一身份，光靠 slug 合并会撞名；官方规范是 slug 与显示名分离。
非 chat 作用域（cron 等）禁止 MCP 写操作与 restart/stop：定时任务里不能改 MCP 配置，这是有意的安全设计。
⚠️ 待补：本次核验未取到 v2.0.0 release 的完整 changelog 正文与协议 v2 的字段级规范，/ws/v2 具体帧格式、latest.json 更新通道字段语义均未逐一验证；接入第三方实现时建议先读 docs/architecture/。
⚠️ 赞助商中立性：README 顶部有 API 中转服务（PackyCode / RightCode / Cubence）赞助，且明确说明"开发本软件所使用的大部分模型资源由这些服务提供"。这是正常的开源赞助，但意味着项目与中转服务存在商业关联，评估其默认配置中立性时值得留意。

七、与同类对比

项目	形态	本地执行	远程访问	生态扩展	适合谁
LiveAgent	Tauri 桌面客户端 + Go Gateway	完整（文件/Bash/进程/子 Agent）	Gateway + WebUI（WebSocket + Protobuf）	MCP（stdio/http/sse）+ Skills + ClawHub	要真动手 + 要远程 + 要隐私的开发者
Claude Code / Codex CLI	CLI	完整	需自行套壳	MCP + Skills	习惯终端、愿意写配置的工程师
Cursor / Windsurf	IDE 插件	受宿主 IDE 限制	弱	MCP	日常写代码要 IDE 内联体验
Open WebUI	自托管 Web	容器内	有	有插件生态	团队共享、多用户、想自托管聊天前端
Dify / Coze 类平台	低代码平台	弱（沙箱）	有	节点式编排	想让非工程师搭工作流

差异化优势："本地优先 + 真执行"是它的核心，Gateway 只做协议中继而非执行引擎，这是它和"云端 Agent 平台"最本质的区别；代价是自建成本高于纯 Web 产品，跨平台打包与 Linux 依赖也更繁琐。

八、一句话推荐

想装一个真能改文件、跑命令、还能从浏览器远程指挥的本地 Agent 桌面客户端，LiveAgent 值得试；但它 v2.0.0 刚发布、Linux 依赖偏新，且 Gateway 反代细节较琐碎——个人尝鲜正好，团队生产环境请先在非关键机器上压一轮。