# WorkspaceAgent

**Repository Path**: pzr001/workspace-agent

## Basic Information

- **Project Name**: WorkspaceAgent
- **Description**: 个人工作台智能体
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Personal Workspace Agent

> 一个本地优先、可扩展的 AI 原生个人工作台智能体（Agent），基于 Agent 编排、工具调用与 MCP（Model Context Protocol，模型上下文协议）集成构建。

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-green.svg)](https://fastapi.tiangolo.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 项目简介

个人生产力工具往往分散在笔记、任务、日历、记忆、文件等多个系统中，导致上下文割裂、操作跳转频繁、信息难以统一利用。  
本项目尝试构建一个**统一的 AI 原生个人工作台**：让单个智能体能够理解用户上下文、调度内部工具、通过 MCP 接入外部能力，并以自然语言的方式完成信息管理与任务协同。

与传统的“问答式聊天机器人”不同，这个项目更强调**系统能力**而非单轮对话能力。它不仅能回答问题，还具备：

- 上下文组织与长期记忆管理
- 多工具统一注册与调用
- 基于 MCP 的外部工具接入
- 会话恢复与执行轨迹记录
- 本地工作台数据的统一检索与操作

换句话说，这不是一个简单的聊天界面，而是一个面向个人效率场景的**AI 原生系统**。

---

## 项目目标

本项目聚焦于构建一个具备以下特征的智能体工作台：

- **本地优先（Local-first）**：核心数据默认存储于本地，便于开发、调试与个人使用
- **单用户（Single-user）**：优先服务于个人工作流，而非多租户 SaaS 场景
- **可扩展（Extensible）**：支持后续扩展更多工具、模型提供方和外部系统
- **可观测（Observable）**：保留会话、工具调用与执行轨迹，便于调试与分析
- **可演示（Demo-friendly）**：内置 demo 模式与 demo MCP server，降低上手门槛

---

## 核心能力

### 1. Agent 编排能力（Agent Orchestration）

系统实现了完整的 **Plan → Act → Observe → Continue → Finalize** 执行闭环，支持：

- 基于上下文的任务规划
- 从统一工具注册表中动态选择工具
- 结合工作台数据进行上下文感知推理
- 可配置的最大步数与工具调用上限
- 出错后的优雅回退（graceful fallback）
- 无需外部模型密钥即可运行的 Mock Provider / Demo 模式

这一设计使系统不再只是“收到消息后直接回复”，而是具备更接近真实 Agent 的执行流程。

### 2. MCP 集成能力（Model Context Protocol）

系统支持通过 MCP 将智能体与外部工具系统连接起来，包含：

- MCP server 配置与连接管理
- 动态工具发现（tool discovery）
- MCP 工具调用与结果回传
- 将 MCP 工具与内建工具统一纳入 Agent 工具池
- 内置 demo MCP server，支持零外部依赖演示

这使项目具备了“从本地工作台走向外部系统集成”的扩展基础。

### 3. 工作台模块（Workspace Modules）

系统内置多个本地工作台模块，用于承载个人知识与任务上下文。

| 模块 | 核心操作 |
|------|----------|
| **Notes（笔记）** | 创建、列表、读取、更新、删除、搜索 |
| **Tasks（任务）** | 创建、列表、更新、完成、删除、搜索 |
| **Calendar（日历）** | 创建事件、列表、更新、删除、搜索 |
| **Memory（记忆）** | 创建、列表、更新、删除、搜索，支持 profile / fact / pinned 类型 |
| **Files（文件）** | 导入、列表、读取、关键词搜索，支持 txt / md / json / csv |

这些模块不仅能通过 API 和页面访问，也能被 Agent 直接调用，作为上下文构建的一部分。

### 4. 会话与轨迹（Sessions & Traces）

系统支持对 Agent 执行过程进行完整记录，包括：

- 会话管理与历史恢复
- 用户输入、计划、工具调用、工具结果、错误、最终回复等完整 trace
- tool run 级别的细粒度记录
- 时间戳与执行过程可追踪信息

这部分能力对于 Agent 调试、系统评估与后续扩展都非常关键。

### 5. 统一搜索（Unified Search）

系统支持跨模块检索，能够在以下数据之间进行统一搜索：

- 笔记（Notes）
- 任务（Tasks）
- 日历（Calendar）
- 记忆（Memory）
- 文件（Files）

同时提供：

- `unified_search`：供 Agent 使用的统一搜索工具
- `get_workspace_context`：用于构建会话上下文的统一上下文提取能力

---

## 系统架构

整体架构如下：

```text
User Input
    │
    ▼
┌─────────────────────────────────┐
│            API Layer            │
│   FastAPI routes + schemas      │
└─────────────┬───────────────────┘
              │
              ▼
┌─────────────────────────────────┐
│         Services Layer          │
│ chat_service / session_service /│
│ workspace_service / trace_service│
└─────────────┬───────────────────┘
              │
              ▼
┌─────────────────────────────────┐
│       Agent Orchestrator        │
│ context_builder → planner →     │
│ executor → observe → finalize   │
└──────┬──────────────┬───────────┘
       │              │
       ▼              ▼
┌──────────────┐ ┌──────────────┐
│ Tool System  │ │   MCP Layer  │
│ base +       │ │ client +     │
│ registry +   │ │ manager +    │
│ built-in     │ │ adapters     │
└──────┬───────┘ └──────┬────────┘
       │                │
       ▼                ▼
┌─────────────────────────────────┐
│      Workspace + Storage        │
│ notes / tasks / calendar /      │
│ memory / files / search +       │
│ SQLite (SQLAlchemy)             │
└─────────────────────────────────┘
```

### 架构分层说明

- **API Layer**：提供 HTTP 接口与输入输出 schema
- **Services Layer**：承接业务逻辑，解耦路由与底层模块
- **Agent Layer**：负责上下文构建、规划、执行、观察与最终响应生成
- **Tool System**：负责工具抽象、注册、调用与扩展
- **MCP Layer**：负责 MCP server 管理、工具发现与外部调用
- **Workspace + Storage**：负责本地工作台数据存储与检索

这种结构使项目具备较好的模块边界，也更适合后续维护与扩展。

---

## 目录结构

```text
.
├── main.py                    # 应用入口
├── README.md                  # 项目说明文档
├── requirements.txt           # Python 依赖清单
├── .env.example               # 环境变量模板
├── .gitignore                 # Git 忽略规则
├── config/                    # 配置模块
│   ├── __init__.py
│   ├── settings.py            # 基于 Pydantic 的配置管理
│   └── logging_config.py      # 日志配置
├── storage/                   # 数据存储层
│   ├── __init__.py
│   ├── db.py                  # 数据库引擎与 session 工厂
│   ├── models.py              # SQLAlchemy ORM 模型
│   ├── repositories.py        # Repository / CRUD 封装
│   └── migrations.py
├── workspace/                 # 工作台领域模块
│   ├── __init__.py
│   ├── notes.py               # 笔记模块逻辑
│   ├── tasks.py               # 任务模块逻辑
│   ├── calendar.py            # 日历模块逻辑
│   ├── memory.py              # 记忆模块逻辑
│   ├── files.py               # 文件导入与读取
│   └── search.py              # 统一搜索
├── tools/                     # Agent 工具实现
│   ├── __init__.py
│   ├── base.py                # 工具基类与 schema
│   ├── registry.py            # 工具注册表
│   ├── notes_tools.py
│   ├── task_tools.py
│   ├── calendar_tools.py
│   ├── memory_tools.py
│   ├── file_tools.py
│   ├── session_tools.py
│   └── search_tools.py
├── agent/                     # Agent 核心
│   ├── __init__.py
│   ├── orchestrator.py        # Agent 主循环
│   ├── context_builder.py     # 上下文组装
│   ├── planner.py             # 计划生成
│   ├── executor.py            # 工具执行
│   ├── prompts.py             # Prompt 模板
│   ├── providers.py           # 模型提供方抽象
│   └── types.py               # Agent 类型定义
├── mcp/                       # MCP 集成
│   ├── __init__.py
│   ├── client.py              # MCP 客户端实现
│   ├── manager.py             # MCP server 生命周期管理
│   ├── registry.py            # MCP 工具注册
│   ├── adapters.py            # 协议适配层
│   └── types.py               # MCP 类型定义
├── services/                  # 业务服务层
│   ├── __init__.py
│   ├── chat_service.py
│   ├── session_service.py
│   ├── trace_service.py
│   ├── integration_service.py
│   └── workspace_service.py
├── api/                       # HTTP API 层
│   ├── __init__.py
│   ├── app_factory.py         # FastAPI app factory
│   ├── deps.py                # 依赖注入
│   ├── routes/
│   │   ├── chat.py
│   │   ├── notes.py
│   │   ├── tasks.py
│   │   ├── calendar.py
│   │   ├── memory.py
│   │   ├── files.py
│   │   ├── sessions.py
│   │   ├── traces.py
│   │   └── integrations.py
│   └── schemas/
├── ui/                        # 轻量 Web 界面
│   ├── templates/
│   │   ├── base.html
│   │   ├── index.html         # Dashboard
│   │   ├── chat.html          # 聊天界面
│   │   ├── workspace.html     # 工作台总览
│   │   ├── integrations.html  # MCP 集成管理
│   │   ├── memory.html        # 记忆管理
│   │   └── sessions.html      # 会话与轨迹展示
│   └── static/
│       ├── app.css
│       └── app.js
├── scripts/                   # 脚本与演示工具
│   ├── run_demo.py            # 快速演示启动脚本
│   ├── seed_demo_data.py      # 初始化演示数据
│   ├── smoke_test.py          # 基础冒烟测试
│   └── demo_mcp_server.py     # 内置 demo MCP server
├── docs/                      # 补充文档
│   ├── architecture.md
│   ├── api.md
│   └── decisions.md
├── data/                      # 运行期数据目录
│   ├── uploads/               # 上传文件
│   └── logs/                  # 日志目录
└── tests/                     # 测试目录
    ├── test_smoke.py
    └── test_tools.py
```

---

## 技术栈

| 层级 | 技术 |
|------|------|
| **后端** | Python 3.11+, FastAPI, Pydantic, Uvicorn |
| **数据库** | SQLite, SQLAlchemy |
| **前端** | Jinja2 模板，原生 CSS / JS |
| **Agent** | 自定义编排循环，统一工具注册表 |
| **MCP** | Python MCP client / adapter + demo server |
| **文件处理** | aiofiles + 内置文本解析能力 |

---

## 快速开始

### 环境要求

- Python 3.11 或更高版本
- `pip` 或 `uv`

### 安装

```bash
# 进入项目目录
cd pythonCode/WorkspaceAgent

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows 下使用 .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt
```

### 配置

```bash
# 复制环境变量模板
cp .env.example .env

# 按需修改 .env 配置
# 若仅运行 demo 模式，可保持默认或只做少量配置
```

### 启动方式

```bash
# 启动 API 服务（默认监听 localhost:8000）
uvicorn main:app --reload

# 或使用 demo 启动脚本
python scripts/run_demo.py
```

启动后可访问：

- **API 文档**：`http://localhost:8000/docs`
- **Dashboard**：`http://localhost:8000/`
- **Chat 页面**：`http://localhost:8000/chat`

---

## 主要 API 接口

| Method | Path | 说明 |
|--------|------|------|
| POST | `/api/chat` | 向 Agent 发送消息 |
| GET | `/api/notes` | 获取笔记列表 |
| POST | `/api/notes` | 创建笔记 |
| GET | `/api/notes/{id}` | 获取单条笔记 |
| PUT | `/api/notes/{id}` | 更新笔记 |
| DELETE | `/api/notes/{id}` | 删除笔记 |
| GET | `/api/tasks` | 获取任务列表 |
| POST | `/api/tasks` | 创建任务 |
| PUT | `/api/tasks/{id}` | 更新任务 |
| PATCH | `/api/tasks/{id}/complete` | 标记任务完成 |
| DELETE | `/api/tasks/{id}` | 删除任务 |
| GET | `/api/calendar` | 获取事件列表 |
| POST | `/api/calendar` | 创建事件 |
| PUT | `/api/calendar/{id}` | 更新事件 |
| DELETE | `/api/calendar/{id}` | 删除事件 |
| GET | `/api/memory` | 获取记忆列表 |
| POST | `/api/memory` | 创建记忆 |
| PUT | `/api/memory/{id}` | 更新记忆 |
| DELETE | `/api/memory/{id}` | 删除记忆 |
| GET | `/api/files` | 获取文件列表 |
| POST | `/api/files/upload` | 上传 / 导入文件 |
| GET | `/api/sessions` | 获取会话列表 |
| POST | `/api/sessions` | 创建会话 |
| GET | `/api/sessions/{id}` | 获取会话及消息历史 |
| GET | `/api/traces` | 获取执行轨迹列表 |
| GET | `/api/traces/{id}` | 获取轨迹详情 |
| GET | `/api/integrations` | 获取 MCP 集成列表 |
| POST | `/api/integrations/connect` | 连接 MCP server |
| DELETE | `/api/integrations/{id}` | 断开 MCP server |

支持通过 `query` 或 `q` 参数进行关键词搜索，例如：

- `GET /api/notes?query=keyword`
- `GET /api/tasks?query=keyword`
- `GET /api/memory?query=keyword`
- `GET /api/files?query=keyword`
- `GET /api/calendar?query=keyword`

---

## Demo 模式

项目支持**无需外部 LLM API Key 的 demo 模式**，便于快速演示整体链路：

```bash
# 在 .env 中启用 demo 模式
DEMO_MODE=true

# 运行演示
python scripts/run_demo.py
```

Demo 模式包括：

- 基于规则的 Mock LLM Provider
- 内置 demo MCP server（`demo_mcp_server.py`）
- 演示数据初始化脚本（`scripts/seed_demo_data.py`）
- 预置的笔记、任务、记忆等示例数据

这使得项目即使在无外部模型依赖的情况下，也能较完整地展示系统能力。

---

## Agent 工作流

系统中的 Agent 采用 **Plan → Act → Observe → Continue → Finalize** 执行流程：

1. **上下文组装（Context Assembly）**  
   收集当前会话历史、长期记忆、工作台数据等上下文

2. **规划（Planning）**  
   根据用户输入与上下文生成简要执行计划

3. **工具选择（Tool Selection）**  
   从统一工具注册表中选择合适的工具

4. **执行（Execution）**  
   调用工具并收集返回结果

5. **观察（Observation）**  
   分析工具结果并判断下一步

6. **继续或结束（Continuation / Finalize）**  
   决定是否继续循环，或进入最终输出阶段

7. **最终响应（Response）**  
   生成回复并返回给用户

8. **持久化（Persistence）**  
   将消息、trace、tool runs 等写入存储层

### 安全边界

- 最大步数：可配置，默认 8
- 最大工具调用次数：可配置，默认 12
- 出错后支持 graceful fallback

---

## MCP 集成说明

MCP（Model Context Protocol）用于让 Agent 发现并调用外部工具。项目中的 MCP 集成流程包括：

1. 配置 MCP server
2. 建立连接（支持 stdio / SSE 等传输方式）
3. 自动发现该 server 暴露的工具
4. 将发现的 MCP 工具纳入统一工具池
5. 在 Agent 执行过程中按需调用

项目内置了一个 **demo MCP server**，可用于本地零依赖演示 MCP 接入流程。

---

## 页面说明

| 页面 | 路径 | 说明 |
|------|------|------|
| Dashboard | `/` | 系统总览与近期活动 |
| Chat | `/chat` | 对话式 Agent 界面 |
| Workspace | `/workspace` | 工作台总览，聚合 Notes / Tasks / Calendar / Memory |
| Integrations | `/integrations` | MCP server 管理与集成状态 |
| Memory | `/memory` | 长期记忆浏览与管理 |
| Sessions | `/sessions` | 会话列表与执行轨迹查看 |

---

## 已实现内容概览

当前版本已经完成了项目的核心主线搭建，主要包括：

- 基于 FastAPI 的 API 服务框架
- 本地工作台模块（Notes / Tasks / Calendar / Memory / Files）
- SQLite + SQLAlchemy 数据存储层
- Agent 主循环与工具调用基础链路
- 统一工具注册机制
- Sessions / Traces / Tool Runs 执行记录
- MCP 集成层与 demo MCP server
- 轻量级 Web 页面与可视化入口
- Demo 模式与演示脚本
- 可扩展的模块化工程结构

从展示和后续扩展角度看，这个版本已经具备一个 AI 原生个人工作台系统的核心骨架与主要能力。

---

## 后续增强方向

项目后续可继续增强的方向包括：

- 更丰富的文件解析能力（如 PDF、DOCX）
- 记忆摘要与会话摘要
- 更强的检索与 RAG 能力
- 导出功能（Markdown / JSON 等）
- 更完整的 Provider 抽象与多模型后端支持
- 更完善的页面交互与使用体验

---

## 当前限制

当前版本仍然保持了较强的本地优先与轻量设计，因此存在一些边界：

- 主要面向单用户本地使用场景
- 文件解析当前以文本类格式为主
- 默认未接入外部平台同步能力
- Demo 模式下使用规则式响应，不依赖真实 LLM

这些限制并不影响项目作为架构演示、Agent 工程展示与后续扩展基础。

---

## 亮点

这个项目的重点不在于“做了一个聊天框”，而在于完整体现了现代 AI 应用工程中的关键能力：

### 1. Agent 架构设计
实现了从上下文构建、规划、执行到轨迹记录的完整 Agent 编排链路，而不是单次问答逻辑。

### 2. 工具体系设计
通过统一的 tool registry 管理内建工具与 MCP 工具，体现了可扩展工具生态的设计思路。

### 3. MCP 协议接入
支持将 Agent 通过标准化协议连接到外部系统，是向更通用 AI 系统扩展的重要基础。

### 4. 长期记忆与上下文管理
通过结构化记忆（profile / fact / pinned）与工作台数据统一纳入上下文，体现了上下文工程能力。

### 5. 可观测性与可调试性
通过 sessions、traces、tool runs 等机制，完整记录 Agent 的行为过程，增强系统可解释性与可调试性。

### 6. 工程化实现
项目采用了相对清晰的模块划分、类型定义、repository 模式、依赖注入和可扩展目录结构，具备继续迭代为更完整产品的基础。

总体来说，这个项目更接近一个**AI 原生个人效率系统的参考实现**，而不仅仅是一个具备聊天能力的小工具。

---