ContextDB Data API 知识评审-云数据库 RDS(RDS)-阿里云帮助中心

本文介绍RDS ContextDB的知识评审Data API，包括评审记录管理、人工评审、重写模板和评审策略配置。

公共信息

基础地址

https://context-database.aliyuncs.com

鉴权方式

所有数据面接口通过workspace级API Key鉴权，以下三种方式任选其一：

方式	Header格式
X-API-Key	`X-API-Key: <YOUR_API_KEY>`
Token	`Authorization: Token <YOUR_API_KEY>`
Bearer	`Authorization: Bearer <YOUR_API_KEY>`

响应信封

本文档所有接口均返回统一信封结构，业务数据放在 data 字段内。

名称	类型	描述	示例值
errorCode	integer	错误码，`0` 表示成功	`0`
errorMessage	string	错误说明，成功时为null	`null`
requestId	string	请求追踪ID	`req-xxx`
data	object/array/null	业务数据，各接口在「返回参数」中单独定义	见各接口示例

公共错误语义

HTTP状态码	errorCode	触发条件
400	`1001`	参数缺失、参数非法、资源不存在、状态不允许操作、权限不足（`errorMessage` 以 `forbidden:` 开头）
401	`4001`	未携带API Key
500	`1000`	服务端内部错误

说明

注意：知识评审域的权限校验失败不返回403，而是以HTTP 400 + errorCode=1001 返回，errorMessage 形如 forbidden: kb_write, knowledge base permission denied: kb-001。

Data API概览

下表列出本文介绍的接口及其功能概述。

API	描述
ListReviews	分页返回入库评审记录，可按decision、review_status过滤。
GetReviewDetail	获取单条评审详情（含质量评分、矛盾列表、冲突信息、重写内容）。
ReviewAction	对评审记录执行人工操作。
DeleteReview	删除单条评审记录，仅允许删除已通过（reviewed）或已拒绝（rejected）的记录。
ResolveConflicts	逐条决策冲突项。
BatchReviewAction	批量执行知识评审操作，仅支持 `confirm` / `reject`，单次最多50条。
BatchDeleteReviews	批量删除评审记录，仅允许删除已通过（reviewed）或已拒绝（rejected）的记录，单次最多50条。
ListKnowledgeReviewTemplates	返回指定知识库内所有活跃的评审重写模板，按名称升序。
CreateKnowledgeReviewTemplate	创建知识评审重写模板。
GetKnowledgeReviewTemplate	返回模板详情；不存在时返回200且data=null。
UpdateKnowledgeReviewTemplate	按template_id更新模板名称、章节或默认标记。
DeleteKnowledgeReviewTemplate	软删指定模板（status=deleted、清空内容、name改写规避唯一键冲突），重复删除幂等。
SetDefaultKnowledgeReviewTemplate	将指定模板设为KB默认评审重写模板（同一事务内清除同KB其他模板的默认标记）。
ClearDefaultKnowledgeReviewTemplate	清除KB内所有模板的is_default标记，运行期注入回落「无模板」行为。
GetReviewSettings	获取当前工作空间的知识评审策略设置。
UpdateReviewSettings	更新当前工作空间的知识评审策略（部分更新语义，仅传入的字段被修改）。

Knowledge Review API

ListReviews

接口说明

分页返回入库评审记录，可按decision、review_status过滤。URL Query支持sort_by、sort_order。sort_by当前仅支持confidence_score；sort_order为asc/desc，传sort_by但省略时默认desc；null分数始终置末尾，同分再按created_at降序、review ID升序。单独传sort_order或非法值返回400；未传sort_by时按created_at降序。

请求语法

GET /v1/knowledge/reviews

请求参数

名称	类型	必填	描述	示例值
decision	string	否	决策类型过滤：`auto_accept`/`pending_review`/`reject`	`pending_review`
review_status	string	否	状态过滤：`pending`/`reviewed`/`rejected`	`pending`
page	integer	否	页码，默认 `1`	`1`
page_size	integer	否	每页条数，默认 `20`，上限 `100`	`20`
sort_by	string	否	排序字段，当前仅支持 `confidence_score`	`confidence_score`
sort_order	string	否	排序方向：`asc`/`desc`；仅在传入sort_by时有效，省略默认 `desc`	`desc`

返回参数（data字段内）

名称	类型	描述	示例值
reviews	array	评审记录列表，元素字段见下表	见示例
total	integer	总条数	`42`
page	integer	当前页码（钳制后的实际值）	`1`
page_size	integer	每页条数（钳制后的实际值）	`20`

reviews数组元素：

名称	类型	描述	示例值
review_id	string	评审记录ID	`rev-001`
document_id	string	文档ID	`doc-001`
document_name	string	文档名称；评审记录内为空时回查文档表，文档已删除则为null	`故障处理手册.md`
knowledge_base_id	string	知识库ID	`kb-001`
confidence_score	float	综合置信度，未评分为null	`0.85`
decision	string	系统决策：`auto_accept`/`pending_review`/`reject`	`pending_review`
review_status	string	评审状态：`pending`/`reviewed`/`rejected`，派生字段，见下表	`pending`
has_conflicts	boolean	是否存在知识冲突	`false`
has_contradictions	boolean	是否存在不可解决的自矛盾	`false`
rewrite_needed	boolean	是否需要重写	`true`
human_action	string	人工操作类型（未操作为null）	`null`
created_at	string	创建时间	`2026-06-01T10:00:00Z`

review_status派生规则

review_status 不是数据库列，而是每次响应时按下列顺序派生：

