---
title: "知识库 API：文档导入与索引"
description: "Halo HTTP API 知识库接口：创建和删除知识库、绑定到工作区或数字人、导入文档并查看索引进度。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/knowledge-base.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：知识库

Halo HTTP API 知识库接口：创建和删除知识库、绑定到工作区或数字人、导入文档并查看索引进度。

知识库是供 Halo 检索的文档集合（API 路径里写作 `tlon`）。用这些接口创建和删除知识库、绑定到工作区或数字人、导入和移除文档，并查看索引进度。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [列出所有知识库](#get-api-tlon) | `GET /api/tlon` |
| [创建知识库](#post-api-tlon) | `POST /api/tlon` |
| [按 ID 获取一个知识库](#get-api-tlon-kbid) | `GET /api/tlon/:kbId` |
| [重命名知识库或修改它的描述和状态](#put-api-tlon-kbid) | `PUT /api/tlon/:kbId` |
| [删除知识库及其全部数据](#delete-api-tlon-kbid) （不可撤销） | `DELETE /api/tlon/:kbId` |
| [绑定知识库，让数字人可以读取](#post-api-tlon-kbid-bind-app) | `POST /api/tlon/:kbId/bind-app` |
| [把知识库绑定到工作区](#post-api-tlon-kbid-bind-space) | `POST /api/tlon/:kbId/bind-space` |
| [清除已提取的文本，从头重建知识库索引](#post-api-tlon-kbid-clear-relearn) | `POST /api/tlon/:kbId/clear-relearn` |
| [按绝对路径把运行 Halo 的电脑上的文件加入知识库](#post-api-tlon-kbid-files) | `POST /api/tlon/:kbId/files` |
| [读取知识库的文档地图（index.md）](#get-api-tlon-kbid-index) | `GET /api/tlon/:kbId/index` |
| [开始为知识库的文档建立索引（立即返回）](#post-api-tlon-kbid-ingest) | `POST /api/tlon/:kbId/ingest` |
| [获取知识库当前的索引进度](#get-api-tlon-kbid-ingest-status) | `GET /api/tlon/:kbId/ingest-status` |
| [把运行 Halo 的电脑上的文件夹关联为实时文档来源](#post-api-tlon-kbid-linked-dirs) | `POST /api/tlon/:kbId/linked-dirs` |
| [停止关注一个关联文件夹](#delete-api-tlon-kbid-linked-dirs-linkid) | `DELETE /api/tlon/:kbId/linked-dirs/:linkId` |
| [重新查找不可用的关联文件夹，找到后恢复关注](#post-api-tlon-kbid-linked-dirs-linkid-retry) | `POST /api/tlon/:kbId/linked-dirs/:linkId/retry` |
| [列出加入知识库的原始文件](#get-api-tlon-kbid-raw) | `GET /api/tlon/:kbId/raw` |
| [从知识库中移除一个文档（原始文件）](#post-api-tlon-kbid-remove-raw) （不可撤销） | `POST /api/tlon/:kbId/remove-raw` |
| [把从知识库读到的路径映射回原始文档](#post-api-tlon-kbid-resolve-sources) | `POST /api/tlon/:kbId/resolve-sources` |
| [解除知识库与数字人的绑定](#post-api-tlon-kbid-unbind-app) | `POST /api/tlon/:kbId/unbind-app` |
| [解除知识库与工作区的绑定](#post-api-tlon-kbid-unbind-space) | `POST /api/tlon/:kbId/unbind-space` |
| [列出绑定到某个工作区的知识库（或默认知识库）](#get-api-tlon-for-space-spaceid) | `GET /api/tlon/for-space/:spaceId` |
| [设置（或清除）新会话自动加载的知识库](#post-api-tlon-set-default) | `POST /api/tlon/set-default` |

## 列出所有知识库 {#get-api-tlon}

`GET /api/tlon` （助手可调用）

**响应**

```ts
{success:true,data:[{id,name,icon,description,status,spaceIds,appIds,stats,isDefault?,...}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 创建知识库 {#post-api-tlon}

`POST /api/tlon` （助手可调用）

- Optional fields: icon, description, linkedDirs (array of {path,label}).

**请求体**

```json
{
  "name": "Product Docs"
}
```

**响应**

```ts
{success:true,data:{id,name,icon,description,status:"active",createdAt,updatedAt,path,linkedDirs:[],spaceIds:[],appIds:[],stats:{...}}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Product Docs"}'
```

## 按 ID 获取一个知识库 {#get-api-tlon-kbid}

`GET /api/tlon/:kbId` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:{id,name,icon,description,status,linkedDirs,spaceIds,appIds,stats,...}} or {success:false,error:"Knowledge base not found"}
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon/<kbId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 重命名知识库或修改它的描述和状态 {#put-api-tlon-kbid}

`PUT /api/tlon/:kbId` （可撤销） （助手可调用）

- All fields optional: name, icon, description, status ("active"|"paused"|"error").

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "name": "New name"
}
```

**响应**

```ts
{success:true,data:<updated entry>} or {success:false,error:"Knowledge base not found"}
```

**示例**

```bash
curl -sX PUT "$HALO_URL/api/tlon/<kbId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New name"}'
```

## 删除知识库及其全部数据 {#delete-api-tlon-kbid}

`DELETE /api/tlon/:kbId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
只想做范围更小的操作时，改用 [`POST /api/tlon/:kbId/remove-raw`](#post-api-tlon-kbid-remove-raw)
:::

- Permanently deletes the collection's entire folder — original source files, extracted text, and the index. Not just the registry entry. If the user only meant to remove one document, use remove-raw instead.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:<deletion result>}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/tlon/<kbId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 绑定知识库，让数字人可以读取 {#post-api-tlon-kbid-bind-app}

`POST /api/tlon/:kbId/bind-app` （可撤销） （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>"
}
```

**响应**

```ts
{success:true,data:<updated entry>}
```

**错误**

- 400 if appId is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/bind-app" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>"}'
```

## 把知识库绑定到工作区 {#post-api-tlon-kbid-bind-space}

`POST /api/tlon/:kbId/bind-space` （可撤销） （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "spaceId": "<spaceId — a uuid from GET /api/spaces>"
}
```

**响应**

```ts
{success:true,data:<updated entry>}
```

**错误**

- 400 if spaceId is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/bind-space" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId — a uuid from GET /api/spaces>"}'
```

## 清除已提取的文本，从头重建知识库索引 {#post-api-tlon-kbid-clear-relearn}

`POST /api/tlon/:kbId/clear-relearn` （可撤销） （助手可调用）

- Use when documents were updated in place and stale extracted text needs replacing. Only clears derived/regeneratable data (extracted text, index) — original source files are untouched and text is rebuilt automatically.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:true} or {success:false,error:"Learning is already in progress"}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/clear-relearn" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 按绝对路径把运行 Halo 的电脑上的文件加入知识库 {#post-api-tlon-kbid-files}

`POST /api/tlon/:kbId/files` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "filePaths": [
    "/absolute/path/to/file.pdf"
  ]
}
```

**响应**

```ts
{success:true,data:{added:string[],rejected:string[]}}
```

**错误**

- 400 if filePaths is missing or empty. Files are copied in, not linked — see linked-dirs for live-watched folders.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/files" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filePaths":["/absolute/path/to/file.pdf"]}'
```

## 读取知识库的文档地图（index.md） {#get-api-tlon-kbid-index}

`GET /api/tlon/:kbId/index` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:string}  — markdown text, empty string if not yet generated
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon/<kbId>/index" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 开始为知识库的文档建立索引（立即返回） {#post-api-tlon-kbid-ingest}

`POST /api/tlon/:kbId/ingest` （助手可调用）

- Returns immediately; the indexing job runs in the background. Poll [`GET /api/tlon/:kbId/ingest-status`](#get-api-tlon-kbid-ingest-status) for progress — back off (2s, then double), do not tight-loop.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:true}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/ingest" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 获取知识库当前的索引进度 {#get-api-tlon-kbid-ingest-status}

`GET /api/tlon/:kbId/ingest-status` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:{kbId,total,completed,current?,phase:"idle"|"running"|"done"|"error",error?,errors?:[{file,message}]}}
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon/<kbId>/ingest-status" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 把运行 Halo 的电脑上的文件夹关联为实时文档来源 {#post-api-tlon-kbid-linked-dirs}

`POST /api/tlon/:kbId/linked-dirs` （助手可调用）

- Optional field: label (defaults to path).
- Failure carries a code instead of throwing: TOO_MANY_FILES (data:{count,limit}), DISK_ROOT (cannot watch a filesystem root), FOLDER_TOO_LARGE, PATH_NOT_FOUND, KB_NOT_FOUND.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "path": "/Users/me/Documents/product-docs"
}
```

**响应**

```ts
{success:true,data:{id,path,label,watching,lastScannedAt?}} on success
```

**错误**

- 400 if path is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/linked-dirs" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/Users/me/Documents/product-docs"}'
```

## 停止关注一个关联文件夹 {#delete-api-tlon-kbid-linked-dirs-linkid}

`DELETE /api/tlon/:kbId/linked-dirs/:linkId` （可撤销） （助手可调用）

- Only removes the watch registration — the target folder and its files are untouched, and can be re-linked.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |
| `linkId` | 知识库关联文件夹的 ID。 |

**响应**

```ts
{success:true,data:<removal result>}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/tlon/<kbId>/linked-dirs/<linkId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 重新查找不可用的关联文件夹，找到后恢复关注 {#post-api-tlon-kbid-linked-dirs-linkid-retry}

`POST /api/tlon/:kbId/linked-dirs/:linkId/retry` （可撤销） （助手可调用）

- A link shows watching:false when its folder was missing at the last check (e.g. an unplugged drive). Halo looks again at every start; this asks now.
- Failure carries a code: PATH_NOT_FOUND (the folder is still missing), LINK_NOT_FOUND, KB_NOT_FOUND.
- learningPaused ({reason:"too-many-files",count,limit} or {reason:"too-large"}) on a link means the folder is there but over the watched-folder limits, so its files are not learned.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |
| `linkId` | 知识库关联文件夹的 ID。 |

**响应**

```ts
{success:true,data:{id,path,label,watching:true,lastScannedAt?,learningPaused?}} when the folder is there
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/linked-dirs/<linkId>/retry" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出加入知识库的原始文件 {#get-api-tlon-kbid-raw}

`GET /api/tlon/:kbId/raw` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**响应**

```ts
{success:true,data:[{name,path,size,learned:boolean,state:"learned"|"pending"|"no-text"|"failed",error?,source:"raw"|"linked",dirLabel?}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon/<kbId>/raw" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 从知识库中移除一个文档（原始文件） {#post-api-tlon-kbid-remove-raw}

`POST /api/tlon/:kbId/remove-raw` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "relativePath": "raw/file.pdf"
}
```

**响应**

```ts
{success:true,data:<removal result>}
```

**错误**

- 400 if relativePath is missing. Permanently deletes the copied file from the collection — no trash, no undo.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/remove-raw" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"relativePath":"raw/file.pdf"}'
```

## 把从知识库读到的路径映射回原始文档 {#post-api-tlon-kbid-resolve-sources}

`POST /api/tlon/:kbId/resolve-sources` （助手可调用）

- Maps paths read from a knowledge base back to the original documents, deduplicated and absolute. Paths that no longer exist are dropped, so a shorter list than the one sent is normal.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "readPaths": [
    "/absolute/path/inside/the/collection"
  ]
}
```

**响应**

```ts
{success:true,data:[{name:string,path:string}]}  — deduped, absolute, files that still exist
```

**错误**

- 400 when `readPaths` is not an array; an empty array returns nothing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/resolve-sources" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"readPaths":["/absolute/path/inside/the/collection"]}'
```

## 解除知识库与数字人的绑定 {#post-api-tlon-kbid-unbind-app}

`POST /api/tlon/:kbId/unbind-app` （可撤销） （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>"
}
```

**响应**

```ts
{success:true,data:<updated entry>}
```

**错误**

- 400 if appId is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/unbind-app" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>"}'
```

## 解除知识库与工作区的绑定 {#post-api-tlon-kbid-unbind-space}

`POST /api/tlon/:kbId/unbind-space` （可撤销） （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `kbId` | 知识库 ID，来自 [`GET /api/tlon`](#get-api-tlon)。 |

**请求体**

```json
{
  "spaceId": "<spaceId — a uuid from GET /api/spaces>"
}
```

**响应**

```ts
{success:true,data:<updated entry>}
```

**错误**

- 400 if spaceId is missing.

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/<kbId>/unbind-space" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId — a uuid from GET /api/spaces>"}'
```

## 列出绑定到某个工作区的知识库（或默认知识库） {#get-api-tlon-for-space-spaceid}

`GET /api/tlon/for-space/:spaceId` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |

**响应**

```ts
{success:true,data:[{id,name,icon,description,status,...}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/tlon/for-space/<spaceId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 设置（或清除）新会话自动加载的知识库 {#post-api-tlon-set-default}

`POST /api/tlon/set-default` （可撤销） （助手可调用）

- kbId can be null to clear the default.

**请求体**

```json
{
  "kbId": "<kbId — a uuid from GET /api/tlon>"
}
```

**响应**

```ts
{success:true,data:<updated entry or null>}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/tlon/set-default" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kbId":"<kbId — a uuid from GET /api/tlon>"}'
```