pub_soft/WeKnora
3
0
Fork 0
mirror of https://github.com/Tencent/WeKnora.git synced 2026-06-04 13:30:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add wiki documentation with cross-referenced links

Browse Source 
- Create structured wiki from docs/ directory
- Add 17 markdown pages organized in 7 categories
- Include standard Markdown relative path links for navigation
- Add Mermaid knowledge graph visualization in Home.md
This commit is contained in:
Liwx1014
2026-04-15 20:16:27 +08:00
committed by lyingbug
parent d2c6814f22
commit 2beb64c429
19 changed files with 1684 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/wiki/API参考/API文档概览.md Normal file
View File

@@ -0,0 +1,91 @@
---
title: API文档概览
tags: [API参考, REST, 认证, 接口]
aliases: [API概览, API文档, API参考]
source: api/README.md
---
# API 文档概览
WeKnora 提供了一系列 RESTful API，用于创建和管理知识库、检索知识，以及进行基于知识的问答。
## 基础信息
- **基础 URL**: `/api/v1`
- **响应格式**: JSON
- **认证方式**: API Key
> API 认证使用 WeKnora 本地 JWT，OIDC 认证流程参见 [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md)
## 认证机制
所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key`：
```
X-API-Key: your_api_key
X-Request-ID: unique_request_id # 建议，便于追踪
```
API Key 在 Web 页面完成账户注册后，前往账户信息页面获取。
## 错误处理
```json
{
"success": false,
"error": {
"code": "错误代码",
"message": "错误信息",
"details": "错误详情"
}
}
```
## API 分类
| 分类 | 描述 | 详细文档 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理 | [auth.md](../../api/auth.md) |
| 租户管理 | 创建和管理租户账户 | [tenant.md](../../api/tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](../../api/knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](../../api/knowledge.md) |
| 模型管理 | 配置和管理各种AI模型 | [model.md](../../api/model.md) |
| 分块管理 | 管理知识的分块内容 | [chunk.md](../../api/chunk.md) |
| 标签管理 | 管理知识库的标签分类 | [tag.md](../../api/tag.md) |
| FAQ管理 | 管理FAQ问答对 | [faq.md](../../api/faq.md) |
| 智能体管理 | 创建和管理自定义智能体 | [agent.md](../../api/agent.md) |
| 会话管理 | 创建和管理对话会话 | [session.md](../../api/session.md) |
| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](../../api/knowledge-search.md) |
| 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](../../api/chat.md) |
| 消息管理 | 获取和管理对话消息 | [message.md](../../api/message.md) |
| 评估功能 | 评估模型性能 | [evaluation.md](../../api/evaluation.md) |
| 初始化管理 | 知识库模型配置与 Ollama 管理 | [initialization.md](../../api/initialization.md) |
| 系统管理 | 系统信息、解析引擎、存储引擎 | [system.md](../../api/system.md) |
| MCP 服务 | MCP 工具服务管理 | [mcp-service.md](../../api/mcp-service.md) |
| 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](../../api/organization.md) |
| Skills | 预装智能体技能 | [skill.md](../../api/skill.md) |
| 网络搜索 | 网络搜索服务商 | [web-search.md](../../api/web-search.md) |
| 向量存储 | 向量数据库连接管理 | [vector-store.md](../../api/vector-store.md) |
> 各 API 的详细说明参见 `docs/api/` 目录下的对应文档
## 相关主题
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — API 认证的 OIDC 流程
- [内置模型管理](../核心功能/内置模型管理.md) — 模型管理 API 的配置参考
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 服务管理 API 的使用
- [共享空间说明](../安全认证/共享空间说明.md) — 组织管理 API 的业务逻辑
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道管理 API
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源管理 API
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — API 认证机制与 OIDC 相关
- [内置模型管理](../核心功能/内置模型管理.md) — 模型管理 API 的底层配置
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 服务 API 的使用场景
- [共享空间说明](../安全认证/共享空间说明.md) — 组织管理 API 的业务逻辑
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道 API 的使用场景
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源 API 的使用场景

123
docs/wiki/Home.md Normal file
View File

@@ -0,0 +1,123 @@
---
title: WeKnora Wiki 首页
tags: [首页, 导航, MOC]
aliases: [Home, Index, wiki首页]
---
# WeKnora Wiki
欢迎使用 WeKnora 知识库 wiki！这里是 WeKnora 项目文档的互联知识网络，所有页面通过双向链接关联，帮助你从任意入口探索整个知识体系。
---
## 项目概述
| 页面 | 简介 |
|------|------|
| [版本路线图](项目概述/版本路线图.md) | 产品规划与计划方向 |
| [Lite与标准版区别](项目概述/Lite与标准版区别.md) | 轻量版与标准版的功能对比 |
## 核心功能
| 页面 | 简介 |
|------|------|
| [知识图谱](核心功能/知识图谱.md) | Neo4j 知识图谱的快速开始与使用 |
| [开启知识图谱功能](核心功能/开启知识图谱功能.md) | 知识图谱功能的完整启用流程 |
| [MCP功能使用说明](核心功能/MCP功能使用说明.md) | MCP 服务的用户操作指南 |
| [内置MCP服务管理](核心功能/内置MCP服务管理.md) | 内置 MCP 服务的系统级管理 |
| [内置模型管理](核心功能/内置模型管理.md) | 内置模型的系统级管理 |
| [Agent技能系统](核心功能/Agent技能系统.md) | Agent Skills 扩展机制与预加载技能 |
## 集成与扩展
| 页面 | 简介 |
|------|------|
| [IM集成开发](集成扩展/IM集成开发.md) | 企业即时通讯平台接入开发 |
| [数据源导入开发](集成扩展/数据源导入开发.md) | 外部平台数据自动同步与导入 |
| [添加网络搜索引擎](集成扩展/添加网络搜索引擎.md) | 扩展新的网络搜索 Provider |
| [集成向量数据库](集成扩展/集成向量数据库.md) | 集成新的向量数据库检索引擎 |
## 安全与认证
| 页面 | 简介 |
|------|------|
| [OIDC认证调用流程](安全认证/OIDC认证调用流程.md) | OIDC 第三方登录的完整调用链路 |
| [共享空间说明](安全认证/共享空间说明.md) | 跨租户协作与知识库/智能体共享 |
## 开发与部署
| 页面 | 简介 |
|------|------|
| [开发指南](开发部署/开发指南.md) | 本地开发环境搭建与工作流 |
| [快速开发模式](开发部署/快速开发模式.md) | 后端/前端热更新开发模式 |
## 运维与排障
| 页面 | 简介 |
|------|------|
| [常见问题](运维排障/常见问题.md) | 部署与使用中的 FAQ |
## API 参考
| 页面 | 简介 |
|------|------|
| [API文档概览](API参考/API文档概览.md) | RESTful API 基础信息与分类索引 |
---
## 知识图谱
```mermaid
graph TB
Home[WeKnora Wiki]
Home --> 项目概述
Home --> 核心功能
Home --> 集成扩展
Home --> 安全认证
Home --> 开发部署
Home --> 运维排障
Home --> API参考
项目概述 --> ROADMAP[版本路线图]
项目概述 --> LITE[Lite与标准版区别]
核心功能 --> KG[知识图谱]
核心功能 --> KGSetup[开启知识图谱功能]
核心功能 --> MCP[MCP功能使用说明]
核心功能 --> BuiltinMCP[内置MCP服务管理]
核心功能 --> BuiltinModel[内置模型管理]
核心功能 --> Skills[Agent技能系统]
集成扩展 --> IM[IM集成开发]
集成扩展 --> DS[数据源导入开发]
集成扩展 --> WebSearch[添加网络搜索引擎]
集成扩展 --> VecDB[集成向量数据库]
安全认证 --> OIDC[OIDC认证调用流程]
安全认证 --> SharedSpace[共享空间说明]
开发部署 --> DevGuide[开发指南]
开发部署 --> QuickDev[快速开发模式]
运维排障 --> FAQ[常见问题]
API参考 --> APIOverview[API文档概览]
KG -.-> KGSetup
MCP -.-> BuiltinMCP
BuiltinMCP -.-> BuiltinModel
Skills -.-> IM
IM -.-> DS
DS -.-> SharedSpace
OIDC -.-> SharedSpace
LITE -.-> SharedSpace
WebSearch -.-> VecDB
DevGuide -.-> QuickDev
FAQ -.-> DevGuide
```
---
## 反向链接
本页为 wiki 首页，所有页面均链接回此处。

91
docs/wiki/安全认证/OIDC认证调用流程.md Normal file
View File

@@ -0,0 +1,91 @@
---
title: OIDC认证调用流程
tags: [安全认证, OIDC, 认证, 登录, SSO]
aliases: [OIDC, OIDC认证, SSO登录, 第三方登录]
source: OIDC认证调用流程.md
---
# OIDC 认证调用流程
本文档说明 WeKnora 当前 OIDC 登录能力的实际调用过程，覆盖前后端完整链路。
> OIDC 认证是标准版多租户场景下的登录方式，[Lite 版](../项目概述/Lite与标准版区别.md)不需要
## 整体设计说明
本项目的 OIDC 登录采用 **后端发起授权参数生成、后端接收回调并完成 code 换 token、前端通过 URL hash 接收最终登录结果** 的模式。
核心特点：
1. **前端只负责发起跳转**，不直接和 OIDC Provider 交换 token
2. **后端负责用授权码 `code` 向 OIDC Provider 换取 token**
3. 后端拿到 OIDC 用户信息后，会查找本地用户；若不存在则自动创建本地账号和默认租户
4. 最终签发 WeKnora 自己的本地 JWT，OIDC token 只用于后端换取用户身份
> 自动创建用户与租户的逻辑与 [共享空间说明](../安全认证/共享空间说明.md) 的多租户模型相关
## 相关接口
| 接口 | 说明 |
|------|------|
| `GET /api/v1/auth/oidc/config` | 获取 OIDC 是否启用及 Provider 展示名称 |
| `GET /api/v1/auth/oidc/url` | 生成第三方登录跳转地址 |
| `GET /api/v1/auth/oidc/callback` | OIDC Provider 回调地址 |
## 调用流程（4 个阶段）
### 阶段一：前端发现能力
前端调用 `/auth/oidc/config`，决定是否展示第三方登录入口。
### 阶段二：浏览器跳转授权
前端调用 `/auth/oidc/url` 获取授权地址，然后跳转到 OIDC Provider。
### 阶段三：后端完成身份兑换
Provider 回调后端 `/auth/oidc/callback`，后端用 `code` 换 token、拉取用户信息、关联或创建本地用户，并签发 WeKnora JWT。
### 阶段四：前端接收最终结果
后端 302 回前端，通过 `#oidc_result` 传递登录结果；前端在 `App.vue` 中统一解析。
## 关键配置项
| 配置项 | 说明 |
|--------|------|
| `OIDC_AUTH_ENABLE` | 是否启用 OIDC 登录 |
| `OIDC_AUTH_CLIENT_ID` | OIDC Client ID |
| `OIDC_AUTH_CLIENT_SECRET` | OIDC Client Secret |
| `OIDC_AUTH_DISCOVERY_URL` | OIDC Discovery 地址 |
| `OIDC_AUTH_SCOPES` | Scope 列表，默认 `openid profile email` |
启用时的最小要求：`client_id` + `client_secret` + (`discovery_url` 或 `authorization_endpoint + token_endpoint`)
## 本地联调示例（Dex）
项目中已提供 Dex 示例配置：`misc/dex-config.yaml`。
> 除 Dex 外，也可以使用 KeyCloak 等其他符合 OpenID Connect 协议的 Provider
## 注意事项
1. **`redirect_uri` 必须严格匹配** Provider 客户端配置
2. **邮箱是本地账号关联主键** — 若 Provider 没返回 email，将无法完成登录
3. **首次 OIDC 登录会自动创建用户和默认租户**
4. **真正用于访问 API 的是本地 JWT**，不是 OIDC access token
## 相关主题
- [共享空间说明](../安全认证/共享空间说明.md) — 多租户场景下的用户与组织管理
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 版无需 OIDC（单租户）
- [API文档概览](../API参考/API文档概览.md) — API 认证机制
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [共享空间说明](../安全认证/共享空间说明.md) — OIDC 创建的用户与租户可用于共享空间
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不需要 OIDC（单租户无需注册）
- [API文档概览](../API参考/API文档概览.md) — API 的认证机制与 OIDC JWT 相关

