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 协议实现
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 是一个精心设计的微内核智能体系统，通过以下核心理念实现了简洁而强大的功能：
- 最小化核心 - Kernel 仅保留必要功能，通过技能系统扩展
- 可进化性 - DNA 模板系统使 Agent 能够自我学习和成长
- 智能上下文 - ACE 引擎动态调整上下文，优化 Token 使用
- 安全优先 - 严格的命令白名单和执行沙箱
- 零门槛 - 通过 npx 直接运行，无需复杂配置
这种架构设计使得 MiniClaw 既保持了极简的代码量，又提供了强大的扩展能力，是理解 AI Agent 架构的优秀范例。