API：知识库

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

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

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 $HALO_URL 和 $HALO_TOKEN 按快速上手设置；地址、鉴权和错误约定见 HTTP API 概览。

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

列出所有知识库

GET /api/tlon 助手可调用

响应

{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 助手可调用

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

请求体

json

{
  "name": "Product Docs"
}

响应

{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 助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

响应

{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 可撤销助手可调用

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

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

{
  "name": "New name"
}

响应

{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 不可撤销助手可调用

不可撤销

执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。只想做范围更小的操作时，改用 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`。

响应

{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 可撤销助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 可撤销助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 可撤销助手可调用

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`。

响应

{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 助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

响应

{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 助手可调用

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

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

响应

{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 助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

响应

{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 助手可调用

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`。

请求体

json

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

响应

{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 可撤销助手可调用

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

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。
`linkId`	知识库关联文件夹的 ID。

响应

{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 可撤销助手可调用

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`。
`linkId`	知识库关联文件夹的 ID。

响应

{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 助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

响应

{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 不可撤销助手可调用

不可撤销

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

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 助手可调用

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`。

请求体

json

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

响应

{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 可撤销助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 可撤销助手可调用

路径参数

名称	说明
`kbId`	知识库 ID，来自 `GET /api/tlon`。

请求体

json

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

响应

{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 助手可调用

路径参数

名称	说明
`spaceId`	工作区 ID，来自 `GET /api/spaces`。Halo 工作区的 ID 固定为 `halo-temp`。

响应

{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 可撤销助手可调用

kbId can be null to clear the default.

请求体

json

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

响应

{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>"}'

API：知识库 ​

列出所有知识库 ​

创建知识库 ​

按 ID 获取一个知识库 ​

重命名知识库或修改它的描述和状态 ​

删除知识库及其全部数据 ​

绑定知识库，让数字人可以读取 ​

把知识库绑定到工作区 ​

清除已提取的文本，从头重建知识库索引 ​

按绝对路径把运行 Halo 的电脑上的文件加入知识库 ​

读取知识库的文档地图（index.md） ​

开始为知识库的文档建立索引（立即返回） ​

获取知识库当前的索引进度 ​

把运行 Halo 的电脑上的文件夹关联为实时文档来源 ​

停止关注一个关联文件夹 ​

重新查找不可用的关联文件夹，找到后恢复关注 ​

列出加入知识库的原始文件 ​

从知识库中移除一个文档（原始文件） ​

把从知识库读到的路径映射回原始文档 ​

解除知识库与数字人的绑定 ​

解除知识库与工作区的绑定 ​

列出绑定到某个工作区的知识库（或默认知识库） ​

设置（或清除）新会话自动加载的知识库 ​

API：知识库

列出所有知识库

创建知识库

按 ID 获取一个知识库

重命名知识库或修改它的描述和状态

删除知识库及其全部数据

绑定知识库，让数字人可以读取

把知识库绑定到工作区

清除已提取的文本，从头重建知识库索引

按绝对路径把运行 Halo 的电脑上的文件加入知识库

读取知识库的文档地图（index.md）

开始为知识库的文档建立索引（立即返回）

获取知识库当前的索引进度

把运行 Halo 的电脑上的文件夹关联为实时文档来源

停止关注一个关联文件夹

重新查找不可用的关联文件夹，找到后恢复关注

列出加入知识库的原始文件

从知识库中移除一个文档（原始文件）

把从知识库读到的路径映射回原始文档

解除知识库与数字人的绑定

解除知识库与工作区的绑定

列出绑定到某个工作区的知识库（或默认知识库）

设置（或清除）新会话自动加载的知识库