🔥 MiniClaw 是一个独立的开源项目，灵感源自 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 客户端的配置文件中：

{
  "mcpServers": {
    "miniclaw": {
      "command": "npx",
      "args": [
        "-y",
        "github:8421bit/miniclaw"
      ],
      "env": {
        "MINICLAW_TOKEN_BUDGET": "12000"
      }
    }
  }
}

前提条件：你的电脑必须安装了 Node.js (v18+)。

初次运行时，MiniClaw 会自动下载最新版，在 ~/.miniclaw 初始化记忆。

🌙 可选：启用潜意识守护进程 (仅 macOS)

如果你希望即使用户关闭了代码编辑器，MiniClaw 也能在深夜自动帮你复盘和整理记忆，你需要额外执行一行命令来安装后台驻留脚本（如果你是使用上述 npx 零安装的方法，你本地没有脚本文件，可以直接通过以下命令将其下载至 ~/.miniclaw 并执行）：

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 项目”。 启动瞬间，它会扫描目录并注入上下文：

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)。

# 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，或在对话中请求：

"帮我添加一个定时任务：每天早上9点提醒我检查邮件"
→ Agent 会更新 jobs.json

jobs.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