deepbot

---

Introduction

DeepBot is a system-level AI assistant focused on enterprise productivity. It integrates deeply with existing enterprise systems, enabling AI to participate in day-to-day operations across departments through multi-Agent collaboration — automating complex business workflows. Whether it's document processing, data analysis, system monitoring, or cross-department coordination, DeepBot handles it through AI Agent technology. It supports parallel task execution, scheduled tasks, and skill extensions, all protected by strict security controls.

✨ Core Features

• Parallel Task Processing — Run multiple tasks simultaneously without interference
• 20+ Built-in Tools — File operations, command execution, browser control, image generation, image/video analysis, document analysis, AI chat, cross-session messaging, web fetching, Feishu/WeChat/WeCom messaging, Feishu document operations, and more
• Memory System — Long-term memory for user preferences and important context
• ⏰ Scheduled Tasks — Automate recurring work with cron-based scheduling
• Skill Extensions — Compose tools into reusable Skills for complex workflows
• Security Controls — Strict path whitelist to protect system access
• Multi-Model Support — Qwen, OpenAI, Claude, and more
• External Integrations — Connect with Feishu and other platforms for cross-platform interaction

---

Quick Start

Requirements

• Python: 3.11+
• Node.js: 20.0.0+ (optional, for running JS scripts)
• pnpm: 10.23.0+ (optional, for running JS scripts)
• OS: macOS, Windows (desktop), Linux/Docker

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

dist:mac vs dist:mac:local:

	dist:mac	dist:mac:local
Code signing	✅ Apple Developer ID	❌ None
Notarization	✅ Apple notarization	❌ None
Gatekeeper	✅ Passes verification	❌ Triggers security warnings
Requirements	Apple Developer account + .env credentials	None

To use dist:mac, configure the following in your .env file:

# Apple signing and notarization (macOS Electron builds only)
[email protected]
APPLE_ID_PASSWORD=your-app-specific-password
APPLE_APP_SPECIFIC_PASSWORD=your-app-specific-password
APPLE_TEAM_ID=your-team-id

You can generate an app-specific password at appleid.apple.com. The Team ID can be found in your Apple Developer account. | Use case | Production release | Local development / testing |

Note: dist:mac:local builds will trigger macOS security warnings on first launch — see the section below for how to handle them.

Docker Deployment

Docker deployment is available for Linux servers. If you need the Docker version, please contact the author.

Note for macOS builds: Signed builds (dist:mac) pass Gatekeeper verification and work without issues. Local builds (dist:mac:local) are unsigned and will trigger security warnings — see below for solutions.

macOS Security Warnings (Local Builds)

When using dist:mac:local (unsigned builds), macOS may show security warnings on first launch:

"App is damaged"

Run this in Terminal, then reopen the app:

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

"Cannot verify developer"

Option 1: Right-click to open

Right-click the app icon, select "Open", then click "Open" again in the dialog.

Option 2: System Settings

1. Try to open the app (you'll see a security warning — click "Cancel")
2. Go to "System Settings" → "Privacy & Security"
3. Scroll to the "Security" section
4. Click "Open Anyway"
5. Try opening the app again and click "Open" in the dialog

---

️ Architecture

DeepBot uses a modular architecture with support for multi-Agent communication and collaboration:

…

Multi-Agent Collaboration

…

Architecture Overview

• Gateway: Manages all Sessions. Each Tab maps to an independent Session with cross-Tab message routing.
• Session: An isolated conversation unit with its own Agent Runtime, memory, and context.
• Agent Runtime: Built on @mariozechner/pi-agent-core, handles intelligent decision-making and tool orchestration.
• System Prompt Assembly Layer: Dynamically assembles system prompts from base prompts, tool instructions, memory files, and Skills.
• Tools: 20+ built-in tools including a cross-Tab messaging tool for inter-Agent communication.
• Security Check: All file and command operations are validated against a path whitelist.
• Multi-Agent Collaboration: Agents in different Tabs can message each other to collaborate on complex tasks.

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

Dynamic Updates:

• When memory files change, all Agent system prompts reload automatically
• Installing or uninstalling Skills updates tool instructions in real time
• Hot updates are supported — no app restart required

---

External Integrations (Connectors)

DeepBot connects to external platforms via the Connector system for cross-platform interaction.

Supported Platforms

Feishu (Lark)

Interact with DeepBot through a Feishu bot, supporting both direct messages and group chats.

Features:

• ✅ Direct messages (requires pairing authorization)
• ✅ Group messages (supports @mention)
• ✅ Message deduplication (prevents duplicate responses)
• ✅ Independent session per conversation (each chat gets its own Tab)
• ✅ Send images and files to users
• ✅ Feishu document operations (create, read, edit, delete, comment)

Setup:

1. In DeepBot, go to "System Settings" → "External Connections" → "Feishu"
2. Enter your Feishu app credentials (App ID, App Secret, Bot Name)
3. Configure security policies (DM policy, group policy)
4. Click "Save" then "Start" the connector

Detailed Configuration Guide:

Feishu Bot Configuration Guide (Chinese)

WeChat

Interact with DeepBot via WeChat, supporting private and group chats.

Features:

• ✅ QR code login
• ✅ Private and group messages
• ✅ Send text, images, files
• ✅ Independent session management

WeCom (WeChat Work)

Interact with DeepBot via WeCom applications.

Features:

• ✅ Application message push
• ✅ Send text, images, files
• ✅ Independent session management
• ✅ Multi-instance support

Smart KF (Customer Service)

External customer service powered by WeCom KF API.

Features:

• ✅ Customer message receiving and replying
• ✅ Send text, images, files
• ✅ Independent session management
• ✅ Security sandbox (restricted tool access)
• ✅ Skill whitelist mechanism

Coming Soon

• Discord
• Slack
• DingTalk

---

20+ Built-in Tools

Tool	Function	Typical Use Cases
File Tool	File read/write	Read configs, save data, search files
Exec Tool	Run shell commands	Execute scripts, system operations, install packages
Browser Tool	Browser automation	Screenshots, web automation, content extraction
Calendar Tool	Calendar management	Check dates, calculate time, schedule reminders
Environment Check	System inspection	Detect system info, verify dependencies, diagnose issues
Image Generation	AI image generation	Create images, design assets, visual content
Media Analysis	Image/video analysis	Image description, video understanding, OCR (DeepBot provider only)
Doc Analysis	Document analysis	Read PDF/Word/Excel/PPT content (requires markitdown)
Web Search	Web search (Tavily)	Real-time queries, research, data collection
Web Fetch	Fetch web content	Extract articles, download page data
Memory Tool	Memory management	Store preferences, retrieve historical context
Skill Manager	Skill management	Install, uninstall, and list skill packages
Scheduled Task	Task scheduling	Create and manage cron-based tasks
Chat Tool	AI conversation	Internal AI calls, backend processing, isolated from main Agent context
Cross Tab Call	Cross-Tab messaging	Inter-Agent communication for multi-Agent collaboration
Feishu Send	Feishu messaging	Send text, images, files to Feishu users
Feishu Doc Tool	Feishu document ops	Create, read, append, update, delete blocks, add comments
WeChat Send	WeChat messaging	Send text, images, files to WeChat users
WeCom Send	WeCom messaging	Send text, images, files to WeCom users
Smart KF Send	Smart KF messaging	Send text, images, files to customer service users
System Command	System commands	Clear session and other system-level operations

Creating Custom Tools

All tools use the unified ToolPlugin interface and live in src/main/tools/.

Quick Start

1. Create a tool file

Create a new file in src/main/tools/ (e.g., my-tool.ts):

…

1. Register in tool-loader.ts

Edit src/main/tools/registry/tool-loader.ts:

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

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

1. Add tool name constant

Edit src/main/tools/tool-names.ts:

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

Then use TOOL_NAMES.MY_TOOL in your tool definition instead of the hardcoded string.

1. Add tool instructions

Edit src/main/prompts/templates/CUSTOM-TOOLS.md to document how the AI should use your tool.

Using the Email tool as an example:

## 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": "[email protected]",
  "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": "[email protected]",
  "subject": "Test Email",
  "body": "This is a test email"
}
```

2. HTML email:
```json
{
  "to": "[email protected]",
  "subject": "Project Progress Report",
  "body": "<h1>Progress</