常见问题 FAQ

安装 / 使用 / 模型 / 网络 / 隐私 / GPU / 生态相关速答。按需搜索。

一、安装与启动

Q1. 应该装哪个平台？

Windows 11/10 优先。Familiars 是 Windows-first 应用，所有功能完整支持。

macOS 部分功能可用但不完整：

功能	macOS 状态
设备指纹 (`src/base/auth/device.py`)	macOS 有真实实现（Keychain）；Windows 仅 hostname 指纹
开机自启 (`src/utils/autorun.py`)	有 macOS 分支（launchd）
日常工具 (`src/utils/daily_tools.py`)	macOS 通过 `AppKit` / `Quartz` 条件导入
WeChat 监听 (`wcferry`)	仅 Windows（wcferry 只提供 Win32 FWWeChat 后端）
UI 自动化 (`uiautomation`)	仅 Windows（UIA 无障碍桥）
音频控制 (`pycaw`)	仅 Windows

Q2. `pip install -r requirements.txt` 报错怎么办？

常见错误与解决：

错误	原因	解决
`Could not find torch==2.9.0+cu126`	没加 PyTorch 索引	`pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126`
`AttributeError: _ARRAY_API not found`	`onnxruntime` 版本过低（<1.28）与 NumPy 2.x 不兼容	确保 `onnxruntime==1.28.0`（requirements.txt 已修正）
`lunardate` 找不到	农历库未装	`pip install lunardate==0.3.0`
`pydantic_settings` 找不到	未装	`pip install pydantic-settings>=2.5.0`
`python-dotenv` 找不到	未装	`pip install python-dotenv>=1.0.0`
`uiautomation` 安装失败（macOS）	macOS 没有 wheel	`requirements.txt` 已用 `sys_platform == "win32"` 限定，macOS 不应尝试安装
编译失败（`hnswlib` / `insightface`）	缺少 VC++ 编译工具	安装 Visual C++ Redistributable 2015–2022 或 Build Tools
下载极慢	PyPI 源慢	加国内镜像：`-i https://pypi.tuna.tsinghua.edu.cn/simple`（PyTorch 索引地址不变）

Q3. 启动后连不上 bridge / 一直转圈？

按以下顺序排查：

检查端口文件：查看 workspace/.bridge.port。如果 18711 被占，bridge 自动选新端口写入该文件。CLI 自动读取。
检查 .env：BASE_URL / API_KEY / DEFAULT_MODEL 是否填写。启动时报 Missing required environment variable(s) 说明漏了必填项。
检查 bridge 日志：查看 workspace/.bridge.log，搜索 ERROR / CRITICAL。
检查 GPU 探测：查看 workspace/gpu_tier.json，确认 GPU 等级识别正确。
尝试 HTTP 回退：设置 FAMILIARS_HTTP_INSECURE=1，bridge 回退到 HTTP + uvicorn（不走 HTTPS/2 + hypercorn）。
检查双实例：workspace/.bridges.json 是否有多个实例。Electron 有 single-instance lock（app.requestSingleInstanceLock()），第二次启动应自动聚焦已有窗口。如果有僵尸进程，手动 kill 后重启。
检查代理：如果系统配了死代理（如 v2ray/SS 没启动），httpx 会报 ConnectError [WinError 10061]。config.py 的 _inject_no_proxy() 会自动将 *_BASE_URL 的主机加入 NO_PROXY，但也可手动检查。

Q4. 为什么不能用 `uvicorn src.bridge.app:app --reload`？

三个致命问题：

丢失 HTTP/2：uvicorn 不支持 HTTP/2。Familiars 依赖 hypercorn 的 HTTP/2 多路复用来绕过 Chromium 的 6-socket-per-host HTTP/1.1 限制（旧版 uvicorn 在快速切换 agent 时会导致渲染器阻塞）。
CUDA race condition：--reload 在 worker 线程上初始化 CUDA，Windows WDDM 不能容忍首次 CUDA touch 来自非主线程，直接崩溃（0xC0000005）。
预热丢失：app.py 的 on_event("startup") 执行精确的启动顺序（CUDA pin → broker bootstrap → pool watchdog → browser hooks → prewarm → autorun → rehydrate）。reload 会重复执行这些初始化，导致状态混乱。

