架构设计

云雀 Agent 是一个模块化 AI 代理运行时，包含 40+ 核心模块，全部在 cmd/agent/main.go 中组装。采用"控制面 + 执行面"双层架构，核心认知引擎与外部集成解耦。

请求处理流程

HTTP / WebSocket / IM 渠道 → Gateway (认证 · CORS · 限流 · RBAC)
  → 安全护栏 (输入: PII 脱敏 · 注入检测 · Shell Guard)
  → 会话管理 (历史加载 · 分支/Fork)
  → 智能路由器 (按复杂度选模型: fast / smart / expert)
  → 成本追踪器 (预算检查 · 实时计费)
  → 上下文管理器 (Token 预算 · 压缩 · 滑动窗口)
  → 规划器 (LLM 规划循环 + 记忆 + 知识 RAG + 技能编排)
  → 安全护栏 (输出审核: PII 脱敏 · 内容过滤)
  → 记忆管线 (异步事实提取 → 5 层记忆)
  → 审计链 (Merkle 不可篡改日志)
  → 反思循环 (经验积累 → 策略编译)

核心模块

认知层 (agentcore)

模块	功能
llm	LLM 客户端，流式输出，提供者注册，熔断器
planner	多步规划循环，技能编排，情绪感知，Reverie 内心独白
memory	5 层记忆系统 (短期/中期/长期/可编辑/知识图谱)
knowledge	混合 RAG：BM25 + 向量 + RRF + Rerank
context	Token 预算管理和上下文压缩
router	按复杂度智能路由模型 (Bandit 在线选择)
skills	技能注册、执行、参数校验
skillmarket	技能安装、ClawHub/ToriHub 市场、SkillFileLoader
emotion	情绪分析、情感历史、表情包映射
persona	人格链、特征开关、Persona 模板
task	任务生命周期、线程管理、工作记忆、增长追踪
workflow	DAG 工作流引擎，条件分支，并行执行
cron	定时任务，支持 cron 表达式和固定间隔
trigger	事件触发器，基于条件自动执行

安全与治理层

模块	功能
guardrails	内容安全，PII 脱敏，注入检测，Shell Guard
audit	Merkle 链不可篡改审计日志
trust	信任分系统，渐进式权限
approval	高风险操作审批，4 级风险分类
rbac	角色权限控制，4 层继承
review	代码/内容审查门控

执行层 (execution)

模块	功能
channel	16+ IM 渠道适配器，韧性封装
sandbox	代码沙箱 (进程/Docker/K8s/Wasm)，E2B Desktop
scheduler	任务调度器，Q-Learning 优化
tools	工具执行管理，Shell 策略

实验性模块 (experimental)

模块	功能
reflect	经验积累 → 策略编译 → 行为优化反馈环
iterate	迭代式改进引擎
distill	语义蒸馏
skillgrow	技能增长检测
heartbeat	心跳守护
causal	因果链提取

目录结构

internal/
├── agentcore/        # 40+ 核心认知模块
│   ├── llm/          # LLM 客户端 + 提供者注册
│   ├── planner/      # 规划器 + Reverie + 情绪感知
│   ├── memory/       # 5 层记忆系统
│   ├── knowledge/    # 混合 RAG 检索
│   ├── skills/       # 技能注册与执行
│   ├── skillmarket/  # 技能市场 + SkillFileLoader
│   ├── emotion/      # 情绪分析 + 表情包
│   ├── persona/      # 人格链
│   ├── task/         # 任务引擎
│   ├── workflow/     # 工作流引擎
│   └── ...           # guardrails, audit, trust, rbac, etc.
├── controlplane/     # HTTP/WS API 网关
├── execution/        # 沙箱、调度器、16+ 渠道适配器
├── experimental/     # 反思、蒸馏、因果链等实验模块
├── storage/          # SQLite 存储层
├── ledger/           # KV 存储 + 持久化桥接
├── mcp/              # MCP 协议集成
├── integrations/     # 第三方集成 (MinerU 等)
├── observe/          # 可观测性
└── tori/             # Tori API 集成
cmd/agent/            # 入口点
plugins/              # Go 技能插件
pkg/                  # 公共库 (plugin loader, skills)
data/                 # 运行时数据
├── plugins/          # 脚本插件 (Python/Node/Shell)
├── skills/           # 文件技能 (SKILL.md)
└── knowledge/        # 知识库文档
heroui-web/           # HeroUI v3 + Next.js 仪表板
docs/                 # VitePress 文档站

存储

双层持久化：SQLite 关系存储（memories/sessions/messages）+ Ledger KV 配置存储（25+ 命名空间）。本地优先，零外部依赖。详见 存储与 Ledger。