优先级	条件	派生结果
1	`human_action` 非空（已执行过人工操作）	取评审记录的 `status` 列，即 `reviewed` 或 `rejected`
2	`decision` = `auto_accept`	`reviewed`
3	其他（含 `decision` = `pending_review`）	`pending`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"reviews":[{"review_id":"rev-001","document_id":"doc-001","document_name":"故障处理手册.md","knowledge_base_id":"kb-001","confidence_score":0.85,"decision":"pending_review","review_status":"pending","has_conflicts":false,"has_contradictions":false,"rewrite_needed":true,"human_action":null,"created_at":"2026-06-01T10:00:00Z"}],"total":42,"page":1,"page_size":20}}

GetReviewDetail

接口说明

获取单条评审详情（含质量评分、矛盾列表、冲突信息、重写内容）。使用统一信封结构返回。原文按3000字符/页切片返回，content_page 控制页码。

请求语法

GET /v1/knowledge/reviews/detail

请求参数

名称	类型	必填	描述	示例值
review_id	string	是	评审记录ID	`rev-001`
content_page	integer	否	原文内容分页页码，默认 `1`，每页3000字符	`1`

参数校验与越界行为

参数	越界/非法输入	实际行为
review_id	缺失	返回400（缺少必填参数）
review_id	在当前workspace下不存在	返回400，`errorMessage` 为 `review not found: xxx`
content_page	`< 1`	静默钳制为 `1`，不报错
content_page	超过实际总页数	不报错，`original_content.text` 返回空字符串，`page` 回显传入值

返回参数（data字段内）

名称	类型	描述	示例值
review_id	string	评审记录ID	`rev-001`
document_id	string	文档ID	`doc-001`
document_name	string	文档名称；评审记录内为空时回查文档表	`故障处理手册.md`
knowledge_base_id	string	知识库ID	`kb-001`
member_id	string	触发入库的成员ID	`member-001`
logic_score	float	逻辑连贯性评分（越高越好），未评分为null	`0.82`
noise_score	float	噪音比例评分（越低越好）	`0.12`
contradiction_score	float	内部矛盾度评分（越低越好）	`0.05`
confidence_score	float	综合置信度	`0.85`
source_type	string	来源类型：`upload`/`memory_promotion`/`process`/`platform`	`upload`
decision	string	系统决策：`auto_accept`/`pending_review`/`reject`	`pending_review`
decision_reason	string	决策说明文案	`综合置信度 0.55 低于自动入库阈值 0.60`
review_status	string	评审状态：`pending`/`reviewed`/`rejected`，派生字段	`pending`
has_contradictions	boolean	是否存在不可解决的自矛盾	`false`
contradictions	string	矛盾详情，JSON字符串（非对象），结构见下表	`[{"snippet1":"...","snippet2":"..."}]`
conflicts	string	与知识库的冲突详情，JSON字符串，结构见下表	`[{"id":"c1","conflict_type":"fact"}]`
quality_details	string	质量详情，JSON字符串，形如 `{"logic_issues":[...],"noise_segments":[...]}`	`{"logic_issues":[...]}`
original_content	object	分页后的原文，子字段见下表；原文为空时为null	见下表
original_logic_score	float	重写前的逻辑评分	`0.61`
original_noise_score	float	重写前的噪音评分	`0.30`
original_contradiction_score	float	重写前的矛盾度评分	`0.10`
original_contradictions	string	重写前的矛盾详情，JSON字符串	空数组
rewrite_needed	boolean	是否需要重写	`true`
rewrite_reason	string	重写触发原因	`置信度 0.55 低于自动入库阈值 0.6，噪音分为短板，优先去噪`
rewrite_strategy	string	重写策略，取值见下表	`denoise`
rewritten_content	string	AI重写后的完整内容（不分页）	`重写后的文档内容...`
rewrite_info_check	string	重写信息保真校验，JSON字符串，形如 `{"missing_facts":[...],"preserved_facts_count":12}`	`{"missing_facts":[...]}`
human_action	string	人工操作类型，未操作为null	`null`
human_edited_content	string	人工编辑后的内容，未编辑为null	`null`
human_conflict_resolutions	string	人工冲突决策，JSON字符串	`[{"conflict_id":"c1","resolution":"use_new"}]`
human_action_by	string	执行人工操作的成员ID	`member-001`
human_action_at	string	人工操作时间	`2026-06-01T11:00:00Z`
loop_iterations	integer	已执行的评审-重写迭代轮数	`1`
max_iterations	integer	最大迭代轮数	`3`
created_at	string	创建时间	`2026-06-01T10:00:00Z`
updated_at	string	更新时间	`2026-06-01T10:05:00Z`

original_content对象：

名称	类型	描述	示例值
text	string	当前页原文切片，每页3000字符；页码越界时为空字符串	`# 故障处理手册...`
page	integer	当前页码，回显请求的content_page（钳制后）	`1`
total_pages	integer	总页数，按 `ceil(总字符数 / 3000)` 计算	`4`
total_chars	integer	原文总字符数	`10240`

rewrite_strategy取值：

取值	描述
`denoise`	去噪：噪音分为短板时选用
`restructure`	重构：逻辑分为短板时选用
`fix_contradiction`	修复矛盾：存在可解决的内部矛盾时选用
`hybrid`	混合策略（代码常量已定义）
`remove_hallucination`	消除幻觉（代码常量已定义）

conflicts元素结构（JSON字符串解析后）：

名称	类型	描述
id	string	冲突ID，ResolveConflicts / ReviewAction 的 `conflict_id` 取此值
kb_document_id	string	冲突所在的知识库文档ID
kb_document_name	string	冲突所在的知识库文档名称
kb_fact	string	知识库中的既有事实
new_fact	string	本次入库内容中的新事实
conflict_type	string	冲突类型
severity_score	float	冲突严重度
ai_recommendation	string	AI建议的处理方式
human_resolution	string	人工决策结果

