WeKnora/docs/api
lyingbug 2be7bd4063
fix(agent): search bound knowledge bases before answering, and pass suggested-question origins (#3400)
* fix(agent): search bound knowledge bases before answering, and pass suggested-question origins

A user picked the suggested question "为什么在比较图形时需要谨慎处理?"
and the agent answered in round 1 with no tool call, claiming it had
searched the knowledge base and found nothing, then explained misleading
statistical charts. The question had been generated from "Corners Don't
Look Like That: Regarding Screenspace Ambient Occlusion" in a bound base,
where "comparing graphs" means SSAO falloff curves.

Two things let that happen: the grounding prompt said "Stable general
explanations need no lookup", and nothing told the agent where the
question came from - the base in question had no profile, only two
recent titles in the directory, and the click sent the text alone.

Prompt
- With knowledge tools available, search bound bases before answering a
  question about a topic, even one that reads like general knowledge;
  directory profiles and recent titles cannot prove a base lacks it.
- The general-explanation exemption applies only without bound bases.
- Say you searched or found nothing only when a search tool ran.

Question origin
- Suggested questions from FAQ/document chunks also return knowledge_id.
- Picking one on the home or chat page sends question_origin
  {knowledge_base_id, knowledge_id} with that question only.
- The service keeps the origin only when its base is inside the turn's
  resolved scope and the document belongs to that base; it never
  changes the scope (unlike knowledge_base_ids, which narrows it).
- The engine renders it in runtime_context as <question_origin> with the
  base and document handles and a note to search it before answering.

* fix(agent): keep question origins across file/tag scopes and bind them to the send

Review follow-up for the suggested-question origin.

- Scope check: the origin was kept only when its base was in the resolved
  KB list, which is empty for file-only and tag-only scopes even though
  their bases are searched. It is now checked against SearchTargets after
  they are built; the document is kept only when a target for that base
  covers it (unfiltered base, or a document scope listing it).
  resolveQuestionOriginInfo re-checks SearchTargets, looks up the name of
  a base that is not in kbInfos, and the renderer omits an unknown name.
- Frontend: the origin travelled through module-level "pending" state, so
  a send that returned early (agent not ready, upload in progress,
  steering) left it behind and a second pick overwrote it. It now rides
  with the one send: triggerSend(text, options) -> createSession ->
  send-msg -> sendMsg / changeFirstQuery.
- RetrieveKBOnlyWhenMentioned: suggestions are still generated from the
  agent's bases, but picking one retrieved nothing. The origin now
  selects its base, as an @mention would, when the agent may read it.
- API sync: question_origin in docs/api/chat.md and swagger;
  QuestionOrigin on the Go SDK's KnowledgeQARequest/AgentQARequest and
  knowledge_id on SuggestedQuestion.
2026-09-18 17:00:47 +08:00
..
README.md chore: prepare v0.8.0 release notes and version bump 2026-09-03 14:46:44 +08:00
agent.md feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
auth.md fix(auth): record last-active-tenant preference on SwitchTenant (#2922) 2026-09-01 15:43:40 +08:00
chat.md fix(agent): search bound knowledge bases before answering, and pass suggested-question origins (#3400) 2026-09-18 17:00:47 +08:00
chunk.md docs(api): rewrite markdown to match current routes 2026-05-12 13:16:58 +08:00
evaluation.md docs(api): rewrite markdown to match current routes 2026-05-12 13:16:58 +08:00
faq.md feat(faq): filter entries by enabled status (#3157) 2026-09-10 14:42:59 +08:00
initialization.md feat: add agent management functionality 2026-03-09 17:34:13 +08:00
knowledge-base.md feat(api): honor resource_urls=public on hybrid-search 2026-08-26 17:40:54 +08:00
knowledge-search.md docs(api): document resource_urls and RESOURCE_URL_MODE 2026-08-05 14:42:51 +08:00
knowledge.md feat(knowledge): add batch file downloads (#3300) 2026-09-16 15:40:10 +08:00
mcp-service.md feat(mcp)!: persist tool catalogs and add guided configuration (#3118) 2026-09-09 13:34:56 +08:00
memory.md fix(memory): preserve extraction progress and atomic memory updates (#3224) 2026-09-13 00:04:16 +08:00
message.md docs(api): document resource_urls and RESOURCE_URL_MODE 2026-08-05 14:42:51 +08:00
model.md fix(models): protect auto-tag model references 2026-09-14 19:29:19 +08:00
organization.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
session.md feat(sandbox): add a graphical desktop to session sandboxes (#3245) 2026-09-14 20:37:37 +08:00
skill.md fix(skills): install ClawHub skills.sh catalog pages via the install resolver 2026-09-02 16:22:55 +08:00
storage-backend.md feat(storage): add storage backend management API and UI enhancements 2026-07-15 14:54:39 +08:00
system.md fix: filter menus by deployment capabilities (#2674) 2026-08-13 20:18:48 +08:00
tag.md docs(api): rewrite markdown to match current routes 2026-05-12 13:16:58 +08:00
tenant.md feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
vector-store.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
web-search.md feat(web-search): add Zhipu AI web search provider support 2026-07-20 12:15:35 +08:00

README.md

WeKnora API 文档

目录

概述

WeKnora 提供了一系列 RESTful API,用于创建和管理知识库、检索知识,以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。

最权威参考:Swagger UI

WeKnora 同时提供基于 OpenAPI 的 Swagger 文档。启动服务后访问 http://localhost:8080/swagger/index.html,可看到所有端点的完整参数、请求/响应 schema,并可直接在浏览器内试调——它随代码自动更新,是最准确的接口参考。

本目录下的 markdown 文档提供更易读的示例与场景说明,与 swagger 同步维护;当二者出现差异时,以 swagger 为准。

Swagger UI 仅在非 release 模式(GIN_MODE != release)下挂载;生产部署默认关闭。

基础信息

  • 基础 URL: /api/v1
  • 响应格式: JSON
  • 认证方式: API Key

认证机制

所有 API 请求需要在 HTTP 请求头中包含 X-API-Key 进行身份认证:

X-API-Key: your_api_key

为便于问题追踪和调试,建议每个请求的 HTTP 请求头中添加 X-Request-ID:

X-Request-ID: unique_request_id

获取 API Key

在 web 页面完成账户注册后,请前往账户信息页面获取您的 API Key。

请妥善保管您的 API Key,避免泄露。API Key 代表您的账户身份,拥有完整的 API 访问权限。

错误处理

所有 API 使用标准的 HTTP 状态码表示请求状态,并返回统一的错误响应格式:

{
  "success": false,
  "error": {
    "code": "错误代码",
    "message": "错误信息",
    "details": "错误详情"
  }
}

文件与图片引用(resource:// 与直链)

响应里的图片、图表、附件默认以内部引用 resource://<handle> 返回,例如问答答案中的 ![示意图](resource://xifDo7NTSL300Lp1goVutw)。这类引用不能被浏览器直接加载,客户端需要再 调用带鉴权的 GET /files?file_path=<引用> 代理去取字节流。

如果你在把 WeKnora 集成进自己的 App,可以让服务端直接返回可加载的 http(s) 直链,省掉这一次 额外请求:

方式 用法 生效范围
单次请求 在 URL 上加 ?resource_urls=public 仅该次请求
整个部署 环境变量 RESOURCE_URL_MODE=public 所有未显式传参的请求

resource_urls 取值为 handle(默认,保持内部引用)或 public(返回直链);传其它值返回 400。单次请求的参数优先于环境变量,因此把部署默认设成 public 后,仍可用 ?resource_urls=handle 单独退回。

支持该参数的接口:

  • POST /api/v1/knowledge-chat/{session_id}(SSE)
  • POST /api/v1/agent-chat/{session_id}(SSE)
  • GET /api/v1/sessions/continue-stream/{session_id}(SSE)
  • GET /api/v1/messages/{session_id}/load
  • POST /api/v1/knowledge-search
  • POST /api/v1/knowledge-bases/{id}/hybrid-search(兼容 GET)

改写覆盖答案正文、检索结果 content / image_info、knowledge_references、Agent 执行步骤与工具结果,以及消息 上的图片附件。流式回答里跨两个 chunk 被截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。

注意事项

  • 需要外链能力。 直链由存储后端预签名,或由 APP_EXTERNAL_URL + /r/<token> 提供。二者都不 可用时(例如 local 存储且未设 APP_EXTERNAL_URL),该引用保持 resource:// 原样,客户端 仍可回退到 /files 代理。详见 .env.example 中的 APP_EXTERNAL_URL 说明。
  • 直链是限时匿名可读的(WeKnora 签发的 grant 2 小时,MinIO 预签名 24 小时)。任何拿到链接的 人在过期前都能读取该文件,请勿写入日志或转发给不应看到该文件的一方。
  • 嵌入式(embed)渠道不支持该参数。 其访客是匿名的,/api/v1/embed/... 下的接口会强制使用 handle(即使传了 ?resource_urls=public、或部署默认是 public),图片仍走渠道维度的鉴权代理。
  • 限定知识库的 API Key 不能使用 public,返回 403。这类 Key 本身也被拒绝访问 /files 代理,若能拿到匿名直链等于绕过同一道限制。改用 handle 即可正常调用。
  • 同一文件的直链会在有效期内复用:重复请求不会反复签发凭证,也不会每次都拿到不同的 URL,客户端 和 CDN 的缓存因此可以命中。凭证被吊销或过期后链接立即失效。

API 概览

WeKnora API 按功能分为以下几类:

分类 描述 文档链接
认证管理 用户注册、登录、令牌管理;OIDC 流程 auth.md · OIDC认证调用流程.md
空间管理 创建和管理空间账户 tenant.md
知识库管理 创建、查询和管理知识库 knowledge-base.md
知识管理 上传、检索和管理知识内容 knowledge.md
模型管理 配置和管理各种AI模型 model.md
分块管理 管理知识的分块内容 chunk.md
标签管理 管理知识库的标签分类 tag.md
FAQ管理 管理FAQ问答对 faq.md
智能体管理 创建和管理自定义智能体 agent.md
会话管理 创建和管理对话会话 session.md
知识搜索 在知识库中搜索内容 knowledge-search.md
聊天功能 基于知识库和 Agent 进行问答 chat.md
消息管理 获取和管理对话消息 message.md
评估功能 评估模型性能 evaluation.md
初始化管理 知识库模型配置与 Ollama 管理 initialization.md
系统管理 系统信息、解析引擎、存储引擎 system.md
MCP 服务 MCP 工具服务管理 mcp-service.md
组织管理 组织、成员、知识库/智能体共享 organization.md
Skills 预装与已安装的智能体技能、技能环境变量 skill.md
长期记忆 当前用户的跨会话记忆(设置、条目、主题、文档亲和度、导出、整理) memory.md
网络搜索 网络搜索服务商 web-search.md
向量存储 向量数据库连接管理 vector-store.md
存储后端 对象/文件存储实例(多实例)管理 storage-backend.md
IM 渠道 企业微信 / 飞书 / Slack 等 IM 平台对接,含渠道 CRUD 与回调 ../IM集成开发文档.md
数据源导入 飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步 ../数据源导入开发文档.md