环境搭建与开发约定

从零搭建 Familiars 开发环境的完整步骤。包含 Python 后端、Electron 前端、环境变量、测试红线。

1. 仓库目录布局

路径	说明
`src/`	Python 后端。`bridge/` = FastAPI 路由层；`models/` = Agent / 对话 / 记忆；`tools/` + `utils/` = 工具系统；`base/` = 配置、GPU 分级、加密、路径对齐；`storage/` = SQLite + 迁移；`broker/` = 交换所层
`electron/`	Electron 桌面端。`electron/main.js` = 主进程；`electron/python.js` = bridge 生命周期管理；`renderer/` = Vue 3 + Vite 前端
`workspace/`	运行时数据。`familiars.db` (SQLite)、`SECRET.json`、`agents/`（每 agent 目录）、`manager/`、`marketplace_host/`、`.bridge_token`、`.bridge.port`、`.bridge.crt`
`test/`	全量测试（pytest）。含 `bridge/`、`decider/`、`broker/`、`recipes/`、`acceptance/`
`deploy/relay/`	Broker 中继 relay 的独立部署（Docker + Caddy）
`main.py`	CLI 入口，包装 bridge 全部 REST 端点

2. 后端环境搭建

2.1 创建虚拟环境

bash

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows CMD
# .venv\Scripts\Activate.ps1       # Windows PowerShell

2.2 安装依赖

依赖定义在 requirements.txt（151 行，涵盖 ML / 多媒体 / 平台专用包）。

bash

# Windows (CUDA 12.6)
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126

# macOS (CPU/MPS)
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cpu

关键注意：

torch==2.9.0+cu126 / torchvision==0.24.0+cu126 / torchaudio==2.9.0+cu126 必须用 PyTorch 索引。直接 pip install torch==2.9.0 会拿到 CPU 版本，本地 QLoRA 模型推理慢 10×。
onnxruntime==1.28.0（非原始 1.26.0）—— 1.26.0 编译于 NumPy 1.x，NumPy 2.x 下 rembg 导入会报 AttributeError: _ARRAY_API not found。
平台专用包用 sys_platform 守卫：
- Windows only: uiautomation、wcferry（微信 RPC）、pycaw、comtypes、wmi、pywin32
- macOS only: AppKit、Quartz

2.3 核心依赖一览

包	用途
`fastapi==0.136.1` + `hypercorn[h2]>=0.16.0`	HTTP/2 + HTTPS bridge
`openai==2.36.0`	LLM API 客户端
`torch==2.9.0+cu126` + `transformers==4.57.3` + `peft==0.19.1`	本地 QLoRA 小模型 (rewriter/decider/memorizer)
`sentence_transformers==5.2.2` + `FlagEmbedding==1.4.0`	RAG 嵌入 (bge-m3)
`onnxruntime==1.28.0` + `rembg` (via insightface)	数字人抠图
`faster-whisper>=1.0.0`	ASR 语音识别
`playwright==1.59.0`	浏览器自动化
`apscheduler==3.11.2`	定时任务调度
`cryptography==45.0.5`	HKDF 密钥派生 + 加密
`pydantic==2.13.4` + `pydantic-settings>=2.5.0`	配置校验
`httpx==0.28.1`	异步 HTTP 客户端
`beautifulsoup4==4.14.3` + `pdfplumber==0.11.4` + `python_docx==1.2.0` + `openpyxl==3.1.5`	文档解析
`paddleocr==3.5.0` + `opencv_python==4.12.0.88`	OCR
`sounddevice>=0.4.6` + `webrtcvad-wheels>=2.0.14`	电话通话音频环回
`datasets==4.8.5` + `trl==1.4.0`	数据生成/训练管线

3. 环境变量配置

配置由 src/base/config.py 集中校验（pydantic-settings）。所有变量在 .env 文件中设置。

3.1 必填变量

