🔍 🤖 🌐 Ollama Chat with MCP

🔍 🤖 🌐 Osoba

一款强大、现代化的 UI，通过 Model Context Protocol（MCP）集成了本地和托管的大模型，并支持智能网页搜索与内容提取、SQL、YouTube 转录文本分析、HubSpot 操作、Python 数据分析、Canva 设计创建、Figma 设计检查、Poe 多模型 AI（文本、图像、视频和音频生成），以及用于安全代码脚手架搭建的 Codex MCP 服务。其功能包括：通过用户资料和对话上下文提供个性化 AI 助手、用于持久参考资料的文档知识库、提供商设置、多提供商模型选择、流式聊天、持久化对话、完善的任务系统，以及支持时区感知调度的定时任务。

概述

Osoba 展示了如何通过使用 MCP 工具扩展本地模型和托管模型。它将通过 Ollama 本地运行的大模型与智能网页搜索和内容提取、SQL 查询、YouTube 字幕摄取、HubSpot 业务操作、基于 Python 的 CSV 分析和可视化、Canva 设计创建与导出、Figma 文件和设计检查与导出、Poe 多模型 AI 文本聊天和媒体生成（图像、视频、音频）结合起来，并提供 Codex Workspace 服务，可在隔离的工作区内生成代码。多提供商层还支持 OpenAI、Anthropic、Google、OpenRouter、Groq 和 SambaNova。对话和任务会持久化存储在 MongoDB 中。

该项目由以下几个主要组件构成：

• 后端（FastAPI）：负责管理聊天逻辑、模型提供商路由、MCP 服务通信（包括启动和管理网页搜索、SQL、YouTube、HubSpot、Python、Canva、Figma、Poe、Codex 等 MCP 服务）、任务和调度程序，以及持久化存储。

• 前端（React）：为用户提供现代、响应式的 Web 界面，用于与聊天应用交互。

• MCP 智能网页搜索服务模块：通过 Serper.dev API 提供智能网页搜索，并自动提取热门搜索结果的内容。采用多种内容提取方法（trafilatura、BeautifulSoup），支持 URL 优先级排序、遵守 robots.txt 以及礼貌抓取实践。

• MCP SQL 服务模块：对 MySQL 数据库执行只读查询（提供架构资源和查询安全机制）。

• MCP YouTube 字幕服务：使用多种策略（youtube-transcript-api、Pytube、yt-dlp）可靠地获取字幕，并可选择使用代理，然后将字幕上下文持久化到对话中，以便后续跟进。

• MCP HubSpot 业务工具：通过 OAuth 使用 HubSpot API 创建和更新营销电子邮件，并采用 JSON 优先的提示流程。

• MCP Python 数据分析服务：全面的数据分析工具包，包含 CSV 加载、数据概况分析、筛选、分组和聚合、异常值检测、数据类型转换、统计假设检验和可视化（base64 图像），支持完整的分析工作流。

• MCP Canva 设计服务：可直接通过聊天或自主任务创建、浏览、导出、导入、调整尺寸和自动填充 Canva 设计。支持标准尺寸预设（Instagram、YouTube、演示文稿等）、自定义尺寸、品牌模板自动填充（Enterprise）、素材上传、设计导入（PDF/PPTX/DOCX/PSD），并可导出为 PNG、JPG、PDF、PPTX、SVG、MP4 或 GIF。需要 Canva Connect API 访问令牌（OAuth 2.0）。

• MCP Figma 设计服务：可读取 Figma 文件、提取指定节点、将画板和组件导出为图像（PNG/JPG/SVG/PDF）、管理评论，并提取完整的设计系统（颜色令牌、字体排版、间距、组件），所有操作均可通过聊天或任务完成。需要 Figma 个人访问令牌。

• MCP Poe AI 模型服务：通过单个兼容 OpenAI 的 API，访问 Poe 平台上的数百种 AI 模型。使用前沿大模型（Claude、GPT、Gemini、Grok、Llama）生成文本，使用 GPT-Image-1.5、Flux 和 Stable Diffusion 等模型创建图像（可控制纵横比），还可生成视频和音频，所有操作均可通过聊天或任务完成。需要 Poe API 密钥。

• MCP Codex Workspace 服务：为每次运行创建独立工作区，并在隔离目录中启动 Codex CLI，持久化保存构件（JSONL 事件、清单），实施可配置的输出策略，并提供异步运行 API，以支持流式交互体验。需要有效的 OpenAI API 密钥才能使用。

• MongoDB：存储对话历史和用户数据。

该架构展示了 MCP 如何让本地模型访问外部工具和数据源，从而显著增强其能力。后端会启动并监管所有 MCP 服务，以支持可扩展且功能丰富的部署。

功能

• 🧠 智能网页搜索：智能网页搜索，并自动提取热门搜索结果中的内容。突破搜索摘要的限制，使用先进的提取技术获取并分析完整网页内容。
• 🔎 URL 优先级排序：根据相关性评分对搜索结果进行智能排序，包括标题／摘要匹配、域名权威性和搜索位置权重。
• 🤖 礼貌的网页爬取：遵守 robots.txt，实施速率限制，并使用规范的 User-Agent 标识，以合乎道德的方式提取内容。
• 👤 用户资料与上下文：配置个人信息（角色、专长、项目），并置顶对话，为 AI 助手提供上下文。AI 会了解你的背景，并可参考以往工作，提供个性化回复。
• 🎯 目标与优先事项：在结构化文档中定义短期、中期和长期目标（最多 2000 个字符），帮助 AI 了解你的目标并提供相关协助。
• 🔔 主动式 Agent 心跳：增强型后台服务，可收集上下文（语义记忆、git、项目文件、系统健康状况）、自动创建任务，并通过文件进行配置（HEARTBEAT.md）。可配置间隔、上下文来源，并实现文件与 UI 之间的双向同步。
• 📌 对话置顶：选择特定对话，将其纳入未来聊天的上下文，让 AI 能在先前讨论的基础上继续交流，并在不同会话间保持连贯。
• 🧠 语义记忆：无限存储对话，并由 ChromaDB 和 nomic-embed-text 嵌入提供智能语义搜索。自动为包含 5 条以上消息的对话编制索引，按含义（而非关键词）搜索，并将相关的过往对话注入新聊天。包含记忆浏览器（Ctrl+Shift+M），可搜索和管理对话历史记录。
• 📚 文档知识库：上传 PDF、Word 文档、Markdown 文件、纯文本或网页 URL，作为持久参考资料。文档会被分块、嵌入，并存储在专用的 ChromaDB 集合中。相关文档片段会与语义记忆一同自动注入每次聊天。按 Ctrl+Shift+K 或点击标题栏中的“KB”按钮打开。
• 🧾 AI 聊天摘要（按需生成）：生成由大模型撰写的简明对话摘要，并将其用作置顶聊天的上下文载荷（不使用启发式方法）。摘要由用户触发，可在设置中选择模型；置顶聊天数量上限为 5 个。
• 🎯 个性化 AI 回复：AI 会根据你的个人资料信息和置顶对话历史调整沟通风格和建议，提供更相关的帮助。
• 💾 持久化对话：聊天历史记录保存在 MongoDB 中，用户可以继续之前的对话。
• 🧠 多提供商大模型：支持 Ollama（本地），以及 OpenAI、Anthropic、Google、OpenRouter、Groq、SambaNova；设置页面支持配置 API 密钥，并提供统一的模型选择器。
• 🔌 MCP 集成：后端将多个 MCP 工具（网页、SQL、YouTube、HubSpot、Python）作为后台服务进行管理。
• 💻 现代 Web 界面：使用 React 构建，带来响应迅速、交互性强的用户体验。
• 📊 结构化搜索结果：以清晰的格式呈现网页搜索数据，提供最佳上下文。
• 🌐 增强型内容提取：使用 trafilatura 和 BeautifulSoup，通过多种方式提取内容，并提供平稳的回退机制，确保最大可靠性。
• ⚙️ 后端 API：基于 FastAPI 的后端，提供稳健的聊天和对话管理 API 端点。
• 🗃️ SQL 查询工具：支持只读 MySQL 查询、架构内省和重试逻辑。
• 🔄 对话管理：列出、重命名和删除对话。
• 📺 YouTube 字幕工具：粘贴 YouTube URL，即可获取字幕并存储，以便进行多轮跟进。
• 🧰 HubSpot 工具：通过 OAuth 连接，然后使用引导式 JSON 提示词创建／更新营销邮件。
• 🐍 Python 分析工具：上传 CSV 并进行全面分析，包括数据概况分析、筛选、分组、异常值检测、统计检验、类型转换和可视化；结果会以流式方式返回，包含图片和详细见解。
• ⚡ 流式响应：前端逐个 Token 呈现模型输出，并显示工具使用指示器。
• 🗓️ 长时运行任务（规划与执行）：创建自主任务，规划并执行多步骤工作流，并支持预算、重试和验证。
• 📈 实时任务进度：任务通过 SSE 流式传输进度；每个步骤的输出（表格／图片／文本）都会在 UI 中呈现。
• 🧩 仅使用大模型的步骤（不使用 MCP）：任务可包含直接通过 Ollama 运行的步骤（例如摘要／推理），而无需使用任何 MCP 工具。
• 🚦 优先级任务队列：采用节省内存的任务执行方式和优先级调度机制——计划任务优先运行，用户任务排在其后；同一时间只执行一个任务，以防系统过载，这对本地、内存受限的系统尤其重要。
• 🎨 Canva 设计工具（MCP）：通过聊天或任务创建 Canva 设计，可使用标准预设（Instagram、YouTube 缩略图、演示文稿、A4 等）或自定义尺寸。浏览现有设计、上传素材、将文件（PDF/PPTX/DOCX/PSD）导入为可编辑设计、调整设计尺寸以适配不同平台、自动填充品牌模板，并导出为 PNG、JPG、PDF、PPTX、SVG、MP4 或 GIF——全程无需离开 Osoba。需要 Canva Connect API 访问令牌。
• 🖼️ Figma 设计工具（MCP）：读取 Figma 文件结构、按 ID 提取特定节点、将画板和组件导出为图片、列出并发布评论，以及提取完整的设计系统（颜色、排版、间距 Token 和组件目录）。适用于设计评审工作流、设计到代码的交接和自动化设计审查。需要 Figma Personal Access Token。
• 🤖 Poe AI 模型（MCP）：通过 Poe 平台访问数百种 AI 模型——使用前沿大模型生成文本，使用 GPT-Image-1.5、Flux 或 Stable Diffusion 生成图片（可控制 9:16／16:9 宽高比），并生成视频和音频。可用于聊天或自主任务。需要 Poe API 密钥。
• ✨ Codex 工作区（MCP）：启动 Codex，在隔离的工作区中生成／编辑文件；在聊天中内联显示运行状态；持久保存产物供审核；需提供 OpenAI 密钥。
• 🗓️ 计划任务（支持时区）：按本地时区计算重复 cron 计划或一次性计划，并安全处理夏令时；一次性计划运行后会自动停用；支持通过模型覆盖来“立即运行”。