正确入口：python -m src.bridge.run（hypercorn + HTTPS/2 + 自签证书）。

Q5. 端口 18711 被占用怎么办？

Bridge 的端口解析优先级：

探测 18711 是否空闲：isPortFree(18711) 检测
空闲 → 使用 18711（默认）
被占 → pickFreePort() 向 OS 申请空闲端口
写端口到 workspace/.bridge.port + workspace/.bridges.json
CLI 自动读取 .bridge.port（或 .bridges.json + psutil PID 存活检查）

常见占用场景：

上次 bridge 未正常退出，端口未释放
其他程序占用了 18711
双 Electron 实例竞争

解决：

等 30 秒让 OS 回收端口
手动 kill 占用进程（netstat -ano | findstr :18711）
或直接用动态端口（CLI 自动适配）

Q6. 双 bridge 实例冲突怎么办？

Familiars 有多重防护：

Electron single-instance lock：app.requestSingleInstanceLock()，第二次启动触发 second-instance 事件，第一个实例自动聚焦窗口，第二个立即 app.quit()。
Bridge 端口健康检查：_port_healthy() 在绑定前检测端口是否已被占用。
_inspectExistingBridge()：Electron 在 glom 到已有 bridge 前，交叉检查 PID 存活 + 窗口响应状态 + age。僵尸 bridge（anyio 线程池死锁但 hypercorn TLS 还在答 /health）会被 kill + respawn。
app.py 豁免已注册 sibling：bridge 启动时检测是否已有同 token 的实例运行。

如果仍然冲突：

bash

# 查看当前 bridge 实例
cat workspace/.bridges.json

# 手动 kill 僵尸进程
taskkill /PID <pid> /F

# 清理端口文件
del workspace/.bridge.port
del workspace/.bridges.json

# 重启
python -m src.bridge.run

Q7. 首次启动很慢（1-2 分钟）正常吗？

正常。Bridge 启动时的预热序列：

CUDA pin（主线程，~50ms）
Broker workshop bootstrap
AnyIO thread limiter bump
Pool saturation watchdog
Browser lifecycle hooks
Embedder 预热（bge-m3，首次需下载 ~400MB）
rembg 预热（背景去除模型）
rewriter 预热（查询改写模型）
最近 agent 的数字人模型预热（GPT-SoVITS）
Autorun install/drift check
Monitor rehydrate
Cron job rehydrate
Skill scheduler rehydrate

首次启动最慢的是 embedder 下载。后续启动有 workspace/gpu_tier.json 缓存，跳过 nvidia-smi 探测。

二、使用

Q8. 对话没有记忆？

排查步骤：

检查 embedder 是否已下载：首次启动需下载 bge-m3（~400MB）。查看 workspace/.bridge.log 搜索 bge-m3。
检查 EMBEDDING_MODEL：.env 中是否正确配置（默认 BAAI/bge-m3）。
检查对话是否过期：DIALOGUE_EXPIRE_TIME 默认 3600 秒（1 小时）。过期对话的内存会被释放。
检查 RAG 参数：
- RAG_DENSE_TOPK（默认 20）— 稠密召回候选数
- RAG_RERANK_MIN_SCORE（默认 0.0）— 重排最低分阈值
- RAG_CHUNK_SIZE（默认 800）— 分块大小
记忆需要先写入：RAG 命中需要"过去写过/说过"——先让 agent 读点东西（「读一下 USER.md」），再问「我记得…」
检查 GPU tier：mode0（无 GPU）下，memorizer 使用云端 LLM 2-call hack，可能较慢或不稳定。

Q9. 工具一直要审批？

默认隐私保护行为。审批阈值由 security_level 控制：

级别	行为
`high`	所有工具都需审批
`medium`（默认）	中高风险工具需审批
`low`	仅高风险工具需审批

临时关闭（仅限开发/内部环境）：

bash

FAMILIARS_APPROVAL_DISABLED=1 python -m src.bridge.run

永久调整：在 .env 中设置 security_level=low，或在 SettingsCenter → 隐私 tab 中调整。

Q10. 每次回答很长 / 看不到工具调用？

