WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

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 分类
+
+| 分类 | 描述 | 详细文档 |
+|------|------|----------|
+| 认证管理 | 用户注册、登录、令牌管理；OIDC 流程 | [auth.md](../../api/auth.md) · [OIDC认证调用流程.md](../安全认证/OIDC认证调用流程.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 的使用场景

docs/wiki/Home.md

@@ -0,0 +1,127 @@
+---
+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 第三方登录的完整调用链路 |
+| [空间RBAC说明](安全认证/RBAC说明.md) | 空间内角色矩阵、资源归属与审计 |
+| [共享空间说明](安全认证/共享空间说明.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认证调用流程]
+    安全认证 --> RBAC[空间RBAC说明]
+    安全认证 --> SharedSpace[共享空间说明]
+
+    开发部署 --> DevGuide[开发指南]
+    开发部署 --> QuickDev[快速开发模式]
+
+    运维排障 --> FAQ[常见问题]
+
+    API参考 --> APIOverview[API文档概览]
+
+    KG -.-> KGSetup
+    MCP -.-> BuiltinMCP
+    BuiltinMCP -.-> BuiltinModel
+    Skills -.-> IM
+    IM -.-> DS
+    DS -.-> SharedSpace
+    OIDC -.-> RBAC
+    RBAC -.-> SharedSpace
+    OIDC -.-> SharedSpace
+    LITE -.-> SharedSpace
+    WebSearch -.-> VecDB
+    DevGuide -.-> QuickDev
+    FAQ -.-> DevGuide
+```
+
+---
+
+## 反向链接
+
+本页为 wiki 首页，所有页面均链接回此处。

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 相关

docs/wiki/安全认证/RBAC说明.md

@@ -0,0 +1,114 @@
+---
+title: 空间RBAC说明
+tags: [安全认证, RBAC, 权限, 多空间, 角色]
+aliases: [RBAC, 角色权限, 空间角色, TenantRBAC]
+source: RBAC说明.md
+---
+
+# 空间 RBAC 说明
+
+本文档介绍 WeKnora 的**空间内权限控制（Workspace RBAC）**，包括角色矩阵、资源归属模型，以及它与 [共享空间](./共享空间说明.md) 的关系。
+
+> 状态：已发布；由配置项 `tenant.enable_rbac` 控制，默认 `true`（强制鉴权）。
+> 完整说明、灰度方案、Schema、路由守卫等参见 [`docs/RBAC说明.md`](../../RBAC说明.md)。
+
+## 解决的问题
+
+RBAC 引入前，只要通过 `X-API-Key` 或 JWT 认证成功，调用方在空间内基本等同管理员。一旦一个空间出现多名真人成员，就需要区分：
+
+- 谁可以删除知识库、撤销 API Key；
+- 谁可以编辑「自己」的 KB / Agent；
+- 谁只读。
+
+## 角色矩阵
+
+| 角色 | 标识 | 关键能力 |
+|------|------|----------|
+| 只读 | `viewer` | 仅读 |
+| 贡献者 | `contributor` | 可变更 `creator_id == 自己` 的资源；他人资源按 Viewer |
+| 管理员 | `admin` | 可变更空间内任意资源；管理成员、共享基础设施 |
+| Owner | `owner` | Admin + 可删空间；每个空间至少一位，可以有多位 |
+
+层级 `viewer < contributor < admin < owner`，高角色继承低角色。
+
+Owner 的数量约束是“至少一位”，而不是“只能一位”。系统允许同一空间存在多个活跃 Owner；降级或移除 Owner 时，只有会导致空间失去最后一位 Owner 的操作才会被拒绝。
+
+### 鉴权层的例外
+
+- **跨空间超管**：`enable_cross_tenant_access` 打开且账号 `CanAccessAllTenants=true`，通过 `X-Tenant-ID` 切换后等同 Admin。
+- **API Key**：合成虚拟用户在所属空间内固定 Admin（删空间除外）。
+- **孤儿空间自愈**：首位认证的真人自动晋升 Owner，避免 API Key-only 空间锁死。
+
+## 资源归属
+
+迁移 `000043` 在关键表加上 `creator_id`：
+
+- `knowledge_bases.creator_id` —— 老数据回填为该空间的 Owner；
+- `custom_agents.creator_id` + `runnable_by_viewer`（默认 `true`，允许 Viewer 在对话中调用）。
+
+子资源沿 `chunk → knowledge → kb → creator_id` 链回溯。
+
+由此得到两类守卫：
+
+- **角色守卫**：只看角色，用于空间级基础设施（模型、向量库、IM 通道等）。
+- **归属守卫**`OwnedXxxOrAdmin`：creator 或 Admin+ 二者其一即放行，用于具体资源写操作。
+
+## 与共享空间的关系
+
+| 维度 | 解决什么 | 主键 |
+|------|---------|------|
+| **空间 RBAC** | 同一空间内「你能对自己/别人/共享基础设施做什么」 | `tenant_members(user_id, tenant_id, role)` |
+| **共享空间** | 跨空间「让别的空间的人也能用我的 KB / Agent」 | `organization_members` + 共享关系 |
+
+两者**正交**：
+
+- 共享空间不持有 KB / Agent，只记录「以何种权限共享到了哪个空间」；资源归属与 `creator_id` 不变；
+- 一次对**他人共享过来**的 KB 的写操作，需要同时满足：共享时设了「可写」 + 你在该空间不是 Viewer + 源空间的 RBAC 仍然放行；
+- API Key 跨空间访问**不会**带 Admin 光环——共享路径由 `organization_members.role` 决定，与 API Key 无关。
+
+判定顺序见 `internal/middleware/kb_access.go`：
+
+```text
+KB 属于我当前空间？─是─► 走空间 RBAC（角色 + creator_id）
+            └─否─► KB 共享给我所在空间？─是─► 取 min(共享权限, 空间角色)
+                                       └─否─► 403 / 404
+```
+
+一句话：**空间 RBAC 是纵向的纵深防御，共享空间是横向的协作通道；跨空间写动作必须同时穿过两道闸口。**
+
+## 配置
+
+```yaml
+tenant:
+  enable_rbac: true          # false 则进入「仅记录不拦截」灰度窗口
+  enable_cross_tenant_access: false
+auth:
+  registration_mode: self_serve   # 或 invite_only
+audit:
+  retention_days: 90              # 0 表示不清理
+```
+
+环境变量 `WEKNORA_TENANT_ENABLE_RBAC` / `WEKNORA_AUDIT_RETENTION_DAYS` 覆盖 YAML。`DISABLE_REGISTRATION=true` 等价于把 `registration_mode` 强制设为 `invite_only`。
+
+## 审计
+
+`audit_logs` 表记录：
+
+- `rbac.member_added` / `removed` / `role_changed` / `left`
+- `rbac.access_denied`（仅强制鉴权时；1 分钟滑动窗口去重）
+
+每日后台 goroutine 清理超过 `audit.retention_days` 的旧行。
+
+## 相关主题
+
+- [共享空间说明](./共享空间说明.md) — 跨空间协作与共享，与 RBAC 正交
+- [OIDC认证调用流程](./OIDC认证调用流程.md) — 多空间用户体系的认证入口
+- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 单用户场景下 RBAC 实际不发挥作用
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [共享空间说明](./共享空间说明.md) — 共享空间访问最终落到空间 RBAC 校验
+- [OIDC认证调用流程](./OIDC认证调用流程.md) — JWT 解析后即进入 RBAC 角色匹配

docs/wiki/安全认证/共享空间说明.md

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

docs/wiki/开发部署/开发指南.md

@@ -0,0 +1,93 @@
+---
+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 |
+
+> Neo4j 的使用参见 [知识图谱](../核心功能/知识图谱.md) 和 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
+
+## 使用 Air 实现后端热重载
+
+```bash
+go install github.com/air-verse/air@latest
+make dev-app  # 检测到 Air 时自动启用热重载
+```
+
+## 前端独立开发
+
+```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) — 开发相关故障排查

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) — 开发模式相关故障排查