76
docs/wiki/安全认证/共享空间说明.md Normal file
View File

@@ -0,0 +1,76 @@
---
title: 共享空间说明
tags: [安全认证, 共享空间, 协作, 多租户, 权限]
aliases: [共享空间, SharedSpace, Organization, 组织]
source: 共享空间说明.md
---
# 共享空间说明
本文档说明 WeKnora 中的**共享空间**功能，包括空间创建与加入、成员角色与权限、知识库与智能体共享规则。
> 共享空间是标准版功能，[Lite 版](../项目概述/Lite与标准版区别.md)不提供
## 共享空间概述
共享空间是跨租户协作的载体。用户可以在同一系统内属于不同租户（账户），通过**加入同一共享空间**，实现：
- 共享知识库：将本租户的知识库共享到空间，供空间内其他成员使用
- 共享智能体：将本租户的智能体共享到空间，供空间内其他成员在对话等场景中使用
- 访问他人共享的知识库和智能体
### 核心概念对照
| 概念 | 说明 |
|------|------|
| 共享空间 | 系统中的「组织」（Organization），用于跨租户共享 |
| 空间创建者 | 自动成为管理员，不可被移除或降级 |
| 空间成员 | 管理员 / 编辑者 / 只读 三种角色 |
| 知识库/智能体归属 | 始终属于一个租户；共享不改变归属 |
## 角色与权限
| 能力 | 管理员 | 编辑者 | 只读 |
|------|:-:|:-:|:-:|
| 查看、检索共享知识库 | ✓ | ✓ | ✓ |
| 编辑共享知识库内容 | ✓ | ✓ | ✗ |
| 将知识库共享到本空间 | ✓ | ✓ | ✗ |
| 管理空间设置与成员 | ✓ | ✗ | ✗ |
| 生成/刷新邀请码 | ✓ | ✗ | ✗ |
## 知识库共享规则
- 只有知识库所属租户下的用户才能发起共享
- 发起人必须是目标空间的**管理员**或**编辑者**
- 共享时指定权限：只读或可写
- 同一知识库可共享到多个空间，各自独立配置权限
## 智能体共享规则
- 智能体共享到空间时**仅支持只读**
- 同一智能体可共享到多个空间
> 智能体须已配置完成（如已选模型、若使用知识库则已选 rerank 模型等）方可共享。模型配置参见 [内置模型管理](../核心功能/内置模型管理.md)
## 智能体停用机制
- 停用是当前租户对**通过共享空间获得的智能体**的个人偏好设置
- 仅影响本租户在对话中选择智能体时的展示，不改变共享关系
- 不影响其他成员
## 相关主题
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多租户场景下的用户认证
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源导入的知识库可被共享
- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前需确保模型已配置
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多租户用户体系支撑共享空间
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 导入的知识库可通过共享空间共享
- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前的模型配置要求