可能原因：

模型不支持工具调用：DEFAULT_MODEL 必须是 agentic 模型（支持 function calling / tool use）。换用 gpt-4o / claude-3 / qwen-max 等。
MAX_TURNS 过大：默认 50 轮。如果模型一直在工具调用循环中，可以降低（如 MAX_TURNS=20）。
intense_mode 开启：默认 True，agent 会持续执行直到"绝对成功"。如果不需要，在 .env 中设置 intense_mode=False。
turbo_mode 冲突：turbo_mode 和 intense_mode 互斥。turbo_mode=True 跳过审批但保留计划验证。
Turn budget escalation：MAX_TURNS 不再是硬上限——耗尽时 ConversationSession 会问 _turn_budget_escalator（manager LLM）是否延长。如果不希望延长，降低 MAX_TURNS。

Q11. 数字人不说话？

数字人需要：

本地 GPU：至少 tier4（4GB+ VRAM）
GPT-SoVITS 模型：语音合成模型需提前下载到 workspace/ 目录
need_figure=True：.env 中 AssistantConfig.need_figure 默认为 True
need_audio=True：.env 中 AssistantConfig.need_audio 默认为 True

无 GPU 时（mode0），数字人面板显示机器人吉祥物 emoji 而非动画头像。

详见数字人章节。

Q12. 语音输入不工作？

语音输入依赖：

faster-whisper：ASR 引擎（requirements.txt 已包含）
麦克风权限：Windows 设置 → 隐私 → 麦克风 → 允许桌面应用访问
@ricky0123/vad-web：语音活动检测（VAD），在浏览器端运行

调试：

检查浏览器控制台是否有麦克风权限错误
检查 faster-whisper 模型是否已下载
尝试手动 push-to-talk（按住说话，松开识别）

Q13. 窗口关闭后找不回来了？

关闭窗口后，Electron 隐藏到系统托盘（不退出）：

找到托盘图标：Windows 右下角系统托盘（可能需要点击 ^ 展开隐藏图标）
右键 → "恢复窗口"
或 左键单击 托盘图标

首次隐藏提示：首次关闭窗口时会显示系统通知，指引你从托盘恢复。标记文件：%APPDATA%/familiars/.tray-hint-shown。

彻底退出：右键托盘 → "退出后台 (彻底关闭)"。

三、模型配置

Q14. 可以用私有化 embedding 吗？

可以。EMBEDDING_MODEL / RERANKER_MODEL 支持：

HuggingFace 模型名：BAAI/bge-m3（默认）
本地路径：/path/to/local/model
OpenAI 兼容端点：通过 BASE_URL 统一配置

修改 .env 后需重启 bridge。

Q15. 本地小模型（decider / rewriter / memorizer）怎么训练？

由训练管线在仓库 training/ 下管理，日常使用无需关心：

rewriter：查询改写（workspace/rewriter/prompt.md 定义提示词）
decider：主动决策（src/base/gpu_tier.py 控制加载策略）
memorizer：记忆写入（QLoRA 微调）

这些模型在 bridge 启动时自动加载（GPU tier 允许的情况下），不需要手动训练。

详见架构·主动决策 Decider。

Q16. `MANAGER_MODEL` 和 `DEFAULT_MODEL` 有什么区别？

变量	用途	推荐
`DEFAULT_MODEL`	所有 agent 的默认对话模型	性价比高的模型（如 `gpt-4o-mini` / `qwen-plus`）
`MANAGER_MODEL`	管理者（agent 0/1）专用	更强的模型（如 `gpt-4o` / `claude-3-opus`）
`MINI_MODEL`	本地轻量模型	默认 `Qwen2.5-1.5B`（decider 等）
`FAST_MODEL`	低延迟快速模型	空（回退到 `DEFAULT_MODEL`）

Manager 负责高管摘要、persona 进化、框架文档索引、跨 agent 路由，需要更强的推理能力。

Q17. `FAST_MODEL` 什么时候用到？

FAST_MODEL 用于延迟敏感的场景：

草稿解析（DraftConfirmModal）
快速分类
轻量级查询改写

