fix(knowledge): reject empty document extraction (#19177)

Signed-off-by: userInner <1239989762@qq.com>

Author: userInner

src/main/features/knowledge/tasks/__tests__/indexDocumentsJobHandler.test.ts

@@ -326,22 +326,38 @@ describe('index-documents job handler', () => {
     ).toHaveLength(0)
   })
 
-  it('warns when an item yields no indexable text, and still completes it with an empty material', async () => {
+  it('rejects a file when its reader yields no indexable text', async () => {
     const handler = createIndexDocumentsJobHandler(knowledgeLockManager as never)
-    knowledgeItemGetByIdMock.mockReturnValue(createNoteItem(NOTE_ITEM_ID))
-    knowledgeItemUpdateStatusMock.mockReturnValue(createNoteItem(NOTE_ITEM_ID))
+    knowledgeItemGetByIdMock.mockReturnValue(createFileItem(FILE_ITEM_ID))
     loadKnowledgeItemDocumentsMock.mockResolvedValueOnce([])
+    const failureReason =
+      'No indexable text was extracted. Check the source, OCR, or document processing settings, then reindex.'
 
-    await handler.execute(createCtx({ baseId: 'kb-1', itemId: NOTE_ITEM_ID }))
+    await expect(handler.execute(createCtx({ baseId: 'kb-1', itemId: FILE_ITEM_ID }))).rejects.toThrow(failureReason)
+
+    // JobManager forwards the thrown reason to onSettled; verify that the existing
+    // settlement seam makes the row visibly failed (and therefore reindexable).
+    await handler.onSettled?.({
+      jobId: 'index-job',
+      type: 'knowledge.index-documents',
+      scheduleId: null,
+      parentId: null,
+      status: 'failed',
+      input: { baseId: 'kb-1', itemId: FILE_ITEM_ID },
+      error: { code: 'FAILED', message: failureReason, retryable: false },
+      attempt: 1,
+      metadata: {}
+    })
 
-    // An image-only PDF or failed extraction must leave a diagnosable trace —
-    // without the warn it would look indexed while matching nothing.
+    expect(embedKnowledgeTextsMock).not.toHaveBeenCalled()
+    expect(rebuildMaterialMock).not.toHaveBeenCalled()
+    expect(knowledgeItemUpdateStatusMock).not.toHaveBeenCalledWith(FILE_ITEM_ID, 'embedding')
+    expect(knowledgeItemUpdateStatusMock).not.toHaveBeenCalledWith(FILE_ITEM_ID, 'completed')
+    expect(knowledgeItemUpdateStatusMock).toHaveBeenCalledWith(FILE_ITEM_ID, 'failed', { error: failureReason })
     expect(loggerWarnMock).toHaveBeenCalledWith(
-      'Knowledge item produced no indexable text; it will complete with an empty index',
-      expect.objectContaining({ baseId: 'kb-1', itemId: NOTE_ITEM_ID })
+      'Knowledge item produced no indexable text; failing indexing',
+      expect.objectContaining({ baseId: 'kb-1', itemId: FILE_ITEM_ID })
     )
-    expect(lastRebuildInput().units).toEqual([])
-    expect(knowledgeItemUpdateStatusMock).toHaveBeenCalledWith(NOTE_ITEM_ID, 'completed')
   })
 
   it('uses the processed-artifact path (indexedRelativePath) as the material relative path', async () => {
@@ -365,21 +381,17 @@ describe('index-documents job handler', () => {
     expect(loadKnowledgeItemDocumentsMock).toHaveBeenCalledWith(expect.objectContaining({ id: FILE_ITEM_ID }))
   })
 
-  it('completes with empty vectors when the reader returns no documents', async () => {
+  it('rejects whitespace-only reader output before embedding or material replacement', async () => {
     const handler = createIndexDocumentsJobHandler(knowledgeLockManager as never)
-    knowledgeItemGetByIdMock.mockReturnValue(createNoteItem(NOTE_ITEM_ID))
-    knowledgeItemUpdateStatusMock.mockReturnValue(createNoteItem(NOTE_ITEM_ID))
-    loadKnowledgeItemDocumentsMock.mockResolvedValueOnce([])
-
-    await handler.execute(createCtx({ baseId: 'kb-1', itemId: NOTE_ITEM_ID }))
+    knowledgeItemGetByIdMock.mockReturnValue(createFileItem(FILE_ITEM_ID))
+    loadKnowledgeItemDocumentsMock.mockResolvedValueOnce([{ text: ' \n\t ', metadata: { source: FILE_ITEM_ID } }])
 
-    expect(knowledgeItemUpdateStatusMock).toHaveBeenCalledWith(NOTE_ITEM_ID, 'reading')
-    expect(knowledgeItemUpdateStatusMock).toHaveBeenCalledWith(NOTE_ITEM_ID, 'embedding')
-    expect(rebuildMaterialMock).toHaveBeenCalledWith(
-      NOTE_ITEM_ID,
-      expect.objectContaining({ content: expect.objectContaining({ text: '' }), units: [], embeddings: [] })
+    await expect(handler.execute(createCtx({ baseId: 'kb-1', itemId: FILE_ITEM_ID }))).rejects.toThrow(
+      'No indexable text was extracted'
     )
-    expect(knowledgeItemUpdateStatusMock).toHaveBeenCalledWith(NOTE_ITEM_ID, 'completed')
+
+    expect(embedKnowledgeTextsMock).not.toHaveBeenCalled()
+    expect(rebuildMaterialMock).not.toHaveBeenCalled()
   })
 
   it('skips vector write when the item becomes deleting inside the mutation lock', async () => {

src/main/features/knowledge/tasks/indexDocumentsJobHandler.ts

@@ -33,6 +33,9 @@ const logger = loggerService.withContext('Knowledge:IndexDocumentsJobHandler')
 // Chunks per embedMany call while rebuilding an item's material. Small enough to
 // surface incremental progress, large enough to not multiply request overhead.
 const EMBEDDING_PROGRESS_BATCH_SIZE = 10
+const EMPTY_INDEXABLE_TEXT_ERROR =
+  'No indexable text was extracted. Check the source, OCR, or document processing settings, then reindex.'
+
 /**
  * How long the final percentage lingers after the job exits. The list's item status
  * is polled, so deleting the key at completion time blanks the percentage while the
@@ -94,14 +97,15 @@ export function createIndexDocumentsJobHandler(
       const documents = await readItemDocuments(ctx, readableItem)
       const chunked = await chunkItemDocuments(base, documents, ctx.signal)
       if (chunked.chunks.length === 0) {
-        // Deliberate: the item still completes (an empty material is written) so the
-        // UI doesn't show a stuck/failed item, but leave a trace — an image-only PDF
-        // or failed extraction would otherwise look indexed while matching nothing.
-        logger.warn('Knowledge item produced no indexable text; it will complete with an empty index', {
+        // Completing here would make a scanned/image-only PDF look searchable while
+        // persisting an empty material. Reject before embedding or replacement so the
+        // normal settlement path exposes a failed, reindexable item with this reason.
+        logger.warn('Knowledge item produced no indexable text; failing indexing', {
           baseId: ctx.input.baseId,
           itemId: ctx.input.itemId,
           jobId: ctx.jobId
         })
+        throw new Error(EMPTY_INDEXABLE_TEXT_ERROR)
       }
 
       // Mark embedding separately so the UI reflects the current long-running phase.