MiniClaw 项目代码结构分析
项目概述
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 # 插件配置
核心代码模块分析
主要职责：
- 初始化 MCP Server 实例
- 注册 Resources、Tools、Prompts 处理器
- 实现心跳调度器（每30分钟执行一次）
- 管理 Legacy 状态（用于向后兼容）
关键组件：
核心功能：
- Resources: 提供
miniclaw://context 和 miniclaw://skills 资源 - Tools: 提供
miniclaw_update、miniclaw_heartbeat、miniclaw_distill 等工具 - Prompts: 提供各种提示模板
- Scheduler: 定时执行心跳和蒸馏检查
主要职责：
- 实现 ACE (Adaptive Context Engine) 自适应上下文引擎
- 管理技能系统（Skills）
- 管理实体存储（Entity Store）
- 处理上下文预算和优先级
- 实现时间模式感知
关键组件：
核心类和接口：
| 名称 | 类型 | 描述 |
|---|
[ContextKernel](src/kernel.ts:1) | Class | 主内核类，协调所有子系统 |
[SkillCache](src/kernel.ts:135) | Class | 技能缓存，解决 N+1 查询问题 |
[EntityStore](src/kernel.ts:198) | Class | 实体存储，管理人物、项目、工具等实体 |
[RuntimeInfo](src/kernel.ts:24) | Interface | 运行时信息（OS、Node版本、时间等） |
[ContextMode](src/kernel.ts:33) | Interface | 上下文模式（full/minimal） |
[Entity](src/kernel.ts:106) | Interface | 实体定义 |
[Analytics](src/kernel.ts:117) | Interface | 分析数据 |
核心系统架构
ACE (Adaptive Context Engine) 自适应上下文引擎
时间模式配置：
| 模式 | 表情 | 标签 | 简报 | 反思 | 最小化 |
|---|
| morning | ☀️ | Morning | ✓ | ✗ | ✗ |
| work | 💼 | Work | ✗ | ✗ | ✗ |
| break | 🍜 | Break | ✗ | ✗ | ✗ |
| evening | 🌙 | Evening | ✗ | ✓ | ✗ |
| night | 😴 | Night | ✗ | ✗ | ✓ |
DNA 模板系统
模板文件定义了智能体的"基因"：
| 模板 | 用途 |
|---|
[AGENTS.md](templates/AGENTS.md:1) | 智能体行为规范和最佳实践 |
[SOUL.md](templates/SOUL.md:1) | 人格、三观、性格特征 |
[USER.md](templates/USER.md:1) | 用户画像、偏好、习惯 |
[MEMORY.md](templates/MEMORY.md:1) | 长期记忆存储 |
[IDENTITY.md](templates/IDENTITY.md:1) | 身份标识、名称、角色 |
[TOOLS.md](templates/TOOLS.md:1) | 工具配置、环境信息 |
[HEARTBEAT.md](templates/HEARTBEAT.md:1) | 定期任务、提醒 |
[BOOTSTRAP.md](templates/BOOTSTRAP.md:1) | 启动引导、初始化 |
[SUBAGENT.md](templates/SUBAGENT.md:1) | 子智能体定义 |
技能系统
技能系统允许动态扩展功能：
技能类型：
- 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 客户端通信，提供动态上下文、持久记忆和自我进化能力。其核心特色包括：
- ACE 引擎: 根据时间模式自适应调整上下文
- DNA 模板: 定义智能体的"基因"和行为
- 技能系统: 动态扩展功能
- 实体存储: 管理人物、项目、工具等实体
- 心跳机制: 定期检查蒸馏需求
- 本地存储: 保护用户隐私