环境搭建与开发约定

开发 Familiars 源码需要了解的工作区布局、环境变量、测试约定。来源：CLAUDE.md 提取 + 实测。

---

工作区布局（顶层）

路径	内容
src/	Python 后端（bridge/==FastAPI，models/==Agent，tools/+utils/==工具系统，base/==配置/GPU/加密，storage/==SQLite，broker/==交换所）
electron/	Electron 前端（renderer/==Vue3+Vite，electron/main.js==主进程）
workspace/	运行时数据（familiars.db、SECRET.json、agents/、marketplace_host/、manager/）
test/	全量测试（pytest，含 bridge/decider/broker/acceptance）
deploy/relay/app/	Broker 中继 relay 的独立部署（docker + Caddy）
docs/、website/	站点与文档

环境变量（开启功能/覆盖默认）

变量	默认 / 说明
BASE_URL / API_KEY / DEFAULT_MODEL / MANAGER_MODEL	OpenAI 兼容 LLM 端点（必需）
EMBEDDING_MODEL	BAAI/bge-m3
RERANKER_MODEL	BAAI/bge-reranker-v2-m3
MAX_TURNS / TIMEOUT / DIALOGUE_EXPIRE_TIME / SLIDE_WINDOW_SIZE	对话调参（50/300/3600/5）
FAMILIARS_DB_PATH	DB 路径（测试用 :memory: 或按租户隔离）
FAMILIARS_HTTP_INSECURE	1 = 回退纯 HTTP + uvicorn
FAMILIARS_MARKETPLACE_URL	市场 index 源
FAMILIARS_TIER*_MAX_MB	GPU 分级阈值
FAMILIARS_APPROVAL_DISABLED	1 = 关闭审批门（开发用）

常用命令

# 后端测试（须真 SQLite，别 mock 仓库）
FAMILIARS_DB_PATH=:memory: pytest -q

# 启动 bridge（hypercorn + HTTP/2, 127.0.0.1:18711）
.venv/Scripts/python -m src.bridge.run

# CLI 驱动
python main.py --help
python main.py agents list --pretty
python main.py broker install --url https://example.com/x.broker.zip --sha256 <64hex> --pubkey <base64>

# 前端 dev/build
cd electron && npm run electron:dev / electron:build

测试约定（红线）

1. 必须真 SQLite：FAMILIARS_DB_PATH=:memory:，不要 mock 仓库。
2. Bridge-route 测试：恢复 import 时捕获的 sys.modules；不要 importlib.reload 路由模块。见 test/bridge/conftest.py。
3. Scratch agent 目录：回 runs/，别放 workspace/agents/（bridge 启动会扫描并真实新建 agent）。
4. 浏览器自动化：走 src/utils/browser_tools.py:familiars_cdp_port() —— 单一共享 Chrome 实例。

---

下一步

• 全量 CLI：[CLI.md](./cli.md)
• 所有端点：[Bridge REST API](./api-bridge.md)
• 内部机制与红线：[内部开发指南](./internals.md)