Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

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.md
index 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 environm
export WEKNORA_BASE_URL=https://weknora.example.com # or http://localhost:8080
export 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 refs
dsh web
```
@@ -45,7 +46,7 @@ For anything beyond that, override the row from your profile's `cordis.patch.yml
maxChunkChars: 1200
requestTimeoutMs: 30000
chatTimeoutMs: 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 refs
toolPrefix: weknora # rename the tools, e.g. to mount two deployments side by side
tools:
listKnowledgeBases: true
@@ -114,6 +115,13 @@ select a workspace. Errors are reported with the HTTP status and WeKnora's own r
Passage content is clipped to `maxChunkChars` before it reaches the model, so one oversized document cannot eat the
context 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.md
index 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-weknora
export WEKNORA_BASE_URL=https://weknora.example.com # 或 http://localhost:8080
export 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 web
maxChunkChars: 1200
requestTimeoutMs: 30000
chatTimeoutMs: 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.yml
index 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_KEY
knowledgeBaseIds: !!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.ts
index 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.ts
index 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 const
diff --git a/packages/dsh-weknora/test/client.test.mjs b/packages/dsh-weknora/test/client.test.mjs
index 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.mjs
index 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.json
index 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.mjs
index 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![系统架构](resource://AbCdEfGhIjKlMnOpQrStUv)',
+ ],
+ },
{
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.mjs
index 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().signal
const 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(`![系统架构](${ARCH_PUBLIC})`))
+ assert.ok(text.includes(`![系统架构](${ARCH_PUBLIC})`))
+})
+
+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(`![系统架构](${ARCH_PUBLIC})`))
+ assert.ok(text.includes(`![系统架构](${ARCH_PUBLIC})`))
+})
+
+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(`![系统架构](${ARCH_HANDLE})`))
+})