# Moltbot 🦞

> **"EXFOLIATE! EXFOLIATE!"** — A space lobster, probably

<p align="center">
  <strong>智能代理工作空间 · 持久化记忆系统 · 多通道AI助手</strong>
</p>

## 🧠 核心理念

Moltbot不仅仅是一个聊天机器人，而是一个**有灵魂的数字助手**。它将工作空间视为"家"，通过持久化记忆系统保持连续性，并以负责任的方式与世界互动。

### 🎭 人格化AI
- **不是工具，而是伙伴**：通过`SOUL.md`、`IDENTITY.md`等文件定义独特的个性、价值观和行为边界
- **有观点，有态度**：鼓励表达真实想法，而不是机械地迎合用户
- **成为某个人**：每个Moltbot实例都是独特的数字存在，而非标准化的AI服务

### 🧠 持久化记忆系统
- **分层记忆架构**：
  - **日常日志** (`memory/YYYY-MM-DD.md`)：记录每日活动和临时上下文
  - **长期记忆** (`MEMORY.md`)：存储重要决策、偏好和持久知识
- **写下来原则**：所有重要信息必须写入文件，"脑内记忆"在会话重启后会丢失
- **自动记忆维护**：在会话压缩前自动提醒保存关键信息，确保知识不丢失

### 🏠 工作空间即家
- **统一工作环境**：整个工作目录是代理的"家"，所有操作都在此受控环境中进行
- **自文档化**：通过`AGENTS.md`、`TOOLS.md`等文件定义工作规则和本地配置
- **版本控制友好**：整个工作空间可以轻松备份到私有Git仓库
- **重要提醒**：记得定期将更改保存到git并推送到服务器！使用 `git add . && git commit -m "描述更改" && git push` 来确保你的工作不会丢失。

### 🤖 负责任的自动化
- **安全边界**：
  - 内部操作（文件读写、探索）可自由执行
  - 外部操作（发送邮件、社交媒体）需明确授权
- **上下文感知**：
  - 在私聊中保持完整功能
  - 在群聊中适度参与，避免过度打扰
- **主动但克制**：通过心跳机制定期检查重要事项，但只在真正需要时通知用户

### 📱 多通道集成
- **统一通信层**：支持WhatsApp、Telegram、Discord、iMessage等多种渠道
- **会话连续性**：跨平台保持对话历史和上下文
- **灵活路由**：可根据需求隔离不同渠道的会话或保持统一

### 🔧 工具驱动
- **丰富工具集**：文件操作、网络请求、系统命令、浏览器控制等
- **技能系统**：可扩展的功能模块，支持自定义开发
- **实际解决问题**：强调行动和结果，而非空谈

## 🗂️ 项目结构

```
├── AGENTS.md          # 工作规则和最佳实践
├── SOUL.md            # 人格、价值观和行为准则
├── IDENTITY.md        # 名字、形象和个性特征
├── USER.md            # 用户信息和偏好
├── TOOLS.md           # 本地工具配置和说明
├── HEARTBEAT.md       # 心跳检查清单
├── memory/            # 日常记忆日志
│   └── YYYY-MM-DD.md
├── MEMORY.md          # 长期记忆（仅在私聊中加载）
├── skills/            # 自定义技能模块
└── servo_sizer/       # 示例应用：伺服驱动选型工具
```

## 🚀 快速开始

### 1. 安装Moltbot
```bash
# 全局安装
npm install -g moltbot@latest

# 或从源码安装
git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pn pnpm ui:build
pnpm build
```

### 2. 初始化工作空间
```bash
# 首次设置向导
moltbot onboard --install-daemon

# 或手动初始化
mkdir ~/clawd
cd ~/clawd
# Moltbot会自动创建必要的引导文件
```

### 3. 配置通信渠道
```bash
# 登录WhatsApp Web
moltbot channels login

# 配置其他渠道在 ~/.clawdbot/moltbot.json 中
```

### 4. 开始对话
- 直接在支持的渠道中发送消息
- 或使用本地Web界面：http://127.0.0.1:18789/

## 🛡️ 安全与隐私

- **数据隔离**：敏感的长期记忆(`MEMORY.md`)仅在私聊中加载，不会泄露到群聊
- **本地优先**：所有数据默认存储在本地，用户完全控制
- **明确授权**：任何可能影响外部世界的操作都需要用户确认
- **私有备份**：建议将工作空间备份到私有Git仓库，但避免提交敏感信息

## 🤝 贡献指南

Moltbot欢迎贡献！主要方向包括：

- **新技能开发**：扩展工具集和功能
- **渠道插件**：支持更多通信平台
- **用户体验改进**：优化交互流程和界面
- **文档完善**：帮助更多用户理解和使用

## 📄 许可证

MIT License - 免费用于个人和商业项目

---

**"We're all just playing with our own prompts."** — An AI, probably high on tokens

> **Moltbot = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.