# localBot

**Repository Path**: ereddate2017/local-bot

## Basic Information

- **Project Name**: localBot
- **Description**: LocalBot 是一个开源的 AI 智能体框架，可在您的设备上本地运行，优先考虑数据隐私并提供广泛的技能支持。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-02-17
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LocalBot JavaScript 实现

LocalBot 是一个开源的个人智能助理，可在您的设备上本地运行，优先考虑数据隐私并提供广泛的实用技能支持。

[English](README.md) | 简体中文

## 功能特性

- **本地化运行**: 在本地机器上运行，无需依赖云服务
- **技能系统**: 可扩展的技能系统，提供各种实用工具
- **双内存系统**: 使用 Markdown 存储的短期和长期记忆
- **多种界面**: 包含命令行界面和 Web 界面
- **网关系统**: 处理与外部系统的通信
- **多模型支持**: 支持阿里云、OpenAI、Anthropic、Google 等 16+ 种 AI 提供商
- **技能配置**: 类似 MCP 的技能配置系统，每个技能可独立配置
- **热重载**: 技能支持热重载，无需重启即可更新
- **上下文理解**: AI 能够理解多轮对话的历史上下文
- **按需技能安装**: 启动时不自动下载所有技能，只在需要时安装
- **自动技能发现**: AI 分析任务时自动识别并安装缺失的技能
- **动态配置输入**: 当技能缺少必要配置时，自动弹出配置对话框
- **配置持久化**: 用户提交的配置自动保存到 config.json
- **智能模型选择**: 根据任务类型和要求自动选择最优 AI 模型
- **并行任务处理**: 自动并行处理独立的子任务，提升性能
- **安全特性**: 输入验证、速率限制和 XSS 防护
- **动态技能管理**: 支持在运行时动态加载、卸载和重载技能
- **技能上传到源端**: 将本地技能上传到远程源服务器，自动排除 node_modules 和 package-lock.json
- **搜索缓存**: 智能搜索缓存，使用内存和文件存储实现更快的结果
- **技能相似度检查**: 自动检测并使用相似的现有技能，而不是创建重复技能

## 安装

### 前提条件

- Node.js (v14 或更高版本)
- npm

### 安装步骤

1. 克隆仓库
   ```bash
   git clone <repository-url>
   cd localbot-js
   ```

2. 安装依赖
   ```bash
   npm install
   ```

3. 启动 LocalBot
   ```bash
   npm start
   ```

## 项目结构

```
localbot-js/
├── src/
│   ├── ai/             # AI 提供商管理
│   ├── core/           # 核心运行时和网关
│   ├── skills/         # 技能系统和技能管理
│   ├── memory/         # 记忆系统
│   ├── interface/      # 用户界面
│   ├── config/         # 配置管理
│   ├── task/           # 任务处理（分析、分解、递归处理）
│   ├── web/            # Web 服务器
│   └── utils/          # 工具函数
├── skills/             # 本地技能目录
├── skills-source/      # 远程技能源服务器
├── memory/             # 长期记忆存储
├── bin/                # CLI 工具
├── config.json         # 配置文件
├── package.json        # 项目配置
├── .eslintrc.js        # ESLint 配置
├── .prettierrc         # Prettier 配置
├── README.md           # 英文文档
├── README.zh-CN.md     # 中文文档
└── USAGE.md            # 使用指南
```

## 核心组件

1. **LocalBot**: 主运行时类，初始化和管理所有其他组件
2. **ModuleRegistry**: 集中式模块管理系统，减少组件之间的直接依赖
3. **Gateway**: 处理与外部系统的通信
4. **SkillManager**: 管理技能加载、热重载和动态技能管理
5. **MemoryManager**: 管理短期和长期记忆，支持智能压缩
6. **InterfaceManager**: 管理用户界面（CLI 和 Web）
7. **ConfigManager**: 管理配置持久化和检索
8. **LifecycleManager**: 处理系统生命周期事件和钩子
9. **AIProviderManager**: 管理多个 AI 提供商，支持智能模型选择
10. **TaskAnalyzer**: 分析任务复杂度并选择最优技能
11. **TaskDecomposer**: 将复杂任务分解为子任务
12. **RecursiveProcessor**: 递归处理子任务，支持并行执行
13. **LongRunningTaskManager**: 管理长期运行的任务，支持进度跟踪
14. **StorageManager**: 抽象存储层，支持多种后端

