# CogitoAgent

**Repository Path**: Miwafi/cogito-agent

## Basic Information

- **Project Name**: CogitoAgent
- **Description**: 持续思考的智能体 - 探索文件 · 联网搜索 · 自主学习
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: project
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CogitoAgent

  <em>一个真正活在你电脑里的智能助手</em>


---

## 产品概述

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

不同于传统的聊天机器人，CogitoAgent 具备持续思考、自主探索、工具执行的能力，能够在后台主动发现和整理用户的本地文件资产，并可通过扩展工具集获得更多能力。

![](show/main.png)

---

## 核心优势

### 🔒 绝对隐私的本地架构
- **数据本地化**: 所有文件操作均在本机完成，数据全程不离开用户设备
- **历史本地存储**: 对话历史以 JSON 格式存储于本地 `data/` 目录，不经过云端
- **工作区隔离**: 支持自定义工作区路径，精确控制 AI 的活动范围，避免越权访问

### 🧠 持续思考与自主探索
- **循环思考机制**: 启动后持续运转，每 3 秒自动触发一次思考循环
- **主动文件发现**: 自主探索文件系统结构，发现并记录有价值的内容
- **智能记忆压缩**: 支持 150 轮对话后自动总结压缩历史，保持推理连贯性同时避免 token 爆炸
- **状态机控制**: 采用 THINKING / AWAITING_INPUT 双状态机，确保人机交互流畅无竞态

### 💬 实时打断与精准响应
- **随时中断**: 按 ENTER 键即可中断当前思考，立即响应用户指令
- **主动等待**: 支持 `[WAIT]` 标签，AI 可主动暂停等待用户回复
- **流式输出**: 采用 OpenAI 兼容 API 流式调用，实时展示 LLM 的思考与回复

### 🎭 丰富的人设选择
- **预设人设包**: 内置 13 种不同风格的人设（探索者、学者、侠客、文臣、武将等）
- **自定义人设**: 用户可通过 `persona.md` 完全自定义 AI 的性格与语言风格
- **首次配置引导**: 首次运行时提供交互式配置流程，引导完成 API 密钥、模型、工作区和人设选择

---

## 能力矩阵

### 文件管理
| 工具 | 功能描述 |
|------|----------|
| `ls(path)` | 列出目录内容（只显示一级） |
| `read(path)` | 读取文件内容（自动检测二进制文件并跳过） |
| `copy(src, dest)` | 复制文件 |
| `mkdir(path)` | 创建文件夹（支持递归创建） |
| `create(path, content)` | 创建新文件 |
  

![](show/file.png)



### 联网能力
| 工具 | 功能描述 |
|------|----------|
| `search(query)` | 联网搜索，获取最新信息摘要与参考链接 |
| `browse(url)` | 在默认浏览器中打开指定网址 |
| `fetchPage(url)` | 抓取静态网页正文，提取标题、段落和链接 |

![](show/web.png)


### 系统操作
| 工具 | 功能描述 |
|------|----------|
| `listApps()` | 列出当前电脑已安装的所有软件 |
| `openApp(name)` | 通过名称打开指定软件（如 `openApp("notepad")`） |
| `closeApp(name)` | 关闭正在运行的指定软件（如 `closeApp("notepad")`） |

![](show/system.png)

---

## 应用场景

- **文件检索与管理**: 用自然语言描述需求，AI 在工作区中定位、复制、整理文件
- **知识挖掘**: 自动发现被遗忘的文件，将分散的文档变成可检索的知识库
- **项目理解**: 基于探索历史回答"这个目录/文件是做什么的"，帮助快速了解陌生项目
- **内容摘要**: 读取文件内容并提炼关键信息，节省阅读时间
- **联网助手**: 结合本地文件与实时网络信息进行综合回答
- **系统控制**: 列出、打开或关闭软件，作为简易的系统控制助手
- **数字伙伴**: 自定义人设，拥有持续记忆的个人 AI 伙伴

---

## 技术架构

```
用户输入 → 状态机调度 → LLM API 流式调用 → 工具执行 → 循环继续
```

