Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(dsh-weknora): show knowledge-base figures in plugin answers (#2829) (#2895)
lyingbugc1b54df75df5
diff --git a/packages/dsh-weknora/README.md b/packages/dsh-weknora/README.mdindex 5de69ac98..5b556bfff 100644--- a/packages/dsh-weknora/README.md+++ b/packages/dsh-weknora/README.md@@ -27,6 +27,7 @@ Then point it at your deployment. The shipped configuration layer reads environmexport WEKNORA_BASE_URL=https://weknora.example.com # or http://localhost:8080export WEKNORA_API_KEY=sk-... # a WeKnora API key with `retrieve` (+ `chat` for ask)export WEKNORA_KNOWLEDGE_BASE_IDS=kb-123,kb-456 # optional default scope+export WEKNORA_RESOURCE_URLS=public # default; `handle` keeps internal file refsdsh web```@@ -45,7 +46,7 @@ For anything beyond that, override the row from your profile's `cordis.patch.ymlmaxChunkChars: 1200requestTimeoutMs: 30000chatTimeoutMs: 300000- resourceUrls: handle # `public` asks WeKnora for directly loadable file URLs in citations+ resourceUrls: handle # default is `public` so cited images are directly loadable; `handle` keeps internal refstoolPrefix: weknora # rename the tools, e.g. to mount two deployments side by sidetools:listKnowledgeBases: true@@ -114,6 +115,13 @@ select a workspace. Errors are reported with the HTTP status and WeKnora's own rPassage content is clipped to `maxChunkChars` before it reaches the model, so one oversized document cannot eat thecontext window. The clip is reported to the model (`truncated: true`) instead of silently hiding text.+With the default `resourceUrls: public`, WeKnora rewrites cited `resource://` figures into directly loadable `http(s)`+URLs. Copy those Markdown images into the assistant reply and the dsh web UI will render the picture. A+knowledge-base-restricted API key cannot receive public URLs (WeKnora answers 403); the plugin retries that call in+handle mode and keeps using handles afterwards.++The shipped configuration layer also reads `WEKNORA_RESOURCE_URLS` (`public` or `handle`).+## Configuration reference| Field | Default | Notes |@@ -127,7 +135,7 @@ context window. The clip is reported to the model (`truncated: true`) instead of| `maxChunkChars` | `1200` | Per-passage character budget || `requestTimeoutMs` | `30000` | Retrieval and document reads || `chatTimeoutMs` | `300000` | `weknora_ask`, which waits on WeKnora's own model calls |-| `resourceUrls` | `handle` | `public` returns directly loadable file URLs |+| `resourceUrls` | `public` | `public` returns directly loadable file URLs; `handle` keeps internal `resource://` refs. A knowledge-base-restricted API key is retried as `handle`. Override with `WEKNORA_RESOURCE_URLS`. || `toolPrefix` | `weknora` | Tool-name prefix, `^[a-z][a-z0-9_]*$` || `tools.*` | all `true` | Register fewer tools to spend fewer prompt tokens |diff --git a/packages/dsh-weknora/README_CN.md b/packages/dsh-weknora/README_CN.mdindex c6ba70fcb..6875b18e3 100644--- a/packages/dsh-weknora/README_CN.md+++ b/packages/dsh-weknora/README_CN.md@@ -26,6 +26,7 @@ dsh plugin --profile web add ./packages/dsh-weknoraexport WEKNORA_BASE_URL=https://weknora.example.com # 或 http://localhost:8080export WEKNORA_API_KEY=sk-... # 需要 `retrieve` 能力(用 ask 还需要 `chat`)export WEKNORA_KNOWLEDGE_BASE_IDS=kb-123,kb-456 # 可选的默认知识库范围+export WEKNORA_RESOURCE_URLS=public # 默认;改成 `handle` 则保留内部文件引用dsh web```@@ -43,7 +44,7 @@ dsh webmaxChunkChars: 1200requestTimeoutMs: 30000chatTimeoutMs: 300000- resourceUrls: handle # 改成 `public`,引用里的图片和文件会给可直接加载的直链+ resourceUrls: handle # 默认是 `public`,引用里的图片给可直接加载的直链;`handle` 保留内部引用toolPrefix: weknora # 重命名工具,例如同时挂两个部署时tools:listKnowledgeBases: true@@ -105,6 +106,12 @@ Key 通过 `X-API-Key` 发送。如果用的是平台级 API Key,还需要配片段内容在进入模型前会按 `maxChunkChars` 截断,避免一份超大文档吃掉整个上下文窗口;截断这件事会明确告知模型(`truncated: true`),而不是悄悄丢文本。+默认 `resourceUrls: public` 时,WeKnora 会把片段里的 `resource://` 图改写成可直接加载的 http(s) 直链——把这些 Markdown+图片写进回复,dsh 网页端就会把图画出来。限定知识库的 API Key 拿不到直链(WeKnora 会 403),插件会把这次调用改回+handle 模式,之后也一直用 handle。++配置层还会读 `WEKNORA_RESOURCE_URLS`(`public` 或 `handle`)。+## 配置项| 字段 | 默认值 | 说明 |@@ -118,7 +125,7 @@ Key 通过 `X-API-Key` 发送。如果用的是平台级 API Key,还需要配| `maxChunkChars` | `1200` | 单个片段的字符预算 || `requestTimeoutMs` | `30000` | 检索与读文档 || `chatTimeoutMs` | `300000` | `weknora_ask`,要等 WeKnora 自己的模型调用 |-| `resourceUrls` | `handle` | `public` 返回可直接加载的文件直链 |+| `resourceUrls` | `public` | `public` 返回可直接加载的文件直链;`handle` 保留内部 `resource://` 引用。限定知识库的 API Key 会自动回退到 `handle`。可用 `WEKNORA_RESOURCE_URLS` 覆盖。 || `toolPrefix` | `weknora` | 工具名前缀,需匹配 `^[a-z][a-z0-9_]*$` || `tools.*` | 全部 `true` | 少注册几个工具就少占几分 prompt |diff --git a/packages/dsh-weknora/cordis.patch.yml b/packages/dsh-weknora/cordis.patch.ymlindex 3709769ef..8c340035b 100644--- a/packages/dsh-weknora/cordis.patch.yml+++ b/packages/dsh-weknora/cordis.patch.yml@@ -11,3 +11,4 @@apiKey: !!js process.env.WEKNORA_API_KEYknowledgeBaseIds: !!js (process.env.WEKNORA_KNOWLEDGE_BASE_IDS ?? '').split(',').filter(Boolean)agentId: !!js process.env.WEKNORA_AGENT_ID+ resourceUrls: !!js process.env.WEKNORA_RESOURCE_URLS || 'public'diff --git a/packages/dsh-weknora/src/client.ts b/packages/dsh-weknora/src/client.tsindex b76467775..1975a9723 100644--- a/packages/dsh-weknora/src/client.ts+++ b/packages/dsh-weknora/src/client.ts@@ -110,6 +110,13 @@ function deadline(signal: AbortSignal, timeoutMs: number): AbortSignal {}export class WeknoraClient {+ /**+ * A knowledge-base-restricted API key rejects `resource_urls=public` with+ * 403. After the first such refusal this client stays on handle mode so+ * later calls do not pay the same round trip.+ */+ private publicModeBlocked = false+constructor(private readonly config: ResolvedConfig) {}private headers(): Record<string, string> {@@ -122,19 +129,45 @@ export class WeknoraClient {return headers}+ private resourceMode(): 'handle' | 'public' {+ return this.config.resourceUrls === 'public' && !this.publicModeBlocked ? 'public' : 'handle'+ }+private url(path: string, query?: Record<string, string | number | undefined>): string {const url = new URL(`${this.config.baseUrl}${path}`)- if (this.config.resourceUrls === 'public') url.searchParams.set('resource_urls', 'public')for (const [key, value] of Object.entries(query ?? {})) {if (value !== undefined) url.searchParams.set(key, String(value))}+ if (this.resourceMode() === 'public') url.searchParams.set('resource_urls', 'public')return url.toString()}+ private isPublicModeForbidden(error: unknown): boolean {+ return error instanceof WeknoraApiError+ && this.config.resourceUrls === 'public'+ && !this.publicModeBlocked+ && error.status === 403+ && error.message.includes('resource_urls=public')+ }+private async fetchJson<T>(path: string,init: { method: 'GET' | 'POST', body?: unknown, query?: Record<string, string | number | undefined> },signal: AbortSignal,+ ): Promise<Envelope<T>> {+ try {+ return await this.fetchJsonOnce(path, init, signal)+ } catch (error) {+ if (!this.isPublicModeForbidden(error)) throw error+ this.publicModeBlocked = true+ return await this.fetchJsonOnce(path, init, signal)+ }+ }++ private async fetchJsonOnce<T>(+ path: string,+ init: { method: 'GET' | 'POST', body?: unknown, query?: Record<string, string | number | undefined> },+ signal: AbortSignal,): Promise<Envelope<T>> {const url = this.url(path, init.query)let response: Response@@ -262,17 +295,26 @@ export class WeknoraClient {...input.agentId === undefined ? {} : { agent_id: input.agentId, agent_enabled: true },...input.webSearch ? { web_search_enabled: true } : {},}- const combined = deadline(signal, this.config.chatTimeoutMs)- let response: Response- try {- response = await fetch(this.url(path), {- method: 'POST',- headers: { ...this.headers(), Accept: 'text/event-stream' },- body: JSON.stringify(body),- signal: combined,- })- } catch (cause) {- throw new WeknoraApiError(`POST ${path} failed: ${describeTransportFailure(cause, signal)}`)+ const open = async (): Promise<Response> => {+ const combined = deadline(signal, this.config.chatTimeoutMs)+ try {+ return await fetch(this.url(path), {+ method: 'POST',+ headers: { ...this.headers(), Accept: 'text/event-stream' },+ body: JSON.stringify(body),+ signal: combined,+ })+ } catch (cause) {+ throw new WeknoraApiError(`POST ${path} failed: ${describeTransportFailure(cause, signal)}`)+ }+ }+ let response = await open()+ if (!response.ok) {+ const text = await response.text()+ const error = new WeknoraApiError(`POST ${path} failed with HTTP ${response.status}: ${reasonOf(text)}`, response.status)+ if (!this.isPublicModeForbidden(error)) throw error+ this.publicModeBlocked = true+ response = await open()}if (!response.ok) {const text = await response.text()diff --git a/packages/dsh-weknora/src/config.ts b/packages/dsh-weknora/src/config.tsindex f746de080..5cbe4c4dc 100644--- a/packages/dsh-weknora/src/config.ts+++ b/packages/dsh-weknora/src/config.ts@@ -28,7 +28,11 @@ export interface Config {requestTimeoutMs?: number/** Timeout for a streamed answer, which includes model and tool time. */chatTimeoutMs?: number- /** `public` asks WeKnora for directly loadable file URLs in citations. */+ /**+ * `public` asks WeKnora for directly loadable file URLs in answers and+ * citations (the default: dsh can render `https://` Markdown images, not+ * `resource://` handles). `handle` keeps the internal references.+ */resourceUrls?: 'handle' | 'public'/** Tool-name prefix, so two instances can serve two deployments. */toolPrefix?: string@@ -58,7 +62,7 @@ const DEFAULTS = {maxChunkChars: 1200,requestTimeoutMs: 30_000,chatTimeoutMs: 300_000,- resourceUrls: 'handle',+ resourceUrls: 'public',toolPrefix: 'weknora',} as constdiff --git a/packages/dsh-weknora/test/client.test.mjs b/packages/dsh-weknora/test/client.test.mjsindex 1ba816c09..8a03566ba 100644--- a/packages/dsh-weknora/test/client.test.mjs+++ b/packages/dsh-weknora/test/client.test.mjs@@ -50,6 +50,28 @@ test('resourceUrls=public is forwarded as a query parameter', async () => {assert.equal(mock.requests.at(-1).query.resource_urls, 'public')})+test('resourceUrls defaults to public so figures are loadable', async () => {+ const { mock, client } = await harness()+ await client.listKnowledgeBases(never)+ assert.equal(mock.requests.at(-1).query.resource_urls, 'public')+})++test('handle mode omits the resource_urls query parameter', async () => {+ const { mock, client } = await harness({ resourceUrls: 'handle' })+ await client.listKnowledgeBases(never)+ assert.equal(mock.requests.at(-1).query.resource_urls, undefined)+})++test('a knowledge-base-restricted key falls back from public URLs to handles', async () => {+ const { mock, client } = await harness({}, { forbidPublicResourceUrls: true })+ const bases = await client.listKnowledgeBases(never)+ assert.equal(bases.length, 2)+ assert.equal(mock.requests[0].query.resource_urls, 'public')+ assert.equal(mock.requests[1].query.resource_urls, undefined)+ await client.listKnowledgeBases(never)+ assert.equal(mock.requests.at(-1).query.resource_urls, undefined, 'later calls must not retry public mode')+})+test('chunk pages carry their pagination envelope', async () => {const { client } = await harness()const page = await client.listChunks({ knowledgeId: 'doc-retrieval-pipeline', page: 1, pageSize: 2 }, never)diff --git a/packages/dsh-weknora/test/config.test.mjs b/packages/dsh-weknora/test/config.test.mjsindex c21488dc8..a7b5d7e37 100644--- a/packages/dsh-weknora/test/config.test.mjs+++ b/packages/dsh-weknora/test/config.test.mjs@@ -15,11 +15,15 @@ test('an empty config resolves to documented defaults', () => {assert.equal(config.baseUrl, 'http://localhost:8080/api/v1')assert.equal(config.maxResults, 8)assert.equal(config.toolPrefix, 'weknora')- assert.equal(config.resourceUrls, 'handle')+ assert.equal(config.resourceUrls, 'public')assert.deepEqual(config.knowledgeBaseIds, [])assert.deepEqual(config.tools, { listKnowledgeBases: true, search: true, readDocument: true, ask: true })})+test('resourceUrls handle remains an explicit opt-out', () => {+ assert.equal(resolveConfig({ resourceUrls: 'handle' }).resourceUrls, 'handle')+})+test('a bad row fails the load and names every violation', () => {assert.throws(() => resolveConfig({ baseUrl: 'not-a-url', maxResults: -1, resourceUrls: 'nope', toolPrefix: '9bad' }),diff --git a/packages/dsh-weknora/test/fixtures/api-contract.json b/packages/dsh-weknora/test/fixtures/api-contract.jsonindex 0b49193fd..162bc5367 100644--- a/packages/dsh-weknora/test/fixtures/api-contract.json+++ b/packages/dsh-weknora/test/fixtures/api-contract.json@@ -10,7 +10,7 @@"tool": "weknora_list_knowledge_bases","method": "GET","path": "/api/v1/knowledge-bases",- "query": {},+ "query": { "resource_urls": "public" },"body": null,"goRequestType": null},@@ -18,7 +18,7 @@"tool": "weknora_search","method": "POST","path": "/api/v1/knowledge-search",- "query": {},+ "query": { "resource_urls": "public" },"body": {"query": "默认的检索阈值是多少","knowledge_base_ids": ["kb-product"]@@ -29,7 +29,7 @@"tool": "weknora_search","method": "GET","path": "/api/v1/knowledge/search",- "query": { "keyword": "默认的检索阈值是多少", "limit": "8" },+ "query": { "keyword": "默认的检索阈值是多少", "limit": "8", "resource_urls": "public" },"body": null,"goRequestType": null},@@ -37,7 +37,7 @@"tool": "weknora_read_document","method": "GET","path": "/api/v1/chunks/doc-retrieval-pipeline",- "query": { "page": "1", "page_size": "5" },+ "query": { "page": "1", "page_size": "5", "resource_urls": "public" },"body": null,"goRequestType": "types.Pagination"},@@ -45,7 +45,7 @@"tool": "weknora_read_document","method": "GET","path": "/api/v1/knowledge/doc-retrieval-pipeline",- "query": {},+ "query": { "resource_urls": "public" },"body": null,"goRequestType": null},@@ -53,7 +53,7 @@"tool": "weknora_ask","method": "POST","path": "/api/v1/sessions",- "query": {},+ "query": { "resource_urls": "public" },"body": {"title": "dsh: 默认的检索阈值是多少"},@@ -63,7 +63,7 @@"tool": "weknora_ask","method": "POST","path": "/api/v1/knowledge-chat/session-mock-1",- "query": {},+ "query": { "resource_urls": "public" },"body": {"query": "默认的检索阈值是多少","channel": "api",@@ -75,7 +75,7 @@"tool": "weknora_ask","method": "POST","path": "/api/v1/agent-chat/s1",- "query": {},+ "query": { "resource_urls": "public" },"body": {"query": "部署方式","channel": "api",diff --git a/packages/dsh-weknora/test/helpers/mock-weknora.mjs b/packages/dsh-weknora/test/helpers/mock-weknora.mjsindex fbc846031..9ce3eb8c9 100644--- a/packages/dsh-weknora/test/helpers/mock-weknora.mjs+++ b/packages/dsh-weknora/test/helpers/mock-weknora.mjs@@ -20,6 +20,15 @@ const DOCUMENTS = ['父子分块开启后,命中子块会回溯父块,把更完整的上下文交给生成模型。',],},+ {+ knowledge_id: 'doc-architecture',+ knowledge_title: '系统架构图.md',+ knowledge_base_id: 'kb-product',+ description: '检索与生成两层的系统架构示意图。',+ chunks: [+ '系统由检索与生成两层组成,整体结构见架构图。\n\n',+ ],+ },{knowledge_id: 'doc-deployment',knowledge_title: 'WeKnora 部署手册.md',@@ -58,6 +67,15 @@ const KNOWLEDGE_BASES = [{ id: 'kb-ops', name: 'Ops runbooks', description: '部署与运维手册' },]+const ARCH_HANDLE = 'resource://AbCdEfGhIjKlMnOpQrStUv'+const ARCH_PUBLIC = 'https://cdn.example.com/architecture.png'++/** Mirror WeKnora's `resource_urls=public` rewrite of `resource://` handles. */+function rewriteResources(value, publicMode) {+ if (!publicMode) return value+ return JSON.parse(JSON.stringify(value).replaceAll(ARCH_HANDLE, ARCH_PUBLIC))+}+/*** Score a passage by character-bigram overlap. The real backend scores with* embeddings plus keyword match; bigrams are enough to make the fixture rank@@ -122,6 +140,8 @@ function answerFor(query, results) {* @param options.apiKey - when set, requests must carry it as `X-API-Key`.* @param options.streamError - make the chat routes stream an `error` event.* @param options.streamTruncated - end the chat stream mid-answer, with no `complete`.+ * @param options.forbidPublicResourceUrls - reject `resource_urls=public` with the+ * 403 WeKnora returns for a knowledge-base-restricted API key.* @returns the base URL, the recorded requests, and a close function.*/export async function startMockWeknora(options = {}) {@@ -161,6 +181,16 @@ export async function startMockWeknora(options = {}) {return}+ if (options.forbidPublicResourceUrls === true && url.searchParams.get('resource_urls') === 'public') {+ json(403, {+ success: false,+ error: { message: 'resource_urls=public is not available for a knowledge-base-restricted API key' },+ })+ return+ }++ const publicMode = url.searchParams.get('resource_urls') === 'public'+const forced = failures.get(url.pathname)if (forced !== undefined) {json(forced, { success: false, error: { message: `forced failure for ${url.pathname}` } })@@ -223,7 +253,10 @@ export async function startMockWeknora(options = {}) {}json(200, {success: true,- data: searchResults(body.query, body.knowledge_base_ids ?? [], body.knowledge_ids ?? []),+ data: rewriteResources(+ searchResults(body.query, body.knowledge_base_ids ?? [], body.knowledge_ids ?? []),+ publicMode,+ ),})return}@@ -280,9 +313,12 @@ export async function startMockWeknora(options = {}) {// Retrieving here anyway would hide an unscoped ask from the tests. The// agent route does have a server-side default, its KBSelectionMode.const scoped = (body.knowledge_base_ids ?? []).length > 0 || (body.knowledge_ids ?? []).length > 0- const results = route === 'agent-chat' || scoped- ? searchResults(body.query ?? '', body.knowledge_base_ids ?? [], [])- : []+ const results = rewriteResources(+ route === 'agent-chat' || scoped+ ? searchResults(body.query ?? '', body.knowledge_base_ids ?? [], [])+ : [],+ publicMode,+ )if (route === 'agent-chat') {send({id: 't1',@@ -329,4 +365,4 @@ export async function startMockWeknora(options = {}) {}}-export { DOCUMENTS, KNOWLEDGE_BASES }+export { ARCH_HANDLE, ARCH_PUBLIC, DOCUMENTS, KNOWLEDGE_BASES }diff --git a/packages/dsh-weknora/test/tools.test.mjs b/packages/dsh-weknora/test/tools.test.mjsindex c36f23bb2..8be07a9ad 100644--- a/packages/dsh-weknora/test/tools.test.mjs+++ b/packages/dsh-weknora/test/tools.test.mjs@@ -6,7 +6,7 @@ import { resolveConfig } from '../dist/config.js'import { apply } from '../dist/index.js'import { createTools } from '../dist/tools.js'import { assertLosslessJson, assertSupportedSchema, validate } from './helpers/json-schema.mjs'-import { startMockWeknora } from './helpers/mock-weknora.mjs'+import { startMockWeknora, ARCH_HANDLE, ARCH_PUBLIC } from './helpers/mock-weknora.mjs'const never = new AbortController().signalconst exec = { signal: never }@@ -336,3 +336,26 @@ test('apply fails the plugin load on an invalid row', () => {const ctx = { tools: { register: () => () => undefined } }assert.throws(() => apply(ctx, { baseUrl: 'ftp://kb.example.com' }), /dsh-weknora configuration is invalid/)})++test('search rewrites cited figures to public URLs in passage content', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '系统架构图' })+ const hit = value.results.find(result => result.knowledge_id === 'doc-architecture')+ assert.ok(hit, 'the architecture document must be in the ranked hits')+ assert.ok(hit.content.includes(``))+ assert.ok(text.includes(``))+})++test('ask copies public figure URLs from the retrieved passages', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ const { value, text } = await call(byName.get('weknora_ask'), { query: '系统架构图长什么样' })+ assert.ok(value.answer.includes(``))+ assert.ok(text.includes(``))+})++test('handle mode keeps internal resource handles instead of public URLs', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'], resourceUrls: 'handle' })+ const { value } = await call(byName.get('weknora_search'), { query: '系统架构图' })+ const hit = value.results.find(result => result.knowledge_id === 'doc-architecture')+ assert.ok(hit.content.includes(``))+})