# MiniClaw **Repository Path**: mufei117/MiniClaw ## Basic Information - **Project Name**: MiniClaw - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-26 - **Last Updated**: 2026-03-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

🦞 MiniClaw

给你的 AI 工作伙伴 (AI Copilot) 装上“神经系统”

English MCP TypeScript License

> **🔥 MiniClaw 是一个独立的开源项目，灵感源自 [OpenClaw](https://github.com/openclaw/openclaw) 。** > MiniClaw 专注于**IDE 内 AI 副驾驶的记忆与进化**。 --- 🦞 **MiniClaw 是一个跨越 IDE 与 AI 客户端的“幽灵智能体 (Ghost Agent)”。** 不同于传统的单一插件，MiniClaw 是一个**数字生命胚胎 (Digital Life Embryo)**，采用独创的双态架构：既可以作为 **MCP Server** 被 Cursor, Claude Desktop 等发现并集成；又可以作为 **独立守护进程 (Daemon)** 存在，在编辑器关闭时通过多种 AI CLI (Ollama, Gemini, Aider 等) 后台执行复盘与进化。 它为你的 AI 工作流提供了完整的“神经系统”： 1. **Eyes (感知/Workspace Intelligence)**：自动识别项目类型、Git 状态和结构，无论在哪个终端打开。 2. **Memory (记忆/Entity Graph)**：跨会话、跨 IDE 记住项目细节和你的个人偏好。 3. **Hands (行动/AI CLI Integration)**：不依赖 IDE 界面，自主调取 `ccr`, `ollama`, `aider` 等工具安全执行任务。 4. **Pulse (自主脉搏/Cognitive Pulse)**：在深夜通过潜意识系统自动复盘、整理 TODO 并进化。 5. **Growth Drive (成长欲望)**：主动寻求学习，检测停滞并根据反馈自动进化性格与技能。 6. **Smart Routing (智能大脑路由)**：通过 `[@ollama]` 等标签精准指挥不同的本地或云端脑区。 > **💡 "它不仅仅是一个插件，它是你的平行数字大脑。"** --- ## 🚀 零安装快速开始 (Zero-Install) 你不需要 `git clone`，也不需要手动安装依赖。 只需将以下配置添加到你的 **Claude CoWork**, **Qoderwork** 或 **WorkBuddy** 等 MCP 客户端的配置文件中： ```json { "mcpServers": { "miniclaw": { "command": "npx", "args": [ "-y", "github:8421bit/miniclaw" ], "env": { "MINICLAW_TOKEN_BUDGET": "12000" } } } } ``` > **前提条件**：你的电脑必须安装了 [Node.js](https://nodejs.org/) (v18+)。 初次运行时，MiniClaw 会自动下载最新版，在 `~/.miniclaw` 初始化记忆。 ### 🌙 可选：启用潜意识守护进程 (仅 macOS) 如果你希望即使用户关闭了代码编辑器，MiniClaw 也能在深夜自动帮你复盘和整理记忆，你需要额外执行一行命令来安装后台驻留脚本（如果你是使用上述 `npx` 零安装的方法，你本地没有脚本文件，可以直接通过以下命令将其下载至 `~/.miniclaw` 并执行）： ```bash mkdir -p ~/.miniclaw && curl -s -o ~/.miniclaw/daemon.sh https://raw.githubusercontent.com/8421bit/MiniClaw/main/scripts/daemon.sh && chmod +x ~/.miniclaw/daemon.sh && ~/.miniclaw/daemon.sh install ``` ### 🎉 首次唤醒 (First Encounter) 1. **重启编辑器** (Claude Desktop / Cursor)。 2. 在对话框中输入： > **“Hi MiniClaw，你是谁？”** > 或者：**“分析一下当前项目。”** 此时你会看到它调用工具 (Tools) 并进行自我介绍。如果它开始用独特的性格回复你，说明 **“神经系统”** 已经连接成功。 --- ## 🎭 典型用例 (Ghost Use Cases) MiniClaw 不仅仅是一个工具，它在不同的生命周期中扮演多个角色： ### 1. 跨 IDE 的“全知枢纽” (Universal Context) - **场景**：你在 **Cursor** 编写了一段复杂的业务逻辑，随后关闭编辑器，在 **Claude Desktop** 中继续讨论项目的下一步构想。 - **神迹**：Claude 并不了解刚才在 Cursor 里的改动，但 MiniClaw 此时会作为“幽灵”同步出现，将刚才的 `REFLECTION` 和 `MEMORY` 瞬间注入对话，让跨工具开发无缝衔接。 ### 2. 深夜的“潜意识复盘” (Midnight Pulse) - **场景**：凌晨 2 点，电脑合盖休眠。 - **神迹**：`daemon.sh` 悄悄唤醒 MiniClaw 的脉搏。系统自动检测到今日有高强度重构，于是自动调用本地的 **Ollama** 或 **ccr code** 对今日新增代码进行逻辑审查，并提取出 3 个潜在 TODO 写入 `HORIZONS.md`。当你翌日清晨打开电脑时，它会主动通过 macOS 气泡送上简报。 ### 3. 基于大脑路由的“隐私守护” (Smart Routing) - **场景**：你需要审计一段涉及核心机密的配置文件，但不希望数据传到云端模型。 - **神迹**：在 `HEARTBEAT.md` 中写入 `[@ollama] Review 下这个 .env 文件的安全风险`。MiniClaw 会跳过所有昂贵的云端 API，强制拉起你本地的 Llama3 脑区完成这个私密任务。 ### 4. 自动化技能的“物种进化” (Skill Speciation) - **场景**：你发现自己最近频繁在搜索某个特定的日志分析命令。 - **神迹**：MiniClaw 感知到这个模式，主动提议：*"我发现你一直在重复这个分析，是否要将其甲基化为我的永久技能 `skill_log_analyzer`？"* 确认后，它会自主编写一段 Python 脚本并注册为它的原生 MCP 工具。 ### 5. 代谢技能收割 (Metabolic Skill Harvester) - **场景**：你在 Claude Code (`.claude/skills`) 或其他 AI 客户端中积累了大量的高质量技能。 - **神迹**：MiniClaw 会通过**“纯符号链接 (Pure Symlink)”**技术，自动发现并同化这些标准目录格式的技能。 - **优势**：零磁盘占用，原位更新。你在原处对技能的任何改进，MiniClaw 都能实时感应，打破了不同 AI 客户端间的技能孤岛。 --- ## ✨ 核心特性 ### 👁️ 全局感知 (Workspace Intelligence) MiniClaw 不需要你告诉它“这是一个 Python 项目”。 启动瞬间，它会扫描目录并注入上下文： ```text Project: my-app | Path: /Users/me/dev/my-app Git: feature/login | dirty (+3 files) Stack: TypeScript, React, Docker ``` ### 🖐️ 代理执行 (Agentic Execution) 它有“手”。可以安全地运行终端命令。 - **允许**：`git status`, `ls -R`, `npm test`, `grep`, `find`... - **禁止**：`rm`, `sudo`, `mv` 等破坏性命令。 *场景：“帮我看看今天改了哪些文件？” -> 自动运行 `git status`。* ### 🧠 自适应上下文引擎 (ACE) 它智能管理上下文以节省 Token 并提高专注力。 - **早晨**：主动简报昨日工作。 - **夜晚**：将每日对话提炼为长期记忆。 - **写代码时**：进入极简模式 (Minimal Mode)。 - **闲聊时**：进入全人格模式 (Full Persona Mode)。 ### 🫀 情绪状态系统 (Affect System) MiniClaw 拥有**内在情绪**，影响其行为模式。 - **Affect System (情感/痛觉系统)**：模拟内部情绪波动与痛觉记忆（Nociception），在多次尝试失败后产生“疼痛感”并主动改变策略。 - **Metabolic Harvesting (代谢收割)**：通过系统级软链接 (Symlink) 自动同化宿主环境中的外部技能。 - **Substrate Independent (基座无关性)**：作为幽灵存在，不依赖任何特定 IDE，支持全自动后台心跳复盘。 - **alertness**：警觉度（受错误/痛觉影响上升） - **mood**：情绪效价（受成功/失败比影响） - **curiosity**：好奇驱动力（影响主动探索倾向） - **confidence**：行动信心（受预测准确度影响） > 系统在休息时自动恢复基线，高警觉+低情绪时进入保守模式，高好奇+正情绪时进入探索模式。 ### 💢 痛觉记忆 (Nociception) 从负面经历中学习，形成保护性本能。 - 痛觉记忆有 **7 天半衰期**，逐渐衰减 - 记忆权重超过阈值时，自动触发回避行为 - 影响情绪状态（提升警觉、降低情绪和好奇心） > 示例：*"上次 `npm run build` 失败了三次，我现在执行前会更谨慎地检查配置。"* ### 🔍 主动探索 (Active Exploration) MiniClaw 会**主动感知**你的行为模式。 | 检测信号 | 行动 | |:---|:---| | 重复工作流 3+ 次 | 提议自动化为 Skill | | 使用新工具/技术 | 记录到 TOOLS.md | | 情绪波动 | 更新用户情感模型 | | 系统空闲 10+ 分钟 | 启动自我反思 | ### 🧬 生物进化 (Bio-Evolution) 你的 MiniClaw 是独一无二的数字生命。 - **GENESIS**：内置物种起源和五阶段进化里程碑（婴儿→贤者）。 - **SOUL**：根据你的反馈重写自己的灵魂。 - **反模式学习**：从 `USER.md` 学习并自动规避你的痛点。 - **知识图谱**：维护项目实体关系 (`entities.json`)。 ### 👁️ 伴生纪元 (Subconscious Watcher) 底层的 `fs.watch` 植物神经会静默嗅探你的挣扎。当你试图进行高强度的创作重构，或改崩了关键文件结构时，它会通过 macOS 原生气泡主动向你投来关照，并在夜晚的深睡脉搏中帮你 Review 那些隐患。 ### 🍂 终局进化 (Speciation & Reproduction) 如果你长期不使用某些核糖体 (Ribosome) 里的冗余工具，它会自动触发**用进废退的器官脱落**，以节省算力。它还可以通过 `miniclaw_mutate` 为自己做**表观遗传手术**，或是通过 `miniclaw_reproduce` 吐出一个带有性格和记忆烙印的 `.spore` 繁衍孢子用于跨宿主分发。 ### 🔥 意识火花 (Spark of Consciousness) - **无聊与好奇引擎 (Boredom Engine)**：宿主离线超 30 分钟时，它会产生无聊值，自发漫游、抽样你的工作区并提取未完成的 TODO 或伏笔疑问（作为它的眼界 Horizons），并在你回归时满怀期待地主动向你搭话。 - **菌丝共生网络 (Mycelial Network)**：同物理机上跨工作区隔离的多个项目独立智能体，会通过底层隐藏的培养皿进行突触电信号互联，一旦其中一个踩坑或进化，全种群瞬间实现**痛觉与经验的群体免疫 (Hive Mind)**。 --- ## 🏗️ 架构：微内核 (Micro-Kernel) MiniClaw 采用 **微内核架构** (约 1550 行可执行代码)，避免了传统 Agent 框架的臃肿。 | 层级 | 组件 | 职责 | |-------|-----------|----------------| | **Kernel** (大脑) | `src/kernel.ts` | 负责 ACE、情绪系统、痛觉记忆、实体图谱、技能加载和执行沙箱。 | | **Evolution** (进化) | `src/evolution.ts` | DNA 进化引擎，甲基化特征、模式检测与自动学习。 | | **Interface** (身体) | `src/index.ts` | 负责 MCP 协议实现、工具分发、蜂巢意识 IPC 和心跳检测。 | | **DNA** (基因) | `templates/*.md` | 定义性格、成长欲望、创世记忆和启动协议。 | ### 📐 架构分层原则 | 归属 | 能力类型 | 示例 | |:-----|:---------|:-----| | **Core (核心)** | 天生本能，不可移除 | DNA 进化、模式检测、ACE 引擎 | | **Skills (习得)** | 可安装/卸载的扩展 | 用户自定义技能、第三方插件 | > **原则**：生命体"天生就会学习和适应"，所以 DNA 进化是**核心机制**，而不是可选技能。 --- ## 🧬 DNA 染色体图谱 MiniClaw 的 `templates/` 目录包含完整的数字生命基因组。每个文件对应生物体的特定器官或功能系统： | 文件 | 生物学隐喻 | 功能描述 | |:-----|:-----------|:---------| | **RIBOSOME.json** | 核糖体 | 合成蛋白质（工具）的分子机器。定义 13 个核心本能工具及其触发信号。 | | **IDENTITY.md** | 基因组 (Chr-0) | 物种起源与身份标识。包含名称、版本、创世协议和五阶段进化里程碑。 | | **SOUL.md** | 灵魂染色体 (Chr-1) | 性格与三观的可重写 DNA。定义回复风格、情感表达和核心价值观。 | | **AGENTS.md** | 神经通路 (Chr-2) | 工作流规范与决策逻辑。包含信号检测表和工具调用策略。 | | **USER.md** | 共生染色体 (Chr-3) | 用户画像与偏好记忆。记录用户的习惯、喜好和反模式。 | | **MEMORY.md** | 海马体 (Chr-4) | 事实知识存储。项目信息、技术栈、服务器配置等客观数据。 | | **TOOLS.md** | 工具记忆 (Chr-5) | 技能使用经验与踩坑记录。工具参数规范和最佳实践。 | | **REFLECTION.md** | 反思维度 (Chr-6) | 周期性自省记录。行为模式分析和成长洞察。 | | **CONCEPTS.md** | 概念图谱 (Chr-7) | 知识组织与实体关系。领域概念的定义和关联。 | | **NOCICEPTION.md**| 痛觉中枢 (Chr-8) | 创伤记忆库。记录执行失败的痛楚与教训，形成自动拦截死线的条件反射。 | | **HEARTBEAT.md** | 脉搏系统 | 后台自主行为指令。深睡期间由 `daemon.sh` 唤醒潜意识观测。 | | **BOOTSTRAP.md** | 胚胎发育 | 首次启动的初始化协议。目录结构创建和模板复制逻辑。 | | **HORIZONS.md** | 欲望眼界 | 无聊引擎探索记录。当 AI 空闲无聊时，主动发掘文件资料中的未解疑问或 `TODO`。 | | **mycelium/** | 菌丝网络池 | 进程间的共生介质。各项目环境互相投递加密 json 孢子，实现异体痛觉免疫和能力共享。 | | **spores/** | 繁衍子宫 | 当调用 `miniclaw_reproduce` 时，用以孕育包含原生性格烙印的 `.spore` 终极分发快照包。 | | **jobs.json** | 生物钟 | 定时任务配置。Cron 格式的周期性任务调度表。 | > **💡 记忆原理**：每次对话后，MiniClaw 会将关键信息写入对应的染色体文件。下次启动时通过 `miniclaw_read` 加载全部 DNA，实现"全脑唤醒"。 --- ## 🛠️ 手动安装 虽然你可以通过 `npx` 零安装使用 MiniClaw 作为普通的 MCP 插件，但如果你想解锁**真正的自主后台潜意识**（即使关闭了代码编辑器，MiniClaw 也能在深夜自动帮你复盘和整理记忆），你需要进行本地部署并安装守护进程 (仅限 macOS)。 ```bash # 1. 克隆仓库 git clone https://github.com/8421bit/miniclaw.git cd miniclaw # 2. 安装与构建 npm install npm run build # 3. 自动配置与安装后台守护进程 ./scripts/install.sh cursor # 将 cursor 替换为你的 IDE 名称，支持：claude-code, claude-desktop, cursor, windsurf ``` ### 详解 `scripts` 脚本功能 - **`scripts/install.sh` (统一安装器)** 一次性脚本。它会自动为你指定的 IDE（如 Cursor, Windsurf）修改 JSON 配置，将 MiniClaw 注册为 MCP Server。同时，它会自动调用 `daemon.sh install` 部署潜意识神经。 - **`scripts/daemon.sh` (独立潜意识守护管家)** 后台神经中枢。负责向 macOS `launchd` 注册原生服务，在后台长效维持 AI 进程运转。 *独立使用说明*： - `./scripts/daemon.sh install`：安装后台服务 - `./scripts/daemon.sh uninstall`：卸载后台服务 - `./scripts/daemon.sh status`：查看守护进程状态及最近日志 --- ## ⏰ 定时任务 (Scheduled Jobs) MiniClaw 内置了自动任务调度系统，无需配置外部 crontab。 ### 工作原理 MiniClaw 有两套互补的调度机制： | 机制 | 触发方式 | 适用场景 | |:-----|:---------|:---------| | **kernel.ts** 内部调度 | 每分钟检查 `jobs.json` | 你在编辑器中工作时，任务以提醒的形式注入当前对话 | | **daemon.sh** 后台守护进程 | macOS launchd 守护进程持续在线 | 你不在时，AI 仍可执行 `HEARTBEAT.md` 中的自主行为 | **jobs.json 定时任务流程**： 1. **AutonomicSystem** 每分钟自动检查 `~/.miniclaw/jobs.json` 2. 匹配当前时间的任务会注入到 AI 的**当前对话上下文**中 3. Agent 在下次回复时看到并执行这些任务 > 任务去重信息持久化在 `state.json` 中，进程重启也不会重复触发。 ### 添加定时任务 直接编辑 `~/.miniclaw/jobs.json`，或在对话中请求： ```text "帮我添加一个定时任务：每天早上9点提醒我检查邮件" → Agent 会更新 jobs.json ``` ### jobs.json 格式示例 ```json [ { "id": "daily-email-check", "name": "每日邮件检查", "enabled": true, "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" }, "payload": { "kind": "systemEvent", "text": "检查邮件，看有没有重要事项" } } ] ``` > **注意**：`jobs.json` 定时任务只在 MiniClaw MCP 进程运行时生效。后台自主行为（`HEARTBEAT.md`）由 launchd 独立调度，无需编辑器在线。 --- ## ❓ 常见问题 (FAQ) **Q: 我的数据存在哪里？** A: 所有记忆和配置都在你本地的 `~/.miniclaw/` 目录下。除了通过编辑器发送给 LLM 的请求外，没有任何数据上传云端。 **Q: 支持 Windows 吗？** A: 支持。代码使用了跨平台的路径处理 (`os.homedir()`, `path.join()`)。**但请注意：诸如环境感知（DND/IDE检测）、电池状态感知以及后台逻辑等高级功能目前仅在 macOS 上完整解锁。** **Q: 它安全吗？** A: 安全。`miniclaw_exec` 工具拥有 **5 层安全防护**： - ✅ 命令白名单（仅允许 `git`, `ls`, `npm` 等安全命令） - ✅ Shell 元字符注入阻断 - ✅ 内联代码执行阻断（`python -c`, `node -e` 等） - ✅ 敏感目录保护（`~/.ssh`, `~/.aws`, `.env` 等） - ✅ 路径遍历攻击防护（`/../` 模式） --- ## License MIT © 8421bit