Skip to content

Latest commit

 

History

826 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Novex

Novex 是一套面向企业交付的 AI Agent 基座。它不是单点 AI 应用,而是把账号、租户、权限、知识库、模型路由、Agent 运行时、工具、MCP、连接器、记忆、评测和交付流程沉淀成可复用平台能力,再按客户、行业和场景组合成具体应用。

当前仓库是一个 Rust first 的 monorepo:backend 负责控制平面、HTTP API 和业务编排,crates/* 承载可复用 AI Foundation 能力,adminapps/* 提供管理后台与客户前台应用,services/* 作为 Python/模型 sidecar,scripts.env.example 支撑本地 POC。完整架构长文见 docs/ARCHITECTURE.md,本 README 保持项目首页、模块地图和开发规范入口。

产品截图

Codex-like Agent 工作台
Codex-like Agent 工作台:联网搜索、模型输出和运行事件。
NotebookLM-like 知识工作区
NotebookLM-like 知识工作区:资料、对话和内容生成。
AI 基座模型管理
AI 基座模型管理:模型路由、密钥占位和健康检查。
AI Skills 导入与管理
AI Skills 导入与管理:GitHub Skill 解析、预览和安装。

当前能力

  • 控制平面:认证、RBAC、数据权限、租户资源、用户/角色/菜单/部门、文件/对象存储、系统配置、密钥占位、身份提供商、审计日志、在线用户、调度任务和 API 兼容响应封装。
  • AI Foundation:模型注册与路由、provider 调用、RAG、知识库、Agent run、Agent queue、turn item ledger、Run Graph、工具注册与执行、审批策略、MCP gateway、连接器、插件、trigger、memory、eval、trace 和成本/用量记录。
  • 运行链路:backend、eval-worker、parser-worker、RabbitMQ outbox、Milvus 向量召回、Redis 协调、MinIO 文件资产、PostgreSQL 事实源和可选 model-runtime adapter。
  • 前台应用:管理后台、员工培训、知识库问答、Agent 工作台、Codex-like POC、客服 Agent 应用。
  • 交付体系:客户差异统一通过后台配置租户、角色、菜单、模型路由、知识库、技能、连接器、评测集和前台应用配置,不再维护独立模板配置包。

快速启动

POC 默认复用外部 docker-common 基础设施。当前启动方式是:只有 PostgreSQL、Redis、RabbitMQ、Milvus、MinIO、Attu、Neo4j 这些共享基础设施在 Docker 里;Novex 自己的 backend、eval-worker、parser-worker 和所有前端 app 都用本机进程启动。

层级 启动方式 内容
共享基础设施 外部 docker-common PostgreSQL、Redis、RabbitMQ、Milvus、MinIO、Attu、Neo4j
Novex 后端/worker 本机 cargo run / uv.venv backend、eval-worker、parser-worker
POC 前端 app 本机 pnpm dev Admin、Training Web、NotebookLM、Agent Workspace、Codex App POC

推荐启动顺序:先启动共享基础设施,再让 run-poc.sh 做环境检查和打印本地启动命令。

cd /path/to/docker-common
docker compose up -d postgres redis rabbitmq etcd minio milvus attu neo4j

cd /path/to/Novex
./scripts/run-poc.sh

scripts/run-poc.sh 会读取根目录 .env 作为 POC 汇总配置;如果该文件不存在,会从根目录 .env.example 复制生成。脚本会检查共享容器、创建缺失的 novex 数据库、校验 AI 相关环境变量,并打印下面这些本地启动命令。它不再启动 novex-poc Docker Compose 项目。

Novex 项目进程分别在独立终端启动。默认走低功耗路径:Cargo 只开 1 个编译任务,Rust 测试只开 1 个线程,前端和 worker 按需启动。

(set -a; . .env; set +a; CARGO_BUILD_JOBS="${CARGO_BUILD_JOBS:-1}" cargo backend)

# Codex-like POC 通常只需要 backend + apps/codex-app-poc。
(cd apps/codex-app-poc && pnpm install && NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 pnpm dev)

# 下面这些 worker 和前端只在验证对应产品路径时启动。
(set -a; . .env; set +a; EVAL_WORKER_ENABLED=true DB_AUTO_MIGRATE=false CARGO_BUILD_JOBS="${CARGO_BUILD_JOBS:-1}" cargo run -p backend --bin eval_worker)

# parser-worker 推荐 uv;没有 uv 时使用下面的 .venv 兜底命令。
(set -a; . .env; set +a; PARSER_BACKEND_BASE_URL=http://127.0.0.1:62601 PARSER_BACKEND_TOKEN="${PARSER_CALLBACK_TOKEN}" PYTHONPATH=services/parser-worker uv run --no-project --with-requirements services/parser-worker/requirements.txt python -m parser_worker.worker)

python3 -m venv services/parser-worker/.venv
services/parser-worker/.venv/bin/python -m pip install -r services/parser-worker/requirements.txt
(set -a; . .env; set +a; PARSER_BACKEND_BASE_URL=http://127.0.0.1:62601 PARSER_BACKEND_TOKEN="${PARSER_CALLBACK_TOKEN}" PYTHONPATH=services/parser-worker services/parser-worker/.venv/bin/python -m parser_worker.worker)

(cd admin && pnpm install && NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 pnpm dev)
(cd apps/training-web && pnpm install && NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 pnpm dev)
(cd apps/notebooklm && pnpm install && NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 pnpm dev)
(cd apps/agent-workspace && pnpm install && NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 pnpm dev)

常用命令:

./scripts/run-poc.sh env       # 检查 LLM / Embedding / Reranker / Parser 等配置
./scripts/run-poc.sh commands  # 打印本地启动命令
./scripts/run-poc.sh status    # 提示如何检查本地进程状态
./scripts/run-poc.sh logs      # 提示日志所在终端
./scripts/run-poc.sh down      # 提示如何停止本地进程,并清理旧 novex-poc 容器

默认访问地址:

服务 地址
Backend http://localhost:62601
Admin http://localhost:62602,本地 pnpm dev
Training Web http://localhost:62603,本地 pnpm dev
NotebookLM http://localhost:62604,本地 pnpm dev
Agent Workspace http://localhost:62605,本地 pnpm dev
Codex App POC http://localhost:62606,本地 pnpm dev
RabbitMQ UI http://localhost:15673
MinIO Console http://localhost:19011
Attu http://localhost:18000
Neo4j Browser http://localhost:17474

健康检查:

curl http://localhost:62601/health
curl http://localhost:62601/ready

Agent 联网搜索

web.search 支持 provider chain,按从左到右的顺序自动 fallback。未配置时默认使用免费的 google_news_rss;如果某些区域无法直连 Google,可以把链路改成 tavily,brave,searxng,bing_news_rss,google_news_rss,或只使用可直连的 provider。

NOVEX_WEB_SEARCH_PROVIDERS=tavily,brave,searxng,bing_news_rss,google_news_rss
NOVEX_TAVILY_API_KEY=
NOVEX_BRAVE_SEARCH_API_KEY=
NOVEX_SEARXNG_ENDPOINT=http://localhost:8080/search

每次搜索结果会返回最终命中的 providerattempts,方便在 62606 的运行事件里排查是哪个搜索源失败或成功。

环境配置

环境文件按运行边界管理:根目录 .env / .env.example 是完整 POC 的汇总入口;各可独立运行项目保留自己的 .env.example,只声明该项目实际读取的变量。不要把真实密钥写入任何 example 文件。

文件 作用
.env.example POC 汇总模板,供 scripts/run-poc.sh 生成根目录 .env,覆盖共享基础设施、后端、worker、模型和前端端口。
backend/.env.example 后端和 Rust worker 独立开发模板,覆盖 DB、Redis、RabbitMQ、Milvus、JWT、队列、模型路由和连接器。
services/parser-worker/.env.example parser-worker 独立开发模板,覆盖 backend callback、RabbitMQ、Redis、MinerU 和 worker lease。
admin/.env.example Admin 前端模板。
apps/training-web/.env.exampleapps/notebooklm/.env.exampleapps/agent-workspace/.env.example 客户前台模板,只配置 API 地址。
apps/codex-app-poc/.env.example Codex-like POC 前端模板,额外包含 dev auto-login 和 agent model route 配置。

主要配置组:

  • 基础运行:AUTH_JWT_SECRETHTTP_PORTADMIN_PORTNOTEBOOKLM_PORTTRAINING_WEB_PORTAGENT_WORKSPACE_PORTCODEX_APP_POC_PORT
  • 共享基础设施:COMMON_DOCKER_NETWORKCOMMON_POSTGRES_DATABASEDATABASE_URLREDIS_URLRABBITMQ_URLMILVUS_ENDPOINTMINIO_ENDPOINT
  • 模型能力:LLM_API_KEYLLM_BASE_URLLLM_MODEL
  • 向量与重排:EMBEDDING_API_KEYEMBEDDING_BASE_URLEMBEDDING_MODELRERANKER_API_KEYRERANKER_BASE_URLRERANKER_MODEL
  • 队列运行:PARSER_QUEUE_*AGENT_QUEUE_*EVAL_QUEUE_*RABBITMQ_PARSER_*RABBITMQ_AGENT_*RABBITMQ_EVAL_*
  • Parser:PARSER_CALLBACK_TOKENPARSER_WORKER_MODEPARSER_WORKER_*MINERU_TOKENMINERU_TIMEOUT_SECONDS
  • 外部连接器:GITHUB_CONNECTOR_TOKENGITHUB_API_BASE_URLGITHUB_OAUTH_CLIENT_IDGITHUB_OAUTH_CLIENT_SECRETFEISHU_WEBHOOK_URL
  • 媒体工具:RIGHT_CODE_DRAW_BASE_URLRIGHT_CODE_DRAW_API_KEY

如果缺少部分外部 AI 配置,平台仍可启动;对应的 live chat、RAG embedding、rerank、PDF/Office/Image 解析、GitHub/飞书连接器或媒体工具能力会降级、dry-run 或不可用。

本地开发

后端是 Cargo workspace:

cargo backend
cargo backend-check
cargo runtime-test

仓库默认通过 .cargo/config.toml 将本地 Cargo 并行编译任务数限制为 1,并把 Rust 测试线程数设为 1;同时在 dev/test profile 中保留增量编译、关闭默认 debug info,并把 rustc codegen unit 降到 1,避免每次编译或跑测试把 CPU 打满。需要临时满速时可以显式覆盖:

CARGO_BUILD_JOBS=8 RUST_TEST_THREADS=8 cargo test -p backend model_loop

根 workspace 的 default-members 只保留 backendcrates/novex-agent-runtime,所以裸跑 cargo checkcargo testcargo run 时会优先覆盖 Codex-like/agent loop 迁移的主路径,而不是默认扫完整 workspace。需要完整验证时显式使用:

cargo test --workspace

项目级 VS Code 设置会关闭 rust-analyzer 的保存时自动 cargo check、build script 展开、proc macro 展开和启动缓存预热,限制 rust-analyzer 使用 2 个线程,手动检查也只用单个 Cargo job 且不扫所有 target,并排除 targetnode_modules.next 等大目录 watcher。需要 IDE 自动检查或更快索引时,可以在个人用户设置里覆盖这些值。

如果电脑仍然发烫,继续保持单任务并缩小编译范围:

CARGO_BUILD_JOBS=1 RUST_TEST_THREADS=1 cargo check -p backend --lib

尽量不要在日常开发中频繁执行全量 cargo clean;它会删除增量编译缓存,下一次 Rust 命令会变成更重的全量编译。只有需要释放磁盘空间或排查缓存问题时再清理;如果只是当前迁移路径需要释放空间,优先用 cargo backend-cleancargo runtime-clean

做 Codex-like / agent loop 迁移时,优先跑窄范围命令,避免全 workspace 编译:

CARGO_BUILD_JOBS=1 RUST_TEST_THREADS=1 cargo test -p novex-agent-runtime --test codex_like_runtime
CARGO_BUILD_JOBS=1 RUST_TEST_THREADS=1 cargo test -p backend model_loop
(cd apps/codex-app-poc && pnpm test -- src/lib/workbench-events.test.ts src/lib/agent-events.test.ts)

需要验证真实 Codex-like ReAct 分支时,在 backend 和 Codex App POC 已启动后运行 live smoke。打开 NOVEX_AGENT_SMOKE_EXPECT_REACT_TOOL=1 后,脚本会要求事件流同时包含 intent_routedmodel_inference,以及与 intent_routed.selectedToolCode 匹配的 tool-call/observation 或 approval-pause 证据:

(cd apps/codex-app-poc && NOVEX_LIVE_AGENT_SMOKE=1 NEXT_PUBLIC_API_BASE_URL=http://localhost:62601 NOVEX_AGENT_SMOKE_EXPECT_REACT_TOOL=1 pnpm smoke:agent-live)

本地启动也尽量只开当前验证路径。Codex-like POC 通常只需要 backend 和 apps/codex-app-poc;eval-worker、parser-worker、Admin、Training Web、NotebookLM、Agent Workspace、Research Radar 都是按需启动。

完整 POC 推荐从仓库根目录启动并共享根目录 .env。单独开发某个项目时,用该项目自己的 .env.example 生成本地 env:后端和 parser-worker 可以复制成各自目录下的 .env,Next.js 前端复制成对应目录下的 .env.local

POC 本地开发时,后端和 eval-worker 直接使用 Cargo,parser-worker 使用 uv 或 .venv,前端使用 pnpm。完整启动命令见上方“快速启动”。

(cd admin && pnpm typecheck && pnpm test)
(cd apps/training-web && pnpm typecheck && pnpm test)
(cd apps/notebooklm && pnpm typecheck && pnpm test)
(cd apps/agent-workspace && pnpm typecheck && pnpm test)
(cd apps/codex-app-poc && pnpm typecheck && pnpm test)

在对应前端目录内执行这些命令。

仓库结构与模块

Novex/
  backend/                 Rust Axum API,控制平面、业务编排、HTTP/WebSocket 接口、worker bins 和后端 .env.example
  crates/                  AI Foundation Rust crates
    novex-ai-core/         tenant context、budget、integration usage、Foundation module、Run Graph
    novex-agent-protocol/  Agent turn item、tool observation、turn outcome 协议
    novex-agent-runtime/   streamed item parser、runtime state reducer
    novex-agent/           intent router、planner、tool selection 和 Agent module metadata
    novex-approval-review/ approval policy、guardian model review、circuit breaker
    novex-model/           模型 provider、route、policy、taxonomy、usage、cost、key masking
    novex-provider-client/ provider HTTP/chat/media/native-cancel/RAG/compaction transport
    novex-rag/             chunk、parse、knowledge model、Milvus request、retrieval、answer builder
    novex-tools/           tool definitions、router、executor、adapters、concurrency、media、risk policy
    novex-connectors/      connector kind、credential binding、GitHub、飞书
    novex-mcp/             JSON-RPC、OAuth、stdio、streamable HTTP、registration、tool code
    novex-plugin/          builtin manifest、plugin types、permission validation
    novex-skill/           skill path、resource kind、技能资源归属
    novex-trigger/         webhook validation、delivery log、source/target kind
    novex-memory/          memory type、scope 和上下文构建
    novex-eval/            eval case、score、report、trace extraction
    novex-trace/           trace event、bundle、replay summary
  admin/                   Next.js 管理后台和前端 .env.example
  apps/
    training-web/          员工培训模板
    notebooklm/              默认 LLM Chat / 知识库问答前台
    agent-workspace/       Agent 工作台模板
    codex-app-poc/         Codex-like POC 应用
    customer-service-agent/客服 Agent 模板应用
  services/
    parser-worker/         Python sidecar,文档解析、MinerU、OCR、格式转换和 worker .env.example
    model-runtime/         可选模型运行时 adapter
  docs/                    架构、计划和交付文档
  scripts/                 POC 启动和 smoke 脚本
  .env.example             本地 POC 汇总环境 schema/defaults;真实值写入未提交的 .env

后端内部采用分层目录:

backend/src/
  application/             用例服务:auth、rbac、system、scheduler、monitor、AI orchestration
  domain/                  领域模型:auth、rbac、data_scope 等稳定概念
  infrastructure/          db、RabbitMQ、repository、storage、security
  interfaces/              HTTP/WebSocket route、middleware、extractor
  shared/                  config、error、response、pagination、time、id
  bin/                     eval_worker、scheduler_worker 等独立进程入口

功能模块说明

模块 位置 说明
控制平面与 RBAC backend/src/application/{auth,rbac,system,identity,data_scope} 认证、用户、角色、菜单、部门、数据权限、密钥占位、身份提供商和外部账号绑定。
监控与调度 backend/src/application/{monitor,scheduler}backend/src/bin/* 系统日志、在线用户、定时任务、安全 HTTP 调度、独立 scheduler/eval worker 入口。
AI 编排 API backend/src/application/aibackend/src/interfaces/http/ai 知识库、模型、Agent、工具、MCP、memory、eval、trigger、notebook、studio、客服 Agent 等 HTTP/API 编排。
Run Graph 与核心上下文 crates/novex-ai-core 租户上下文、资源引用、预算、集成用量、Foundation module 状态和 AI run graph 的通用结构。
模型路由与 provider 调用 crates/novex-modelcrates/novex-provider-client 模型注册、能力分类、路由策略、成本/用量、chat/media/RAG/native cancel/compaction transport。
RAG 与知识库 crates/novex-ragbackend/src/application/ai/knowledge_service.rs 文档解析结果入库、chunk、embedding、Milvus 召回、关键词 fallback、rerank、引用和答案构建。
Agent Runtime crates/novex-agent*backend/src/application/ai/agent_* turn item 协议、流式 item 解析、runtime 状态、intent/planner/tool selection、队列化 agent run、事件轮询/WebSocket。
工具与审批 crates/novex-toolscrates/novex-approval-review tool schema、路由、执行 envelope、并发控制、风险等级、approval policy、guardian review 和 breaker。
MCP 与连接器 crates/novex-mcpcrates/novex-connectors MCP server 注册、OAuth/token dispatch、stdio/streamable HTTP 客户端、GitHub/飞书 connector credential。
插件、技能、触发器 crates/novex-plugincrates/novex-skillcrates/novex-trigger 插件 manifest、权限声明、技能资源、webhook/schedule/plugin event 入口、delivery/retry/dead-letter 语义。
Memory、Eval、Trace crates/novex-memorycrates/novex-evalcrates/novex-trace 会话/用户/组织/项目记忆上下文、评测用例/评分/报告、trace bundle 与回放摘要。
Parser Worker services/parser-worker RabbitMQ parser job 消费、Redis lease/idempotency、MinerU v4 client、文本解析 fallback、backend callback。
Model Runtime services/model-runtime 可选模型运行时 adapter,用于内网开源模型、本地 embedding/rerank 或实验性模型服务接入。
前台应用 adminapps/* Admin 控制台、Training Web、NotebookLM、Agent Workspace、Codex-like POC、客服 Agent route contract。
统一交付配置 adminbackend/src/application/ai/* 客户交付差异通过后台配置租户、RBAC、模型路由、知识库、技能、连接器、插件、触发器、评测集和前台应用入口。

架构边界

Novex 采用 Rust first、Python sidecar、Next.js frontend:

  • Rust 负责长期稳定、强权限、强并发、强审计的核心控制面和 AI 编排能力。
  • Python 只作为插件型 sidecar,承载 MinerU、LibreOffice、OCR、文档版面分析、本地模型 adapter 或实验性 connector。
  • Next.js 负责管理后台和客户可交付前台模板。
  • 跨语言调用通过 HTTP、queue job、MCP/tool schema 或稳定 API 完成;sidecar 不直接绕过后端访问核心业务表。
  • PostgreSQL 是控制面和 AI 元数据事实源;Milvus、Redis、RabbitMQ、MinIO、Neo4j 都是可替换的运行支撑,不替代权限和审计边界。

总体分层:

Customer Apps
  培训系统 / 知识库问答 / 客服辅助 / 研发助手 / 运营自动化
        |
App Template Layer
  标准前台模板 / 客户品牌 / 行业页面 / 业务工作台 / 管理后台
        |
AI Foundation Layer
  Agent Runtime / Run Graph / RAG / Model / Tools / MCP / Eval / Trace
        |
Control Plane
  RBAC / Tenant / Audit / Config / Scheduler / File / Observability
        |
Infrastructure
  PostgreSQL / Milvus / Redis / RabbitMQ / MinIO / Parser Worker / Model Runtime

设计原则:

  1. 权限优先:知识库、工具、技能、记忆、会话和评测数据都必须经过租户、用户、角色和资源权限过滤。
  2. 后端只做控制面、HTTP API 和编排;RAG、Agent、Model、Tool、MCP、Eval、Trace 等通用领域逻辑沉淀到对应 crates/*
  3. crates/* 不能反向依赖 backend/src;跨 crate 类型优先放在 novex-ai-core 或对应领域 crate。
  4. 所有模型调用先经过 novex-model 的路由/策略,再由 novex-provider-client 或受控 adapter 执行,避免在业务 service 中硬编码 provider。
  5. RAG 与 Agent 分离:知识问答走 RAG;源码检索、工具执行和任务自动化走 Agentic Search + Tool Use。
  6. 外部动作必须进入 Tool Registry,声明 schema、风险、权限、审批、超时和审计;中高风险动作默认经过 approval/guardian 机制。
  7. GitHub 登录属于 Identity Provider;GitHub repo/issue/PR 操作属于 Connector + Tool;两类凭据不能混用。
  8. MCP 统一走 gateway、registration、OAuth/secret、stdio 或 streamable HTTP client,不让 Agent 直接散落调用外部 server。
  9. Parser/model sidecar 只通过 API、queue job、callback 或 MCP/tool schema 交付结果,不直接写核心业务表。
  10. 客户差异优先沉淀为模板、权限、技能、模型路由、连接器配置、页面配置和运行策略,避免为单个客户 fork 核心代码。
  11. 可观测、可评测、可回放:检索、重排、模型调用、工具调用、意图路由、审批和 Agent turn item 都要留下 trace 或可查询事件。
  12. POC 阶段保持资源可控:优先复用 PostgreSQL、Milvus Standalone、Redis、RabbitMQ、MinIO、外部 OpenAI-compatible endpoint 和独立 parser worker。

当前依赖方向:

backend
  -> novex-ai-core / novex-model / novex-provider-client / novex-rag
  -> novex-agent / novex-agent-protocol / novex-agent-runtime
  -> novex-tools / novex-approval-review / novex-mcp / novex-connectors
  -> novex-plugin / novex-skill / novex-trigger / novex-memory / novex-eval / novex-trace

novex-agent
  -> novex-ai-core / novex-model / novex-rag / novex-tools / novex-memory

novex-agent-runtime
  -> novex-agent-protocol / novex-tools

novex-provider-client
  -> novex-model / novex-tools

novex-rag
  -> novex-ai-core / novex-model

novex-tools
  -> novex-ai-core / novex-model / novex-connectors

novex-mcp
  -> novex-ai-core / novex-tools

novex-plugin
  -> novex-ai-core / novex-tools / novex-connectors / novex-trigger

文档索引

  • docs/ARCHITECTURE.md:完整 AI Agent Foundation 架构说明。
  • backend/README.md:后端本地账号、迁移 smoke、Milvus、GitHub、飞书、媒体工具和 API 响应契约。
  • docs/plans:按日期沉淀的设计和实施计划。

维护约定

  • 根 README 保持入口级别,不承载完整架构长文;深入设计写入 docs/
  • 新增运行依赖时,同步更新对应项目的 .env.example;如果完整 POC 也需要该变量,再同步更新根目录 .env.examplescripts/run-poc.sh 和本 README。
  • 新增前台应用时,同步更新 apps/ 目录说明、默认端口、该 app 的 .env.example 和 POC 启动脚本。
  • 新增客户前台应用时,同步更新对应 apps/* README、环境模板、后台菜单/权限和 smoke/test 脚本。

About

No description, website, or topics provided.

Resources

Stars

22 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages