# https://github.com/Upsonic/Upsonic 项目说明书

生成时间：2026-06-26 09:54:58 UTC

## 目录

- [概述、安装与快速入门](#page-overview)
- [智能体、团队与图编排](#page-agents)
- [工具、MCP 集成与技能系统](#page-tools)
- [数据、存储、知识库与外部接口](#page-data)

<a id='page-overview'></a>

## 概述、安装与快速入门

### 相关页面

相关主题：[智能体、团队与图编排](#page-agents), [工具、MCP 集成与技能系统](#page-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Upsonic/Upsonic/blob/main/README.md)
- [src/upsonic/cli/printer.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)
- [src/upsonic/cli/main.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/main.py)
- [src/upsonic/cli/commands/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/__init__.py)
- [src/upsonic/cli/commands/init/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/command.py)
- [src/upsonic/cli/commands/remove/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/remove/command.py)
- [src/upsonic/cli/commands/install/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/install/__init__.py)
- [src/upsonic/cli/commands/shared/openapi.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/shared/openapi.py)
- [src/upsonic/run/agent/input.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)
- [src/upsonic/run/agent/output.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)
- [src/upsonic/utils/agent/events.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)
</details>

# 概述、安装与快速入门

## 1. 项目概述

Upsonic 是一个面向生产环境的 AI 智能体（Agent）框架，主打"极简智能体（minimalist agent）+ MCP（Model Context Protocol）"的核心理念，覆盖从本地原型到分布式部署的完整工具链 [README.md](https://github.com/Upsonic/Upsonic/blob/main/README.md)。框架通过一组统一的 Python API 与 CLI 工具，让开发者能够在不依赖云服务的前提下完成智能体的开发、测试、运行与打包。

核心能力包括：智能体运行时（同步/异步双路径）、细粒度事件流（events）、多模态输入处理（文本、URL、二进制内容）、结构化输出（内置类型与 Pydantic 模型）以及基于 FastAPI + Swagger UI 的服务化能力。

> **社区动态**：v0.75.0 引入 `KBState` 状态机管理知识库生命周期（`UNINITIALIZED → CONNECTED → INDEXED → CLOSED`）；v0.76.0 起预置 Applied Scientist 等可直接使用的智能体；当前最新版本为 v0.77.3（2026-05-19），主要修复了集中化用量注册表 [v0.77.3 Release](https://github.com/Upsonic/Upsonic/releases/tag/v0.77.3)。v0.77.1 起 CI 切换为 `uv publish`，发布链路更稳定 [v0.77.1 Release](https://github.com/Upsonic/Upsonic/releases/tag/v0.77.1)。

## 2. 安装方式

Upsonic 以 Python 包形式分发，可通过 `uv`（首选）或 `pip` 安装。CLI 子命令 `upsonic install` 会读取 `upsonic_configs.json` 中的依赖段并执行安装流程 [src/upsonic/cli/printer.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)。

```bash
# 直接安装库
pip install upsonic

# 通过 CLI 安装项目配置中声明的依赖
upsonic install           # 安装 api 段（默认）
upsonic install streamlit # 安装 streamlit 段
upsonic install all       # 一次性安装全部段
```

`install` 命令在执行时优先调用 `uv`，若不可用则回退到 `pip` [src/upsonic/cli/commands/install/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/install/__init__.py)。

## 3. CLI 快速入门

`upsonic` CLI 提供一组面向项目的脚手架与运行时命令，统一在 [src/upsonic/cli/commands/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/__init__.py) 中导出：

| 命令 | 作用 | 主要来源文件 |
|------|------|--------------|
| `upsonic init` | 提示输入 agent 名称并生成 `main.py` / `upsonic_configs.json` 模板 | init/command.py |
| `upsonic add <lib> <section>` | 往指定段（api/streamlit/development）追加依赖 | printer.py |
| `upsonic remove <lib> <section>` | 从指定段移除依赖（剥离版本号/extras 后按包名匹配） | remove/command.py |
| `upsonic install [section]` | 按段或 `all` 安装依赖 | printer.py |
| `upsonic run [--host --port]` | 启动 FastAPI 服务并暴露 `/docs` Swagger UI | printer.py |
| `upsonic zip [filename]` | 打包当前目录为 zip，便于备份分享 | printer.py |

### 3.1 项目初始化流程

```mermaid
flowchart LR
    A[upsonic init] --> B{输入 agent 名称}
    B --> C[生成 main.py]
    B --> D[生成 upsonic_configs.json]
    D --> E[upsonic add / install]
    E --> F[upsonic run]
    F --> G[FastAPI + Swagger UI /docs]
```

初始化时若目标文件已存在，CLI 会提示是否覆盖；`remove` 命令在解析包名时会按 `==` / `>=` / `<=` / `~=` / `!=` / `[` / `;` 等分隔符拆分，剥离版本与 extras 后执行匹配 [src/upsonic/cli/commands/remove/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/remove/command.py)。

## 4. 配置文件与默认结构

`upsonic_configs.json` 是项目的中枢配置，由 `init` 命令生成，涵盖输入/输出 schema、机器规格、依赖段以及入口文件指针 [src/upsonic/cli/commands/init/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/command.py)。

- **api 段**（默认）：`fastapi>=0.115.12`、`uvicorn>=0.34.2`、`celery>=5.5.2`、`sqlalchemy>=2.0.40`、`psycopg2-binary>=2.9.9`、`redis>=5.0.0`、`fire>=0.7.0` 等；
- **streamlit 段**：固定为 `streamlit==1.32.2`、`pandas==2.2.1`、`numpy==1.26.4`；
- **development 段**：`watchdog`、`pytest`、`ipdb`、`streamlit-autorefresh` 等。

CLI 还会基于 input/output schema 自动生成 OpenAPI 规范，类型映射规则定义于 [src/upsonic/cli/commands/shared/openapi.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/shared/openapi.py)，常见映射如 `files` → JSON `array<string>` / Multipart `array<string, format=binary>`；`file`/`binary` → JSON `string` / Multipart `string, format=binary`。

## 5. 智能体运行与事件

运行时通过 `events` 模块暴露细粒度回调，包括文本增量（`yield_text_delta_event`）、工具调用（`yield_tool_call_event` / `yield_tool_result_event`）、缓存命中（`yield_cache_hit_event`）、策略校验（`yield_policy_check_event`）、反思与可靠性（`yield_reflection_event` / `yield_reliability_event`）等，每个事件均提供同步与异步（`a*` 前缀）两个版本 [src/upsonic/utils/agent/events.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)。

输入侧支持文本、`ImageUrl` / `DocumentUrl`（自动通过 `httpx` 下载并转换为 `BinaryContent`）以及本地二进制资源 [src/upsonic/run/agent/input.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)；输出侧可声明为内置 `str` 或任意 Pydantic 模型，通过 `ModelResponsePartTypeAdapter` 与 `ModelProfile.from_dict` 进行反序列化 [src/upsonic/run/agent/output.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)。

## 6. 常见问题与社区反馈

- **缺少 temperature 参数**：社区 #333 反馈 Agent 配置类未暴露 `temperature` 顶层字段，需通过底层模型客户端进行设置 [Issue #333](https://github.com/Upsonic/Upsonic/issues/333)。
- **MCP 集成位置**：#244 中用户询问 `add_mcp_server` 的环境变量与添加位置，建议参考 MCP server 注册文档 [Issue #244](https://github.com/Upsonic/Upsonic/issues/244)。

## 参见

- CLI 命令索引：参见 `src/upsonic/cli/commands/` 下各子模块
- 事件与可观测性：参见 `src/upsonic/utils/agent/events.py`
- 输入/输出序列化：参见 `src/upsonic/run/agent/input.py` 与 `output.py`
- 发布历史：参见 [GitHub Releases](https://github.com/Upsonic/Upsonic/releases)

---

<a id='page-agents'></a>

## 智能体、团队与图编排

### 相关页面

相关主题：[概述、安装与快速入门](#page-overview), [工具、MCP 集成与技能系统](#page-tools), [数据、存储、知识库与外部接口](#page-data)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Upsonic/Upsonic/blob/main/README.md)
- [src/upsonic/cli/printer.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)
- [src/upsonic/cli/commands/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/__init__.py)
- [src/upsonic/utils/agent/events.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)
- [src/upsonic/run/agent/input.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)
- [src/upsonic/run/agent/output.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)
- [src/upsonic/cli/commands/remove/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/remove/command.py)
- [src/upsonic/cli/commands/install/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/install/__init__.py)
- [src/upsonic/cli/commands/init/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/__init__.py)
</details>

# 智能体、团队与图编排

## 概述

Upsonic 定位为"在 Python 中构建自主 AI 智能体"的框架,其能力分三层堆叠:单个 **Agent** 负责与模型、工具和上下文进行单次或多次交互;**Team** 把多个 Agent 组合为协作单元;**Graph** 则以有向方式编排这些节点,使数据沿显式定义的控制流与数据流传递。README 强调框架支持"Autonomous AI Agents",并提供 OCR、多模态、MCP、KnowledgeBase、Mail Interface 等开箱即用能力,这些能力在不同编排层级中可被复用 [README.md](https://github.com/Upsonic/Upsonic/blob/main/README.md)。

CLI 子系统为这三层提供统一的脚手架入口:`init` 创建 `main.py` 与 `upsonic_configs.json`,`add/remove/install` 维护依赖,`run` 把当前项目作为 FastAPI 服务暴露,从而在本地把任意 Agent、Team 或 Graph 节点变成可调用端点 [src/upsonic/cli/printer.py:1-80](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)、[src/upsonic/cli/commands/__init__.py:1-22](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/__init__.py)。

## 智能体运行时:事件驱动生命周期

单 Agent 的执行被建模为一系列可观测事件,这为 Team 与 Graph 编排提供了统一的追踪原语。`src/upsonic/utils/agent/events.py` 集中导出了一组同步/异步事件产出函数,覆盖文本、工具、缓存、模型、消息、运行、记忆、策略、反思、可靠性与执行结果等阶段 [src/upsonic/utils/agent/events.py:1-80](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)。

```mermaid
stateDiagram-v2
    [*] --> RunStarted: yield_run_started_event
    RunStarted --> ContextBuilt: yield_context_built_event
    ContextBuilt --> MessagesBuilt: yield_messages_built_event
    MessagesBuilt --> ModelRequest: yield_model_request_start_event
    ModelRequest --> ModelResponse: yield_model_response_event
    ModelResponse --> ToolsConfigured: yield_tools_configured_event
    ToolsConfigured --> ToolCall: yield_tool_call_event
    ToolCall --> ToolResult: yield_tool_result_event
    ToolResult --> ModelRequest: 再次请求
    ToolsConfigured --> FinalOutput: yield_final_output_event
    FinalOutput --> [*]: yield_execution_complete_event
```

`ayield_*` 与 `yield_*` 配对允许同一事件在同步与异步运行中保持语义一致,这是 Team 级 fan-out 与 Graph 级并行节点所依赖的基础 [src/upsonic/utils/agent/events.py:1-40](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)。

## 智能体输入与输出模型

编排系统要跨节点传递数据,必须用稳定的序列化协议。`src/upsonic/run/agent/input.py` 中的 `to_dict` 区分了四种 `user_prompt` 形态:普通字符串、`ModelRequest` 列表、单个 `ModelRequest` 以及任意 Pydantic `BaseModel`,后两者使用 `ModelMessagesTypeAdapter` 写入 JSON [src/upsonic/run/agent/input.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)。`ImageUrl` / `DocumentUrl` 会被 `_convert_url_to_binary` 同步或异步下载为 `BinaryContent`,保证编排图内部只流转"已落地"的字节数据 [src/upsonic/run/agent/input.py:1-40](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)。

`src/upsonic/run/agent/output.py` 处理反向序列化:支持从 `__pydantic_type__` / `__type__` / `__builtin_type__` 三种字典标签反查类对象,`thinking_parts` 使用 `ModelResponsePartTypeAdapter` 还原,`model_provider_profile` 则通过 `ModelProfile.from_dict` 重建,这些机制让 Team 中间结果与 Graph 节点状态可以被持久化、迁移和跨进程传递 [src/upsonic/run/agent/output.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)。

## CLI 脚手架:把编排产物变成可运行服务

`upsonic init` 会生成 `main.py`(包含 `async main()`)与 `upsonic_configs.json`(含输入/输出 schema),这是把单个 Agent、Team 或 Graph 注册为标准工程项目的入口 [src/upsonic/cli/printer.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)、[src/upsonic/cli/commands/init/__init__.py:1](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/__init__.py)。

| 命令 | 作用 | 关键文件 |
|------|------|----------|
| `upsonic init` | 创建 Agent/编排项目骨架 | [src/upsonic/cli/commands/init/__init__.py:1](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/__init__.py) |
| `upsonic add <lib> <section>` | 写入 `api` / `streamlit` / `development` 依赖 | [src/upsonic/cli/printer.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py) |
| `upsonic remove <lib> <section>` | 按包名(剥离版本符)从配置中移除 | [src/upsonic/cli/commands/remove/command.py:1-20](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/remove/command.py) |
| `upsonic install [section]` | 优先使用 `uv`,回退 `pip` 安装依赖 | [src/upsonic/cli/commands/install/__init__.py:1](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/install/__init__.py) |
| `upsonic run` | 以 FastAPI 暴露编排节点,自动生成 OpenAPI | [src/upsonic/cli/printer.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py) |

`upsonic run` 强调"动态从 `upsonic_configs.json` 的输入/输出 schema 构建 API",这意味着同一套编排对象既能在脚本里直接调用,也能在进程间通过 HTTP 调用——这是 Team 与 Graph 跨进程编排的关键能力 [src/upsonic/cli/printer.py:1-40](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)。

## 团队与图编排的扩展点

社区反馈显示,典型编排痛点集中在三个方向:配置(例如 #333 关注 Agent 缺少 `temperature` 参数)、工具接入(#244 询问 MCP `add_mcp_server` 的环境变量与位置)、以及跨节点状态(v0.75.0 引入的 `KBState` 枚举把 `UNINITIALIZED → CONNECTED → INDEXED → CLOSED` 状态机强加给 KnowledgeBase,体现了"用显式状态机代替布尔标志"在编排一致性上的价值)。结合事件系统、序列化协议与 CLI 服务化,Upsonic 的 Team 通常把多个 Agent 包装为可订阅相同事件流的子运行,而 Graph 则把它们的 `AgentRunOutput` 沿声明式边连接,使一次图执行等价于对这些事件的统一编排 [src/upsonic/utils/agent/events.py:1-80](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)、[src/upsonic/run/agent/output.py:1-60](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)。

## 参见

- 智能体输入与输出序列化(同 `run/agent` 子包)
- CLI 命令参考(`src/upsonic/cli/commands/`)
- 知识库状态机(社区上下文: v0.75.0 发行说明)
- MCP 工具接入(社区上下文: issue #244)

---

<a id='page-tools'></a>

## 工具、MCP 集成与技能系统

### 相关页面

相关主题：[智能体、团队与图编排](#page-agents), [数据、存储、知识库与外部接口](#page-data)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/upsonic/tools/base.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/base.py)
- [src/upsonic/tools/builtin_tools.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/builtin_tools.py)
- [src/upsonic/tools/mcp.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/mcp.py)
- [src/upsonic/tools/hitl.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/hitl.py)
- [src/upsonic/tools/registry.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/registry.py)
- [src/upsonic/tools/policy_manager.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/tools/policy_manager.py)
- [src/upsonic/utils/agent/events.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)
- [src/upsonic/run/agent/input.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)
- [src/upsonic/run/agent/output.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)
</details>

# 工具、MCP 集成与技能系统

## 1. 概述与定位

工具（Tools）、MCP（Model Context Protocol）集成与技能（Skills）系统共同构成 Upsonic 智能体（Agent）与外部世界交互的能力层。智能体在执行任务时可以声明式地挂载工具、连接 MCP 服务器，或者复用预置的技能（例如 `AppliedScientist`），从而把 LLM 的纯语言推理能力扩展为可观测、可治理、可中断的实际动作。`src/upsonic/tools/base.py` 定义了工具的抽象基类，`src/upsonic/tools/builtin_tools.py` 提供了开箱即用的内建工具集，`src/upsonic/tools/mcp.py` 则负责与外部 MCP 服务器建立通道。

整体上，该系统遵循"声明 → 配置 → 执行 → 事件"四段式生命周期，相关运行事件集中定义在 `src/upsonic/utils/agent/events.py` 的 `__all__` 列表中。

资料来源：[src/upsonic/tools/base.py:1-1]()、[src/upsonic/tools/mcp.py:1-1]()、[src/upsonic/utils/agent/events.py:1-52]()

## 2. 工具抽象与执行事件

Upsonic 把工具视作一等公民。`src/upsonic/tools/base.py` 提供基类，支持同步与异步调用，并能挂载到 Agent 的 `tools` 列表中。执行过程通过统一事件流对外暴露，便于上层 UI、日志或审计系统订阅。

```mermaid
flowchart LR
    A[Agent 运行] --> B[yield_tools_configured_event]
    B --> C[LLM 决策调用]
    C --> D[yield_tool_call_event]
    D --> E[执行工具]
    E --> F[yield_tool_result_event]
    F --> G{需人工介入?}
    G -- 是 --> H[yield_external_tool_pause_event]
    H --> I[HITL 反馈]
    G -- 否 --> J[继续推理]
```

事件类型在 `src/upsonic/utils/agent/events.py` 中以字符串名称显式注册，主要包含 `yield_tools_configured_event`、`yield_tool_call_event`、`yield_tool_result_event` 与 `yield_external_tool_pause_event`（资料来源：[src/upsonic/utils/agent/events.py:1-52]()）。其中 `yield_external_tool_pause_event` 专门用于标识工具需要 Human-in-the-Loop 介入的场景，对应 `src/upsonic/tools/hitl.py` 的实现。

### 2.1 输入与输出适配

工具的入参由 `src/upsonic/run/agent/input.py` 统一处理。该模块在序列化输入时会检测 `ImageUrl` 与 `DocumentUrl` 类型的字段，并通过 `_convert_url_to_binary` / `_aconvert_url_to_binary` 异步或同步地把远程资源下载并包装为 `BinaryContent`，再交给下游工具使用（资料来源：[src/upsonic/run/agent/input.py:1-1]()）。

输出侧由 `src/upsonic/run/agent/output.py` 接管。它利用 `ModelResponsePartTypeAdapter.validate_python` 解析模型响应中的 `thinking_parts`，并结合 `ModelProfile.from_dict` 还原 `model_provider_profile` 等元数据，方便工具结果附带结构化上下文（资料来源：[src/upsonic/run/agent/output.py:1-1]()）。

## 3. MCP 集成

`src/upsonic/tools/mcp.py` 是 MCP 客户端适配层。社区中常见的使用方式是直接调用客户端的 `add_mcp_server` 方法注册外部服务器：

```python
instance.client.add_mcp_server(
    "websearch",
    "npx",
    ["-y", "@mzxrai/mcp-webresearch"],
)
```

该方法接受一个语义化名称、可执行命令（`npx`、`uvx`、`python` 等）以及参数列表，符合 MCP stdio 传输协议。社区议题 #244 反馈了关于环境变量与命令注入位置的困惑（资料来源：[GitHub Issue #244](https://github.com/Upsonic/Upsonic/issues/244)），官方维护的"minimalist agent + MCP"路线则进一步强调通过统一注册中心来收敛这些细节（资料来源：[GitHub Issue #609](https://github.com/Upsonic/Upsonic/issues/609)）。

## 4. 技能系统：预置与扩展

技能（Skills）是"工具 + 工作流 + 提示词"的更高层封装。`src/upsonic/tools/registry.py` 维护技能的全局注册表，`src/upsonic/tools/policy_manager.py` 则在执行前对工具/技能进行策略检查（policy check），相关事件为 `yield_policy_check_event` 与 `yield_policy_feedback_event`（资料来源：[src/upsonic/utils/agent/events.py:1-52]()）。

内建技能持续扩展，典型代表包括：

| 技能 / 工具 | 简介 | 引入版本 |
| --- | --- | --- |
| `AppliedScientist` | 自动化测试新论文在当前 ML 模型上的效果 | v0.76.0 |
| Mail Interface | SMTP/IMAP 邮件收发与附件处理 | v0.74.4 |
| Memory 改进 | 增强 Agent 长期记忆 | v0.74.4 |
| KBState 状态机 | `UNINITIALIZED → CONNECTED → INDEXED → CLOSED` | v0.75.0 |

资料来源：[GitHub Releases v0.76.0](https://github.com/Upsonic/Upsonic/releases/tag/v0.76.0)、[GitHub Releases v0.74.4](https://github.com/Upsonic/Upsonic/releases/tag/v0.74.4)、[GitHub Releases v0.75.0](https://github.com/Upsonic/Upsonic/releases/tag/v0.75.0)

## 5. 常见问题与失败模式

- **温度等推理参数**：社区议题 #333 指出 Agent 配置类中没有直接的 `temperature` 字段（资料来源：[GitHub Issue #333](https://github.com/Upsonic/Upsonic/issues/333)），需通过模型层或 `model_provider_profile` 传递。
- **MCP 注册位置**：议题 #244 显示 `add_mcp_server` 并不总是显式可见，建议参考 `src/upsonic/tools/mcp.py` 的最新方法签名。
- **工具参数容错**：v0.77.2 修复了"tolerate trailing junk in tool args"问题，说明在重试任务时工具参数解析会重置（资料来源：[GitHub Releases v0.77.2](https://github.com/Upsonic/Upsonic/releases/tag/v0.77.2)）。
- **安全建议**：外部 SAST 工具反馈了 `shell=True`、`pickle` 持久化等风险（资料来源：[GitHub Issue #596](https://github.com/Upsonic/Upsonic/issues/596)），使用 `builtin_tools` 中的 shell 类工具时需要审慎配置 `policy_manager`。

## 6. 总结

工具、MCP 集成与技能系统把 Upsonic Agent 从一个语言模型升级为可执行、可治理的运行时。开发者通过 `base.py` 自定义工具、通过 `mcp.py` 接入 MCP 服务、通过 `registry.py` 与 `policy_manager.py` 统一注册与治理；运行期产生的所有阶段事件（工具配置、调用、结果、暂停、策略反馈）均通过 `events.py` 的事件流对外暴露，便于观测和扩展。

## See Also

- [智能体事件系统](Agent-Events-System)
- [知识库与状态机](KnowledgeBase-and-KBState)
- [预置智能体：AppliedScientist](Prebuilt-Agents-AppliedScientist)
- [CLI 与 OpenAPI 服务化](CLI-and-OpenAPI)

---

<a id='page-data'></a>

## 数据、存储、知识库与外部接口

### 相关页面

相关主题：[智能体、团队与图编排](#page-agents), [工具、MCP 集成与技能系统](#page-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/upsonic/cli/commands/init/command.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/init/command.py)
- [src/upsonic/cli/commands/shared/openapi.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/shared/openapi.py)
- [src/upsonic/run/agent/input.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/input.py)
- [src/upsonic/run/agent/output.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/run/agent/output.py)
- [src/upsonic/utils/agent/events.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/utils/agent/events.py)
- [src/upsonic/cli/printer.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/printer.py)
- [src/upsonic/cli/commands/__init__.py](https://github.com/Upsonic/Upsonic/blob/main/src/upsonic/cli/commands/__init__.py)
- [README.md](https://github.com/Upsonic/Upsonic/blob/main/README.md)
</details>

# 数据、存储、知识库与外部接口

## 概述

Upsonic 的「数据、存储、知识库与外部接口」子系统负责定义 Agent 运行时所接触的全部 I/O 形态：它规定了项目的初始化配置（输入/输出 schema 与依赖分组），负责将 URL 与二进制文档转写为可被模型消费的 `BinaryContent`，通过 `ModelResponsePartTypeAdapter` 完成输出反序列化，并以 `OpenAPI` 暴露服务，还通过统一的事件系统把数据流、缓存、记忆、策略与外部工具的副作用显式地广播出去。资料来源：[src/upsonic/cli/commands/init/command.py:30-80]()、资料来源：[src/upsonic/run/agent/input.py:60-100]()、资料来源：[src/upsonic/run/agent/output.py:40-90]()。

## 初始化配置与依赖分组

`upsonic init` 命令会生成 `upsonic_configs.json`，作为数据与外部接口的「单一事实源」。该配置将依赖拆分为 `api`、`streamlit`、`development` 三个语义段，使运行时、UI 与开发工具链解耦：

```text
{
  "agent_name": "<user-supplied>",
  "description": "Upsonic AI Agent",
  "streamlit": false,
  "proxy_agent": false,
  "dependencies": {
    "api": ["fastapi>=0.115.12", "uvicorn>=0.34.2", "sqlalchemy>=2.0.40", "redis>=5.0.0", ...],
    "streamlit": ["streamlit==1.32.2", "pandas==2.2.1", "numpy==1.26.4"],
    "development": ["watchdog", "ipdb", "pytest", "streamlit-autorefresh"]
  },
  "entrypoints": { "api_file": "main.py", "streamlit_file": "..." }
}
```

`upsonic install [api|streamlit|development|all]` 默认只安装 `api` 段；`uv` 优先，`pip` 兜底。资料来源：[src/upsonic/cli/commands/init/command.py:50-95]()、资料来源：[src/upsonic/cli/printer.py:200-300]()。机器规格字段（`cpu`、`memory`、`storage`）与 `features` 字典也保存在同一文件中，为部署侧提供静态画像。资料来源：[src/upsonic/cli/commands/init/command.py:30-50]()。

## 输入处理：URL、二进制与多模态

`run/agent/input.py` 定义了 Agent 入参的统一规整逻辑。当 `documents` 中出现 `ImageUrl` 或 `DocumentUrl` 时，会触发同步或异步下载并转写为 `BinaryContent`：

- 同步路径：直接 `httpx.get(url)`，包装为带 `media_type`、`identifier` 的 `BinaryContent`。
- 异步路径：使用 `httpx.AsyncClient` 上下文管理器，避免连接泄漏。
- `_is_url_type` 守卫确保只有 URL 类型才会触发网络 I/O。

资料来源：[src/upsonic/run/agent/input.py:60-100]()`to_dict()` 进一步用 `ModelMessagesTypeAdapter` 序列化 `ModelRequest`，对 `BaseModel` 子类使用 `model_dump`，从而在多模态、字符串、Pydantic 模型三种入参之间保持一致的 JSON 表示。资料来源：[src/upsonic/run/agent/input.py:110-150]()。

## 输出处理：Schema 还原与思考部分

`run/agent/output.py` 处理从持久化层恢复 `AgentRunOutput` 的反向序列化。关键能力包括：

- 对 `__pydantic_type__` 与 `__type__` 标记的 schema，通过 `importlib.import_module` 动态重建类型。
- 对 `__builtin_type__=str` 的特殊路径直接还原为 `str`。
- 使用 `ModelResponsePartTypeAdapter.validate_python` 还原 `thinking_parts`，保留推理痕迹。
- 使用 `ModelProfile.from_dict` 将提供者画像反序列化为 `ModelProfile` 实例。

资料来源：[src/upsonic/run/agent/output.py:40-90]()`AgentRunOutput` 的字段集合体现了完整的运行态：身份（`run_id`、`agent_id`、`session_id`、`user_id`、`trace_id`）、任务嵌入（`task`，作为 HITL 的单一事实源）、`step_results`、`requirements`、`output_schema`、聊天历史与「本轮新增消息」的分离等。资料来源：[src/upsonic/run/agent/output.py:150-220]()。

## 外部接口：OpenAPI、Mail 与 MCP

`cli/commands/shared/openapi.py` 将 `upsonic_configs.json` 中的 `inputs`/`output` schema 动态映射为 OpenAPI 3 组件。`map_inputs_props` 同时产出 JSON 与 `multipart/form-data` 两份属性表，类型映射如下：

| 配置 type | JSON schema | multipart schema |
| --- | --- | --- |
| `files` | `array<string>` | `array<string, format=binary>` |
| `file` / `binary` / `string($binary)` | `string` | `string, format=binary` |
| `number` / `integer` / `boolean` / `list` | 对应原子类型 | 保持相同 |
| `object` | 内联对象 / `$ref` | 同上 |

请求体先注册 `multipart/form-data` 再注册 `application/json`，并使用 `$ref` 指向 `RequestModel`，避免 schema 重复定义。`POST /jobs` 的 200 响应统一引用 `JobStatus` 组件。资料来源：[src/upsonic/cli/commands/shared/openapi.py:20-140]()。

社区侧已记录的外部接口扩展包括：

- **Mail Interface（v0.74.4）**：基于 SMTP/IMAP 的收发与附件处理，支持 Gmail/Outlook/Yahoo/Zoho 与自托管服务器，配合白名单与心跳轮询。资料来源：[GitHub Releases v0.74.4](https://github.com/Upsonic/Upsonic/releases/tag/v0.74.4)。
- **MCP 接入（社区问题 #244）**：通过 `instance.client.add_mcp_server(name, command, args, env=...)` 注册外部工具，社区反馈了 `env` 与位置语义不清的问题，建议在客户端构造时显式声明环境变量与工作目录。
- **Valkey Search 向量库（社区问题 #603）**：计划作为第 9 个向量库提供者，主打低延迟内存检索。

## 知识库生命周期与数据流事件

知识库（`KnowledgeBase`）在 v0.75.0 引入了 `KBState` 枚举状态机，把原先零散的布尔标志统一为 `UNINITIALIZED → CONNECTED → INDEXED → CLOSED` 四态，非法跃迁抛 `RuntimeError`；同步与异步内容管理 API（如 `aadd_source`、`aadd_text`、`aremove_document`）与状态机强绑定，确保连接、索引、清理顺序的确定性。资料来源：[GitHub Releases v0.75.0](https://github.com/Upsonic/Upsonic/releases/tag/v0.75.0)。

`utils/agent/events.py` 暴露了与数据/存储/外部接口相关的全部可观测事件，按类别分组：文本增量与完成、工具调用与结果、缓存命中/未命中/写入、模型选择与请求、消息装配、运行启动/取消、记忆更新、策略检查与反馈、反思与可靠性、上下文与用户输入构建、聊天历史加载、存储连接、LLM 准备等。其同步与异步版本并列导出，便于上层消费者（CLI、Streamlit、外部服务）订阅同一信号源。资料来源：[src/upsonic/utils/agent/events.py:30-200]()。

```mermaid
flowchart LR
  A[用户/外部系统] -->|JSON / multipart| B[OpenAPI Gateway]
  B --> C[AgentRunOutput 还原]
  C --> D[知识库 KBState]
  D --> E[向量检索/嵌入]
  E --> F[模型推理 + 工具/MCP/Mail]
  F --> G[事件总线]
  G --> H[持久化与流式输出]
```

## 常见失败模式与最佳实践

- **Pickle 反序列化风险**：社区问题 #596 指出，使用 `pickle` 持久化 `AgentRunOutput` 存在注入风险，建议改用 `output.py` 已实现的 `ModelResponsePartTypeAdapter` / `ModelProfile.from_dict` 路径。资料来源：[GitHub Issue #596](https://github.com/Upsonic/Upsonic/issues/596)。
- **MCP 环境变量与工作目录**：注册 MCP server 时必须显式传入 `env` 与 `cwd`，否则子进程将继承父进程环境，造成难以复现的行为差异。资料来源：[GitHub Issue #244](https://github.com/Upsonic/Upsonic/issues/244)。
- **SSL 上下文**：当 `BinaryContent` 通过自建 URL 拉取时，应在 `httpx.AsyncClient` 显式传入 `verify=` 参数，避免在企业代理环境下出现静默 TLS 失败。资料来源：[GitHub Issue #596](https://github.com/Upsonic/Upsonic/issues/596)。
- **schema 漂移**：`upsonic_configs.json` 中的 `inputs`/`output` 与运行时代码的 Pydantic 模型若不一致，`map_inputs_props` 仍会生成 OpenAPI，但实际请求会因 422 失败，建议在 CI 中加入 schema 一致性校验。

## 参见

- [Upsonic 快速上手](https://docs.upsonic.ai/get-started/quickstart)
- [GitHub Issue #596：持久化与最佳实践建议](https://github.com/Upsonic/Upsonic/issues/596)
- [GitHub Issue #244：MCP 注册方式](https://github.com/Upsonic/Upsonic/issues/244)
- [GitHub Issue #603：Valkey Search 向量库提案](https://github.com/Upsonic/Upsonic/issues/603)
- [Release v0.75.0：KnowledgeBase 状态机与内容 API](https://github.com/Upsonic/Upsonic/releases/tag/v0.75.0)
- [Release v0.74.4：Mail Interface 与 Memory 改进](https://github.com/Upsonic/Upsonic/releases/tag/v0.74.4)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Upsonic/Upsonic

摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：feat(vectordb): Add Valkey Search as a vector database provider。

## 1. 安装坑 · 来源证据：feat(vectordb): Add Valkey Search as a vector database provider

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(vectordb): Add Valkey Search as a vector database provider
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/Upsonic/Upsonic/issues/603 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Upsonic/Upsonic | host_targets=mcp_host, claude, openclaw, cursor

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Upsonic/Upsonic | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Upsonic/Upsonic | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Upsonic/Upsonic | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Upsonic/Upsonic | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：Best-practice: SSL context, SQLAlchemy text(f''), agent shell=True comment, and pickle persistence

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Best-practice: SSL context, SQLAlchemy text(f''), agent shell=True comment, and pickle persistence
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Upsonic/Upsonic/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：OwnX Network's hackathon offer for Upsonic

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OwnX Network's hackathon offer for Upsonic
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Upsonic/Upsonic/issues/619 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 安全/权限坑 · 来源证据：Possible collab: OpenxAI x Upsonic

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Possible collab: OpenxAI x Upsonic
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Upsonic/Upsonic/issues/609 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安全/权限坑 · 来源证据：Possible collab: OwnX x Upsonic

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Possible collab: OwnX x Upsonic
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Upsonic/Upsonic/issues/609 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Upsonic/Upsonic | issue_or_pr_quality=unknown

## 12. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Upsonic/Upsonic | release_recency=unknown

<!-- canonical_name: Upsonic/Upsonic; human_manual_source: deepwiki_human_wiki -->