变量	说明	示例
`BASE_URL`	OpenAI 兼容 API 基础 URL	`https://api.openai.com/v1`
`API_KEY`	LLM API 密钥	`sk-...`
`DEFAULT_MODEL`	默认对话模型	`gpt-4o`

缺失任一会在 bridge 启动时抛出 ValueError: Missing required environment variable(s): ...。

3.2 LLM 配置

变量	默认值	说明
`MANAGER_MODEL`	`gpt-4o`	AssistantManager 执行摘要/人设演化专用模型
`MINI_MODEL`	`Qwen2.5-1.5B`	本地轻量模型（rewriter/decider）
`FAST_MODEL`	`""`	低延迟快速模型（草稿解析等），空 = 回退 `DEFAULT_MODEL`
`BETA`	`0.3`	模型路由公式中成本权重

3.3 基础设施调优

变量	默认值	说明
`TIMEOUT`	`300`	HTTP 请求超时（秒）
`MAX_TURNS`	`50`	工具调用循环最大轮次
`DIALOGUE_EXPIRE_TIME`	`3600`	对话过期时间（秒）
`SLIDE_WINDOW_SIZE`	`5`	对话历史滑动窗口大小
`WORKSPACE_ROUTE`	`""`	工作空间根目录，默认 = cwd
`TOP_K`	`5`	RAG 检索返回结果数

3.4 嵌入模型

变量	默认值	说明
`EMBEDDING_MODEL`	`BAAI/bge-m3`	sentence-transformers 嵌入模型
`BASE_ROUTE`	`""`	本地模型/路由文件基础目录

3.5 RAG 调优

变量	默认值	说明
`RAG_DENSE_TOPK`	`20`	密集检索额外候选数
`RAG_DATA_TOPFILES`	`3`	data 模式下钻文件数
`RAG_DATA_TOPCHUNKS`	`5`	data 模式表面 chunk 数
`RAG_CHUNK_SIZE`	`800`	目标 chunk 大小（字符）
`RAG_RERANK_MIN_SCORE`	`0.0`	重排最低分阈值（0 = 全保留）
`RAG_REFINER_MAX_RETRIES`	`3`	Refiner JSON 解析重试预算
`RAG_FILE_WEIGHT`	`0.4`	data 模式文件级重排权重 α
`RAG_CHUNK_WEIGHT`	`0.6`	data 模式 chunk 级重排权重 β
`RAG_RRF_K`	`60`	Reciprocal Rank Fusion 常数
`RAG_CACHE_DIR`	`""`	RAG 缓存目录，空 = `<workspace>/.cache/rag`
`RAG_FEEDBACK_WEIGHT`	`0.0`	历史成功率在重排中的权重（0 = 关）
`RAG_ANN_MIN_N`	`64`	注册表达到此数量后构建 hnswlib ANN 索引
`RAG_MULTIQUERY_N`	`1`	本地 rewriter 查询变体联合数（1 = 单查询）

3.6 电路断路器 / LLM 并发控制

变量	默认值	说明
`CB_FAILURE_THRESHOLD`	`5`	断路器开启前的连续失败次数
`CB_RECOVERY_SECONDS`	`30.0`	断路器半开恢复等待时间（秒）
`LLM_MAX_RETRIES`	`3`	每次 LLM 调用的最大重试次数
`LLM_RETRY_BASE_DELAY`	`1.0`	重试初始退避延迟（秒）
`LLM_RETRY_MAX_DELAY`	`30.0`	重试最大退避延迟（秒）
`LLM_MAX_CONCURRENT_PER_URL`	`8`	每个 URL 最大并发 LLM 调用（AIMD 上限）
`LLM_MIN_CONCURRENT_PER_URL`	`1`	AIMD 收缩下限
`LLM_QUEUE_WAIT_S`	`120`	调用者等待 gate 许可的最大秒数
`LLM_AIMD_GROW_AFTER`	`20`	连续成功多少次后 AIMD 目标 +1
`LLM_AIMD_SHRINK_FACTOR`	`0.5`	超时时 AIMD 目标乘数（0.5 = 减半）
`LLM_GATE_DISABLED`	`false`	总开关：true = 并发 gate 失效（不限量）
`RESPONSES_API_ENABLED`	`""`	强制 Responses API 开/关（`true`/`false`），空 = 自动探测
`RESPONSES_API_PATH`	`""`	覆盖 Responses API 路径（如 `/v1/responses`）

