188 lines
7.6 KiB
Markdown
188 lines
7.6 KiB
Markdown
# NanoClaw 需求
|
||
|
||
项目创建者的原始需求和设计决策。
|
||
|
||
---
|
||
|
||
## 为什么存在这个项目
|
||
|
||
这是 OpenClaw（原名 ClawBot）的轻量、安全的替代方案。那个项目变得臃肿至极——4 到 5 个不同的进程运行不同的网关，无穷无尽的配置文件，无穷无尽的集成。它是一个安全噩梦，agent 不在隔离的进程中运行；有各种漏洞百出的变通方案试图阻止它们访问不应访问的系统部分。任何人都不可能真正理解整个代码库。运行它基本上就是在赌运气。
|
||
|
||
NanoClaw 为您提供核心功能，没有那些混乱。
|
||
|
||
---
|
||
|
||
## 理念
|
||
|
||
### 小到可以读懂
|
||
|
||
整个代码库应该是您可以阅读和理解的东西。一个 Node.js 进程。少量源文件。没有微服务，没有消息队列，没有抽象层。
|
||
|
||
### 通过真正的隔离实现安全
|
||
|
||
不是通过应用级权限系统试图阻止 agent 访问东西，agent 运行在实际的 Linux 容器中。隔离在操作系统层面。Agent 只能看到显式挂载的内容。Bash 访问是安全的，因为命令在容器内运行，而不是在您的 Mac 上。
|
||
|
||
### 为个人用户构建
|
||
|
||
这不是一个框架或平台。它是为每个用户量身定制的软件。您 fork 仓库，添加您想要的渠道（WhatsApp、Telegram、Discord、Slack、Gmail），最终得到做您所需事情的干净代码。
|
||
|
||
### 定制 = 代码修改
|
||
|
||
没有配置膨胀。如果您想要不同的行为，修改代码。代码库足够小，这样做既安全又实用。极小部分内容如触发词在配置中。其他一切——只需修改代码做您想做的事。
|
||
|
||
### AI 原生开发
|
||
|
||
我不需要安装向导——Claude Code 引导设置。我不需要监控仪表板——我问 Claude Code 发生了什么。我不需要精心设计的日志 UI——我让 Claude 读日志。我不需要调试工具——我描述问题，Claude 修复它。
|
||
|
||
代码库假设您有一个 AI 协作者。它不需要过度自文档化或自调试，因为 Claude 始终在那里。
|
||
|
||
### Skills 优先于功能
|
||
|
||
当人们贡献时，他们不应该在支持 WhatsApp 的同时再添加"Telegram 支持"。他们应该贡献一个 skill，如 `/add-telegram`，来改造代码库。用户 fork 仓库，运行 skills 进行定制，最终得到做他们所需事情的干净代码——而不是一个试图同时支持每个人用例的臃肿系统。
|
||
|
||
---
|
||
|
||
## RFS（Request for Skills）
|
||
|
||
我们希望看到贡献的 skills：
|
||
|
||
### 通信渠道
|
||
- `/add-signal` - 添加 Signal 作为渠道
|
||
- `/add-matrix` - 添加 Matrix 集成
|
||
|
||
> **注意：** Telegram、Slack、Discord、Gmail 和 Apple Container 的 skills 已经存在。完整列表请参见 [skills 文档](https://docs.nanoclaw.dev/integrations/skills-system)。
|
||
|
||
---
|
||
|
||
## 愿景
|
||
|
||
一个可通过消息访问的个人 Claude 助手，使用最少的自定义代码。
|
||
|
||
**核心组件：**
|
||
- **Claude Agent SDK** 作为核心 agent
|
||
- **容器（Containers）** 用于隔离的 agent 执行（Linux VM）
|
||
- **多渠道消息**（WhatsApp、Telegram、Discord、Slack、Gmail）——仅添加您需要的渠道
|
||
- **持久化记忆**——按对话和全局
|
||
- **定时任务**，运行 Claude 并能回复消息
|
||
- **Web 访问**，用于搜索和浏览
|
||
- **浏览器自动化**，通过 agent-browser
|
||
|
||
**实现方法：**
|
||
- 使用现有工具（渠道库、Claude Agent SDK、MCP 服务器）
|
||
- 最少的胶水代码
|
||
- 尽可能使用基于文件的系统（CLAUDE.md 用于记忆，目录用于群组）
|
||
|
||
---
|
||
|
||
## 架构决策
|
||
|
||
### 消息路由
|
||
- 路由器监听已连接的渠道，根据配置路由消息
|
||
- 仅处理来自已注册群组的消息
|
||
- 触发词：`@Andy` 前缀（不区分大小写），可通过 `ASSISTANT_NAME` 环境变量配置
|
||
- 未注册的群组完全被忽略
|
||
|
||
### 记忆系统
|
||
- **按群组记忆**：每个群组有一个带自己 `CLAUDE.md` 的目录
|
||
- **全局记忆**：根 `CLAUDE.md` 供所有群组读取，但只能从"主群组"（自我聊天）写入
|
||
- **文件**：群组可以在其目录中创建/读取文件并引用它们
|
||
- Agent 运行在群组的目录中，自动继承两个 CLAUDE.md 文件
|
||
|
||
### Session 管理
|
||
- 每个群组维护一个对话 session（通过 Claude Agent SDK）
|
||
- Sessions 在上下文过长时自动压缩，保留关键信息
|
||
|
||
### 容器隔离
|
||
- 所有 agent 在容器（轻量级 Linux VM）内运行
|
||
- 每次 agent 调用启动一个挂载了目录的容器
|
||
- 容器提供文件系统隔离——agent 只能看到已挂载的路径
|
||
- Bash 访问安全，因为命令在容器内运行，而非在宿主机上
|
||
- 通过 agent-browser 和容器中的 Chromium 进行浏览器自动化
|
||
|
||
### 定时任务
|
||
- 用户可以从任何群组要求 Claude 安排定期或一次性任务
|
||
- 任务在创建它们的群组上下文中作为完整 agent 运行
|
||
- 任务可以访问包括 Bash 在内的所有工具（在容器中安全）
|
||
- 任务可以选择性地通过 `send_message` 工具向群组发送消息，或静默完成
|
||
- 任务运行记录到数据库，包含持续时间和结果
|
||
- 调度类型：cron 表达式、间隔（毫秒）或一次性（ISO 时间戳）
|
||
- 从主群组：可以为任何群组安排任务，查看/管理所有任务
|
||
- 从其他群组：只能管理该群组的任务
|
||
|
||
### 群组管理
|
||
- 新群组通过主渠道显式添加
|
||
- 群组在 SQLite 中注册（通过主渠道或 IPC `register_group` 命令）
|
||
- 每个群组在 `groups/` 下获得一个专用目录
|
||
- 群组可以通过 `containerConfig` 挂载额外目录
|
||
|
||
### 主渠道权限
|
||
- 主渠道是管理员/控制群组（通常是自我聊天）
|
||
- 可以向全局记忆写入（`groups/CLAUDE.md`）
|
||
- 可以为任何群组安排定时任务
|
||
- 可以查看和管理所有群组的任务
|
||
- 可以为任何群组配置额外的目录挂载
|
||
|
||
---
|
||
|
||
## 集成点
|
||
|
||
### 渠道
|
||
- WhatsApp (baileys)、Telegram (grammy)、Discord (discord.js)、Slack (@slack/bolt)、Gmail (googleapis)
|
||
- 每个渠道存于单独的 fork 仓库中，通过 skills（例如 `/add-whatsapp`、`/add-telegram`）添加
|
||
- 消息存储在 SQLite 中，由路由器轮询
|
||
- 渠道在启动时自行注册——未配置的渠道被跳过并发出警告
|
||
|
||
### 调度器
|
||
- 内置调度器在宿主机上运行，启动容器执行任务
|
||
- 自定义 `nanoclaw` MCP 服务器（容器内）提供调度工具
|
||
- 工具：`schedule_task`、`list_tasks`、`pause_task`、`resume_task`、`cancel_task`、`send_message`
|
||
- 任务存储在 SQLite 中，带运行历史
|
||
- 调度器循环每分钟检查到期任务
|
||
- 任务在容器化的群组上下文中执行 Claude Agent SDK
|
||
|
||
### Web 访问
|
||
- 内置 WebSearch 和 WebFetch 工具
|
||
- 标准 Claude Agent SDK 能力
|
||
|
||
### 浏览器自动化
|
||
- 容器中的 agent-browser CLI 和 Chromium
|
||
- 基于快照的交互，带元素引用（@e1、@e2 等）
|
||
- 截图、PDF、视频录制
|
||
- 认证状态持久化
|
||
|
||
---
|
||
|
||
## 设置与定制
|
||
|
||
### 理念
|
||
- 最小化配置文件
|
||
- 通过 Claude Code 进行设置和定制
|
||
- 用户克隆仓库并运行 Claude Code 进行配置
|
||
- 每个用户得到精确匹配其需求的定制设置
|
||
|
||
### Skills
|
||
- `/setup` - 安装依赖，配置渠道，启动服务
|
||
- `/customize` - 通用 skill，用于添加能力
|
||
- `/update-nanoclaw` - 拉取上游更改，与定制合并
|
||
|
||
### 部署
|
||
- 运行在 macOS (launchd)、Linux (systemd) 或 Windows (WSL2) 上
|
||
- 单个 Node.js 进程处理一切
|
||
|
||
---
|
||
|
||
## 个人配置（参考）
|
||
|
||
以下是创建者的设置，存档于此供参考：
|
||
|
||
- **触发词**：`@Andy`（不区分大小写）
|
||
- **响应前缀**：`Andy:`
|
||
- **角色**：默认 Claude（无自定义个性）
|
||
- **主渠道**：自我聊天（在 WhatsApp 中给自己发消息）
|
||
|
||
---
|
||
|
||
## 项目名称
|
||
|
||
**NanoClaw** - 引用 Clawdbot（现为 OpenClaw）。
|