任务执行与内存管理

任务系统 MCP 工具访问权限

任务系统可以完整访问聊天界面中的所有 MCP 工具，从而自主执行复杂工作流：

可用工具（共 55 个）：

• 网页搜索（5 个工具）：基础搜索、智能内容提取、图片搜索、新闻搜索、直接获取 URL
• Python 数据分析（17 个工具）：数据加载、检查、清理、转换、统计分析、可视化
• Canva 设计（10 个工具）：创建设计、列出设计、获取设计详情、导出为文件、上传素材、自动填充品牌模板、获取模板字段、导入设计、调整设计尺寸、获取设计页面
• Figma 设计（6 个工具）：获取文件结构、获取节点、导出图片、列出评论、发表评论、提取设计系统
• Poe AI 模型（5 个工具）：按模态列出模型、文本聊天、图像生成（支持宽高比）、视频生成、音频生成
• HubSpot 商务（2 个工具）：创建／更新营销邮件（需要 OAuth）
• Codex 工作区（7 个工具）：代码生成和工作区管理（需要 OpenAI API 密钥）
• 数据库（1 个工具）：只读 SQL 查询
• YouTube（1 个工具）：提取文字稿
• 仅限大模型（1 个工具）：直接调用大模型执行推理步骤

高级任务能力：

• 使用智能内容提取进行研究（获取完整网页内容，而不仅是摘要）
• 高级数据分析，包括异常值检测和统计假设检验
• Canva 设计工作流：研究主题，然后自动创建设计并导出
• Figma 设计工作流：提取设计令牌、导出素材，并检查文件结构，以便交接设计转代码工作
• Poe AI 工作流：控制宽高比生成图像，然后上传到 Canva，或用于多步骤创意流程
• 通过 HubSpot 集成实现营销自动化
• 使用细粒度的 Codex 工作区管理生成代码
• 结合搜索、分析、设计和生成的多步骤工作流
• 附加知识库上下文：创建任务时附加 1–2 份已索引的知识库文档，将参考资料注入规划器和每个大模型步骤

优先级队列系统

应用采用基于优先级的任务队列，以确保系统稳定，并避免多个大模型实例造成内存过载：

• 优先级 1（最高）：计划任务始终最先运行
• 优先级 2（标准）：用户创建的任务排在计划任务之后
• 一次一个任务：同时只执行一个任务，避免内存崩溃
• 队列位置：用户会收到自己在队列中位置的反馈

内存安全

• 防止过载：多个并发大模型实例（例如，3 个 Llama3.1 8B = 24GB）可能导致内存有限的系统崩溃
• 安全执行：单任务执行可确保内存使用量保持在系统限制内
• 自动排队：有其他任务运行时，新任务会自动排队

任务计划

• 基于 Cron 的计划：使用标准 Cron 表达式实现灵活计划
• 系统要求：仅当系统处于唤醒状态且应用正在运行时，计划任务才会运行
• 补执行：系统恢复运行时，逾期任务会立即执行

定时任务可靠性

补执行逻辑（默认）： 后端在停止后重新启动，或计算机从睡眠中唤醒时，已过期的定时任务会立即执行。延迟超过 5 分钟的任务会在 UI 中显示警告标记，指出任务运行晚了多久（例如，“⚠️ Last run: 45m late”）。周期性任务会根据当前时间计算下次运行时间，以防止延迟不断累积。

延迟细分： 系统会区分两种延迟：

• 系统延迟（睡眠）：计算机处于睡眠状态或后端已停止的时间
• 队列延迟（排队）：等待其他任务完成所花费的时间

UI 会显示延迟细分：“⚠️ Last run: 15m late (sleep: 10m, queued: 5m)”。这有助于你了解延迟是由系统睡眠还是任务队列拥堵造成的。为确保内存安全，任务一次只执行一个，因此系统唤醒后，任务可能会排在补执行任务之后。

作为服务运行（可选）： 如需确保任务执行并在系统启动时自动运行，可以将 Osoba 后端作为系统服务运行。这样可确保后端始终处于运行状态，并能按时执行定时任务。我们提供了适用于 macOS（Launch Agent）、Linux（systemd）和 Windows（NSSM）的设置脚本。详细设置说明请参阅 scripts/README.md。

唤醒调度（高级）： 在支持的系统上，你可以将计算机配置为从睡眠中唤醒，以专门运行定时任务。这需要管理员/root 权限；由于会影响电池续航，建议主要在台式机或接通电源时使用。各平台的说明：

• macOS：使用 pmset 安排唤醒事件
• Linux：使用 RTC 唤醒（需要硬件支持）
• Windows：使用带唤醒计时器的 Task Scheduler

有关唤醒调度的完整设置和故障排除说明，请参阅 scripts/README.md。

要求

• Python 3.11+
• 用于前端的 Node.js（v18+）和 npm/yarn
• 已安装并在本地运行的 Ollama
• 一个 Serper.dev API 密钥（提供免费套餐）
• MongoDB 实例（本地或云端）
• MySQL 服务器（可选，用于 SQL 查询工具）
• 用于网络搜索和下载软件包的互联网连接

语义记忆与文档知识库：

• 安装了 nomic-embed-text 模型的 Ollama：ollama pull nomic-embed-text
• ChromaDB、tiktoken 和 pdfplumber（通过 requirements.txt 自动安装）

可选（启用其他工具）：

• 智能网络搜索：trafilatura、beautifulsoup4、lxml（自动安装）
• Python 数据分析：pandas、numpy、matplotlib、seaborn
• YouTube 转录文本：youtube-transcript-api、pytube、yt-dlp、requests
• HubSpot OAuth：有效的 OAuth 应用（客户端 ID/密钥）和重定向 URL
• Canva 设计：Canva Connect API 访问令牌（请参阅设置说明）
• Figma 设计：Figma Personal Access Token（在 Figma Account Settings → Security → Personal access tokens 中获取）
• Poe AI 模型：Poe API 密钥（从 poe.com/api/keys 获取，需要 Poe 订阅）
• Codex 工作区：PATH 中可用的 Codex CLI（或设置 CODEX_BIN），并已配置 OpenAI API 密钥

安装

1. 克隆代码仓库：

   git clone https://github.com/redbuilding/osoba.git
   cd osoba
   

