Skip to content
Back to search

deepbot

DeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kevinluosl--deepbot/badge.svg)](/listings/kevinluosl--deepbot)

HTML

<a href="/listings/kevinluosl--deepbot"><img src="/api/listings/kevinluosl--deepbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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)
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

> You can generate an app-specific password at [appleid.apple.com](https://appleid.apple.com). The Team ID can be found in your [Apple Developer account](https://developer.apple.com/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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 815 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="banner.jpg" alt="DeepBot Terminal" width="500"/>
  3. <p>
  4. **Bring AI into your enterprise workflows — a real working partner, not just a chatbot**
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
  7. [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
  8. [![Electron](https://img.shields.io/badge/Electron-28+-9feaf9.svg)](https://www.electronjs.org/)
  9. [English](README.md) | [简体中文](README_ZH.md)
  10. </div>
  11. ---
  12. ## 📖 Introduction
  13. 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.
  14. ### ✨ Core Features
  15. - 🎯 **Parallel Task Processing** — Run multiple tasks simultaneously without interference
  16. - 🔧 **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
  17. - 🧠 **Memory System** — Long-term memory for user preferences and important context
  18. - ⏰ **Scheduled Tasks** — Automate recurring work with cron-based scheduling
  19. - 🎨 **Skill Extensions** — Compose tools into reusable Skills for complex workflows
  20. - 🔒 **Security Controls** — Strict path whitelist to protect system access
  21. - 🤖 **Multi-Model Support** — Qwen, OpenAI, Claude, and more
  22. - 🌐 **External Integrations** — Connect with Feishu and other platforms for cross-platform interaction
  23. ---
  24. ## 🚀 Quick Start
  25. ### Requirements
  26. - **Python**: 3.11+
  27. - **Node.js**: 20.0.0+ (optional, for running JS scripts)
  28. - **pnpm**: 10.23.0+ (optional, for running JS scripts)
  29. - **OS**: macOS, Windows (desktop), Linux/Docker
  30. ### Installation
  31. ```bash
  32. # Clone the repository
  33. git clone https://github.com/kevinluosl/deepbot.git
  34. cd deepbot
  35. # Install dependencies
  36. pnpm install
  37. # Start in development mode
  38. pnpm run dev
  39. ```
  40. ### Build Desktop App
  41. ```bash
  42. # Build for all platforms
  43. pnpm run dist
  44. # macOS (with code signing + notarization, requires Apple Developer account)
  45. pnpm run dist:mac
  46. # macOS local build (no signing, no notarization — for development/testing)
  47. pnpm run dist:mac:local
  48. # Windows only
  49. pnpm run dist:win
  50. ```
  51. **`dist:mac` vs `dist:mac:local`**:
  52. | | `dist:mac` | `dist:mac:local` |
  53. |---|---|---|
  54. | Code signing | ✅ Apple Developer ID | ❌ None |
  55. | Notarization | ✅ Apple notarization | ❌ None |
  56. | Gatekeeper | ✅ Passes verification | ❌ Triggers security warnings |
  57. | Requirements | Apple Developer account + `.env` credentials | None |
  58. To use `dist:mac`, configure the following in your `.env` file:
  59. ```bash
  60. # Apple signing and notarization (macOS Electron builds only)
  61. APPLE_ID=your-apple-id@example.com
  62. APPLE_ID_PASSWORD=your-app-specific-password
  63. APPLE_APP_SPECIFIC_PASSWORD=your-app-specific-password
  64. APPLE_TEAM_ID=your-team-id
  65. ```
  66. > You can generate an app-specific password at [appleid.apple.com](https://appleid.apple.com). The Team ID can be found in your [Apple Developer account](https://developer.apple.com/account).
  67. | Use case | Production release | Local development / testing |
  68. > **Note**: `dist:mac:local` builds will trigger macOS security warnings on first launch — see the section below for how to handle them.
  69. ### Docker Deployment
  70. Docker deployment is available for Linux servers. If you need the Docker version, please contact the author.
  71. **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.
  72. ### macOS Security Warnings (Local Builds)
  73. When using `dist:mac:local` (unsigned builds), macOS may show security warnings on first launch:
  74. #### "App is damaged"
  75. Run this in Terminal, then reopen the app:
  76. ```bash
  77. sudo xattr -rd com.apple.quarantine /Applications/DeepBot.app
  78. ```
  79. #### "Cannot verify developer"
  80. **Option 1: Right-click to open**
  81. Right-click the app icon, select "Open", then click "Open" again in the dialog.
  82. **Option 2: System Settings**
  83. 1. Try to open the app (you'll see a security warning — click "Cancel")
  84. 2. Go to "System Settings" → "Privacy & Security"
  85. 3. Scroll to the "Security" section
  86. 4. Click "Open Anyway"
  87. 5. Try opening the app again and click "Open" in the dialog
  88. ---
  89. ## 🏗️ Architecture
  90. DeepBot uses a modular architecture with support for multi-Agent communication and collaboration:
  91. ```
  92. ┌─────────────────────────────────────────┐
  93. │ User Interface (Electron) │
  94. │ External Communication: Feishu │
  95. └─────────────────┬───────────────────────┘
  96. │ IPC / WebSocket
  97. ┌─────────────────▼───────────────────────┐
  98. │ Gateway (Session Management) │
  99. │ • Session per Tab │
  100. │ • Message queue & routing │
  101. │ • Connector management │
  102. │ • Cross-Tab message routing 🆕 │
  103. └─────────────────┬───────────────────────┘
  104. │
  105. ┌─────────┼─────────┐
  106. ▼ ▼ ▼
  107. Session 1 Session 2 Session N
  108. (Tab 1) (Tab 2) (Tab N)
  109. │ │ │
  110. ▼ ▼ ▼
  111. ┌─────────────────────────────────────────┐
  112. │ Agent Runtime (one per Session) │
  113. │ • Intelligent decision & orchestration│
  114. │ • Auto-continue (up to 100 times) │
  115. │ • Operation tracking (max 3 retries) │
  116. │ • Independent memory & context │
  117. │ • Cross-Tab calling tool 🆕 │
  118. │ • Dynamic system prompt assembly 🆕 │
  119. └─────────────────┬───────────────────────┘
  120. │
  121. ┌─────────────────▼───────────────────────┐
  122. │ System Prompt Assembly Layer 🆕 │
  123. │ • Base Agent prompt (AGENT.md) │
  124. │ • Tool instructions (TOOLS.md) │
  125. │ • Custom tool instructions │
  126. │ • Global memory (MEMORY.md) │
  127. │ • Per-tab memory (memory-<tab>.md) │
  128. │ • Skills instructions (SKILL.md) │
  129. │ • Dynamic loading & live updates │
  130. └─────────────────┬───────────────────────┘
  131. │
  132. ┌─────────────────▼───────────────────────┐
  133. │ 14 Tools + Security Check │
  134. │ 🔒 Path whitelist • Workspace isolation│
  135. │ 🔄 Cross-Tab messaging tool 🆕 │
  136. └─────────────────┬───────────────────────┘
  137. │
  138. ┌─────────┼─────────┐
  139. ▼ ▼ ▼
  140. Skills Scheduled Data Storage
  141. Tasks
  142. ```
  143. ### Multi-Agent Collaboration 🆕
  144. ```
  145. ┌─────────────────────────────────────────┐
  146. │ Enterprise Multi-Agent System │
  147. └─────────────────┬───────────────────────┘
  148. │
  149. ┌─────────┼─────────┐
  150. ▼ ▼ ▼
  151. ┌─────────┐ ┌─────────┐ ┌─────────┐
  152. │ Sales │ │ Gateway │ │Marketing│
  153. │AI Agent │ │Message │ │AI Agent │
  154. └────┬────┘ │Router │ └────┬────┘
  155. │ └────┬────┘ │
  156. └───────────┼───────────┘
  157. │
  158. ┌───────────┼───────────┐
  159. ▼ ▼ ▼
  160. ┌─────────┐ ┌─────────┐ ┌─────────┐
  161. │Solutions│ │Product │ │ R&D │
  162. │AI Agent │ │AI Agent │ │AI Agent │
  163. └────┬────┘ └────┬────┘ └────┬────┘
  164. │ │ │
  165. └───────────┼───────────┘
  166. │
  167. ▼
  168. ┌─────────┐
  169. │Project │
  170. │Manager │
  171. │AI Agent │
  172. └─────────┘
  173. ```
  174. ### Architecture Overview
  175. - **Gateway**: Manages all Sessions. Each Tab maps to an independent Session with cross-Tab message routing.
  176. - **Session**: An isolated conversation unit with its own Agent Runtime, memory, and context.
  177. - **Agent Runtime**: Built on `@mariozechner/pi-agent-core`, handles intelligent decision-making and tool orchestration.
  178. - **System Prompt Assembly Layer**: Dynamically assembles system prompts from base prompts, tool instructions, memory files, and Skills.
  179. - **Tools**: 20+ built-in tools including a cross-Tab messaging tool for inter-Agent communication.
  180. - **Security Check**: All file and command operations are validated against a path whitelist.
  181. - **Multi-Agent Collaboration**: Agents in different Tabs can message each other to collaborate on complex tasks.
  182. #### System Prompt Assembly Flow 🆕
  183. ```
  184. Agent starts → Load base Agent prompt (AGENT.md)
  185. ↓
  186. Load tool instructions (TOOLS.md + CUSTOM-TOOLS.md)
  187. ↓
  188. Load global memory (MEMORY.md)
  189. ↓
  190. Load per-tab memory (memory-<tab-id>.md)
  191. ↓
  192. Load Skills instructions (SKILL.md files)
  193. ↓
  194. Assemble complete system prompt
  195. ↓
  196. Send to AI model
  197. ```
  198. **Dynamic Updates**:
  199. - When memory files change, all Agent system prompts reload automatically
  200. - Installing or uninstalling Skills updates tool instructions in real time
  201. - Hot updates are supported — no app restart required
  202. ---
  203. ## 🌐 External Integrations (Connectors)
  204. DeepBot connects to external platforms via the Connector system for cross-platform interaction.
  205. ### Supported Platforms
  206. #### Feishu (Lark)
  207. Interact with DeepBot through a Feishu bot, supporting both direct messages and group chats.
  208. **Features**:
  209. - ✅ Direct messages (requires pairing authorization)
  210. - ✅ Group messages (supports @mention)
  211. - ✅ Message deduplication (prevents duplicate responses)
  212. - ✅ Independent session per conversation (each chat gets its own Tab)
  213. - ✅ Send images and files to users
  214. - ✅ Feishu document operations (create, read, edit, delete, comment)
  215. **Setup**:
  216. 1. In DeepBot, go to "System Settings" → "External Connections" → "Feishu"
  217. 2. Enter your Feishu app credentials (App ID, App Secret, Bot Name)
  218. 3. Configure security policies (DM policy, group policy)
  219. 4. Click "Save" then "Start" the connector
  220. **Detailed Configuration Guide**:
  221. 📖 [Feishu Bot Configuration Guide](docs/飞书机器人配置指南.md) (Chinese)
  222. #### WeChat
  223. Interact with DeepBot via WeChat, supporting private and group chats.
  224. **Features**:
  225. - ✅ QR code login
  226. - ✅ Private and group messages
  227. - ✅ Send text, images, files
  228. - ✅ Independent session management
  229. #### WeCom (WeChat Work)
  230. Interact with DeepBot via WeCom applications.
  231. **Features**:
  232. - ✅ Application message push
  233. - ✅ Send text, images, files
  234. - ✅ Independent session management
  235. - ✅ Multi-instance support
  236. #### Smart KF (Customer Service)
  237. External customer service powered by WeCom KF API.
  238. **Features**:
  239. - ✅ Customer message receiving and replying
  240. - ✅ Send text, images, files
  241. - ✅ Independent session management
  242. - ✅ Security sandbox (restricted tool access)
  243. - ✅ Skill whitelist mechanism
  244. ### Coming Soon
  245. - 🔜 Discord
  246. - 🔜 Slack
  247. - 🔜 DingTalk
  248. ---
  249. ## 🔧 20+ Built-in Tools
  250. | Tool | Function | Typical Use Cases |
  251. |------|----------|-------------------|
  252. | **File Tool** | File read/write | Read configs, save data, search files |
  253. | **Exec Tool** | Run shell commands | Execute scripts, system operations, install packages |
  254. | **Browser Tool** | Browser automation | Screenshots, web automation, content extraction |
  255. | **Calendar Tool** | Calendar management | Check dates, calculate time, schedule reminders |
  256. | **Environment Check** | System inspection | Detect system info, verify dependencies, diagnose issues |
  257. | **Image Generation** | AI image generation | Create images, design assets, visual content |
  258. | **Media Analysis** | Image/video analysis | Image description, video understanding, OCR (DeepBot provider only) |
  259. | **Doc Analysis** | Document analysis | Read PDF/Word/Excel/PPT content (requires markitdown) |
  260. | **Web Search** | Web search (Tavily) | Real-time queries, research, data collection |
  261. | **Web Fetch** | Fetch web content | Extract articles, download page data |
  262. | **Memory Tool** | Memory management | Store preferences, retrieve historical context |
  263. | **Skill Manager** | Skill management | Install, uninstall, and list skill packages |
  264. | **Scheduled Task** | Task scheduling | Create and manage cron-based tasks |
  265. | **Chat Tool** | AI conversation | Internal AI calls, backend processing, isolated from main Agent context |
  266. | **Cross Tab Call** | Cross-Tab messaging | Inter-Agent communication for multi-Agent collaboration |
  267. | **Feishu Send** | Feishu messaging | Send text, images, files to Feishu users |
  268. | **Feishu Doc Tool** | Feishu document ops | Create, read, append, update, delete blocks, add comments |
  269. | **WeChat Send** | WeChat messaging | Send text, images, files to WeChat users |
  270. | **WeCom Send** | WeCom messaging | Send text, images, files to WeCom users |
  271. | **Smart KF Send** | Smart KF messaging | Send text, images, files to customer service users |
  272. | **System Command** | System commands | Clear session and other system-level operations |
  273. ### Creating Custom Tools
  274. All tools use the unified `ToolPlugin` interface and live in `src/main/tools/`.
  275. #### Quick Start
  276. 1. **Create a tool file**
  277. Create a new file in `src/main/tools/` (e.g., `my-tool.ts`):
  278. ```typescript
  279. import { Type } from '@sinclair/typebox';
  280. import type { ToolPlugin } from './registry/tool-interface';
  281. import { TOOL_NAMES } from './tool-names';
  282. export const myToolPlugin: ToolPlugin = {
  283. // 工具元数据(用于 UI 展示和管理)
  284. metadata: {
  285. id: 'my-tool', // 唯一标识,kebab-case
  286. name: 'My Tool', // 显示名称(给用户看)
  287. description: 'My custom tool',
  288. version: '1.0.0',
  289. author: 'DeepBot',
  290. category: 'custom', // 分类:file | network | system | ai | custom
  291. tags: ['custom'],
  292. },
  293. // 创建工具实例,接收运行时上下文(工作目录、会话 ID、配置等)
  294. create: (options) => ({
  295. name: TOOL_NAMES.MY_TOOL, // AI 调用时使用的工具名(必须在 tool-names.ts 中注册)
  296. label: 'My Tool', // 执行步骤中显示的标签
  297. description: 'Execute custom operations', // 告诉 AI 这个工具做什么
  298. // 参数定义(使用 TypeBox,AI 会根据 description 自动填充参数)
  299. // 常见参数类型示例:
  300. // Type.String({ description: '...' }) — 字符串
  301. // Type.Number({ description: '...' }) — 数字
  302. // Type.Boolean({ description: '...' }) — 布尔值
  303. // Type.Optional(Type.String({ description: '...' })) — 可选参数
  304. // Type.Union([Type.Literal('a'), Type.Literal('b')]) — 枚举(AI 只能选其中一个)
  305. parameters: Type.Object({
  306. action: Type.Union([
  307. Type.Literal('search'),
  308. Type.Literal('create'),
  309. Type.Literal('delete'),
  310. ], { description: 'Operation type' }),
  311. query: Type.String({ description: 'Search keyword or target name' }),
  312. limit: Type.Optional(Type.Number({ description: 'Max results (default 10)' })),
  313. force: Type.Optional(Type.Boolean({ description: 'Skip confirmation' })),
  314. }),
  315. execute: async (toolCallId, params, signal) => {
  316. // signal: AbortSignal,用户停止时会触发
  317. // params: 已经过 schema 验证的参数对象
  318. return {
  319. // content: 返回给 AI 的内容(AI 会基于此决定下一步)
  320. content: [{ type: 'text', text: 'Success' }],
  321. // details: 结构化数据,用于 UI 渲染或日志记录(AI 不可见)
  322. details: { success: true },
  323. };
  324. },
  325. }),
  326. };
  327. ```
  328. 2. **Register in tool-loader.ts**
  329. Edit `src/main/tools/registry/tool-loader.ts`:
  330. ```typescript
  331. import { myToolPlugin } from '../my-tool';
  332. // Inside loadTools(), add with other plugins:
  333. tools.push(...await resolvePluginTools(myToolPlugin.create(pluginOpts)));
  334. ```
  335. 3. **Add tool name constant**
  336. Edit `src/main/tools/tool-names.ts`:
  337. ```typescript
  338. export const TOOL_NAMES = {
  339. // ...existing tools
  340. MY_TOOL: 'my_tool',
  341. };
  342. ```
  343. Then use `TOOL_NAMES.MY_TOOL` in your tool definition instead of the hardcoded string.
  344. 4. **Add tool instructions**
  345. Edit `src/main/prompts/templates/CUSTOM-TOOLS.md` to document how the AI should use your tool.
  346. Using the Email tool as an example:
  347. ````markdown
  348. ## Email (Email Sending Tool)
  349. ### Core Principles
  350. 1. SMTP must be configured before use
  351. 2. The config file path is fixed — don't give users incorrect paths
  352. 3. On failure, guide users to fix their config based on the error message
  353. 4. Don't retry repeatedly — report the failure reason after one attempt
  354. ### Prerequisites
  355. **Config file path** (searched in priority order):
  356. 1. Project-level: `<workspace>/.deepbot/tools/email-tool/config.json`
  357. 2. User-level: `~/.deepbot/tools/email-tool/config.json`
  358. **Config file format**:
  359. ```json
  360. {
  361. "user": "your-email@example.com",
  362. "password": "your-password-or-auth-code",
  363. "smtpServer": "smtp.example.com",
  364. "smtpPort": 465,
  365. "useSsl": true,
  366. "fromName": "Your Name"
  367. }
  368. ```
  369. **Common provider notes**:
  370. - QQ Mail: Use authorization code, not your QQ password
  371. - Gmail: Use an app-specific password
  372. - 163 Mail: Enable SMTP service and use an authorization code
  373. ### Use Cases
  374. - ✅ Notification emails, report emails
  375. - ✅ Emails with attachments
  376. - ✅ HTML-formatted emails
  377. - ❌ Bulk marketing emails (risk of account suspension)
  378. - ❌ Sensitive information (emails are not encrypted)
  379. ### Examples
  380. 1. Plain text email:
  381. ```json
  382. {
  383. "to": "recipient@example.com",
  384. "subject": "Test Email",
  385. "body": "This is a test email"
  386. }
  387. ```
  388. 2. HTML email:
  389. ```json
  390. {
  391. "to": "team@company.com",
  392. "subject": "Project Progress Report",
  393. "body": "<h1>Progress</h1><ul><li>Feature A: Done</li></ul>",
  394. "html": true
  395. }
  396. ```
  397. 3. Email with attachment:
  398. ```json
  399. {
  400. "to": "client@example.com",
  401. "subject": "Contract Documents",
  402. "body": "Please find the contract attached",
  403. "attachments": ["~/Documents/contract.pdf"]
  404. }
  405. ```
  406. ### Error Handling
  407. | Error | Cause | Fix |
  408. |-------|-------|-----|
  409. | "nodemailer not installed" | Missing dependency | Ask user to install nodemailer |
  410. | "Email tool not configured" | Config file missing | Ask user to create the config file |
  411. | "Authentication failed" | Wrong credentials | Check account and authorization code |
  412. ````
  413. **Documentation structure**:
  414. - **Core Principles**: Rules the AI must follow
  415. - **Prerequisites**: Required setup (config files, dependencies)
  416. - **Use Cases**: When to use or avoid this tool
  417. - **Examples**: Real usage from simple to complex
  418. - **Error Handling**: Common errors and how to resolve them
  419. #### Advanced Features
  420. - **Config files**: Read from `~/.deepbot/tools/<tool-name>/config.json`
  421. - **External dependencies**: Use dynamic `require()` to avoid bundling
  422. - **Cancellation**: Support user cancellation via `AbortSignal`
  423. - **Prompt management**: Document tool behavior in `CUSTOM-TOOLS.md` so the AI uses it correctly
  424. #### References
  425. - 📖 [Full Development Guide](src/main/tools/registry/TOOL-DEVELOPMENT-GUIDE.md)
  426. - 📝 [Example Tool Template](src/main/tools/registry/example-tool.ts)
  427. - 🔧 [Email Tool Example](src/main/tools/email-tool.ts) — complete example with config and external dependencies
  428. ---
  429. ## 🔒 Security
  430. DeepBot enforces strict access controls so AI Agents can only reach directories you've explicitly authorized.
  431. ### Path Whitelist
  432. Only the following directories (and their subdirectories) are accessible:
  433. | Type | Default Path | Purpose | Configurable |
  434. |------|-------------|---------|--------------|
  435. | **Workspace** | `~` (home directory) | File read/write, command execution | ✅ |
  436. | **Scripts** | `~/.deepbot/scripts` | Python script storage | ✅ |
  437. | **Skills** | `~/.agents/skills` | Skill package installation | ✅ |
  438. | **Images** | `~/.deepbot/generated-images` | AI-generated image storage | ✅ |
  439. ### Security Check Flow
  440. ```
  441. Tool call → Path security check → Within whitelist?
  442. ├─ Yes → Allow execution
  443. └─ No → Reject, return error
  444. ```
  445. ---
  446. ## 🧠 Memory System
  447. DeepBot supports persistent long-term memory to retain user preferences and important context across sessions.
  448. ### Global Memory
  449. - **Location**: `~/.deepbot/memory/MEMORY.md`
  450. - **Format**: Structured Markdown
  451. - **Auto-injection**: Loaded into every conversation's system prompt
  452. - **Live updates**: Memory changes automatically reload all active Agents
  453. - **Scope**: Shared across all Tabs — stores general preferences and shared context
  454. ### Per-Tab Memory (Multi-Agent Support)
  455. Each Tab (Agent) can have its own independent memory file, enabling true multi-role collaboration:
  456. - **Independent memory files**: Each Tab can have its own `memory-<tab-id>.md`
  457. - **Independent role definitions**: Different Tabs can take on different roles (e.g., Product Manager, Developer, QA Engineer)
  458. - **Independent work styles**: Each Agent can have its own domain expertise and preferences
  459. - **Persistent storage**: Tab memory and role settings are saved across sessions
  460. ### Usage Examples
  461. **Global memory**:
  462. ```
  463. User: "Remember: I prefer concise code"
  464. DeepBot: "Got it, I'll keep that in mind"
  465. ```
  466. **Per-tab memory**:
  467. ```
  468. User: "Create a Sales Analysis Agent"
  469. DeepBot: "New Tab created. This Agent will focus on customer relationship management and sales data analysis"
  470. User: "Remember: You are a Sales Expert responsible for customer follow-up and performance analysis"
  471. Sales Agent: "Understood, I've saved my role and responsibilities"
  472. ```
  473. ### Multi-Agent Collaboration Example
  474. 1. **Sales Agent** — Customer relationship management and sales pipeline; stores customer info and sales strategies
  475. 2. **Marketing Agent** — Market analysis and campaigns; stores market data and promotion plans
  476. 3. **Solutions Agent** — Technical solution design and requirements analysis; stores solution templates and specs
  477. 4. **Product Agent** — Product planning and backlog management; stores roadmaps and user feedback
  478. 5. **R&D Agent** — Technical development and implementation; stores technical docs and coding standards
  479. 6. **Project Manager Agent** — Project coordination and progress tracking; stores project plans and resource allocation
  480. Each Agent operates with independent memory and domain expertise, enabling efficient cross-department collaboration.
  481. ---
  482. ## ⏰ Scheduled Tasks
  483. Create and manage scheduled tasks to automate recurring work:
  484. ### Features
  485. - ✅ Cron expression support
  486. - ✅ Dedicated Tab execution (locked, cannot be closed)
  487. - ✅ Context reset between runs (retains last run's output as context)
  488. - ✅ Execution history tracking
  489. ### Example
  490. ```
  491. User: "Check desktop files every day at 9 AM"
  492. DeepBot: "Scheduled task created — will run daily at 9:00"
  493. ```
  494. ---
  495. ## 🎨 Skill Extensions
  496. The Skills system lets you compose multiple tools into reusable, complex workflows.
  497. ### Install an Existing Skill
  498. ```bash
  499. # Use the Skill Manager tool in DeepBot
  500. "Install weather skill"
  501. ```
  502. ### Create a Custom Skill
  503. A Skill is a directory containing a `SKILL.md` file using YAML frontmatter + Markdown format.
  504. #### 1. Create the Skill directory
  505. ```bash
  506. mkdir -p ~/.agents/skills/my-skill
  507. cd ~/.agents/skills/my-skill
  508. ```
  509. #### 2. Create SKILL.md
  510. ````markdown
  511. ---
  512. name: my-skill
  513. description: My custom skill for handling specific tasks
  514. version: 1.0.0
  515. author: Your Name
  516. ---
  517. # My Custom Skill
  518. ## When to use this skill
  519. Use this skill when the user needs to:
  520. - Operation 1
  521. - Operation 2
  522. ## How to use
  523. ### Step 1: Read file
  524. Use the file_read tool:
  525. ```json
  526. {
  527. "path": "~/example.txt"
  528. }
  529. ```
  530. ### Step 2: Process data
  531. Process the data as needed...
  532. ### Step 3: Save results
  533. Use the file_write tool to save results...
  534. ## Notes
  535. - Note 1
  536. - Note 2
  537. ````
  538. #### 3. Install the Skill
  539. **Option 1: Direct placement** (recommended)
  540. Place the Skill directory under `~/.agents/skills/` and restart DeepBot — it will be loaded automatically.
  541. **Option 2: Use Skill Manager**
  542. ```bash
  543. "Install local skill at path ~/.agents/skills/my-skill"
  544. ```
  545. ### Skill Directory
  546. - **Default path**: `~/.agents/skills/`
  547. - **Auto-discovery**: All installed Skills are loaded at startup
  548. - **Dynamic management**: Install and uninstall at runtime
  549. ### Skill Capabilities
  550. - 📖 Skills can call all 20+ built-in tools
  551. - 📝 Supports async operations and error handling
  552. - 🔧 Compose multiple tools for complex multi-step workflows
  553. ---
  554. ## 🤖 Supported AI Models
  555. - **Qwen** (Alibaba Cloud) — default model
  556. - **OpenAI** (GPT-4, GPT-3.5)
  557. - **Claude** (Anthropic)
  558. Configure your API keys in System Settings to get started.
  559. ### ⚠️ Important: Avoid Reasoning Models
  560. DeepBot is optimized for standard conversational models. Models with built-in thinking/reasoning modes can cause display issues with `<think>...</think>` tags, slower responses, and unnecessary overhead for simple tasks.
  561. **Not recommended:**
  562. - ❌ QwQ-32B-Preview
  563. - ❌ OpenAI o1, o1-mini, o1-preview
  564. - ❌ DeepSeek-R1
  565. - ❌ Any model with explicit reasoning/thinking steps
  566. ---
  567. ## 📦 External Services
  568. | Service | Purpose | Configuration |
  569. |---------|---------|---------------|
  570. | **Tavily API** | Web search | System Settings → Web Search |
  571. | **Gemini** | Image generation (Imagen 3) | System Settings → Image Generation |
  572. ---
  573. ## 🛠️ Development Guide
  574. ### Project Structure
  575. ```
  576. deepbot/
  577. ├── src/
  578. │ ├── main/ # Main process
  579. │ │ ├── gateway.ts # Session management
  580. │ │ ├── agent-runtime/ # Agent runtime
  581. │ │ ├── tools/ # Tool system
  582. │ │ ├── scheduled-tasks/ # Scheduled tasks
  583. │ │ ├── connectors/ # External connectors
  584. │ │ └── database/ # Data storage
  585. │ ├── renderer/ # Renderer process (React)
  586. │ ├── shared/ # Shared utilities
  587. │ └── types/ # Type definitions
  588. ├── docs/ # Documentation
  589. └── scripts/ # Build scripts
  590. ```
  591. ---
  592. ## 📝 License
  593. This project is licensed under the [MIT License](LICENSE).
  594. ---
  595. ## 🙏 Acknowledgments
  596. DeepBot was inspired by:
  597. - [Clawdbot](https://github.com/openclaw/openclaw) — architectural reference
  598. - [@mariozechner/pi-agent-core](https://github.com/badlogic/pi-agent) — AI Agent Runtime
  599. ---
  600. ## 📧 Contact
  601. - **Author**: Kevin Luo @ Deepglint
  602. - **Issues**: [GitHub Issues](https://github.com/kevinluosl/deepbot/issues)
  603. ---
  604. <div align="center">
  605. **⭐ If DeepBot is useful to you, a star goes a long way!**
  606. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.