01 · 系统总览与前端

技术架构第一篇：系统长什么样、为什么这么分层、前端怎么和 bridge 通信。 对应「技术架构长视频」章节 1（时间点待录制）。来源：ARCHITECTURE.md §1–§2。

---

§1 系统总览

核心：Windows-first 多 Agent AI 桌面应用。

电子桌面壳(Electron)  ←──────────────────►  本地 Bridge(FastAPI)
  Vue3+Pinia+Vite                      127.0.0.1:18711 (HTTPS/HTTP2)
  组件/工坊/市场 UI                        会话/工具/记忆/调度
                                              │
            ┌─────────────────────────────────┼────────────────────┐
            ▼                                 ▼                    ▼
     OpenAI 兼容 LLM *N                   本地小模型            工具系统
     (各类 agent/router)                  (rewriter/decider/     (browser/DH/
                                          memorizer-writer)       multimodal/…)

• 为什么桌面前端用 Electron：复用系统 API（托盘/自启动/浏览器共享 Profile）、桌面限制少、跨平台（但以 Win 为主）。
• 为什么后端只一个桥：单进程内存共享、避免 C10K 的 IPC 复杂度、启动链可控。
• 为什么能力边界清晰：记忆/对话/工具都在 bridge 一个进程内 → 隐私可控、故障可诊断。

§2 前端：Electron + Vue 3 + Vite

• 技术栈：Vue3 + TypeScript + Pinia；Vite 构建。
• 目录：electron/renderer/（组件/工坊/市场）、electron/electron/（主进程 main.js + python.js 启动桥）。
• 前端 ↔ Bridge 通信：
  • 主进程 python.js 负责 spawn bridge（BRIDGE_PORT=18711、健康探针）；
  • 端口冲突时 pickFreePort() 选新端口，发布到 workspace/.bridge.port + .bridges.json；
  • renderer 经 preload 暴露的 window.familiars API 调用 HTTP/SSE。

关键设计决策（为什么不用 LangChain/AutoGen 等）：详见 03-Agent 管线 §4.1。

---

视频时间点映射

视频时间点	内容
（待录制）	系统总览动画 + 为什么 Electron + FastAPI 单进程
（待录制）	renderer → main → bridge 一条请求走通全流程

---

下一篇：02-Bridge 层 →