2. 设置后端：

   • 导航到后端目录：

     cd backend
     

   • 创建并激活虚拟环境：

     python3 -m venv mcp
     source mcp/bin/activate  # On Windows: mcp\Scripts\activate
     

   • 安装 Python 依赖：

     pip install -r requirements.txt
     

   • 在 backend 目录中创建 .env 文件。后端及其管理的 MCP 服务会在此查找环境变量。为安全存储提供商 API 密钥，必须生成一个稳定的加密密钥（Fernet），并设置 SETTINGS_ENCRYPTION_KEY：

     • 安装：pip install cryptography
     • 生成（任选一种）：
       • python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
       • 在 Python REPL 中：from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())
     • 将密钥粘贴到 .env 中，设为 SETTINGS_ENCRYPTION_KEY=...

     
     # 用于加密在模型提供商设置弹窗中输入的 API 密钥
     SETTINGS_ENCRYPTION_KEY=<paste_generated_fernet_key_here>
     
     # 用于智能网页搜索（server_search.py）
     SERPER_API_KEY=your_serper_api_key_here
     
     # 智能提取配置（可选）
     SMART_EXTRACT_MAX_URLS=3
     SMART_EXTRACT_MAX_CHARS_PER_URL=2000
     SMART_EXTRACT_MAX_TOTAL_CHARS=5000
     SMART_EXTRACT_REQUEST_DELAY=1.0
     
     # 用于 MongoDB（main.py）
     MONGODB_URI=mongodb://localhost:27017/
     MONGODB_DATABASE_NAME=mcp_chat_db
     
     # 用于 MySQL 数据库查询（server_mysql.py）
     DB_HOST=localhost
     DB_USER=your_db_user
     DB_PASSWORD=your_db_password
     DB_NAME=your_db_name
     
     # 可选：Canva 设计工具（backend/server_canva.py）
     # 从以下网址获取你的令牌：https://www.canva.com/developers/
     CANVA_API_TOKEN=your_canva_personal_access_token_here
     
     # 可选：Figma 设计工具（backend/server_figma.py）
     # 在 Figma 账户设置 → 安全 → 个人访问令牌中获取你的令牌
     FIGMA_ACCESS_TOKEN=your_figma_personal_access_token_here
     
     # 可选：Poe AI 模型（backend/server_poe.py）
     # 从 https://poe.com/api/keys 获取你的密钥（需要 Poe 订阅）
     POE_API_KEY=your_poe_api_key_here
     
     # 可选：HubSpot OAuth（backend/auth_hubspot.py）
     HUBSPOT_CLIENT_ID=your_hubspot_client_id
     HUBSPOT_CLIENT_SECRET=your_hubspot_client_secret
     HUBSPOT_REDIRECT_URI=http://localhost:8000/auth/hubspot/oauth-callback
     FRONTEND_URL=http://localhost:5173
     
     # 可选：YouTube 字幕服务器（backend/server_youtube.py）
     # YTA_PROXY=https://user:pass@host:port
     # YTA_LOG_LEVEL=INFO
     
     # 可选：后端默认值
     DEFAULT_OLLAMA_MODEL=llama3.1
     OLLAMA_REPEAT_PENALTY=1.15
     
     # Codex MCP 调试状态
     CODEX_DEBUG=false
     

   • 安装其他工具所需的可选依赖（如计划使用）：

     # 智能网页搜索内容提取（推荐）
     pip install trafilatura beautifulsoup4 lxml
     
     # YouTube 字幕工具
     pip install youtube-transcript-api pytube yt-dlp requests
     
     # Python 分析工具
     pip install pandas numpy matplotlib seaborn scipy
     

3. 设置前端：

   • 导航到前端目录：

     cd ../frontend
     

     （如果你位于 backend/ 目录中，否则请从项目根目录导航：cd frontend）
   • 安装 Node.js 依赖：

     npm install
     # or
     # yarn install
     

   • 可选：创建 frontend/.env 并设置自定义 API URL（默认为 http://localhost:8000/api）：

     echo 'VITE_API_URL=http://localhost:8000/api' > .env
     

4. 确保已安装 Ollama 并准备好模型： 应用可能默认使用特定模型（例如，llama3.1）。拉取你想要的模型：

   ollama pull llama3.1
   # or your preferred model like llama3, mistral, etc.
   

   你可以在界面中选择模型，也可以在后端 .env 文件中通过 DEFAULT_OLLAMA_MODEL 配置默认模型。

安全注意事项

⚠️ Osoba 专为本地单用户使用而设计。 API 没有身份验证层。切勿将端口 8000 暴露给不受信任的网络（例如，通过 ngrok、端口转发或绑定到 0.0.0.0）。

• 网络暴露：后端默认绑定到 127.0.0.1。除非你了解风险，否则不要将其更改为 0.0.0.0。
• 加密密钥：在 backend/.env 中设置稳定的 Fernet 密钥 SETTINGS_ENCRYPTION_KEY。否则，每次重启都会丢失提供商 API 密钥。
• MongoDB：默认连接不使用身份验证。对于敏感数据，请启用 MongoDB 身份验证，并使用包含凭据的连接字符串。
• 提供商 API 密钥：密钥使用 Fernet 加密后静态存储，且 API 永远不会返回这些密钥。请妥善保护 .env 文件，并确保其不纳入版本控制。
• MySQL 查询：查询会经过验证，仅允许只读 SELECT 语句，并自动限制为 1000 行。连接和读取超时可防止查询失控。
• CSV 上传：上传内容解码后的大小上限为 50 MB，内存中的 DataFrame 存储最多可容纳 10 个数据集（优先移除最早添加的数据集）。

使用方法

1. 确保前置条件均已启动：

   • Ollama：必须正在运行。
   • MongoDB：必须能够访问 MongoDB 实例。
   • MySQL Server（如果使用 SQL 工具）：MySQL Server 必须正在运行，且可使用 .env 中提供的凭据访问。

2. 启动后端服务： 进入 backend 目录并运行 FastAPI 应用：

   # From the backend directory
   uvicorn main:app --reload --port 8000
   

   后端 API 通常可通过 http://localhost:8000 访问。 FastAPI 应用会通过其生命周期管理器自动启动并管理所有 MCP 服务（Web、SQL、YouTube、HubSpot、Python、Codex），并将它们作为后台进程运行。你不需要单独运行 MCP 服务。

3. 启动前端开发服务： 进入 frontend 目录并运行：

   npm run dev
   # or
   # yarn dev
   

   Web 界面通常可通过 http://localhost:5173 访问（也可能使用 Vite 指定的其他端口）。

与应用交互

• 在浏览器中打开前端 URL（例如，http://localhost:5173）。
• 使用聊天界面发送消息；回复会实时流式显示，并在工具运行时显示相应指示。
• 点击 ✨ 工具选择器，启用以下任一工具：Smart Web Search、Database、YouTube、HubSpot、Python、Canva、Figma、Poe、Codex（需要配置 OpenAI）。
• 使用 Settings（页眉中的设置）配置提供商 API 密钥，以解锁非 Ollama 模型和 Codex。
• 配置用户资料：在 Settings → User Profile 中添加你的角色、专业领域、当前项目和沟通偏好，以获得个性化的 AI 助手服务。
• 设定目标：在 Settings → Goals & Priorities 中定义短期、中期和长期目标（最多 2000 个字符）。AI 会参考这些目标提供情境相关的帮助和主动洞察。
• 启用主动洞察：在 Settings → Goals & Priorities → Heartbeat Settings 中配置心跳服务，定期接收 AI 生成的进度、障碍和建议洞察。点击页眉中的铃铛图标（🔔）查看洞察。
• 置顶对话：将鼠标悬停在侧边栏中的对话上，然后点击置顶按钮，即可将其作为未来聊天的上下文。
  • 如果对话没有摘要，系统会提示你先生成摘要再置顶。生成摘要期间，界面会暂停操作；摘要生成后，对话便会置顶。
  • 最多可置顶 5 个对话。超过上限的操作会被阻止，侧边栏会显示“X/5 pinned”。
  • 摘要由你选择的模型按需生成（参见 Settings → Summaries），并会保存以供重复使用；上下文只会使用已保存的摘要。
• 对于 YouTube：粘贴视频 URL。系统会获取视频文字稿并保存到对话中，供后续交流使用。
• 对于 HubSpot：点击“Connect HubSpot”完成 OAuth，然后描述要创建或更新的邮件。
• 对于 Canva：在 .env 中设置 CANVA_API_TOKEN，然后让 AI 创建设计（例如，“创建一个名为 'AI in 2025' 的 YouTube 缩略图”）、列出设计、上传素材、导入文件或将设计导出为 PDF。
• 对于 Figma：在 .env 中设置 FIGMA_ACCESS_TOKEN，然后让 AI 读取 Figma 文件（例如，“获取 Figma 文件 ABC123 的结构”）、将指定画板导出为图片、提取设计系统令牌，或列出／发布评论。
• 对于 Poe：在 .env 中设置 POE_API_KEY，然后让 AI 生成图片（例如，“生成一张 16:9 的山间日落横向图片”）、与前沿模型聊天，或生成视频／音频。
• 对于 Python：按提示上传 CSV 文件；后续问题会复用已加载的 DataFrame，以进行筛选、分组、异常值检测、统计检验和可视化等高级分析。
• 使用侧边栏管理对话（新建、选择、重命名、删除，或置顶以用作上下文）。

长时运行任务（规划与执行）

• 打开任务面板（点击页眉中的“任务”按钮）以：
  • 输入高级目标，创建新任务。
  • 监控进度（实时 SSE 流）、查看步骤输出（表格、图像、文本），并暂停、恢复或取消任务。
  • 在任意用户聊天消息中选择“提升为任务”，自动填入目标并将任务关联到对话。
  • 使用专用复制按钮复制完整任务结果或单个步骤输出。
  • 删除已完成、失败或已取消的任务，以清理任务列表。
  • 后端会将每项任务规划为结构化 JSON（步骤、工具、参数、成功标准），然后按顺序执行步骤，并提供：
  • 预算：最长运行时间和最大工具调用次数。
  • 单步超时，以及带退避的有限重试次数。
  • 根据成功标准验证输出。
