热点

AI SCORE

开源项目2026-08-01 19:17

CogitoAgent：本地优先的开源AI Agent框架

dev.to · AI#Agent#开源#隐私

Editor brief · 编辑速览

开源AI agent项目，支持200+工具、本地执行、持续思考、隐私优先；对比云依赖的商业方案，强调数据主权和自主部署。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

持续思考。自主行动。保持隐私。

当今大多数 AI agent 分为两类：要么将你的文件上传到第三方云服务，要么闲置等待你输入新的 prompt。CogitoAgent 是一个采取不同立场的开源项目——你的文件保留在本地机器上，agent 会持续自主思考。

在这篇文章中，我将介绍 CogitoAgent 是什么、它的架构方式，以及你可能想给它一个 star 的原因。

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

Gitee (中国镜像): https://gitee.com/cnt-code/cogito-agent

技术栈: TypeScript 5.x · Node.js ≥ 22.12 · Electron · isolated-vm

当前版本: v2.3.2

CogitoAgent 是一个开源的自主 agent 框架，直接在你的本地工作空间运行。它调用你选择的 LLM API（任何兼容 OpenAI 的端点，自带密钥）来驱动推理和决策，同时你的文件、代码、git 仓库和数据库永远不会离开你的机器。

关键短语是"云驱动、本地执行"。它不是完全离线的本地 LLM（那是路线图上的计划）。相反，只有会话上下文被发送到你指定的 LLM API——文件 I/O、代码执行、git 操作和数据库查询都在本地进行。

如果你用过 AutoGPT、Claude Code 或 Cline，以下是 CogitoAgent 的定位方式：

核心特性一览

TypeScript 核心 —— 完整的 TypeScript 重写，具有编译时类型安全。

隐私优先 —— 工作空间文件保留在本地；只有会话上下文被发送到你的 LLM API。

持续思考 —— thinkCycle() 每 3 秒自动触发一次（可配置）。

工具执行 —— 28 个工具模块，200+ 个工具，覆盖文件操作、代码、git、数据库、OCR、Office、GIS、生物信息学、医学、化学、金融等。

安全沙箱 —— JavaScript 在 isolated-vm 中运行以实现进程级隔离；Python 通过 subprocess 运行。

多会话管理 —— 独立的会话，具有持久存储和自动压缩（150 轮次 / 100k tokens）。

桌面模式 —— Electron 窗口通过 WebSocket（端口 9527）与终端 agent 通信。

MCP 协议 —— 将所有工具公开为 MCP Server（端口 3001 上的 JSON-RPC 2.0），以便与其他 AI 客户端集成。

插件系统 —— 动态加载自定义工具插件。

思考链可视化 —— 推理过程和工具执行的实时可视化。

Agent 集群 —— 子 agent 生成、任务委托和多 agent 协作。

微信集成 —— 二维码登录、消息收发、专用会话（通过 iLink 协议，可选）。

架构：思考循环 + 状态机 + 注册表

最干净的理解 CogitoAgent 的方式是通过三个核心组件。

1. 思考循环 (Agent.ts)

这就是让 agent"自主思考"的原因。推理周期每 3 秒触发一次（可配置）：

thinkCycle() fires
   ↓
streamChat()  →  SSE stream to LLM API
   ↓
tool-parser.ts parses [TOOL] fn(args) [/TOOL]
   ↓
executeTool()  →  registry lookup, run tool
   ↓
scheduleNextCycle()  →  loop control

工具调用通过自定义的 [TOOL] functionName(args) [/TOOL] 标签格式表达，由 tool-parser.ts 解析。这种方法相比原生函数调用的优势在于：它是与模型无关的——任何能发出文本的模型都可以驱动工具，这就是 CogitoAgent 能与 GPT、Claude 或任何兼容 OpenAI 的提供商配合使用的原因。

2. 状态机 (state.ts)

Agent 在三种状态下循环：

AWAITING_INPUT —— 等待用户输入

THINKING —— 当前正在推理

AWAITING_CONFIRMATION —— 等待用户批准（用于危险操作）

AWAITING_CONFIRMATION 状态与 DANGEROUS_OPERATIONS 机制配对——破坏性操作（文件删除、git push 等）在执行前需要明确的用户确认。这就是 CogitoAgent 如何平衡自主性和安全性的方式。

3. 工具注册表 (registry.ts)