contradictions元素结构（JSON字符串解析后）：

名称	类型	描述
snippet1	string	矛盾片段一
snippet2	string	矛盾片段二
type	string	矛盾类型
resolvable	boolean	是否可自动解决；存在不可解决项时 `has_contradictions=true` 且决策强制为 `pending_review`
confidence	float	矛盾判定置信度

说明

contradictions、conflicts、quality_details、original_contradictions、rewrite_info_check、human_conflict_resolutions 六个字段在信封中均为JSON字符串，客户端需二次解析；上表描述的是解析后的结构，字段以入库时写入的JSON为准。

ReviewAction

接口说明

对评审记录执行人工操作。使用统一信封结构返回。同一条评审记录只允许操作一次（human_action 已写入后重复调用返回400）；操作前会校验workspace处于active状态。

请求语法

POST /v1/knowledge/reviews/action

请求参数

名称	类型	必填	描述	示例值
review_id	string	是	评审记录ID	`rev-001`
action	string	是	操作类型：`confirm`/`force_accept`/`accept_rewrite`/`reject`/`reject_reupload`	`accept_rewrite`
edited_content	string	否	人工编辑内容（仅 `accept_rewrite` 时使用）	`修改后的文档内容...`
conflict_resolutions	array	否	冲突决策列表	`[{"conflict_id":"c1","resolution":"use_new"}]`

conflict_resolutions数组元素：

名称	类型	必填	描述	示例值
conflict_id	string	是	冲突ID，取 `conflicts` 中的 `id`	`c1`
resolution	string	是	决策：`use_new`/`keep_old`/`merge`/`annotate_divergence`	`use_new`

说明

conflict_resolutions 仅被序列化写入 human_conflict_resolutions 审计字段，服务端不校验conflict_id 是否存在于该评审的 conflicts 中，也不校验 resolution 是否在枚举内。

action语义

action	含义	文档处理	评审记录status
`confirm`	复核确认，原样入库	派发KNOWLEDGE_REVIEW_APPROVE事件（启用chunks + 图谱抽取），文档review_status置 `reviewed`	`reviewed`
`force_accept`	存在矛盾但强制原样入库	同 `confirm`	`reviewed`
`accept_rewrite`	采纳重写内容	以 `edited_content`（缺省用 `rewritten_content`）重新入库，文档review_status置 `reviewed`	`reviewed`
`reject`	拒绝入库	文档置 `deleting` 并派发KNOWLEDGE_DOC_DELETE事件（清理ES chunks + OSS + 快照），文档review_status置 `rejected`	`rejected`
`reject_reupload`	拒绝并要求重新上传	与 `reject` 完全相同的清理流程	`rejected`

参数校验与错误语义

条件	HTTP	errorMessage
`review_id` 缺失或空白	400	`review_id is required`
`action` 缺失或空白	400	`action is required`
`action` 不在5个枚举值内	400	`invalid action: xxx`
workspace不存在	400	`workspace not found: xxx`
workspace非active（停机期间）	400	`workspace is not active: xxx`
`review_id` 在当前workspace下不存在	400	`review not found: xxx`
该评审已执行过人工操作	400	`Review already actioned: xxx`
`action=accept_rewrite` 且 `edited_content` 与 `rewritten_content` 均为空	400	`edited_content or rewritten_content is required for accept_rewrite`

返回参数（data字段内）

返回操作后的评审详情，字段与 GetReviewDetail 完全一致（original_content 固定返回第1页）：

名称	类型	描述	示例值
review_id	string	评审记录ID	`rev-001`
document_id	string	文档ID	`doc-001`
document_name	string	文档名称	`故障处理手册.md`
knowledge_base_id	string	知识库ID	`kb-001`
member_id	string	触发入库的成员ID	`member-001`
logic_score	float	逻辑连贯性评分	`0.82`
noise_score	float	噪音比例评分	`0.12`
contradiction_score	float	内部矛盾度评分	`0.05`
confidence_score	float	综合置信度	`0.85`
source_type	string	来源类型	`upload`
decision	string	系统决策	`pending_review`
decision_reason	string	决策说明文案	`综合置信度 0.55 低于自动入库阈值 0.60`
review_status	string	评审状态，操作后为 `reviewed` 或 `rejected`	`reviewed`
has_contradictions	boolean	是否存在不可解决的自矛盾	`false`
contradictions	string	矛盾详情，JSON字符串	空数组
conflicts	string	冲突详情，JSON字符串	空数组
quality_details	string	质量详情，JSON字符串	`{"logic_issues":[...]}`
original_content	object	分页后的原文（第1页），子字段同GetReviewDetail	见GetReviewDetail
original_logic_score	float	重写前的逻辑评分	`0.61`
original_noise_score	float	重写前的噪音评分	`0.30`
original_contradiction_score	float	重写前的矛盾度评分	`0.10`
original_contradictions	string	重写前的矛盾详情，JSON字符串	空数组
rewrite_needed	boolean	是否需要重写	`true`
rewrite_reason	string	重写触发原因	`噪音分为短板，优先去噪`
rewrite_strategy	string	重写策略	`denoise`
rewritten_content	string	AI重写后的完整内容	`重写后的文档内容...`
rewrite_info_check	string	重写信息保真校验，JSON字符串	`{"missing_facts":[...]}`
human_action	string	本次写入的人工操作类型	`accept_rewrite`
human_edited_content	string	本次写入的人工编辑内容	`修改后的文档内容...`
human_conflict_resolutions	string	本次写入的冲突决策，JSON字符串	`[{"conflict_id":"c1","resolution":"use_new"}]`
human_action_by	string	执行人的成员ID，由服务端注入	`member-001`
human_action_at	string	人工操作时间	`2026-06-01T11:00:00Z`
loop_iterations	integer	已执行的评审-重写迭代轮数	`1`
max_iterations	integer	最大迭代轮数	`3`
created_at	string	创建时间	`2026-06-01T10:00:00Z`
updated_at	string	更新时间	`2026-06-01T11:00:00Z`