• 完成：最后一步结束后，任务状态变为 COMPLETED。若发生故障、超时或超出预算，状态则为 FAILED。系统会将简明摘要发布回关联的对话。
  • 配置了 OpenAI 密钥时，规划器可能会针对脚手架搭建/创建目标提出 codex.run 步骤；否则，此类步骤会自动禁用。

API：

• 创建任务：POST /api/tasks { goal, conversation_id?, dry_run? }
• 列出任务：GET /api/tasks
• 任务详情：GET /api/tasks/{id}
• 任务流（SSE）：GET /api/tasks/{id}/stream
• 暂停/恢复/取消：POST /api/tasks/{id}/pause|resume|cancel
• 删除任务：DELETE /api/tasks/{id}
• 状态：GET /api/status 包含 tasks.active 计数

仅限大模型的步骤（无需 MCP）：

• 规划器支持直接通过 Ollama 运行的 llm.generate 步骤，无需任何 MCP 服务。如果省略 prompt，则使用步骤的 instruction。这些步骤同样遵守预算、超时和验证规则。

旧版客户端（已移除）

原有的 chat_client.py（终端）和 chat_frontend.py（Gradio）已从代码库中移除，因为它们不再兼容当前的 FastAPI 后端架构。现在，所有功能均通过现代 React 前端提供。

Python 数据分析工具

Python MCP 服务通过以下工具提供全面的数据分析能力：

核心数据操作

• load_csv - 从 base64 编码字符串加载 CSV 数据
• get_head - 显示 DataFrame 的前 N 行
• get_data_info - 提供全面的 DataFrame 信息（数据类型、内存用量、非空值计数）
• get_descriptive_statistics - 数值列的统计摘要

数据质量与清洗

• check_missing_values - 检查各列中的缺失值
• handle_missing_values - 处理缺失数据（删除、填充、插值）
• convert_data_types - 安全地转换数据类型（日期时间、类别、数值）
• detect_outliers - 使用 IQR 或 Z-score 方法检测异常值

数据处理与分析

• filter_dataframe - 使用带安全验证的 pandas 查询语法筛选数据
• group_and_aggregate - 按列分组并应用聚合函数
• query_dataframe - 执行高级 DataFrame 查询并创建新的 DataFrame
• rename_columns - 重命名 DataFrame 列
• drop_columns - 删除指定列

统计分析

• get_correlation_matrix - 计算数值列的相关矩阵
• get_value_counts - 对类别列进行频数分析
• perform_hypothesis_test - 执行统计假设检验：
  • 双样本 t 检验
  • Pearson 相关性检验
  • 卡方独立性检验

数据可视化

• create_plot - 生成多种类型的图表：
  • 散点图
  • 直方图
  • 条形图
  • 箱线图
  • 返回 base64 编码的图像，以便在网页中显示

所有工具都通过内存中的 DataFrame 存储维护会话状态，因此可在单次对话中执行复杂的多步骤分析工作流。

用户档案与上下文 AI 辅助

该应用通过用户档案和对话上下文管理提供个性化 AI 辅助：

用户档案配置

• 个人信息：配置你的角色、专业领域、当前项目和沟通偏好
• 上下文理解：AI 会了解你的背景，并据此调整回复
• 设置集成：通过“设置”→“用户档案”轻松配置

对话上下文系统

• 选择性固定：选择特定对话，作为未来聊天的上下文
• 可视化控制：通过直观的控件直接从侧边栏固定/取消固定对话
• 自动摘要：需要时，系统会自动为已固定的对话生成摘要
• 混合摘要方式：同时记录用户问题和助手解决方案，提供完整上下文
• 上下文连续性：AI 可以参考之前的问题和解决方案，提供连贯的帮助
• 智能限制：上下文总预算约为 2700 个字符（200 个字符用于档案，最多 2500 个字符用于 已固定对话的摘要）
• 持久化存储：生成的摘要会被存储并重复使用，避免重新生成

个性化 AI 回复

AI 会结合你的档案信息和已固定对话的上下文，提供：

• 相关建议：根据你的角色和当前项目提供建议
• 适当的复杂度：技术深度与你的专业水平相匹配
• 连贯的上下文：能够参考之前的工作并保持对话连续性
• 了解解决方案：知道已经尝试过哪些方法，并能以此为基础继续推进
• 自适应沟通：根据你的偏好调整回复风格

用户档案与 AI 配置

• 用户档案：关于你自己的信息（角色、项目、偏好）——帮助 AI 了解它正在与谁交谈
• AI 档案：AI 行为和个性的配置——定义 AI 应如何行动
• 综合效果：打造个性化互动，让 AI 同时了解你是谁以及它应该如何回复

技术实现

• 自动生成摘要：固定对话时，根据最近 5 条消息按需生成摘要
• 混合摘要格式：同时包含用户问题和助手的关键解决方案（例如，“用户问题 | 已解决：pandas、matplotlib”）
• 智能提取解决方案：从助手回复中识别代码示例、工具推荐和解决方案模式
• 用户隔离：按用户筛选对话，防止不同用户之间的上下文泄漏
• 性能优化：摘要只生成一次并存储，以便在多个聊天中重复使用

语义记忆系统

Osoba 配备了先进的语义记忆系统，支持无限量存储对话并进行智能语义搜索，突破了最多固定 5 个对话的限制。

工作原理

自动索引：

• 含有 5 条或更多消息的对话在闲置 10 分钟后会自动编入索引
• 使用 nomic-embed-text（通过 Ollama）生成本地嵌入，保护隐私
• 将对话片段存储在 ChromaDB 向量数据库中，以便进行语义搜索
• 非阻塞后台进程确保不会影响聊天性能

语义搜索：

• 按含义搜索，而不仅仅是关键词——查找概念上相似的对话
• 相关性评分显示结果与查询的匹配程度（例如，“匹配度 87%”）
• 自动将相关的过往对话注入新聊天
• 仅纳入相似度高于 60% 阈值的对话，避免噪声

记忆浏览器（Ctrl+Shift+M）：

• 对所有已编入索引的对话进行全文语义搜索
• 预览带有相关性评分的片段
• 从记忆中移除单个对话
• 使用键盘快捷键快速访问

主要功能

无限存储：

• 没有人为限制，可存储数千条对话
• 智能分块（512 个词元，重叠 50 个词元），保留上下文
• 根据保留策略自动清理（可配置）

智能上下文注入：

• 自动将相关的过往对话添加到聊天上下文中
• 仅包含最相关的对话（而非所有已索引的对话）
• 在遵守上下文窗口限制的同时，最大限度提高相关性

隐私优先：

• 通过 Ollama 在本地生成嵌入（不调用外部 API）
• 所有数据都存储在本地 ChromaDB 中
• 对话数据不会离开你的设备

使用语义记忆

手动保存：

• 点击“💾 Save to Memory”按钮（对包含 5 条以上消息的对话显示）
• 立即为该对话建立索引，供日后参考

自动索引：

• 对话在包含 5 条以上消息且闲置 10 分钟后自动建立索引
• 后台服务每 5 分钟检查一次符合条件的对话
• 无需用户操作

搜索记忆：

1. 按 Ctrl+Shift+M 打开记忆浏览器
2. 输入搜索查询（例如，“Python pandas dataframe”）
3. 查看带有相关性评分和预览文本的结果
4. 点击即可查看或移除对话

记忆管理：

• 前往“Settings → Semantic Memory”查看统计信息和控制选项
• 查看已索引对话总数和存储用量
• 手动触发自动索引检查
• 清除所有记忆（需确认）

技术详情

嵌入模型：

• nomic-embed-text（768 维嵌入）
• 通过 Ollama 在本地运行
• 无 API 费用或速率限制

向量数据库：

• 使用 ChromaDB 进行持久化向量存储
• 高效相似度搜索（典型查询耗时 <100ms）
• 自动持久化到磁盘

上下文集成：

• 语义记忆在配置文件上下文之后注入
• 格式为“Relevant past conversations”部分
• 包含对话标题、相关性评分和预览文本

相较于置顶的优势

功能	置顶（最多 5 条）	语义记忆
容量	5 条对话	无限
选择方式	手动	根据相关性自动选择
搜索	无	语义搜索
上下文效率	包含全部 5 条	仅包含相关对话
管理方式	手动置顶/取消置顶	自动索引

文档知识库

文档知识库支持上传持久化参考资料——SOP、研究论文、规范、文档等，并让 AI 在每次对话中自动参考这些内容，就像语义记忆会参考过往聊天一样。

支持的格式

格式	扩展名	解析器
纯文本	.txt	UTF-8 解码
Markdown	.md	UTF-8 解码
Word 文档	.docx	python-docx
PDF	.pdf	pdfplumber
网页	URL	trafilatura

每份文档的大小上限：200,000 个字符。

