kevinluosl/deepbot

Bring AI into your enterprise workflows — a real working partner, not just a chatbot

English | 简体中文

📖 Introduction

✨ Core Features

🚀 Quick Start

Requirements

Installation

# Clone the repository
git clone https://github.com/kevinluosl/deepbot.git
cd deepbot

# Install dependencies
pnpm install

# Start in development mode
pnpm run dev

Build Desktop App

# Build for all platforms
pnpm run dist

# macOS (with code signing + notarization, requires Apple Developer account)
pnpm run dist:mac

# macOS local build (no signing, no notarization — for development/testing)
pnpm run dist:mac:local

# Windows only
pnpm run dist:win

# Apple signing and notarization (macOS Electron builds only)
APPLE_ID=your-apple-id@example.com
APPLE_ID_PASSWORD=your-app-specific-password
APPLE_APP_SPECIFIC_PASSWORD=your-app-specific-password
APPLE_TEAM_ID=your-team-id

Docker Deployment

macOS Security Warnings (Local Builds)

"App is damaged"

sudo xattr -rd com.apple.quarantine /Applications/DeepBot.app

"Cannot verify developer"

🏗️ Architecture

┌─────────────────────────────────────────┐
│      User Interface (Electron)          │
│   External Communication: Feishu        │
└─────────────────┬───────────────────────┘
                  │ IPC / WebSocket
┌─────────────────▼───────────────────────┐
│      Gateway (Session Management)       │
│    • Session per Tab                    │
│    • Message queue & routing            │
│    • Connector management               │
│    • Cross-Tab message routing 🆕       │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
   Session 1  Session 2  Session N
   (Tab 1)    (Tab 2)    (Tab N)
        │         │         │
        ▼         ▼         ▼
┌─────────────────────────────────────────┐
│   Agent Runtime (one per Session)       │
│    • Intelligent decision & orchestration│
│    • Auto-continue (up to 100 times)    │
│    • Operation tracking (max 3 retries) │
│    • Independent memory & context       │
│    • Cross-Tab calling tool 🆕          │
│    • Dynamic system prompt assembly 🆕  │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│     System Prompt Assembly Layer 🆕     │
│    • Base Agent prompt (AGENT.md)       │
│    • Tool instructions (TOOLS.md)       │
│    • Custom tool instructions           │
│    • Global memory (MEMORY.md)          │
│    • Per-tab memory (memory-<tab>.md)   │
│    • Skills instructions (SKILL.md)     │
│    • Dynamic loading & live updates     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│      14 Tools + Security Check          │
│    🔒 Path whitelist • Workspace isolation│
│    🔄 Cross-Tab messaging tool 🆕        │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
    Skills   Scheduled   Data Storage
                Tasks

Multi-Agent Collaboration 🆕

┌─────────────────────────────────────────┐
│      Enterprise Multi-Agent System      │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Sales   │ │ Gateway │ │Marketing│
│AI Agent │ │Message  │ │AI Agent │
└────┬────┘ │Router   │ └────┬────┘
     │      └────┬────┘      │
     └───────────┼───────────┘
                 │
     ┌───────────┼───────────┐
     ▼           ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Solutions│ │Product  │ │  R&D    │
│AI Agent │ │AI Agent │ │AI Agent │
└────┬────┘ └────┬────┘ └────┬────┘
     │           │           │
     └───────────┼───────────┘
                 │
                 ▼
           ┌─────────┐
           │Project  │
           │Manager  │
           │AI Agent │
           └─────────┘

Architecture Overview

System Prompt Assembly Flow 🆕

Agent starts → Load base Agent prompt (AGENT.md)
             ↓
           Load tool instructions (TOOLS.md + CUSTOM-TOOLS.md)
             ↓
           Load global memory (MEMORY.md)
             ↓
           Load per-tab memory (memory-<tab-id>.md)
             ↓
           Load Skills instructions (SKILL.md files)
             ↓
           Assemble complete system prompt
             ↓
           Send to AI model

🌐 External Integrations (Connectors)

Supported Platforms

Feishu (Lark)

WeChat

WeCom (WeChat Work)

Smart KF (Customer Service)

Coming Soon

🔧 20+ Built-in Tools

Creating Custom Tools

Quick Start

import { Type } from '@sinclair/typebox';
import type { ToolPlugin } from './registry/tool-interface';
import { TOOL_NAMES } from './tool-names';

export const myToolPlugin: ToolPlugin = {
  // 工具元数据（用于 UI 展示和管理）
  metadata: {
    id: 'my-tool',              // 唯一标识，kebab-case
    name: 'My Tool',            // 显示名称（给用户看）
    description: 'My custom tool',
    version: '1.0.0',
    author: 'DeepBot',
    category: 'custom',         // 分类：file | network | system | ai | custom
    tags: ['custom'],
  },
  
  // 创建工具实例，接收运行时上下文（工作目录、会话 ID、配置等）
  create: (options) => ({
    name: TOOL_NAMES.MY_TOOL,   // AI 调用时使用的工具名（必须在 tool-names.ts 中注册）
    label: 'My Tool',           // 执行步骤中显示的标签
    description: 'Execute custom operations',  // 告诉 AI 这个工具做什么
    // 参数定义（使用 TypeBox，AI 会根据 description 自动填充参数）
    // 常见参数类型示例：
    //   Type.String({ description: '...' })                    — 字符串
    //   Type.Number({ description: '...' })                    — 数字
    //   Type.Boolean({ description: '...' })                   — 布尔值
    //   Type.Optional(Type.String({ description: '...' }))     — 可选参数
    //   Type.Union([Type.Literal('a'), Type.Literal('b')])     — 枚举（AI 只能选其中一个）
    parameters: Type.Object({
      action: Type.Union([
        Type.Literal('search'),
        Type.Literal('create'),
        Type.Literal('delete'),
      ], { description: 'Operation type' }),
      query: Type.String({ description: 'Search keyword or target name' }),
      limit: Type.Optional(Type.Number({ description: 'Max results (default 10)' })),
      force: Type.Optional(Type.Boolean({ description: 'Skip confirmation' })),
    }),
    
    execute: async (toolCallId, params, signal) => {
      // signal: AbortSignal，用户停止时会触发
      // params: 已经过 schema 验证的参数对象
      
      return {
        // content: 返回给 AI 的内容（AI 会基于此决定下一步）
        content: [{ type: 'text', text: 'Success' }],
        // details: 结构化数据，用于 UI 渲染或日志记录（AI 不可见）
        details: { success: true },
      };
    },
  }),
};

