diff --git a/README.en.md b/README.en.md
index 96847319..4e2abe19 100644
--- a/README.en.md
+++ b/README.en.md
@@ -1,5 +1,7 @@
-
Yuxi - A Multi-tenant Harness Platform Combining Knowledge Bases and Knowledge Graphs
+
Yuxi
+
+
A multi-tenant agent platform combining RAG and knowledge graphs
Make enterprise knowledge retrievable, reasoned over, and deliverable by agents
[](https://github.com/xerrors/Yuxi/blob/main/docker-compose.yml)
[](https://github.com/xerrors/Yuxi/issues)
@@ -18,19 +20,36 @@
**Image generated by GPT-Image-2.*
+## Introduction
+
+Yuxi is an LLM-powered platform for building knowledge-base and knowledge-graph agents. It unifies **RAG retrieval**, **LightRAG knowledge graphs**, and **LangGraph multi-agent orchestration** into a single multi-tenant workspace: administrators configure knowledge bases, models, and permissions, while users chat — in a ChatGPT-like interface — with agents that can mount Skills, MCPs, sub-agents, and sandbox tools, and receive answers with cited sources, graph-based reasoning, and deliverable artifacts.
+
## Core Features
-- **Agent development**: Built on LangGraph, with support for sub-agents, Skills, MCPs, Tools, and middleware.
-- **Knowledge base (RAG)**: Multi-format document parsing, Embedding / Rerank configuration, and knowledge base evaluation.
-- **Knowledge graph**: Graph construction and visualization based on LightRAG, with property graph support for agent reasoning.
-- **Platform and engineering**: Vue + FastAPI architecture with dark mode, Docker-based development, and production-oriented deployment.
+- 🤖 **Agent development** — Built on LangGraph, with sub-agents (SubAgents), Skills, MCPs, Tools, and middleware; long-running tasks run asynchronously on a background worker, backed by a sandbox file system for persisting, previewing, and downloading tool artifacts.
+- 📚 **Knowledge base (RAG)** — Multi-format document parsing (MinerU / PaddleX / OCR), configurable Embedding and Rerank models, knowledge base evaluation, in-app PDF / image preview, and retrieval sources backfilled as chat citations.
+- 🕸️ **Knowledge graph** — Graph construction and visualization based on LightRAG, with property graph support that feeds directly into agent reasoning.
+- 🏢 **Multi-tenancy & permissions** — User / department-level access control, unified model provider configuration, and API Key authentication for external system integration.
+- ⚙️ **Platform & engineering** — Vue + FastAPI architecture, ready-to-run Docker Compose deployment, dark mode, a lightweight LITE startup mode, and production-grade orchestration.
+
+## Tech Stack
+
+| Layer | Technologies |
+| --- | --- |
+| Frontend | Vue 3 · Vite · Pinia |
+| Backend | FastAPI · LangGraph · ARQ (async worker) |
+| Storage | PostgreSQL · Redis · MinIO · Milvus · Neo4j |
+| Doc parsing | MinerU · PaddleX · RapidOCR |
+| Deployment | Docker Compose |
## Quick Start
-Clone the repository and initialize the project:
+**Prerequisites**: [Docker](https://docs.docker.com/get-docker/) and Docker Compose installed, plus at least one OpenAI-compatible LLM API.
+
+**1. Clone and initialize**
```bash
-git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git
+git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git
cd Yuxi
# Linux/macOS
@@ -40,13 +59,17 @@ cd Yuxi
.\scripts\init.ps1
```
-Start the project with Docker:
+**2. Start with Docker**
```bash
docker compose up --build
```
-After the services are ready, open `http://localhost:5173`.
+**3. Open the platform**
+
+Once the services are ready, open `http://localhost:5173` in your browser and sign in with the admin account generated during initialization.
+
+> 💡 If you don't need heavy dependencies like knowledge bases / graphs, run `make up-lite` for a lightweight LITE mode with faster cold starts. See the [docs](https://xerrors.github.io/Yuxi) for more deployment details.
## Examples and Demo
diff --git a/README.md b/README.md
index d7139bab..f1fb902f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
-
语析 - 结合知识库与知识图谱的多租户 Harness 平台
+
语析 Yuxi
+
+
融合 RAG 与知识图谱的多租户智能体平台
让企业知识可被智能体检索、推理与交付
[](https://github.com/xerrors/Yuxi/blob/main/docker-compose.yml)
[](https://github.com/xerrors/Yuxi/issues)
@@ -20,16 +22,46 @@
**图由 GPT-Image-2 生成*
+## 简介
+
+语析(Yuxi)是一个基于大模型的智能知识库与知识图谱智能体开发平台。它把 **RAG 检索**、**LightRAG 知识图谱** 与 **LangGraph 多智能体编排** 整合进统一的多租户工作台:管理员配置知识库、模型与权限,用户在类 ChatGPT 的界面中与可挂载 Skills、MCP、子智能体和沙盒工具的智能体对话,并获得带引用来源、知识图谱推理与可交付产物的回答。
+
## 核心特性
-- **智能体开发**:基于 LangGraph,支持子智能体、Skills、MCPs、Tools 与中间件机制
-- **知识库(RAG)**:多格式文档解析,支持 Embedding / Rerank 配置及知识库评估
-- **知识图谱**:基于 LightRAG 的图谱构建与可视化,支持属性图谱并参与智能体推理
-- **平台与工程化**:Vue + FastAPI 架构,支持暗黑模式、Docker 与生产级部署
+- 🤖 **智能体开发** —— 基于 LangGraph 构建,支持子智能体(SubAgents)、Skills、MCP、Tools 与中间件机制;长耗时任务由后台 worker 异步执行,配套沙盒文件系统支持工具产物落盘、预览与下载。
+- 📚 **知识库(RAG)** —— 多格式文档解析(MinerU / PaddleX / OCR),可配置 Embedding 与 Rerank 模型,支持知识库评估与 PDF / 图片在线预览,检索来源回填到对话引用。
+- 🕸️ **知识图谱** —— 基于 LightRAG 的图谱构建与可视化,支持属性图谱,并作为检索增强直接参与智能体推理。
+- 🏢 **多租户与权限** —— 用户 / 部门级权限管理,模型供应商统一配置,支持 API Key 认证供外部系统集成调用。
+- ⚙️ **平台与工程化** —— Vue + FastAPI 架构,开箱即用的 Docker Compose 部署,支持暗黑模式、LITE 轻量启动与生产级编排。
+
+## 技术栈
+
+| 层 | 技术 |
+| --- | --- |
+| 前端 | Vue 3 · Vite · Pinia |
+| 后端 | FastAPI · LangGraph · ARQ (异步 worker) |
+| 存储 | PostgreSQL · Redis · MinIO · Milvus · Neo4j |
+| 文档解析 | MinerU · PaddleX · RapidOCR |
+| 部署 | Docker Compose |
## 最新动态
+
+[2026/06] v0.7.0 开发中(重要不兼容变更)
+
+### 重大变更
+
+- **模型配置收敛**:移除旧版 v1 模型配置与 Ollama 支持,运行时统一使用 `provider_id:model_id` 与独立 provider 模块,自定义 provider 迁移到数据库
+- **智能体运行时收敛**:用户可见的 `AgentConfig` 收敛为数据库持久化的一级 `Agent`,新增 `/api/agent` 管理与运行接口,前端只提交 `agent_id`
+- **知识库能力收敛**:移除 Upload 与 LightRAG 知识库/图谱能力,知识库类型收敛为 **Milvus** 与只读连接器(**Dify**、**Notion**);知识图谱仅保留 Milvus 知识库内的构建/展示/检索
+- **Skill 安装与权限收敛**:以 `source_type / share_config / enabled` 表达来源、生效范围与启用状态;内置 Skill 启动自动入库并默认全局启用,上传/远程统一改为「解析草稿 → 确认安装」
+- **用户身份命名收敛**:业务登录标识统一为字符串 `uid`
+
+详见 [开发路线图](docs/develop-guides/roadmap.md)。
+
+
+
[2026/04/01] v0.6.0 版本发布
@@ -87,10 +119,12 @@
## 快速开始
-克隆代码,并初始化
+**前置要求**:已安装 [Docker](https://docs.docker.com/get-docker/) 与 Docker Compose,并准备至少一个兼容 OpenAI 接口的大模型 API。
-```
-git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git
+**1. 克隆代码并初始化**
+
+```bash
+git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git
cd Yuxi
# Linux/macOS
@@ -100,13 +134,17 @@ cd Yuxi
.\scripts\init.ps1
```
-然后需要使用 docker 启动项目
+**2. 使用 Docker 启动**
-```
+```bash
docker compose up --build
```
-等待启动完成后,访问 `http://localhost:5173`
+**3. 访问平台**
+
+等待启动完成后,浏览器打开 `http://localhost:5173`,使用初始化时生成的管理员账户登录即可。
+
+> 💡 不需要知识库 / 知识图谱等重依赖时,可使用 `make up-lite` 以 LITE 轻量模式启动,加快冷启动速度。更多部署说明见 [项目文档](https://xerrors.github.io/Yuxi)。
## 示例与演示
diff --git a/docs/advanced/document-processing.md b/docs/advanced/document-processing.md
index 0f019432..3464b867 100644
--- a/docs/advanced/document-processing.md
+++ b/docs/advanced/document-processing.md
@@ -119,3 +119,4 @@ HOST_IP=your_server_ip
2. **GPU 要求**:MinerU 和 PP-Structure-V3 需要 GPU 支持
3. **API 密钥**:部分服务需要额外的 API 密钥配置
4. **超时处理**:复杂文档解析可能耗时较长,可通过 `MINERU_TIMEOUT` 环境变量调整超时时间
+5. **文件大小限制**:单个上传文件大小不超过 100 MB
diff --git a/docs/agents/middleware.md b/docs/agents/middleware.md
index 4325dbf0..6ec41273 100644
--- a/docs/agents/middleware.md
+++ b/docs/agents/middleware.md
@@ -41,4 +41,4 @@ async def get_graph(self):
## 自定义中间件
-新增中间件时,将其放入 `backend/package/yuxi/agents/common/middlewares` 目录,然后在智能体的 `middleware` 列表中引用即可。
+新增中间件时,将其放入 `backend/package/yuxi/agents/middlewares` 目录,然后在智能体的 `middleware` 列表中引用即可。该目录下已内置知识库挂载(`knowledge_base`)、Skills 注入(`skills`)、附件上下文(`attachment`)、子智能体任务(`subagent_task`)、上下文压缩(`summary`)、动态工具(`dynamic_tool`)等中间件。
diff --git a/docs/agents/sandbox-architecture.md b/docs/agents/sandbox-architecture.md
index 966fb1d1..edbde25d 100644
--- a/docs/agents/sandbox-architecture.md
+++ b/docs/agents/sandbox-architecture.md
@@ -293,7 +293,7 @@ CHECK_YUXI_SANDBOX_ENV_EXISTS=True
## 十四、和旧版文档相比,今天最重要的理解方式
-当前项目不应再按“应用直接管理一个长期存在的本地 sandbox 服务”去理解。更准确的认识应该是:Yuxi 只管理线程和上下文;provisioner 负责创建线程对应的沙盒实例;文件系统不是简单地暴露一个容器根目录,而是把可写工作区、只读 skills 和只读知识库组合成一个受控命名空间。
+当前项目不应再按“应用直接管理一个长期存在的本地 sandbox 服务”去理解。更准确的认识应该是:Yuxi 只管理线程和上下文;provisioner 负责创建线程对应的沙盒实例;文件系统不是简单地暴露一个容器根目录,而是把可写工作区、只读 skills 等组合成一个受控命名空间(知识库不再映射为沙盒目录,改由 `query_kb`/`open_kb_document` 等工具访问)。
因此,当你在界面上“启用沙盒”或者在文档里“选择 K8s”时,本质上做的不是切换一段业务逻辑,而是在切换 provisioner 的底层实例承载方式。选择 `docker` 时,沙盒由当前部署机上的 Docker daemon 动态创建;选择 `kubernetes` 时,沙盒由目标 K8s 集群动态创建。Yuxi 自己始终只面对一个 provisioner 服务地址。
diff --git a/docs/agents/skills-management.md b/docs/agents/skills-management.md
index 5ebb29c0..07789825 100644
--- a/docs/agents/skills-management.md
+++ b/docs/agents/skills-management.md
@@ -164,11 +164,11 @@ Skills 之间可以建立依赖关系,形成一个松耦合的技能网络。
2. 递归展开 `skill_dependencies`,派生 `_prompt_skills` 和 `_readable_skills`
3. 将 `_prompt_skills` 对应的技能说明注入到系统提示词中
-这意味着:只要配置了某个 Skill,它的依赖 Skill 就会立即进入提示词和 `/home/gem/skills` 只读范围。
+这意味着:只要配置了某个 Skill,它的依赖 Skill 就会立即进入提示词和沙盒 `/home/gem/skills` 只读范围。
**阶段二:技能激活**
-当 Agent 通过 `read_file` 工具读取 `/skills//SKILL.md` 时,视为"激活"该技能。系统会:
+当 Agent 通过 `read_file` 工具读取 `/home/gem/skills//SKILL.md` 时,视为"激活"该技能。系统会:
1. 验证该技能在可见列表中
2. 将其添加到 `activated_skills` 列表
3. 后续的模型调用会使用激活列表来加载依赖
@@ -211,13 +211,13 @@ Skills 管理采用基于角色的权限控制:
### Agent 如何使用 Skills
-1. **提示词注入**:系统会在 Agent 的系统提示词开头自动插入可用 Skills 的描述
-2. **文件访问**:Skills 目录以只读方式挂载到 `/skills//...`
+1. **提示词注入**:系统在每次模型请求时动态注入可用 Skills 的描述(请求级注入,避免污染 runtime context)
+2. **文件访问**:Skills 目录以只读方式挂载到 `/home/gem/skills//...`
3. **工具调用**:当 Agent 需要使用某个 Skill 时,会先读取对应的 SKILL.md 了解使用方法
### 文件操作限制
-运行时 `/skills` 路径有以下限制:
+运行时 `/home/gem/skills` 路径有以下限制:
- **只读**:Agent 只能读取文件内容
- **禁止写入**:不能创建、修改或删除文件
- **路径安全**:所有路径都经过安全校验,防止目录穿越攻击
diff --git a/docs/agents/tools-system.md b/docs/agents/tools-system.md
index db3c03b6..b68f4b4e 100644
--- a/docs/agents/tools-system.md
+++ b/docs/agents/tools-system.md
@@ -62,14 +62,16 @@ Qwen-Image 生成能力已迁移为内置 Skill `image-gen`。模型调用与图
from yuxi.agents.toolkits.kbs import get_common_kb_tools
kb_tools = get_common_kb_tools()
-# 返回: [list_kbs, get_mindmap, query_kb]
+# 返回: [list_kbs, get_mindmap, query_kb, find_kb_document, open_kb_document]
```
| 工具 | 说明 |
|------|------|
| `list_kbs` | 列出用户可访问的知识库 |
| `get_mindmap` | 获取知识库的思维导图结构 |
-| `query_kb` | 在指定知识库中检索内容 |
+| `query_kb` | 在指定知识库中检索内容,返回结构化的 `resource_id`(即 `kb_id`)/`file_id`/`chunk` |
+| `find_kb_document` | 在已知文件内按关键词或正则定位内容 |
+| `open_kb_document` | 按 `file_id` 分段打开知识库文档(默认窗口 1800 行) |
## 工具组装
@@ -99,6 +101,6 @@ async def get_tools_from_context(self, context) -> list:
## Skills 集成
-Skills 与工具是两种不同的扩展机制。工具是具体的功能实现,而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 `context.skills` 配置 Skills 时,对应的技能文件会被挂载到 `/skills//...`,智能体可以通过读取 SKILL.md 来了解如何使用这些技能。
+Skills 与工具是两种不同的扩展机制。工具是具体的功能实现,而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 `context.skills` 配置 Skills 时,对应的技能文件会被挂载到沙盒的 `/home/gem/skills//...`,智能体可以通过读取 SKILL.md 来了解如何使用这些技能。
关于 Skills 的详细机制,请参阅 [Skills 管理](./skills-management.md)。
diff --git a/docs/intro/evaluation.md b/docs/intro/evaluation.md
index de79c1a8..adfa2cb9 100644
--- a/docs/intro/evaluation.md
+++ b/docs/intro/evaluation.md
@@ -56,7 +56,7 @@ JSONL 只是导入和导出的交换格式。导入后,系统会把评估数
## 运行评估
-在知识库详情页点击「评估」标签,选择评估基准后配置:
+在知识库详情页左侧边栏,「评估基准」Tab 用于管理评估数据集,「RAG 评估」Tab 用于运行评估并查看结果。在「RAG 评估」中选择评估数据集后配置:
1. **答案生成模型**(可选):基于检索到的文档块生成答案
2. **评判模型**(可选):评估生成答案与标准答案的一致性
diff --git a/docs/intro/knowledge-base.md b/docs/intro/knowledge-base.md
index 41860338..2b9db944 100644
--- a/docs/intro/knowledge-base.md
+++ b/docs/intro/knowledge-base.md
@@ -1,6 +1,6 @@
# 知识库与知识图谱
-Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索,以及 Dify Dataset 只读检索。
+Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索,以及 Dify Dataset、Notion Data Source 只读检索。
## 为什么需要知识库
@@ -15,17 +15,18 @@ Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支
| 类型 | 特点 | 适用场景 |
|------|------|----------|
| **Milvus** | 高性能向量检索,支持文档入库、检索测试、评估和知识图谱构建 | 自建文档知识库与生产检索 |
-| **Dify** | 连接 Dify Dataset 检索 API,只读使用 | 复用已有 Dify 数据集 |
+| **Dify** | 连接 Dify Dataset 检索 API,只读连接器 | 复用已有 Dify 数据集 |
+| **Notion** | 连接 Notion Data Source 检索 API,只读连接器 | 复用已有 Notion 页面内容 |
-历史 LightRAG 类型不再作为受支持类型展示或创建。
+只读连接器(Dify、Notion)仅用于检索,不支持上传与入库;历史 LightRAG 类型不再作为受支持类型展示或创建。
## 创建知识库
访问 Web 界面的「知识库」页面,点击「新建知识库」:
1. 填写知识库名称和描述
-2. 选择 Milvus 或 Dify
-3. Milvus 配置嵌入模型和分块策略;Dify 配置 API URL、Token 和 Dataset ID
+2. 选择知识库类型(Milvus、Dify 或 Notion)
+3. Milvus 配置嵌入模型和分块策略;只读连接器(Dify、Notion)按类型动态渲染连接参数(如 API URL、Token、Dataset ID 等)
4. 配置访问权限
5. 保存
@@ -51,7 +52,7 @@ Milvus 文件从上传到可检索,经历三个阶段:
### 3. 入库阶段
-系统对 Markdown 内容进行分块,将 chunk 元数据保存到 PostgreSQL,并将向量写入 Milvus。
+系统对 Markdown 内容进行分块,将 chunk 内容与元数据双写到 PostgreSQL 的 `knowledge_chunks` 表,并将向量写入 Milvus。
在前端界面中,默认会自动完成前两个阶段。如果需要自动入库,勾选「上传后自动入库」选项;否则需要手动点击入库按钮。
@@ -60,8 +61,8 @@ Milvus 文件从上传到可检索,经历三个阶段:
每个知识库可以配置独立的访问权限:
- **全局共享**:所有用户可访问
-- **部门授权**:仅指定部门可访问
-- **私有**:仅创建者和管理员可访问
+- **部门共享**:指定部门可访问,且必须包含当前用户所在部门
+- **指定人可访问**:仅创建者、管理员及被明确授权的人员可访问
权限规则:
@@ -71,7 +72,7 @@ Milvus 文件从上传到可检索,经历三个阶段:
## 知识图谱
-Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系,并写入 Neo4j 作为图存储。
+Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系,将 entity/triple 本体与 chunk 引用写入 Neo4j 和 PostgreSQL,并为唯一实体/三元组建立 Milvus 语义索引;检索时可召回图谱实体与三元组,并与 chunk 命中结果融合(RRF)。
主要能力:
diff --git a/docs/intro/project-overview.md b/docs/intro/project-overview.md
index b91611e8..c6be39dc 100644
--- a/docs/intro/project-overview.md
+++ b/docs/intro/project-overview.md
@@ -18,8 +18,8 @@ Yuxi (语析) 是一个智能知识库和知识图谱 Agent 开发平台,能
| 状态管理 | Pinia | 前端集中式状态管理 |
| 后端 API | FastAPI, Uvicorn | 高性能异步 Python Web 框架 |
| Agent 框架 | LangGraph v1 | 声明式 Agent 编排与状态管理 |
-| 知识库 | Milvus, Dify | 基于向量存储与外部 Dataset 的 RAG 实现 |
-| 图数据库 | Neo4j | 知识图谱存储与查询 |
+| 知识库 | Milvus(可建库入库)、Dify / Notion(只读连接器) | 向量知识库 RAG 与外部只读数据源检索 |
+| 图数据库 | Neo4j | Milvus 知识库内知识图谱存储与查询 |
| 文档处理 | MinerU, PaddleX, RapidOCR | 多格式文档解析与 OCR |
| 任务队列 | Redis, PostgreSQL Workers | 异步任务处理 |
| 对象存储 | MinIO | 文件与文档存储 |
@@ -47,11 +47,11 @@ Yuxi 提供完整的知识入库链路,而不是只做检索接口封装。文
### 3. 知识图谱参与推理,而不只是展示
-Yuxi 的知识图谱能力不是孤立的可视化模块,而是和 Milvus 知识库入库链路联动的。系统可以从已入库 chunks 中抽取实体和关系,写入 Neo4j,并在知识库详情页展示和检索子图。
+Yuxi 的知识图谱能力不是孤立的可视化模块,而是和 Milvus 知识库入库链路联动的。系统可以从已入库 chunks 中抽取实体和关系,写入 Neo4j 与 PostgreSQL 并为唯一实体/三元组建立 Milvus 语义索引;检索时可召回图谱实体与三元组,并与 chunk 命中结果融合(RRF),在知识库详情页展示和检索子图。
### 4. 面向生产落地的文档理解与平台能力
-为了让知识真正可用,Yuxi 集成了 MinerU、PP-Structure-V3、Docling 等解析能力,覆盖 PDF、Office、Markdown、图片等常见格式,解决原始资料进入系统前的结构化处理问题。
+为了让知识真正可用,Yuxi 集成了 MinerU、PP-Structure-V3、RapidOCR、DeepSeek OCR 等解析能力,覆盖 PDF、Office、Markdown、图片等常见格式,解决原始资料进入系统前的结构化处理问题。
在此基础上,平台还补齐了业务落地常用的工程能力,例如:
diff --git a/docs/intro/quick-start.md b/docs/intro/quick-start.md
index afe7117b..2b699b2b 100644
--- a/docs/intro/quick-start.md
+++ b/docs/intro/quick-start.md
@@ -20,7 +20,7 @@
```bash
# 克隆最新版本
-git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git
+git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git
cd Yuxi
```
@@ -28,7 +28,7 @@ cd Yuxi
| 版本 | 适用场景 |
|------|----------|
-| v0.6.x | 当前开发版本,包含最新特性 |
+| v0.7.x | 当前开发版本,包含最新特性 |
| main | 开发版本,包含最新特性(可能不稳定) |
### 步骤二:配置环境变量