From 03a44a007cbe88fd181a61abe10660b64b94a6fe Mon Sep 17 00:00:00 2001 From: chengke <404835780@qq.com> Date: Thu, 8 Oct 2026 16:31:51 +0800 Subject: [PATCH 1/2] docs(retrieval): mark evidenceText as deprecated and always empty Keep evidence as the consume path and stop documenting evidenceText as a live projection. Co-authored-by: Cursor --- README.md | 4 ++-- src/knowledge/__tests__/knowledge.test.ts | 2 +- src/resources/__tests__/retrieval-wire.test.ts | 2 +- src/resources/__tests__/retrieval.test.ts | 4 ++-- src/types/retrieval.ts | 4 ++-- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f8f2924..4f9b2e3 100644 --- a/README.md +++ b/README.md @@ -311,8 +311,8 @@ const response = await client.retrieval.query({ console.log(response.answerText); // LLM-generated answer console.log(response.referencedChunks); // cited evidence chunks -console.log(response.evidence); // composed parts to consume (text/HTML and inline images) -console.log(response.evidenceText); // text projection of those parts +console.log(response.evidence); // grouped [E n] parts (text/HTML and inline images) +console.log(response.evidenceText); // deprecated; always empty. Use evidence. console.log(response.stopReason); // agentic termination reason, when returned console.log(response.failureReason); // no-answer reason, when returned diff --git a/src/knowledge/__tests__/knowledge.test.ts b/src/knowledge/__tests__/knowledge.test.ts index aa17729..6fbaba4 100644 --- a/src/knowledge/__tests__/knowledge.test.ts +++ b/src/knowledge/__tests__/knowledge.test.ts @@ -1201,7 +1201,7 @@ function createClient(parseResult: ParseResult): { routerUsed: 'legacy', answerText: null, evidence: [{ type: 'text', text: 'Margin guidance improved.' }], - evidenceText: '[report.md / Revenue]\nMargin guidance improved.', + evidenceText: '', referencedChunks: [ { documentId: 'doc-1', diff --git a/src/resources/__tests__/retrieval-wire.test.ts b/src/resources/__tests__/retrieval-wire.test.ts index 91b024a..113527f 100644 --- a/src/resources/__tests__/retrieval-wire.test.ts +++ b/src/resources/__tests__/retrieval-wire.test.ts @@ -95,7 +95,7 @@ describe('Retrieval wire response', () => { { type: 'text', text: 'before' }, { type: 'image', media_type: 'image/png', data: 'abc' }, ], - evidence_text: 'beforedata:image/png;base64,abc', + evidence_text: '', results: [ { content: '[images/a.png]', diff --git a/src/resources/__tests__/retrieval.test.ts b/src/resources/__tests__/retrieval.test.ts index b87d059..730a6b1 100644 --- a/src/resources/__tests__/retrieval.test.ts +++ b/src/resources/__tests__/retrieval.test.ts @@ -200,7 +200,7 @@ describe('Retrieval Resource', () => { query: 'test', routerUsed: 'workflow_single_step', answerText: 'LLM-generated answer', - evidenceText: 'Rendered retrieval evidence', + evidenceText: '', stopReason: 'answer_done', failureReason: 'insufficient evidence', decisionTrace: [ @@ -242,7 +242,7 @@ describe('Retrieval Resource', () => { const referencedChunk: RetrievalReferencedChunk | undefined = response.referencedChunks[0]; expect(typedResponse.answerText).toBe('LLM-generated answer'); - expect(response.evidenceText).toBe('Rendered retrieval evidence'); + expect(response.evidenceText).toBe(''); expect(response.stopReason).toBe('answer_done'); expect(response.failureReason).toBe('insufficient evidence'); expect(response.referencedChunks).toHaveLength(1); diff --git a/src/types/retrieval.ts b/src/types/retrieval.ts index 234ec9d..e1c052e 100644 --- a/src/types/retrieval.ts +++ b/src/types/retrieval.ts @@ -155,7 +155,7 @@ export interface RetrievalReferencedChunk { * * Downstream agents consume: * - `evidence`: composed parts (text/HTML and inline images) - * - `evidenceText`: text projection of those parts + * - `evidenceText`: deprecated; always empty. Use `evidence`. * - `results`: raw path chunks for debug * - `decisionTrace`: per-step navigation decisions (includes stop/failure) * - `referencedChunks`: structured chunk citations for follow-up queries @@ -173,7 +173,7 @@ export interface RetrievalQueryResponse { answerText: string | null; /** Cited evidence chunks with asset URLs when available */ referencedChunks: RetrievalReferencedChunk[]; - /** Text projection of evidence. Tables stay as HTML; images are data URLs. */ + /** Deprecated. Always empty. Use evidence. */ evidenceText?: string | null; /** Reason why the agentic run stopped (e.g. answer_done, not_found) */ stopReason?: string | null; From f6c22b19810995699dfaf584db6263e3a8e00f34 Mon Sep 17 00:00:00 2001 From: chengke <404835780@qq.com> Date: Thu, 8 Oct 2026 16:33:03 +0800 Subject: [PATCH 2/2] chore: add changeset for evidenceText deprecation Co-authored-by: Cursor --- .changeset/deprecate-evidence-text.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/deprecate-evidence-text.md diff --git a/.changeset/deprecate-evidence-text.md b/.changeset/deprecate-evidence-text.md new file mode 100644 index 0000000..7df405e --- /dev/null +++ b/.changeset/deprecate-evidence-text.md @@ -0,0 +1,5 @@ +--- +"@ontos-ai/knowhere-sdk": patch +--- + +Mark evidenceText as deprecated and always empty. Consume evidence instead.