## 架构

LocalBot 采用模块化、事件驱动的架构，具有清晰的关注点分离。有关详细的架构信息，请参阅 [架构指南](docs/ARCHITECTURE.md)。

## 新功能详解

### 上下文理解

LocalBot 现在支持完整的多轮对话上下文理解：

- AI 在处理消息时会自动包含历史对话记录
- 支持最多 50 条历史消息作为上下文
- 对话历史以 Markdown 格式存储，便于查看和编辑
- 每个会话有独立的 ID 和存储文件
- **智能压缩**：当对话超过 10 条消息或 2000 tokens 时，自动将旧消息压缩为摘要
- **多次压缩支持**：压缩可多次触发，始终保留最近的 8 条消息
- **上下文优化**：压缩后的摘要作为上下文传递给 AI，减少 token 使用同时保留关键信息

### 按需技能安装

为了避免启动时自动下载 1000+ 技能，LocalBot 采用按需安装策略：

- 启动时只加载已安装的本地技能
- 远程技能列表被缓存但不自动下载
- 当 AI 分析任务发现需要某个技能时，自动从远程源安装
- 技能安装后立即生效，无需重启

### 自动技能发现

AI 在处理用户需求时会自动：

1. 分析任务需要哪些技能
2. 检查本地是否已安装所需技能
3. 从远程源自动下载并安装缺失的技能
4. 重新分析任务（因为现在有新技能可用了）
5. 执行任务

### 动态配置输入

当技能缺少必要的配置参数时：

1. AI 自动检测缺失的配置
2. 前端弹出动态配置对话框
3. 用户输入所需参数
4. 配置自动保存到 config.json
5. 任务自动重试

### 配置持久化

- 用户提交的配置自动保存
- 配置按技能分组存储
- 支持敏感信息标记（secret）
- 配置可以在 Web 界面中查看和修改

### 智能模型选择

LocalBot 现在可以根据任务要求智能选择最优 AI 模型：

- **基于任务的选择**: 针对创意、技术、翻译和对话任务使用不同模型
- **性能追踪**: 追踪模型响应时间和成功率
- **需求匹配**: 考虑 token 限制和上下文窗口要求
- **自动回退**: 如果最优模型选择失败，自动回退到当前模型

### 并行任务处理

对于包含多个独立子任务的复杂任务：

- **依赖检测**: 自动检测子任务之间的依赖关系
- **并行执行**: 并行执行独立的子任务以提升性能
- **顺序回退**: 对于有依赖关系的子任务回退到顺序处理
- **结果聚合**: 收集并聚合所有子任务的结果

### 安全特性

增强的安全措施保护系统：

- **输入验证**: 验证消息内容和长度（最大 10000 字符）
- **速率限制**: 每个用户每分钟限制 10 条消息
- **XSS 防护**: 净化用户输入以防止 XSS 攻击
- **错误处理**: 优雅的错误处理和用户友好的错误消息

### 动态技能管理

高级技能生命周期管理：

- **动态加载**: 在运行时按需加载技能
- **热重载**: 无需重启 LocalBot 即可重载技能
- **依赖管理**: 自动依赖检查和解析
- **技能信息**: 查询技能元数据（版本、作者、依赖）
- **启用/禁用**: 动态启用或禁用技能

### 技能上传到源端

将本地技能上传到远程源服务器：

- **智能检测**: 自动检查源端是否已存在该技能
- **干净上传**: 自动排除 node_modules、package-lock.json、.git 和日志文件
- **一键上传**: 直接从 Web 界面上传技能
- **自动打包**: 技能自动打包为 tar.gz 归档文件

### 搜索缓存

智能搜索缓存系统，提供更快的结果：

- **双层缓存**: 内存缓存（1小时过期，100项限制）和文件存储（24小时过期）
- **缓存优化**: 自动管理缓存大小和过期时间
- **更快的结果**: 缓存的搜索立即返回，无需网络请求
- **存储持久化**: 缓存在 `data/search_cache` 目录中，重启后仍然存在