示例

请求体：

{"review_id":"rev-001","action":"accept_rewrite","edited_content":"修改后的文档内容..."}

DeleteReview

接口说明

删除单条评审记录，仅允许删除已通过（reviewed）或已拒绝（rejected）的记录。删除为物理删除（数据库行直接DELETE），不可恢复；只清理评审记录本身，不影响已入库的文档。

请求语法

DELETE /v1/knowledge/reviews

请求参数

名称	类型	必填	描述	示例值
review_id	string	是	评审记录ID	`rev-001`

可删除条件

判定依据是评审记录持久化的 status 列，不是响应里的派生字段 review_status：

记录status	产生时机	是否可删除
`reviewed`	执行过 `confirm`/`force_accept`/`accept_rewrite`	可删除
`rejected`	执行过 `reject`/`reject_reupload`	可删除
`active`	记录创建后的初始值，含尚未人工操作的 `pending_review` 记录以及 `auto_accept` 记录	不可删除，返回400

说明

注意：decision=auto_accept 的记录在列表/详情中派生出的 review_status 是 reviewed，但其 status 列仍为 active，因此无法删除，会返回 only reviewed or rejected review can be deleted, current status: active。此为现行实现行为。

错误语义

条件	HTTP	errorMessage
`review_id` 缺失	400	缺少必填参数
`review_id` 为空白字符串	400	`review_id is required`
记录在当前workspace下不存在	400	`review not found: xxx`
记录status不是 `reviewed`/`rejected`	400	`only reviewed or rejected review can be deleted, current status: xxx`

返回参数（data字段内）

名称	类型	描述	示例值
review_id	string	已删除的评审记录ID	`rev-001`
deleted	boolean	是否已删除，固定为 `true`	`true`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"review_id":"rev-001","deleted":true}}

ResolveConflicts

接口说明

逐条决策冲突项。使用统一信封结构返回。本接口只写入冲突决策审计字段（human_conflict_resolutions、human_action_by、human_action_at），不写入 human_action、不改变评审记录status、不触发文档入库或删除；因此调用后 review_status 仍保持 pending，后续仍需调用 ReviewAction 落地。

请求语法

POST /v1/knowledge/reviews/resolve-conflicts

请求参数

名称	类型	必填	描述	示例值
review_id	string	是	评审记录ID	`rev-001`
resolutions	array	是	冲突决策列表，非空，元素字段见下表	`[{"conflict_id":"c1","resolution":"use_new"}]`

resolutions数组元素：

名称	类型	必填	描述	示例值
conflict_id	string	是	冲突ID，取 `conflicts` 中的 `id`	`c1`
resolution	string	是	决策：`use_new`/`keep_old`/`merge`/`annotate_divergence`	`use_new`

说明

与 ReviewAction 一致：服务端整体序列化后存库，不校验conflict_id 是否属于该评审、也不校验resolution 枚举值；重复调用会整体覆盖上一次的决策列表。

错误语义

条件	HTTP	errorMessage
`review_id` 缺失或空白	400	`review_id is required`
`resolutions` 缺失或为空数组	400	`resolutions is required`
记录在当前workspace下不存在	400	`review not found: xxx`

返回参数（data字段内）

返回操作后的评审详情，字段与 GetReviewDetail 完全一致（original_content 固定返回第1页）：

名称	类型	描述	示例值
review_id	string	评审记录ID	`rev-001`
document_id	string	文档ID	`doc-001`
document_name	string	文档名称	`故障处理手册.md`
knowledge_base_id	string	知识库ID	`kb-001`
member_id	string	触发入库的成员ID	`member-001`
logic_score	float	逻辑连贯性评分	`0.82`
noise_score	float	噪音比例评分	`0.12`
contradiction_score	float	内部矛盾度评分	`0.05`
confidence_score	float	综合置信度	`0.85`
source_type	string	来源类型	`upload`
decision	string	系统决策	`pending_review`
decision_reason	string	决策说明文案	`存在与知识库冲突的事实`
review_status	string	评审状态，本接口不改变其取值，通常仍为 `pending`	`pending`
has_contradictions	boolean	是否存在不可解决的自矛盾	`false`
contradictions	string	矛盾详情，JSON字符串	空数组
conflicts	string	冲突详情，JSON字符串	`[{"id":"c1"}]`
quality_details	string	质量详情，JSON字符串	`{"logic_issues":[...]}`
original_content	object	分页后的原文（第1页）	见GetReviewDetail
original_logic_score	float	重写前的逻辑评分	`0.61`
original_noise_score	float	重写前的噪音评分	`0.30`
original_contradiction_score	float	重写前的矛盾度评分	`0.10`
original_contradictions	string	重写前的矛盾详情，JSON字符串	空数组
rewrite_needed	boolean	是否需要重写	`false`
rewrite_reason	string	重写触发原因	`null`
rewrite_strategy	string	重写策略	`null`
rewritten_content	string	AI重写后的完整内容	`null`
rewrite_info_check	string	重写信息保真校验，JSON字符串	`null`
human_action	string	人工操作类型，本接口不写入，仍为null	`null`
human_edited_content	string	人工编辑内容	`null`
human_conflict_resolutions	string	本次写入的冲突决策，JSON字符串	`[{"conflict_id":"c1","resolution":"use_new"}]`
human_action_by	string	本次操作人的成员ID，由服务端注入	`member-001`
human_action_at	string	本次操作时间	`2026-06-01T11:00:00Z`
loop_iterations	integer	已执行的评审-重写迭代轮数	`1`
max_iterations	integer	最大迭代轮数	`3`
created_at	string	创建时间	`2026-06-01T10:00:00Z`
updated_at	string	更新时间	`2026-06-01T11:00:00Z`

