【MiniClaw 深度解析】第二章：项目架构设计

# 第二章：项目架构设计 > 🏗️ 本章深入分析 MiniClaw 的微内核架构、三层模型和目录结构设计。 --- ## 2.1 整体架构概览 ### 2.1.1 微内核架构（Micro-Kernel Architecture） MiniClaw 采用 **微内核架构**，这是一种轻量级、可扩展、模块化的架构模式。 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 微内核架构设计理念 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 传统 Agent 框架 MiniClaw 微内核 │ │ ┌───────────────────┐ ┌───────────────────┐ │ │ │ ████████████████ │ │ ◉ 内核 │ │ │ │ █ 臃肿的核心 █ │ │ (~500 行) │ │ │ │ ████████████████ │ │ │ │ │ │ █ 功能耦合 █ │ │ ┌───┐ ┌───┐ ┌───┐│ │ │ │ █ 难以扩展 █ │ │ │技能│ │技能│ │技能││ │ │ │ █ 维护困难 █ │ │ └───┘ └───┘ └───┘│ │ │ │ ████████████████ │ │ 插件化扩展 │ │ │ └───────────────────┘ └───────────────────┘ │ │ │ │ ❌ 代码量大、复杂度高 ✅ 代码量小、易于维护 │ │ ❌ 功能耦合、难以定制 ✅ 功能解耦、灵活扩展 │ │ ❌ 学习曲线陡峭 ✅ 学习曲线平缓 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` #### 架构特点 | 特点 | 说明 | 优势 | |:-----|:-----|:-----| | **轻量级** | 核心代码约 2,700 行 | 易于理解和维护 | | **可扩展** | 技能插件化设计 | 按需添加功能 | | **模块化** | 清晰的职责分离 | 降低耦合度 | | **高内聚** | 每个模块职责单一 | 提高代码质量 | ### 2.1.2 三层架构模型 MiniClaw 采用 **三层架构模型**，将系统划分为 Kernel、Interface、DNA 三个层次。 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ MiniClaw 三层架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ 👤 用户 │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Interface 层 (身体) │ │ │ │ src/index.ts │ │ │ │ ┌──────────────┬──────────────┬──────────────┐ │ │ │ │ │ MCP 协议实现 │ 工具分发 │ 心跳检测 │ │ │ │ │ └──────────────┴──────────────┴──────────────┘ │ │ │ └────────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Kernel 层 (大脑) │ │ │ │ src/kernel.ts │ │ │ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │ │ │ │ACE 引擎 │记忆图谱 │技能加载 │执行沙箱 │ │ │ │ │ └──────────┴──────────┴──────────┴──────────┘ │ │ │ └────────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ DNA 层 (基因) │ │ │ │ templates/*.md │ │ │ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │ │ │ │性格定义 │宪法规则 │启动协议 │用户画像 │ │ │ │ │ └──────────┴──────────┴──────────┴──────────┘ │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 2.2 目录结构详解 ### 2.2.1 项目目录结构 ``` miniclaw/ ├── 📁 src/ # 源代码目录 │ ├── 📄 index.ts # 入口文件 (Interface 层) │ ├── 📄 kernel.ts # 核心内核 (Kernel 层) │ └── 📄 types.ts # 类型定义 │ ├── 📁 templates/ # DNA 模板文件 │ ├── 📄 AGENTS.md # 工作空间章程 │ ├── 📄 SOUL.md # 灵魂/三观 │ ├── 📄 IDENTITY.md # 身份信息 │ ├── 📄 USER.md # 用户画像 │ ├── 📄 TOOLS.md # 环境配置 │ ├── 📄 MEMORY.md # 长期记忆 │ ├── 📄 HEARTBEAT.md # 心跳检查 │ ├── 📄 BOOTSTRAP.md # 启动协议 │ └── 📄 SUBAGENT.md # 子代理定义 │ ├── 📁 scripts/ # 脚本工具 │ └── 📄 verify_kernel.ts # 内核验证脚本 │ ├── 📄 package.json # 项目配置 ├── 📄 tsconfig.json # TypeScript 配置 └── 📄 README.md # 项目说明 ``` ### 2.2.2 运行时目录结构 ``` ~/.miniclaw/ # MiniClaw 主目录 ├── 📄 AGENTS.md # 工作空间章程 ├── 📄 SOUL.md # 灵魂/三观 ├── 📄 IDENTITY.md # 身份信息 ├── 📄 USER.md # 用户画像 ├── 📄 TOOLS.md # 环境配置 ├── 📄 MEMORY.md # 长期记忆 ├── 📄 HEARTBEAT.md # 心跳检查 ├── 📄 BOOTSTRAP.md # 启动协议 ├── 📄 SUBAGENT.md # 子代理定义 │ ├── 📁 memory/ # 记忆目录 │ ├── 📄 2026-02-12.md # 今日日志 │ ├── 📄 2026-02-11.md # 昨日日志 │ └── 📄 ... │ ├── 📁 archived/ # 归档目录 │ └── 📄 2026-02-10.md.gz # 压缩归档 │ ├── 📁 skills/ # 技能目录 │ ├── 📁 git-workflow/ # Git 工作流技能 │ ├── 📁 code-review/ # 代码审查技能 │ └── 📁 ... │ └── 📄 heartbeat_state.json # 心跳状态 ``` --- ## 2.3 核心模块职责 ### 2.3.1 Interface 层（index.ts） ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Interface 层 (身体) │ │ src/index.ts │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 核心职责：与外部世界的交互接口 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ MCP 服务器实现 │ │ │ │ ├── 服务器初始化 │ │ │ │ ├── 能力声明 │ │ │ │ └── 传输层连接 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 资源处理器 │ │ │ │ ├── 列出可用资源 │ │ │ │ ├── 读取资源内容 │ │ │ │ └── 动态资源生成 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 工具处理器 │ │ │ │ ├── 列出可用工具 │ │ │ │ ├── 调用工具 │ │ │ │ └── 参数验证 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 提示词处理器 │ │ │ │ ├── 列出可用提示词 │ │ │ │ └── 获取提示词内容 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 2.3.2 Kernel 层（kernel.ts） ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Kernel 层 (大脑) │ │ src/kernel.ts │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 核心职责：智能体的大脑，负责核心逻辑处理 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ ACE 自适应上下文引擎 │ │ │ │ • 时间模式检测 (morning/work/break/evening/night) │ │ │ │ • 会话延续检测 │ │ │ │ • 上下文预算管理 │ │ │ │ • 内容差异检测 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 记忆图谱管理 │ │ │ │ • EntityStore 实体知识图谱 │ │ │ │ • 双层记忆系统 (短期/长期) │ │ │ │ • 记忆蒸馏评估 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 技能加载系统 │ │ │ │ • SkillCache 技能缓存 │ │ │ │ • 技能发现 (prompts/resources/tools) │ │ │ │ • 可执行技能支持 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 执行沙箱 │ │ │ │ • 命令白名单检查 │ │ │ │ • 超时控制 (10s) │ │ │ │ • 输出截断 (1MB) │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 本章小结 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 第二章 核心要点 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 🏗️ 微内核架构 │ │ • 轻量级核心 (~2,700 行) │ │ • 插件化扩展 │ │ • 低耦合高内聚 │ │ │ │ 🏛️ 三层架构模型 │ │ • DNA 层 (基因) - 模板文件 │ │ • Kernel 层 (大脑) - 核心逻辑 │ │ • Interface 层 (身体) - 外部交互 │ │ │ │ 📁 目录结构 │ │ • src/ - 源代码 │ │ • templates/ - 默认模板 │ │ • ~/.miniclaw/ - 运行时数据 │ │ │ │ 🔄 数据流 │ │ 请求 → Interface → Kernel → DNA → 响应 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- *本文档是《MiniClaw 深度解析》系列的第二章，下一章将详细介绍核心模块 index.ts 和 kernel.ts 的实现细节。*