为空时回退到 DEFAULT_MODEL。如果你的 DEFAULT_MODEL 较慢（如 gpt-4o），可以设置 FAST_MODEL=gpt-4o-mini 来加速轻量任务。

四、网络与连接

Q18. `ConnectError [WinError 10061]` 连接被拒？

常见原因：

系统代理问题：配了死代理（v2ray/SS 没启动）。config.py 的 _inject_no_proxy() 会自动将 *_BASE_URL 的主机加入 NO_PROXY，但也可手动检查。
Bridge 未启动：检查 workspace/.bridge.port，确认 bridge 进程存活。
端口不匹配：CLI 的 --base-url 与 bridge 实际端口不一致。
TLS 证书不信任：workspace/.bridge.crt 自签证书未被信任。CLI 自动 pin 该证书；浏览器需手动信任一次。

Q19. HTTP/2 vs HTTP 回退？

Familiars 默认使用 HTTPS + HTTP/2（hypercorn）：

优势：HTTP/2 多路复用绕过 Chromium 的 6-socket-per-host 限制（快速切换 agent 时不会阻塞渲染器）
证书：workspace/.bridge.crt 自签证书，Electron 自动信任
CLI：自动 pin 该证书（session.verify = str(crt)）

回退到 HTTP（不推荐，除非 hypercorn 或证书信任出问题）：

bash

FAMILIARS_HTTP_INSECURE=1 python -m src.bridge.run

回退后使用 uvicorn + HTTP/1.1。Electron 的 main.js 和 CLI 都读 FAMILIARS_HTTP_INSECURE 保持协议对齐。

Q20. CLI 报 401 Unauthorized？

X-Bridge-Token 缺失或错误。

排查：

检查 workspace/.bridge_token 是否存在
检查 bridge 是否已启动（token 在 bridge 启动时生成）
手动指定 token：python main.py --token <token> agents list
或设置环境变量：BRIDGE_TOKEN=<token>

Q21. SSE 流式响应中断？

可能原因：

网络超时：TIMEOUT 默认 300 秒。长任务可能超时。
代理断开：系统代理或防火墙切断长连接。
Bridge 重启：bridge 重启后所有 SSE 流断开。
Chromium socket 限制：HTTP/1.1 下 6-socket 限制。使用 HTTP/2 可避免。

五、隐私与安全

Q22. 我的对话会上传吗？

默认所有记忆/对话/数据库在本地：

SQLite 数据库：workspace/familiars.db
对话树：workspace/agents/agent_<id>/dialogue_<n>/
记忆：workspace/agents/agent_<id>/ + workspace/USER.md
敏感信息：workspace/SECRET.json（加密存储）
Bridge：127.0.0.1:18711（仅本机访问）

会出网的请求：

LLM 推理（BASE_URL 配置的端点）
Embedding 模型下载（HuggingFace，首次）
搜索工具（ddgs / tavily）
市场索引（FAMILIARS_MARKETPLACE_URL）
OTA 更新检查（UPDATE_URL）

详见安全模型。

Q23. 审批卡上显示"敏感信息"？

sensitive_detector 做三级脱敏：

gitleaks：正则匹配密钥/token/密码模式
Presidio：NER 识别个人信息（姓名/邮箱/电话/地址）
mini-LLM：轻量模型判断上下文敏感性

命中的敏感内容只以密文进 SECRET.json（crypto.encrypt_value，HKDF info = b"familiars-secrets-v1"）。

这是功能不是 bug——防止敏感信息在对话记录中明文存储。

Q24. HKDF info 字符串能改吗？

src/base/crypto.py 的 HKDF info 为 b"familiars-secrets-v1"。

⚠️ 修改它会作废所有已写入 SECRET.json 的密钥，因为解密时 info 必须匹配。如果必须改，需要同步实现 re-encryption migration（解密旧 → 用新 info 加密 → 写回）。

六、GPU 与性能

Q25. GPU tier 探测不准怎么办？

强制覆盖：

bash

# 强制指定 tier
FAMILIARS_GPU_TIER=tier6 python -m src.bridge.run

# 强制重新探测（忽略缓存）
FAMILIARS_GPU_TIER_FORCE_REDETECT=1 python -m src.bridge.run