示例

请求体：

{"review_id":"rev-001","resolutions":[{"conflict_id":"c1","resolution":"use_new"}]}

BatchReviewAction

接口说明

批量执行知识评审操作，仅支持 confirm / reject，单次最多50条。逐条串行调用单条操作逻辑，部分失败不中断整批，失败项在 results 中给出 error 说明。

请求语法

POST /v1/knowledge/reviews/batch

请求参数

名称	类型	必填	描述	示例值
action	string	是	批量操作类型：`confirm`/`reject`	`confirm`
ids	array	是	评审记录ID列表，非空，单次最多50条	`["rev-001"]`

参数校验与越界行为

条件	HTTP	errorMessage
`action` 缺失或空白	400	`action is required`
`action` 不是 `confirm`/`reject`	400	`batch action only supports confirm or reject, got: xxx`
`ids` 缺失或为空数组	400	`ids is required and must not be empty`
`ids`超过50条	400（不截断）	`ids must not exceed 50 items`
`ids` 含空白元素	400	`ids must not contain blank values`
workspace非active	400	`workspace is not active: xxx`

说明

ids 元素会去除首尾空白后按给定顺序处理；重复ID不去重，第二次会因「已执行过人工操作」而在该项上失败。

返回参数（data字段内）

名称	类型	描述	示例值
total	integer	提交的条目总数	`2`
succeeded	integer	成功条数	`1`
failed	integer	失败条数	`1`
results	array	逐项结果，元素字段见下表	见示例

results数组元素：

名称	类型	描述	示例值
id	string	评审记录ID（回显传入的原始值，未去空白）	`rev-001`
success	boolean	该项是否成功	`true`
error	string	失败原因；成功时该字段不出现在JSON中	`review not found: rev-002`

示例

请求体：

{"action":"confirm","ids":["rev-001","rev-002"]}

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"total":2,"succeeded":1,"failed":1,"results":[{"id":"rev-001","success":true},{"id":"rev-002","success":false,"error":"review not found: rev-002"}]}}

BatchDeleteReviews

接口说明

批量删除评审记录，仅允许删除已通过（reviewed）或已拒绝（rejected）的记录，单次最多50条。逐条预检后对通过校验的记录批量物理删除，部分失败不中断整批。

请求语法

DELETE /v1/knowledge/reviews/batch

请求参数

名称	类型	必填	描述	示例值
ids	array	是	评审记录ID列表，非空，单次最多50条	`["rev-001"]`

参数校验与越界行为

条件	HTTP	errorMessage
`ids` 缺失或为空数组	400	`ids is required and must not be empty`
`ids`超过50条	400（不截断）	`ids must not exceed 50 items`
`ids` 含空白元素	400	`ids must not contain blank values`

逐项失败语义

条件	该项error
记录在当前workspace下不存在	`review not found`
记录status不是 `reviewed`/`rejected`	`review is not deletable, current status: xxx`

返回参数（data字段内）

名称	类型	描述	示例值
total	integer	提交的条目总数	`2`
succeeded	integer	成功条数	`1`
failed	integer	失败条数	`1`
results	array	逐项结果，元素字段见下表	见示例

results数组元素：

名称	类型	描述	示例值
id	string	评审记录ID	`rev-001`
success	boolean	该项是否成功	`true`
error	string	失败原因；成功时该字段不出现在JSON中	`review is not deletable, current status: active`

示例

请求体：

{"ids":["rev-001","rev-002"]}

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"total":2,"succeeded":1,"failed":1,"results":[{"id":"rev-001","success":true},{"id":"rev-002","success":false,"error":"review is not deletable, current status: active"}]}}

KnowledgeReviewTemplates

知识评审重写模板是per-KB资源，用于控制知识评审阶段的重写提示词。读操作需要KB_READ权限，写操作需要KB_WRITE权限。每个知识库最多5个活跃模板。

隔离与约束：

项	值	依据
隔离维度	知识库（KB）维度	唯一键 `uk_kb_name (knowledge_base_id, name)`；Service查询方法均以 `knowledgeBaseId` 为主键条件
每KB活跃模板上限	5	应用层校验，超出返回400
模板名称长度上限	128字符	去空白后计算
章节条数范围	1-15	空数组与超过15条均返回400
标题层级范围	1-3（对应 `#`/`##`/`###`）	越界返回400
渲染后Markdown长度上限	65536字符	超出返回400
权限不足	HTTP 400，`errorMessage` 以 `forbidden:` 开头	并非403

模板对象：

名称	类型	描述	示例值
id	string	模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	模板名称	`客服质检重写模板`
is_default	boolean	是否为KB默认模板	`true`
sections	array	结构化章节数组，元素字段见下表	见示例
content	string	服务端渲染后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:00:00Z`

sections数组元素：

名称	类型	描述	示例值
level	integer	标题层级，1-3；请求省略时默认1	`1`
title	string	章节标题，必填非空，单行	`问题摘要`
guidance	string	撰写指引，必填非空，允许多行	`概括原文中需要重写的核心问题`

ListKnowledgeReviewTemplates

接口说明

返回指定知识库内所有活跃的评审重写模板，按名称升序。需要该KB的KB_READ权限。

请求语法

GET /v1/knowledge/review_templates?knowledge_base_id={knowledge_base_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID（Query参数）	`kb-001`

返回参数（data字段内）

名称	类型	描述	示例值
data	array	模板对象数组，按name升序；无活跃模板时为空数组，元素字段见下表	见示例

data数组元素（模板对象）：

名称	类型	描述	示例值
id	string	模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	模板名称	`客服质检重写模板`
is_default	boolean	是否为KB默认模板	`true`
sections	array	结构化章节数组，元素字段同上文「sections数组元素」	见示例
content	string	服务端渲染后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:00:00Z`

