【深度解析】MiniClaw 项目分析报告 —— 微内核智能体的神经系统架构

# 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`](src/index.ts:1) - MCP 服务器入口 **主要职责：** - 初始化 MCP Server 实例 - 注册 Resources、Tools、Prompts 处理器 - 实现心跳调度器（每30分钟执行一次） - 管理 Legacy 状态（用于向后兼容） **关键组件：** ```mermaid 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`](src/kernel.ts:1) - 核心内核 **主要职责：** - 实现 ACE (Adaptive Context Engine) 自适应上下文引擎 - 管理技能系统（Skills） - 管理实体存储（Entity Store） - 处理上下文预算和优先级 - 实现时间模式感知 **关键组件：** ```mermaid 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`](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) 自适应上下文引擎 ```mermaid 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`](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) | 子智能体定义 | --- ### 技能系统 技能系统允许动态扩展功能： ```mermaid 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 ``` --- ## 依赖关系 ```mermaid 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`: 数据模式验证 --- ## 工作流程 ```mermaid 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/index.ts:1) 和 [`src/kernel.ts`](src/kernel.ts:1) 两个文件中。项目通过 MCP 协议与 AI 客户端通信，提供动态上下文、持久记忆和自我进化能力。其核心特色包括： 1. **ACE 引擎**: 根据时间模式自适应调整上下文 2. **DNA 模板**: 定义智能体的"基因"和行为 3. **技能系统**: 动态扩展功能 4. **实体存储**: 管理人物、项目、工具等实体 5. **心跳机制**: 定期检查蒸馏需求 6. **本地存储**: 保护用户隐私

# 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 协议实现 ```mermaid 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 字段 ```yaml --- 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** | <span class="mention-invalid">@modelcontextprotocol</span>/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 架构的优秀范例。