知识库 Wiki 与索引治理 API
知识库增强索引的管理与数据面:LLM Wiki(canonical 页面 / 不可变版本 / 编译冲突与提案 / 页面链接图谱 / 导出到 Memory / 重置)、GraphRAG 图谱浏览(node-link 图 / 社区报告 / 实体邻域),以及可插拔索引能力(graphrag / raptor / wiki)的配置、构建/修复操作与清理。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/knowledgebases。 - 项目级 Wiki 面(不带
{knowledgeBaseId}):/knowledgebases/wiki/overview|query|search——跨项目内可见知识库检索。 - 库级资源:知识库
{knowledgeBaseId}→ GraphRAG 图谱(graph、实体{entityId})、索引能力{capability}(graphrag/raptor/wiki)、索引操作{operationId}、Wiki 页面{slug}→ 版本{revisionId}/ 冲突 / 提案{proposalId}。 - 索引构建为异步操作:
POST index-operations与clear/reset返回202+ 操作对象,轮询GET index-operations/{operationId}至终态。
认证与权限
认证与请求头约定见 通用约定。本域 scope:knowledgebases.read(overview/query/search、图谱浏览、能力与操作读取、Wiki 页面/版本/冲突/提案读取、recommended-limits)、knowledgebases.write(能力配置与清理、操作创建与取消、Wiki 页面写/删/恢复/导出、冲突解决、提案接受、reset)。Wiki/GraphRAG 构建与检索经 LLM Gateway 执行;export-to-memory 另要求当前项目已启用并激活 AppBase Memory(见 memory)。
端点清单
| 方法 + 路径 | 用途 | ||
|---|---|---|---|
GET /knowledgebases/wiki/overview | 项目级 Wiki 状态卡片(按权限过滤) | ||
POST /knowledgebases/wiki/query | 跨显式选定知识库查询 Wiki 索引 | ||
POST /knowledgebases/wiki/search | 跨全部可见知识库检索 Wiki 索引 | ||
GET /knowledgebases/{knowledgeBaseId}/graph | 浏览活跃 GraphRAG node-link 图 | ||
GET .../graph/community-reports | 活跃 GraphRAG 社区报告列表 | ||
GET .../graph/entities/{entityId}/neighbors | 展开实体邻域 | ||
GET /knowledgebases/{knowledgeBaseId}/index-capabilities | 列出索引能力与状态 | ||
PATCH .../index-capabilities/{capability} | 配置一个索引能力 | ||
POST .../index-capabilities/{capability}/clear | 排队清理能力的派生索引 | ||
| `GET\ | POST /knowledgebases/{knowledgeBaseId}/index-operations` | 索引操作列表/发起构建或修复 | |
GET .../index-operations/{operationId} | 索引操作详情 | ||
POST .../index-operations/{operationId}/cancel | 请求取消索引操作 | ||
GET /knowledgebases/{knowledgeBaseId}/wiki/pages | Wiki 页面列表 | ||
POST .../wiki/pages | 创建人工持有的 Wiki 页面 | ||
| `GET\ | PATCH\ | DELETE .../wiki/pages/{slug}` | Wiki 页面读/CAS 更新/删除 |
GET .../wiki/pages/{slug}/revisions | 页面版本列表 | ||
GET .../wiki/pages/{slug}/revisions/{revisionId} | 单个版本详情 | ||
POST .../wiki/pages/{slug}/restore | 恢复历史版本(新 CAS 版本) | ||
POST .../wiki/pages/{slug}/export-to-memory | 导出页面到 Memory 服务 | ||
GET .../wiki/conflicts | 未解决编译冲突页面列表 | ||
GET .../wiki/conflicts/{slug}/proposal | 冲突页最新编译提案 | ||
POST .../wiki/conflicts/{slug}/resolve | 解决冲突(CAS) | ||
GET .../wiki/proposals | 冲突页最新编译提案列表 | ||
POST .../wiki/proposals/{proposalId}/accept | 接受整条编译提案(CAS) | ||
GET .../wiki/graph | canonical Wiki 页面链接图谱(含红链) | ||
GET .../wiki/recommended-limits | 推荐 Wiki 编译上限 | ||
POST .../wiki/reset | 删除整个 canonical Wiki 并排队清理编译索引 |
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
- 认证:所有请求携带
X-Appwrite-Project: <YOUR_PROJECT_ID>与X-Appwrite-Key: <YOUR_API_KEY>。 - Wiki 页面写操作(更新/删除/恢复/冲突解决/提案接受)一律带
contentRevision做乐观并发(CAS):与当前版本不一致即被拒。 - 示例中的资源 ID(
kb_product_docs、refund-policy、ent_0123、op_0001、rev_0007)请替换为实际值。
公共响应模型
以下模型在多个端点复用,此处给出完整字段表;各端点「输出」只列关键字段并指回本节。
**Models.KnowledgeBaseWikiPage**(Wiki 页面):
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | Wiki 页面 ID。 |
$createdAt* / $updatedAt* | string | 创建/最近更新时间(ISO 8601)。 |
knowledgeBaseId* | string | 所属知识库 ID。 |
slug* | string | 库内唯一 Wiki slug。 |
title* | string | 页面标题。 |
pageType* | string | 页面类型:entity / topic / survey / agent_practice / category_index。 |
contentMd* | string | canonical Markdown 内容。 |
summary | string | 页面摘要。 |
status* | string | 页面状态:draft / published / conflict / archived。 |
pendingConflicts* | object | 结构化的未解决冲突元数据。 |
conflicts* | object[] | 面向调用方的冲突明细(见下方 KnowledgeBaseWikiConflict)。 |
sourceChunks* / sourceGraph* / sourceMemory* | object | chunk / 图谱 / Memory 三类来源溯源。 |
compiledBy | string | 编译器标识;人工持有页面为 null。 |
pinned* | boolean | 是否人工置顶。 |
viewCount* | integer | 页面浏览计数。 |
contentRevision* | integer | 写操作要求的 CAS 版本号。 |
embeddingModel | string | 当前投影使用的模型。 |
projectionResultGeneration | string | 包含该页面版本的派生结果代。 |
embeddingUpdatedAt | string | 投影发布时间。 |
links* | object | 出链,含未解析的红链。 |
backlinks* | object | 其他 Wiki 页面的入链。 |
aliases* | object | 指向本页的别名。 |
conflictEvidence* | object | 冲突内容引用的水合证据。 |
divergenceRecommendations* | object | 分歧内容选项的推荐。 |
conflictBlocks* | object | 供渲染的冲突块。 |
internalContradictions* / ruleBasedContradictions* | object | 规则检测的矛盾。 |
generalKnowledgeConflicts* | object | 与通用知识的冲突。 |
**Models.KnowledgeBaseWikiConflict**(conflicts[] 元素):
| 字段 | 类型 | 说明 |
|---|---|---|
id* | string | 稳定的冲突 ID。 |
type* | string | 冲突检测器分类。 |
reason* | string | 冲突的人读原因。 |
claim | string | 被评估的论断(如有)。 |
conflictingContents* | string[] | 互相竞争的原句。 |
sources* | object[] | 竞争语句归属的源文档/切片(见下)。 |
readOnly* | boolean | 该冲突是否必须手工合并内容。 |
confidence | number | 检测器置信度(如有)。 |
scope | string | 冲突范围(如有)。 |
recommendedOptionIndex | integer | 推荐选项下标;无安全推荐时为 null。 |
**KnowledgeBaseWikiConflictSource**(sources[] 元素):documentId(源文档 ID)、documentName(展示名)、documentTag(调用方自定义定位标签,来自 metadata.documentTag)、chunkId、conflictingContent(归属该源的冲突原句)、context(有界上下文摘录)、locator(object,页/节等位置元数据)。
**Models.KnowledgeBaseWikiRevision**(不可变版本/提案):
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 版本 ID。 |
$createdAt* | string | 版本创建时间。 |
knowledgeBaseId* | string | 知识库 ID。 |
pageId* | string | Wiki 页面 ID。 |
pageSlug / pageTitle | string | 页面 slug / 标题(提案列表返回时携带)。 |
actorId | string | 创建该版本的主体。 |
revisionType* | string | 版本类型。 |
titleBefore / titleAfter | string | 前/后标题。 |
contentBefore / contentAfter | string | 前/后 Markdown。 |
reason | string | 版本原因。 |
**Models.KnowledgeBaseIndexOperation**(索引操作):
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 操作 ID。 |
$createdAt* / $updatedAt* | string | 创建/最近更新时间。 |
knowledgeBaseId* | string | 知识库 ID。 |
capability* | string | 能力标识:graphrag / raptor / wiki。 |
kind* | string | 操作种类(如 build / repair)。 |
scope* | string | 操作范围(knowledgebase / document)。 |
documentIds* | string[] | document 范围操作的文档 ID。 |
status* | string | 生命周期状态:queued / running / succeeded / failed / cancelling / cancelled / clearing / cleared。 |
stage | string | 当前处理阶段。 |
progress* | integer | 完成百分比。 |
message | string | 当前脱敏状态消息。 |
effectiveConfig* | object | 冻结的生效配置。 |
configHash* / sourceHash* | string | 生效配置 / 冻结源快照哈希。 |
resultGeneration | string | 暂存结果代。 |
resultVersion | string | 索引器实现版本。 |
retryOf | string | 本操作为重试时的原操作 ID。 |
stats* | object | 操作统计。 |
error* | object | 脱敏操作错误。 |
logTail | string | 有界脱敏日志尾部。 |
startedAt / heartbeatAt / finishedAt | string | 处理开始 / 最近 worker 心跳 / 终态完成时间。 |
**Models.KnowledgeBaseIndexCapability**(索引能力状态):capability*(string)、available*(boolean,部署是否提供该能力)、configured*(boolean,是否已保存配置)、enabled*(boolean)、state*(string,当前状态)、activeResultGeneration(string,活跃不可变结果代)、sourceHash / configHash(string)、resultVersion(string)、lastOperationId(string)、staleReason(string,可空,结果代过期原因)、stats*(object)、error*(object,脱敏最近错误)、config*(object,已保存配置)、limits*(object,服务端强制上限)。
**Models.KnowledgeBaseWikiMutation**(删除/重置结果):pagesDeleted*、linksDeleted*、linksNulled*(入链转红链数)、revisionsDeleted*、aliasesDeleted*(均为 integer)、clearOperationId(string,排队中的 Wiki 索引清理操作,如适用)。
项目级 Wiki 概览与检索
GET /v1/knowledgebases/wiki/overview
SDK:KnowledgeBases.getWikiOverview · scope:knowledgebases.read
返回当前项目按权限过滤的 Wiki 状态卡片:只汇总可见知识库,并把部署可用性、已保存的启用状态、索引状态、页面计数与冲突计数区分开。
输入:无 path/query/body 参数。
输出:
200,返回模型 Models.KnowledgeBaseWikiOverview。
| 字段 | 类型 | 说明 |
|---|---|---|
cards* | object | 按权限过滤的逐知识库 Wiki 状态卡片(泛化对象,卡片字段以实际返回为准)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/wiki/overview" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例(cards 为泛化对象,示意——字段以实际返回为准):
{
"cards": []
}POST /v1/knowledgebases/wiki/query
SDK:KnowledgeBases.createWikiQuery · scope:knowledgebases.read
跨显式选定的可见知识库查询 Wiki 索引:可指定路由档位(mode)或留 auto,并用 linkOptions 做有界链接扩展。不可访问的知识库不会暴露;能力故障在 degradedKnowledgeBases 中报告。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseIds | body | string[] | 是 | 1–20 个 | 要查询的知识库 ID。 |
query | body | string | 是 | Wiki 查询文本。 | |
mode | body | string | 否 | 枚举:auto / wiki_direct / wiki_retrieved / rag_first | Wiki 路由档位覆盖。 |
topK | body | integer | 否 | 每个知识库返回的结果数。 | |
useVector | body | boolean | 否 | 是否包含向量召回。 | |
vectorWeight | body | number | 否 | RRF 前的向量权重。 | |
linkOptions | body | object | 否 | 有界 Wiki 链接扩展选项(泛化对象)。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiProjectSearch。
| 字段 | 类型 | 说明 |
|---|---|---|
results* | object | 按知识库分组、按权限过滤的 Wiki 结果(泛化对象,结果字段以实际返回为准)。 |
degradedKnowledgeBases* | object | Wiki 不可用或未就绪的可见知识库(泛化对象)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/wiki/query" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseIds": ["kb_product_docs"],
"query": "退款政策是什么?",
"mode": "auto",
"topK": 5,
"useVector": true,
"vectorWeight": 0.7
}'响应示例(results / degradedKnowledgeBases 为泛化对象,示意——字段以实际返回为准):
{
"results": [],
"degradedKnowledgeBases": []
}POST /v1/knowledgebases/wiki/search
SDK:KnowledgeBases.createWikiProjectSearch · scope:knowledgebases.read
跨项目内全部可见知识库检索 Wiki 索引:返回排序且按版本围栏(revision-fenced)的结果与显式的降级知识库。需要显式选择知识库时改用 createWikiQuery。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | Wiki 查询文本。 | |
mode | body | string | 否 | 枚举:auto / wiki_direct / wiki_retrieved / rag_first | Wiki 路由档位覆盖。 |
topK | body | integer | 否 | 每个知识库返回的结果数。 | |
useVector | body | boolean | 否 | 是否包含向量召回。 | |
vectorWeight | body | number | 否 | RRF 前的向量权重。 | |
linkOptions | body | object | 否 | 有界 Wiki 链接扩展选项(泛化对象)。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiProjectSearch(字段同上:results*、degradedKnowledgeBases*)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/wiki/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "退款政策是什么?",
"mode": "auto",
"topK": 5
}'响应示例(泛化对象,示意——字段以实际返回为准):
{
"results": [],
"degradedKnowledgeBases": []
}GraphRAG 图谱
GET /v1/knowledgebases/{knowledgeBaseId}/graph
SDK:KnowledgeBases.getGraph · scope:knowledgebases.read
浏览活跃 GraphRAG 结果代的有界快照:可按文本/类型/社区过滤实体,或给 seed + hops 做有界图探索。hasMore=true 时跟随 nextCursor 翻页;truncated=true 表示响应只是图的有界子集。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
query | query | string | 否 | 默认 "" | 实体文本过滤。 |
type | query | string | 否 | 默认 "" | 实体类型过滤。 |
community | query | string | 否 | 默认 "" | 社区过滤。 |
seed | query | string | 否 | 默认 "" | 有界 N 跳扩展的实体种子。 |
hops | query | integer | 否 | 默认 1 | 带 seed 时的邻域跳数。 |
limit | query | integer | 否 | 默认 100 | 最大返回节点数。 |
cursor | query | string | 否 | 默认 "" | 上一页返回的不透明游标。 |
输出:
200,返回模型 Models.KnowledgeBaseGraph。
| 字段 | 类型 | 说明 |
|---|---|---|
resultGeneration* | string | 活跃 GraphRAG 结果代。 |
graph* | object | 过滤后的 node-link 图快照({nodes, edges} 结构,字段以实际返回为准)。 |
totalNodes* | integer | 匹配当前过滤条件的节点总数。 |
hasMore* | boolean | 是否还有下一页。 |
nextCursor | string | 下一页的不透明游标。 |
truncated* | boolean | 返回图是否为有界子集。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph?query=退款&limit=100" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"resultGeneration": "gen_0007",
"graph": {
"nodes": [],
"edges": []
},
"totalNodes": 0,
"hasMore": false,
"nextCursor": "",
"truncated": false
}GET /v1/knowledgebases/{knowledgeBaseId}/graph/community-reports
SDK:KnowledgeBases.listGraphCommunityReports · scope:knowledgebases.read
列出活跃 GraphRAG 结果代的社区报告:每份含社区标识、标题、实体、权重与报告载荷。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
limit | query | integer | 否 | 默认 100 | 最大返回报告数。 |
offset | query | integer | 否 | 默认 0 | 跳过的报告数。 |
输出:
200,返回模型 Models.KnowledgeBaseGraphCommunityReportList。
| 字段 | 类型 | 说明 |
|---|---|---|
resultGeneration* | string | 活跃 GraphRAG 结果代。 |
reports* | object[] | 社区报告列表(元素为 Models.KnowledgeBaseGraphCommunityReport,子字段见下)。 |
id* | string | 社区报告记录 ID。 |
communityId* | string | 社区标识。 |
title* | string | 报告标题。 |
entities* | string[] | 报告覆盖的实体。 |
weight* | number | 报告权重。 |
content* | object | 结构化报告内容与证据(泛化对象)。 |
hasMore* | boolean | 是否还有更多报告。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph/community-reports?limit=100&offset=0" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"resultGeneration": "gen_0007",
"reports": [
{
"id": "cr_0001",
"communityId": "community_3",
"title": "退款与售后",
"entities": ["ent_0123"],
"weight": 0.82,
"content": {}
}
],
"hasMore": false
}GET /v1/knowledgebases/{knowledgeBaseId}/graph/entities/{entityId}/neighbors
SDK:KnowledgeBases.getGraphEntityNeighbors · scope:knowledgebases.read
在活跃 GraphRAG 结果代中展开单个实体的有界邻域。hops 只作用于图探索,不改变 GraphRAG 检索算法。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
entityId | path | string | 是 | 图实体 ID。 | |
hops | query | integer | 否 | 默认 1 | 邻域跳数。 |
limit | query | integer | 否 | 默认 100 | 最大返回节点数。 |
输出:
200,返回模型 Models.KnowledgeBaseGraphNeighbors。
| 字段 | 类型 | 说明 |
|---|---|---|
resultGeneration* | string | 活跃 GraphRAG 结果代。 |
nodes* | object | 从种子到达的节点(泛化对象)。 |
edges* | object | 由到达节点诱导的边(泛化对象)。 |
truncated* | boolean | 扩展是否触达请求上限。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph/entities/ent_0123/neighbors?hops=1&limit=100" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例(nodes / edges 为泛化对象,示意——字段以实际返回为准):
{
"resultGeneration": "gen_0007",
"nodes": [],
"edges": [],
"truncated": false
}索引能力(index-capabilities)
GET /v1/knowledgebases/{knowledgeBaseId}/index-capabilities
SDK:KnowledgeBases.listIndexCapabilities · scope:knowledgebases.read
列出 GraphRAG、RAPTOR 与 LLM Wiki 三个可插拔索引能力的部署可用性、已保存配置、生命周期状态、活跃结果代、上限、统计与脱敏错误。available、enabled、state 是三个独立信号:索引器临时不健康不会抹掉已保存配置或活跃结果代。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseIndexCapabilityList。
| 字段 | 类型 | 说明 |
|---|---|---|
capabilities* | object[] | 能力列表,元素为 Models.KnowledgeBaseIndexCapability(字段见「公共响应模型」)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-capabilities" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"capabilities": [
{
"capability": "wiki",
"available": true,
"configured": true,
"enabled": true,
"state": "ready",
"activeResultGeneration": "gen_0007",
"sourceHash": "sha256:…",
"configHash": "sha256:…",
"resultVersion": "1.0.0",
"lastOperationId": "op_0001",
"staleReason": null,
"stats": {},
"error": {},
"config": {
"enabled": true
},
"limits": {}
}
]
}PATCH /v1/knowledgebases/{knowledgeBaseId}/index-capabilities/{capability}
SDK:KnowledgeBases.updateIndexCapability · scope:knowledgebases.write
整体替换一个 graphrag / raptor / wiki 能力的已保存配置。对会调用 Chat LLM 的能力,先配置知识库的 indexingDefaults。启用部署不可用的能力返回 knowledge_index_capability_unavailable;禁用会保留既有结果代与历史。
三个能力都接受 config.language 控制生成语言:auto(默认,按源内容检测)/ zh / en / ja;显式值覆盖源语言检测。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
capability | path | string | 是 | 枚举:graphrag / raptor / wiki | 能力标识。 |
config | body | object | 是 | 完整能力配置(泛化对象;language 枚举 auto / zh / en / ja,默认 auto)。 |
输出:
200,返回模型 Models.KnowledgeBaseIndexCapability(字段见「公共响应模型」)。
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-capabilities/wiki" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"enabled": true,
"language": "auto"
}
}'响应示例:
{
"capability": "wiki",
"available": true,
"configured": true,
"enabled": true,
"state": "ready",
"activeResultGeneration": "gen_0007",
"sourceHash": "sha256:…",
"configHash": "sha256:…",
"resultVersion": "1.0.0",
"lastOperationId": "op_0001",
"staleReason": null,
"stats": {},
"error": {},
"config": {
"enabled": true,
"language": "auto"
},
"limits": {}
}POST /v1/knowledgebases/{knowledgeBaseId}/index-capabilities/{capability}/clear
SDK:KnowledgeBases.clearIndexCapability · scope:knowledgebases.write
排队清理一个能力的派生索引。confirmation 必须是 clear:<capability>;idempotencyKey 使重试安全。源文档、切片、其他能力与 canonical Wiki 页面/版本都被保留——删除 canonical Wiki 内容要用 resetWiki。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
capability | path | string | 是 | 枚举:graphrag / raptor / wiki | 能力标识。 |
confirmation | body | string | 是 | 形如 clear:<capability> | 显式确认。 |
idempotencyKey | body | string | 是 | 去重重试的稳定键。 |
输出:
202,返回模型 Models.KnowledgeBaseIndexOperation(清理操作,字段见「公共响应模型」);轮询 GET index-operations/{operationId} 至终态。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-capabilities/wiki/clear" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"confirmation": "clear:wiki",
"idempotencyKey": "clear-wiki-20260918-0001"
}'响应示例:
{
"$id": "op_0002",
"$createdAt": "2026-09-18T03:00:00.000+00:00",
"$updatedAt": "2026-09-18T03:00:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"documentIds": [],
"status": "queued",
"stage": "",
"progress": 0,
"message": "",
"effectiveConfig": {},
"configHash": "sha256:…",
"sourceHash": "sha256:…",
"stats": {},
"error": {}
}索引操作(index-operations)
GET /v1/knowledgebases/{knowledgeBaseId}/index-operations
SDK:KnowledgeBases.listIndexOperations · scope:knowledgebases.read
列出知识库的索引操作:可按能力与生命周期状态过滤并分页。能力被禁用或不可用时操作历史仍可见。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
capability | query | string | 否 | 枚举:graphrag / raptor / wiki | 能力过滤。 |
status | query | string | 否 | 枚举:queued / running / succeeded / failed / cancelling / cancelled / clearing / cleared | 操作状态过滤。 |
limit | query | integer | 否 | 默认 25 | 最大返回操作数。 |
offset | query | integer | 否 | 默认 0 | 跳过的操作数。 |
输出:
200,返回模型 Models.KnowledgeBaseIndexOperationList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的操作总数。 |
operations* | object[] | 操作列表,元素为 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations?capability=wiki&status=running&limit=25" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"operations": [
{
"$id": "op_0001",
"$createdAt": "2026-09-18T02:40:00.000+00:00",
"$updatedAt": "2026-09-18T02:41:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"documentIds": [],
"status": "running",
"stage": "compile",
"progress": 40,
"message": "",
"effectiveConfig": {},
"configHash": "sha256:…",
"sourceHash": "sha256:…",
"stats": {},
"error": {}
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/index-operations
SDK:KnowledgeBases.createIndexOperation · scope:knowledgebases.write
为可插拔索引能力排队一次 build 或 repair 操作。要点:
- RAPTOR 生效配置为 document 范围时,用
scope=document并传已有可索引切片的documentIds——配置与操作的范围必须一致。 - Wiki
sources接受rag、graphrag、memory;RAPTOR 摘要自动增强rag,不是独立的 source 值。 - Server SDK 取值
knowledgebase与 HTTP 默认knowledgeBase都表示知识库范围。 - 提供稳定的
idempotencyKey;force=true会先请求取消冲突中的活跃操作再排队新操作。 - 轮询返回的操作直至终态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
capability | body | string | 是 | 枚举:graphrag / raptor / wiki | 能力标识。 |
kind | body | string | 否 | 枚举:build / repair | 操作种类。 |
scope | body | string | 否 | 枚举:knowledgebase / document | 操作范围。 |
documentIds | body | string[] | 否 | document 范围操作的文档 ID。 | |
config | body | object | 否 | 操作级配置覆盖(泛化对象)。 | |
force | body | boolean | 否 | 排队前先取消另一个活跃操作。 | |
idempotencyKey | body | string | 是 | 去重重试的稳定键。 | |
retryOf | body | string | 否 | 要修复的先前失败/取消的操作。 |
输出:
202,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"idempotencyKey": "build-wiki-20260918-0001"
}'响应示例:
{
"$id": "op_0001",
"$createdAt": "2026-09-18T02:40:00.000+00:00",
"$updatedAt": "2026-09-18T02:40:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"documentIds": [],
"status": "queued",
"stage": "",
"progress": 0,
"message": "",
"effectiveConfig": {},
"configHash": "sha256:…",
"sourceHash": "sha256:…",
"stats": {},
"error": {}
}GET /v1/knowledgebases/{knowledgeBaseId}/index-operations/{operationId}
SDK:KnowledgeBases.getIndexOperation · scope:knowledgebases.read
读取单个索引操作:冻结的生效配置、源/配置哈希、进度、有界日志尾、结果代、统计、脱敏错误与时间戳。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
operationId | path | string | 是 | 索引操作 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations/op_0001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "op_0001",
"$createdAt": "2026-09-18T02:40:00.000+00:00",
"$updatedAt": "2026-09-18T02:44:30.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"documentIds": [],
"status": "succeeded",
"stage": "publish",
"progress": 100,
"message": "",
"effectiveConfig": {},
"configHash": "sha256:…",
"sourceHash": "sha256:…",
"resultGeneration": "gen_0007",
"resultVersion": "1.0.0",
"stats": {},
"error": {},
"logTail": "",
"startedAt": "2026-09-18T02:40:05.000+00:00",
"heartbeatAt": "2026-09-18T02:44:25.000+00:00",
"finishedAt": "2026-09-18T02:44:30.000+00:00"
}POST /v1/knowledgebases/{knowledgeBaseId}/index-operations/{operationId}/cancel
SDK:KnowledgeBases.cancelIndexOperation · scope:knowledgebases.write
请求取消一个排队中或运行中的索引操作。取消按 attempt 围栏:更新的 attempt 接管后,过期 worker 无法再发布结果。轮询操作直至变为 cancelled 或其他终态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
operationId | path | string | 是 | 索引操作 ID。 |
无请求体。
输出:
202,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations/op_0001/cancel" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "op_0001",
"$createdAt": "2026-09-18T02:40:00.000+00:00",
"$updatedAt": "2026-09-18T02:41:10.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"capability": "wiki",
"kind": "build",
"scope": "knowledgebase",
"documentIds": [],
"status": "cancelling",
"stage": "compile",
"progress": 40,
"message": "",
"effectiveConfig": {},
"configHash": "sha256:…",
"sourceHash": "sha256:…",
"stats": {},
"error": {}
}Wiki 页面
GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages
SDK:KnowledgeBases.listWikiPages · scope:knowledgebases.read
列出知识库中的 canonical Wiki 页面:可按页面类型或发布状态过滤并分页。列表返回 canonical 页面记录;需要最新详情时调用 getWikiPage。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
pageType | query | string | 否 | 枚举:entity / topic / survey / agent_practice / category_index | 页面类型过滤。 |
status | query | string | 否 | 枚举:draft / published / conflict / archived | 页面状态过滤。 |
limit | query | integer | 否 | 默认 50 | 最大返回页数。 |
offset | query | integer | 否 | 默认 0 | 跳过的页数。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPageList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的页面总数。 |
pages* | object[] | 页面列表,元素为 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages?pageType=entity&status=published&limit=50" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"pages": [
{
"$id": "wp_0001",
"$createdAt": "2026-09-10T08:00:00.000+00:00",
"$updatedAt": "2026-09-17T09:30:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n…",
"summary": "退款条件与时效",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 12,
"contentRevision": 3,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages
SDK:KnowledgeBases.createWikiPage · scope:knowledgebases.write
创建人工持有的 canonical Wiki 页面:可带 Markdown、别名与显式出链;Markdown 中的 [[slug]] 链接也会被服务端提取,未解析目标保留为红链。本操作创建首个不可变版本。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | body | string | 是 | 库内唯一 Wiki 页面 slug。 | |
title | body | string | 是 | 页面标题。 | |
pageType | body | string | 否 | 枚举:entity / topic / survey / agent_practice / category_index | 页面类型。 |
contentMd | body | string | 否 | canonical Markdown 内容。 | |
summary | body | string | 否 | 页面摘要。 | |
status | body | string | 否 | 枚举:draft / published / conflict / archived | 页面状态。 |
pinned | body | boolean | 否 | 是否人工置顶。 | |
links | body | object | 否 | 显式出链(泛化对象)。 | |
aliases | body | object | 否 | 人工别名(泛化对象)。 | |
reason | body | string | 否 | 版本原因。 |
输出:
201,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n\n签收后 7 日内可申请退款,详见 [[after-sale-flow]]。",
"summary": "退款条件与时效",
"status": "published",
"reason": "人工整理退款政策"
}'响应示例:
{
"$id": "wp_0001",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"$updatedAt": "2026-09-18T03:10:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n\n签收后 7 日内可申请退款,详见 [[after-sale-flow]]。",
"summary": "退款条件与时效",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 0,
"contentRevision": 1,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}
SDK:KnowledgeBases.getWikiPage · scope:knowledgebases.read
按 slug 读取 canonical Wiki 页面:出链、入链、别名、来源溯源、投影结果代、未解决冲突与水合冲突证据。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。关键字段:contentRevision*(后续写操作的 CAS 版本号)、conflicts*、links* / backlinks* / aliases*。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "wp_0001",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"$updatedAt": "2026-09-18T03:10:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n…",
"summary": "退款条件与时效",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 12,
"contentRevision": 1,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}PATCH /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}
SDK:KnowledgeBases.updateWikiPage · scope:knowledgebases.write
以乐观并发更新 canonical Wiki 页面:contentRevision 必须与当前页面版本一致。page 对象承载变更字段;省略 links / aliases 表示保留。成功写入创建不可变版本并刷新检索投影。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | 当前 Wiki 页面 slug。 | |
contentRevision | body | integer | 是 | 期望的当前内容版本号。 | |
page | body | object | 是 | 要更新的字段:slug、title、pageType、contentMd、summary、status 或 pinned。 | |
links | body | object | 否 | 替换出链;省略则保留。 | |
aliases | body | object | 否 | 替换人工别名;省略则保留。 | |
reason | body | string | 否 | 版本原因。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"contentRevision": 1,
"page": {
"contentMd": "# 退款政策\n\n签收后 7 日内可申请退款(定制商品除外),详见 [[after-sale-flow]]。"
},
"reason": "补充定制商品例外"
}'响应示例:
{
"$id": "wp_0001",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"$updatedAt": "2026-09-18T03:25:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n\n签收后 7 日内可申请退款(定制商品除外),详见 [[after-sale-flow]]。",
"summary": "退款条件与时效",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 12,
"contentRevision": 2,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}DELETE /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}
SDK:KnowledgeBases.deleteWikiPage · scope:knowledgebases.write
删除一个 canonical Wiki 页面:confirmation 必须是 delete:<slug>,contentRevision 必须与当前版本一致。这是破坏性操作,删除 canonical 页面,版本/审计行为按服务端定义保留(DELETE 携带 JSON 请求体)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
contentRevision | body | integer | 是 | 期望的当前页面版本号。 | |
confirmation | body | string | 是 | 形如 delete:<slug> | 显式确认。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiMutation(字段见「公共响应模型」)。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"contentRevision": 2,
"confirmation": "delete:refund-policy"
}'响应示例:
{
"pagesDeleted": 1,
"linksDeleted": 1,
"linksNulled": 0,
"revisionsDeleted": 2,
"aliasesDeleted": 0,
"clearOperationId": "op_0003"
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/revisions
SDK:KnowledgeBases.listWikiPageRevisions · scope:knowledgebases.read
列出一个 canonical Wiki 页面的不可变版本:含主体、版本类型、前后内容、原因与创建时间,可配合 restoreWikiPage 使用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
limit | query | integer | 否 | 默认 50 | 最大返回版本数。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiRevisionList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的版本总数。 |
revisions* | object[] | 版本列表,元素为 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/revisions?limit=50" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"revisions": [
{
"$id": "rev_0007",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"pageId": "wp_0001",
"revisionType": "create",
"titleAfter": "退款政策",
"contentAfter": "# 退款政策\n…",
"reason": "人工整理退款政策"
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/revisions/{revisionId}
SDK:KnowledgeBases.getWikiPageRevision · scope:knowledgebases.read
读取 canonical Wiki 页面的单个不可变版本。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
revisionId | path | string | 是 | Wiki 版本 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/revisions/rev_0007" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "rev_0007",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"pageId": "wp_0001",
"revisionType": "create",
"titleAfter": "退款政策",
"contentAfter": "# 退款政策\n…",
"reason": "人工整理退款政策"
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/restore
SDK:KnowledgeBases.restoreWikiPage · scope:knowledgebases.write
把一个历史版本恢复为新版本:contentRevision 提供乐观并发围栏;历史版本本身永不被改写。省略 links 表示保留当前出链。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
revisionId | body | string | 是 | 要恢复的版本 ID。 | |
contentRevision | body | integer | 是 | 期望的当前内容版本号。 | |
links | body | object | 否 | 替换出链;省略则保留。 | |
reason | body | string | 否 | 恢复原因。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/restore" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"revisionId": "rev_0007",
"contentRevision": 2,
"reason": "回退到人工整理版"
}'响应示例:
{
"$id": "wp_0001",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"$updatedAt": "2026-09-18T03:40:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n…",
"summary": "退款条件与时效",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 12,
"contentRevision": 3,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/export-to-memory
SDK:KnowledgeBases.createWikiPageMemoryExport · scope:knowledgebases.write
把一个 canonical Wiki 页面作为事实导出到既有 AppBase Memory 服务。前提:当前项目已有活跃的 AppBase Memory 项目(启用知识库不会自动创建);Memory 服务禁用/初始化中/缺失/不可用时返回 503 memory_service_unavailable。调用方须能写知识库与目标 Memory scope;响应不暴露任何模型或 provider 凭据。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
agentId | body | string | 否 | 导出事实的 Memory agent 身份。 |
输出:
201,返回模型 Models.KnowledgeBaseWikiMemoryExport。
| 字段 | 类型 | 说明 |
|---|---|---|
memory* | object | Memory 服务对导出页面的响应(泛化对象,字段以实际返回为准)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/export-to-memory" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agent_support_bot"
}'响应示例(memory 为泛化对象,示意——字段以实际返回为准):
{
"memory": {}
}Wiki 冲突与提案
GET /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts
SDK:KnowledgeBases.listWikiConflicts · scope:knowledgebases.read
列出仍含未解决编译冲突的 canonical Wiki 页面:每页含当前 contentRevision、原始 pendingConflicts 元数据与面向调用方的 conflicts 数组。响应 total 是未解决冲突页总数,不是当前页返回数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
limit | query | integer | 否 | 默认 100 | 最大返回冲突页数。 |
offset | query | integer | 否 | 默认 0 | 跳过的冲突页数。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPageList(total* + pages*[],页面字段见「公共响应模型」;conflicts[] 含稳定冲突 id、检测器 type、人读 reason、精确 conflictingContents 与归属 sources)。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts?limit=100&offset=0" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"pages": [
{
"$id": "wp_0002",
"$createdAt": "2026-09-12T08:00:00.000+00:00",
"$updatedAt": "2026-09-17T10:00:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "shipping-time",
"title": "发货时效",
"pageType": "topic",
"contentMd": "# 发货时效\n…",
"status": "conflict",
"pendingConflicts": [],
"conflicts": [
{
"id": "cf_0001",
"type": "contradiction",
"reason": "两处来源对发货时效表述不一致",
"conflictingContents": ["48 小时内发货", "72 小时内发货"],
"sources": [
{
"documentId": "doc_manual_v2",
"documentName": "售后手册 v2",
"chunkId": "chk_0042",
"conflictingContent": "48 小时内发货",
"context": "…工作日订单 48 小时内发货…",
"locator": {}
}
],
"readOnly": false,
"confidence": 0.91
}
],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": "wiki-compiler",
"pinned": false,
"viewCount": 3,
"contentRevision": 5,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts/{slug}/proposal
SDK:KnowledgeBases.getWikiConflictProposal · scope:knowledgebases.read
读取冲突 Wiki 页面的最新编译提案:返回的不可变版本可在逐条解决冲突或接受整条提案前查阅。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts/shipping-time/proposal" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "rev_0009",
"$createdAt": "2026-09-17T10:05:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"pageId": "wp_0002",
"revisionType": "compile_proposal",
"titleBefore": "发货时效",
"titleAfter": "发货时效",
"contentBefore": "# 发货时效\n…",
"contentAfter": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
"reason": "编译器合并提案"
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts/{slug}/resolve
SDK:KnowledgeBases.resolveWikiConflict · scope:knowledgebases.write
以乐观并发解决 Wiki 冲突:要么解决一条精确冲突选项,要么提交手工合并后的文档。解决提案的一部分时,传 proposalId 与剩余提案 Markdown(proposalMd),避免未解决部分被静默丢弃。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
slug | path | string | 是 | Wiki 页面 slug。 | |
contentRevision | body | integer | 是 | 期望的当前内容版本号。 | |
contentMd | body | string | 否 | 手工合并后的 Markdown。 | |
resolvedConflictId | body | string | 否 | 要解决的精确待决冲突 ID。 | |
resolvedConflictOptionText | body | string | 否 | 为该冲突选定的选项文本。 | |
proposalId | body | string | 否 | 正在部分解决的编译提案 ID。 | |
proposalMd | body | string | 否 | 更新后的未解决提案 Markdown。 | |
links | body | object | 否 | 替换出链;省略则保留。 | |
reason | body | string | 否 | 解决原因。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts/shipping-time/resolve" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"contentRevision": 5,
"resolvedConflictId": "cf_0001",
"resolvedConflictOptionText": "48 小时内发货",
"reason": "以售后手册 v2 为准"
}'响应示例:
{
"$id": "wp_0002",
"$createdAt": "2026-09-12T08:00:00.000+00:00",
"$updatedAt": "2026-09-18T04:00:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "shipping-time",
"title": "发货时效",
"pageType": "topic",
"contentMd": "# 发货时效\n\n工作日订单 48 小时内发货。",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": "wiki-compiler",
"pinned": false,
"viewCount": 3,
"contentRevision": 6,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/proposals
SDK:KnowledgeBases.listWikiProposals · scope:knowledgebases.read
列出知识库中冲突 Wiki 页面的最新编译提案:提案是不可变版本,被显式接受或解决前不会替换 canonical 内容。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
limit | query | integer | 否 | 默认 100 | 最大返回提案数。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiRevisionList(total* + revisions*[],版本字段见「公共响应模型」)。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/proposals?limit=100" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"revisions": [
{
"$id": "rev_0009",
"$createdAt": "2026-09-17T10:05:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"pageId": "wp_0002",
"pageSlug": "shipping-time",
"pageTitle": "发货时效",
"revisionType": "compile_proposal",
"contentAfter": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
"reason": "编译器合并提案"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/proposals/{proposalId}/accept
SDK:KnowledgeBases.acceptWikiProposal · scope:knowledgebases.write
把一条精确的编译提案接受为 canonical Wiki 页面:contentRevision 必须与当前页面版本一致,因此提案无法覆盖更新的人工编辑。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
proposalId | path | string | 是 | 精确的编译提案版本 ID。 | |
contentRevision | body | integer | 是 | 期望的当前页面版本号。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/proposals/rev_0009/accept" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"contentRevision": 5
}'响应示例:
{
"$id": "wp_0002",
"$createdAt": "2026-09-12T08:00:00.000+00:00",
"$updatedAt": "2026-09-18T04:10:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "shipping-time",
"title": "发货时效",
"pageType": "topic",
"contentMd": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": "wiki-compiler",
"pinned": false,
"viewCount": 3,
"contentRevision": 6,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}Wiki 图谱与治理
GET /v1/knowledgebases/{knowledgeBaseId}/wiki/graph
SDK:KnowledgeBases.getWikiGraph · scope:knowledgebases.read
读取 canonical Wiki 页面链接图谱:含 canonical 页面与已解析/未解析链接;目标页为 null 或 redLink=true 表示目标页尚不存在的红链。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiGraph。
| 字段 | 类型 | 说明 |
|---|---|---|
pages* | object[] | Wiki 图谱页面,元素为 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。 |
links* | object | 已解析与红链边(泛化对象;目标页为 null 或 redLink=true 表示红链)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/graph" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例(links 为泛化对象,示意——字段以实际返回为准):
{
"pages": [
{
"$id": "wp_0001",
"$createdAt": "2026-09-18T03:10:00.000+00:00",
"$updatedAt": "2026-09-18T03:25:00.000+00:00",
"knowledgeBaseId": "kb_product_docs",
"slug": "refund-policy",
"title": "退款政策",
"pageType": "entity",
"contentMd": "# 退款政策\n…",
"status": "published",
"pendingConflicts": [],
"conflicts": [],
"sourceChunks": [],
"sourceGraph": {},
"sourceMemory": [],
"compiledBy": null,
"pinned": false,
"viewCount": 12,
"contentRevision": 2,
"links": [],
"backlinks": [],
"aliases": [],
"conflictEvidence": {},
"divergenceRecommendations": {},
"conflictBlocks": [],
"internalContradictions": [],
"ruleBasedContradictions": [],
"generalKnowledgeConflicts": []
}
],
"links": []
}GET /v1/knowledgebases/{knowledgeBaseId}/wiki/recommended-limits
SDK:KnowledgeBases.getWikiRecommendedLimits · scope:knowledgebases.read
根据当前文档、GraphRAG 与 Memory 源信号推荐有界的 Wiki 编译上限。enableLlmRefine=false 时只给确定性推荐;否则知识库的共享 Chat 模型可参与修正。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
enableLlmRefine | query | boolean | 否 | 默认 true | 是否允许共享 Knowledge chat 模型修正确定性推荐。 |
输出:
200,返回模型 Models.KnowledgeBaseWikiLimits。
| 字段 | 类型 | 说明 |
|---|---|---|
max_entities* | integer | 推荐的最大实体页数。 |
max_topics* | integer | 推荐的最大主题页数。 |
max_surveys* | integer | 推荐的最大综述页数。 |
rag_max_docs* | integer | 推荐的 RAG 文档预算。 |
rag_max_chunks_per_doc* | integer | 推荐的每文档切片数。 |
evidence_max_chunks_to_embed* | integer | 推荐的证据 Embedding 预算。 |
strategy* | string | heuristic 或 ai。 |
signals* | object | 推荐使用的有界 Knowledge 源信号(泛化对象)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/recommended-limits?enableLlmRefine=false" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"max_entities": 200,
"max_topics": 60,
"max_surveys": 20,
"rag_max_docs": 500,
"rag_max_chunks_per_doc": 40,
"evidence_max_chunks_to_embed": 2000,
"strategy": "heuristic",
"signals": {}
}POST /v1/knowledgebases/{knowledgeBaseId}/wiki/reset
SDK:KnowledgeBases.resetWiki · scope:knowledgebases.write
删除整个 canonical Wiki 并排队删除其编译投影。confirmation 必须是 reset:wiki;idempotencyKey 使派生索引清理请求可安全重试。比 clearIndexCapability 更具破坏性——后者保留 canonical Wiki 内容。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 | |
confirmation | body | string | 是 | 固定 reset:wiki | 显式确认。 |
idempotencyKey | body | string | 是 | 去重重试的稳定键。 |
输出:
202,返回模型 Models.KnowledgeBaseWikiMutation(字段见「公共响应模型」);clearOperationId 指向排队中的索引清理操作。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/reset" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"confirmation": "reset:wiki",
"idempotencyKey": "reset-wiki-20260918-0001"
}'响应示例:
{
"pagesDeleted": 42,
"linksDeleted": 87,
"linksNulled": 3,
"revisionsDeleted": 120,
"aliasesDeleted": 15,
"clearOperationId": "op_0004"
}错误与边界
- 资源不存在(知识库/页面/版本/提案/操作):
404;Wiki 页面 slug 在库内唯一,重复创建按冲突处理。 - 所有 Wiki 写操作走
contentRevisionCAS:版本不匹配即被拒——先GET取最新版本号再重试。 - 启用部署不可用的能力:
knowledge_index_capability_unavailable;禁用能力保留既有结果代与操作历史。 export-to-memory前置不满足(Memory 禁用/初始化中/缺失/不可用):503 memory_service_unavailable。- 破坏性操作均需显式确认串:页面删除
delete:<slug>、能力清理clear:<capability>、Wiki 重置reset:wiki;清理/重置另需idempotencyKey保证重试安全。 - 索引操作是异步的:
202仅代表已排队,终态(succeeded/failed/cancelled/cleared)须轮询GET index-operations/{operationId};取消按 attempt 围栏,过期 worker 不能发布结果。 - Wiki
clearIndexCapability只清投影、保留 canonical 页面/链接/版本/别名;只有resetWiki删除 canonical Wiki。 - 编译提案不可变且不自动生效:接受(
accept)或逐条解决(resolve)前 canonical 内容不变。 - GraphRAG 图谱浏览是有界快照:
hasMore/nextCursor翻页,truncated=true表示只拿到子集。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
KnowledgeBases.getWikiOverview | GET /knowledgebases/wiki/overview |
KnowledgeBases.createWikiQuery | POST /knowledgebases/wiki/query |
KnowledgeBases.createWikiProjectSearch | POST /knowledgebases/wiki/search |
KnowledgeBases.getGraph | GET .../graph |
KnowledgeBases.listGraphCommunityReports | GET .../graph/community-reports |
KnowledgeBases.getGraphEntityNeighbors | GET .../graph/entities/{entityId}/neighbors |
KnowledgeBases.listIndexCapabilities | GET .../index-capabilities |
KnowledgeBases.updateIndexCapability / clearIndexCapability | PATCH .../index-capabilities/{capability}、POST .../clear |
KnowledgeBases.listIndexOperations / createIndexOperation | GET / POST .../index-operations |
KnowledgeBases.getIndexOperation / cancelIndexOperation | GET .../index-operations/{operationId}、POST .../cancel |
KnowledgeBases.listWikiPages / createWikiPage | GET / POST .../wiki/pages |
KnowledgeBases.getWikiPage / updateWikiPage / deleteWikiPage | GET / PATCH / DELETE .../wiki/pages/{slug} |
KnowledgeBases.listWikiPageRevisions / getWikiPageRevision | GET .../revisions、GET .../revisions/{revisionId} |
KnowledgeBases.restoreWikiPage | POST .../wiki/pages/{slug}/restore |
KnowledgeBases.createWikiPageMemoryExport | POST .../wiki/pages/{slug}/export-to-memory |
KnowledgeBases.listWikiConflicts / getWikiConflictProposal / resolveWikiConflict | GET .../wiki/conflicts、GET .../conflicts/{slug}/proposal、POST .../resolve |
KnowledgeBases.listWikiProposals / acceptWikiProposal | GET .../wiki/proposals、POST .../proposals/{proposalId}/accept |
KnowledgeBases.getWikiGraph | GET .../wiki/graph |
KnowledgeBases.getWikiRecommendedLimits | GET .../wiki/recommended-limits |
KnowledgeBases.resetWiki | POST .../wiki/reset |
事实源
- Server API spec:
agentbase-sdksv2.7.2specs/open-api3-latest-server.json(/knowledgebases域 Wiki/GraphRAG/索引治理 26 个路径、Wiki 页面与版本模型、索引能力与操作模型、capability/mode/pageType/status/kind/scope 枚举)。 - Server SDK 生成物:
server-nodejsv2.7.0KnowledgeBasesservice(方法名与参数序实读src/services/knowledge-bases.ts;返回模型Models.KnowledgeBaseWiki*/KnowledgeBaseGraph*/KnowledgeBaseIndex*)。 - 语义深度参考:
skills/ob-agentbase/references/knowledge-bases.md(能力配置顺序、language语义、clear 与 reset 的边界、RAPTOR document scope 约束)。 - 上游发布:appbase
v2.7.0(release-2.7.0 分支尖端34b7c8633813a8fe75cc58e8348bd4a9efdd0e21)。 - 证据缺口:
cards/results/degradedKnowledgeBases/graph/nodes/edges/links/memory/signals等为泛化对象(spec 未声明字段级模型),以实际返回为准;未对 SIT/生产实例做实机调用验证。