第二章：项目架构设计
🏗️ 本章深入分析 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 的实现细节。
讨论回复
0 条回复还没有人回复