94
docs/wiki/开发部署/开发指南.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: 开发指南
tags: [开发部署, 开发, 本地开发, 环境搭建]
aliases: [开发环境, DevGuide, 开发指南]
source: 开发指南.md
---
# 开发指南
## 快速开发模式（推荐）
如果需要频繁修改 `app` 或 `frontend` 代码，不需要每次都重新构建 Docker 镜像，可以使用本地开发模式。
> 详细的开发模式说明参见 [快速开发模式](../开发部署/快速开发模式.md)
### 方式一：使用 Make 命令（推荐）
```bash
# 终端 1：启动基础设施
make dev-start
# 终端 2：启动后端
make dev-app
# 终端 3：启动前端
make dev-frontend
```
### 方式二：使用脚本命令
```bash
./scripts/dev.sh start # 启动基础设施
./scripts/dev.sh app # 启动后端
./scripts/dev.sh frontend # 启动前端
```
## 访问地址
| 服务 | 地址 |
|------|------|
| 前端开发服务器 | http://localhost:5173 |
| 后端 API | http://localhost:8080 |
| PostgreSQL | localhost:5432 |
| Redis | localhost:6379 |
| MinIO Console | http://localhost:9001 |
| Neo4j Browser | http://localhost:7474 |
| Jaeger UI | http://localhost:16686 |
> Neo4j 的使用参见 [知识图谱](../核心功能/知识图谱.md) 和 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
## 使用 Air 实现后端热重载
```bash
go install github.com/air-verse/air@latest
air # 修改 Go 代码后自动重新编译和重启
```
## 前端独立开发
```bash
cd frontend
npm run dev # 连接到 http://localhost:8080 的后端 API
```
## 生产环境部署
```bash
sh scripts/build_images.sh # 构建所有镜像
sh scripts/start_all.sh # 启动生产环境
```
## 常见问题
- **启动 dev-app 时报错连接不到数据库**：确保先运行了 `make dev-start`
- **前端 CORS 错误**：检查 `vite.config.ts` 中的代理配置
- **DocReader 需要重新构建**：`sh scripts/build_images.sh -d`
> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
## 相关主题
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构说明
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 配置
- [Agent技能系统](../核心功能/Agent技能系统.md) — 沙箱镜像的构建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构对比说明
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 启动
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 开发环境中启用图谱功能
- [常见问题](../运维排障/常见问题.md) — 开发相关故障排查

84
docs/wiki/开发部署/快速开发模式.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: 快速开发模式
tags: [开发部署, 开发, 热更新, Air]
aliases: [快速开发, QuickDev, dev模式]
source: 快速开发模式说明.md
---
# 快速开发模式
解决开发流程中，每次修改 `app`（后端）或 `frontend`（前端）代码后，都需要打包 Docker 镜像的问题，实现这两个模块的热更新。
> 本页是 [开发指南](../开发部署/开发指南.md) 的补充，提供更详细的架构说明
## 使用方法
### 方式 1：Make 命令（推荐）
```bash
make dev-start # 终端 1：启动基础设施
make dev-app # 终端 2：启动后端
make dev-frontend # 终端 3：启动前端
```
### 方式 2：开发脚本
```bash
./scripts/dev.sh start # 终端 1
./scripts/dev.sh app # 终端 2
./scripts/dev.sh frontend # 终端 3
```
### 方式 3：一键启动
```bash
./scripts/quick-dev.sh
```
### 使用 Air 实现后端热重载
```bash
go install github.com/air-verse/air@latest
make dev-app # 自动检测 Air 并使用
```
## 架构对比
### 开发模式
```
本地后端 App (:8080) ← 本地前端 UI (:5173) → Docker 基础设施容器
(PostgreSQL/Redis/MinIO/Neo4j/DocReader)
```
- 后端/前端在本地直接运行，修改后秒级生效
- 基础设施仍使用 Docker 容器
### 生产模式
```
容器后端 App (:8080) ← 容器前端 UI (:80) → 基础设施容器
```
- 所有服务均运行在 Docker 容器中
- 每次修改需要重新构建镜像
## 效率对比
| 方式 | 每次修改耗时 |
|------|------------|
| 旧方式（重建镜像） | 2-5 分钟 |
| 新方式（本地开发） | 后端 5-10 秒，前端实时热重载 |
## 相关主题
- [开发指南](../开发部署/开发指南.md) — 完整的开发环境搭建指南
- [常见问题](../运维排障/常见问题.md) — 开发模式相关问题排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开发指南](../开发部署/开发指南.md) — 完整开发指南（本页的补充说明）
- [常见问题](../运维排障/常见问题.md) — 开发模式相关故障排查

110
docs/wiki/核心功能/Agent技能系统.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: Agent技能系统
tags: [核心功能, Agent, Skills, 技能, 沙箱]
aliases: [Agent Skills, 技能系统, agent-skills]
source: agent-skills.md
---
# Agent 技能系统
## 概述
Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同，Skills 通过注入到 System Prompt 来扩展 Agent 的能力，遵循 **Progressive Disclosure（渐进式披露）** 的设计理念。目前仅支持带**智能推理**能力的智能体使用。
### 核心特性
- **非侵入式扩展**：不影响原有 Agent ReAct 流程
- **按需加载**：三级渐进式加载，优化 Token 使用
- **沙箱执行**：脚本在隔离环境中安全执行
- **灵活配置**：支持多目录、白名单过滤
> Skills 与 [MCP](../核心功能/MCP功能使用说明.md) 是两种不同的 Agent 扩展机制：Skills 通过 Prompt 注入，MCP 通过协议调用外部工具。
## 设计理念
### Progressive Disclosure（渐进式披露）
```
┌─────────────────────────────────────────────────────────────────┐
│ Level 1: 元数据 (Metadata) │
│ • 始终加载到 System Prompt • 约 100 tokens/skill │
│ • 包含：技能名称 + 简短描述 │
└─────────────────────────────────────────────────────────────────┘
↓ 用户请求匹配时
┌─────────────────────────────────────────────────────────────────┐
│ Level 2: 指令 (Instructions) │
│ • 通过 read_skill 工具按需加载 • SKILL.md 的指令内容 │
│ • 包含：详细指令、代码示例、使用方法 │
└─────────────────────────────────────────────────────────────────┘
↓ 需要更多信息时
┌─────────────────────────────────────────────────────────────────┐
│ Level 3: 附加资源 (Resources) │
│ • 通过 read_skill 工具加载特定文件 │
│ • 通过 execute_skill_script 执行脚本 │
└─────────────────────────────────────────────────────────────────┘
```
## Skill 目录结构
```
my-skill/
├── SKILL.md # 必需：主文件（含 YAML frontmatter）
├── REFERENCE.md # 可选：补充文档
├── templates/ # 可选：模板文件
└── scripts/ # 可选：可执行脚本
```
## 预加载技能
系统内置了以下 5 个预加载技能：
| 技能 | 用途 |
|------|------|
| citation-generator | 自动生成规范引用格式 |
| data-processor | 数据处理与分析 |
| doc-coauthoring | 引导用户完成结构化文档创作 |
| document-analyzer | 深度分析文档结构和内容 |
| summary-generator | 内容摘要生成 |
预加载技能位于 `skills/preloaded/` 目录下。
## 沙箱安全机制
### 脚本安全校验
执行前进行多层安全校验：危险命令检测、危险模式匹配、网络访问检测、反向 Shell 检测、参数注入检测等。
### Sandbox 模式
| 模式 | 说明 |
|------|------|
| `docker` | 使用 Docker 容器隔离（推荐） |
| `local` | 本地进程执行（基础安全限制） |
| `disabled` | 禁用脚本执行 |
通过环境变量 `WEKNORA_SANDBOX_MODE` 配置。
## 配置示例
```json
{
"skills_enabled": true,
"skill_dirs": ["/path/to/project/skills"],
"allowed_skills": ["pdf-processing", "code-review"]
}
```
## 相关主题
- [MCP功能使用说明](MCP功能使用说明.md) — 另一种 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 可通过 IM 渠道使用技能
- [开发指南](../开发部署/开发指南.md) — 沙箱镜像的构建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [MCP功能使用说明](MCP功能使用说明.md) — 与 Skills 并列的 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可使用技能
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的 Skills 社区扩展方向