错误语义

条件	HTTP	errorMessage
`knowledge_base_id` 缺失	400	缺少必填参数
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_READ权限	400	`forbidden: kb_read, knowledge base permission denied: xxx`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":[{"id":"tpl-001","knowledge_base_id":"kb-001","name":"客服质检重写模板","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括原文中需要重写的核心问题"}],"content":"# 问题摘要\n概括原文中需要重写的核心问题","created_by":"member-001","created_at":"2026-06-01T10:00:00Z","updated_at":"2026-06-01T10:00:00Z"}]}

CreateKnowledgeReviewTemplate

接口说明

创建知识评审重写模板。name必填、KB内唯一、≤128字符；sections必填，1-15条；每个section的title必填非空且单行，guidance必填非空且允许多行但不允许空行，level可选且范围1-3、默认1。每个知识库最多5个活跃模板，超过5个、名称重复或章节校验失败时返回400；is_default=true时清除同KB其他默认模板。需要该KB的KB_WRITE权限。

请求语法

POST /v1/knowledge/review_templates?knowledge_base_id={knowledge_base_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID（Query参数）	`kb-001`
name	string	是	模板名称，≤128字符，KB内唯一	`客服质检重写模板`
is_default	boolean	否	是否设为KB默认模板，缺省false；true时清除同KB其他默认模板	`true`
sections	array	是	章节列表，1-15条，按文档顺序排列	见下表

sections数组元素：

名称	类型	必填	描述	示例值
level	integer	否	标题层级，1-3，缺省1	`1`
title	string	是	章节标题，去空白后非空，单行	`问题摘要`
guidance	string	是	撰写指引，去空白后非空，允许多行但不允许空行	`概括原文中需要重写的核心问题`

校验规则与错误语义

条件	HTTP	errorMessage
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_WRITE权限	400	`forbidden: kb_write, knowledge base permission denied: xxx`
`sections` 缺失或为空数组	400	`sections must not be empty`
`sections` 超过15条	400	`sections must not contain more than 15 entries`
`sections[i]` 为null	400	`sections[i] must not be null`
`name` 缺失或全空白	400	`name must not be blank`
`name` 去空白后超过128字符	400	`name must not exceed 128 characters`
KB内活跃模板已达5个	400	`knowledge base template limit (5) reached`
`name` 在KB内已存在（活跃模板）	400	`template name already exists in this knowledge base`
`sections[i].title` 缺失或全空白	400	`sections[i].title must not be blank`
`sections[i].title` 含换行	400	`sections[i].title must not contain line breaks`
`sections[i].guidance` 缺失或全空白	400	`sections[i].guidance must not be blank`
`sections[i].guidance` 含空行	400	`sections[i].guidance must not contain blank lines`
`sections[i].level` 不在1-3	400	`sections[i].level must be between 1 and 3`
渲染后Markdown超过65536字符	400	`rendered template content must not exceed 65536 characters`
渲染-解析roundtrip不一致	400	`sections[i] cannot be represented as template Markdown`

说明

title与guidance会被逐行去除首尾空白后归一化落库，返回值是归一化后的结果。

返回参数（data字段内）

名称	类型	描述	示例值
id	string	新建模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	模板名称（去空白后）	`客服质检重写模板`
is_default	boolean	是否为KB默认模板	`true`
sections	array	结构化章节数组，元素字段同上文「sections数组元素」	见示例
content	string	服务端渲染后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID，服务端注入	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:00:00Z`

示例

请求体：

{"name":"客服质检重写模板","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括原文中需要重写的核心问题"},{"level":2,"title":"建议改写","guidance":"输出可直接入库的重写后内容"}]}

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"id":"tpl-001","knowledge_base_id":"kb-001","name":"客服质检重写模板","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括原文中需要重写的核心问题"},{"level":2,"title":"建议改写","guidance":"输出可直接入库的重写后内容"}],"content":"# 问题摘要\n概括原文中需要重写的核心问题\n\n## 建议改写\n输出可直接入库的重写后内容","created_by":"member-001","created_at":"2026-06-01T10:00:00Z","updated_at":"2026-06-01T10:00:00Z"}}

GetKnowledgeReviewTemplate

接口说明

返回模板详情；不存在时返回200且data=null。需要该KB的KB_READ权限。

请求语法

GET /v1/knowledge/review_templates/detail?knowledge_base_id={knowledge_base_id}&template_id={template_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID	`kb-001`
template_id	string	是	模板ID	`tpl-001`

返回参数（data字段内）

模板不存在、不属于该KB或已软删时，data 为 null（HTTP仍为200、errorCode仍为0）。存在时字段如下：

名称	类型	描述	示例值
id	string	模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	模板名称	`客服质检重写模板`
is_default	boolean	是否为KB默认模板	`true`
sections	array	结构化章节数组，元素字段同上文「sections数组元素」	见示例
content	string	服务端渲染后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:00:00Z`

错误语义

条件	HTTP	errorMessage
`knowledge_base_id` 或 `template_id` 缺失	400	缺少必填参数
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_READ权限	400	`forbidden: kb_read, knowledge base permission denied: xxx`
模板不存在	200	`data` 为null，不报错

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"id":"tpl-001","knowledge_base_id":"kb-001","name":"客服质检重写模板","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括原文中需要重写的核心问题"}],"content":"# 问题摘要\n概括原文中需要重写的核心问题","created_by":"member-001","created_at":"2026-06-01T10:00:00Z","updated_at":"2026-06-01T10:00:00Z"}}