docs/wiki/核心功能/Agent技能系统.md

@@ -0,0 +1,104 @@
+---
+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、CubeSandbox 或 E2B 配置。远端模板从目标集群实时获取；缺少 WeKnora 标准模板时由系统自动创建。智能体在编辑页选择一份空间配置，没有选择时不执行技能脚本。Docker、CubeSandbox、E2B 均保留会话级沙箱。
+
+## 配置示例
+
+```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 社区扩展方向

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 工具

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) — 同为内置系统配置，模式相似

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`、`litellm`、`requesty`、`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) — 路线图中模型训练方向

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) — 图谱功能相关的故障排查

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 的配置与启动

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 安全策略

docs/wiki/集成扩展/IM集成开发.md

@@ -0,0 +1,130 @@
+---
+title: IM集成开发
+tags: [集成扩展, IM, 企微, 飞书, Lark, Slack, Telegram, 钉钉, Mattermost]
+aliases: [IM集成, IM开发, 企业微信, 即时通讯]
+source: IM集成开发文档.md
+---
+
+# IM 集成开发
+
+WeKnora 的 IM 集成模块将企业即时通讯平台（企业微信、飞书、Lark、Slack、Telegram、钉钉、Mattermost）接入 WeKnora 知识问答管道，支持在 IM 中直接向 AI 提问并获得实时流式回答。
+
+IM 渠道绑定到 Agent，一个 Agent 可接入多个 IM 渠道。
+
+> IM 渠道中的 Agent 可以使用 [MCP 工具](../核心功能/MCP功能使用说明.md) 和 [Skills 技能](../核心功能/Agent技能系统.md)
+
+## 支持的平台
+
+| 平台 | WebSocket 模式 | Webhook 模式 | 流式输出 |
+|------|:-:|:-:|:-:|
+| 企业微信 | ✅ | ✅ | ✅ |
+| 飞书 | ✅ | ✅ | ✅ (CardKit) |
+| Lark（飞书国际版） | ✅ | ✅ | ✅ (CardKit) |
+| Slack | ✅ (Socket Mode) | ✅ (Events API) | ✅ |
+| Telegram | ✅ (长轮询) | ✅ | ✅ |
+| 钉钉 | ✅ (Stream) | ✅ | ✅ (AI 卡片) |
+| Mattermost | — | ✅ | ✅ |
+
+## 快速接入指南
+
+### 前置条件
+
+- WeKnora 已部署并运行
+- 已创建至少一个 Agent（自定义智能体）
+- Agent 已配置好模型和知识库
+
+> Agent 配置模型参见 [内置模型管理](../核心功能/内置模型管理.md)
+
+### 企业微信接入
+
+提供两种模式：
+- **WebSocket 模式**（智能机器人，推荐）— 无需公网域名
+- **Webhook 模式**（自建应用）— 需要公网回调地址
+
+### 飞书接入
+
+- **WebSocket 模式**（推荐）— 无需公网域名
+- **Webhook 模式** — 需要公网回调地址
+
+> 飞书同时也是数据源导入的支持平台，参见 [数据源导入开发](数据源导入开发.md)
+
+### Lark 接入
+
+Lark 是飞书的国际版，IM 接口一致，与飞书共用同一套适配器。接入步骤基本相同，但开放平台
+与**权限清单**不同：
+
+- 飞书：<https://open.feishu.cn/>
+- Lark：<https://open.larksuite.com/>
+
+> **权限不可套用飞书的清单**：飞书清单混入了数据源连接器（Wiki 同步）用的权限，其中部分在
+> Lark 并不存在，整份导入会失败。Lark 只需 IM 相关的 6 项，见
+> [IM集成开发文档 — Lark 权限配置](../../IM集成开发文档.md#lark-权限配置)。
+
+> 两朵云的应用互不通用，凭证只在创建它的那朵云上有效。
+
+### 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 集成已完成的里程碑

docs/wiki/集成扩展/数据源导入开发.md

@@ -0,0 +1,103 @@
+---
+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 地址
+
+## 飞书 docx 解析模式与环境变量
+
+飞书新版云文档（docx）的解析路径由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制（作用于 app 服务，对飞书知识库和飞书云盘两个连接器同时生效）：
+
+| 模式 | 值 | 解析路径 | 图片与文档关联 | 速度 | docx 内附件 |
+|---|---|---|---|---|---|
+| export（默认） | 留空 / `export` | 异步导出 -> .docx 二进制 -> docreader 解析 | ✅ 图片 inline 进父文档，`parent_chunk_id` 关联 | 慢 | 丢失 |
+| blocks | `blocks` | blocks API -> Markdown | ❌ 图片作为独立知识条目，与文档割裂 | 快 | 保留 |
+
+**优缺点对比：**
+
+- **export**：导出 .docx 交 docreader 解析，图片 inline 进父文档（与普通 docx 上传一致），通过 `parent_chunk_id` 建立同知识条目父子关联，三个场景都能关联图片内容；代价是同步变慢（异步导出 + docx 解析）、docx 内附件丢失、图片 OCR/caption 依赖多模态配置。
+- **blocks**：图片 block 渲染成空 `![图片]()` 占位符，图片单独下载成独立知识条目，检索 / Wiki / 智能体无法把图片内容关联回文档；但同步快、保留 docx 内 file block 附件。
+
+配置方法：默认即为 export，无需设置；需要 blocks 模式时在 `.env` 或 `docker-compose.yml` 的 app 服务环境变量中设置 `FEISHU_DOCX_PARSE_MODE=blocks`，重启 app 服务生效。详见 [飞书云盘数据源接入说明](飞书云盘数据源接入说明.md#6-docx-解析模式与环境变量)。
+
+## 架构设计
+
+```
+外部平台 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) — 同类扩展开发模式

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) — 路线图中的社区组件扩展方向

