10 · 工程与附录

架构剖析第十篇：外部 Agent 适配、代码组织速查、构建运行、关键变更点、附录。 对应「技术架构长视频」章节 10（收尾）。来源 ARCHITECTURE.md §12–§15。

§12 外部 Agent 适配

支持接入由用户自己跑的外部 agent（自定义 skill / 自定义 pipeline 的宿主）；
外部 agent 通过 bridge REST + 工具网关参与同一张图。

§13 代码组织速查

核心跳转表（精简）：

目录/文件	职责
`src/bridge/app.py`	FastAPI 挂载、CUDA pin、预热、autorun、监控 rehydrate
`src/bridge/deps.py`	DI 提供者（AssistantManager/DialogueManager/CommHub/UsageTracker）
`src/models/assistant.py`	Assistant + AssistantManager（生命周期/报告/人设演化）
`src/models/conversation.py`	ConversationSession + DialogueManager + RAG 组合
`src/models/transferer.py`	跨 agent / 跨 client / 跨模型派发（6 优先级）
`src/tools/tool_dispatcher.py`	工具名→可调用表（15 默认工具实例）
`src/tools/security.py`	风险等级 / 审批门 / 敏感信息脱敏
`src/utils/browser_tools.py`	Chrome CDP 自动化（单一共享实例）
`src/base/vram_gate.py`	单一 VRAM 准入闸（4 级优先级 / 3 级驱逐）
`src/storage/db.py`	SQLite WAL + 迁移 runner（v1…v19）
`src/broker/hub.py`	Broker 层根（身份/传输/匹配/限流/账本）
`src/flow/engine.py`	FlowEngine 并发执行 + `resume.py` 断点续跑
`src/base/config.py`	pydantic-settings `Settings` 聚合 + `validate_config()`
`src/base/crypto.py`	加密原语（HKDF `b"familiars-secrets-v1"`）

§14 构建与运行

Python 环境：.venv + requirements*.txt；启动 python -m src.bridge.run（HTTPS/2）。
Electron：cd electron && npm run electron:dev（dev）/ electron:build（生产）。
测试：pytest（须真 SQLite，FAMILIARS_DB_PATH=:memory:）。
生产 relay：deploy/relay/app/（docker + Caddy，Cloudflare DNS-01）。

§15 附录：与最新代码对齐的关键变更点

原文档 §15 专门列出"文档 vs 代码已对齐的关键变更"（如 consult_doc 仍活跃、broker v18/v19、flow 落地）。请看源文与 CHANGELOG 方向保持一致。

视频时间点映射

视频时间点	内容
（待录制）	代码地图：30 秒定位任意功能
（待录制）	从零跑起：git clone → venv → bridge → CLI 一条命令

🎉 架构剖析十篇结束。继续：开发指南或生态开发教程。