模板不存在：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":null}

UpdateKnowledgeReviewTemplate

接口说明

按template_id更新模板名称、章节或默认标记。三个body字段均为可选、按需部分更新：name省略或为空白时不改名，改名需保持KB内唯一；sections传入非空数组时整体替换并重建模板内容，省略或传空数组时保留原章节；is_default=true时清除KB内其他默认标记并把本模板设为默认，显式传false时取消本模板的默认标记，省略时不动。请求体本身不可为null。模板不存在返回400。需要该KB的KB_WRITE权限。

请求语法

PUT /v1/knowledge/review_templates?knowledge_base_id={knowledge_base_id}&template_id={template_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID（Query参数）	`kb-001`
template_id	string	是	模板ID（Query参数）	`tpl-001`
name	string	否	模板名称，≤128字符，KB内唯一；省略或空白时保持原名	`客服质检重写模板 v2`
is_default	boolean	否	true时设为默认并清除同KB其他默认模板；false时取消当前模板默认标记；省略时不变更	`true`
sections	array	否	章节列表，1-15条，按文档顺序排列；传入非空数组时整体替换章节并重建模板内容，省略或空数组时保持原章节	见下表

sections数组元素：

名称	类型	必填	描述	示例值
level	integer	否	标题层级，1-3，缺省1	`1`
title	string	是	章节标题，去空白后非空，单行	`问题摘要`
guidance	string	是	撰写指引，去空白后非空，允许多行但不允许空行	`概括原文中需要重写的核心问题`

校验规则与错误语义

条件	HTTP	errorMessage
请求体缺失	400	`request body is required`
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_WRITE权限	400	`forbidden: kb_write, knowledge base permission denied: xxx`
模板不存在、不属于该KB或已软删	400	`review template not found in this knowledge base`
`name` 去空白后超过128字符	400	`name must not exceed 128 characters`
新 `name` 与KB内其他活跃模板重名	400	`template name already exists in this knowledge base`
`sections` 校验失败（条数、title、guidance、level、roundtrip）	400	同 CreateKnowledgeReviewTemplate 的对应错误信息

返回参数（data字段内）

名称	类型	描述	示例值
id	string	模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	更新后的模板名称	`客服质检重写模板 v2`
is_default	boolean	更新后的默认标记	`true`
sections	array	更新后的结构化章节数组，元素字段同上表	见示例
content	string	重建后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID（不随更新变化）	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:10:00Z`

示例

请求体：

{"name":"客服质检重写模板 v2","sections":[{"level":1,"title":"问题摘要","guidance":"概括问题"}]}

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"id":"tpl-001","knowledge_base_id":"kb-001","name":"客服质检重写模板 v2","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括问题"}],"content":"# 问题摘要\n概括问题","created_by":"member-001","created_at":"2026-06-01T10:00:00Z","updated_at":"2026-06-01T10:10:00Z"}}

DeleteKnowledgeReviewTemplate

接口说明

软删指定模板（status=deleted、清空内容、name改写规避唯一键冲突），重复删除幂等。需要该KB的KB_WRITE权限。

请求语法

DELETE /v1/knowledge/review_templates?knowledge_base_id={knowledge_base_id}&template_id={template_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID	`kb-001`
template_id	string	是	模板ID	`tpl-001`

删除语义

项	行为
删除方式	软删除：`status` 置 `deleted`，`content` 与 `parsed_json` 清空为空串，数据行保留
名称墓碑化	`name` 改写为 `原名 + "__del_" + 模板 ID 前 8 位`，超过128字符时保留尾部，规避 `uk_kb_name` 冲突，因此原名可立即重建
幂等性	模板不存在或已软删时静默返回`{"deleted": true}`，不报错
默认标记	软删不显式清除 `is_default`；运行期注入在模板失效时回落为「无模板」行为
与评审记录删除的差异	评审记录（DeleteReview/BatchDeleteReviews）为物理删除，模板为软删除

错误语义

条件	HTTP	errorMessage
`knowledge_base_id` 或 `template_id` 缺失	400	缺少必填参数
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_WRITE权限	400	`forbidden: kb_write, knowledge base permission denied: xxx`

返回参数（data字段内）

名称	类型	描述	示例值
deleted	boolean	是否已删除，固定为 `true`	`true`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"deleted":true}}

SetDefaultKnowledgeReviewTemplate

接口说明

将指定模板设为KB默认评审重写模板（同一事务内清除同KB其他模板的默认标记）。需要该KB的KB_WRITE权限。

请求语法

POST /v1/knowledge/review_templates/set_default?knowledge_base_id={knowledge_base_id}&template_id={template_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID	`kb-001`
template_id	string	是	模板ID	`tpl-001`

错误语义

条件	HTTP	errorMessage
`knowledge_base_id` 或 `template_id` 缺失	400	缺少必填参数
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_WRITE权限	400	`forbidden: kb_write, knowledge base permission denied: xxx`
模板不存在、不属于该KB或已软删	400	`review template not found in this knowledge base`

返回参数（data字段内）

名称	类型	描述	示例值
id	string	模板ID	`tpl-001`
knowledge_base_id	string	知识库ID	`kb-001`
name	string	模板名称	`客服质检重写模板`
is_default	boolean	设置后固定为 `true`	`true`
sections	array	结构化章节数组，元素字段同上文「sections数组元素」	见示例
content	string	服务端渲染后的Markdown模板原文	`# 问题摘要...`
created_by	string	创建人member ID	`member-001`
created_at	string	创建时间，UTC Z格式	`2026-06-01T10:00:00Z`
updated_at	string	更新时间，UTC Z格式	`2026-06-01T10:00:00Z`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"id":"tpl-001","knowledge_base_id":"kb-001","name":"客服质检重写模板","is_default":true,"sections":[{"level":1,"title":"问题摘要","guidance":"概括原文中需要重写的核心问题"}],"content":"# 问题摘要\n概括原文中需要重写的核心问题","created_by":"member-001","created_at":"2026-06-01T10:00:00Z","updated_at":"2026-06-01T10:00:00Z"}}

