3585219637
Some checks failed
Backend Maven CI / backend-local (push) Has been cancelled
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3819 lines
133 KiB
YAML
3819 lines
133 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse Knowledge API
|
||
description: |
|
||
Muse 知识模块完整 API 契约，覆盖管理员全局知识库治理、用户知识库管理、
|
||
知识草稿确认、作品知识绑定、已安装知识库、资料处理和发布准备。
|
||
所有接口通过 X-API-Version Header 进行版本控制。
|
||
version: 1.0.0
|
||
license:
|
||
name: Proprietary
|
||
contact:
|
||
name: Muse Team
|
||
|
||
servers:
|
||
- url: /
|
||
description: 同源 API 网关
|
||
|
||
tags:
|
||
- name: Admin-Knowledge
|
||
description: 管理员全局知识库治理、授权策略、来源事件和投影任务
|
||
- name: Knowledge-Entity
|
||
description: 知识实体查询、更新和关联关系
|
||
- name: Knowledge-Graph
|
||
description: 知识图谱可视化
|
||
- name: Knowledge-Draft
|
||
description: 知识草稿确认、忽略和重验
|
||
- name: Knowledge-Base
|
||
description: 用户知识库创建、维护、资料管理、版本、发布和导出
|
||
- name: Installed-KB
|
||
description: 已安装知识库管理
|
||
- name: Knowledge-Binding
|
||
description: 作品知识来源绑定与解绑
|
||
- name: Knowledge-Retrieval
|
||
description: 作品已绑定知识来源检索
|
||
- name: Local-Knowledge
|
||
description: 作品局域知识库
|
||
|
||
components:
|
||
securitySchemes:
|
||
adminBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 管理后台认证 scheme，仅用于 /admin-api/** 接口，admin-api token 与 app-api token 不互通。
|
||
appBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 用户端认证 scheme，仅用于 /app-api/** 接口，app-api token 与 admin-api token 不互通。
|
||
|
||
paths:
|
||
# ============================================================
|
||
# Admin Knowledge Management（设计文档 Section 3.3）
|
||
# ============================================================
|
||
|
||
/admin-api/muse/knowledge/global-kbs:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库列表
|
||
operationId: listGlobalKnowledgeBases
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: keyword
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 搜索关键词
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [active, disabled, processing, failed]
|
||
description: 按状态筛选
|
||
- name: category
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 按分类筛选
|
||
responses:
|
||
'200':
|
||
description: 全局知识库分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 GlobalKBSummary：
|
||
- kbId: string (知识库 ID)
|
||
- name: string (名称)
|
||
- description: string (说明)
|
||
- category: string (分类)
|
||
- currentVersion: integer (当前激活版本)
|
||
- status: string (active/disabled/processing/failed)
|
||
- activePolicyVersion: integer (当前授权策略版本)
|
||
- documentCount: integer (资料数量)
|
||
- bindingCount: integer (绑定作品数量)
|
||
- createdAt: date-time
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 创建全局知识库
|
||
operationId: createGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [name, commandId]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: 知识库名称
|
||
description:
|
||
type: string
|
||
description: 知识库说明
|
||
category:
|
||
type: string
|
||
description: 分类标签
|
||
visibilityScope:
|
||
type: string
|
||
enum: [all, role_based, custom]
|
||
description: 可见范围
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [draft]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库详情
|
||
description: 返回当前版本、授权策略、来源状态和处理摘要
|
||
operationId: getGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 全局知识库详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
category:
|
||
type: string
|
||
visibilityScope:
|
||
type: string
|
||
currentVersion:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [active, disabled, processing, failed]
|
||
activePolicyVersion:
|
||
type: integer
|
||
documentCount:
|
||
type: integer
|
||
bindingCount:
|
||
type: integer
|
||
processingSummary:
|
||
type: object
|
||
properties:
|
||
searchableCount:
|
||
type: integer
|
||
generativeCount:
|
||
type: integer
|
||
failedCount:
|
||
type: integer
|
||
processingCount:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
patch:
|
||
tags: [Admin-Knowledge]
|
||
summary: 更新全局知识库
|
||
description: 更新名称、说明、分类、可见范围和停用原因
|
||
operationId: updateGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
category:
|
||
type: string
|
||
visibilityScope:
|
||
type: string
|
||
enum: [all, role_based, custom]
|
||
disableReason:
|
||
type: string
|
||
description: 停用时必填原因
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: string
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/documents:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库资料列表
|
||
description: 返回资料列表、处理状态、版本和来源摘要
|
||
operationId: listGlobalKBDocuments
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: processingStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending_scan, scan_blocked, pending_process, processing, searchable, generative, failed, deleting]
|
||
description: 按处理状态筛选
|
||
responses:
|
||
'200':
|
||
description: 资料分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 DocumentSummary：
|
||
- documentId: string
|
||
- name: string
|
||
- type: string (file/entry/link)
|
||
- size: integer (字节数)
|
||
- version: integer
|
||
- processingStatus: string
|
||
- scanStatus: string
|
||
- isSearchable: boolean
|
||
- isGenerative: boolean
|
||
- failureReason: string
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 上传或登记全局知识库资料
|
||
description: 上传文件或登记外链资料，返回 documentId 和处理任务
|
||
operationId: uploadGlobalKBDocument
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
description: 上传文件（与 entryContent/linkUrl 三选一）
|
||
entryContent:
|
||
type: string
|
||
description: 手写条目内容
|
||
linkUrl:
|
||
type: string
|
||
format: uri
|
||
description: |
|
||
外链资料 URL。服务端必须执行 SSRF 防护：仅允许配置 allowlist 内的域名或协议，
|
||
拦截私网/环回/链路本地 IP 和 DNS 重绑定，使用隔离抓取环境下载，
|
||
对抓取文件做类型校验和恶意文件扫描，并以异步处理状态返回扫描、解析和索引结果。
|
||
sourceDescription:
|
||
type: string
|
||
description: 来源说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 上传成功，进入待扫描
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: integer
|
||
format: int64
|
||
scanTaskId:
|
||
type: string
|
||
processingStatus:
|
||
type: string
|
||
enum: [pending_scan]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/documents/{documentId}:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库资料详情
|
||
description: 返回资料详情、版本、解析状态和索引状态
|
||
operationId: getGlobalKBDocument
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 资料详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
size:
|
||
type: integer
|
||
currentVersion:
|
||
type: integer
|
||
scanStatus:
|
||
type: string
|
||
processingStatus:
|
||
type: string
|
||
isSearchable:
|
||
type: boolean
|
||
isGenerative:
|
||
type: boolean
|
||
parseStatus:
|
||
type: string
|
||
indexStatus:
|
||
type: string
|
||
failureReason:
|
||
type: string
|
||
versions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
processingStatus:
|
||
type: string
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
delete:
|
||
tags: [Admin-Knowledge]
|
||
summary: 停用全局知识库资料
|
||
description: 停用资料，触发来源事件和索引刷新
|
||
operationId: deleteGlobalKBDocument
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
reason:
|
||
type: string
|
||
description: 停用原因
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 停用成功，资料进入删除同步
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
sourceEventId:
|
||
type: string
|
||
affectedBindings:
|
||
type: integer
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/documents/{documentId}/versions:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 新增全局知识库资料版本
|
||
description: 上传新版本文件，触发处理任务
|
||
operationId: createGlobalKBDocumentVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
sourceDescription:
|
||
type: string
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 新版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
newVersion:
|
||
type: integer
|
||
processingTaskId:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/versions:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库版本列表
|
||
description: 返回版本列表和发布摘要
|
||
operationId: listGlobalKBVersions
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 版本列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
currentActiveVersion:
|
||
type: integer
|
||
versions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: integer
|
||
isActive:
|
||
type: boolean
|
||
documentCount:
|
||
type: integer
|
||
searchableCount:
|
||
type: integer
|
||
generativeCount:
|
||
type: integer
|
||
changeSummary:
|
||
type: string
|
||
activatedAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/versions/{version}/activate:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 激活全局知识库版本
|
||
description: 激活指定版本，必须带 commandId 和影响预览
|
||
operationId: activateGlobalKBVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: version
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 激活原因
|
||
impactPreviewReference:
|
||
type: string
|
||
description: 影响预览引用 ID
|
||
responses:
|
||
'200':
|
||
description: 激活成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
activeVersion:
|
||
type: integer
|
||
sourceEventId:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库授权策略列表
|
||
description: 返回授权策略列表和 active 摘要
|
||
operationId: listGlobalKBAccessPolicies
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 授权策略列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
activePolicyVersion:
|
||
type: integer
|
||
policies:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
policyId:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
isActive:
|
||
type: boolean
|
||
scope:
|
||
type: string
|
||
description: 授权范围（all_users/role_based/custom）
|
||
canSearch:
|
||
type: boolean
|
||
canGenerate:
|
||
type: boolean
|
||
canExport:
|
||
type: boolean
|
||
canCopy:
|
||
type: boolean
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
publishedAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies/drafts:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 保存全局知识库授权策略草稿
|
||
operationId: saveGlobalKBAccessPolicyDraft
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, scope]
|
||
properties:
|
||
scope:
|
||
type: string
|
||
description: 授权范围
|
||
allowedRoles:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 角色列表（scope=role_based 时必填）
|
||
canSearch:
|
||
type: boolean
|
||
default: true
|
||
canGenerate:
|
||
type: boolean
|
||
default: false
|
||
canExport:
|
||
type: boolean
|
||
default: false
|
||
canCopy:
|
||
type: boolean
|
||
default: false
|
||
externalScope:
|
||
type: string
|
||
description: 外发范围限制
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
description: 过期时间
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 草稿保存成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
draftId:
|
||
type: string
|
||
draftVersion:
|
||
type: integer
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies/drafts/{draftId}/publish:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 发布全局知识库授权策略
|
||
description: 发布授权策略，必须带 commandId 和影响预览
|
||
operationId: publishGlobalKBAccessPolicy
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: draftId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 发布原因
|
||
impactPreviewReference:
|
||
type: string
|
||
description: 影响预览引用 ID
|
||
responses:
|
||
'200':
|
||
description: 发布成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
activePolicyVersion:
|
||
type: integer
|
||
sourceEventId:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/enable:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 启用全局知识库
|
||
operationId: enableGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: 启用成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [active]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/disable:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 停用全局知识库
|
||
description: 停用全局知识库，触发来源事件
|
||
operationId: disableGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
description: 停用原因
|
||
responses:
|
||
'200':
|
||
description: 停用成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [disabled]
|
||
sourceEventId:
|
||
type: string
|
||
affectedBindings:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/impact-preview:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库影响预览
|
||
description: 返回授权、绑定、检索、导出和运行任务影响
|
||
operationId: previewGlobalKBImpact
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [actionType]
|
||
properties:
|
||
actionType:
|
||
type: string
|
||
enum: [enable, disable, version_activate, policy_publish, document_delete]
|
||
description: 预览的操作类型
|
||
targetVersion:
|
||
type: integer
|
||
description: 目标版本（version_activate 时必填）
|
||
responses:
|
||
'200':
|
||
description: 影响预览结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
impactId:
|
||
type: string
|
||
description: 影响预览引用 ID，用于后续命令
|
||
affectedBindings:
|
||
type: integer
|
||
affectedInstalls:
|
||
type: integer
|
||
affectedWorks:
|
||
type: integer
|
||
runningTasks:
|
||
type: integer
|
||
riskSummary:
|
||
type: string
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/reindex:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 重建全局知识库索引
|
||
description: 重建索引，返回处理任务
|
||
operationId: reindexGlobalKnowledgeBase
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
scope:
|
||
type: string
|
||
enum: [full, incremental, failed_only]
|
||
default: full
|
||
description: 重建范围
|
||
responses:
|
||
'200':
|
||
description: 重建索引任务已创建
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued]
|
||
pollUrl:
|
||
type: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/processing-tasks:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 全局知识库资料处理任务状态
|
||
description: 查询资料处理、索引和投影任务状态
|
||
operationId: listGlobalKBProcessingTasks
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [queued, scanning, cleaning, parsing, indexing, completed, failed, cancelling]
|
||
description: 按任务状态筛选
|
||
responses:
|
||
'200':
|
||
description: 处理任务分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 ProcessingTaskSummary：
|
||
- taskId: string
|
||
- taskType: string (scan/clean/parse/index/export)
|
||
- status: string
|
||
- stage: string
|
||
- documentCount: integer
|
||
- failedCount: integer
|
||
- startedAt: date-time
|
||
- updatedAt: date-time
|
||
- failureReason: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/global-kbs/{kbId}/source-events:
|
||
post:
|
||
tags: [Admin-Knowledge]
|
||
summary: 触发全局知识库来源事件
|
||
description: 传播 SourceEventType、SourceStatus、SourceActionPolicy 和原因归因
|
||
operationId: triggerGlobalKBSourceEvent
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, eventType, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
eventType:
|
||
type: string
|
||
enum: [status_changed, version_changed, policy_changed, document_deleted, kb_disabled, kb_enabled]
|
||
reason:
|
||
type: string
|
||
targetVersion:
|
||
type: integer
|
||
actionPolicy:
|
||
type: string
|
||
enum: [allowed, read_only, blocked, needs_recheck]
|
||
responses:
|
||
'200':
|
||
description: 来源事件已触发
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
eventId:
|
||
type: string
|
||
affectedTargets:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/admin-api/muse/knowledge/source-bindings:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 查询来源绑定和状态
|
||
operationId: listSourceBindings
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: sourceType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [global_kb, market_kb, user_kb]
|
||
description: 来源类型
|
||
- name: sourceStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [active, stale, revoked, recalled, delisted, blocked, owner_missing, unauthorized]
|
||
description: 来源状态
|
||
- name: targetOwner
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [content, knowledge, ai, market, account]
|
||
description: 目标 owner
|
||
responses:
|
||
'200':
|
||
description: 来源绑定分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 SourceBindingSummary：
|
||
- bindingId: string
|
||
- sourceType: string
|
||
- sourceId: string
|
||
- sourceVersion: integer
|
||
- sourceStatus: string
|
||
- actionPolicy: string
|
||
- targetOwner: string
|
||
- targetId: string
|
||
- affectedWorkCount: integer
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/drafts:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 查询知识草稿治理摘要
|
||
operationId: listKnowledgeDraftsGovernance
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending, confirmed, ignored, conflicted, failed]
|
||
- name: sourceType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [extraction, import, external]
|
||
responses:
|
||
'200':
|
||
description: 知识草稿治理摘要分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 KnowledgeDraftGovernanceSummary：
|
||
- draftId: string
|
||
- workId: string
|
||
- workTitle: string
|
||
- entityType: string
|
||
- sourceType: string
|
||
- status: string
|
||
- conflictCount: integer
|
||
- createdAt: date-time
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/knowledge/projection-tasks:
|
||
get:
|
||
tags: [Admin-Knowledge]
|
||
summary: 查询知识投影和索引任务
|
||
operationId: listProjectionTasks
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [queued, running, completed, failed]
|
||
responses:
|
||
'200':
|
||
description: 投影和索引任务分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 ProjectionTaskSummary：
|
||
- taskId: string
|
||
- taskType: string
|
||
- status: string
|
||
- sourceKbId: string
|
||
- sourceKbName: string
|
||
- affectedProjectionCount: integer
|
||
- startedAt: date-time
|
||
- completedAt: date-time
|
||
- failureReason: string
|
||
|
||
# ============================================================
|
||
# App Knowledge Entity & Graph（保留并更新路径前缀）
|
||
# ============================================================
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/works/{workId}/entities:
|
||
get:
|
||
tags: [Knowledge-Entity]
|
||
summary: 获取作品知识实体列表
|
||
operationId: listEntities
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [confirmed, draft, conflicted]
|
||
- name: type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [character, location, event, item, concept, note]
|
||
responses:
|
||
'200':
|
||
description: 实体列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
entityId:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
enum: [character, location, event, item, concept, note]
|
||
status:
|
||
type: string
|
||
enum: [confirmed, draft, conflicted]
|
||
description:
|
||
type: string
|
||
sourceRef:
|
||
type: string
|
||
description: 来源引用
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/entities/{entityId}:
|
||
get:
|
||
tags: [Knowledge-Entity]
|
||
summary: 获取知识实体详情
|
||
description: 返回实体详情（含关联关系和来源引用）
|
||
operationId: getEntity
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: entityId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 实体详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
entityId:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
status:
|
||
type: string
|
||
description:
|
||
type: string
|
||
attributes:
|
||
type: object
|
||
additionalProperties: true
|
||
description: 自定义属性键值对
|
||
sourceRefs:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
sourceType:
|
||
type: string
|
||
sourceId:
|
||
type: string
|
||
sourceVersion:
|
||
type: integer
|
||
confidence:
|
||
type: number
|
||
format: float
|
||
relations:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
relationId:
|
||
type: string
|
||
targetEntityId:
|
||
type: string
|
||
targetEntityName:
|
||
type: string
|
||
relationType:
|
||
type: string
|
||
description:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
put:
|
||
tags: [Knowledge-Entity]
|
||
summary: 更新知识实体
|
||
operationId: updateEntity
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: entityId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
attributes:
|
||
type: object
|
||
additionalProperties: true
|
||
description: 自定义属性键值对
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
entityId:
|
||
type: string
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/entities/{entityId}/relations:
|
||
get:
|
||
tags: [Knowledge-Entity]
|
||
summary: 获取实体关联关系
|
||
operationId: listRelations
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: entityId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 关系列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
relationId:
|
||
type: string
|
||
sourceEntityId:
|
||
type: string
|
||
targetEntityId:
|
||
type: string
|
||
targetEntityName:
|
||
type: string
|
||
relationType:
|
||
type: string
|
||
description:
|
||
type: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Knowledge-Entity]
|
||
summary: 创建知识关系
|
||
operationId: createRelation
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: entityId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: 源实体
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [targetEntityId, relationType, commandId]
|
||
properties:
|
||
targetEntityId:
|
||
type: integer
|
||
format: int64
|
||
relationType:
|
||
type: string
|
||
example: "knows"
|
||
description:
|
||
type: string
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
relationId:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/works/{workId}/graph:
|
||
get:
|
||
tags: [Knowledge-Graph]
|
||
summary: 获取知识图谱数据
|
||
operationId: getKnowledgeGraph
|
||
security:
|
||
- appBearerAuth: []
|
||
description: 返回节点和边的 JSON，用于前端可视化渲染
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: depth
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 3
|
||
default: 2
|
||
description: 图谱展开深度
|
||
- name: entityType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [character, location, event, item, concept, note]
|
||
description: 按实体类型筛选
|
||
responses:
|
||
'200':
|
||
description: 图谱数据（nodes + edges）
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
nodes:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
status:
|
||
type: string
|
||
edges:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
source:
|
||
type: string
|
||
target:
|
||
type: string
|
||
relationType:
|
||
type: string
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/works/{workId}/knowledge-retrievals:
|
||
post:
|
||
tags: [Knowledge-Retrieval]
|
||
summary: 检索作品已绑定知识来源
|
||
description: |
|
||
用户在 Studio 主动触发作品知识检索。后端先校验作品归属，再走 Knowledge Retrieval owner API 的用途门、
|
||
授权快照门、来源状态门和 RAGFlow 检索。无绑定、未授权、缺 dataset、检索失败或无 chunk 均以
|
||
status=empty + omittedReason 返回，供前端透明反馈，不静默省略。
|
||
operationId: retrieveKnowledgeForWork
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, question]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 检索关联追踪键，用于日志关联；本接口不写业务事实
|
||
question:
|
||
type: string
|
||
maxLength: 500
|
||
description: 检索问题
|
||
topK:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 20
|
||
default: 5
|
||
description: 返回片段上限
|
||
responses:
|
||
'200':
|
||
description: 检索结果或透明降级原因
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [ok, empty]
|
||
omittedReason:
|
||
type: string
|
||
nullable: true
|
||
description: empty 时的总体原因，如 no_binding/no_dataset/not_authorized/retrieval_failed/no_chunk/blank_question
|
||
chunks:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
sourceKbId:
|
||
type: string
|
||
datasetId:
|
||
type: string
|
||
documentId:
|
||
type: string
|
||
nullable: true
|
||
contentSummary:
|
||
type: string
|
||
description: 脱敏截断后的片段摘要
|
||
similarity:
|
||
type: number
|
||
format: double
|
||
nullable: true
|
||
sourceOwner:
|
||
type: string
|
||
sourceObjectVersion:
|
||
type: string
|
||
nullable: true
|
||
authorizationSnapshotId:
|
||
type: string
|
||
sourceStatus:
|
||
type: string
|
||
nullable: true
|
||
allowedPurpose:
|
||
type: string
|
||
omittedSources:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
enum: [not_authorized, stale_source, token_budget, no_dataset]
|
||
sourceStatus:
|
||
type: string
|
||
nullable: true
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
|
||
# ============================================================
|
||
# App Knowledge Bases（设计文档 Section 4.6）
|
||
# ============================================================
|
||
|
||
/app-api/muse/knowledge-bases:
|
||
get:
|
||
tags: [Knowledge-Base]
|
||
summary: 用户知识库和已安装知识库
|
||
operationId: listKnowledgeBases
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: keyword
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 搜索关键词
|
||
- name: source
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [user, installed, account_available, global]
|
||
description: 按来源筛选
|
||
- name: processingStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [draft, processing, searchable, generative, partial_failed, disabled, authorization_expired, delisted, deleting]
|
||
description: 按处理状态筛选
|
||
- name: authorizationStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [valid, expired, revoked]
|
||
description: 按授权状态筛选
|
||
responses:
|
||
'200':
|
||
description: 知识库分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 KnowledgeBaseSummary：
|
||
- kbId: string
|
||
- name: string
|
||
- source: string (user/installed/account_available/global)
|
||
- type: string
|
||
- currentVersion: integer
|
||
- processingStatus: string
|
||
- authorizationStatus: string
|
||
- isEditable: boolean
|
||
- bindableWorkCount: integer
|
||
- recentHitCount: integer
|
||
- riskSummary: string
|
||
- createdAt: date-time
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 创建用户知识库
|
||
operationId: createKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [name, commandId]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: 知识库名称
|
||
description:
|
||
type: string
|
||
description: 知识库说明
|
||
templateId:
|
||
type: string
|
||
description: 模板 ID（从模板创建时）
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [draft]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}:
|
||
get:
|
||
tags: [Knowledge-Base]
|
||
summary: 用户知识库详情
|
||
description: 返回资料摘要、版本、来源状态和处理状态
|
||
operationId: getKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 知识库详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
source:
|
||
type: string
|
||
ownership:
|
||
type: string
|
||
currentVersion:
|
||
type: integer
|
||
processingStatus:
|
||
type: string
|
||
authorizationStatus:
|
||
type: string
|
||
isEditable:
|
||
type: boolean
|
||
documentCount:
|
||
type: integer
|
||
bindableWorkCount:
|
||
type: integer
|
||
recentHitCount:
|
||
type: integer
|
||
riskSummary:
|
||
type: string
|
||
publishStatus:
|
||
type: string
|
||
processingSummary:
|
||
type: object
|
||
properties:
|
||
searchableCount:
|
||
type: integer
|
||
generativeCount:
|
||
type: integer
|
||
failedCount:
|
||
type: integer
|
||
processingCount:
|
||
type: integer
|
||
licenseSummary:
|
||
type: object
|
||
properties:
|
||
canSearch:
|
||
type: boolean
|
||
canGenerate:
|
||
type: boolean
|
||
canExport:
|
||
type: boolean
|
||
canCopy:
|
||
type: boolean
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
patch:
|
||
tags: [Knowledge-Base]
|
||
summary: 更新用户知识库基础信息
|
||
operationId: updateKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbId:
|
||
type: string
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
delete:
|
||
tags: [Knowledge-Base]
|
||
summary: 删除用户知识库
|
||
description: 删除用户知识库，按状态进入软删除或异步清理
|
||
operationId: deleteKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, impactConfirmed]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
impactConfirmed:
|
||
type: boolean
|
||
description: 用户已确认影响范围
|
||
retentionConfirmed:
|
||
type: boolean
|
||
description: 用户已确认留存规则
|
||
responses:
|
||
'200':
|
||
description: 删除流程已启动
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [deleting]
|
||
cancellableUntil:
|
||
type: string
|
||
format: date-time
|
||
affectedBindings:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/disable:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 停用用户知识库
|
||
description: 停用用户知识库，阻断新绑定和新检索
|
||
operationId: disableKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, impactConfirmed]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
impactConfirmed:
|
||
type: boolean
|
||
description: 用户已确认影响范围
|
||
responses:
|
||
'200':
|
||
description: 停用成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [disabled]
|
||
affectedBindings:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/restore:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 恢复用户知识库
|
||
description: 恢复可恢复的用户知识库
|
||
operationId: restoreKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 恢复成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [active, searchable, generative]
|
||
reindexRequired:
|
||
type: boolean
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/documents:
|
||
get:
|
||
tags: [Knowledge-Base]
|
||
summary: 用户知识库资料列表
|
||
description: 返回资料列表、版本、处理状态和来源摘要
|
||
operationId: listKBDocuments
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: processingStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending_scan, scan_blocked, pending_process, processing, searchable, generative, failed, deleting]
|
||
description: 按处理状态筛选
|
||
- name: type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [file, entry, link]
|
||
description: 按资料类型筛选
|
||
- name: keyword
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 搜索关键词
|
||
responses:
|
||
'200':
|
||
description: 资料分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 DocumentSummary：
|
||
- documentId: string
|
||
- name: string
|
||
- type: string (file/entry/link)
|
||
- size: integer
|
||
- sourceDescription: string
|
||
- currentVersion: integer
|
||
- scanStatus: string
|
||
- processingStatus: string
|
||
- isSearchable: boolean
|
||
- isGenerative: boolean
|
||
- failureReason: string
|
||
- riskSummary: string
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 上传用户知识库资料
|
||
description: 上传资料，返回 documentId 和处理任务
|
||
operationId: uploadKBDocument
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
description: 上传文件
|
||
entryContent:
|
||
type: string
|
||
description: 手写条目内容
|
||
linkUrl:
|
||
type: string
|
||
format: uri
|
||
description: |
|
||
外链资料 URL。服务端必须执行 SSRF 防护：仅允许配置 allowlist 内的域名或协议，
|
||
拦截私网/环回/链路本地 IP 和 DNS 重绑定，使用隔离抓取环境下载，
|
||
对抓取文件做类型校验和恶意文件扫描，并以异步处理状态返回扫描、解析和索引结果。
|
||
sourceDescription:
|
||
type: string
|
||
description: 来源说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 上传成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: integer
|
||
format: int64
|
||
scanTaskId:
|
||
type: string
|
||
processingStatus:
|
||
type: string
|
||
enum: [pending_scan]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/documents/{documentId}/versions:
|
||
get:
|
||
tags: [Knowledge-Base]
|
||
summary: 用户知识库资料版本列表
|
||
operationId: listKBDocumentVersions
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 资料版本列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: integer
|
||
sourceDescription:
|
||
type: string
|
||
scanStatus:
|
||
type: string
|
||
processingStatus:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 上传用户知识库资料新版本
|
||
description: 上传新版本文件，触发处理任务
|
||
operationId: createKBDocumentVersion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
sourceDescription:
|
||
type: string
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 新版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
newVersion:
|
||
type: integer
|
||
processingTaskId:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/documents/{documentId}:
|
||
delete:
|
||
tags: [Knowledge-Base]
|
||
summary: 删除或停用用户知识库资料
|
||
description: 删除或停用资料，触发来源事件
|
||
operationId: deleteKBDocument
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: documentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
impactConfirmed:
|
||
type: boolean
|
||
description: 用户已确认影响范围
|
||
responses:
|
||
'200':
|
||
description: 删除成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
sourceEventId:
|
||
type: string
|
||
affectedBindings:
|
||
type: integer
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}:
|
||
get:
|
||
tags: [Knowledge-Base]
|
||
summary: 查询用户知识库资料处理任务
|
||
description: 查询资料处理、解析、切分、索引或投影任务
|
||
operationId: getKBProcessingTask
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: taskId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 处理任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
taskId:
|
||
type: string
|
||
taskType:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued, scanning, cleaning, parsing, indexing, completed, failed, cancelling]
|
||
stage:
|
||
type: string
|
||
progress:
|
||
type: number
|
||
format: float
|
||
description: 进度百分比 0-100
|
||
documentCount:
|
||
type: integer
|
||
failedCount:
|
||
type: integer
|
||
failureReason:
|
||
type: string
|
||
retryable:
|
||
type: boolean
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: string
|
||
startedAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/reindex:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 重建用户知识库索引
|
||
description: 重建索引，返回任务
|
||
operationId: reindexKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
scope:
|
||
type: string
|
||
enum: [full, incremental, failed_only]
|
||
default: full
|
||
description: 重建范围
|
||
responses:
|
||
'200':
|
||
description: 重建索引任务已创建
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued]
|
||
pollUrl:
|
||
type: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/knowledge-bases/{kbId}/publish-prechecks:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 生成源侧可发布性摘要
|
||
description: |
|
||
只在 Knowledge owner 内生成知识库源侧可发布性摘要，返回 publishReadinessId 或阻断原因。
|
||
该接口不创建 Market 发布申请，不产生审核结论；实际 submit/review 必须在 Market 模块完成。
|
||
operationId: createKBPublishReadiness
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, version]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
version:
|
||
type: integer
|
||
description: 待发布的知识库版本
|
||
responses:
|
||
'200':
|
||
description: 预检结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
publishReadinessId:
|
||
type: string
|
||
description: 源侧可发布性摘要 ID，用于生成发布快照
|
||
blocked:
|
||
type: boolean
|
||
blockedReasons:
|
||
type: array
|
||
items:
|
||
type: string
|
||
warnings:
|
||
type: array
|
||
items:
|
||
type: string
|
||
rightsStatus:
|
||
type: string
|
||
privacyStatus:
|
||
type: string
|
||
processingStatus:
|
||
type: string
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/publish-snapshots:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 生成源侧发布快照
|
||
description: |
|
||
固化知识库版本、授权、来源、处理状态和可发布性摘要，形成给 Market 发布草稿使用的源侧快照。
|
||
该接口不提交 Market 审核。
|
||
operationId: createKBPublishSnapshot
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, version, publishReadinessId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
version:
|
||
type: integer
|
||
description: 知识库版本
|
||
publishReadinessId:
|
||
type: string
|
||
description: 源侧可发布性摘要 ID
|
||
responses:
|
||
'201':
|
||
description: 发布快照创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
snapshotId:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
packageHash:
|
||
type: string
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/publish-readiness:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 生成 Market 发布交接材料
|
||
description: |
|
||
消费源侧可发布性摘要和发布快照，生成 Market 发布草稿可引用的交接材料。
|
||
不创建 Market 发布申请、不进入审核队列；实际 submit/review 由 Market API 负责。
|
||
operationId: createKBMarketPublishReadiness
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, publishReadinessId, snapshotId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
publishReadinessId:
|
||
type: string
|
||
description: 源侧可发布性摘要 ID
|
||
snapshotId:
|
||
type: string
|
||
description: 发布快照 ID
|
||
rightsDeclaration:
|
||
type: string
|
||
description: 权利声明
|
||
licenseScope:
|
||
type: object
|
||
description: 许可范围
|
||
prohibitedUses:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 禁止用途
|
||
responses:
|
||
'201':
|
||
description: 发布交接材料已生成
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
readinessPackageId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [ready_for_market_submission]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-bases/{kbId}/export-tasks:
|
||
post:
|
||
tags: [Knowledge-Base]
|
||
summary: 创建知识库导出任务
|
||
description: 创建知识库导出任务，需要预检和脱敏确认
|
||
operationId: createKBExportTask
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, kbExportCheckId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
kbExportCheckId:
|
||
type: string
|
||
description: 导出预检 ID
|
||
format:
|
||
type: string
|
||
enum: [json, markdown, zip]
|
||
default: zip
|
||
description: 导出格式
|
||
scope:
|
||
type: string
|
||
enum: [full, metadata_only, documents_only]
|
||
default: full
|
||
description: 导出范围
|
||
desensitizationConfirmed:
|
||
type: boolean
|
||
description: 用户已确认脱敏规则
|
||
responses:
|
||
'201':
|
||
description: 导出任务已创建
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued]
|
||
pollUrl:
|
||
type: string
|
||
downloadExpiresAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
# ============================================================
|
||
# App Installed Knowledge Bases（设计文档 Section 4.6）
|
||
# ============================================================
|
||
|
||
/app-api/muse/installed-knowledge-bases:
|
||
get:
|
||
tags: [Installed-KB]
|
||
summary: 已安装知识库列表
|
||
description: 返回已安装知识库列表、授权、来源状态和可绑定范围
|
||
operationId: listInstalledKnowledgeBases
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [installed, disabled, authorization_expired, delisted, upgrade_available]
|
||
description: 按安装状态筛选
|
||
responses:
|
||
'200':
|
||
description: 已安装知识库分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
description: |
|
||
list 元素为 InstalledKBSummary：
|
||
- installId: string
|
||
- kbId: string
|
||
- name: string
|
||
- publisher: string
|
||
- currentVersion: integer
|
||
- latestVersion: integer
|
||
- upgradeAvailable: boolean
|
||
- isVersionPinned: boolean
|
||
- status: string
|
||
- licenseSummary: object
|
||
- canSearch: boolean
|
||
- canGenerate: boolean
|
||
- expiresAt: date-time
|
||
- updatedAt: date-time
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/installed-knowledge-bases/{installId}/disable:
|
||
post:
|
||
tags: [Installed-KB]
|
||
summary: 停用已安装知识库
|
||
operationId: disableInstalledKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: installId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 停用成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [disabled]
|
||
affectedWorkBindings:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/installed-knowledge-bases/{installId}:
|
||
delete:
|
||
tags: [Installed-KB]
|
||
summary: 删除已安装知识库记录
|
||
description: 删除已安装知识库记录，不删除来源市场资产
|
||
operationId: deleteInstalledKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: installId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
impactConfirmed:
|
||
type: boolean
|
||
description: 用户已确认影响范围
|
||
responses:
|
||
'200':
|
||
description: 删除成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
affectedWorkBindings:
|
||
type: integer
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/installed-knowledge-bases/{installId}/restore:
|
||
post:
|
||
tags: [Installed-KB]
|
||
summary: 恢复已安装知识库
|
||
operationId: restoreInstalledKnowledgeBase
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: installId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 恢复成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
enum: [installed]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
# ============================================================
|
||
# App Local Knowledge & Knowledge Drafts（设计文档 Section 4.6）
|
||
# ============================================================
|
||
|
||
/app-api/muse/works/{workId}/local-knowledge:
|
||
get:
|
||
tags: [Local-Knowledge]
|
||
summary: 作品 Local KB
|
||
description: 查询作品局域知识库，属于单作品正式事实
|
||
operationId: getLocalKnowledge
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: entityType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [character, location, event, item, concept, note]
|
||
description: 按实体类型筛选
|
||
- name: keyword
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 搜索关键词
|
||
responses:
|
||
'200':
|
||
description: 作品局域知识库
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
workId:
|
||
type: string
|
||
entityCount:
|
||
type: integer
|
||
entities:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
entityId:
|
||
type: string
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [confirmed, draft, conflicted]
|
||
description:
|
||
type: string
|
||
sourceRef:
|
||
type: string
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
sourceBindings:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
bindingId:
|
||
type: string
|
||
sourceType:
|
||
type: string
|
||
sourceId:
|
||
type: string
|
||
sourceName:
|
||
type: string
|
||
sourceStatus:
|
||
type: string
|
||
purposes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/works/{workId}/knowledge-drafts:
|
||
get:
|
||
tags: [Knowledge-Draft]
|
||
summary: 待确认知识草稿
|
||
description: 查询作品待确认的知识草稿列表
|
||
operationId: listKnowledgeDrafts
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending, confirmed, ignored, conflicted]
|
||
- name: entityType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [character, location, event, item, concept, note]
|
||
responses:
|
||
'200':
|
||
description: 知识草稿列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
draftId:
|
||
type: integer
|
||
format: int64
|
||
entityType:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [pending, confirmed, ignored, conflicted]
|
||
sourceType:
|
||
type: string
|
||
sourceRef:
|
||
type: string
|
||
confidence:
|
||
type: number
|
||
format: float
|
||
conflictSummary:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/app-api/muse/knowledge-drafts/{draftId}/confirm:
|
||
post:
|
||
tags: [Knowledge-Draft]
|
||
summary: 确认知识草稿
|
||
description: 确认知识草稿，必须重新校验来源状态、授权快照和风险标记
|
||
operationId: confirmKnowledgeDraft
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: draftId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, expectedDraftRevision, sourceSnapshotId, authorizationSnapshotId, confirmMode, decisionType, riskAcknowledgement]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
expectedDraftRevision:
|
||
type: integer
|
||
description: 草稿版本乐观锁，必须与服务端当前 draft revision 匹配
|
||
sourceSnapshotId:
|
||
type: string
|
||
description: 草稿生成时的来源快照 ID，用于防 stale 校验
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 草稿生成时的授权快照 ID，用于重新校验外发、生成和导出权限
|
||
confirmMode:
|
||
type: string
|
||
enum: [single, batch]
|
||
description: 确认模式
|
||
decisionType:
|
||
type: string
|
||
enum: [accept, accept_with_overrides, resolve_conflict]
|
||
description: 用户确认决策类型
|
||
riskAcknowledgement:
|
||
type: object
|
||
required: [acknowledged]
|
||
properties:
|
||
acknowledged:
|
||
type: boolean
|
||
description: 用户是否已确认风险提示
|
||
acknowledgedRiskCodes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 已确认的风险码列表
|
||
description: 风险确认信息；存在风险标记时必须由服务端校验为 true
|
||
overrides:
|
||
type: object
|
||
additionalProperties: true
|
||
description: 手动修正的属性值
|
||
responses:
|
||
'200':
|
||
description: 确认成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
draftId:
|
||
type: string
|
||
entityId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [confirmed]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-drafts/{draftId}/ignore:
|
||
post:
|
||
tags: [Knowledge-Draft]
|
||
summary: 忽略知识草稿
|
||
operationId: ignoreKnowledgeDraft
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: draftId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 忽略原因
|
||
responses:
|
||
'200':
|
||
description: 已忽略
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
draftId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [ignored]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/knowledge-drafts/{draftId}/recheck:
|
||
post:
|
||
tags: [Knowledge-Draft]
|
||
summary: 重验知识草稿来源
|
||
description: 触发来源重验任务，不直接恢复绑定或确认
|
||
operationId: recheckKnowledgeDraft
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: draftId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 重验任务已创建
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued]
|
||
pollUrl:
|
||
type: string
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
# ============================================================
|
||
# App Knowledge Bindings（设计文档 Section 4.6）
|
||
# ============================================================
|
||
|
||
/app-api/muse/works/{workId}/knowledge-bindings/prechecks:
|
||
post:
|
||
tags: [Knowledge-Binding]
|
||
summary: 目标 owner 绑定预检
|
||
description: |
|
||
消费市场 handoff、来源授权摘要、来源版本、来源状态和授权快照，返回 kbBindPrecheckId。
|
||
Knowledge 在这里执行目标 owner 预检；不会信任后续 bind 请求重复传入的可变来源事实。
|
||
operationId: createKnowledgeBindingPrecheck
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, sourceType, sourceId, sourceVersion, sourceStatus, authorizationSummaryId, authorizationSnapshotId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
sourceType:
|
||
type: string
|
||
enum: [user_kb, market_kb, global_kb]
|
||
description: 来源类型
|
||
sourceId:
|
||
type: string
|
||
description: 来源知识库 ID
|
||
sourceVersion:
|
||
type: integer
|
||
description: 来源版本
|
||
sourceStatus:
|
||
type: string
|
||
enum: [available, authorization_expired, source_delisted, source_recalled, source_revoked, unavailable]
|
||
description: 来源状态快照；不能用 needs_recheck 表达重验，重验原因由 actionPolicy 返回
|
||
handoffToken:
|
||
type: string
|
||
description: 市场 handoff token（市场知识库时必填）
|
||
authorizationSummaryId:
|
||
type: string
|
||
description: Market 生成的来源侧授权摘要 ID
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 授权快照 ID
|
||
purposes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
enum: [search, generate, check, export]
|
||
description: 请求的用途
|
||
responses:
|
||
'200':
|
||
description: 预检结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
kbBindPrecheckId:
|
||
type: string
|
||
description: 绑定预检 ID，用于后续绑定
|
||
allowedPurposes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
blockedPurposes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
conflictStrategy:
|
||
type: string
|
||
blockedReasons:
|
||
type: array
|
||
items:
|
||
type: string
|
||
sourceStatus:
|
||
type: string
|
||
actionPolicy:
|
||
type: object
|
||
properties:
|
||
searchPolicy:
|
||
type: string
|
||
enum: [allowed, blocked]
|
||
generationPolicy:
|
||
type: string
|
||
enum: [allowed, blocked]
|
||
exportPolicy:
|
||
type: string
|
||
enum: [allowed, blocked]
|
||
recheckReasons:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 需要重验的原因列表，不把 needs_recheck 写入 SourceStatus
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/works/{workId}/knowledge-bindings:
|
||
post:
|
||
tags: [Knowledge-Binding]
|
||
summary: 绑定用户/市场知识库
|
||
description: |
|
||
只消费 kbBindPrecheckId、commandId 和 expectedWorkRevision 完成绑定。
|
||
sourceType/sourceId/sourceVersion/authorizationSnapshotId/purposes 等来源事实必须来自服务端预检快照，
|
||
不在 bind 请求体中重复信任前端可变事实。
|
||
operationId: createKnowledgeBinding
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, kbBindPrecheckId, expectedWorkRevision]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
kbBindPrecheckId:
|
||
type: string
|
||
description: 绑定预检 ID
|
||
expectedWorkRevision:
|
||
type: integer
|
||
description: 目标作品 revision 乐观锁，避免绑定写入过期作品状态
|
||
responses:
|
||
'201':
|
||
description: 绑定成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
bindingId:
|
||
type: string
|
||
sourceType:
|
||
type: string
|
||
sourceId:
|
||
type: string
|
||
sourceVersion:
|
||
type: integer
|
||
purposes:
|
||
type: array
|
||
items:
|
||
type: string
|
||
authorizationSnapshotId:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
|
||
/app-api/muse/works/{workId}/knowledge-bindings/{bindingId}:
|
||
delete:
|
||
tags: [Knowledge-Binding]
|
||
summary: 解绑作品知识来源
|
||
description: 解绑知识来源，后续生成不再使用该来源
|
||
operationId: deleteKnowledgeBinding
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: bindingId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
impactConfirmed:
|
||
type: boolean
|
||
description: 用户已确认影响范围
|
||
responses:
|
||
'200':
|
||
description: 解绑成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
bindingId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [unbound]
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|