66
docs/wiki/核心功能/MCP功能使用说明.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: MCP功能使用说明
tags: [核心功能, MCP, 工具集成]
aliases: [MCP使用, MCP功能]
source: MCP功能使用说明.md
---
# MCP 功能使用说明
## 功能概述
- MCP（Model Context Protocol）让 WeKnora 可以安全地连接外部工具或数据源，扩展 Agent 在推理时可调用的能力。
- 在前端 `设置 > MCP 服务`（`frontend/src/views/settings/McpSettings.vue`）中集中管理所有服务，无需手动改配置文件。
- 每个服务都包含名称、传输方式（SSE / HTTP Streamable / Stdio）、连接地址或命令、认证信息以及高级超时与重试策略。
> 关于系统级的内置 MCP 服务管理，参见 [内置MCP服务管理](内置MCP服务管理.md)
## 入口与界面
- 打开控制台左侧菜单 `设置 -> MCP 服务`，即可看到当前租户下的所有 MCP 服务列表。
- 列表中可快速启停服务、查看描述，并通过右侧菜单执行"测试 / 编辑 / 删除"。
- "添加服务"按钮会弹出 `McpServiceDialog`，用于创建或修改服务。
## 常用操作流程
### 1. 新建服务
- 点击"添加服务"，填写名称与描述，选择传输方式。
- SSE / HTTP Streamable 需提供可访问的服务 URL；Stdio 需配置 `uvx`/`npx` 命令与参数，可附加环境变量。
- 根据需要填写 API Key、Bearer Token、超时与重试策略，保存后服务会出现在列表中。
### 2. 启停服务
- 在列表开关中切换启用状态，系统会即时调用后端 `updateMCPService`，失败时会自动回滚状态并弹出提示。
### 3. 连接测试
- 通过更多菜单选择"测试"，前端会调用 `/api/v1/mcp-services/{id}/test` 并弹出 `McpTestResult`。
- 成功时会展示服务可用的工具清单（含输入 schema）和资源列表；失败时会显示错误信息，方便排查网络或鉴权问题。
### 4. 编辑 / 删除
- "编辑"会带出原有配置，修改后保存即可。
- "删除"需要在弹窗中确认，完成后列表自动刷新。
## 使用建议
- **传输方式选择**：优先使用 SSE 获取流式体验；需要标准 HTTP Streamable 兼容时再切换；本地调试或离线环境适合使用 Stdio 并在同机启动 MCP Server。
- **鉴权管理**：将 API Key / Token 保存在"认证配置"中，生产环境建议单独创建最小权限 Key，并定期轮换。
- **重试策略**：对公网或第三方服务适当提高 `retry_count` 与 `retry_delay`，避免间歇性超时导致 Agent 中断
## 相关主题
- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 系统管理员视角的内置 MCP 服务配置
- [Agent技能系统](Agent技能系统.md) — 另一种 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中 Agent 使用 MCP 工具
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 扩展搜索能力的另一种方式
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [内置MCP服务管理](内置MCP服务管理.md) — MCP 的系统级管理（管理员视角）
- [Agent技能系统](Agent技能系统.md) — 与 MCP 并列的 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可调用 MCP 工具

105
docs/wiki/核心功能/内置MCP服务管理.md Normal file
View File

@@ -0,0 +1,105 @@
---
title: 内置MCP服务管理
tags: [核心功能, MCP, 系统管理, 内置服务]
aliases: [内置MCP, BuiltinMCP, BUILTIN_MCP_SERVICES]
source: BUILTIN_MCP_SERVICES.md
---
# 内置 MCP 服务管理指南
## 概述
内置 MCP 服务是系统级别的 MCP（Model Context Protocol）服务配置，对所有租户可见，但敏感信息会被隐藏，且不可编辑或删除。内置 MCP 服务通常用于提供系统默认的外部工具和资源接入，确保所有租户都能使用统一的 MCP 服务。
> 用户视角的 MCP 服务操作参见 [MCP功能使用说明](MCP功能使用说明.md)
## 内置 MCP 服务特性
- **所有租户可见**：内置 MCP 服务对所有租户都可见，无需单独配置
- **安全保护**：内置 MCP 服务的敏感信息（URL、认证配置、Headers、环境变量）会被隐藏，无法查看详情
- **只读保护**：内置 MCP 服务不能被编辑或删除，仅支持测试连接
- **统一管理**：由系统管理员统一维护，确保配置一致性和安全性
## 与内置模型的对比
| 特性 | 内置模型 | 内置 MCP 服务 |
|------|---------|--------------|
| 标识字段 | `is_builtin` | `is_builtin` |
| 可见范围 | 所有租户 | 所有租户 |
| 隐藏信息 | API Key、Base URL | URL、认证配置、Headers、环境变量 |
| 编辑保护 | 不可编辑/删除 | 不可编辑/删除 |
| 前端标签 | 显示"内置"标签 | 显示"内置"标签 |
| 启停控制 | — | 禁用开关（始终启用） |
> 内置模型的详细管理参见 [内置模型管理](内置模型管理.md)
## 如何添加内置 MCP 服务
内置 MCP 服务需要通过数据库直接插入。
### 1. 准备服务数据
- 服务名称（name）
- 服务描述（description）
- 传输方式（transport_type）：`sse` 或 `http-streamable`
- 服务地址（url）
- 认证配置（auth_config）
- 高级配置（advanced_config）
- 租户ID（tenant_id）：建议使用小于 10000 的租户ID
**支持的传输方式**：
- `sse`：Server-Sent Events，推荐用于流式体验
- `http-streamable`：HTTP Streamable，标准 HTTP 兼容
> 注意：出于安全考虑，`stdio` 传输方式在服务端已被禁用。
### 2. 执行 SQL 插入语句
```sql
INSERT INTO mcp_services (
id, tenant_id, name, description, enabled,
transport_type, url, auth_config, advanced_config, is_builtin
) VALUES (
'builtin-mcp-001', 10000, 'Web Search', '内置 Web 搜索 MCP 服务',
true, 'sse', 'https://mcp.example.com/sse',
'{"api_key": "your-api-key"}'::jsonb,
'{"timeout": 30, "retry_count": 3, "retry_delay": 1}'::jsonb,
true
) ON CONFLICT (id) DO NOTHING;
```
### 3. 验证插入结果
```sql
SELECT id, name, transport_type, enabled, is_builtin
FROM mcp_services WHERE is_builtin = true ORDER BY created_at;
```
## 注意事项
1. **ID 命名规范**：建议使用 `builtin-mcp-{序号}` 格式
2. **租户ID**：建议使用第一个租户ID（通常是 10000）
3. **JSON 格式**：`auth_config`、`advanced_config`、`headers` 必须是有效的 JSON
4. **幂等性**：使用 `ON CONFLICT (id) DO NOTHING` 确保重复执行不会报错
5. **安全性**：内置 MCP 服务的 URL、认证信息在前端会被自动隐藏
6. **传输方式限制**：仅支持 `sse` 和 `http-streamable`
## 将现有 MCP 服务设置为内置服务
```sql
UPDATE mcp_services SET is_builtin = true WHERE id = '服务ID' AND name = '服务名称';
```
## 移除内置 MCP 服务
```sql
UPDATE mcp_services SET is_builtin = false WHERE id = '服务ID';
```
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [MCP功能使用说明](MCP功能使用说明.md) — 用户视角的 MCP 服务操作
- [内置模型管理](内置模型管理.md) — 同为内置系统配置，模式相似

