CogitoAgent:隐私优先的本地AI助手,持续思考、自主探索、工具执行

向AI转型的程序员都关注公众号机器学习AI算法工程

项目名称：CogitoAgent — 云端驱动、本地执行的自主AI智能体

技术栈：Node.js + Electron + WebSocket + LLM API

核心定位：隐私优先的本地AI助手，持续思考、自主探索、工具执行

工具数量：16+工具模块，100+工具函数

GitHub：

https://github.com/SnowLeopard-io/CogitoAgent

一、项目概述

CogitoAgent 是一款运行于本地的自主AI智能体，融合了文件管理、知识挖掘、系统操作、代码执行与联网能力。它直接在用户配置的工作目录下运行，无需上传任何文件至第三方服务器，在保障数据隐私安全的同时，提供持续运转的智能助理服务。

与传统聊天机器人的本质区别

传统聊天机器人是"一问一答"的被动模式，用户不提问，AI就处于休眠状态。而CogitoAgent具备三大核心能力：

持续思考：
每3秒自动触发一次思考循环，主动分析当前任务状态
自主探索：
LLM自主决策调用工具，无需用户逐一下达指令
工具执行：
内置19个工具模块，支持文件操作、代码执行、Git、数据库、OCR等

简而言之，CogitoAgent不是又一个聊天机器人，而是一个真正"活"在你电脑里的智能体。

二、核心功能特性

特性	说明
隐私优先	所有数据本地存储，不上传任何文件到第三方服务器
持续思考	每3秒自动触发思考循环，主动分析当前任务状态
工具执行	内置19个工具模块，支持文件操作、代码执行、Git、数据库、OCR、Office文档等
安全沙箱	JavaScript代码执行采用isolated-vm进程级隔离
多会话管理	支持多个独立对话会话，会话数据持久化存储
桌面模式	Electron桌面窗口，与终端Agent通过WebSocket通信
MCP协议	工具可作为MCP Server暴露，供其他AI客户端集成
插件系统	动态加载自定义工具插件
思维链可视化	实时可视化思考过程和工具执行
Agent集群	子Agent创建、任务委托、多Agent协作
微信集成	二维码登录、消息收发、专属会话

记忆系统
—— 基于 SQLite 的长期存储和语义检索
任务管理
—— 任务创建、分解和状态追踪
代码沙箱
—— isolated-vm 进程级隔离，支持 JS 和 Python
角色系统
—— 22 个预设角色，支持自定义和热切换
会话管理
—— 独立上下文，自动压缩
统计模块
—— 工具使用追踪和性能指标
思维链可视化
—— 实时思考过程展示
智能体集群
—— 子智能体创建、任务委派与集群监控，详见 introduction/agent-cluster.md

扩展

详见 introduction/extensions.md

插件系统
—— 动态加载自定义工具插件
MCP 协议
—— 将工具暴露为 MCP Server
追踪系统
—— 工具执行和 LLM 调用的轻量级可观测性
熔断与重试
—— 可靠的网络请求
多模型支持
—— OpenAI、Moark、Anthropic、Google
网络搜索
—— 内置互联网搜索能力

Docker

详见 introduction/deployment.md

docker-compose up -d

三、技术架构深度解析

3.1 整体架构

CogitoAgent采用分层架构设计，主要包含四个层次：

┌─────────────────────────────────────────────────────┐│                  终端层 (Terminal Layer)              ││   ┌──────────────┐    ┌─────────────────────┐       ││   │  CLI Terminal │    │ Electron Dashboard  │       ││   │  输入入口     │    │   GUI 窗口          │       ││   └──────────────┘    └─────────────────────┘       │├─────────────────────────────────────────────────────┤│                  核心层 (Core Layer)                 ││   ┌──────────┐  ┌──────────┐  ┌──────────┐         ││   │ Agent.js │  │ state.js │  │session.js│         ││   │ 思考循环  │  │ 状态机   │  │ 会话管理 │         ││   │  3秒触发 │  │          │  │          │         ││   └──────────┘  └──────────┘  └──────────┘         ││   ┌──────────┐  ┌──────────┐  ┌──────────┐         ││   │commands.js│ │registry.js│ │ stats.js │         ││   │ 命令处理  │  │ 工具注册  │  │ 统计分析 │         ││   └──────────┘  └──────────┘  └──────────┘         │├─────────────────────────────────────────────────────┤│                  工具层 (Tool Layer)                 ││   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     ││   │ 文件   │ │  网页  │ │ 浏览器 │ │ 代码   │     ││   │ 操作   │ │  工具  │ │ 自动化 │ │ 沙箱   │     ││   └────────┘ └────────┘ └────────┘ └────────┘     ││   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     ││   │  Git   │ │ 任务   │ │ 记忆   │ │ 微信   │     ││   │ 操作   │ │ 管理   │ │ 系统   │ │ 渠道   │     ││   └────────┘ └────────┘ └────────┘ └────────┘     │├─────────────────────────────────────────────────────┤│                  扩展层 (Extension Layer)            ││   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     ││   │  MCP   │ │ 插件   │ │ 重试   │ │ 追踪   │     ││   │ 协议   │ │ 系统   │ │ 熔断   │ │ 可观测 │     ││   └────────┘ └────────┘ └────────┘ └────────┘     │├─────────────────────────────────────────────────────┤│                  API层 (API Layer)                   ││   ┌─────────────────────────────────────────┐      ││   │  LLM API (OpenAI / Claude / 兼容API)    │      ││   └─────────────────────────────────────────┘      │└─────────────────────────────────────────────────────┘