3.7 用户偏好

变量	默认值	说明
`need_figure`	`true`	是否需要立绘
`need_audio`	`true`	是否需要语音
`need_video`	`true`	是否需要视频
`need_report`	`true`	是否需要报告
`intense_mode`	`true`	任务执行直到绝对成功
`turbo_mode`	`false`	跳过审批但保留计划验证和交互（与 intense_mode 互斥）

3.8 对话设置

变量	默认值	说明
`color`	`blue`	Agent 主题色（red/blue/green/cyan/grey/yellow）
`need_initiative`	`true`	对话是否需要主动发起
`security_level`	`medium`	审批阈值（high/medium/low）
`verify_plan`	`false`	执行前是否验证计划
`skill_auto_apply`	`false`	自动应用技能提议

3.9 每日监控

变量	默认值	说明
`DAILY_MONITOR_MAX_TASKS`	`8`	每 agent 最大并发监控任务
`DAILY_MONITOR_EMBEDDING_THRESHOLD`	`0.54`	嵌入余弦相似度阈值
`DAILY_MONITOR_KEYWORD_ENABLED`	`true`	启用关键词快速通道
`DAILY_MONITOR_MINI_CONFIRM_ENABLED`	`true`	启用小模型确认步骤
`DAILY_MONITOR_CLIENT_TIMEOUT`	`60.0`	浏览器/输入客户端调度超时（秒）
`DAILY_MONITOR_DISABLED`	`false`	完全禁用每日监控模块

3.10 外部服务 / 第三方

变量	默认值	说明
`HUGGING_FACE_API_KEY`	`""`	Hugging Face API 密钥
`DATAGEN_BASE_URL`	`""`	数据生成 API URL
`DATAGEN_API_KEY`	`""`	数据生成 API 密钥
`UPDATE_URL`	`""`	OTA 更新源 URL（electron-updater generic provider），空 = 禁用
`UPDATE_CHECK_INTERVAL_HOURS`	`24`	自动更新检查间隔（小时）

3.11 FAMILIARS_* 运行时标志

变量	说明
`FAMILIARS_DB_PATH`	SQLite 数据库路径。默认 `workspace/familiars.db`。测试用 `:memory:`
`FAMILIARS_HTTP_INSECURE`	`1` = 回退纯 HTTP + uvicorn（不走 HTTPS/HTTP2）
`FAMILIARS_MARKETPLACE_URL`	marketplace index.json 源地址
`FAMILIARS_TIER*_MAX_MB`	GPU 分级 VRAM 阈值（`TIER1` ~ `TIER4`）
`FAMILIARS_APPROVAL_DISABLED`	`1` = 关闭审批门（开发用，所有工具直接执行）
`FAMILIARS_FRAMEWORK_DOCS_TOPK`	manager 框架文档检索 top-K
`FAMILIARS_BROKER_ADVERTISE_URL`	broker 公网/LAN 地址（跨机器联邦）
`FAMILIARS_BROKER_BIND`	bridge 绑定地址。`0.0.0.0` 暴露跨机器；空 = `127.0.0.1`
`FAMILIARS_BROKER_DIRECT_TIMEOUT`	联邦直连投递超时（秒），默认 `10.0`

4. 前端环境搭建

4.1 Node.js 依赖

bash

cd electron
npm install

4.2 核心前端依赖

