第二章：项目架构设计
🏗️ 本章深入分析 MiniClaw 的微内核架构、三层模型和目录结构设计。
2.1 整体架构概览
2.1.1 微内核架构（Micro-Kernel Architecture）
MiniClaw 采用 微内核架构，这是一种轻量级、可扩展、模块化的架构模式。
┌─────────────────────────────────────────────────────────────────────┐
│ 微内核架构设计理念 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 传统 Agent 框架 MiniClaw 微内核 │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ ████████████████ │ │ ◉ 内核 │ │
│ │ █ 臃肿的核心 █ │ │ (~500 行) │ │
│ │ ████████████████ │ │ │ │
│ │ █ 功能耦合 █ │ │ ┌───┐ ┌───┐ ┌───┐│ │
│ │ █ 难以扩展 █ │ │ │技能│ │技能│ │技能││ │
│ │ █ 维护困难 █ │ │ └───┘ └───┘ └───┘│ │
│ │ ████████████████ │ │ 插件化扩展 │ │
│ └───────────────────┘ └───────────────────┘ │
│ │
│ ❌ 代码量大、复杂度高 ✅ 代码量小、易于维护 │
│ ❌ 功能耦合、难以定制 ✅ 功能解耦、灵活扩展 │
│ ❌ 学习曲线陡峭 ✅ 学习曲线平缓 │
│ │
└─────────────────────────────────────────────────────────────────────┘架构特点
| 特点 | 说明 | 优势 |
|---|---|---|
| 轻量级 | 核心代码约 2,700 行 | 易于理解和维护 |
| 可扩展 | 技能插件化设计 | 按需添加功能 |
| 模块化 | 清晰的职责分离 | 降低耦合度 |
| 高内聚 | 每个模块职责单一 | 提高代码质量 |
┌─────────────────────────────────────────────────────────────────────┐
│ 代码规模对比 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ OpenClaw (完整版) │
│ ████████████████████████████████████████████████████ ~10,000+ 行 │
│ │
│ MiniClaw (极简版) │
│ ██████████████████████████ ~2,700 行 │
│ │
│ └── 仅保留核心功能，降低 70%+ 代码量 │
│ │
└─────────────────────────────────────────────────────────────────────┘2.1.2 三层架构模型
MiniClaw 采用 三层架构模型，将系统划分为 Kernel、Interface、DNA 三个层次。
┌─────────────────────────────────────────────────────────────────────┐
│ MiniClaw 三层架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ 👤 用户 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Interface 层 (身体) │ │
│ │ src/index.ts │ │
│ │ ┌──────────────┬──────────────┬──────────────┐ │ │
│ │ │ MCP 协议实现 │ 工具分发 │ 心跳检测 │ │ │
│ │ └──────────────┴──────────────┴──────────────┘ │ │
│ └────────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Kernel 层 (大脑) │ │
│ │ src/kernel.ts │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │ACE 引擎 │记忆图谱 │技能加载 │执行沙箱 │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ └────────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ DNA 层 (基因) │ │
│ │ templates/*.md │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │性格定义 │宪法规则 │启动协议 │用户画像 │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘各层职责详解
┌─────────────────────────────────────────────────────────────────────┐
│ Kernel 层 (大脑) │
│ src/kernel.ts │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 核心职责：智能体的大脑，负责核心逻辑处理 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ACE 自适应上下文引擎 │ │
│ │ • 时间模式检测 (morning/work/break/evening/night) │ │
│ │ • 会话延续检测 │ │
│ │ • 上下文预算管理 │ │
│ │ • 内容差异检测 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 记忆图谱管理 │ │
│ │ • EntityStore 实体知识图谱 │ │
│ │ • 双层记忆系统 (短期/长期) │ │
│ │ • 记忆蒸馏评估 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 技能加载系统 │ │
│ │ • SkillCache 技能缓存 │ │
│ │ • 技能发现 (prompts/resources/tools) │ │
│ │ • 可执行技能支持 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 执行沙箱 │ │
│ │ • 命令白名单检查 │ │
│ │ • 超时控制 (10s) │ │
│ │ • 输出截断 (1MB) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ Interface 层 (身体) │
│ src/index.ts │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 核心职责：与外部世界的交互接口 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MCP 协议实现 │ │
│ │ • Server 实例创建与配置 │ │
│ │ • 能力声明 (resources/tools/prompts) │ │
│ │ • Stdio 传输层 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 工具分发 │ │
│ │ • ListToolsRequestSchema 处理 │ │
│ │ • CallToolRequestSchema 处理 │ │
│ │ • 参数验证 (Zod Schema) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 心跳检测 │ │
│ │ • node-cron 调度器 │ │
│ │ • 30 分钟周期检查 │ │
│ │ • 蒸馏需求评估 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ DNA 层 (基因) │
│ templates/*.md │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 核心职责：定义智能体的"基因"——性格、规则、身份 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AGENTS.md → 工作空间章程 (宪法) │ │
│ │ SOUL.md → 世界观与人格 (灵魂) │ │
│ │ IDENTITY.md → 名称与元数据 (身份) │ │
│ │ USER.md → 用户画像 (认知) │ │
│ │ TOOLS.md → 环境配置 (工具) │ │
│ │ MEMORY.md → 长期记忆 (经验) │ │
│ │ HEARTBEAT.md → 周期检查项 (习惯) │ │
│ │ BOOTSTRAP.md → 首次运行引导 (出生) │ │
│ │ SUBAGENT.md → 子代理上下文 (分身) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 特点：Markdown 格式，可被 Agent 读写和进化 │
│ │
└─────────────────────────────────────────────────────────────────────┘层级交互流程
sequenceDiagram
participant U as 用户
participant I as Interface 层
participant K as Kernel 层
participant D as DNA 层
U->>I: 发起请求
I->>K: 调用 boot()
K->>D: 加载模板文件
D-->>K: 返回文件内容
K->>K: 编译上下文
K-->>I: 返回编译结果
I-->>U: 响应用户2.2 目录结构详解
2.2.1 项目源码目录结构
MiniClaw/
│
├── 📁 dist/ # 编译输出目录
│ ├── 📄 index.js # 入口文件编译产物
│ └── 📄 kernel.js # 内核编译产物
│
├── 📁 docs/ # 文档目录
│ ├── 📄 openclaw_context_humanized.md # OpenClaw 上下文机制解析
│ └── 📁 chapters/ # 章节文档目录
│ ├── 第一章-项目概述.md
│ ├── 第二章-项目架构设计.md
│ └── ...
│
├── 📁 src/ # 源代码目录
│ ├── 📄 index.ts # MCP 服务入口 (Interface 层)
│ └── 📄 kernel.ts # 核心内核实现 (Kernel 层)
│
├── 📁 templates/ # 模板文件目录 (DNA 层)
│ ├── 📄 AGENTS.md # 工作空间章程
│ ├── 📄 BOOTSTRAP.md # 首次运行引导
│ ├── 📄 HEARTBEAT.md # 心跳检查项
│ ├── 📄 IDENTITY.md # 身份定义
│ ├── 📄 MEMORY.md # 长期记忆
│ ├── 📄 SOUL.md # 灵魂/三观
│ ├── 📄 SUBAGENT.md # 子代理上下文
│ ├── 📄 TOOLS.md # 环境配置
│ └── 📄 USER.md # 用户画像
│
├── 📁 scripts/ # 脚本目录
│ ├── 📄 install.sh # 安装脚本
│ ├── 📄 session-start.sh # 会话启动脚本
│ └── 📄 verify_kernel.ts # 内核验证脚本
│
├── 📄 .gitignore # Git 忽略配置
├── 📄 package.json # NPM 包配置
├── 📄 package-lock.json # 依赖锁定文件
├── 📄 plugin.json # 插件配置
├── 📄 tsconfig.json # TypeScript 配置
├── 📄 README.md # 中文说明文档
└── 📄 README_EN.md # 英文说明文档2.2.2 目录职责说明
┌─────────────────────────────────────────────────────────────────────┐
│ 目录职责矩阵 │
├───────────────┬─────────────────────────────────────────────────────┤
│ 目录 │ 职责说明 │
├───────────────┼─────────────────────────────────────────────────────┤
│ dist/ │ 编译产物，由 TypeScript 编译生成，可直接运行 │
├───────────────┼─────────────────────────────────────────────────────┤
│ docs/ │ 项目文档，包含设计文档、教程、章节分析等 │
├───────────────┼─────────────────────────────────────────────────────┤
│ src/ │ 源代码，核心实现逻辑 │
│ │ • index.ts: MCP 协议层，处理外部交互 │
│ │ • kernel.ts: 内核层，核心业务逻辑 │
├───────────────┼─────────────────────────────────────────────────────┤
│ templates/ │ DNA 模板，定义 Agent 的"基因" │
│ │ 首次运行时复制到 ~/.miniclaw/ │
├───────────────┼─────────────────────────────────────────────────────┤
│ scripts/ │ 辅助脚本，安装、验证、启动等 │
└───────────────┴─────────────────────────────────────────────────────┘2.3 运行时目录结构
2.3.1 ~/.miniclaw/ 目录详解
MiniClaw 运行时会在用户主目录创建 ~/.miniclaw/ 目录存储所有数据。
~/.miniclaw/
│
├── 📄 AGENTS.md # 工作空间章程
├── 📄 SOUL.md # 世界观与人格
├── 📄 IDENTITY.md # 名称与元数据
├── 📄 USER.md # 用户画像
├── 📄 TOOLS.md # 环境配置
├── 📄 MEMORY.md # 长期记忆
├── 📄 HEARTBEAT.md # 周期检查项
├── 📄 BOOTSTRAP.md # 首次运行引导（完成后删除）
│
├── 📄 state.json # 持久化状态
├── 📄 entities.json # 实体知识图谱
├── 📄 heartbeat_state.json # 心跳状态
│
├── 📁 memory/ # 运行时日志目录
│ ├── 📄 2026-02-01.md # 每日日志
│ ├── 📄 2026-02-02.md
│ ├── 📄 ...
│ └── 📁 archived/ # 归档日志
│ ├── 📄 2026-01-01.md
│ └── 📄 ...
│
└── 📁 skills/ # 技能目录
└── 📁 <skill-name>/ # 单个技能
├── 📄 SKILL.md # 技能定义
└── 📁 references/ # 技能参考文件2.3.2 文件类型分类
┌─────────────────────────────────────────────────────────────────────┐
│ 运行时文件分类 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 📜 配置文件 (Markdown) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AGENTS.md SOUL.md IDENTITY.md USER.md │ │
│ │ TOOLS.md MEMORY.md HEARTBEAT.md BOOTSTRAP.md │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 📊 数据文件 (JSON) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ state.json → 分析统计、工具调用记录 │ │
│ │ entities.json → 实体知识图谱 │ │
│ │ heartbeat_state.json → 心跳状态、蒸馏标记 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 📝 日志文件 (Markdown) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ memory/YYYY-MM-DD.md → 每日对话日志 │ │
│ │ memory/archived/ → 归档的历史日志 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 🔧 技能文件 (Markdown + Scripts) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ skills/<name>/SKILL.md → 技能定义 │ │
│ │ skills/<name>/references/ → 技能参考文档 │ │
│ │ skills/<name>/<script> → 可执行脚本 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘2.3.3 数据流向图
┌─────────────────────────────────────────────────────────────────────┐
│ 数据流向图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户输入 │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Interface │ │
│ │ (MCP) │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ 读取配置 ┌─────────────┐ │
│ │ │ ◄───────────────── │ *.md 文件 │ │
│ │ Kernel │ │ (DNA) │ │
│ │ │ ─────────────────► │ │ │
│ │ (大脑) │ 写入进化 └─────────────┘ │
│ └──────┬──────┘ │
│ │ │
│ ├──────────────┬──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │state.json │ │entities. │ │ memory/ │ │
│ │ │ │ json │ │ YYYY-MM-DD│ │
│ │ (统计) │ │ (图谱) │ │ (日志) │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘2.4 架构设计原则
2.4.1 SOLID 原则应用
┌─────────────────────────────────────────────────────────────────────┐
│ SOLID 原则在 MiniClaw 中的应用 │
├───────────────┬─────────────────────────────────────────────────────┤
│ 原则 │ 应用说明 │
├───────────────┼─────────────────────────────────────────────────────┤
│ S - 单一职责 │ • index.ts 专注 MCP 协议 │
│ │ • kernel.ts 专注核心逻辑 │
│ │ • EntityStore 专注实体管理 │
│ │ • SkillCache 专注技能缓存 │
├───────────────┼─────────────────────────────────────────────────────┤
│ O - 开放封闭 │ • 技能系统支持插件扩展 │
│ │ • 核心代码无需修改即可添加新功能 │
├───────────────┼─────────────────────────────────────────────────────┤
│ L - 里氏替换 │ • 工具处理器可替换 │
│ │ • 资源处理器可替换 │
├───────────────┼─────────────────────────────────────────────────────┤
│ I - 接口隔离 │ • 清晰的接口定义 │
│ │ • 各处理器独立 │
├───────────────┼─────────────────────────────────────────────────────┤
│ D - 依赖倒置 │ • 依赖抽象接口而非具体实现 │
│ │ • MCP SDK 提供抽象层 │
└───────────────┴─────────────────────────────────────────────────────┘2.4.2 设计模式应用
┌─────────────────────────────────────────────────────────────────────┐
│ 设计模式应用 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🏭 工厂模式 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ discoverSkillPrompts() → 创建技能提示词声明 │ │
│ │ discoverSkillTools() → 创建技能工具声明 │ │
│ │ discoverSkillResources()→ 创建技能资源声明 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 📦 缓存模式 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ SkillCache 类 │ │
│ │ • TTL = 5000ms │ │
│ │ • 解决 N+1 查询问题 │ │
│ │ • 自动刷新机制 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 🎯 策略模式 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ TimeMode 策略 │ │
│ │ • morning/work/break/evening/night │ │
│ │ • 每种模式有不同的上下文策略 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 🔧 模板方法模式 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ boot() 方法流程 │ │
│ │ 1. 初始化环境 │ │
│ │ 2. 检测模式 │ │
│ │ 3. 并行扫描 │ │
│ │ 4. 编译上下文 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘本章小结
┌─────────────────────────────────────────────────────────────────────┐
│ 第二章 核心要点 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🏗️ 微内核架构：轻量级、可扩展、模块化 │
│ │
│ 📊 三层模型：Kernel (大脑) + Interface (身体) + DNA (基因) │
│ │
│ 📁 目录结构：清晰的职责分离，源码/模板/脚本分离 │
│ │
│ 💾 运行时目录：~/.miniclaw/ 存储所有用户数据 │
│ │
│ 🎯 设计原则：SOLID 原则 + 经典设计模式 │
│ │
└─────────────────────────────────────────────────────────────────────┘下一章：核心模块分析 →