**核心模块:**
- `Agent.js` — 状态机与思考循环核心，处理用户中断与工具调用
- `tools/` — 模块化工具集（文件/网页/系统工具分离）
- `prompt.js` — 对话历史管理与上下文压缩
- `api/client.js` — OpenAI 兼容 API 客户端，支持流式响应
- `io/terminal.js` — 终端彩色 UI 与分块展示
- `config.js` — 配置管理
- `setup.js` — 首次运行引导流程

---

## 快速开始

### 环境要求
- Node.js 18+
- 可访问的 OpenAI 兼容 API（支持自定义 base URL）

### 安装与运行

```bash
# 安装依赖
npm install

# 首次运行（自动引导配置）
npm start

# 日常启动
npm start
```

### 首次配置流程
首次运行会自动引导完成以下配置：
1. API Base URL（支持 OpenAI 兼容的第三方 API）
2. API Key
3. 模型名称
4. 工作区路径
5. 人设选择

### 交互方式
- **ENTER** — 打断当前思考，输入指令
- **指令 + ENTER** — 发送消息给 AI
- **exit** — 退出程序

---

## 项目结构

```
CogitoAgent/
├── src/
│   ├── agent/
│   │   ├── Agent.js              # 核心智能体与状态机
│   │   ├── prompt.js             # 对话历史与上下文管理
│   │   └── tools/                # 工具集
│   │       ├── index.js          # 工具统一导出入口
│   │       ├── path.js           # 工作区路径工具
│   │       ├── file.js           # 文件操作工具
│   │       ├── web.js            # 网页相关工具
│   │       ├── system.js         # 系统操作工具
│   │       └── TOOL_DEVELOPMENT.md  # 工具开发文档
│   ├── api/
│   │   ├── client.js             # OpenAI 兼容 API 客户端
│   │   └── webSearch.js          # 联网搜索模块
│   ├── io/
│   │   └── terminal.js           # 终端 UI 与彩色输出
│   ├── config.js                 # 配置管理
│   └── setup.js                  # 首次运行引导
├── personas/                     # 预设人设包
│   ├── explorer.md
│   ├── scholar.md
│   ├── assistant.md
│   ├── creative.md
│   ├── critic.md
│   ├── teacher.md
│   ├── wenchen.md
│   ├── wujiang.md
│   ├── yingwei.md
│   ├── zhanshi.md
│   ├── moushi.md
│   ├── jianguan.md
│   └── xiake.md
├── data/
│   └── conversation.json         # 对话历史持久化
├── persona.md                    # 当前人设配置
├── config.json                   # 用户配置
└── package.json
```

---

## 与同类产品对比

| 特性 | ChatGPT | OpenClaw | CogitoAgent |
|------|---------|----------|-------------|
| 了解本地文件 | ❌ | ❌ | ✅ |
| 持续自主运行 | ❌ | 部分 | ✅ |
| 完全本地化运行 | ❌ | ❌ | ✅ |
| 本地文件操作能力 | ❌ | ✅ | ✅ |
| 轻量化部署 | ❌ | ❌ | ✅ |
| 隐私数据保护 | ⚠️ | ⚠️ | ✅ |
| 灵活定制人格 | ✅ | ❌ | ✅ |
| 系统软件控制 | ❌ | ❌ | ✅ |

---

## 适用人群

- 有大量本地文件需要管理的个人用户
- 注重数据隐私，不希望文件上传云端的用户
- 希望拥有持续运转的本地 AI 助手的开发者
- 需要快速了解陌生项目/文件夹结构的团队成员
- 设计师、研究员、学生等需要管理大量素材/笔记的用户
- 希望拥有自定义人格的数字伙伴的用户

---

## 扩展开发

CogitoAgent 采用模块化架构，可轻松扩展新的工具和功能。详细的开发指南请参考：
[`src/agent/tools/TOOL_DEVELOPMENT.md`](src/agent/tools/TOOL_DEVELOPMENT.md)

---

## 产品愿景

本地磁盘中堆积的论文、笔记、项目代码、设计素材——这些数据资产长期处于沉睡状态。

CogitoAgent 致力于将它们激活：通过持续探索与智能记忆，让每一个文件都能被精准定位、理解和复用，并通过可扩展的工具集，成为一个真正活在用户电脑里的通用 AI 智能体。

---

<p align="center">
  <em>让智能体自主运转，让能力无限扩展</em>
</p>