3.2 核心组件职责

组件	职责	说明
Agent.js	思考循环	每3秒自动触发一次思考
state.js	状态机	THINKING / AWAITING_INPUT / AWAITING_CONFIRMATION
registry.js	工具注册表	19个工具模块集中管理
session.js	会话管理	多会话切换、上下文压缩
commands.js	命令处理	/help、/status等特殊命令
sandbox.js	代码沙箱	isolated-vm进程级隔离
ws-server.js	WebSocket	桌面模式通信

3.3 双状态机设计

CogitoAgent的状态机设计非常简洁，只有两个核心状态：

STATE = {

THINKING: 'THINKING', // 思考状态

AWAITING_INPUT: 'AWAITING_INPUT' // 等待用户输入

}

设计优势：

THINKING状态下，思考循环持续运行，AI主动分析和执行任务
AWAITING_INPUT状态下，思考循环完全停止，等待用户输入
用户按Enter键可随时中断思考，切换到输入模式
解决了一般Agent"用户输入时AI还在思考"的冲突问题

3.4 基于标记的工具调用协议

CogitoAgent没有使用OpenAI的Function Calling（因为需要特定API支持和复杂的参数schema），而是设计了一套纯文本标记协议：

工具调用格式：

[TOOL] functionName(args) [/TOOL]

优势：

不依赖特定API的Function Calling支持
比JSON schema更简单直观
兼容任何OpenAI兼容的API
易于调试和日志记录

四、工具系统详解

CogitoAgent内置19个工具模块，覆盖100+工具函数：

分类	文件	主要功能
文件操作	file.js	ls、read、create、copy、mkdir、delete、move
网页工具	web.js	search、browse、fetchPage、searchOnEngine
浏览器自动化	browser.js	initBrowser、clickElement、fillField、takeScreenshot
系统操作	system.js	listApps、openApp、closeApp
代码执行	code.js	executeCode、runJavaScript、runPython
Git	git.js	gitStatus、gitCommit、gitPush、gitPull、gitDiff
任务管理	task.js	createTask、getTasks、completeTask、splitTask
记忆系统	memory.js	addMemory、searchMemory、getRelatedMemories
数据处理	data.js	readCSV、writeJSON、csvToJSON、queryData
数据库	db.js	executeSQL、query、insert、update、createTable
邮件	email.js	sendEmail、sendTextEmail、sendHtmlEmail
系统监控	monitor.js	getCPUInfo、getMemoryInfo、monitorSystem
定时任务	scheduler.js	addScheduleTask、getScheduleTasks
图像识别	ocr.js	ocr、ocrBatch
Office文档	office.js	createPpt、createWord、createExcel、readExcel

五、核心优势与价值

隐私安全：数据不出本地

所有文件操作使用本地fs模块，对话历史存于data/conversation.json，不上传任何用户数据到第三方服务器。只有对话上下文会发送到用户配置的LLM API，工作区文件始终保持在本地。

适用场景：企业内部文档处理、敏感数据处理、个人隐私文件管理

持续思考：AI主动工作

传统AI需要用户不断提问，CogitoAgent每3秒自动触发思考循环。例如，用户可以说"帮我整理downloads文件夹"，AI会在后台持续执行，直到任务完成。

核心机制：setTimeout递归循环 + 双状态机，确保思考过程可控

工具丰富：一站式解决方案

内置19个工具模块，覆盖文件管理、代码执行、网页搜索、数据库操作、OCR识别、Office文档等场景。用户无需在多个工具间切换，CogitoAgent可以自动调用合适的工具完成复杂任务。

示例："帮我搜索最新的AI论文，下载PDF，提取摘要，保存到research文件夹"

安全沙箱：代码执行无忧

JavaScript代码执行采用isolated-vm进程级隔离，确保AI执行代码时不会影响系统安全。Python代码通过子进程执行，同样具备隔离性。

安全等级：进程级隔离，比虚拟机更轻量，比直接执行更安全

多会话管理：任务隔离

支持多个独立对话会话，每个会话拥有独立的上下文和历史记录。可以为不同项目或任务创建不同会话，互不干扰。

功能：会话创建、切换、删除、重命名、历史压缩

桌面模式：可视化操作

提供Electron桌面窗口，通过WebSocket与终端Agent通信。支持Dashboard模式和Monitor模式，可视化展示思考过程、工具执行、集群状态。

模式：桌面悬浮窗 + Dashboard全窗口 + Monitor监控面板

六、社区认可度

