知识库 API & MCP

在 model.dflop.top/wiki 上传文档(PDF / Word / Markdown / 表格等),系统会把它们编译成互相链接的知识页(带标题 / 摘要 / 标签 / 出链)。本页描述的两套对外只读检索面让你在自己的工具里直接查这些知识:

检索面	形态	适用场景
`/api/v1/ext/wiki/*`	8 条只读 REST 端点	自己写脚本 / 后端服务集成
`/mcp`	MCP server(Streamable HTTP,6 个工具)	Claude Code / Codex / Cursor 等 MCP 客户端

两者底层是同一套检索逻辑,鉴权也是同一把 sk-gpushare-* API Key —— 与聊天端点共用,鉴权方式见鉴权。结果仅限这把 Key 所属账号可读的知识库(个人知识库 + 有权限的团队知识库)。

只读检索本身不消耗余额。带 AI 问答的 agentic 检索(自动多轮搜索 + 引用)在 model.dflop.top 的 Chat 里,不在本 API 面。

REST 端点#

全部为 GET,挂在 https://api.dflop.top 下:

端点	用途
`/api/v1/ext/wiki/search`	词法搜索,返回排序命中 + 真实总命中数
`/api/v1/ext/wiki/kbs`	列出可访问的知识库(`kb_id` + 页数)
`/api/v1/ext/wiki/tags`	某知识库的全部标签 + 计数(标签云)
`/api/v1/ext/wiki/tags/{tag}`	某标签下的全部页
`/api/v1/ext/wiki/pages`	按 `?ids=a,b,c` 批量读页(最多 25 个,正文节选)
`/api/v1/ext/wiki/pages/{id}`	读单页完整内容(正文 + 出链 + 来源)
`/api/v1/ext/wiki/pages/{id}/backlinks`	链向该页的页列表(反向链接)
`/api/v1/ext/wiki/pages/{id}/source`	该页编译自的源文档信息 + 临时下载链接

通用约定#

kb_id query 参数:除 /kbs 外所有端点都接受,缺省 default(个人默认知识库)。可用取值来自 /kbs 返回的 kb_id 字段。
404 语义:不可读 / 不存在的知识库或页面一律返回 404(不区分"不存在"与"无权限",不泄露存在性)。
鉴权失败:无效 Key 返回 401(invalid_api_key),与聊天端点同一套错误格式。

示例 1:搜索#

curl "https://api.dflop.top/api/v1/ext/wiki/search?q=报销流程&limit=10" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

参数	默认	说明
`q`	(必填)	搜索关键词,中文可直接传
`kb_id`	`default`	知识库 id
`limit`	20	本页条数,上限 50
`offset`	0	翻页偏移

响应:

{
  "query": "报销流程",
  "total_hits": 37,
  "offset": 0,
  "returned": 10,
  "has_more": true,
  "results": [
    {
      "id": "expense-reimbursement",
      "title": "差旅报销流程",
      "summary": "员工差旅费用的申请、审批与打款流程…",
      "snippet": "员工差旅费用的申请、审批与打款流程…",
      "tags": ["财务", "流程"],
      "confidence": "high",
      "needs_review": false,
      "score": 12.4
    }
  ]
}

total_hits 是库内真实总命中数(与本页返回数无关),配合 offset / has_more 翻页可拿全量。

示例 2:读页#

curl "https://api.dflop.top/api/v1/ext/wiki/pages/expense-reimbursement" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

响应(节选):

{
  "id": "expense-reimbursement",
  "kb_id": "default",
  "title": "差旅报销流程",
  "summary": "…",
  "tags": ["财务", "流程"],
  "aliases": [],
  "links": ["approval-chain"],
  "body": "完整 Markdown 正文…",
  "confidence": "high",
  "needs_review": false,
  "source": {
    "r2_key": "…",
    "filename": "财务制度2026.pdf",
    "locator": "第 12-14 页",
    "compiled_at": "2026-06-01T08:00:00Z",
    "model": "gpt-5.5"
  },
  "outgoing_links": [{ "id": "approval-chain", "resolved": true, "title": "审批链" }]
}

单页 /pages/{id} 返回完整正文;批量 /pages?ids=a,b,c 每页正文截断到 4000 字符(body_truncated: true 标记),空 ids 返回 400。
/pages/{id}/source 返回 {r2_key, filename, locator, url, url_ttl_secs},其中 url 是源文档的预签名下载链接,1 小时过期(url_ttl_secs: 3600)。

MCP 接入#

https://api.dflop.top/mcp 是一个 Streamable HTTP 的 MCP server(无状态 + JSON 响应模式),暴露 6 个只读工具:

工具	参数	用途
`search_wiki`	`q`, `limit?`(默认 10,最大 50), `offset?`	词法搜索,返回轻量条目(不含正文)
`read_page`	`id`	读单页完整内容(正文上限 8000 字符)
`read_pages`	`ids[]`(最多 25 个)	批量读页(每页正文节选 1200 字符),适合全量枚举
`list_by_tag`	`tag`	按标签浏览
`backlinks`	`id`	反向链接,发现相关页
`get_source`	`id`	溯源到原始文件(临时链接 1 小时过期)

与 REST 不同,MCP 工具不接受 kb_id 参数 —— 检索范围恒为"这把 Key 用户的全部可读知识"(个人 + 全部有权限的团队知识库)。

Claude Code#

claude mcp add --transport http gpushare-wiki https://api.dflop.top/mcp \
  --header "Authorization: Bearer sk-gpushare-xxx"

之后在对话里直接问"在知识库里查一下报销流程",Claude 会自动调 search_wiki → read_page。

Codex / Cursor 等通用配置#

支持远程 MCP server 的客户端只需两项:URL + 鉴权 header。以 JSON 配置(Cursor 的 mcp.json 等)为例:

{
  "mcpServers": {
    "gpushare-wiki": {
      "url": "https://api.dflop.top/mcp",
      "headers": {
        "Authorization": "Bearer sk-gpushare-xxx"
      }
    }
  }
}

Codex(config.toml)等用其它格式的客户端,按各自的远程 MCP server 语法填同样的 URL 与 header 即可。Authorization: Bearer 也可换成 x-api-key: sk-gpushare-xxx。

注意事项#

只读:全部端点与工具都是检索,不能通过 API 创建 / 修改 / 删除知识页。上传文档、构建知识库在 model.dflop.top/wiki 的 Web 界面完成。
owner 范围:所有结果限定在 Key 所属账号可读的知识库内;拿别人的页面 id 来查只会得到 404。
必须直连 api.dflop.top:MCP 走 POST,不能经过任何只缓存 GET 的边缘代理;REST 虽是 GET,也建议直连以拿到实时数据。
临时链接会过期:get_source / pages/{id}/source 返回的源文档下载链接 1 小时失效,需要长期引用请下载转存。
批量上限:批量读页一次最多 25 个 id,超出部分被静默丢弃;搜索单页最多 50 条,更多结果用 offset 翻页。