包	版本	用途
`vue`	`^3.5.41`	UI 框架
`pinia`	`^2.1.7`	状态管理
`@vue-flow/core`	`^1.48.2`	流程图编辑器
`@vue-flow/minimap` / `controls` / `background`	配套	流程图辅助组件
`@dagrejs/dagre`	`^3.0.0`	流程图自动布局
`axios`	`^1.7.0`	HTTP 客户端
`electron`	`^30.0.0`	桌面 shell
`electron-builder`	`^24.13.0`	打包（NSIS Windows / DMG macOS）
`electron-updater`	`^6.8.9`	OTA 自动更新
`markdown-it` + `katex` + `mermaid`	-	消息渲染（Markdown / LaTeX / 图表）
`onnxruntime-web`	`^1.26.0`	浏览器端 ONNX 推理
`@ricky0123/vad-web`	`^0.0.30`	浏览器端 VAD（语音活动检测）
`highlight.js`	`^11.11.1`	代码高亮
`jszip`	`^3.10.1`	zip 打包/解压
`d3`	`^7.9.0`	数据可视化

4.3 前端构建脚本

json

{
  "dev": "vite",
  "build": "vite build",
  "test": "vitest run",
  "electron:dev": "concurrently \"vite\" \"wait-on http://localhost:5173 && electron .\"",
  "electron:build": "vite build && electron-builder"
}

4.4 构建配置

appId: com.familiars.desktop
productName: Familiars
Windows: NSIS 安装器（非一键，可选安装路径，创建桌面/开始菜单快捷方式）
macOS: DMG
更新源: https://api.familiars.cn/_app-updates/（generic provider）
extraResources: cover.png（应用封面）

5. 启动开发

5.1 启动 bridge（后端）

bash

# 推荐方式：hypercorn + HTTPS/HTTP2 + 自签证书
.venv/Scripts/python -m src.bridge.run

# 回退方式：纯 HTTP + uvicorn（调试用）
FAMILIARS_HTTP_INSECURE=1 .venv/Scripts/python -m src.bridge.run

Bridge 监听 127.0.0.1:18711（默认）。若端口被占用，Electron 会自动 pickFreePort() 并写入 workspace/.bridge.port。

自签证书自动生成于 workspace/.bridge.crt。

5.2 启动 Electron 前端（开发模式）

bash

cd electron && npm run electron:dev

这会同时启动 Vite dev server（:5173）和 Electron 窗口，并自动 spawn bridge 进程。

5.3 CLI 驱动

bash

python main.py --help                    # 列出命令组
python main.py agents list --pretty      # 列出所有 agent
python main.py chat stream --prompt "你好" --agent-id 1   # SSE 流式对话

5.4 生产构建

bash

cd electron && npm run electron:build

输出在 electron/dist-electron/。

6. 测试约定（红线）

6.1 必须用真 SQLite

bash

FAMILIARS_DB_PATH=:memory: pytest -q

不要 mock 存储仓库。所有测试必须通过真实的 SQLite（内存或文件）运行。

6.2 Bridge 路由测试

恢复 sys.modules：bridge 路由在 import 时捕获模块状态，测试必须恢复。见 test/bridge/conftest.py。
禁止 importlib.reload：不要 reload 路由模块——import 时副作用（CUDA pin、路径对齐）无法安全重放。

6.3 Scratch agent 目录

临时 agent 目录放 runs/，不要放 workspace/agents/。bridge 启动会扫描 workspace/agents/ 并真实创建 agent。

6.4 浏览器自动化

走 src/utils/browser_tools.py:familiars_cdp_port() —— 单一共享 Chrome 实例（bridge + Playwright + 透视渲染共用）。

6.5 新增日志须入 `KNOWN_LOGS`

src/utils/framework_tools.py 的 KNOWN_LOGS 列表控制 manager 能看到哪些日志。新增日志文件必须在此注册。

7. .env 模板

bash

# ---- LLM 必填 ----
BASE_URL=https://api.openai.com/v1
API_KEY=sk-your-key-here
DEFAULT_MODEL=gpt-4o

