Appearance
安装
本文覆盖三种安装路径：Windows 一键安装（推荐）、源码运行（开发者）、Docker Relay（仅部署交换所/中继）。Familiars 是 Windows-first 应用，以下以 Windows 为主，macOS 支持有限（见文末）。
一、Windows 一键安装（推荐）
⏳ 内容待录制：安装包分发渠道（官网下载 / 静默安装/ 自动生成 .env）将在 M0 装修时补齐。
安装包制作方式（开发者视角，供内部复用）：
- 进入
electron/，运行npm run electron:build（Vite 打包 renderer + electron-builder 产出 Windows 安装包）。 - 安装包默认会把 Python 侧依赖一并打进
extraResources；首次启动自动生成workspace/与.env。 - 用户只需双击安装 → 首次启动引导填入 LLM API 端点（
BASE_URL/API_KEY/ 模型）。
二、源码运行（开发者 / 自 build）
前置：Windows + Python 3.10+ + Node.js 18+。
bash
# 1. 克隆并进入仓库
git clone <repo-url> familiars
cd familiars
# 2. 创建虚拟环境并装依赖
python -m venv .venv
source .venv/bin/activate # PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 3. 配置 .env（必需字段见下）
# cp .env.example .env 然后编辑.env 必需字段：
| 变量 | 说明 |
|---|---|
BASE_URL | LLM OpenAI 兼容端点，如 https://api.familiars.cn/v1 |
API_KEY | 你的 API 密钥 |
DEFAULT_MODEL | 默认对话模型 |
MANAGER_MODEL | 管理者（agent 0）模型，通常更强 |
EMBEDDING_MODEL | 默认 BAAI/bge-m3 |
RERANKER_MODEL | 默认 BAAI/bge-reranker-v2-m3 |
常用调节项：MAX_TURNS(50)、TIMEOUT(300)、DIALOGUE_EXPIRE_TIME(3600)、SLIDE_WINDOW_SIZE(5)；GPU 分级用 FAMILIARS_TIER* 前缀。
启动
bash
# 方式 A：仅后端 bridge（推荐后端测试用）
.venv/Scripts/python -m src.bridge.run
# 服务 https://127.0.0.1:18711（hypercorn + HTTP/2 + 自签证书）
# 方式 B：Electron 全栈（dev）
cd electron && npm install
npm run electron:dev
# 方式 C：CLI 驱动（需已运行 bridge）
python main.py agents list --pretty
python main.py chat stream --prompt "hi" --agent-id 1FAQ：bridge 端口被占时用
FAMILIARS_HTTP_INSECURE=1走 HTTP 回退；端口文件在workspace/.bridge.port。
三、Docker Relay（仅部署交换所/中继）
如需自托管 Broker 交换所（relay），仓库自带 deploy/relay/app/：
bash
cd deploy/relay/app
cp .env.example .env # 填 DOMAIN / CLOUDFLARE_API_TOKEN 等
docker compose up -d架构：Cloudflare → Caddy:443(DNS-01) → relay:18712。详见 deploy/relay/app/README.md 与 docs/install-docker.md。
四、macOS 说明
本仓库 Python 侧与 Electron 侧以 Windows 为主；assistant.py/autorun.py/device.py 存在 macOS 分支但部分落后 Windows。macOS 上部分功能（设备指纹、自启动）可能不稳定，如需支持请优先使用 Windows 环境。
五、疑难
| 问题 | 处理 |
|---|---|
pip install 慢 | 用国内镜像 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt |
| 启动报 self-signed cert 信任 | Electron 端自动信任workspace/.bridge.crt；CLI/浏览器手动信任一次即可 |
| 端口被占 | 查看 workspace/.bridge.port；pickFreePort() 会自动选新端口 |
用uvicorn src.bridge.app:app --reload | 不要用 —— 丢 HTTP/2 且会在 worker 线程 race 初始化 CUDA，Windows WDDM 下崩溃 |
下一步：快速上手 →