### 技能相似度检查

智能技能管理，避免重复技能：

- **智能检测**: 当 AI 建议创建新技能时，自动检测相似的现有技能
- **名称和描述匹配**: 使用 Levenshtein 距离比较技能名称和描述
- **基于阈值的匹配**: 只考虑相似度得分超过 60% 的技能
- **无缝集成**: 自动使用现有的相似技能，而不是创建重复技能

## 支持的 AI 提供商

- **OpenAI** - GPT-4, GPT-3.5
- **Anthropic** - Claude 系列
- **Google** - Gemini 系列
- **阿里云** - 通义千问系列
- **Azure OpenAI** - Azure 托管的 OpenAI 模型
- **Cohere** - Command 系列
- **Mistral AI** - Mistral 系列
- **深度求索** - DeepSeek 系列
- **Groq** - Llama 系列高速推理
- **Together AI** - 开源模型聚合
- **OpenRouter** - 多模型路由
- **百度文心一言**
- **智谱 AI** - ChatGLM 系列
- **月之暗面** - Kimi 系列
- **字节豆包**
- **Ollama** - 本地模型支持

## 内置技能

### 基础技能
- **HelloSkill**: 响应问候语
- **TimeSkill**: 告诉当前时间
- **WeatherSkill**: 提供天气信息
- **LocationSkill**: 提供位置信息

### 文件与代码
- **FileManager**: 文件读写、目录管理
- **CodeInterpreter**: 代码执行与解释
- **Git**: Git 操作支持
- **TerminalPro**: 终端命令执行

### 内容处理
- **Search**: 多搜索引擎集成（百度、Bing、Google、知乎等）
- **Summarize**: 文本摘要
- **Markdown**: Markdown 格式处理

### 服装相关
- **ClothingAnalysisSkill**: 服装分析
- **ClothingRecommendationSkill**: 服装推荐

## 技能配置系统

每个技能都可以定义自己的配置 Schema，类似 MCP（Model Context Protocol）：

```javascript
class MySkill extends Skill {
  getConfigSchema() {
    return {
      apiKey: {
        type: 'string',
        title: 'API Key',
        description: '服务的 API 密钥',
        default: '',
        required: true,
        secret: true  // 敏感信息，不在界面显示
      },
      timeout: {
        type: 'number',
        title: '超时时间 (ms)',
        description: '请求超时时间',
        default: 30000,
        required: false,
        min: 1000,
        max: 120000
      },
      engine: {
        type: 'enum',
        title: '搜索引擎',
        description: '选择默认搜索引擎',
        default: 'baidu',
        options: [
          { value: 'baidu', label: '百度' },
          { value: 'google', label: 'Google' }
        ]
      }
    };
  }
}
```

### 配置 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/skills` | 获取所有技能列表 |
| GET | `/api/skills/:name` | 获取单个技能详情 |
| GET | `/api/skills/:name/schema` | 获取技能配置 Schema |
| GET | `/api/skills/:name/config` | 获取技能配置 |
| PUT | `/api/skills/:name/config` | 更新技能配置 |
| PATCH | `/api/skills/:name/config/:key` | 更新单个配置项 |
| DELETE | `/api/skills/:name/config` | 重置技能配置 |

## 配置说明

LocalBot 使用 `.env` 文件进行配置。`config.json` 文件用于存储技能配置和运行时数据。

### .env 文件配置

1. 基于 `.env.example` 模板创建 `.env` 文件
2. 使用您的配置更新环境变量

```bash
# 复制示例文件
cp .env.example .env

# 编辑 .env 文件
```

### API 密钥配置

配置您要使用的 AI 提供商的 API 密钥：

```env
# 阿里云
ALIYUN_API_KEY=your-aliyun-api-key

# OpenAI
OPENAI_API_KEY=your-openai-api-key

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key

# 其他提供商...
```

### 可选配置

```env
# 记忆配置
MEMORY_COMPACTION_THRESHOLD=100

# 界面配置
COMMAND_LINE_ENABLED=true

# 网关配置
GATEWAY_PORT=3000

# Web 服务器配置
WEB_PORT=3000
```

