系统架构

受众： 开发者
前提： 项目结构
目标： 理解 CocoCat v2 的分层架构

架构分层

┌──────────────────────────────────────────────┐
│              用户交互层                         │
│  React SPA / REST API / WebSocket / 频道回调   │
└───────────────────┬──────────────────────────┘
                    │ HTTP / WS
┌───────────────────▼──────────────────────────┐
│             FastAPI 应用层                     │
│  cococat/app.py — 路由注册、认证中间件、生命周期   │
└───────────────────┬──────────────────────────┘
                    │ AppContext (DI)
┌───────────────────▼──────────────────────────┐
│           核心服务层                            │
│  AgentPool / EventBus / SubAgentExecutor       │
│  SandboxProvider / DagStore / TaskWorker       │
└───────────────────┬──────────────────────────┘
                    │
┌───────────────────▼──────────────────────────┐
│           数据层 (SQLite WAL)                   │
│  agents / messages / tasks / scenes           │
│  facts (FTS5) / dag_runs / todos              │
└──────────────────────────────────────────────┘

核心组件

Agent (cococat/core/agent.py)

Python 对象，非子进程。每个 Agent 包含 LLM 实例、系统提示词、工具列表。支持 ReAct 循环：LLM 思考 → 工具调用 → 结果反馈 → 继续思考（最多 20 轮）。

AgentPool (cococat/core/agent_pool.py)

管理所有运行中的 Agent 实例。支持场景绑定、空闲代理查找。

EventBus (cococat/core/event_bus.py)

进程内异步发布/订阅。轻量替代消息队列。WebSocket 推送、子代理完成通知等事件通过此总线。

SubAgentExecutor (cococat/core/sub_agent.py)

子代理任务分发。支持两种模式：AgentPool 模式（复用空闲代理）和 SandboxProvider 模式（按任务创建沙箱）。

SandboxProvider (cococat/core/sandbox/)

沙箱执行环境管理。LocalExecutor（进程内）和 CubeSandboxExecutor（KVM MicroVM）两种后端。

DagStore (cococat/core/dag_store.py)

DAG 任务图持久化。SqliteDagStore（SQLite）和 FileDagStore（YAML 文件）两种适配器。

TaskWorker (cococat/worker.py)

后台轮询 Worker，处理待执行的 KB 摄入任务和 DAG 任务。

记忆系统 (cococat/memory/)

统一记忆管理。MemoryStore 提供：手动记录/搜索、Auto-Dream 自动提取、定期摘要编译（today → week → longterm）、FTS5 原子事实提取。

知识库 (cococat/kb/ + cococat/ingest/)

LLM 驱动的文档摄入管道 → 结构化 Wiki 页面。支持全文搜索、交叉引用、去重、知识图谱可视化。

频道架构

所有频道适配器在 cococat/core/channels/ 下，继承 ChannelBase：

• WeChat — 微信公众号被动回复
• Feishu — WebSocket + REST API
• Weixin — 个人微信 (iLink)
• Discord — WebSocket Gateway + REST
• Telegram — 长轮询 Bot API

安全模型

三层防护：

1. 认证 — JWT Bearer + X-API-Key 中间件
2. 沙箱 — 路径白名单、命令校验
3. 隔离 — 可选的 CubeSandbox MicroVM 或 Linux namespace