docs/wiki/集成扩展/集成向量数据库.md

@@ -0,0 +1,123 @@
+---
+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/`
+- Apache Doris 4.1: `internal/application/repository/retriever/doris/`
+- Tencent VectorDB: `internal/application/repository/retriever/tencentvectordb/`
+
+## Apache Doris 4.1 集成要点
+
+Doris 是 MPP 风格的分析型 SQL 库，其接入方式与 NoSQL 向量库有几处特殊点：
+
+- **协议**：MySQL 协议（FE 9030）走主链路；HTTP API（FE 8030）走 Stream Load partial update。
+- **表结构**：每维度一张 `<DORIS_TABLE_PREFIX>_<dim>` 表，`UNIQUE KEY(id)` + `enable_unique_key_merge_on_write=true`。
+- **索引**：INVERTED 索引覆盖过滤字段、`content` 字段使用 `chinese` parser；ANN 索引使用 HNSW + cosine_distance（异步构建，建表后自动轮询 30s 等待 `FINISHED`）。
+- **分数语义**：使用 `1 - cosine_distance_approximate(...)`，threshold 比较 `>=`、`ORDER BY DESC`，与 Qdrant cosine 相似度方向一致。
+- **关键词检索**：基于 Doris 倒排索引的 `MATCH_ANY`，无需在 Go 端做 jieba 分词。
+- **批量字段更新**：`BatchUpdateChunkEnabledStatus` 与 `BatchUpdateChunkTagID` 通过 Stream Load partial update 协议实现，支持 1MiB 自动分批。
+
+环境变量：
+
+```
+RETRIEVE_DRIVER=doris
+DORIS_ADDR=doris-fe:9030
+DORIS_HTTP_PORT=8030
+DORIS_DATABASE=weknora
+DORIS_USERNAME=root
+DORIS_PASSWORD=
+DORIS_TABLE_PREFIX=weknora_embeddings
+```
+
+启动方式：`docker compose --profile doris up -d`，然后在 FE 上 `CREATE DATABASE weknora;`。
+
+## Tencent VectorDB
+
+WeKnora 内置 Tencent VectorDB 适配器，驱动名为 `tencent_vectordb`。该适配器支持向量检索、基于 BM25 sparse vector 的关键词检索和索引管理，可参与 WeKnora 上层混合检索。
+
+```env
+RETRIEVE_DRIVER=tencent_vectordb
+TENCENT_VECTORDB_ADDR=http://your-instance.tencentvectordb.com
+TENCENT_VECTORDB_USERNAME=root
+TENCENT_VECTORDB_API_KEY=your_tencent_vectordb_api_key
+TENCENT_VECTORDB_DATABASE=weknora
+TENCENT_VECTORDB_COLLECTION=weknora_embeddings
+TENCENT_VECTORDB_REPLICA_NUMBER=1
+```
+
+`TENCENT_VECTORDB_COLLECTION` 是集合名前缀。WeKnora 会按向量维度创建实际集合，例如 `weknora_embeddings_768`。
+`TENCENT_VECTORDB_REPLICA_NUMBER` 是创建集合时使用的副本数，默认 `1`；单节点 QA 环境可设为 `0`，生产环境可按 Tencent VectorDB 集群规模调整。
+
+关键词检索依赖 Tencent VectorDB sparse vector 索引。新建集合会自动创建 `sparse_vector` 索引；旧版本已创建的向量集合如果没有该索引，需要重建集合并重新导入知识库数据后才能启用关键词检索。
+
+## 相关主题
+
+- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式（接口实现 + 注册 + DI）
+- [知识图谱](../核心功能/知识图谱.md) — 知识图谱功能依赖 Neo4j 而非向量数据库
+- [常见问题](../运维排障/常见问题.md) — Embedding 模型配置与向量维度相关
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式
+- [知识图谱](../核心功能/知识图谱.md) — 另一种知识检索方式（基于图而非向量）
+- [版本路线图](../项目概述/版本路线图.md) — 路线图中的检索能力扩展方向

docs/wiki/集成扩展/飞书云盘数据源接入说明.md

@@ -0,0 +1,167 @@
+# 飞书云盘数据源使用说明
+
+飞书云盘数据源(`feishu_drive` / `lark_drive`)可以把飞书/Lark 云盘某个文件夹下的文档和文件自动同步到 WeKnora 知识库,支持增量同步、定时同步和子文件夹递归。
+
+---
+
+## 1. 前置条件:创建飞书应用
+
+1. 登录[飞书开放平台](https://open.feishu.cn/app)(Lark 用户使用 [Lark 开放平台](https://open.larksuite.com/app)),创建**企业自建应用**。
+2. 记录应用的 **App ID**(`cli_` 开头)和 **App Secret**,配置数据源时需要填写。
+3. 按下节表格开通权限,并**发布应用版本**(权限修改后必须重新发布才生效)。
+
+> 注意:飞书(open.feishu.cn)和 Lark(open.larksuite.com)是两个独立体系,应用不通用。同步飞书云盘用飞书应用,同步 Lark Drive 用 Lark 应用,凭据不能混用。
+
+---
+
+## 2. 所需权限(详细)
+
+在应用后台「权限管理」中开通以下 **3 个权限**:
+
+| 权限标识 | 名称 | 用途 | 缺少时的表现 |
+|---|---|---|---|
+| `drive:drive:readonly` | 查看云空间中的文件 | 列举文件夹内容(list API)、下载云盘普通文件 | 加载文件夹/同步时报 403,提示「需先将文件夹分享给应用所在的群」 |
+| `drive:export:readonly` | 导出云文档 | 把 docx/doc/sheet/bitable 导出为 docx/xlsx 再解析 | 云文档类文件同步失败 |
+| `docx:document:readonly` | 读取新版文档内容 | 通过 blocks API 解析 docx 文档正文与附件(导出失败时的主路径) | docx 文档解析失败或回退导出也失败 |
+
+说明:
+
+- 与「飞书知识库」连接器相比,云盘**不需要** `wiki:wiki:readonly`,其余权限相同。
+- list API 本身还接受 `drive:drive`(读写)或 `space:document:retrieve` 作为替代,但推荐只开只读的 `drive:drive:readonly`,最小授权。
+- 权限开通后必须**创建并发布新版本**,否则接口仍报无权限。
+
+---
+
+## 3. 关键一步:把文件夹分享给应用
+
+飞书的权限模型要求:即使应用开通了上述 API 权限,也只能访问**被显式分享给它的文件**。
+
+1. 创建一个飞书（Lark）群或复用某个飞书（Lark）群
+2. 将需要导入的**飞书云盘管理者**拉进群
+> PS: 不拉进群也会导致没有访问权限
+3. 在飞书云盘中打开目标文件夹;
+4. 点击「分享」/「··· → 添加协作者」,把文件夹分享给**应用所在的群**(把应用拉进一个群,再将文件夹分享给该群),权限给「可阅读」即可;
+5. 子文件夹和其中的文件会随父文件夹一起获得授权,无需逐个分享;
+6. 如果之后新增的文件同步报 403,检查该文件是否在这棵已分享的目录树下。
+
+这是一次性操作,但不做的话,加载文件夹会直接报「应用无权访问该文件夹」。
+
+---
+
+## 4. 配置数据源(四步)
+
+入口:知识库 → 设置 → 数据源 → 新建数据源,选择「飞书云盘」。
+
+### 第 1 步:选择类型
+
+选择「飞书云盘」(国际版选「Lark Drive」)。
+
+### 第 2 步:配置凭证
+
+填写 App ID 和 App Secret,点击下一步时系统会自动测试连接(验证 tenant_access_token 能否获取)。此步只验证应用身份,不验证文件夹权限。
+
+### 第 3 步:选择范围
+
+1. 在「云盘文件夹 Token」输入框填入目标文件夹的 `folder_token`,**或直接粘贴文件夹的完整链接**(飞书 `https://xxx.feishu.cn/drive/folder/<token>` 或 Lark `https://xxx.larksuite.com/drive/folder/<token>`,系统按路径自动提取 token,两种链接都支持);
+2. 点击「加载」,列出该文件夹下的完整目录树;
+3. 勾选要同步的文件/文件夹,支持逐级展开、全选/折叠分支。
+
+注意:
+
+- **不支持云空间根目录**(根目录不分页且不返回快捷方式),必须选择具体文件夹;
+- 加载失败时按提示处理:403 → 回到第 3 节分享文件夹;token 无效 → 重新从文件夹 URL 复制。
+
+### 第 4 步:同步策略
+
+| 配置项 | 说明 | 默认值 |
+|---|---|---|
+| 同步计划 | cron 表达式,默认每 6 小时一次;留空则只手动触发 | `0 0 */6 * * *` |
+| 同步模式 | 增量(按修改时间游标)/ 全量 | 增量 |
+| 冲突策略 | 内容变更时覆盖 / 跳过 | 覆盖 |
+| 同步删除 | 源端删除的文档**只计数,不自动删除知识库内容**,需在知识库手动删除 | 开启 |
+
+保存后数据源开始按策略运行,也可在数据源卡片上手动「触发同步」。
+
+---
+
+## 5. 支持的文件类型
+
+| 云盘类型 | 处理方式 |
+|---|---|
+| `docx` / `doc`(新旧文档) | blocks API 解析正文与附件,失败时回退导出为 docx 解析 |
+| `sheet` / `bitable`(表格/多维表格) | 导出为 xlsx 解析 |
+| `file`(普通上传文件,如 PDF/PPT/图片) | 直接下载后按文件类型解析 |
+| `shortcut`(快捷方式) | 自动解析为目标文件同步(快捷方式不能指向文件夹) |
+| `folder`(文件夹) | 递归遍历 |
+| `mindnote` / `slides` / `board` | 不支持,跳过 |
+
+补充行为:
+
+- docx 中的**附件**会作为独立知识条目同步(与父文档关联,父文档更新时自动清理已移除的附件);
+- 文档内嵌图片会尝试 OCR/多模态解析,未配置对象存储或 VLM 时自动跳过,不影响正文同步。
+
+---
+
+## 6. docx 解析模式与环境变量
+
+飞书新版云文档(docx)有两种解析路径,由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制。该变量作用于 WeKnora **app 服务**(不是数据源配置),对飞书云盘和飞书知识库两个连接器同时生效。
+
+### 模式对比
+
+| | export(默认) | blocks |
+|---|---|---|
+| 环境变量值 | 留空 / `export` | `blocks` |
+| 解析路径 | 异步导出 API -> .docx 二进制 -> docreader 解析 | blocks API -> Markdown |
+| 图片与文档关联 | ✅ 图片 inline 进父文档,`parent_chunk_id` 关联 | ❌ 图片作为独立知识条目,与文档割裂 |
+| 检索 / Wiki / 智能体能否关联图片 | 是 | 否 |
+| 同步速度 | 慢(异步导出 + docx 解析) | 快 |
+| docx 内附件(file block) | 丢失(.docx 导出不含) | 保留,作为独立条目 |
+| 所需权限 | `drive:drive:readonly` + `drive:export:readonly` | `drive:drive:readonly` + `drive:export:readonly` + `docx:document:readonly` |
+
+### 为什么图片关联有差异
+
+- **export 模式**:导出 .docx 后由 docreader 解析,图片 inline 进父文档(与普通 docx 上传一致),通过 `parent_chunk_id` 建立同知识条目的父子关联,三个场景都能在一次检索中把图片内容与文档一起返回。
+- **blocks 模式**:走 blocks API,图片 block 渲染成空 `![图片]()` 占位符,图片单独下载成独立知识条目,与父文档只有元数据级弱关联。WeKnora 的检索、Wiki 构建、智能体问答链路都不会把图片内容关联回文档,图片和正文是割裂的。
+
+### 配置方法
+
+在 WeKnora 服务的 `.env` 或 `docker-compose.yml` 的 app 服务环境变量中设置:
+
+```env
+FEISHU_DOCX_PARSE_MODE=blocks
+```
+
+不设置或设为 `export` 即用默认模式。修改后需重启 app 服务生效。
+
+### export 模式的代价
+
+- **同步变慢**:每个 docx 都要走异步导出(创建任务 + 轮询 + 下载)+ docreader 解析,比 blocks API 慢。
+- **附件丢失**:docx 内 file block 附件不随 .docx 导出下载,如需附件用 blocks 模式或单独同步。
+- **图片内容依赖多模态**:图片 inline 后 OCR/caption 由多模态服务异步生成,未配置对象存储或 VLM 时图片只存储不生成内容(前端展示正常,但检索层面仍弱)。
+
+### 选择建议
+
+- 需要图片内容在检索 / Wiki / 智能体中与文档关联:用默认 **export**。
+- 只需文档正文、要保留附件、追求同步速度:用 **blocks**。
+
+---
+
+## 7. 同步行为说明
+
+- **增量同步**:以文件修改时间为游标,只拉取上次同步后变更的内容;中断后从断点续传。
+- **部分失败不中断**:某个子文件夹无权限或某个文件下载失败时,该条目记为失败,其余内容继续同步,失败明细可在「同步日志」中查看。
+- **更新语义**:内容变更的文件会先删除旧知识条目再重建,解析期间该文档短暂不可用,属正常现象。
+- **安全约束**:为避免误删,源端删除的文件不会自动从知识库移除(见第 4 步「同步删除」)。
+
+---
+
+## 8. 常见问题
+
+| 现象 | 原因与处理 |
+|---|---|
+| 「请输入具体文件夹的 folder_token,不支持云空间根目录」 | 输入为空或粘贴的是根目录链接,换具体文件夹链接 |
+| 「应用无权访问该文件夹。请…分享给应用所在的群」 | 未完成第 3 节的分享,或分享的对象不是应用所在的群 |
+| 「应用凭证无效或缺少云盘权限」 | App ID/Secret 错误,或第 2 节权限未开通/未发布版本 |
+| 「folder_token 不存在或已删除」 | token 复制有误,从文件夹「分享 → 复制链接」重新获取 |
+| 同步日志中部分条目失败 | 点开日志看失败阶段:`list_children` 多为子文件夹未授权,`fetch` 多为单文件权限或类型不支持 |
+| 知识列表中来源显示 | 云盘同步的文档来源标记为「飞书云盘」,与知识库同步的「飞书」区分 |

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) — 标准版多空间场景下的认证方式

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 集成已完成的里程碑