调整阈值：

bash

# 调整 tier4 上界（MiB）
FAMILIARS_TIER4_MAX_MB=6000

# 调整 tier6 上界（MiB）
FAMILIARS_TIER6_MAX_MB=8000

缓存位置：workspace/gpu_tier.json（可手动删除后重启）。

运行时降级：VRAM pressure watchdog 可在运行时降级 tier（set_transient_tier），内存有效，不写磁盘。恢复后自动清除（clear_transient_tier）。

Q26. 显存不够（OOM）怎么办？

降级 GPU tier：FAMILIARS_GPU_TIER=tier4（或 tier6）
关闭不需要的功能：
- need_figure=False — 关闭数字人
- need_video=False — 关闭视频处理
- DAILY_MONITOR_DISABLED=True — 关闭日常监控
减少并发模型：tier4 下模型顺序加载（rewriter 用完驱逐再加载 reranker）
使用 API-only 模式：FAMILIARS_GPU_TIER=mode0（所有本地模型回退到云端）

Q27. Apple Silicon (MPS) 支持如何？

Apple Silicon 没有 nvidia-smi，默认解析为 mode0（API-only）。

强制启用本地推理（实验性）：

bash

FAMILIARS_GPU_TIER=tier4 python -m src.bridge.run

MPS 后端通过 PyTorch CPU 索引的 +cpu wheel 暴露（MPS 是同一 build）。但性能和稳定性不如 NVIDIA CUDA，部分操作（如 insightface）可能不支持 MPS。

推荐：Apple Silicon 用户使用 API-only 模式，依赖云端模型。

七、生态（Broker / Recipe / Flow）

Q28. 什么是 Broker / Recipe / Flow？

概念	说明	教程
Recipe	单一技能的自动化"配方"（图：输入→处理→输出）	Recipe 教程
Flow	跨 agent 的多阶段工作流（含并行/分支/子轨道）	Flow 教程
Broker	可分享的应用包（manifest+UI+插件），可在市场安装	Broker 教程

Q29. 市场里的 Broker 安全吗？

市场提交需：

Ed25519 签名（作者密钥：~/.familiars/authors/<name>.key）
sha256 校验（文件树哈希）
发布即审核（人工队列）

⚠️ 当前 Broker 仍在 bridge 进程内运行（无沙箱），仅建议安装可信作者的作品。

安装命令：

bash

python main.py broker install --file my_broker.broker.zip
# 或从 URL
python main.py broker install --url https://example.com/my_broker.broker.zip

详见 Broker 教程与安全模型。

Q30. 我可以把 agent 数据迁移到另一台机器吗？

可以。把 workspace/ 整目录拷贝即可。

路径漂移自动对齐：src.base.paths_align.align_all_paths() 在 bridge 启动时（src/bridge/app.py，CUDA pin 之后、route import 之前）自动执行：

Repo-root drift：比较每个 dialogue.path 前缀与 _repo_root()。移动仓库后，下次启动透明重写每个 dialogue.json + turn_*/plan.json + step_*.json。
External-directory aliases：对于仓库外的重命名（如数据文件夹），运行 python -m src.tools.paths_migrate <old> <new> --record 一次，之后每次启动重放。

检测到的路径对追加到 workspace/.paths_aliases.json（审计用）。

自动对齐是幂等的（0-hit 文件跳过），稳定启动时无成本。

日志文件（.bridge.log、audit.log）永远不触碰——它们是真实历史记录。

八、开发调试

Q31. 如何查看 bridge 日志？

日志文件：

文件	内容
`workspace/.bridge.log`	Bridge 主日志（INFO/WARNING/ERROR）
`workspace/audit.log`	审计日志（工具调用、审批、敏感信息检测）
`workspace/.bridge.watchdog.log`	看门狗日志
`workspace/memorizer_audit.jsonl`	记忆审计（JSONL）
`workspace/reminders/*.jsonl`	提醒日志
`workspace/agents/agent_<id>/daily_*.jsonl`	Agent 每日日志

Manager 工具：Manager（agent 0）有 list_logs / read_log 工具，可直接在对话中浏览日志。

CLI 查看：

bash

# 实时跟踪
tail -f workspace/.bridge.log