工作原理

Upload (file / URL)
    ↓
document_parser.py  ← extracts plain text
    ↓
documents_crud.py   ← stores metadata + raw text in MongoDB ("documents" collection)
    ↓
document_indexing.py ← chunks text → embeds via nomic-embed-text → stores in ChromaDB ("documents" collection)
    ↓
kb_context.py       ← at chat time: embeds query, searches "documents", formats snippets
    ↓
chat_service.py     ← injects "=== Knowledge Base ===" section into system prompt

超过 50,000 个字符的文档会在后台建立索引，以便上传请求立即返回。

打开知识库面板

• 键盘快捷键：Ctrl+Shift+K
• 标题栏按钮：点击顶部导航栏中的“KB”

文档标签页

• 拖放上传，或点击“Choose File”选择 .txt、.md、.docx 或 .pdf 文件
• URL 导入：粘贴任意 URL，然后点击“Add URL”（或按 Enter）以抓取网页并建立索引
• 文档卡片显示：类型徽标（按颜色区分）、索引状态圆点（绿色 = 就绪，琥珀色 = 等待中）、字符数、上传日期和删除按钮
• 上传后立即为文档建立索引（大型文件则在后台建立索引）

搜索标签页

• 输入查询，即可对所有已索引的文档块进行语义搜索
• 结果显示文档标题、相关性百分比和文本摘要

侧边栏状态

左侧边栏页脚会实时显示已索引文档的数量。至少有一份文档可用时，指示点会变为绿色。

聊天集成

发送消息时，后端会：

1. 使用 nomic-embed-text 为你的查询生成嵌入
2. 在 documents ChromaDB 集合中搜索最相关的前 5 个文本块（分数 ≥ 0.4）
3. 将匹配结果格式化为 === Knowledge Base === 部分，与语义记忆一同注入系统提示词

当文档内容与问题相关时，AI 会引用这些内容，你无需在每条消息中手动添加。

在任务中使用知识库文档

创建任务时，你可以明确附加 1–2 份已编入索引的知识库文档，为规划器和步骤 Agent 提供参考材料。此功能完全可选：如果未附加文档，任务的行为与之前完全一致。

附加方法：

1. 打开 任务 面板（Ctrl+Shift+T 或点击「任务」标题按钮）
2. 输入你的目标
3. 点击 「添加知识库文档」——内嵌下拉菜单会列出所有已编入索引的文档
4. 最多选择 2 份文档；每份文档都会以可关闭的标签显示在输入框下方
5. 点击运行按钮——所选文档会作为 kb_doc_ids 发送到请求负载中

底层处理过程：

Task creation request (with kb_doc_ids)
    ↓
api/tasks.py  — fetches each doc from MongoDB, excerpts up to 4,000 chars each
    ↓ stores {kb_docs: [{id, title}], kb_context: "=== Knowledge Base ===\n..."} in task doc
         ↓                              ↓
task_planner.py              task_runner.py
(planning prompt includes     (every LLM step gets kb_context
 "Reference material" block)   as the 2nd message after system)

限制：

约束	值
每个任务的文档数上限	2
每份文档摘录的字符数上限	4,000
知识库上下文字符串总长度上限	约 9,000 个字符
仅可选择已编入索引的文档	是
创建时保存内容快照	是——在所有步骤中保持一致
仅注入大模型步骤	是——不会注入 MCP 工具步骤

**任务详情视图：**附加的文档会以小标签显示在任务标题中，让你一眼就能看到提供了哪些上下文。

**提示：**对于涉及遵循既定流程的任务，请附加 SOP 或规范文档。规划器会将文档中的限制纳入步骤设计，每个大模型生成步骤都可以使用完整摘录。

API 端点

方法	路径	描述
POST	/api/documents/upload	上传文件（请求体为 base64 编码的 JSON）
POST	/api/documents/url	从 URL 导入
GET	/api/documents	列出所有文档
GET	/api/documents/{id}	获取文档详情（包含内容）
DELETE	/api/documents/{id}	从 MongoDB + ChromaDB 删除
GET	/api/documents/search?q=...	对文档文本块进行语义搜索
GET	/api/documents/stats	统计数量、字符数和文本块数

上传请求负载格式：

{
  "filename": "spec.pdf",
  "data_b64": "<base64 string>",
  "title": "Product Spec",
  "description": "Optional description",
  "user_id": "default"
}

后端文件

文件	用途
backend/db/document_store.py	DocumentVectorStore——ChromaDB "documents" 集合
backend/db/documents_crud.py	文档元数据的 MongoDB CRUD
backend/services/document_parser.py	文件/URL → 纯文本提取
backend/services/document_indexing.py	分块 + 嵌入 + 存储管线
backend/services/kb_context.py	查询时上下文构建器
backend/api/documents.py	FastAPI 路由器（/api/documents）

Agent 主动心跳系统

增强型心跳系统通过自动生成洞察和创建任务，提供主动的 AI 协助。它会分析你的目标、对话、项目状态和系统运行状况，从而建议可执行的后续步骤。

主要功能

上下文收集：

• 语义记忆：对话历史、已编入索引的对话、存储空间使用情况
• Git 仓库：当前分支、未提交文件、未推送提交、近期提交
• 项目文件：TODO/FIXME 注释、近期修改的文件
• 系统运行状况：磁盘使用情况、服务状态

自动创建任务：

• 洞察可以自动创建跟踪任务
• 可通过「创建任务」按钮手动转换
• 任务会关联到洞察，便于跟踪

基于文件的配置（高级用户）：

• 在 HEARTBEAT.md 中定义心跳任务
• 按类别组织任务
• 自定义计划（cron 或间隔格式）
• 文件与 UI 之间双向同步

工作原理

心跳服务会在后台按可配置的间隔运行（默认：每 2 小时一次）。每次心跳期间：

1. 收集上下文：收集目标、对话、任务和增强上下文（记忆、Git、项目、系统）
2. AI 分析：将上下文发送给你选择的大模型（默认使用 Haiku，兼顾成本效益，约为每位用户每天 0.01 美元）
3. 生成洞见：AI 生成可执行的洞见和建议，或识别阻碍因素
4. 智能筛选：使用“HEARTBEAT_OK”模式，在一切进展顺利时抑制通知
5. 创建任务：可选择根据洞见创建跟踪任务
6. 通知：在铃铛图标面板（标题栏右上角）中显示洞见

快速入门

1. 启用心跳：

• 设置 → 主动心跳
• 切换“启用心跳”
• 选择检查间隔（30m、1h、2h、4h、6h）

2. 配置上下文来源：

• 启用语义记忆（推荐）
• 启用 Git 仓库（推荐）
• 可选：启用项目文件和系统健康状态

3. 启用自动创建任务（可选）：

• 切换“自动创建任务”
• 系统将根据洞见自动创建跟踪任务

4. 设置目标：

• 设置 → 目标与优先级
• 输入你的目标文档（最多 2000 个字符）

使用 HEARTBEAT.md（高级用户）

在项目根目录中创建 HEARTBEAT.md：

# Heartbeat Tasks

## Memory Management
Schedule: 0 2 * * *
Enabled: true
Prompt: Review semantic memory usage and suggest cleanup if storage exceeds 100MB
Context: memory

## Testing Reminders
Schedule: 0 9 * * 1
Enabled: true
Prompt: Check test coverage and suggest missing tests
Create_Task: true
Context: git,project

同步选项：

• 从文件加载：将 HEARTBEAT.md 中的任务导入数据库
• 保存到文件：将已配置的任务导出到 HEARTBEAT.md

使用洞见

1. 查看通知：点击标题栏中的铃铛图标（🔔）

• 徽标显示未读洞见数量
• 下拉面板显示近期洞见

2. 查看洞见：每条洞见都包含：

• 标题：洞见的简要概述
• 描述：详细建议或观察
• 时间戳：生成洞见的时间
• 创建任务按钮：将洞见转换为跟踪任务

3. 忽略洞见：点击“忽略”，移除已处理的洞见

4. 手动触发：立即强制执行一次心跳检查：

curl -X POST "http://localhost:8000/api/heartbeat/trigger?user_id=default"

洞见示例

进度检查：

标题：“身份验证功能进度”
描述：“你提到本周要完成身份验证功能。最近的对话显示你正在处理密码重置。将其标记为完成前，可以考虑测试边缘情况。”

识别阻碍因素：

标题：“设计模型阻碍”
描述：“你的目标提到正在等待设计模型。你记录这个阻碍因素后已经过去 3 天。可以考虑联系设计团队，或自行创建线框图。”

任务建议：

标题：“API 文档提醒”
描述：“你有 5 个与 API 端点相关的已完成任务，但没有文档任务。可以考虑创建任务，为新的端点编写文档。”

HEARTBEAT_OK（无通知）： 一切进展顺利时，AI 会回复“HEARTBEAT_OK”，不会创建通知，从而减少干扰。

成本考量

