diff --git a/docs/wiki/API参考/API文档概览.md b/docs/wiki/API参考/API文档概览.md new file mode 100644 index 00000000..fceea447 --- /dev/null +++ b/docs/wiki/API参考/API文档概览.md @@ -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 的使用场景 diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 00000000..d20b800a --- /dev/null +++ b/docs/wiki/Home.md @@ -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 首页，所有页面均链接回此处。 diff --git a/docs/wiki/安全认证/OIDC认证调用流程.md b/docs/wiki/安全认证/OIDC认证调用流程.md new file mode 100644 index 00000000..4d85cdd5 --- /dev/null +++ b/docs/wiki/安全认证/OIDC认证调用流程.md @@ -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 相关 diff --git a/docs/wiki/安全认证/共享空间说明.md b/docs/wiki/安全认证/共享空间说明.md new file mode 100644 index 00000000..d56f7c09 --- /dev/null +++ b/docs/wiki/安全认证/共享空间说明.md @@ -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) — 智能体共享前的模型配置要求 diff --git a/docs/wiki/开发部署/开发指南.md b/docs/wiki/开发部署/开发指南.md new file mode 100644 index 00000000..af0143fb --- /dev/null +++ b/docs/wiki/开发部署/开发指南.md @@ -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) — 开发相关故障排查 diff --git a/docs/wiki/开发部署/快速开发模式.md b/docs/wiki/开发部署/快速开发模式.md new file mode 100644 index 00000000..289c9673 --- /dev/null +++ b/docs/wiki/开发部署/快速开发模式.md @@ -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) — 开发模式相关故障排查 diff --git a/docs/wiki/核心功能/Agent技能系统.md b/docs/wiki/核心功能/Agent技能系统.md new file mode 100644 index 00000000..6565d1e8 --- /dev/null +++ b/docs/wiki/核心功能/Agent技能系统.md @@ -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 社区扩展方向 diff --git a/docs/wiki/核心功能/MCP功能使用说明.md b/docs/wiki/核心功能/MCP功能使用说明.md new file mode 100644 index 00000000..3d688d54 --- /dev/null +++ b/docs/wiki/核心功能/MCP功能使用说明.md @@ -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 工具 diff --git a/docs/wiki/核心功能/内置MCP服务管理.md b/docs/wiki/核心功能/内置MCP服务管理.md new file mode 100644 index 00000000..2f9ad5f2 --- /dev/null +++ b/docs/wiki/核心功能/内置MCP服务管理.md @@ -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) — 同为内置系统配置，模式相似 diff --git a/docs/wiki/核心功能/内置模型管理.md b/docs/wiki/核心功能/内置模型管理.md new file mode 100644 index 00000000..ab85b672 --- /dev/null +++ b/docs/wiki/核心功能/内置模型管理.md @@ -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) — 路线图中模型训练方向 diff --git a/docs/wiki/核心功能/开启知识图谱功能.md b/docs/wiki/核心功能/开启知识图谱功能.md new file mode 100644 index 00000000..9616fbcf --- /dev/null +++ b/docs/wiki/核心功能/开启知识图谱功能.md @@ -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) — 图谱功能相关的故障排查 diff --git a/docs/wiki/核心功能/知识图谱.md b/docs/wiki/核心功能/知识图谱.md new file mode 100644 index 00000000..299a7a38 --- /dev/null +++ b/docs/wiki/核心功能/知识图谱.md @@ -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 的配置与启动 diff --git a/docs/wiki/运维排障/常见问题.md b/docs/wiki/运维排障/常见问题.md new file mode 100644 index 00000000..93958023 --- /dev/null +++ b/docs/wiki/运维排障/常见问题.md @@ -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 安全策略 diff --git a/docs/wiki/集成扩展/IM集成开发.md b/docs/wiki/集成扩展/IM集成开发.md new file mode 100644 index 00000000..3c93fe7b --- /dev/null +++ b/docs/wiki/集成扩展/IM集成开发.md @@ -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 集成已完成的里程碑 diff --git a/docs/wiki/集成扩展/数据源导入开发.md b/docs/wiki/集成扩展/数据源导入开发.md new file mode 100644 index 00000000..171faedf --- /dev/null +++ b/docs/wiki/集成扩展/数据源导入开发.md @@ -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) — 同类扩展开发模式 diff --git a/docs/wiki/集成扩展/添加网络搜索引擎.md b/docs/wiki/集成扩展/添加网络搜索引擎.md new file mode 100644 index 00000000..50f3b0d7 --- /dev/null +++ b/docs/wiki/集成扩展/添加网络搜索引擎.md @@ -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) — 路线图中的社区组件扩展方向 diff --git a/docs/wiki/集成扩展/集成向量数据库.md b/docs/wiki/集成扩展/集成向量数据库.md new file mode 100644 index 00000000..9f8b3fab --- /dev/null +++ b/docs/wiki/集成扩展/集成向量数据库.md @@ -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) — 路线图中的检索能力扩展方向 diff --git a/docs/wiki/项目概述/Lite与标准版区别.md b/docs/wiki/项目概述/Lite与标准版区别.md new file mode 100644 index 00000000..b68b79c0 --- /dev/null +++ b/docs/wiki/项目概述/Lite与标准版区别.md @@ -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) — 标准版多租户场景下的认证方式 diff --git a/docs/wiki/项目概述/版本路线图.md b/docs/wiki/项目概述/版本路线图.md new file mode 100644 index 00000000..9d542eff --- /dev/null +++ b/docs/wiki/项目概述/版本路线图.md @@ -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 集成已完成的里程碑