Nexent Doc

简体中文

English

简体中文

English

Appearance

Nexent 开发指南 ​

本指南帮助开发者快速理解 Nexent 的代码结构、服务边界和本地开发流程。Nexent 是一个零代码智能体平台，同时提供可独立使用的 Python SDK；开发时应先确认改动属于前端、后端服务还是 SDK，再选择对应的调试和测试方式。

🏗️ 整体架构 ​

text
nexent/
├── frontend/          # Web 应用（Next.js + TypeScript）
├── backend/           # HTTP 接口与业务服务（FastAPI + Python）
├── sdk/nexent/        # 智能体运行框架与数据处理能力
├── deploy/            # Docker、Kubernetes 与数据库部署配置
├── doc/               # VitePress 文档站点
├── test/              # 后端与 SDK 测试
└── assets/            # 项目静态资源

一次典型请求会经过以下边界：

  1. 前端调用 FastAPI 接口。
  2. backend/apps/ 解析请求，并把业务处理交给 backend/services/。
  3. 服务层读取数据库、对象存储或配置，并将运行参数传给 sdk/nexent/。
  4. SDK 负责模型调用、工具执行、智能体协作和沙箱工作区；运行结果再以普通响应或流式事件返回前端。

后端异常也遵循同一边界：服务层抛出领域异常，接口层再转换为对应的 HTTP 状态码。新增业务逻辑时，不要把数据库操作和业务编排直接写进接口函数。

🛠️ 技术栈 ​

前端技术栈 ​

  • 框架：Next.js 15（App Router）
  • 语言：TypeScript
  • 界面：React、Tailwind CSS、Ant Design
  • 对话界面：Assistant UI
  • 状态管理：React Hooks、Zustand、TanStack Query
  • 国际化：i18next
  • 包管理器：npm

后端技术栈 ​

  • 框架：FastAPI
  • 语言：Python 3.11+
  • 数据库与缓存：PostgreSQL、Redis
  • 检索与向量存储：Elasticsearch
  • 文件存储：MinIO
  • 后台任务：Celery、Ray
  • 智能体框架：Nexent SDK、smolagents
  • 运行隔离：默认启用系统级沙箱，并为每次运行提供独立工作区

部署技术栈 ​

  • 容器化：Docker、Docker Compose
  • 集群部署：Kubernetes、Helm
  • 反向代理：Nginx
  • 可观测性：OpenTelemetry 及可选监控后端
  • 日志与健康检查：结构化日志、服务健康检查

🧱 环境准备 ​

环境相关步骤已迁移至独立的 环境准备 指南，涵盖：

  • 通用依赖与前置条件
  • 全栈 Nexent 搭建（基础设施、后端、前端和服务启动）
  • 仅使用 SDK 的安装方式

请先完成环境准备，再回到此页选择需要开发的模块。

🔧 开发模块指南 ​

🎨 前端开发 ​

  • 目录：frontend/
  • 核心功能：页面交互、智能体配置、实时问答、资源管理和国际化
  • 质量检查：运行 pnpm run check-all，依次完成类型检查、代码检查、格式检查和构建
  • 详细信息：查看 前端概览

🔧 后端开发 ​

  • 目录：backend/
  • 接口层：backend/apps/ 负责请求解析、鉴权和 HTTP 错误映射
  • 服务层：backend/services/ 负责编排业务逻辑并抛出领域异常
  • 配置入口：环境变量统一在 backend/consts/const.py 中读取，其他模块应从该文件导入配置
  • 详细信息：查看 后端概览

🤖 AI 智能体开发 ​

  • 目录：sdk/nexent/core/agents/
  • 核心功能：智能体运行、工具调用、多智能体协作、记忆、流式输出和沙箱工作区
  • 配置方式：后端服务读取平台配置，再通过参数传给 SDK；SDK 不直接读取部署环境变量
  • 系统提示词：位于 backend/prompts/
  • 详细信息：查看 智能体模块

🛠️ 工具开发 ​

  • 内置工具：在平台服务中注册，由智能体按配置调用
  • MCP 工具：支持远程 MCP 服务、容器化 MCP 服务和 OpenAPI 转换
  • Skill：可包含说明、脚本和资源文件；脚本在运行时沙箱中执行
  • 详细规范：查看 工具开发指南

📦 SDK 开发工具包 ​

  • 目录：sdk/nexent/
  • 功能：提供智能体、模型、工具、记忆、数据处理和可观测性接口
  • 适用场景：既可作为 Nexent 平台运行内核，也可作为 Python 包独立集成
  • 详细信息：查看 SDK 概览

📊 数据处理 ​

  • 文件处理：解析常见文档、表格、演示文稿和文本格式
  • 分块策略：支持 basic、by_title、none
  • 处理流程：文件解析、分片、向量化和 Elasticsearch 入库通过独立数据处理服务完成
  • 详细信息：查看 数据处理指南

🏗️ 构建与部署 ​

Docker 构建 ​

详细的构建指南请参考 Docker 构建指南。部署配置位于 deploy/；修改 Compose 文件时，需要继续兼容项目声明的 Docker Engine 最低版本。

📋 开发最佳实践与注意事项 ​

代码质量 ​

  1. 控制改动范围：把接口、业务逻辑和 SDK 能力放在各自层级，不重复实现。
  2. 补充测试：后端和 SDK 使用 pytest；修复缺陷时至少覆盖对应回归场景。
  3. 检查前端：提交前运行类型、格式、代码检查和构建命令。
  4. 同步文档：用户可见的行为、配置项或部署方式发生变化时，同时更新中英文文档。

性能优化 ​

  1. 优先异步 I/O：避免在请求处理路径中执行长时间阻塞操作。
  2. 控制上下文：为模型输出、历史消息和工具结果设置合理上限。
  3. 使用后台任务：文档处理、记忆整理等耗时任务通过队列执行。
  4. 关注资源释放：正确关闭连接、临时文件和沙箱工作区。

安全考虑 ​

  1. 验证输入：在 HTTP 边界校验参数、文件类型和大小。
  2. 执行鉴权：服务层也要检查租户、用户组和资源权限，不能只依赖前端隐藏入口。
  3. 保护敏感信息：不要在日志、Metadata、提示词或工具输出中暴露密码和令牌。
  4. 隔离执行：需要执行脚本或处理不可信文件时，使用平台提供的沙箱和工作区能力。

重要开发注意事项 ​

  1. 环境变量：只在 backend/consts/const.py 中新增环境变量读取逻辑。
  2. SDK 边界：SDK 通过函数参数接收配置，不应直接读取环境变量。
  3. 数据库迁移：已合入目标分支的 SQL 文件不可修改；新增数据库变更应创建新的版本化迁移文件。
  4. 服务依赖：运行应用前，确认 PostgreSQL、Redis、Elasticsearch 和 MinIO 已就绪。
  5. 沙箱依赖：系统级沙箱默认启用，本地调试工具或 Skill 脚本时应确保 Docker 服务可用。
  6. 代码修改: 修改代码后需重启相关服务，代码注释和 docstring 使用英文
  7. 开发模式: 开发环境建议用调试模式
  8. 提示词测试: 系统提示词需充分测试
  9. 基础设施: 开发前确保基础设施服务正常运行

💡 获取帮助 ​

文档资源 ​

社区支持 ​