NanoClaw 源码解析(极简版)

NanoClaw 是轻量级、容器隔离、AI 原生的个人 Claude 助手，基于 TypeScript + Node.js 实现，仅 12 个文件、约 4000 行代码。核心是：宿主机派单 + 容器安全执行 + AI 原生扩展。

一、整体架构（一句话）

宿主机（单 Node.js 进程）接收 WhatsApp 消息 → 存入 SQLite → 按群组派单到隔离容器 → 容器内运行 Claude Agent → 结果回传。

二、目录结构（核心）
nanoclaw/
├── src/ # 宿主机核心（9 个 TS）
│ ├── index.ts # 主入口：消息循环、容器调度、IPC
│ ├── container-runner.ts # 容器启动/挂载/安全
│ ├── db.ts # SQLite 消息/任务存储
│ ├── task-scheduler.ts # 定时任务
│ └── mount-security.ts # 挂载安全校验
├── container/ # 容器镜像与 Agent
│ └── agent-runner/ # 容器内执行：Claude SDK、IPC
└── groups/ # 按群组隔离：CLAUDE.md、日志、会话
三、核心模块详解

1. 主入口：src/index.ts（指挥中心）

• 消息循环：轮询 SQLite，按群组分发，至少一次交付（成功才更新时间戳）

• 容器调度：热容器复用、冷启动按需创建，按群组隔离

• IPC 监控：监听容器文件 IPC，处理发消息、定时任务等跨边界操作

2. 容器运行器：src/container-runner.ts（安全核心）

• OS 级隔离：Apple Container / Docker，文件/网络/进程三重隔离

• 挂载控制：主群组读写、普通群组只读，禁止 .ssh/.env 等敏感路径

• 凭证过滤：仅暴露必要环境变量，密钥不进容器

3. 数据层：src/db.ts（真相唯一来源）

• 表：messages（消息）、scheduled_tasks（定时）、chats（群组）

• 游标机制：lastTimestamp/lastAgentTimestamp 实现断点续传、故障恢复

• 用 better-sqlite3 同步操作，零依赖、极简

4. Skills Engine（灵魂：AI 原生扩展）

• 技能即代码修改：通过 applySkill() 自动合并代码，而非传统插件

• 三路合并：Base/Current/Skill 用 git merge-file 安全合并

• 事务生命周期：版本检查 → 加锁 → 备份 → 合并 → 测试 → 回滚/提交

• Intent 文件：自然语言描述修改意图，让 AI 解决冲突

5. 容器内 Agent：container/agent-runner/src/index.ts

• 接收 prompt → 调用 Claude → 工具调用（bash/读写/搜索）→ 结果回传

• 会话归档、内部思考标签 <internal> 过滤

四、关键设计亮点

• 安全第一：容器隔离 + 挂载校验 + IPC 授权，纵深防御

• 极简主义：单进程、无 MQ、无 ORM、无框架，代码即配置

• AI 原生：用 Claude Code 安装/调试/扩展，无需复杂界面

• 按群隔离：每个群组独立容器、记忆、文件系统，互不干扰

五、技术栈

• 运行时：Node.js 20+、TypeScript 5.x

• 通信：Baileys（WhatsApp）、文件 IPC

• 存储：better-sqlite3

• 隔离：Apple Container / Docker

• AI：Anthropic Claude Agent SDK

六、核心流程（消息处理）

1. WhatsApp 消息 → 存入 SQLite

2. 消息循环检测到新消息 → 按群组路由

3. 启动/复用容器 → 挂载群组目录

4. 容器内 Agent 处理 → 工具执行 → 结果返回

5. 结果发回 WhatsApp → 更新状态

七、扩展方式（Skills）

1. 编写 SKILL.md + modify/ + intent.md

2. 运行 apply-skill.ts → 自动合并代码、安装依赖、测试

3. 失败自动回滚，成功写入状态