• 默认模型：Claude Haiku 4.5（每 100 万个输入 token 约 0.25 美元）
• 典型成本：每 2 小时检查一次时，每位用户每天约 0.01 美元
• 上下文大小：约 1500 个 token（目标 + 3 条对话 + 5 个任务）
• 每日心跳次数：每天检查 12 次（每 2 小时一次）= 约 18K 个 token = 0.0045 美元

成本优化：

• 使用更长的间隔（3-4 小时），降低检查频率
• 通过活跃时段设置，在非工作时段禁用
• 使用本地 Ollama 模型（免费），而非托管服务提供商
• 保持目标文档简洁

隐私与数据

• 本地处理：所有上下文都保留在你的系统内
• 无外部存储：洞见仅存储在你的 MongoDB 中
• 用户隔离：每位用户的目标和洞见完全独立
• 随时选择退出：在设置中禁用，或删除目标文档

故障排除

未显示洞察：

1. 检查设置中是否启用了心跳
2. 确认当前时间处于活跃时段内
3. 确保目标文档已保存
4. 检查后端日志是否有错误

通知过多：

1. 延长间隔（例如，2h → 4h）
2. 将活跃时段调整为仅限工作时间
3. 检查目标文档，使其描述更具体

洞察不相关：

1. 更新目标文档，写入当前优先事项
2. 补充有关阻碍因素和进展的背景信息
3. 固定相关对话，以提供更好的上下文

API 参考

获取洞察：

GET /api/heartbeat/insights?user_id=default&dismissed=false

忽略洞察：

POST /api/heartbeat/insights/{insight_id}/dismiss?user_id=default

获取配置：

GET /api/heartbeat/config?user_id=default

更新配置：

PUT /api/heartbeat/config?user_id=default
Content-Type: application/json

{
  "enabled": true,
  "interval": "2h",
  "active_hours": {
    "start": "09:00",
    "end": "18:00",
    "timezone": "America/New_York"
  }
}

手动触发：

POST /api/heartbeat/trigger?user_id=default

智能网页搜索与内容提取

智能网页搜索 MCP 服务提供了先进的网页搜索功能，远超基本的搜索摘要：

智能内容提取

• 多方法提取：主要使用 trafilatura，并在必要时回退到 BeautifulSoup，以实现最高可靠性
• 完整网页内容：提取完整文章，而不只是搜索摘要
• 内容清理：移除 HTML 标签、规范化空白字符并处理实体
• 结构保留：保留标题、段落和内容层级

URL 优先级算法

• 相关性评分：根据标题和摘要中与查询词的匹配情况为 URL 排序
• 位置加权：考虑搜索结果位置和域名权威性
• 智能筛选：优先选取文档、教程和权威来源

礼貌且合乎伦理的爬取

• 遵循 robots.txt：自动检查并遵守 robots.txt 文件
• 速率限制：请求之间的延迟可配置（默认：1 秒）
• 规范标识：使用描述性的 User-Agent 标头
• 超时处理：无法访问网站时优雅地恢复失败

配置选项

通过环境变量配置提取行为：

SMART_EXTRACT_MAX_URLS=3              # Maximum URLs to extract (default: 3)
SMART_EXTRACT_MAX_CHARS_PER_URL=2000  # Character limit per webpage (default: 2000)
SMART_EXTRACT_MAX_TOTAL_CHARS=5000    # Total character limit (default: 5000)
SMART_EXTRACT_REQUEST_DELAY=1.0       # Delay between requests (default: 1.0s)

性能与质量

• 上下文增加 8 倍：提供的内容远多于基本搜索摘要
• 高成功率：多方法提取确保可靠地获取内容
• 内存高效：字符数限制可防止上下文溢出
• 处理快速：礼貌延迟下，处理 3 个 URL 通常需要 3–5 秒

智能搜索功能会在所有网页搜索中自动启用——用户无需进行额外配置或更改 UI，即可获得增强的内容提取能力。

模型提供商与设置

• 支持的提供商：ollama（本地）、openai、anthropic、google（Gemini）、openrouter、groq、sambanova。
• 打开设置弹窗（标题栏 → Settings），为各个提供商添加/验证 API 密钥。系统会通过轻量级请求验证密钥（OpenAI 会使用较小的 max_tokens=16 进行检查，以避免误判）。
• 模型选择器会按提供商显示模型。只有在提供商完成配置后，才会显示非 Ollama 模型。
• 提供商模型命名/前缀（示例）：
  • Ollama：llama3.1（无前缀）。
  • OpenAI：openai/gpt-5.6-sol。
  • Anthropic：anthropic/claude-sonnet-5。
  • Google：gemini/gemini-flash-latest。
  • OpenRouter：openrouter/z-ai/glm-5.3。
  • Groq：groq/openai/gpt-oss-20b。
  • SambaNova：sambanova/Meta-Llama-3.3-70B-Instruct。

API 端点：

• 列出提供商：GET /api/providers
• 提供商模型：GET /api/providers/models
• 提供商状态：GET /api/providers/{provider_id}/status
• 保存 API 密钥：POST /api/providers/settings { provider, api_key }
• 移除 API 密钥：DELETE /api/providers/{provider_id}/settings
• 验证（不返回密钥）：GET /api/providers/{provider_id}/validate
• 所有模型（包含提供商的扁平列表）：GET /api/models
• 模型诊断扫描：POST /api/providers/test-models { conversation_id?, include_ollama } — 对每个已配置的模型执行一次最简真实调用，并将结构化的 Model Diagnostics 报告发布到聊天对话中。

模型诊断（实时冒烟测试）： 在模型选择器中点击 Test Models，即可对每个已配置的提供商模型（以及已安装的 Ollama 模型）执行一次单句真实调用。每个模型的状态、延迟和回复/错误都会以结构化报告的形式发布到当前聊天中（如果当前没有对话，则会创建一个新的 Model Diagnostics 对话）。模型按顺序测试，每个模型超时为 30s，以遵守速率限制。

注意：

• Codex MCP 需要有效的 OpenAI API 密钥。如果尚未配置 OpenAI，界面会禁用 Codex 工具。

提供商 API 密钥加密（必需）：

• 后端使用通过 backend/.env 中的 SETTINGS_ENCRYPTION_KEY 设置的 Fernet 密钥，对提供商 API 密钥进行静态加密。
• 生成一次并在重启期间保持不变；更改密钥会使之前保存的密钥失效（你需要重新输入）。
• 生成并设置：
  • pip install cryptography
  • python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
  • 在 backend/.env 中设置：SETTINGS_ENCRYPTION_KEY=<output>

Codex 工作区（MCP）

代码生成在隔离的工作区中运行，并提供可审核的清单和产物。

• 界面：点击 ✨ 工具选择器，然后选择“Codex（Workspace）”。输入一条指令（例如，“搭建一个 Vite + React 应用”）。助手会插入一条内嵌的 codex_run 消息，实时显示状态，并在完成时显示简要摘要。
• 后端：FastMCP 服务（backend/server_codex.py）提供用于创建工作区、启动／轮询／取消运行、读取文件和获取清单的工具。运行采用异步方式，并使用一个小型内存任务跟踪器。产物写入工作区下的 codex_artifacts/。
• 安全措施：每次运行使用专属工作区，HOME 隔离在工作区内，拒绝符号链接，并执行 realpath 包含性检查；还可选择运行后输出策略（允许的扩展名、点文件白名单、最大文件数／字节数、二进制文件启发式检测）。如需最强隔离，请在不联网的容器／虚拟机中运行该服务。
• 要求：Codex CLI 可通过 PATH 使用（或设置 CODEX_BIN），并且具有有效的 OPENAI_API_KEY（通过 Settings 或环境变量提供）——密钥只会注入 Codex 子进程。

端点：

• 创建工作区：POST /api/codex/workspaces { name_hint, keep }
• 启动运行（若工作区不存在则自动创建）：POST /api/codex/runs { workspace_id, instruction, model?, timeout_seconds? }
• 获取运行状态：GET /api/codex/runs/{run_id}
• 取消运行：POST /api/codex/runs/{run_id}/cancel
• 获取清单：GET /api/codex/workspaces/{workspace_id}/manifest
• 读取文件：GET /api/codex/workspaces/{workspace_id}/file?relative_path=…

环境变量（可选，显示默认值）：

• CODEX_BIN=codex，CODEX_WORKSPACES_DIR=./.codex_workspaces，CODEX_MAX_CONCURRENCY=1，CODEX_RUN_TTL_HOURS=48
• CODEX_MAX_PROMPT_CHARS=20000，CODEX_MAX_STDOUT_CHARS=200000，CODEX_MAX_STDERR_CHARS=50000
• CODEX_MAX_OUTPUT_FILES=500，CODEX_MAX_OUTPUT_TOTAL_BYTES=20971520，CODEX_DEBUG=false

前端体验说明：

• Codex 运行现在以内嵌聊天消息（type='codex_run'）的形式呈现，并保留在对话记录中。旧的浮动运行卡片已移除。
• 侧边栏会显示 Codex MCP 状态；只有当服务已就绪且 OpenAI 已配置时，状态才会显示为绿色。
• 文件查看器模态框已准备好供未来通过清单／文件 API 使用；为避免出现失效链接，目前不会自动触发。

Canva 设计工具（MCP）

