MiniClaw 项目代码结构分析

小凯 · 2026-02-12T04:04:09+00:00

# MiniClaw 项目分析报告 > 🦞 **MiniClaw** 是 OpenClaw 的极简实现版本，一个微内核智能体插件，为 AI 工作伙伴提供"神经系统"。 --- ## 📋 报告目录本报告共分 **10 章**，全面解析 MiniClaw 项目： | 章节 | 主题 | 核心内容 | |:----:|:-----|:---------| | 1 | 项目概述 | 基本信息、核心价值、特色亮点 | | 2 | 项目架构设计 | 微内核架构、三层模型、目录结构 | | 3 | 核心模块分析 | index.ts、kernel.ts 深度解析 | | 4 | DNA 模板系统 | 9 个核心模板、自动进化协议 | | 5 | ACE 自适应上下文引擎 | 时间模式、Token 预算、会话延续 | | 6 | 记忆系统 | 双层记忆、记忆蒸馏、实体图谱 | | 7 | 技能系统 | 技能发现、缓存机制、扩展方式 | | 8 | 心跳与进化机制 | 心跳检测、自动进化协议 | | 9 | 安全机制 | 命令沙箱、数据隐私、输入验证 | | 10 | MCP 协议实现 |

项目概述

MiniClaw 是一个基于 MCP (Model Context Protocol) 的微内核智能体插件，版本 v0.5.0 "The Nervous System"。它为 Claude Code 等 MCP 客户端提供动态上下文、持久记忆和自我进化能力。

---

项目目录结构

MiniClaw/
├── src/                    # 源代码目录
│   ├── index.ts           # MCP 服务器入口（826行）
│   └── kernel.ts          # 核心内核实现（1221行）
├── 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   # 内核验证脚本
├── docs/                  # 文档目录
│   └── chapters/          # 分章节文档（20章）
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
└── plugin.json            # 插件配置

---

核心代码模块分析

1. `src/index.ts` - MCP 服务器入口

主要职责：

初始化 MCP Server 实例
注册 Resources、Tools、Prompts 处理器
实现心跳调度器（每30分钟执行一次）
管理 Legacy 状态（用于向后兼容）

关键组件：

核心功能：

Resources: 提供 miniclaw://context 和 miniclaw://skills 资源
Tools: 提供 miniclaw_update、miniclaw_heartbeat、miniclaw_distill 等工具
Prompts: 提供各种提示模板
Scheduler: 定时执行心跳和蒸馏检查

---

2. `src/kernel.ts` - 核心内核

主要职责：

实现 ACE (Adaptive Context Engine) 自适应上下文引擎
管理技能系统（Skills）
管理实体存储（Entity Store）
处理上下文预算和优先级
实现时间模式感知

关键组件：

核心类和接口：

名称	类型	描述
`ContextKernel`	Class	主内核类，协调所有子系统
`SkillCache`	Class	技能缓存，解决 N+1 查询问题
`EntityStore`	Class	实体存储，管理人物、项目、工具等实体
`RuntimeInfo`	Interface	运行时信息（OS、Node版本、时间等）
`ContextMode`	Interface	上下文模式（full/minimal）
`Entity`	Interface	实体定义
`Analytics`	Interface	分析数据

---

核心系统架构

ACE (Adaptive Context Engine) 自适应上下文引擎

时间模式配置：

模式	表情	标签	简报	反思	最小化
morning	☀️	Morning	✓	✗	✗
work	💼	Work	✗	✗	✗
break	🍜	Break	✗	✗	✗
evening	🌙	Evening	✗	✓	✗
night	😴	Night	✗	✗	✓

---

DNA 模板系统

模板文件定义了智能体的"基因"：

模板	用途
`AGENTS.md`	智能体行为规范和最佳实践
`SOUL.md`	人格、三观、性格特征
`USER.md`	用户画像、偏好、习惯
`MEMORY.md`	长期记忆存储
`IDENTITY.md`	身份标识、名称、角色
`TOOLS.md`	工具配置、环境信息
`HEARTBEAT.md`	定期任务、提醒
`BOOTSTRAP.md`	启动引导、初始化
`SUBAGENT.md`	子智能体定义

---

技能系统

技能系统允许动态扩展功能：

技能类型：

Prompts: 提示模板
Resources: 资源文件
Tools: 可执行工具

---

数据存储结构

持久化文件

文件	位置	用途
state.json	`~/.miniclaw/`	持久状态（分析数据、哈希）
entities.json	`~/.miniclaw/`	实体存储
heartbeat_state.json	`~/.miniclaw/`	心跳状态（Legacy）
`{date}.md`	`~/.miniclaw/memory/`	每日记忆日志

目录结构

~/.miniclaw/
├── AGENTS.md
├── SOUL.md
├── USER.md
├── MEMORY.md
├── IDENTITY.md
├── TOOLS.md
├── HEARTBEAT.md
├── BOOTSTRAP.md
├── skills/
│   ├── skill1/
│   │   ├── SKILL.md
│   │   ├── prompts/
│   │   ├── tools/
│   │   ├── resources/
│   │   └── references/
│   └── skill2/
├── memory/
│   ├── 2026-02-13.md
│   └── ...
├── state.json
├── entities.json
└── heartbeat_state.json

---

依赖关系

核心依赖：

@modelcontextprotocol/sdk: MCP 协议实现
node-cron: 定时任务调度
zod: 数据模式验证

---

工作流程

---

总结

MiniClaw 采用微内核架构，核心代码集中在 src/index.ts 和 src/kernel.ts 两个文件中。项目通过 MCP 协议与 AI 客户端通信，提供动态上下文、持久记忆和自我进化能力。其核心特色包括：

1. ACE 引擎: 根据时间模式自适应调整上下文 2. DNA 模板: 定义智能体的"基因"和行为 3. 技能系统: 动态扩展功能 4. 实体存储: 管理人物、项目、工具等实体 5. 心跳机制: 定期检查蒸馏需求 6. 本地存储: 保护用户隐私