# LLMWiki × WeKnora 集成与部署

## 目标与边界

DeerFlow 只把 WeKnora 当作独立部署的知识抽取、向量化和检索服务，不复制或修改 WeKnora 前端，也不接管它的运行配置。

本版本按 WeKnora `v0.7.2` 的官方 REST API 实现；升级 WeKnora 大版本前应先回归下文列出的主要接口。

- WeKnora 自己负责 PostgreSQL、Redis、对象存储、解析器、向量库、Embedding/Rerank/LLM 等依赖。
- DeerFlow 只保存 WeKnora 连接地址，以及 DeerFlow 用户、发布状态、智能体绑定与 WeKnora 知识库之间的映射。
- DeerFlow 不保存也不发送 WeKnora API Key、Bearer Token 或其他 WeKnora 凭证；浏览器拿不到原始 WeKnora 知识库 ID。
- 用户权限、智能体所有权和页面风格全部沿用 DeerFlow；库所有者发布后立即进入公共 LLMWiki，不经过审核队列。

## 模式开关

`config.yaml` 中 `llmwiki.weknora.api_base_url` 非空时启用 WeKnora 模式；为空时继续使用原有 LLMWiki 页面和流程。

```yaml
llmwiki:
  weknora:
    api_base_url: "http://weknora-app:8080"
    web_base_url: "http://weknora-app:8080"
```

管理员也可在 DeerFlow 原 LLMWiki 页面中的“集成配置”修改地址。页面配置是运行时覆盖项：启用覆盖并填写地址会切换到 WeKnora；启用覆盖但留空会强制回到原模式；“恢复配置文件设置”会重新采用 `config.yaml`。

这两个地址是 DeerFlow 中全部的 WeKnora 配置，不需要创建密钥文件，也不需要在 DeerFlow 中配置 WeKnora 的数据库、模型或存储参数。

## WeKnora 侧准备

先按 WeKnora 官方部署方式完整启动 WeKnora。数据库、Redis、MinIO/S3、解析服务和所有模型均在 WeKnora 自己的 compose、`.env` 或管理页面配置，DeerFlow 无对应字段。

DeerFlow 对 WeKnora 使用无凭证的内部 HTTP 请求，因此 `api_base_url` 必须指向可信内网服务，不能把匿名接口直接暴露到公网。需要在 WeKnora 自身或前置反向代理中，仅按容器网络、源 IP、安全组或 mTLS 等基础设施边界放行 DeerFlow。若 WeKnora 保持默认接口鉴权且未放行，连接测试会收到 401/403，并提示配置 WeKnora 或反向代理；DeerFlow 不提供凭证回退。

WeKnora 中至少需要一个可用且标为默认的 Embedding 模型。创建知识库时，DeerFlow 调用 WeKnora `/api/v1/models` 查找 `type=Embedding` 的默认模型，并把它的 ID 传给 WeKnora；因此 DeerFlow 不提供 `default_embedding_model_id` 配置。这个 ID 的含义是“新知识库使用哪个编码模型生成向量”，其生命周期属于 WeKnora。

WeKnora 侧放行范围需要覆盖本版本调用的模型读取、知识库管理、文档写入和知识检索接口。如果基础设施只放行检索接口，可以检索已有知识库，但无法通过 DeerFlow 创建知识库或上传文档。

## 数据与权限模型

DeerFlow 的 `llmwiki_knowledge_bases` 表保存以下控制面数据：DeerFlow 映射 ID、WeKnora ID、所有者用户 ID、名称快照和公开状态。文档、切片、向量和模型参数仍只存在 WeKnora。

- 个人库：仅所有者和 DeerFlow 管理员可管理。
- 公共库：所有者点击发布后立即公开，全部 DeerFlow 用户只读可检索；所有者可随时取消公开。
- 删除个人库时先删除 WeKnora 实体，再删除 DeerFlow 映射。
- 所有 BFF 接口和智能体工具都会按当前 DeerFlow 登录用户重新鉴权，不能靠前端提交任意知识库 ID 越权。

当前无凭证/反向代理方案使用一个固定的 WeKnora 服务身份。因此 DeerFlow 的用户隔离是映射层的逻辑隔离：不同 DeerFlow 用户只能看到自己拥有的库和已公开库；但这些库在 WeKnora 物理上都创建于该服务身份所属的同一个空间。上传文件不会落到 DeerFlow 用户目录，而是经 DeerFlow BFF 转发给 WeKnora，由 WeKnora 把文件对象、知识元数据、切片和向量分别写入自己的对象存储、数据库和向量存储。需要在 WeKnora 后台核对时，应登录这个服务身份所属空间，在“知识库管理”中按同名知识库进入查看。

如果要求 WeKnora 本身也按 DeerFlow 用户划分空间，则需要另一种部署：为每个 DeerFlow 用户建立 WeKnora 用户/租户并安全保存、轮换各自凭证。它与当前“不在 DeerFlow 配置 WeKnora 凭证”的单服务身份方案不同，不能只靠前端切换实现。