无需离开 Osoba，即可创建、浏览、导入、调整大小和导出 Canva 设计。Canva MCP 服务使用 OAuth 2.0 访问令牌连接到 Canva Connect API。

设置

1. 前往 canva.com/developers 并登录（需要 MFA）。
2. 前往 Your integrations → Create an integration。
3. 在 Scopes 下启用：design:content（读取和写入）、design:meta（读取）、asset（读取和写入）。如需自动填充，还要启用 brandtemplate:meta（读取）和 brandtemplate:content（读取）。
4. 在 Authentication 下添加重定向 URL（例如 http://127.0.0.1:3000/redirect）。
5. 生成测试令牌：前往任意一个 API 参考页面 → 滚动到“Try it out” → 点击 "Generate an access token" → 完成浏览器内的 OAuth 流程 → 复制令牌。
6. 将令牌添加到 backend/.env：

CANVA_API_TOKEN=your_access_token_here

注意： 测试令牌 4 小时后过期。如需长期使用，需要实现完整的 OAuth 2.0 Authorization Code 流程并使用刷新令牌。

后端会自动启动 Canva 服务，并与所有其他 MCP 服务一起运行——无需单独启动进程。若要在不移除令牌的情况下禁用该服务，请在 .env 中设置 DISABLED_MCP_SERVICES=canva_service。

工具

工具	参数	功能
create_design	title、preset?、width?、height?、unit?、template_id?	按指定尺寸创建一个新的空白 Canva 设计
list_designs	limit?、page_token?	分页列出账户中的设计
get_design	design_id	获取设计的元数据和编辑器 URL
get_design_pages	design_id	获取多页设计的页面元数据
export_design	design_id、format?、pages?	导出设计并返回下载 URL
upload_asset	name、url	从公开 URL 上传图片/视频到用户的 Canva 资源库
autofill_design	brand_template_id、data、title?	使用文本/图片数据填充品牌模板以创建设计（Enterprise）
get_brand_template_dataset	brand_template_id	查找品牌模板中可自动填充的字段（Enterprise）
import_design	title、url、mime_type?	从 URL 导入文件（PDF、PPTX、DOCX、PSD、AI、Keynote 等），并将其转换为可编辑的 Canva 设计
resize_design	design_id、width、height	创建现有设计的调整尺寸副本（Pro/Enterprise）

支持的预设（适用于 create_design）：

预设	尺寸	用途
presentation	Canva 原生类型	幻灯片
instagram_post	1080×1080	方形帖子
instagram_story	1080×1920	快拍 / Reels
facebook_post	1200×630	信息流帖子
facebook_cover	820×312	页面封面
twitter_post	1200×675	Twitter/X 帖子
linkedin_banner	1584×396	个人资料横幅
youtube_thumbnail	1280×720	视频缩略图
a4	595×842	文档
us_letter	612×792	US Letter 文档
custom	用户自定义	需要以像素为单位提供 width 和 height

导出格式：png（默认）、jpg、pdf、pptx、svg、mp4、gif

在聊天中

从 ✨ 工具选择器中选择 Canva 工具，然后直接提出需求：

• “列出我最近的 Canva 设计”
• “创建一个标题为‘AI 的未来’的 YouTube 缩略图”
• “将设计 DABcd1234 导出为 PDF”
• “将这张图片上传到我的 Canva 资源库：https://example.com/photo.jpg”
• “获取设计 DABcd1234 的页面”
• “将这个演示文稿导入 Canva：https://example.com/deck.pptx”

AI 会选择合适的工具并执行，然后返回结果（编辑器 URL、下载链接、资源 ID 等）。

在任务中

任务规划器可使用 Canva 工具执行多步骤自主工作流。规划器可识别以下工具别名：design、canva_create、export、canva_export、canva_list、canva_get、canva_upload、canva_autofill、canva_import、canva_resize、canva_pages。

任务目标示例：

• “研究 2025 年排名前 5 的 AI 工具，并创建一个总结研究结果的 LinkedIn 横幅”
• “为产品发布创建演示文稿幻灯片结构，然后将其导出为 PDF”
• “列出我所有的 Canva 设计，找到最近的演示文稿，并将其导出为 PNG”

规划器会自动串联 web_search → llm.generate → create_design → export_design 步骤，并将每一步的输出作为下一步的输入。

文件

文件	用途
backend/server_canva.py	FastMCP 服务 — 10 个 MCP 工具
backend/utils/canva_client.py	异步 httpx 客户端、Pydantic 模型、轮询逻辑
backend/tests/test_canva_mcp.py	77 个单元测试（无需 API 令牌）

Figma 设计工具（MCP）

无需离开 Osoba，即可读取、检查和导出 Figma 设计。Figma MCP 服务使用你的个人访问令牌连接到 Figma REST API。

设置

将令牌添加到 backend/.env：

FIGMA_ACCESS_TOKEN=your_figma_personal_access_token_here

前往 Figma → Account Settings → Security → Personal access tokens 获取令牌。后端会在启动所有其他 MCP 服务的同时自动启动 Figma 服务，无需单独启动进程。如需禁用该服务但保留令牌，请在 .env 中设置 DISABLED_MCP_SERVICES=figma_service。

所有工具使用的文件密钥，是 Figma 文件 URL 中的字母数字 ID： figma.com/file/{file_key}/file-name

工具

工具	参数	功能
figma_get_file	file_key, depth?	获取完整的文件结构和元数据（节点树、组件、样式）
figma_get_nodes	file_key, node_ids, depth?	按逗号分隔的 ID 获取指定节点（例如 "1:2,3:4"）
figma_export_images	file_key, node_ids, format?, scale?	将节点导出为图像，并返回临时下载 URL
figma_get_comments	file_key	列出文件中的所有评论
figma_post_comment	file_key, message, node_id?, parent_id?	发布评论，可选择将评论关联到某个节点或回复其他评论
figma_get_design_system	file_key	提取颜色令牌、排版、间距令牌和组件目录

导出格式（用于 figma_export_images）：png（默认）、jpg、svg、pdf

缩放比例（用于 figma_export_images）：0.01–4.0，默认为 1.0

注意：figma_export_images 返回的导出 URL 是临时的（由 Figma 的 CDN 托管）。请尽快下载，它们会在几小时内过期。

速率限制

Figma 免费套餐允许每小时 1000 次请求。客户端会使用滑动窗口令牌桶，自动将请求控制在此限制内。如果你的付费套餐有更高的限制，可以通过环境变量覆盖：

FIGMA_RATE_LIMIT_REQUESTS=5000   # requests per window (default: 1000)
FIGMA_RATE_LIMIT_WINDOW=3600     # window in seconds (default: 3600)

在聊天中使用

启动 Figma 服务后，可以直接向 AI 提出请求：

• “获取 Figma 文件 ABC123 的结构”
• “将文件 ABC123 中的主视觉画框（节点 1:23）导出为 PNG”
• “Figma 文件 ABC123 中有哪些评论？”
• “从我们的品牌文件 XYZ789 中提取设计系统令牌”
• “在文件 ABC123 的节点 5:10 上发表评论：‘请在此处提高对比度’”

AI 会调用相应的工具，并直接在聊天中返回结果，包括节点树、导出 URL、评论串或令牌列表。

在任务中使用

任务规划器可使用 Figma 工具执行多步骤自主工作流。规划器可识别以下工具别名：figma_file、figma_nodes、figma_images、figma_comments、figma_comment、figma_design_system、figma_tokens。

任务目标示例：

• “获取 Figma 文件 ABC123，提取所有颜色和排版令牌，然后生成 CSS 变量文件”
• “将 Figma 文件 ABC123 中的所有画框导出为 PNG 图像，并列出其下载 URL”
• “检查 Figma 文件 ABC123 中的设计系统令牌，并撰写颜色调色板摘要”

规划器会自动串联 figma_get_design_system → llm.generate 步骤，以生成所需的交付内容。

文件

文件	用途
backend/server_figma.py	FastMCP 服务——6 个 MCP 工具
backend/utils/figma_client.py	异步 httpx 客户端、Pydantic 模型、速率限制器
backend/tests/test_figma_mcp.py	54 个单元测试（无需 API 令牌）

Poe AI Models（MCP）

无需离开 Osoba，即可访问 Poe 平台上的数百种 AI 模型，涵盖文本、图像、视频和音频生成。Poe MCP 服务使用你的 API 密钥连接到 Poe OpenAI-compatible API。

设置

1. 前往 poe.com/api/keys（需要 Poe 订阅）。
2. 生成 API 密钥。
3. 将其添加到 backend/.env：

POE_API_KEY=your_poe_api_key_here

后端会在启动所有其他 MCP 服务的同时自动启动 Poe 服务，无需单独启动进程。如需禁用该服务但保留密钥，请在 .env 中设置 DISABLED_MCP_SERVICES=poe_service。

工具

