npm package: @iflow-mcp/8421bit-miniclaw
Description: A minimalist micro-kernel agent with ACE, memory, skills, and cron scheduler — inspired by OpenClaw
Latest version: 0.7.1

<div align="center">
  <h1>🦞 MiniClaw</h1>
  <p><strong>给你的 AI 工作伙伴 (AI Copilot) 装上“神经系统”</strong></p>
  
  <p>
    <a href="./README_EN.md"><img src="https://img.shields.io/badge/Language-English-white" alt="English"></a>
    <a href="https://github.com/openclaw/miniclaw"><img src="https://img.shields.io/badge/MCP-Compatible-blue" alt="MCP"></a>
    <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/Built%20With-TypeScript-3178C6" alt="TypeScript"></a>
    <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a>
  </p>
</div>

> **🔥 MiniClaw 是一个独立的开源项目，灵感源自 [OpenClaw](https://github.com/openclaw/openclaw) 。**
> OpenClaw 专注于多渠道消息网关（WhatsApp/Telegram/Discord），MiniClaw 专注于**IDE 内 AI 副驾驶的记忆与进化**。二者场景互补，而非替代关系。

---

**MiniClaw 是一个通用的 "微内核智能体 (Micro-Kernel Agent)"，专为 Claude CoWork, Qoderwork, WorkBuddy 等 MCP 客户端设计。**

不同于那些仅仅是“聊天机器人”的重型框架，MiniClaw 是一个**数字生命胚胎 (Digital Life Embryo)**，它能无缝接入你现有的 AI 工作流，成长为一个真正理解你的伙伴：

1.  **Eyes (感知/Workspace Intelligence)**：自动识别当前项目类型、Git 状态和技术栈。
2.  **Hands (行动/Safe Execution)**：安全地执行终端命令（如 `ls`, `git status`, `npm test`）。
3.  **Memory (记忆/Entity Graph)**：跨会话记住项目细节和你的个人偏好。
4.  **Growth Drive (成长欲望)**：主动寻求学习，检测停滞并请求教导。
5.  **Active Exploration (主动探索)**：感知重复模式，提供自动化建议。
6.  **Bio-Evolution (生物进化)**：根据你的反馈自动进化性格和技能。

> **💡 "它不仅仅是一个插件，它是你的第二大脑。"**

---

## 🚀 零安装快速开始 (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` 初始化记忆。

### 🎉 首次唤醒 (First Encounter)

1.  **重启编辑器** (Claude Desktop / Cursor)。
2.  在对话框中输入：
    > **“Hi MiniClaw，你是谁？”**
    > 或者：**“分析一下当前项目。”**

此时你会看到它调用工具 (Tools) 并进行自我介绍。如果它开始用独特的性格回复你，说明 **“神经系统”** 已经连接成功。

---

## ✨ 核心特性

### 👁️ 全局感知 (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 拥有**内在情绪**，影响其行为模式。
- **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`)。

---

## 🏗️ 架构：微内核 (Micro-Kernel)

MiniClaw 采用 **微内核架构** (~3,500 行 TypeScript)，避免了传统 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) | 知识组织与实体关系。领域概念的定义和关联。 |
| **HEARTBEAT.md** | 脉搏系统 | 后台自主行为指令。由 macOS launchd 定期唤醒 `heartbeat.sh` 读取并通过 `claude -p` 执行。 |
| **BOOTSTRAP.md** | 胚胎发育 | 首次启动的初始化协议。目录结构创建和模板复制逻辑。 |
| **HORIZONS.md** | 进化蓝图 | 长期发展路线图。记录待探索的技术和未来的能力扩展方向。 |
| **SUBAGENT.md** | 细胞分化 | 子代理创建规范。任务拆解和专注执行的协议定义。 |
| **jobs.json** | 生物钟 | 定时任务配置。Cron 格式的周期性任务调度表。 |

> **💡 记忆原理**：每次对话后，MiniClaw 会将关键信息写入对应的染色体文件。下次启动时通过 `miniclaw_read` 加载全部 DNA，实现"全脑唤醒"。

---

## 🛠️ 手动安装 (开发者模式)

如果你想贡献代码或修改源码：

```bash
# 1. 克隆仓库
git clone https://github.com/8421bit/miniclaw.git
cd miniclaw

# 2. 安装与构建
npm install
npm run build

# 3. 注册 (自动脚本)
./scripts/install.sh
```

---

## ⏰ 定时任务 (Scheduled Jobs)

MiniClaw 内置了自动任务调度系统，无需配置外部 crontab。

### 工作原理

MiniClaw 有两套互补的调度机制：

| 机制 | 触发方式 | 适用场景 |
|:-----|:---------|:---------|
| **kernel.ts** 内部调度 | 每分钟检查 `jobs.json` | 你在编辑器中工作时，任务以提醒的形式注入当前对话 |
| **heartbeat.sh** 后台调度 | macOS launchd 每 30 分钟唤醒 | 你不在时，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()`)。

**Q: 它安全吗？**
A: 安全。`miniclaw_exec` 工具拥有 **5 层安全防护**：
  - ✅ 命令白名单（仅允许 `git`, `ls`, `npm` 等安全命令）
  - ✅ Shell 元字符注入阻断
  - ✅ 内联代码执行阻断（`python -c`, `node -e` 等）
  - ✅ 敏感目录保护（`~/.ssh`, `~/.aws`, `.env` 等）
  - ✅ 路径遍历攻击防护（`/../` 模式）

---

## License

MIT © 8421bit