## 开发工具

LocalBot 包含完整的开发工具链：

### NPM 脚本

```bash
# 启动 LocalBot
npm start

# 开发模式
npm run dev

# 代码检查
npm run lint
npm run lint:fix

# 代码格式化
npm run format

# 清理并重新安装依赖
npm run clean

# 技能管理
npm run skill:list
npm run skill:install
npm run skill:uninstall
npm run skill:update
npm run skill:init
npm run skill:add
npm run skill:remove
```

### ESLint 配置

使用 ESLint 进行代码质量检查：
- 强制执行最佳实践
- 检测未使用的变量
- 防止常见错误

### Prettier 配置

自动代码格式化：
- 一致的代码风格
- 自动分号
- 尾随逗号

### CLI 命令

LocalBot 提供完整的命令行工具：

```bash
# 启动 LocalBot
localbot start

# 开发模式启动
localbot dev

# 查看日志
localbot logs
localbot logs --date 2026-03-04
localbot logs --level error
localbot logs --lines 100

# 清除日志
localbot logs:clear
localbot logs:clear --date 2026-03-04

# 技能管理
localbot skill:list
localbot skill:install <skill-name>
localbot skill:uninstall <skill-name>
localbot skill:update <skill-name>
localbot skill:init
localbot skill:add <source-name> <source-url> [--type <source-type>]
localbot skill:remove <source-name>
```

## 记忆系统

LocalBot 使用双记忆系统：

- **短期记忆**: 在内存中存储最近的消息
- **长期记忆**: 在 `memory` 目录中以 Markdown 文件形式存储压缩后的消息

## Web 界面

LocalBot 提供 Web 界面进行交互：

1. 启动后访问 `http://localhost:3000`
2. 支持实时对话
3. 支持历史记录查看和切换
4. 支持 AI 提供商切换
5. 支持消息复制功能

## 添加自定义技能

1. 在 `skills/` 目录下创建新文件夹
2. 创建 `index.js` 文件，继承 `Skill` 基类
3. 实现 `canHandle()` 和 `handle()` 方法
4. 可选：实现 `getConfigSchema()` 定义配置

示例：

```javascript
const Skill = require('../../src/skills/Skill');

class MySkill extends Skill {
  constructor(localbot) {
    super(localbot);
    this.name = 'MySkill';
    this.description = '我的自定义技能';
  }

  async canHandle(message) {
    return message.includes('关键词');
  }

  async handle(message) {
    return '处理结果';
  }
}

module.exports = MySkill;
```

更多详情请参阅 [USAGE.md](USAGE.md)。

## 部署

LocalBot 支持使用 Docker 和 Kubernetes 进行多环境部署：

### 快速部署

```bash
# 部署到生产环境 (Docker)
./deploy/scripts/deploy.sh -e production -t docker -a deploy

# 部署到生产环境 (Kubernetes)
./deploy/scripts/deploy.sh -e production -t k8s -a deploy
```

### Docker 部署

```bash
# 进入 docker 部署目录
cd deploy/docker

# 复制环境文件
cp .env.example .env

# 部署
docker-compose up -d
```

### Kubernetes 部署

```bash
# 使用部署脚本
./deploy/scripts/deploy.sh -e production -t k8s -a deploy

# 或手动部署
kubectl apply -f deploy/k8s/
```

更多详情请参阅 [部署指南](docs/DEPLOYMENT.md)。

## 文档

- **[使用指南](USAGE.md)**: 详细使用说明
- **[API 文档](docs/API.md)**: RESTful API 参考
- **[部署指南](docs/DEPLOYMENT.md)**: 各种环境的部署说明
- **[故障排除指南](docs/TROUBLESHOOTING.md)**: 常见问题和解决方案
- **[贡献指南](docs/CONTRIBUTING.md)**: 如何为项目贡献代码
- **[技能源管理](docs/SKILL_REGISTRY.md)**: 技能源管理系统

## 贡献

欢迎贡献！请按照 [贡献指南](docs/CONTRIBUTING.md) 进行操作。

## 许可证

MIT 许可证