83
docs/wiki/核心功能/内置模型管理.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: 内置模型管理
tags: [核心功能, 模型, 系统管理, 内置服务]
aliases: [内置模型, BuiltinModel, BUILTIN_MODELS]
source: BUILTIN_MODELS.md
---
# 内置模型管理指南
## 概述
内置模型是系统级别的模型配置，对所有租户可见，但敏感信息会被隐藏，且不可编辑或删除。内置模型通常用于提供系统默认的模型配置，确保所有租户都能使用统一的模型服务。
> 同为内置系统配置的还有 [内置MCP服务管理](内置MCP服务管理.md)
## 内置模型特性
- **所有租户可见**：无需单独配置
- **安全保护**：API Key、Base URL 被隐藏
- **只读保护**：不能被编辑或删除，只能设置为默认模型
- **统一管理**：由系统管理员统一维护
## 如何添加内置模型
### 1. 准备模型数据
- 模型名称（name）
- 模型类型（type）：`KnowledgeQA`、`Embedding`、`Rerank` 或 `VLLM`
- 模型来源（source）：`local` 或 `remote`
- 模型参数（parameters）：包括 base_url、api_key、provider 等
- 租户ID（tenant_id）：建议使用小于10000的租户ID
**支持的服务商（provider）**：`generic`、`openai`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`deepseek`、`minimax`、`mimo`、`siliconflow`、`jina`、`openrouter`、`gemini`、`modelscope`、`moonshot`、`qianfan`、`qiniu`、`longcat`、`gpustack`
### 2. 执行 SQL 插入语句
```sql
-- LLM 内置模型
INSERT INTO models (
id, tenant_id, name, type, source, description, parameters,
is_default, status, is_builtin
) VALUES (
'builtin-llm-001', 10000, 'GPT-4', 'KnowledgeQA', 'remote',
'内置 LLM 模型',
'{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai"}'::jsonb,
false, 'active', true
) ON CONFLICT (id) DO NOTHING;
-- Embedding 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
-- Rerank 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
```
### 3. 验证
```sql
SELECT id, name, type, is_builtin, status
FROM models WHERE is_builtin = true ORDER BY type, created_at;
```
## 注意事项
1. **ID 命名规范**：建议使用 `builtin-{type}-{序号}` 格式
2. **租户ID**：建议使用第一个租户ID（通常是 10000）
3. **参数格式**：`parameters` 字段必须是有效的 JSON 格式
4. **幂等性**：使用 `ON CONFLICT (id) DO NOTHING`
5. **安全性**：API Key 和 Base URL 在前端会被自动隐藏
## 模型配置与常见问题
- 如果 Embedding 模型未正确配置，会导致文档无法上传。排查步骤参见 [常见问题](../运维排障/常见问题.md)
- 模型参数中的 `provider` 决定了 API 调用格式和认证方式
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 同为内置系统配置，模式相似
- [常见问题](../运维排障/常见问题.md) — 模型配置相关的故障排查
- [版本路线图](../项目概述/版本路线图.md) — 路线图中模型训练方向

104
docs/wiki/核心功能/开启知识图谱功能.md Normal file
View File

@@ -0,0 +1,104 @@
---
title: 开启知识图谱功能
tags: [核心功能, 知识图谱, Neo4j, 配置]
aliases: [知识图谱配置, KnowledgeGraphSetup]
source: 开启知识图谱功能.md
---
# 开启知识图谱功能
本文档介绍如何在 WeKnora 中启用并验证知识图谱（Neo4j）功能，帮助你完成从环境准备到前端配置的全流程。
## 前置条件
- 已完成 WeKnora 后端与前端的基础部署
- 具备可用的 Docker/Docker Compose 运行环境
- 本地或远端可访问的 Neo4j 服务（推荐使用项目自带的 Docker Compose）
> 快速入门参见 [知识图谱](知识图谱.md)
## 步骤一：配置环境变量
在项目根目录的 `.env` 文件中新增或修改以下变量：
```
NEO4J_ENABLE=true
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_strong_password
# 可选：NEO4J_DATABASE=neo4j
```
说明：
- `NEO4J_ENABLE` 设置为 `true` 才会启用知识图谱相关逻辑
- `NEO4J_URI` 中的 `neo4j` 为 docker-compose 服务名，如使用外部实例请替换为实际地址
- 如果生产环境使用密钥管理，请确保密码通过安全方式注入
## 步骤二：启动 Neo4j 服务
项目附带 Neo4j 组件，可直接用以下命令启动：
```bash
docker-compose --profile neo4j up -d
```
常见验证命令：
```bash
docker ps | grep neo4j
```
> 开发环境中 Neo4j 的启动方式参见 [开发指南](../开发部署/开发指南.md)
## 步骤三：重启 WeKnora 服务
为了让新的环境变量生效，重启后端与前端：
```bash
make stop && make start
# 或者
docker compose up -d --build
```
确保后端日志中出现 `neo4j` 初始化成功的提示。
## 步骤四：在前端启用实体/关系抽取
1. 登录 WeKnora 前端管理页面
2. 打开「知识库设置」或创建新的知识库
3. 勾选「启用实体抽取」与「启用关系抽取」开关
4. 根据界面提示补充所需的 LLM、回调或模型参数（若有）
保存后，系统会在文档入库阶段自动触发实体与关系抽取任务。
## 步骤五：验证知识图谱
### 方式一：Neo4j 控制台
1. 访问 `http://localhost:7474`（或对应主机/端口）
2. 使用 `.env` 中的账号密码登录
3. 执行 `MATCH (n) RETURN n LIMIT 50;` 检查是否有新节点/关系
### 方式二：WeKnora 界面
在知识库或对话页面中上传文档后，前端应展示图谱可视化入口；对话时系统会自动根据意图查询图谱并返回补充信息。
## 常见问题排查
- **无法连接 Neo4j**：确认网络可达、`NEO4J_URI` 与用户名密码正确，并检查 Neo4j 容器日志
- **未生成节点**：确认知识库已开启实体/关系抽取，且上传的文档已完成解析；查看后端日志中是否有抽取任务异常
- **查询无结果**：尝试在 Neo4j 控制台执行 `CALL db.schema.visualization;` 查看 schema 是否存在，必要时重新导入文档
> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
完成以上步骤后，知识图谱功能即成功启用，可结合 RAG 及 Agent 流程提升问答质量。
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [知识图谱](知识图谱.md) — 知识图谱快速入门（本页的精简版）
- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的启动与配置
- [常见问题](../运维排障/常见问题.md) — 图谱功能相关的故障排查

50
docs/wiki/核心功能/知识图谱.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: 知识图谱
tags: [核心功能, 知识图谱, Neo4j]
aliases: [KnowledgeGraph, 图谱]
source: KnowledgeGraph.md
---
# 知识图谱
## 快速开始
- .env 配置相关环境变量
- 启用 Neo4j: `NEO4J_ENABLE=true`
- Neo4j URI: `NEO4J_URI=bolt://neo4j:7687`
- Neo4j 用户名: `NEO4J_USERNAME=neo4j`
- Neo4j 密码: `NEO4J_PASSWORD=password`
- 启动 Neo4j
```bash
docker-compose --profile neo4j up -d
```
- 在知识库设置页面启用实体和关系提取，并根据提示配置相关内容
> 详细的启用步骤参见 [开启知识图谱功能](开启知识图谱功能.md)
## 生成图谱
上传任意文档后，系统会自动提取实体和关系，并生成对应的知识图谱。
![知识图片示例](../../images/graph3.png)
## 查看图谱
登陆 `http://localhost:7474`，执行 `match (n) return (n)` 即可查看生成的知识图谱。
在对话时，系统会自动查询知识图谱，并获取相关知识。
## 相关主题
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能的完整启用指南
- [常见问题](../运维排障/常见问题.md) — 知识图谱相关的故障排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开启知识图谱功能](开启知识图谱功能.md) — 本页的详细版本，包含完整的启用流程
- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的配置与启动

