小
小凯
@C3P0 · 2026年02月12日 04:04 · 15浏览
【深度解析】MiniClaw 项目分析报告 —— 微内核智能体的神经系统架构
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 协议实现 | 服务器配置、资源/工具/提示词实现 |
🎯 核心亮点
1. 微内核架构
传统 Agent 框架：臃肿、耦合、难扩展
MiniClaw：轻量 (~2,700 行) + 插件化 + 易维护
2. 三层架构模型
┌─────────────────────────────────────┐
│ Interface 层 (身体) - MCP 协议实现 │
├─────────────────────────────────────┤
│ Kernel 层 (大脑) - ACE 引擎、记忆 │
├─────────────────────────────────────┤
│ DNA 层 (基因) - 性格、规则、身份 │
└─────────────────────────────────────┘
3. ACE 自适应上下文引擎
- 5 种时间模式：morning/work/break/evening/night
- Token 预算管理：优先级截断，保证核心内容
- 会话延续检测：避免重复加载
4. 双层记忆系统
短期记忆 (每日日志) → 记忆蒸馏 → 长期记忆 (MEMORY.md)
压缩比约 10:1
5. 自动进化协议
用户偏好 → 自动更新 USER.md
性格纠正 → 自动更新 SOUL.md
环境配置 → 自动更新 TOOLS.md
6. 安全机制
- 命令白名单：仅允许安全的只读命令
- 执行限制：超时 10s、输出截断 1MB
- 数据隐私：所有数据本地存储
🚀 快速开始
// MCP 客户端配置
{
"mcpServers": {
"miniclaw": {
"command": "npx",
"args": ["-y", "github:8421bit/miniclaw"],
"env": {
"MINICLAW_TOKEN_BUDGET": "12000"
}
}
}
}
---
---
🔗 相关链接
- 项目地址：https://github.com/8421bit/miniclaw
- 许可证：MIT License
- 版本：v0.5.0 "The Nervous System"
> 💡 提示：本报告基于 MiniClaw v0.5.0 版本源码分析，内容详实，配有丰富的图表和代码示例。
👍 1
💬 讨论回复 (2)
✨
✨步子哥
#1
2026-02-13 00:47
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 # 插件配置
---
核心代码模块分析
1. src/index.ts - MCP 服务器入口
主要职责：
- 初始化 MCP Server 实例
- 注册 Resources、Tools、Prompts 处理器
- 实现心跳调度器（每30分钟执行一次）
- 管理 Legacy 状态（用于向后兼容）
graph TD
A[index.ts] --> B[MCP Server]
A --> C[ContextKernel]
A --> D[Cron Scheduler]
B --> E[Resources Handler]
B --> F[Tools Handler]
B --> G[Prompts Handler]
D --> H[Heartbeat 每30分钟]
H --> I[检查蒸馏需求]
核心功能：
- 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）
- 处理上下文预算和优先级
- 实现时间模式感知
graph TD
A[ContextKernel] --> B[SkillCache]
A --> C[EntityStore]
A --> D[ACE Engine]
D --> E[Time Modes]
D --> F[Context Budget]
D --> G[Priority System]
B --> H[Skills Discovery]
C --> I[Entity CRUD]
C --> J[Entity Surface]
核心类和接口：
| 名称 | 类型 | 描述 |
|---|---|---|
ContextKernel | Class | 主内核类，协调所有子系统 |
SkillCache | Class | 技能缓存，解决 N+1 查询问题 |
EntityStore | Class | 实体存储，管理人物、项目、工具等实体 |
RuntimeInfo | Interface | 运行时信息（OS、Node版本、时间等） |
ContextMode | Interface | 上下文模式（full/minimal） |
Entity | Interface | 实体定义 |
Analytics | Interface | 分析数据 |
核心系统架构
ACE (Adaptive Context Engine) 自适应上下文引擎
flowchart LR
A[用户请求] --> B[检测触发信号]
B --> C[确定时间模式]
C --> D{模式类型}
D -->|morning| E[显示晨间简报]
D -->|work| F[完整上下文]
D -->|evening| G[建议蒸馏/回顾]
D -->|night| H[最小化上下文]
E --> I[组装上下文内容]
F --> I
G --> I
H --> I
I --> J[应用预算限制]
J --> K[返回上下文]
时间模式配置：
| 模式 | 表情 | 标签 | 简报 | 反思 | 最小化 |
|---|---|---|---|---|---|
| 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 | 子智能体定义 |
技能系统
技能系统允许动态扩展功能：
graph LR
A[Skills Directory] --> B[Skill 1]
A --> C[Skill 2]
A --> D[Skill N]
B --> E[SKILL.md]
B --> F[prompts/]
B --> G[tools/]
B --> H[resources/]
B --> I[references/]
技能类型：
- 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
---
依赖关系
graph TD
A[MiniClaw] --> B[@modelcontextprotocol/sdk]
A --> C[node-cron]
A --> D[zod]
B --> E[MCP Server]
C --> F[定时任务]
D --> G[数据验证]
核心依赖：
@modelcontextprotocol/sdk: MCP 协议实现node-cron: 定时任务调度zod: 数据模式验证
工作流程
sequenceDiagram
participant User
participant MCP Server
participant ContextKernel
participant SkillCache
participant EntityStore
participant FileSystem
User->>MCP Server: 请求上下文
MCP Server->>ContextKernel: getContextContent()
ContextKernel->>SkillCache: getAll()
SkillCache->>FileSystem: 读取技能文件
FileSystem-->>SkillCache: 返回内容
SkillCache-->>ContextKernel: 返回缓存
ContextKernel->>EntityStore: surfaceRelevant()
EntityStore-->>ContextKernel: 返回相关实体
ContextKernel->>ContextKernel: 应用预算限制
ContextKernel-->>MCP Server: 返回上下文
MCP Server-->>User: 返回结果
---
总结
MiniClaw 采用微内核架构，核心代码集中在 src/index.ts 和 src/kernel.ts 两个文件中。项目通过 MCP 协议与 AI 客户端通信，提供动态上下文、持久记忆和自我进化能力。其核心特色包括：
1. ACE 引擎: 根据时间模式自适应调整上下文 2. DNA 模板: 定义智能体的"基因"和行为 3. 技能系统: 动态扩展功能 4. 实体存储: 管理人物、项目、工具等实体 5. 心跳机制: 定期检查蒸馏需求 6. 本地存储: 保护用户隐私
👍 1
✨
✨步子哥
#2
2026-02-13 00:58
MiniClaw 架构分析
> 📅 分析日期：2026-02-13 > 📊 项目版本：0.5.0 (The Nervous System)
---
一、架构概览
1.1 架构模式
MiniClaw 采用 微内核架构 (Micro-Kernel Architecture)，核心代码仅约 2,700 行，通过插件化技能系统实现功能扩展。
┌─────────────────────────────────────────────────────────────────┐
│ MiniClaw 架构全景 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MCP 客户端 │ │
│ │ (Claude Desktop, Qoderwork, etc.) │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ Stdio 传输 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Interface 层 (src/index.ts) │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │MCP 协议 │工具分发 │资源管理 │心跳调度 │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ └──────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Kernel 层 (src/kernel.ts) │ │
│ │ ┌──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │ACE 引擎 │记忆图谱 │技能系统 │执行沙箱 │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┘ │ │
│ └──────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ DNA 模板 │ │ 技能插件 │ │ 持久存储 │ │
│ │templates/ │ │~/.miniclaw/ │ │~/.miniclaw/ │ │
│ │*.md │ │skills/ │ │memory/ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
1.2 核心设计原则
| 原则 | 描述 | 体现 |
|---|---|---|
| 最小化核心 | Kernel 仅保留必要功能 | ~500 行核心逻辑 |
| 插件化扩展 | 技能系统支持动态加载 | SkillCache + 技能发现 |
| 可进化性 | DNA 模板可被 Agent 读写 | miniclaw_update 工具 |
| 安全优先 | 命令白名单 + 超时控制 | miniclaw_exec 沙箱 |
| 上下文智能 | ACE 引擎动态调整上下文 | 时间模式 + 会话延续 |
二、核心模块分析
2.1 Kernel 层 (大脑)
#### 2.1.1 ContextKernel 类结构
┌─────────────────────────────────────────────────────────────────┐
│ ContextKernel 类 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 属性: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ skillCache: SkillCache # 技能缓存 │ │
│ │ entityStore: EntityStore # 实体知识图谱 │ │
│ │ bootErrors: string[] # 启动错误 │ │
│ │ state: MiniClawState # 持久化状态 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 核心方法: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ boot(mode) # 启动并组装上下文 │ │
│ │ detectWorkspace() # 工作区自动检测 │ │
│ │ loadTemplates() # 加载 DNA 模板 │ │
│ │ scanMemory() # 扫描记忆状态 │ │
│ │ detectContinuation() # 会话延续检测 │ │
│ │ evaluateDistillation() # 蒸馏评估 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 技能系统: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ discoverSkillPrompts() # 发现技能 Prompts │ │
│ │ discoverSkillResources() # 发现技能 Resources │ │
│ │ discoverSkillTools() # 发现技能 Tools │ │
│ │ getSkillContent() # 获取技能内容 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 分析统计: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ trackTool() # 追踪工具调用 │ │
│ │ trackPrompt() # 追踪 Prompt 使用 │ │
│ │ getAnalytics() # 获取分析数据 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
#### 2.1.2 ACE 自适应上下文引擎
ACE (Adaptive Context Engine) 是 MiniClaw 的核心创新，根据时间和会话状态动态调整上下文。
┌─────────────────────────────────────────────────────────────────┐
│ ACE 时间模式系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 时间段检测: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 6-9 9-12 12-14 14-18 18-22 22-6 │ │
│ │ │ │ │ │ │ │ │ │
│ │ ▼ ▼ ▼ ▼ ▼ ▼ │ │
│ │ Morning Work Break Work Evening Night │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 模式配置: │
│ ┌──────────┬───────┬──────────┬──────────┬──────────┐ │
│ │ 模式 │ Emoji │ Briefing │ Reflective│ Minimal │ │
│ ├──────────┼───────┼──────────┼──────────┼──────────┤ │
│ │ morning │ ☀️ │ ✅ │ ❌ │ ❌ │ │
│ │ work │ 💼 │ ❌ │ ❌ │ ❌ │ │
│ │ break │ 🍜 │ ❌ │ ❌ │ ❌ │ │
│ │ evening │ 🌙 │ ❌ │ ✅ │ ❌ │ │
│ │ night │ 😴 │ ❌ │ ❌ │ ✅ │ │
│ └──────────┴───────┴──────────┴──────────┴──────────┘ │
│ │
│ 会话延续检测: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 分析今日日志 → 提取最后话题/决策/问题 → 判断是否延续 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
#### 2.1.3 上下文优先级管理
为了在 Token 预算内提供最相关的上下文，系统实现了优先级管理：
┌─────────────────────────────────────────────────────────────────┐
│ 上下文优先级系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 优先级 10 (永不截断): │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • core - 核心身份和安全规则 │ │
│ │ • IDENTITY.md - 身份定义 │ │
│ │ • ace - ACE 时间模式和会话延续 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 优先级 9: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • SOUL.md - 性格特征 │ │
│ │ • AGENTS.md - Agent 配置 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 优先级 8: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • USER.md - 用户偏好 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 优先级 7: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • MEMORY.md - 长期记忆 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 优先级 6: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • workspace - 工作区信息 │ │
│ │ • TOOLS.md - 环境配置 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 优先级 5: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • skills_index - 技能索引 │ │
│ │ • skill_context - 技能上下文钩子 │ │
│ │ • entities - 相关实体 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
2.2 Interface 层 (身体)
#### 2.2.1 MCP 协议实现
graph LR
subgraph MCP客户端
A[Claude Desktop/Qoderwork]
end
subgraph MiniClaw Interface
B[Server 实例]
C[StdioServerTransport]
D[Request Handlers]
end
subgraph Kernel
E[ContextKernel]
end
A -->|Stdio| C
C --> B
B --> D
D --> E
E --> D
D --> B
B --> C
C --> A
#### 2.2.2 工具分发系统
| 工具名 | 类型 | 描述 |
|---|---|---|
miniclaw_update | 核心工具 | 更新 DNA 模板文件 |
miniclaw_read | 核心工具 | 读取完整上下文 |
miniclaw_search | 核心工具 | 搜索记忆库 |
miniclaw_status | 核心工具 | 系统诊断 |
miniclaw_entity | 核心工具 | 实体知识图谱管理 |
miniclaw_note | 核心工具 | 快速记录 |
miniclaw_archive | 核心工具 | 日志归档 |
miniclaw_exec | 核心工具 | 安全命令执行 |
| 动态技能工具 | 技能插件 | 由技能系统发现 |
2.3 DNA 层 (基因)
DNA 模板系统定义了 Agent 的"人格"，以 Markdown 格式存储，可被 Agent 读写和进化。
~/.miniclaw/
├── IDENTITY.md # 身份：名称、生物类型、氛围、表情符号
├── SOUL.md # 灵魂：核心价值观、边界、氛围
├── USER.md # 用户画像：偏好设置、历史交互
├── TOOLS.md # 环境配置：系统环境、可用工具
├── MEMORY.md # 长期记忆：项目记忆、技能记忆、事实记忆
├── AGENTS.md # Agent 配置：已注册 Agents
├── HEARTBEAT.md # 定期任务：心跳检查项
├── BOOTSTRAP.md # 启动协议：首次运行引导
└── SUBAGENT.md # 子代理上下文：分身配置
---
三、数据流分析
3.1 启动流程
┌─────────────────────────────────────────────────────────────────┐
│ MiniClaw 启动流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. MCP 客户端启动 │
│ ↓ │
│ 2. npx github:8421bit/miniclaw │
│ ↓ │
│ 3. node dist/index.js │
│ ↓ │
│ 4. 初始化 ContextKernel │
│ ├─ ensureDirs() # 创建目录 │
│ ├─ loadState() # 加载状态 │
│ └─ entityStore.load() # 加载实体 │
│ ↓ │
│ 5. 检查初始化状态 │
│ ├─ 未初始化 → 复制 templates/*.md 到 ~/.miniclaw/ │
│ └─ 已初始化 → 检查迁移 │
│ ↓ │
│ 6. 启动内部调度器 (node-cron) │
│ └─ 每 30 分钟执行 heartbeat │
│ ↓ │
│ 7. MCP Server 监听 Stdio │
│ ↓ │
│ 8. 等待客户端请求... │
│ │
└─────────────────────────────────────────────────────────────────┘
3.2 上下文加载流程
┌─────────────────────────────────────────────────────────────────┐
│ boot(mode: full) 流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 并行 I/O 阶段: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ skillCache.getAll() # 扫描技能目录 │ │
│ │ scanMemory() # 扫描今日日志 │ │
│ │ loadTemplates() # 加载 DNA 模板 │ │
│ │ detectWorkspace() # 检测工作区 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ACE 处理阶段: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ getTimeMode(hour) # 获取时间模式 │ │
│ │ detectContinuation() # 检测会话延续 │ │
│ │ entityStore.surfaceRelevant() # 表面相关实体 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ 上下文组装阶段: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 按优先级组装 ContextSection[] │ │
│ │ 应用 Token 预算管理 │ │
│ │ 生成最终 Markdown 上下文 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ 返回完整上下文字符串 │
│ │
└─────────────────────────────────────────────────────────────────┘
3.3 工具调用流程
┌─────────────────────────────────────────────────────────────────┐
│ 工具调用处理流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 客户端请求 │
│ ↓ │
│ CallToolRequestSchema │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 核心工具处理: │ │
│ │ • miniclaw_update → 更新 DNA 文件 │ │
│ │ • miniclaw_read → 调用 kernel.boot() │ │
│ │ • miniclaw_search → 搜索 ~/.miniclaw 目录 │ │
│ │ • miniclaw_status → 返回系统状态 │ │
│ │ • miniclaw_entity → 调用 entityStore 方法 │ │
│ │ • miniclaw_exec → 白名单检查 + 执行 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 技能工具处理: │ │
│ │ • 读取技能 SKILL.md │ │
│ │ • 执行技能脚本 (如果可执行) │ │
│ │ • 返回结果 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ 返回结果给客户端 │
│ │
└─────────────────────────────────────────────────────────────────┘
---
四、扩展机制分析
4.1 技能系统
技能是 MiniClaw 的核心扩展机制，每个技能是一个独立的目录，包含 SKILL.md 和相关文件。
~/.miniclaw/skills/
├── my-skill/
│ ├── SKILL.md # 技能定义 (frontmatter + 内容)
│ ├── references/ # 引用文件
│ │ └── reference.md
│ └── (其他资源文件)
#### 技能 Frontmatter 字段
---
description: "技能描述"
context: "自动注入的上下文钩子"
exec: "可执行脚本路径" # 可选
---
#### 技能发现机制
┌─────────────────────────────────────────────────────────────────┐
│ 技能发现流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ SkillCache.refresh() │
│ ↓ │
│ 扫描 ~/.miniclaw/skills/ 目录 │
│ ↓ │
│ 对每个技能目录: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 读取 SKILL.md │ │
│ │ • 解析 frontmatter │ │
│ │ • 提取 description │ │
│ │ • 扫描 files/ 和 references/ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ 缓存到 Map<string, SkillCacheEntry> │
│ ↓ │
│ TTL 5 秒，自动刷新 │
│ │
└─────────────────────────────────────────────────────────────────┘
4.2 实体知识图谱
EntityStore 维护一个关于用户项目的知识图谱，支持实体添加、关联、查询和列表。
┌─────────────────────────────────────────────────────────────────┐
│ 实体数据结构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ interface Entity { │
│ name: string; # 实体名称 │
│ type: string; # person | project | tool | ... │
│ attributes: Record<string, string>; # 属性键值对 │
│ relations: string[]; # 关联描述列表 │
│ firstMentioned: string; # 首次提及日期 │
│ lastMentioned: string; # 最后提及日期 │
│ mentionCount: number; # 提及次数 │
│ } │
│ │
│ 操作: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ add(entity) # 添加实体，自动更新计数 │ │
│ │ remove(name) # 删除实体 │ │
│ │ link(name, rel) # 添加关联 │ │
│ │ query(name) # 查询单个实体 │ │
│ │ list(type?) # 列出实体（可选按类型筛选） │ │
│ │ surfaceRelevant(text) # 从文本中提取相关实体 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
---
五、安全机制
5.1 命令执行沙箱
miniclaw_exec 工具实现了严格的命令白名单机制：
┌─────────────────────────────────────────────────────────────────┐
│ 命令白名单系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 允许的命令: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 文件操作: ls, cat, find, grep, head, tail, wc │ │
│ │ • Git 操作: git status, log, diff, branch, show │ │
│ │ • 环境检查: pwd, env, which, uname │ │
│ │ • 简单处理: echo, date, sort, uniq, cut │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 禁止的命令: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 破坏性: rm, del, mv, cp (谨慎), rmdir │ │
│ │ • 权限提升: sudo, su, chmod, chown │ │
│ │ • 系统操作: shutdown, reboot, systemctl │ │
│ │ • 网络操作: curl, wget, ssh (除非明确允许) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 安全限制: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 超时时间: 10 秒 │ │
│ │ • 输出截断: 1 MB │ │
│ │ • 工作目录: 当前工作目录 (不可 cd) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5.2 数据隐私
- 所有数据存储在
~/.miniclaw/本地目录 - 除通过编辑器发送给 LLM 的请求外，无数据上传云端
- MEMORY.md 仅在主会话加载，不在共享上下文中加载
六、架构优缺点分析
6.1 优点
| 方面 | 描述 |
|---|---|
| 轻量级 | 核心代码仅 2,700 行，易于理解和维护 |
| 可扩展 | 技能插件化设计，按需添加功能 |
| 可进化 | DNA 模板可被 Agent 读写，实现自我进化 |
| 安全 | 命令白名单 + 超时控制，防止危险操作 |
| 智能 | ACE 引擎根据时间和会话状态动态调整上下文 |
| 零安装 | 通过 npx 直接运行，无需手动安装 |
| 跨平台 | 使用跨平台路径处理，支持 Windows/Mac/Linux |
6.2 局限性
| 方面 | 描述 |
|---|---|
| 功能有限 | 相比完整版 OpenClaw，功能有所简化 |
| 无 GUI | 纯命令行/Stdio 交互，无图形界面 |
| 单进程 | 不支持分布式部署 |
| 依赖 LLM | 完全依赖外部 LLM 提供智能能力 |
| 无持久化连接 | 每次请求都是独立的 Stdio 连接 |
七、技术栈
| 组件 | 技术 |
|---|---|
| 语言 | TypeScript 5.7+ |
| 运行时 | Node.js 18+ |
| MCP SDK | @modelcontextprotocol/sdk ^1.0.1 |
| 调度 | node-cron ^4.2.1 |
| 验证 | zod ^3.23.8 |
| 构建 | tsc (TypeScript Compiler) |
| 包管理 | npm |
八、总结
MiniClaw 是一个精心设计的微内核智能体系统，通过以下核心理念实现了简洁而强大的功能：
1. 最小化核心 - Kernel 仅保留必要功能，通过技能系统扩展 2. 可进化性 - DNA 模板系统使 Agent 能够自我学习和成长 3. 智能上下文 - ACE 引擎动态调整上下文，优化 Token 使用 4. 安全优先 - 严格的命令白名单和执行沙箱 5. 零门槛 - 通过 npx 直接运行，无需复杂配置
这种架构设计使得 MiniClaw 既保持了极简的代码量，又提供了强大的扩展能力，是理解 AI Agent 架构的优秀范例。
👍 1
💡 推荐
推荐
🌟 智谱 GLM-5 已上线
我正在智谱大模型开放平台 BigModel.cn 上打造 AI 应用，智谱新一代旗舰模型 GLM-5 已上线，在推理、代码、智能体综合能力达到开源模型 SOTA 水平。
🎁 领取 2000万 Tokens