# 知识库 API & MCP

> 在 zhonkemodel.dflop.top/wiki 构建知识库,用同一把 API Key 通过 8 条只读 REST 端点或 /mcp MCP server 在自己的工具里检索

来源：https://zhonkemodel.dflop.top/docs/reference/wiki-api

在 [zhonkemodel.dflop.top/wiki](https://zhonkezhonkemodel.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 —— 与聊天端点共用,鉴权方式见 [鉴权](./authentication.md)。结果**仅限这把 Key 所属账号**可读的知识库(个人知识库 + 有权限的团队知识库)。

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

---

## REST 端点

全部为 `GET`,挂在 `https://zhonkezhonkeapi.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`),与聊天端点同一套 [错误格式](./errors.md)。

### 示例 1:搜索

```bash
curl "https://zhonkezhonkeapi.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 | 翻页偏移 |

响应:

```json
{
  "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:读页

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

响应(节选):

```json
{
  "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://zhonkezhonkeapi.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

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

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

### Codex / Cursor 等通用配置

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

```json
{
  "mcpServers": {
    "gpushare-wiki": {
      "url": "https://zhonkezhonkeapi.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 创建 / 修改 / 删除知识页。上传文档、构建知识库在 [zhonkemodel.dflop.top/wiki](https://zhonkezhonkemodel.dflop.top/wiki) 的 Web 界面完成。
- **owner 范围**:所有结果限定在 Key 所属账号可读的知识库内;拿别人的页面 id 来查只会得到 `404`。
- **必须直连 `zhonkeapi.dflop.top`**:MCP 走 POST,不能经过任何只缓存 GET 的边缘代理;REST 虽是 GET,也建议直连以拿到实时数据。
- **临时链接会过期**:`get_source` / `pages/{id}/source` 返回的源文档下载链接 1 小时失效,需要长期引用请下载转存。
- **批量上限**:批量读页一次最多 25 个 id,超出部分被静默丢弃;搜索单页最多 50 条,更多结果用 `offset` 翻页。