ClearDefaultKnowledgeReviewTemplate

接口说明

清除KB内所有模板的is_default标记，运行期注入回落「无模板」行为。KB内本就没有默认模板时也返回成功（幂等）。需要该KB的KB_WRITE权限。

请求语法

DELETE /v1/knowledge/review_templates/default?knowledge_base_id={knowledge_base_id}

请求参数

名称	类型	必填	描述	示例值
knowledge_base_id	string	是	知识库ID	`kb-001`

错误语义

条件	HTTP	errorMessage
`knowledge_base_id` 缺失	400	缺少必填参数
KB不存在或不属于当前workspace	400	`knowledge base not found: xxx`
无KB_WRITE权限	400	`forbidden: kb_write, knowledge base permission denied: xxx`

返回参数（data字段内）

名称	类型	描述	示例值
cleared	boolean	是否已清除默认标记，固定为 `true`	`true`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"cleared":true}}

ReviewSettings

评审设置是workspace维度的单行配置（knowledge_review_settings.workspace_id 唯一键），workspace由API Key解析注入。读写均不要求管理员角色。

GetReviewSettings

接口说明

获取当前工作空间的知识评审策略设置。使用统一信封结构返回。workspace尚未配置过时，按默认值构造响应但不落库，此时 created_at 与 updated_at 为 null。

请求语法

GET /v1/knowledge/reviewSettings

请求参数

无。

返回参数（data字段内）

名称	类型	描述	示例值
workspace_id	string	工作空间ID	`ws-001`
high_threshold	float	自动通过阈值（置信度高于此分数自动入库；低于此分数且开启重写时触发文档重写）	`0.8`
rewrite_enabled	boolean	是否开启文档重写	`true`
conflict_detection_enabled	boolean	是否开启冲突检测	`true`
rewrite_auto_ingest_enabled	boolean	重写文档是否自动入库	`false`
logic_rewrite_threshold	float	逻辑重写触发阈值（已弃用：重写改为置信度低于 `high_threshold` 时触发，此字段不再参与触发）	`0.5`
noise_rewrite_threshold	float	噪音重写触发阈值（已弃用：同上）	`0.3`
max_rewrite_iterations	integer	最大重写迭代次数	`3`
created_at	string	创建时间；从未配置过时为 `null`	`2026-06-01T00:00:00Z`
updated_at	string	更新时间；从未配置过时为 `null`	`2026-06-01T10:00:00Z`

未配置时的默认值

字段	默认值	来源
high_threshold	`0.6`	系统默认值
rewrite_enabled	`true`	服务层构造默认设置时写入
conflict_detection_enabled	`true`	服务层构造默认设置时写入
rewrite_auto_ingest_enabled	`true`	实体字段默认值
logic_rewrite_threshold	`0.4`	系统默认值
noise_rewrite_threshold	`0.4`	系统默认值
max_rewrite_iterations	`3`	系统默认值

决策与重写触发规则

规则	行为
`confidence >= high_threshold`	决策 `auto_accept`，直接入库
`confidence < high_threshold`	决策 `pending_review`，需人工评审；开启重写时按短板选择 `restructure`（逻辑分低）或 `denoise`（噪音分高）
存在不可解决的自矛盾	无论置信度多高，决策强制 `pending_review`
存在high级幻觉	无论置信度多高，决策强制 `pending_review`

示例

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":{"workspace_id":"ws-001","high_threshold":0.8,"rewrite_enabled":true,"conflict_detection_enabled":true,"rewrite_auto_ingest_enabled":false,"logic_rewrite_threshold":0.5,"noise_rewrite_threshold":0.3,"max_rewrite_iterations":3,"created_at":"2026-06-01T00:00:00Z","updated_at":"2026-06-01T10:00:00Z"}}

UpdateReviewSettings

接口说明

更新当前工作空间的知识评审策略（部分更新语义，仅传入的字段被修改）。使用统一信封结构返回。workspace尚无配置行时首次调用即插入新行并对未传字段落默认值。

请求语法

PUT /v1/knowledge/reviewSettings

请求参数

名称	类型	必填	描述	示例值
high_threshold	float	否	自动通过阈值（同时作为文档重写的触发线：置信度低于此值且开启重写时触发）	`0.85`
rewrite_enabled	boolean	否	是否开启文档重写	`true`
conflict_detection_enabled	boolean	否	是否开启冲突检测	`true`
rewrite_auto_ingest_enabled	boolean	否	重写文档是否自动入库	`true`
logic_rewrite_threshold	float	否	逻辑重写触发阈值（已弃用，不再参与触发）	`0.5`
noise_rewrite_threshold	float	否	噪音重写触发阈值（已弃用，不再参与触发）	`0.3`
max_rewrite_iterations	integer	否	最大重写迭代次数	`5`

返回参数

data 固定为 null，以信封 errorCode: 0 表示成功。更新后的完整配置需再调用 GetReviewSettings 获取。

示例

请求体：

{"high_threshold":0.85,"rewrite_auto_ingest_enabled":true}

正常返回：

{"errorCode":0,"errorMessage":null,"requestId":"req-xxx","data":null}