import { myToolPlugin } from '../my-tool';

// Inside loadTools(), add with other plugins:
tools.push(...await resolvePluginTools(myToolPlugin.create(pluginOpts)));

export const TOOL_NAMES = {
  // ...existing tools
  MY_TOOL: 'my_tool',
};

## Email (Email Sending Tool)

### Core Principles
1. SMTP must be configured before use
2. The config file path is fixed — don't give users incorrect paths
3. On failure, guide users to fix their config based on the error message
4. Don't retry repeatedly — report the failure reason after one attempt

### Prerequisites

**Config file path** (searched in priority order):
1. Project-level: `<workspace>/.deepbot/tools/email-tool/config.json`
2. User-level: `~/.deepbot/tools/email-tool/config.json`

**Config file format**:
```json
{
  "user": "your-email@example.com",
  "password": "your-password-or-auth-code",
  "smtpServer": "smtp.example.com",
  "smtpPort": 465,
  "useSsl": true,
  "fromName": "Your Name"
}
```

**Common provider notes**:
- QQ Mail: Use authorization code, not your QQ password
- Gmail: Use an app-specific password
- 163 Mail: Enable SMTP service and use an authorization code

### Use Cases
- ✅ Notification emails, report emails
- ✅ Emails with attachments
- ✅ HTML-formatted emails
- ❌ Bulk marketing emails (risk of account suspension)
- ❌ Sensitive information (emails are not encrypted)

### Examples

1. Plain text email:
```json
{
  "to": "recipient@example.com",
  "subject": "Test Email",
  "body": "This is a test email"
}
```

2. HTML email:
```json
{
  "to": "team@company.com",
  "subject": "Project Progress Report",
  "body": "<h1>Progress</h1><ul><li>Feature A: Done</li></ul>",
  "html": true
}
```

3. Email with attachment:
```json
{
  "to": "client@example.com",
  "subject": "Contract Documents",
  "body": "Please find the contract attached",
  "attachments": ["~/Documents/contract.pdf"]
}
```

### Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| "nodemailer not installed" | Missing dependency | Ask user to install nodemailer |
| "Email tool not configured" | Config file missing | Ask user to create the config file |
| "Authentication failed" | Wrong credentials | Check account and authorization code |

Advanced Features

References

🔒 Security

Path Whitelist

Security Check Flow

Tool call → Path security check → Within whitelist?
                                   ├─ Yes → Allow execution
                                   └─ No  → Reject, return error

🧠 Memory System

Global Memory

Per-Tab Memory (Multi-Agent Support)

Usage Examples

User: "Remember: I prefer concise code"
DeepBot: "Got it, I'll keep that in mind"

User: "Create a Sales Analysis Agent"
DeepBot: "New Tab created. This Agent will focus on customer relationship management and sales data analysis"

User: "Remember: You are a Sales Expert responsible for customer follow-up and performance analysis"
Sales Agent: "Understood, I've saved my role and responsibilities"

Multi-Agent Collaboration Example

⏰ Scheduled Tasks

Features

Example

User: "Check desktop files every day at 9 AM"
DeepBot: "Scheduled task created — will run daily at 9:00"

🎨 Skill Extensions

Install an Existing Skill

# Use the Skill Manager tool in DeepBot
"Install weather skill"

Create a Custom Skill

1. Create the Skill directory

mkdir -p ~/.agents/skills/my-skill
cd ~/.agents/skills/my-skill

2. Create SKILL.md

---
name: my-skill
description: My custom skill for handling specific tasks
version: 1.0.0
author: Your Name
---

# My Custom Skill

## When to use this skill

Use this skill when the user needs to:
- Operation 1
- Operation 2

## How to use

### Step 1: Read file

Use the file_read tool:

```json
{
  "path": "~/example.txt"
}
```

### Step 2: Process data

Process the data as needed...

### Step 3: Save results

Use the file_write tool to save results...

## Notes

- Note 1
- Note 2

3. Install the Skill

"Install local skill at path ~/.agents/skills/my-skill"

Skill Directory

Skill Capabilities

🤖 Supported AI Models

⚠️ Important: Avoid Reasoning Models

📦 External Services

🛠️ Development Guide

Project Structure

deepbot/
├── src/
│   ├── main/           # Main process
│   │   ├── gateway.ts          # Session management
│   │   ├── agent-runtime/      # Agent runtime
│   │   ├── tools/              # Tool system
│   │   ├── scheduled-tasks/    # Scheduled tasks
│   │   ├── connectors/         # External connectors
│   │   └── database/           # Data storage
│   ├── renderer/       # Renderer process (React)
│   ├── shared/         # Shared utilities
│   └── types/          # Type definitions
├── docs/               # Documentation
└── scripts/            # Build scripts

📝 License

🙏 Acknowledgments

📧 Contact

⭐ If DeepBot is useful to you, a star goes a long way!