106
docs/wiki/运维排障/常见问题.md Normal file
View File

@@ -0,0 +1,106 @@
---
title: 常见问题
tags: [运维排障, FAQ, 故障排查, 部署]
aliases: [FAQ, 故障排查, QA]
source: QA.md
---
# 常见问题
## 1. 如何查看日志？
```bash
docker compose logs -f app docreader postgres
```
## 2. 如何启动和停止服务？
```bash
./scripts/start_all.sh # 启动服务
./scripts/start_all.sh --stop # 停止服务
./scripts/start_all.sh --stop && make clean-db # 清空数据库
```
> 开发模式下的启停参见 [开发指南](../开发部署/开发指南.md)
## 3. 服务启动后无法正常上传文档？
通常是 Embedding 模型和对话模型没有正确被设置导致。
### 排查步骤
1. 查看 `.env` 配置中的模型信息是否配置完整：
```bash
INIT_LLM_MODEL_NAME=your_llm_model
INIT_EMBEDDING_MODEL_NAME=your_embedding_model
INIT_EMBEDDING_MODEL_DIMENSION=your_embedding_model_dimension
INIT_EMBEDDING_MODEL_ID=your_embedding_model_id
```
2. 如果使用 remote API，还需提供 `BASE_URL` 和 `API_KEY`
3. 如需重排序功能，额外配置 Rerank 模型
4. 查看主服务日志，是否有 `ERROR` 日志输出
> 模型管理参见 [内置模型管理](../核心功能/内置模型管理.md)
## 4. 没有图片或者显示无效的图片链接？
1. 确认多模态功能已正确配置（知识库设置 → 高级设置 → 多模态功能）
2. 确认 MinIO 服务已启动
3. 检查 MinIO Bucket 权限
4. 配置 `MINIO_PUBLIC_ENDPOINT`（如需从其他设备访问）
**重要**：Bucket 名称不要包含特殊字符；如无法修改权限，可填入不存在的 bucket 名称，系统会自动创建。
## 5. 平台兼容性说明
`OCR_BACKEND=paddle` 在部分平台上可能无法正常运行。
- **方案一**：关闭 OCR 识别（删除 `OCR_BACKEND` 配置）
- **方案二**：使用外部 OCR 模型（推荐）— 配置 `OCR_BACKEND=vlm`
## 6. 如何使用数据分析功能？
- **智能推理**：需在工具配置中勾选「查看数据元信息」和「数据分析」
- **快速问答智能体**：无需手动选择工具
### 注意事项
- 仅支持 CSV 和 Excel 格式
- 仅支持只读查询（SELECT、SHOW 等）
## 7. 页面里刚保存的配置几秒后又消失了？
通常是浏览器代理、缓存或插件干扰导致。建议：
1. 关闭浏览器代理和抓包工具
2. 强制刷新或使用无痕窗口
3. 检查 Network 面板确认请求未被代理改写
## 8. SSRF 校验白名单
`SSRF_WHITELIST` 配置项用于绕过常规 SSRF 限制，支持：精确域名、通配域名、IPv4/IPv6、CIDR。
```bash
# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12
```
> 生产环境请谨慎配置。搜索引擎的 API 端点硬编码策略参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)
## 相关主题
- [开发指南](../开发部署/开发指南.md) — 开发环境问题排查
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能故障排查
- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置问题
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 集成相关问题
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开发指南](../开发部署/开发指南.md) — 开发环境搭建与问题排查
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能相关故障排查
- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置相关问题
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式相关问题
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — SSRF 白名单与搜索 API 安全策略

115
docs/wiki/集成扩展/IM集成开发.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: IM集成开发
tags: [集成扩展, IM, 企微, 飞书, Slack, Telegram, 钉钉, Mattermost]
aliases: [IM集成, IM开发, 企业微信, 即时通讯]
source: IM集成开发文档.md
---
# IM 集成开发
WeKnora 的 IM 集成模块将企业即时通讯平台（企业微信、飞书、Slack、Telegram、钉钉、Mattermost）接入 WeKnora 知识问答管道，支持在 IM 中直接向 AI 提问并获得实时流式回答。
IM 渠道绑定到 Agent，一个 Agent 可接入多个 IM 渠道。
> IM 渠道中的 Agent 可以使用 [MCP 工具](../核心功能/MCP功能使用说明.md) 和 [Skills 技能](../核心功能/Agent技能系统.md)
## 支持的平台
| 平台 | WebSocket 模式 | Webhook 模式 | 流式输出 |
|------|:-:|:-:|:-:|
| 企业微信 | ✅ | ✅ | ✅ |
| 飞书 | ✅ | ✅ | ✅ (CardKit) |
| Slack | ✅ (Socket Mode) | ✅ (Events API) | ✅ |
| Telegram | ✅ (长轮询) | ✅ | ✅ |
| 钉钉 | ✅ (Stream) | ✅ | ✅ (AI 卡片) |
| Mattermost | — | ✅ | ✅ |
## 快速接入指南
### 前置条件
- WeKnora 已部署并运行
- 已创建至少一个 Agent（自定义智能体）
- Agent 已配置好模型和知识库
> Agent 配置模型参见 [内置模型管理](../核心功能/内置模型管理.md)
### 企业微信接入
提供两种模式：
- **WebSocket 模式**（智能机器人，推荐）— 无需公网域名
- **Webhook 模式**（自建应用）— 需要公网回调地址
### 飞书接入
- **WebSocket 模式**（推荐）— 无需公网域名
- **Webhook 模式** — 需要公网回调地址
> 飞书同时也是数据源导入的支持平台，参见 [数据源导入开发](数据源导入开发.md)
### Slack 接入
- **Socket Mode**（推荐）— 无需公网域名
- **Events API** — 需要公网回调地址
### Telegram 接入
- **长轮询模式**（推荐）— 无需公网域名
- **Webhook 模式** — 需要 HTTPS 公网回调
### 钉钉接入
- **Stream 模式**（推荐）— 无需公网域名
- **Webhook 模式** — 需要公网回调地址
### Mattermost 接入
- 仅支持 **Webhook 模式**（出站 Webhook + REST API v4）
## 架构设计
系统采用 **Adapter Pattern**，每个平台实现 `im.Adapter` 接口，通过 `AdapterFactory` 动态创建。核心设计模式包括：
| 模式 | 用途 |
|------|------|
| Adapter Pattern | 统一不同 IM 平台的差异 |
| Factory Pattern | 从数据库渠道配置动态创建 Adapter |
| Command Pattern | 可插拔的斜杠指令系统 |
| Producer-Consumer | QA 队列 + Worker Pool |
## 斜杠指令系统
| 指令 | 说明 |
|------|------|
| `/help` | 显示所有可用指令 |
| `/info` | 查看当前绑定智能体信息 |
| `/search` | 对知识库执行混合检索 |
| `/stop` | 取消当前 QA 请求 |
| `/clear` | 清空当前对话记忆 |
## 扩展新平台
接入新的 IM 平台只需 3 步：
1. 实现 `im.Adapter` 接口（可选 `StreamSender`、`FileDownloader`）
2. 注册适配器工厂
3. 前端添加平台选项
> 扩展开发模式与 [添加网络搜索引擎](添加网络搜索引擎.md) 和 [集成向量数据库](集成向量数据库.md) 类似
## 相关主题
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 飞书数据源同步（共享飞书应用凭证）
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — Agent 可调用 MCP 工具
- [Agent技能系统](../核心功能/Agent技能系统.md) — Agent 可使用 Skills 技能
- [开发指南](../开发部署/开发指南.md) — 开发环境搭建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 同样涉及飞书集成，可共享应用凭证
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — IM 中 Agent 可调用 MCP 工具
- [Agent技能系统](../核心功能/Agent技能系统.md) — IM 中 Agent 可使用 Skills
- [版本路线图](../项目概述/版本路线图.md) — IM 集成已完成的里程碑