# ---- LLM 可选 ----
MANAGER_MODEL=gpt-4o
MINI_MODEL=Qwen2.5-1.5B
FAST_MODEL=

# ---- 嵌入 / RAG ----
EMBEDDING_MODEL=BAAI/bge-m3
RAG_DENSE_TOPK=20
RAG_CHUNK_SIZE=800

# ---- 对话调优 ----
MAX_TURNS=50
TIMEOUT=300
DIALOGUE_EXPIRE_TIME=3600
SLIDE_WINDOW_SIZE=5

# ---- 运行时标志 ----
# FAMILIARS_DB_PATH=workspace/familiars.db
# FAMILIARS_HTTP_INSECURE=0
# FAMILIARS_APPROVAL_DISABLED=0
# FAMILIARS_MARKETPLACE_URL=https://api.familiars.cn/marketplace

# ---- Broker 联邦 ----
# FAMILIARS_BROKER_ADVERTISE_URL=
# FAMILIARS_BROKER_BIND=127.0.0.1

# ---- 用户偏好 ----
color=blue
intense_mode=true
security_level=medium

# ---- 每日监控 ----
DAILY_MONITOR_MAX_TASKS=8
DAILY_MONITOR_EMBEDDING_THRESHOLD=0.54

# ---- 电路断路器 ----
CB_FAILURE_THRESHOLD=5
LLM_MAX_RETRIES=3
LLM_MAX_CONCURRENT_PER_URL=8

环境搭建与开发约定 ​

1. 仓库目录布局 ​

2. 后端环境搭建 ​

2.1 创建虚拟环境 ​

2.2 安装依赖 ​

2.3 核心依赖一览 ​

3. 环境变量配置 ​

3.1 必填变量 ​

3.2 LLM 配置 ​

3.3 基础设施调优 ​

3.4 嵌入模型 ​

3.5 RAG 调优 ​

3.6 电路断路器 / LLM 并发控制 ​

3.7 用户偏好 ​

3.8 对话设置 ​

3.9 每日监控 ​

3.10 外部服务 / 第三方 ​

3.11 FAMILIARS_* 运行时标志 ​

4. 前端环境搭建 ​

4.1 Node.js 依赖 ​

4.2 核心前端依赖 ​

4.3 前端构建脚本 ​

4.4 构建配置 ​

5. 启动开发 ​

5.1 启动 bridge（后端） ​

5.2 启动 Electron 前端（开发模式） ​

5.3 CLI 驱动 ​

5.4 生产构建 ​

6. 测试约定（红线） ​

6.1 必须用真 SQLite ​

6.2 Bridge 路由测试 ​

6.3 Scratch agent 目录 ​

6.4 浏览器自动化 ​

6.5 新增日志须入 KNOWN_LOGS ​

7. .env 模板 ​

8. 下一步 ​

环境搭建与开发约定

1. 仓库目录布局

2. 后端环境搭建

2.1 创建虚拟环境

2.2 安装依赖

2.3 核心依赖一览

3. 环境变量配置

3.1 必填变量

3.2 LLM 配置

3.3 基础设施调优

3.4 嵌入模型

3.5 RAG 调优

3.6 电路断路器 / LLM 并发控制

3.7 用户偏好

3.8 对话设置

3.9 每日监控

3.10 外部服务 / 第三方

3.11 FAMILIARS_* 运行时标志

4. 前端环境搭建

4.1 Node.js 依赖

4.2 核心前端依赖

4.3 前端构建脚本

4.4 构建配置

5. 启动开发

5.1 启动 bridge（后端）

5.2 启动 Electron 前端（开发模式）

5.3 CLI 驱动

5.4 生产构建

6. 测试约定（红线）

6.1 必须用真 SQLite

6.2 Bridge 路由测试

6.3 Scratch agent 目录

6.4 浏览器自动化

6.5 新增日志须入 `KNOWN_LOGS`

7. .env 模板

8. 下一步