| 命令 |
作用 |
make dev |
启动桌面 GUI 开发模式。 |
make build |
构建桌面 GUI。 |
make desktop-build-macos |
macOS 普通桌面打包。 |
make desktop-build-macos-release |
macOS Developer ID 签名、公证相关 release 打包。 |
make desktop-build-macos-intel |
Intel macOS 目标构建。 |
make desktop-build-macos-m |
Apple Silicon macOS 目标构建。 |
make desktop-build-windows |
Windows 桌面目标构建。 |
make desktop-build-linux |
Linux 桌面目标构建。 |
make dev-gateway |
本地启动 Go Gateway 开发服务。 |
make dev-webui |
本地启动 Gateway WebUI Vite 开发服务。 |
make proto |
生成 Gateway proto。 |
make webui |
构建 Gateway WebUI 静态资源。 |
make gateway-build |
proto + webui + Gateway 构建。 |
| 子项目 |
Manifest |
说明 |
| Rust workspace |
Cargo.toml |
根工作区，包含 Tauri/Rust crate。 |
| GUI frontend |
crates/agent-gui/package.json |
桌面 React/Tauri 前端依赖与脚本。 |
| Gateway |
crates/agent-gateway/go.mod |
Go Gateway 依赖。 |
| Gateway WebUI |
crates/agent-gateway/web/package.json |
浏览器 WebUI 依赖与构建脚本。 |
| 场景 |
命令 |
| GUI build |
pnpm -C crates/agent-gui build |
| WebUI build |
pnpm -C crates/agent-gateway/web build |
| Gateway tests |
cd crates/agent-gateway && go test ./... |
| Gateway lint |
cd crates/agent-gateway && golangci-lint run ./... |
| Proto 检查 |
make proto-check（buf lint + 对 origin/main 的 breaking 检查） |
| Tauri/Rust tests |
cargo test --manifest-path crates/agent-gui/src-tauri/Cargo.toml |
| 前端专项测试 |
pnpm -C crates/agent-gui test:frontend |
| diff 空白检查 |
git diff --check |
| 当前改动 |
git status --short |
工具链版本由根 mise.toml 固定（git 跟踪），mise install 一键对齐，CI 使用相同版本。
实际脚本名称可能随 package.json 调整，运行前以当前 manifest 为准。
| 路径 |
说明 |
~/.liveagent/config.sqlite |
桌面端 settings 数据库。 |
~/.liveagent/chat-history.sqlite3 |
Chat history 数据库。 |
~/.liveagent/memory/ |
Memory Markdown 根目录与 memory-index.sqlite3。 |
~/.liveagent/skills |
Skills runtime root。 |
~/.liveagent/default-project |
首次安装/空 workdir 时的默认项目目录。 |
~/.liveagent/debug/*.jsonl |
debug JSONL 日志。 |
| 项 |
说明 |
| HTTP |
internal/server/http.go 注册 /ws/v2* 三链路、/api/status、/api/files/import、public share 和静态资源。 |
| Proto |
改 proto/v2/*.proto 后执行 make proto（buf 生成 Go+TS），生成物随源同 PR 提交；make proto-check 把关破坏性变更。 |
| Shutdown |
make dev-gateway 应支持 Ctrl+C 后 HTTP 干净退出。 |
| WebUI embed |
Gateway build 通常依赖 make webui 先产出静态资源。 |
| 新增桌面端能力 |
proto/v2/gateway.proto 加信封臂（编号只增不改）→ make proto → v2 直通白名单（internal/protocol/pbws/guard.go）放行 → 各端生成物随源同 PR 提交；新增网关本地操作则在 v2 帧（proto/v2/gateway_ws.proto）加臂。 |
| 弃用惯例 |
Go // Deprecated: <原因；替代物；删除条件>、Rust #[deprecated]、TS @deprecated、proto option deprecated；弃用代码原地保留只修 bug，删除前先经使用打点观察。 |
| 代码类型 |
位置 |
| 传输机制（写泵/背压/心跳，帧格式无关） |
internal/transport/wscore |
| v2 协议编解码/握手/直通/扇出 |
internal/protocol/pbws |
| 跨协议域逻辑（终端门控、Origin 校验等） |
internal/protocol/shared |
| chat 命令编排 |
internal/chatcmd |
| 会话状态与关联路由（transport 无关） |
internal/session |
| 日志装置与协议使用打点 |
internal/observability |
| HTTP 入口与 public share |
internal/server |
| 改动类型 |
需要同步检查 |
| Settings 子页面 |
crates/agent-gui/src/pages/settings/* 与 crates/agent-gateway/web/src/pages/settings/*。 |
| Chat 气泡/侧边栏/上传 |
GUI src/pages/chat/src/components/chat 与 WebUI 对应 copy。 |
| Skills Hub |
GUI/WebUI pages/skills-hub、lib/skills、i18n。 |
| MCP Hub |
GUI/WebUI pages/mcp-hub、lib/mcpRegistry、i18n。 |
| Provider 设置 |
GUI/WebUI settings、Rust settings、Gateway redaction、模型请求层。 |
| Memory |
Rust MemoryStore、GUI/WebUI MemoryPanel、Gateway memory.manage、MemoryManager tool。 |
本文档树只描述当前架构，不要求启动 dev server 或跑 build。若后续文档改动伴随代码改动，应按触达模块补充对应 build/test。