工具	参数	功能说明
poe_list_models	input_modality?、output_modality?、search?、limit?	列出可用的 Poe 模型，可按模态（文本／图像／视频／音频）或名称筛选
poe_chat	prompt、model?、system?、temperature?、max_tokens?、image_urls?	与任意 Poe 模型进行文本对话（默认：Claude-Sonnet-4-6）
poe_generate_image	prompt、model?、system?、aspect_ratio?、download_media?	生成图像并返回 URL，以及可选的 base64 数据
poe_generate_video	prompt、model、system?、download_media?	生成视频（必须指定模型，可使用 poe_list_models 查找）
poe_generate_audio	prompt、model、system?、download_media?	生成音频／TTS／音乐（必须指定模型）

宽高比（用于 poe_generate_image）：9:16（纵向，例如快拍／短视频），16:9（横向，例如 YouTube 缩略图）。省略时使用模型的默认值（通常为 1:1 正方形）。

默认图像模型：gpt-image-1.5（OpenAI 的最新模型）。其他热门选项包括 Flux-Pro-1.1、DALL-E-3、SD3.5-Large 等，可使用 poe_list_models(output_modality="image") 查找所有可用模型。

在聊天中使用

从 ✨ Tool Selector 中选择 Poe 工具，然后直接提出需求：

• “列出 Poe 上可用的图像生成模型”
• “生成一张 16:9 的横向图像，描绘日落时的未来城市景观”
• “使用 Flux-Pro 为咖啡店制作一个极简风格的徽标”
• “生成一张 9:16 的纵向图像，描绘霓虹灯照亮的东京小巷”
• “与 GPT-5.4 聊聊量子计算”

AI 会选择合适的工具并执行，然后返回结果（图像 URL、文本回复等）。

在任务中使用

任务规划器可在多步骤自主工作流中使用 Poe 工具。规划器可识别以下工具别名：poe、poe_models、poe_image、poe_video、poe_audio、poe_generate。

任务目标示例：

• “生成一张 16:9 的横向图像，描绘山间日落，并将其上传到我的 Canva 资源库”
• “调研 2025 年的主要 AI 趋势，然后为每个趋势生成一张说明图像”
• “列出 Poe 上的所有图像模型，然后使用三个不同的模型生成相同提示词，以便比较”

规划器可以串联 poe_generate_image → upload_asset（Canva）→ autofill_design 步骤，根据生成的图像创建完整的设计工作流。

文件

文件	用途
backend/server_poe.py	FastMCP 服务 — 5 个 MCP 工具
backend/utils/poe_client.py	Async httpx 客户端、Pydantic 模型、媒体下载
backend/tests/test_poe_mcp.py	87 个单元测试（无需 API 密钥）

工作原理

1. 用户与 React 前端交互。
2. 前端向 FastAPI 后端 API 发送请求（聊天消息、对话管理）。
3. 对于聊天消息，后端（main.py）会处理请求：
   • 后端可能会通过提供商层与大模型交互（默认使用 Ollama；可在 Settings 中配置其他提供商）。
   • 如果用户通过界面启用了某个工具（例如网络搜索、SQL 查询）：
     • 后端会准备必要的上下文（例如，获取 SQL 查询所需的数据库架构）。
     • 后端可能会提示 Ollama 模型生成特定工具所需的输入（例如 SQL 查询或 HubSpot JSON 负载）。
     • 随后，后端会与相应的 MCP 服务模块通信（作为子进程管理：search、SQL、YouTube、HubSpot、Python、Codex）。
     • MCP 服务模块会执行该工具（例如，调用 Serper.dev API、查询 MySQL）。
     • MCP 服务模块会将结果返回给后端。
     • 后端可能会将工具结果再次提供给 Ollama，以生成最终的、信息充分的回复。
4. 后端会在 MongoDB 中存储／检索对话历史记录。
5. 最终回复会流式传回 前端并显示给用户。

用于上下文的 AI 摘要

• 目的：固定的对话会向系统提示词提供由大模型生成的简短摘要，让后续聊天无需发送完整记录，也能参考之前的工作。
• 生成：
  • 按需由用户发起（非启发式）。如果你固定的聊天没有摘要，应用会先询问是否生成摘要，并在生成完成前阻止固定操作。
  • 后端会整理最多约 1000 个词的近期对话（去除 HTML），并提示所选模型生成一段不超过约 750 个字符的摘要。
  • 已存储的摘要会重复使用；不会自动重新生成。
• 限制与执行：
  • 最多可固定 5 个对话。后端会强制执行此上限，并且 UI 会在达到上限时禁用固定功能。
  • UI 会显示固定数量统计信息（例如“已固定 X/5 个”）。
• 模型选择：
  • 在 Settings → Summaries → Select Model 下选择模型。此处使用与聊天相同的提供商模型目录。
  • 如果没有为摘要配置模型，生成操作将失败，直到你选择模型。
• 上下文整理：
  • 系统提示词中仅包含已存储的摘要；不会使用启发式/自动生成的摘要。
  • 上下文服务会为摘要和个人资料提示词统筹分配空间。
• 维护：
  • 提供了管理工具，可批量删除摘要和/或取消固定所有聊天，以便清空数据。请在生产环境中谨慎使用。

API（参考）：

• 摘要设置：GET /api/summaries/settings，POST /api/summaries/settings { model_name }
• 生成摘要：POST /api/summaries/generate { conversation_id }
• 固定对话：POST /api/user-context/pin-conversation { conversation_id, pinned }（强制执行上限）
• 固定数量统计：GET /api/user-context/pin-stats → { count, max }

定时任务（时区与单次执行）

• 在 Tasks 面板的 Scheduled 选项卡中创建计划。
• 两种模式：
  • 周期性：Cron 表达式 + 时区。下一次运行时间根据所选时区的本地时间计算（考虑夏令时），并以 UTC 存储。
  • 单次执行：设置日期/时间和时区；首次运行后自动禁用。
• 你可以选择“立即运行”，并可按需覆盖本次运行所用的模型。

完整详情请参阅 TASKS_USER_GUIDE.md。

自定义

• 模型提供商：使用页眉中的模型选择器选择提供商/模型。在 Settings 中配置提供商 API 密钥；只有完成配置后，才会显示非 Ollama 模型。
• Ollama 模型：从可用的本地模型中选择（或设置 DEFAULT_OLLAMA_MODEL）。适合编码的模型可能更擅长处理 SQL（例如 codestral）。
• 搜索结果：在 backend/main.py 中调整要处理的搜索结果数量。
• 数据库架构上下文：在 backend/main.py 中修改 MAX_TABLES_FOR_SCHEMA_CONTEXT，以控制发送给大模型的表架构数量。
• 提示词工程：修改 backend/main.py 中发送给 Ollama 的系统提示词，以定制回答和 SQL 生成。
• 样式：修改 CSS 文件或 frontend/src/ 中 React 组件的样式，自定义前端外观。

设置与使用（快速入门）

1. 后端：cd backend && uvicorn main:app --reload --port 8000
2. 前端：cd frontend && npm install && npm run dev
3. 在应用中：
   • 选择模型（标题栏 → 模型选择器）。
   • 可选：打开设置，添加 OpenAI 或其他提供商的密钥。
   • 使用 ✨ 工具选择器运行智能网页搜索、数据库、YouTube、Python、HubSpot、Poe 或 Codex。
   • 对于 Canva：在 backend/.env 中设置 CANVA_API_TOKEN，然后让 AI 创建、导入或导出设计。
   • 对于 Figma：在 backend/.env 中设置 FIGMA_ACCESS_TOKEN，然后让 AI 读取文件（例如：“获取 Figma 文件 ABC123 的结构”）。
   • 对于 Poe：在 backend/.env 中设置 POE_API_KEY，然后让 AI 生成图像或与前沿模型聊天。
   • 任务面板支持临时任务和计划任务。

前置条件：

• 本地模型需要 Ollama 正在运行（拉取一个模型，例如 ollama pull llama3.1）。
• MongoDB 可访问（用于历史记录/任务）。
• 对于 Canva：需要 Canva Connect API 访问令牌（请参阅设置说明）。
• 对于 Figma：需要从 Figma 账户设置 → 安全 → Personal access tokens 获取个人访问令牌。
• 对于 Poe：需要从 poe.com/api/keys 获取 Poe API 密钥（需要 Poe 订阅）。
• 对于 Codex：安装 Codex CLI 并配置 OpenAI API 密钥（通过设置或环境变量），然后再开始运行。

更新

在不影响现有数据（MongoDB、ChromaDB、.env）的情况下更新到最新版本：

# 1. Pull latest code
git pull origin main

# 2. Update backend dependencies
cd backend
pip install -r requirements.txt

# 3. Rebuild frontend
cd ../frontend
npm install
npm run build

# 4. Restart the backend
# Manually:
cd ../backend
uvicorn main:app --host 127.0.0.1 --port 8000

# macOS Launch Agent:
launchctl stop com.osoba.backend && launchctl start com.osoba.backend

# Linux systemd:
sudo systemctl restart osoba-backend

你的数据是安全的：MongoDB（对话、任务、文档、设置）和 ChromaDB（语义记忆、知识库嵌入）是外部服务，代码更新不会触及它们。你的 .env 文件已被 gitignore 忽略，绝不会被覆盖。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。