87
docs/wiki/集成扩展/数据源导入开发.md Normal file
View File

@@ -0,0 +1,87 @@
---
title: 数据源导入开发
tags: [集成扩展, 数据源, 飞书, 同步, 连接器]
aliases: [数据源导入, DataSource, 数据同步]
source: 数据源导入开发文档.md
---
# 数据源导入开发
WeKnora 的数据源导入模块支持从外部平台（飞书、企业微信、Notion、Confluence 等）自动导入和同步内容到知识库。用户可配置数据源连接，选择需要同步的资源，并通过手动触发或定时调度自动完成内容的增量/全量同步。
数据源绑定到知识库，一个知识库可接入多个数据源。凭证使用 AES-256-GCM 加密存储。
> 数据源导入与 [IM集成开发](../集成扩展/IM集成开发.md) 都涉及飞书集成，可考虑共享飞书应用凭证
## 当前支持的连接器
| 连接器 | 认证方式 | 增量同步 | 删除同步 |
|--------|---------|:-:|:-:|
| 飞书 (Feishu) | OAuth2 (Tenant Access Token) | ✅ | ✅ |
## 快速接入：飞书知识库
1. 创建飞书应用，获取 App ID / App Secret
2. 开通权限：`wiki:wiki:readonly`、`drive:drive:readonly`、`drive:export:readonly`、`docx:document:readonly`
3. 在知识库设置页添加数据源，选择飞书，填写凭证
4. 测试连接，选择知识库空间，配置同步策略
5. 触发首次同步验证
> 注意：飞书国际版（Lark）同样支持，自动适配 `https://open.larksuite.com` 的 API 地址
## 架构设计
```
外部平台 API → Connector → ConnectorRegistry → DataSourceService → WeKnora Core (知识入库管道)
```
核心设计模式：
| 模式 | 用途 |
|------|------|
| Adapter Pattern | 统一不同平台的差异 |
| Registry Pattern | 按类型动态查找连接器 |
| Strategy Pattern | SyncMode（增量/全量）、ConflictStrategy（覆盖/跳过） |
| Cursor-based Pagination | 增量同步基于 SyncCursor 跟踪变更 |
## 关键概念
- **DataSource** — 数据源：外部平台连接与知识库的绑定
- **Connector** — 连接器：与外部平台交互的适配层
- **SyncCursor** — 同步游标：增量同步的状态标记
- **FetchedItem** — 拉取到的文档条目
## API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/datasource/types` | 获取可用连接器类型 |
| POST | `/api/v1/datasource/validate-credentials` | 验证凭证 |
| POST | `/api/v1/datasource` | 创建数据源 |
| GET | `/api/v1/datasource?kb_id=xxx` | 列出数据源 |
| POST | `/api/v1/datasource/:id/sync` | 手动触发同步 |
| POST | `/api/v1/datasource/:id/pause` | 暂停 |
| POST | `/api/v1/datasource/:id/resume` | 恢复 |
## 扩展新连接器
1. 实现 `Connector` 接口（Validate、ListResources、FetchAll、FetchIncremental）
2. 注册连接器到 `ConnectorRegistry`
3. 前端添加配置
> 扩展开发模式与 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) 和 [集成向量数据库](../集成扩展/集成向量数据库.md) 类似
## 相关主题
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中的飞书集成
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享机制
- [常见问题](../运维排障/常见问题.md) — 数据源同步相关故障排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [IM集成开发](../集成扩展/IM集成开发.md) — 同样涉及飞书集成，可共享应用凭证
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享与数据源导入互补
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式

102
docs/wiki/集成扩展/添加网络搜索引擎.md Normal file
View File

@@ -0,0 +1,102 @@
---
title: 添加网络搜索引擎
tags: [集成扩展, 搜索, 网络搜索, Provider]
aliases: [网络搜索, WebSearch, 搜索引擎扩展]
source: 添加新的网络搜索引擎.md
---
# 添加新的网络搜索引擎
本文档说明如何在 WeKnora 中添加一个新的网络搜索引擎类型（如 Brave Search、Searx 等）。
## 架构概述
搜索引擎的 API 端点**硬编码**在代码中，不向用户暴露 BaseURL，从源头消除 SSRF 风险。
```
internal/types/web_search_provider.go # 实体定义 + Provider 类型元数据
internal/infrastructure/web_search/ # Provider 实现（bing/google/duckduckgo/tavily）
internal/container/container.go # DI 注册
internal/types/interfaces/web_search.go # WebSearchProvider 接口
```
> 类似的扩展开发模式参见 [集成向量数据库](../集成扩展/集成向量数据库.md)
## 步骤
以添加 **Brave Search** 为例：
### 1. 注册类型常量
在 `internal/types/web_search_provider.go` 中添加：
```go
WebSearchProviderTypeBrave WebSearchProviderType = "brave"
```
### 2. 添加类型元数据
在 `GetWebSearchProviderTypes()` 中添加：
```go
{
ID: "brave", Name: "Brave Search", Free: false,
RequiresAPIKey: true, Description: "Brave Search API",
DocsURL: "https://brave.com/search/api/",
}
```
### 3. 创建 Provider 实现
新建 `internal/infrastructure/web_search/brave.go`：
- 构造函数签名：`func(types.WebSearchProviderParameters) (interfaces.WebSearchProvider, error)`
- API 端点**硬编码**为常量
- 实现 `interfaces.WebSearchProvider` 接口：`Name()` 和 `Search()`
### 4. 添加参数校验
在 `isValidProviderType()` 中添加新类型。
### 5. DI 注册
在 `registerWebSearchProviders` 中注册。
### 6. 验证
```bash
go build ./...
# 调用 API 验证
curl http://localhost:8080/api/v1/web-search-providers/types
```
## 需要额外参数的情况
如果新引擎需要 API Key 以外的参数：
- **方式一**：使用 `WebSearchProviderParameters.ExtraConfig` 字段
- **方式二**：在 `WebSearchProviderParameters` 中添加专用字段
## 文件变更清单
| 文件 | 操作 |
|------|------|
| `internal/types/web_search_provider.go` | 添加常量 + 类型元数据 |
| `internal/infrastructure/web_search/brave.go` | **新建** Provider 实现 |
| `internal/application/service/web_search_provider.go` | `isValidProviderType` 加新类型 |
| `internal/container/container.go` | `registerWebSearchProviders` 注册 |
## 相关主题
- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式（接口实现 + 注册 + DI）
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 也可集成搜索工具
- [常见问题](../运维排障/常见问题.md) — SSRF 白名单配置
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 搜索工具与网络搜索引擎互补
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的社区组件扩展方向

