常见问题 FAQ

安装 / 使用 / 模型 / 隐私相关速答。按需搜索。

---

安装与启动

Q1. 装哪个平台？ Windows 11/10 优先；macOS 部分功能（设备指纹、自启动）可用但不完整，详见 安装·macOS。

Q2. pip install -r requirements.txt 报错怎么办？ 先换国内镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple；若某包需编译，先装 build-essential 或对应的 VC++ Redistributable。

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

• 看 workspace/.bridge.port 里是不是非 18711 端口（被占用自动换端口）；
• .env 检查 BASE_URL/API_KEY；
• 试 FAMILIARS_HTTP_INSECURE=1 走 HTTP 回退。

Q4. 为什么不用 uvicorn src.bridge.app:app --reload？ 会丢 HTTP/2，且 reload 会在 worker 线程 race 初始化 CUDA —— Windows WDDM 上直接崩溃。请用 python -m src.bridge.run。

使用

Q5. 对话没有记忆？

• 确认 .env 的 EMBEDDING_MODEL 已下载（首次会拉 bge-m3）；
• RAG 命中需要"过去写过/说过"——先让它读点东西，再问"我记得…"。

Q6. 工具一直要审批？ 默认隐私保护。需要时在审批卡点允许；或开发/内部环境用 FAMILIARS_APPROVAL_DISABLED=1（慎用）。

Q7. 每次答得很长/看不到工具调用？ 建议检查模型是否为 agentic 型（支持工具调用）：DEFAULT_MODEL 换更强模型，或调 MAX_TURNS。

Q8. 数字人不说话？ 本地无 GPU 或缺少 GPT-SoVITS 语音模型。数字人属高级功能，见 数字人章节。

模型

Q9. 可以用私有化 embedding 吗？ 可以。EMBEDDING_MODEL / RERANKER_MODEL 可指向任意 hf 或 OpenAI 兼容端点（见 安装）。

Q10. 本地小模型（decider/rewriter/memorizer）怎么训练？ 由训练管线在仓库 training/ 下管理；日常使用无需关心。见 架构·主动决策 Decider。

隐私与安全

Q11. 我的对话会上传吗？ 默认所有记忆/对话/数据库在本地。仅当你配置 LLM API 后，推理请求进入所选模型端点（云端模型 = 会出网）；桥是本地 127.0.0.1:18711。敏感数据冷储在 workspace/，令牌加密落盘 SECRET.json。详见 安全模型。

Q12. 审批卡上显示"敏感信息"？ sensitive_detector 会做「gitleaks → Presidio → 小型 LLM」三级脱敏，命中的内容只以密文进 SECRET.json。这是功能不是 bug。

生态

Q13. 什么是 Broker / Recipe / Flow？怎么开始开发？

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

Q14. 市场里的东西安全吗？ 市场提交需 Ed25519 签名 + sha256 校验 + 发布即审核（人工队列）；当前 Broker 仍在 bridge 进程内运行，仅建议安装可信作者的作品。见 安全模型 与 Broker 教程。

Q15. 我可以把 agent 数据迁移到另一台机器吗？ 把 workspace/ 整目录拷贝即可；路径漂移由启动时自动对齐（paths_align）。见 内部指南。

---

没找到答案？去 反馈页 提交提问或加入社群。