## 智能体和对话选择

智能体 `config.yaml` 可保存：

```yaml
llmwiki_knowledge_base_ids:
  - "deerflow-mapping-id-1"
  - "deerflow-mapping-id-2"
```

这里必须是 DeerFlow 映射 ID，不是 WeKnora 原始 ID。智能体创建页和详情编辑页均提供内嵌的“绑定知识空间”面板，可直接搜索、分组、多选、全选或清空当前用户有权读取的个人库和公共库，不再通过额外弹窗配置。

新建智能体对话时，页面只展示“智能体已绑定”且“当前登录用户仍有权读取”的交集，默认全选，可在发送第一条消息前调整或清空。普通新建对话也可选择知识库；选中了智能体时会自动切换成该智能体的绑定范围。问答选择器仿照 WeKnora 的交互结构，作为输入框工具栏的锚定下拉呈现，包含搜索、个人/公共分组、文档数量、多选、全选和清空，不再在输入框外单独占据一行。选择结果写入 LangGraph thread metadata 和运行 context，重新打开对话会恢复，开始对话后不可中途扩大权限范围。

`llmwiki_search` 是只读工具，只在 WeKnora 模式注册。每次调用会同时校验：

1. 当前对话选择；
2. 智能体允许的绑定范围；
3. 当前 DeerFlow 用户对映射的实时读取权限。

明确选择空列表表示本次对话不使用 LLMWiki；旧对话没有选择字段时，智能体对话默认使用其绑定范围，通用 Lead Agent 默认使用当前用户全部可见知识库。

## 前端实现

WeKnora 前端不做任何修改。DeerFlow 原“知识库资源管理”入口根据运行模式渲染：

- 原模式：保留现有 LLMWiki iframe 页面；
- WeKnora 模式：渲染 DeerFlow 原生 React 页面，提供个人库、公共库、直接发布和检索。点击卡片进入独立知识库路由，内容区复刻 WeKnora 的详情页结构，同时保留 DeerFlow 的导航、登录和权限壳。Wiki 库按 **Wiki → 文档 → 图谱** 排列并默认打开 Wiki；标准库不显示 Wiki 标签，按 **文档 → 图谱** 排列。Wiki 视图包含页面目录、搜索、页面正文和引用摘要；文档以卡片网格展示，点击后从右侧抽屉查看元数据、原文件与真实解析分块；图谱视图渲染 WeKnora Wiki 页面节点和边。新建知识库可选择“Wiki 知识库”或“标准知识库”，详情页支持文件、网页 URL、手工 Markdown 三种导入方式。问答选择器沿用 WeKnora 的紧凑搜索/分组/多选交互，颜色、间距和组件沿用 DeerFlow 设计系统；智能体创建和编辑页使用同一数据源的内嵌绑定面板。

问答检索命中以 DeerFlow 来源卡片展示。“查看原文”调用 DeerFlow 的 `/api/llmwiki/sources/context`，由服务端在重新校验 DeerFlow 用户权限后向 WeKnora 读取命中切片及相邻上下文，不向浏览器暴露 WeKnora 原始资源 ID。

## 主要接口

- `GET /api/llmwiki/runtime`：当前原模式/WeKnora 模式。
- `/api/system-settings/llmwiki`：管理员地址配置、重置和连通性测试。
- `/api/llmwiki/knowledge-bases`：知识库 CRUD、标准/Wiki 模式创建、详情、文档上传、解析、直接发布和取消公开。
- `POST /api/llmwiki/knowledge-bases/{id}/documents/url`：导入网页 URL。
- `POST /api/llmwiki/knowledge-bases/{id}/documents/manual`：发布手工 Markdown 内容。
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}`：具体文档元数据。
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/preview`：鉴权后代理原文件预览。
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/chunks`：分页读取解析后的真实分块索引。
- `GET /api/llmwiki/knowledge-bases/{id}/graph`：读取 Wiki 页面图谱的节点和边；未开启 Wiki 索引时返回明确的空状态。
- `GET /api/llmwiki/knowledge-bases/{id}/wiki/pages` 与 `.../wiki/pages/{slug}`：读取 Wiki 页面目录和正文。
- `GET /api/llmwiki/agents/{agent_id}/knowledge-bases`：当前用户可用于该智能体的绑定交集。
- `POST /api/llmwiki/search`：页面检索。
- `GET /api/llmwiki/sources/context`：引用原文上下文。

## 验收建议

1. 地址留空启动，确认原 LLMWiki 页面和原有流程不变。
2. 在可信网络中放行 DeerFlow，配置地址，测试连接并创建个人库、上传文档、等待解析完成；确认 DeerFlow 请求没有认证头。
3. 普通用户直接发布，换另一用户确认能立即读取和检索、但不能修改；再由所有者取消公开并确认访问随即失效。
4. 给智能体绑定两个库，新建对话取消其中一个，确认引用只来自保留的库；重新打开对话确认选择恢复。
5. 撤销公共发布或删除用户权限后继续提问，确认工具实时拒绝已失效的知识库。