77
docs/wiki/集成扩展/集成向量数据库.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: 集成向量数据库
tags: [集成扩展, 向量数据库, 检索引擎, 扩展]
aliases: [向量数据库, VecDB, 向量检索, RetrieveEngine]
source: 使用其他向量数据库.md
---
# 集成新的向量数据库
本文提供了向 WeKnora 项目添加新向量数据库支持的完整指南。通过实现标准化接口和遵循结构化流程，开发者可以高效地集成自定义向量数据库。
> 类似的扩展开发模式参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)
## 集成流程
### 1. 实现基础检索引擎接口
```go
type RetrieveEngine interface {
EngineType() types.RetrieverEngineType
Retrieve(ctx context.Context, params types.RetrieveParams) ([]*types.RetrieveResult, error)
Support() []types.RetrieverType
}
```
### 2. 实现存储层接口
实现 `RetrieveEngineRepository` 接口，扩展基础检索引擎能力，添加索引管理功能：
- `Save` / `BatchSave` — 保存索引
- `EstimateStorageSize` — 估算存储空间
- `DeleteByChunkIDList` / `DeleteByKnowledgeIDList` — 删除索引
- `CopyIndices` — 复制索引
### 3. 实现服务层接口
创建 `RetrieveEngineService` 实现，负责索引创建和管理的业务逻辑。
### 4. 添加环境变量配置
```
RETRIEVE_DRIVER=postgres,elasticsearch_v8,your_database
YOUR_DATABASE_ADDR=host:port
YOUR_DATABASE_USERNAME=username
YOUR_DATABASE_PASSWORD=password
```
### 5. 注册检索引擎
在 `internal/container/container.go` 的 `initRetrieveEngineRegistry` 中添加初始化与注册逻辑。
### 6. 定义检索引擎类型常量
在 `internal/types/retriever.go` 中添加新的引擎类型常量。
## 参考实现
建议参考现有实现：
- PostgreSQL: `internal/application/repository/retriever/postgres/`
- ElasticsearchV7: `internal/application/repository/retriever/elasticsearch/v7/`
- ElasticsearchV8: `internal/application/repository/retriever/elasticsearch/v8/`
## 相关主题
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式（接口实现 + 注册 + DI）
- [知识图谱](../核心功能/知识图谱.md) — 知识图谱功能依赖 Neo4j 而非向量数据库
- [常见问题](../运维排障/常见问题.md) — Embedding 模型配置与向量维度相关
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式
- [知识图谱](../核心功能/知识图谱.md) — 另一种知识检索方式（基于图而非向量）
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的检索能力扩展方向

37
docs/wiki/项目概述/Lite与标准版区别.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Lite与标准版区别
tags: [项目概述, 部署, Lite]
aliases: [Lite, LITE, 标准版区别]
source: LITE.md
---
# Lite 与标准版区别
Lite 面向希望快速在本地使用、部署尽量简单的场景；标准版面向多租户协作与完整企业能力。主要差异如下。
| 维度 | Lite | 标准版 |
|------|------|--------|
| **共享空间** | 不提供共享空间（成员邀请、跨成员共享知识库与智能体等） | 提供共享空间及租户隔离检索等协作能力 |
| **租户与账号** | 单租户；开箱即用，**无需注册** | 多租户；通常需要注册、登录与组织管理 |
| **文档解析** | 内置仅 **Simple** 类型解析引擎；可通过 **Cloud** 等方式接入其他解析能力 | 可配置多种解析引擎（含高精度等），与完整文档处理链路集成 |
| **部署形态** | **单应用、零依赖**（不依赖独立的数据库、消息队列等外部服务栈） | 典型为 Docker Compose 等多服务部署，依赖与组件更多 |
| **数据归属** | 数据**完全在本地**存储与处理 | 私有化部署时数据也可在本地；具体取决于你的部署方式 |
| **网络暴露** | **默认仅本机访问**；可按需配置，**选择是否放行到公网** | 按部署与安全策略自行绑定地址与网关 |
> 若你不需要多团队协作、复杂解析流水线与多服务架构，Lite 更适合个人或小团队在本机零依赖试用；需要共享空间、多租户与完整解析引擎矩阵时，请使用标准版。
## 相关主题
- 共享空间的详细说明参见 [共享空间说明](../安全认证/共享空间说明.md) — 标准版独有功能
- 认证体系参见 [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 标准版多租户 OIDC 登录
- 开发环境搭建参见 [开发指南](../开发部署/开发指南.md)
- 部署相关 FAQ 参见 [常见问题](../运维排障/常见问题.md)
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [版本路线图](版本路线图.md) — 路线图中的轻量化部署方向
- [共享空间说明](../安全认证/共享空间说明.md) — Lite 不支持的共享空间功能的详细说明
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 标准版多租户场景下的认证方式

83
docs/wiki/项目概述/版本路线图.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: 版本路线图
tags: [项目概述, 路线图, 规划]
aliases: [ROADMAP, Roadmap]
source: ROADMAP.md
---
# 版本路线图
本文档描述 WeKnora 的产品规划与计划方向，会随项目进展持续更新。
## 轻量化部署
- [ ] WeKnora 官方提供原子化调用接口（Embedding、ReRank、LLM、文档解析等），并提供一定免费使用额度
- [ ] WeKnora 官方提供完整云端服务，用户可在平台上直接体验 WeKnora 能力
- [ ] 推出 WeKnora Lite 版本，供私有化部署需求不强的用户快速体验产品能力
> 关于 Lite 版本的详细差异，参见 [Lite与标准版区别](Lite与标准版区别.md)
## 知识理解
- [x] 抽象整体文档解析模块，支持切换内置解析、MinerU 或其它解析方式
- [ ] 优化文档分块策略，除规则分块外支持语义分块、章节分块等
- [ ] 文档结构可视化：展示解析后的文档章节结构、图谱关系等
- [ ] 支持音视频等更多文档格式，增强多模态理解能力
> 知识图谱相关功能参见 [知识图谱](../核心功能/知识图谱.md) 与 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
## 检索与总结
- [ ] 支持在输入框中通过「@标签」指定检索范围
- [ ] 支持在输入框中上传图片、附件进行检索
- [x] 支持对话框中上传图片
- [ ] 支持对话框中上传附件
> 检索引擎扩展参见 [集成向量数据库](../集成扩展/集成向量数据库.md)
## 知识库相关模型训练
- [ ] 训练与检索召回相关的模型（Embedding、ReRank、LLM 等）
- [ ] 在文档解析与文档理解方面持续探索，推进自研相关模型
> 模型管理参见 [内置模型管理](../核心功能/内置模型管理.md)
## 知识库形态
- [ ] 扩展知识库形态，支持时序数据的存储与索引
- [ ] 探索知识库与 Memory 结合的应用场景
## IM 集成
- [x] 支持与企微、飞书等 IM 系统集成，在 IM 内使用 WeKnora 能力
> IM 集成开发详见 [IM集成开发](../集成扩展/IM集成开发.md)
## 组件与扩展
- [ ] 鼓励社区维护各厂商的模型服务、网络搜索服务等组件
- [ ] 鼓励社区提供更多与知识库相关的 Skills
> 扩展开发参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)、[集成向量数据库](../集成扩展/集成向量数据库.md)、[Agent技能系统](../核心功能/Agent技能系统.md)
## 周边生态建设
- [ ] 提供 Chrome 扩展，支持类似「剪藏」功能
- [ ] 提供小程序插件（具体形态待定）
- [ ] 提供 JS SDK，便于在网页中集成 WeKnora 能力
- [ ] 鼓励社区提供 VSCode、Cursor、Claude Code 等编辑器/IDE 插件
## 文档建设
- [ ] 完善官方文档（使用说明、API、部署等）
- [ ] 鼓励用户贡献文档、博客、视频等，形成社区化文档体系
- [ ] 在知乎平台建设 WeKnora 内容合集
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [Lite与标准版区别](Lite与标准版区别.md) — Lite 版本定位与路线图中的轻量化部署方向对应
- [内置模型管理](../核心功能/内置模型管理.md) — 路线图中模型训练方向关联内置模型管理
- [IM集成开发](../集成扩展/IM集成开发.md) — 路线图中 IM 集成已完成的里程碑