项目在Gitee和GitHub双平台开源，拥有完整的文档体系（中文为主），包括工具系统文档、架构文档、配置指南、部署文档等。作者在CSDN发布了一系列开发实战文章，详细介绍了项目的技术路线和实现细节。

七、实战指南

7.1 环境要求

Node.js
：22.12或更高版本
npm/yarn
：包管理器
Python
：3.x（可选，用于Python代码执行）

7.2 安装步骤

# 1. 克隆项目（国内推荐Gitee）git clone https://gitee.com/cnt-code/cogito-agent.gitcd cogito-agent# 2. 安装依赖npm install# 3. 首次启动（会进入配置向导）npm start

国内用户注意：如果npm install下载Electron二进制文件失败，可设置镜像：

# Windows PowerShell$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"npm install# Linux/Macexport ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"npm install

7.3 首次配置

运行npm start后，会进入交互式配置向导，需要填写以下信息：

配置项	说明	示例
API Base URL	支持OpenAI兼容的第三方API	https://api.openai.com/v1
API Key	您的API密钥	sk-xxxxxx
模型名称	使用的LLM模型	gpt-4o / claude-3-sonnet
工作区路径	AI可以访问的目录	C:\Users\username\Documents
人设选择	预设的AI人设	22种预设人设可选

7.4 启动模式

命令	模式	说明
`npm start`	设置向导	首次配置或修改配置
`npm run cli`	CLI模式	纯终端，适合服务器/无头环境
`npm run electron:desktop`	桌面模式	Electron悬浮窗 + 终端Agent
`npm run electron:dashboard`	Dashboard模式	全窗口Dashboard，带会话管理和工具可视化

7.5 常用命令

命令	说明
`/sessions`	列出所有会话
`/new`	创建新会话
`/switch <id>`	切换到指定会话
`/persona <name>`	切换人设
`/personas`	列出所有可用人设
`/tools`	列出所有可用工具
`/status`	显示当前状态
`/help`	显示帮助信息
`/clear`	清空对话历史
`ENTER`	中断思考，进入输入模式
`exit`	退出程序

7.6 实战示例

示例1：文件整理

# 用户输入帮我整理downloads文件夹，把所有PDF文件移动到Documents/PDFs目录# CogitoAgent自动执行流程1. 调用 ls("C:\Users\username\Downloads") 列出文件2. 筛选出所有.pdf文件3. 调用 mkdir("C:\Users\username\Documents\PDFs") 创建目标目录4. 循环调用 move() 移动每个PDF文件5. 返回整理结果

示例2：代码分析

# 用户输入分析当前项目的代码结构，给出改进建议# CogitoAgent自动执行流程1. 调用 ls(".") 列出项目根目录2. 递归读取关键文件（package.json、src/等）3. 调用 searchMemory() 查找相关记忆4. LLM分析代码结构，生成改进建议5. 返回结构化分析报告

示例3：网页研究

# 用户输入搜索最新的React 19特性，总结关键变化# CogitoAgent自动执行流程1. 调用 search("React 19 new features 2026") 搜索网页2. 调用 fetchPage() 获取相关页面内容3. LLM分析和总结关键特性4. 调用 create() 保存总结到本地文件5. 返回结构化总结

八、扩展开发

8.1 自定义工具开发

CogitoAgent支持动态加载自定义工具插件。工具开发遵循统一接口规范：

// 自定义工具示例: myTool.jsmodule.exports = {  name: 'myCustomTool',  description: '我的自定义工具',  parameters: {    type: 'object',    properties: {      input: { type: 'string', description: '输入参数' }    },    required: ['input']  },async execute(args) {// 工具逻辑实现return { success: true, data: '执行结果' };  }};

8.2 MCP协议集成

CogitoAgent支持将工具作为MCP Server暴露，供其他AI客户端（如Claude Desktop、Cursor等）集成使用。

8.3 插件系统

通过插件系统，可以在运行时动态加载新的工具模块，无需修改核心代码。

九、Docker部署

项目支持Docker容器化部署：

# 使用docker-compose一键启动docker-compose up -d# 或者手动构建docker build -t cogito-agent .docker run -it -v /path/to/workspace:/workspace cogito-agent

十、适用人群

开发者

学习Agent架构设计：状态机、工具系统、会话管理
学习LLM应用开发：流式响应、上下文管理、提示词工程
学习Electron桌面应用开发

技术团队

内部知识库管理和检索
自动化运维任务
代码审查和分析

个人用户

文件整理和管理
信息搜索和总结
日程管理和提醒

十一、与同类项目对比

特性	CogitoAgent	Open Interpreter	Aider
运行方式	本地运行，云端思考	本地运行	本地运行
持续思考	✅ 3秒自动触发	❌ 需要用户触发	❌ 需要用户触发
工具数量	19+模块，100+函数	基础工具	代码编辑工具
多会话	✅	❌	❌
桌面模式	✅ Electron	❌	❌
MCP协议	✅	❌	❌
代码沙箱	✅ isolated-vm	❌	❌
中文支持	✅ 原生中文	❌	❌