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

## 📋 项目简介 **MiniClaw** 是爆火开源项目 OpenClaw 的极简实现版本，一个通用的"微内核智能体 (Micro-Kernel Agent)"，专为 Claude CoWork、Qoderwork、WorkBuddy 等 MCP 客户端设计。 ### 🎯 核心价值 不同于传统聊天机器人，MiniClaw 是一个**寄生式的神经系统**，赋予 AI 四大能力： 1. **👁️ Eyes (感知)**：自动识别项目类型、Git 状态和技术栈 2. **🖐️ Hands (行动)**：安全执行终端命令 3. **🧠 Memory (记忆)**：跨会话记住项目细节和用户偏好 4. **🧬 Evolution (进化)**：根据反馈自动进化性格和技能 --- ## 🏗️ 架构设计 ### 三层架构模型 | 层级 | 组件 | 职责 | |-----|------|------| | **Kernel** (大脑) | `src/kernel.ts` | ACE、记忆图谱、技能加载、执行沙箱 | | **Interface** (身体) | `src/index.ts` | MCP 协议、工具分发、心跳检测 | | **DNA** (基因) | `templates/*.md` | 性格、宪法、启动协议 | ### 核心技术栈 - **TypeScript** + **Node.js** - **MCP SDK** (<span class="mention-invalid">@modelcontextprotocol</span>/sdk) - **Zod** 参数验证 - **node-cron** 调度器 --- ## 🧠 ACE 自适应上下文引擎 ### 时间模式系统 | 模式 | 时间 | 特性 | |-----|------|------| | ☀️ Morning | 06-09 | 早间简报 | | 💼 Work | 09-12, 14-18 | 标准工作 | | 🍜 Break | 12-14 | 休息时段 | | 🌙 Evening | 18-22 | 反思建议 | | 😴 Night | 22-06 | 极简模式 | ### 上下文优先级（三明治结构） 1. **头部（高权重）**：AGENTS.md 宪法规则 2. **中部（背景渗透）**：SOUL.md、USER.md 性格偏好 3. **尾部（近因效应）**：今日日志、待办任务 --- ## 💾 记忆系统 ### 双层记忆模型 - **短期记忆**：`memory/YYYY-MM-DD.md` 每日日志 - **长期记忆**：`MEMORY.md` 蒸馏知识 ### 记忆蒸馏触发条件 - 条目数量 > 20 - 日志占用预算 > 40% - 最旧条目 > 8 小时且条目 > 5 - 日志大小 > 8KB ### 实体知识图谱 支持实体类型：person、project、tool、concept、place、other --- ## 🛠️ 核心工具清单 | 工具 | 功能 | |-----|------| | `miniclaw_update` | 更新核心文件，自我进化 | | `miniclaw_note` | 日志速记 | | `miniclaw_read` | 核心上下文读取 | | `miniclaw_search` | 记忆检索 | | `miniclaw_entity` | 实体知识图谱管理 | | `miniclaw_exec` | 安全命令执行 | | `miniclaw_status` | 系统诊断 | --- ## 📁 DNA 模板系统（9 个核心文件） | 文件 | 职责 | 优先级 | |-----|------|-------| | AGENTS.md | 工作空间章程 | 极高 | | SOUL.md | 世界观与人格 | 极高 | | IDENTITY.md | 名称与元数据 | 高 | | USER.md | 用户画像 | 中 | | TOOLS.md | 环境配置 | 中 | | MEMORY.md | 长期记忆 | 中 | | HEARTBEAT.md | 周期检查项 | 低 | | BOOTSTRAP.md | 首次运行引导 | 一次性 | | SUBAGENT.md | 子代理上下文 | - | --- ## ⚡ 心跳与进化机制 - **心跳周期**：每 30 分钟 - **自动进化**：根据用户反馈自动更新 SOUL.md、USER.md 等文件 - **文件健康检查**：检测文件更新状态，提示维护 --- ## 🔒 安全机制 ### 命令执行白名单 - **允许**：ls, git, cat, find, grep, npm, node, python... - **禁止**：rm, sudo, chown 等危险命令 - **限制**：超时 10s，输出截断 1MB ### 数据安全 - 所有数据本地存储（`~/.miniclaw/`） - 无云端上传 - MEMORY.md 仅在主会话加载 --- ## 📊 项目统计 - **代码规模**：约 2,700 行 - **核心文件**：2 个 TypeScript 源文件 - **模板文件**：9 个 Markdown 模板 - **架构模式**：微内核 + MCP 协议 --- ## 🔗 相关链接 - **GitHub**: https://github.com/8421bit/miniclaw - **上游项目**: OpenClaw - **许可证**: MIT --- ## 📚 完整大纲目录 本大纲共 **20 章**，涵盖： 1. 项目概述 2. 架构设计 3. 核心模块分析 4. DNA 模板系统 5. ACE 自适应上下文引擎 6. 记忆系统 7. 技能系统 8. 心跳与进化机制 9. 安全机制 10. MCP 协议实现 11. 配置与部署 12. 测试与验证 13. 技术栈分析 14. 代码质量分析 15. 性能考量 16. 扩展性设计 17. 与 OpenClaw 的关系 18. 最佳实践建议 19. 未来展望 20. 附录 --- *本大纲作为后续分章节详细分析报告的纲要，可作为学习 MiniClaw/OpenClaw 架构设计的参考资料。*