Spaces

可创建 知识库（kind=knowledge）或 任务文献库（kind=task_literature），并查询列表与详情。

通用鉴权与 Base URL 见 HTTP API 总览。

创建空间

两种类型都走同一接口，用请求/响应里的 kind 区分知识库与任务文献库。

POST /v1/knowledge-bases

创建成功后会自动生成概览页 overview.md 与日志页 log.md（不计为「上传文件数」）。

请求体

字段	类型	必填	说明
`name`	string	是	显示名称
`description`	string \| null	否	描述
`kind`	string	否	`knowledge`（默认）或 `task_literature`
`external_task_id`	string \| null	否	论文任务幂等键；传入则创建/复用任务文献库（`kind` 视为 `task_literature`）

示例：创建知识库

POST /v1/knowledge-bases
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "机器学习资料",
  "description": "跨课题复用",
  "kind": "knowledge"
}

示例：创建任务文献库（普通）

POST /v1/knowledge-bases
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "论文任务-XXX",
  "kind": "task_literature"
}

示例：论文任务幂等建库（推荐对接）

同一用户 + 同一 external_task_id 可重复调用：新建 201，已存在 200（返回原库，并可更新 name/description）。

POST /v1/knowledge-bases
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "论文任务-大模型评测",
  "external_task_id": "lp_task_abc123",
  "description": "可选"
}

（兼容旧路径：POST /v1/integrations/paper/task-libraries，响应多包一层 { created, knowledge_base }。）

成功响应

新建 201，幂等复用 200。返回空间对象（节选）：

字段	说明
`id`	空间 UUID（上传、列文档时要用）
`name` / `slug` / `description`	名称与标识
`kind`	`knowledge` 或 `task_literature`
`source_count`	用户上传文件数（不含 `/wiki/` 下结构页与 `.keep`）
`wiki_page_count`	编译文稿 / 知识页面数（不含 overview、log、index）
`storage_bytes`	占用空间（字节）
`max_storage_bytes`	本空间容量上限（字节）；按 `kind` 取全局配置，`0` = 不限制
`created_at` / `updated_at`	时间

默认：知识库 10 GiB、任务文献库 1 GiB（可在设置页「空间容量」查看；具体上限以账号方案为准）。

列出空间

GET /v1/knowledge-bases
Authorization: Bearer <token>

成功：200，空间对象数组（含知识库与任务文献库；用 kind 区分）。字段与「创建空间 · 成功响应」相同。

查看单个空间

GET /v1/knowledge-bases/{kb_id}
Authorization: Bearer <token>

成功：200，单个空间对象（含 source_count / wiki_page_count / storage_bytes / max_storage_bytes）。
失败：404。

查看用量

GET /v1/knowledge-bases/{kb_id}/usage
Authorization: Bearer <token>

成功：200

字段	说明
`total_pages`	已计入 OCR 的页数
`document_count`	文档数（不含 `.keep`）
`max_pages`	页数上限
`total_storage_bytes`	占用空间（字节）
`max_storage_bytes`	容量上限（字节）；`0` = 不限制

{
  "total_pages": 12,
  "document_count": 5,
  "max_pages": 1000,
  "total_storage_bytes": 15728640,
  "max_storage_bytes": 1073741824
}

超出空间容量时，上传返回 413。

更新空间

PATCH /v1/knowledge-bases/{kb_id}
Authorization: Bearer <token>
Content-Type: application/json

{ "name": "新名称" }

可更新 name / description / kind（至少一项）。
成功：200，更新后的空间对象。