# 搜索错误
grep ERROR workspace/.bridge.log

Q32. 如何调试前端？

DevTools：Ctrl+Shift+I 或 F12 打开
Vite HMR：npm run electron:dev 支持热模块替换，修改 Vue 组件自动刷新
Vue DevTools：安装浏览器扩展
网络面板：检查 /api/* 请求状态
Console：搜索 [error] / [warn]

Q33. 如何调试后端？

日志级别：设置 LOG_LEVEL=DEBUG（或 INFO / WARNING / ERROR）
断点调试：python -m debugpy --listen 5678 -m src.bridge.run

测试：

bash

# 运行所有测试
pytest

# 运行特定测试
pytest test/bridge/test_app.py -v

# 运行 recipe 测试
pytest test/recipes/ -v

内存测试：使用 FAMILIARS_DB_PATH=:memory: 避免磁盘副作用

Q34. 如何添加新的 bridge 路由？

在 src/bridge/routes/ 下创建新文件（如 my_route.py）
定义 router = APIRouter(prefix="/api/my-route", tags=["my-route"])
在 src/bridge/app.py 中 import 并 mount
更新 src/models/RAG/bridge_api_surface.py（manager API 表面索引）
如果需要 CLI 支持，在 main.py 中添加命令组

Q35. 如何添加新的工具？

在 src/tools/ 或 src/utils/ 下实现工具类
在 src/tools/tool_dispatcher.py 中注册实例
更新 workspace/tools.json（schema）
如果需要特定 client 可见，更新 src/models/clients/*_client.py

九、其他

Q36. 如何更新 Familiars？

源码安装：

bash

git pull
pip install -r requirements.txt --index-url https://download.pytorch.org/whl/cu126
cd electron && npm install

一键安装：

electron-updater 自动检查更新（UPDATE_URL 配置 feed URL）
检查间隔：UPDATE_CHECK_INTERVAL_HOURS（默认 24 小时）
手动检查：设置中心 → 关于 → 检查更新

Q37. 数据库结构在哪里？

SQLite 数据库：workspace/familiars.db（src/storage/db.py:get_default_db_path）

覆盖路径：FAMILIARS_DB_PATH（测试可用 :memory:）

迁移：src/storage/migrations/ 下 v1 … v19（含 .sql 和 .py 变体）。v16 是 Python migration（v16__schedule_dedup_and_unique.py）。v18（broker）和 v19（broker_workshop）为交换所层。

Q38. 配置文件（`.env`）的优先级？

src/base/config.py 的 load_dotenv(override=True) 使 .env 文件覆盖已存在的环境变量。

优先级（从高到低）：

.env 文件（override=True）
进程环境变量（export FOO=bar）
默认值（Field(default=...)）

这意味着如果 shell export 了旧值，.env 中的新值会覆盖它。

Q39. `WORKSPACE_ROUTE` 是什么？

WORKSPACE_ROUTE 是 workspace/ 目录的父目录（通常是仓库根目录）。

默认：""（空 → 回退到 cwd）
Electron：自动设置为仓库根
Bridge：src/bridge/app.py 中 WORKSPACE_ROUTE pin 在 import 时

不要将 WORKSPACE_ROUTE 设置为 workspace/ 本身——它是 workspace/ 的父目录。

Q40. 没找到答案？

查看用户手册
查看架构文档
查看 CLI 参考
去反馈页提交提问或加入社群

常见问题 FAQ ​

一、安装与启动 ​

Q1. 应该装哪个平台？ ​

Q2. pip install -r requirements.txt 报错怎么办？ ​

Q3. 启动后连不上 bridge / 一直转圈？ ​

Q4. 为什么不能用 uvicorn src.bridge.app:app --reload？ ​

Q5. 端口 18711 被占用怎么办？ ​

Q6. 双 bridge 实例冲突怎么办？ ​

Q7. 首次启动很慢（1-2 分钟）正常吗？ ​

二、使用 ​

Q8. 对话没有记忆？ ​

Q9. 工具一直要审批？ ​

Q10. 每次回答很长 / 看不到工具调用？ ​

Q11. 数字人不说话？ ​

Q12. 语音输入不工作？ ​

Q13. 窗口关闭后找不回来了？ ​

三、模型配置 ​

Q14. 可以用私有化 embedding 吗？ ​

Q15. 本地小模型（decider / rewriter / memorizer）怎么训练？ ​

Q16. MANAGER_MODEL 和 DEFAULT_MODEL 有什么区别？ ​

Q17. FAST_MODEL 什么时候用到？ ​

四、网络与连接 ​

Q18. ConnectError [WinError 10061] 连接被拒？ ​

Q19. HTTP/2 vs HTTP 回退？ ​

Q20. CLI 报 401 Unauthorized？ ​

Q21. SSE 流式响应中断？ ​

五、隐私与安全 ​

Q22. 我的对话会上传吗？ ​

Q23. 审批卡上显示"敏感信息"？ ​

Q24. HKDF info 字符串能改吗？ ​

六、GPU 与性能 ​

Q25. GPU tier 探测不准怎么办？ ​

Q26. 显存不够（OOM）怎么办？ ​

Q27. Apple Silicon (MPS) 支持如何？ ​

七、生态（Broker / Recipe / Flow） ​

Q28. 什么是 Broker / Recipe / Flow？ ​

Q29. 市场里的 Broker 安全吗？ ​

Q30. 我可以把 agent 数据迁移到另一台机器吗？ ​

八、开发调试 ​

Q31. 如何查看 bridge 日志？ ​

Q32. 如何调试前端？ ​

Q33. 如何调试后端？ ​

Q34. 如何添加新的 bridge 路由？ ​

Q35. 如何添加新的工具？ ​

九、其他 ​

Q36. 如何更新 Familiars？ ​

Q37. 数据库结构在哪里？ ​

Q38. 配置文件（.env）的优先级？ ​

Q39. WORKSPACE_ROUTE 是什么？ ​

Q40. 没找到答案？ ​

常见问题 FAQ

一、安装与启动

Q1. 应该装哪个平台？

Q2. `pip install -r requirements.txt` 报错怎么办？

Q3. 启动后连不上 bridge / 一直转圈？

Q4. 为什么不能用 `uvicorn src.bridge.app:app --reload`？

Q5. 端口 18711 被占用怎么办？

Q6. 双 bridge 实例冲突怎么办？

Q7. 首次启动很慢（1-2 分钟）正常吗？

二、使用

Q8. 对话没有记忆？

Q9. 工具一直要审批？

Q10. 每次回答很长 / 看不到工具调用？

Q11. 数字人不说话？

Q12. 语音输入不工作？

Q13. 窗口关闭后找不回来了？

三、模型配置

Q14. 可以用私有化 embedding 吗？

Q15. 本地小模型（decider / rewriter / memorizer）怎么训练？

Q16. `MANAGER_MODEL` 和 `DEFAULT_MODEL` 有什么区别？

Q17. `FAST_MODEL` 什么时候用到？

四、网络与连接

Q18. `ConnectError [WinError 10061]` 连接被拒？

Q19. HTTP/2 vs HTTP 回退？

Q20. CLI 报 401 Unauthorized？

Q21. SSE 流式响应中断？

五、隐私与安全

Q22. 我的对话会上传吗？

Q23. 审批卡上显示"敏感信息"？

Q24. HKDF info 字符串能改吗？

六、GPU 与性能

Q25. GPU tier 探测不准怎么办？

Q26. 显存不够（OOM）怎么办？

Q27. Apple Silicon (MPS) 支持如何？

七、生态（Broker / Recipe / Flow）

Q28. 什么是 Broker / Recipe / Flow？

Q29. 市场里的 Broker 安全吗？

Q30. 我可以把 agent 数据迁移到另一台机器吗？

八、开发调试

Q31. 如何查看 bridge 日志？

Q32. 如何调试前端？

Q33. 如何调试后端？

Q34. 如何添加新的 bridge 路由？

Q35. 如何添加新的工具？

九、其他

Q36. 如何更新 Familiars？

Q37. 数据库结构在哪里？

Q38. 配置文件（`.env`）的优先级？

Q39. `WORKSPACE_ROUTE` 是什么？

Q40. 没找到答案？