仓库索引

整个仓库的地图。来源：REPOSITORY.md（agent 知识库版），本页导航 + 关键结构摘录；逐文件紧凑摘要见源文档 §7。

---

项目定位

Familiars 是 Windows-first 多 Agent AI 桌面应用：Electron(Vue3) 前端 + 单进程 FastAPI bridge（127.0.0.1:18711）+ 本地小模型 + 工具系统 + 记忆 + Broker 生态。

总体架构（缩略）

electron/          Vue3 renderer → IPC → bridge
src/
  ├─ bridge/       FastAPI(47 路由) + deps + app.py 启动副作用
  ├─ models/       AssistantManager / Assistant / Conversation / DialogueManager / RAG
  ├─ tools/        ToolDispatcher + security + sensitive_detector + 15 工具实例
  ├─ utils/        工具实现 + 记忆 + 浏览器 CDP + 多模态 + skill + broker
  ├─ base/         config / gpu_tier / crypto / paths / vram_gate
  ├─ storage/      SQLite(WAL) + migrations v1…v19
  ├─ broker/       hub + workshop（可安装应用包）
  └─ flow/         FlowEngine + resume
workspace/         familitars.db + SECRET.json + agents/ + marketplace_host/ + manager/
test/              pytest 全量
deploy/relay/app/  独立 relay（docker + Caddy）
docs/ + website/   站点与文档

关键运行链路

1. 对话：renderer → /api/chat/stream(SSE) → ConversationSession 工具循环(≤MAX_TURNS) → 模型 → 工具 → 记忆 → 回复。
2. 记忆：DialogueManager 每次构建 RAG 历史（α·cos + e^{−β·Δt} + γ·tree_distance），人设/身份写 USER.md/IDENTITY.md。
3. 主动决策：Decider 小模型做「要不要主动做事」。
4. Broker：交易链 + 可安装 app（manifest+UI+插件），市场走 deploy/relay。

安全与隐私边界

• 本地优先（记忆/对话/DB 本地）、工具审批门（src/tools/security.py：风险分级 + 审批卡）、敏感信息三级脱敏加密（sensitive_detector.py → SECRET.json：gitleaks → Presidio → mini-LLM）。
• 令牌不落明文：X-Bridge-Token 读 workspace/.bridge_token；密钥 HKDF（b"familiars-secrets-v1"）。
• 详见 安全模型。

收录与省略策略

• 仓库把文档（ARCHITECTURE/OPERATION/…）作为 manager 内置知识库（framework_docs.py 索引 + 工具读取）。
• 训练产物 / 大模型权重不收入 git（models/、training/、dataset/ 已忽略）。

阅读路线（最小集）

目标	读哪些
用户	本手册 + OPERATION
架构理解	ARCHITECTURE (§1-§5) + CLAUDE.md 架构摘要
二次开发	CLAUDE.md + REPOSITORY §7 逐文件 + test/
生态开发	RECIPE / FLOW / BROKER_DEVELOPMENT

---

唯一权威：仓库根 REPOSITORY.md（含 §7 逐文件紧凑摘要 + §8 最小阅读路线）。