所有工具都在单个 TOOL_REGISTRY 中注册，由 executeTool() 查询。集中化这一点给你带来：

通过统计的可观测性 —— stats.ts 跟踪每个类别的工具调用计数和成功率。

追踪 —— tracing.ts 记录带有持续时间的工具执行事件。

统一的可扩展性 —— 插件 (plugin.ts) 和 MCP (mcp.ts) 都注入到同一个注册表中；主循环不知道源的来源。

工具系统：28 个模块中的 200+ 个工具

这是项目中最厚重的部分。模块的样本：

要点：CogitoAgent 不仅仅是一个"编码 agent"。它将科学计算（生物信息学、分子量、医学公式）、地理空间处理、财务计算、文档生成、浏览器自动化等众多功能整合到一个单一的注册表中。对于研究人员、分析师和办公自动化爱好者来说，这种广度通常比纯粹的代码生成更重要。

扩展工具集

插件系统 (plugin.ts) —— 动态加载自定义工具插件。仓库在 plugins/ 下提供三个示例插件：biopython-bio、pubmed-research 和 rdkit-chem（生物信息学 / 文献搜索 / 化学信息学）。

MCP 协议 (mcp.ts) —— 将所有 200+ 个工具公开为 MCP Server，这样任何兼容 MCP 的 AI 客户端都可以重用 CogitoAgent 的工具生态系统。

多 Agent 集群：从"一个助手"到"一个团队"

最有趣的功能之一。通过 orchestrator.ts 和 cluster.ts，主 agent 可以：

/spawn <persona> <name> <instruction> —— 创建具有给定 persona 的子 agent

/delegate <agentId> <task> —— 将任务委托给子 agent

parallelExecute —— 并行运行子 agent

pipeline —— 在顺序管道中链接子 agent

voting / panelDiscussion —— 投票或圆桌决策模式

子 agent 的状态转换是标准化的：

idle → thinking → tool_executing → thinking → ... → done
  ↓                                                    ↓
  └────────────────── error ←──────────────────────────┘

一个专用的监视面板（一个单独的 Electron 窗口，16:9 布局）提供三个实时可视化：

思考链 —— 带有参数、状态和持续时间的实时推理步骤。

工具统计 —— 每个类别的调用计数和成功率的 ECharts 条形图；颜色强度编码成功率。

集群拓扑 —— 一个 Canvas 渲染的环形拓扑，主 agent 在中心，子 agent 环绕；活跃节点脉动显示。

这意味着你不仅可以委托工作，还可以观看 agent 的工作过程，这对调试多 agent 行为和研究 agent 可观测性非常有用。

Persona 系统：程序员、医生、侠客等

CogitoAgent 在 personas/ 目录中提供 20+ 个预设 persona，分为两个系列：

现代专业角色 —— 程序员、医生、生物学家、化学家、计算科学家、学者、侦探、心理学家、教师、厨师、画家、策略家、商人等

历史/地域角色 —— 侠客、帝国评论家、学官、蒙古青年、陕北青年、藏族青年、战士、影子卫士、隐士等

Persona 通过 system-prompt.ts 加载，可以通过 /persona <name> 热切换。每个 persona 都有自己的 persona.md 文件；某些包含肖像图像。

结合集群功能，这让你可以生成一个学者子 agent 来进行文献审查、一个程序员子 agent 来编写代码，以及一个评论家子 agent 来评审它——不同的"个性"各自负责任务的一部分。

快速开始

要求：Node.js ≥ 22.12、npm 或 yarn、Python 3.x（可选，用于 Python 代码执行）。

git clone https://github.com/SnowLeopard-io/CogitoAgent.git
cd CogitoAgent
npm install
npm start

首次启动会要求以下五项内容：

API 基础 URL —— 任何兼容 OpenAI 的端点

模型名称 —— 例如 gpt-4o、claude-3-sonnet

工作空间路径 —— agent 可以访问的目录（使用专用文件夹，而不是你的主目录）

Persona —— 选择一个预设角色

Docker 一行命令也可以工作：

docker-compose up -d

中国用户注意：如果 npm install 无法获取 Electron 二进制文件，请在安装前设置 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/。也可以使用 Gitee 镜像以加快克隆速度：https://gitee.com/cnt-code/cogito-agent

安全提示：始终将"工作空间路径"限定在专用文件夹中。当 agent 尝试破坏性操作时，它进入 AWAITING_CONFIRMATION —— 在批准前仔细审查。