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
feat(gallery): add an image gallery tab with schema-driven filters (#3694)
tayadwx68fe9599cdb8
diff --git a/frontend/src/api/auth/index.ts b/frontend/src/api/auth/index.tsindex 2cd3f7064..247eff201 100644--- a/frontend/src/api/auth/index.ts+++ b/frontend/src/api/auth/index.ts@@ -102,6 +102,12 @@ export interface UserPreferences {last_active_tenant_id?: number | null// oidc_only_login 为 true 表示账号由 OIDC 自动开通且用户尚未设置已知密码。oidc_only_login?: boolean+ // gallery 记录图库的个人状态:搜索激活模式与逐字段开/关(按属性 ID)。+ // 每次变更整体覆盖该块;后端会校验 mode 与 status 取值。+ gallery?: {+ mode?: 'all' | 'custom'+ status?: Record<string, string>+ }}// 用户信息接口diff --git a/frontend/src/api/image-gallery/index.ts b/frontend/src/api/image-gallery/index.tsnew file mode 100644index 000000000..a7c0fc6ff--- /dev/null+++ b/frontend/src/api/image-gallery/index.ts@@ -0,0 +1,206 @@+import { get } from '@/utils/request';++// ---------------------------------------------------------------------------+// Image Gallery API+//+// The gallery lists every image asset inside a knowledge base. An "asset" is a+// single rendered image projected from a chunk's `image_info` array (a document+// chunk can carry several images). The backend de-duplicates, filters by+// keyword / attribute / enabled state, sorts and paginates in the database, so+// a page costs the same however many images the KB holds.+//+// What the gallery shows (filters, searchable fields, sort options) is NOT+// hardcoded here: GET /knowledge-bases/:id/gallery-config returns the+// self-describing contract (attribute sources, resolved per-attribute usage,+// the caller's search activation state) and the UI renders from it. New+// backend attributes therefore light up with no frontend change.+// ---------------------------------------------------------------------------++/** One image projected from a chunk, as returned by the backend. */+export interface ImageAsset {+ /** Stable id: "<chunkID>#<index-in-array>". */+ id: string;+ /** Owning chunk id. */+ chunk_id: string;+ /** Owning knowledge (document) id. */+ knowledge_id: string;+ /** Human-readable name of the source knowledge item (document title). */+ source_name: string;+ /** Owning chunk type; empty for images discovered on a text (document) chunk. */+ chunk_type: string;+ /** Rendered image URL. */+ url: string;+ /** Pre-transform source reference, when different. */+ original_url: string;+ /** Model-generated image description. */+ caption: string;+ /** Extracted OCR text, if any. */+ ocr_text: string;+ /** Observed attribute map keyed by source-local attribute name. */+ attrs: Record<string, unknown>;+ /** Mirrors the owning chunk's enabled flag. */+ is_enabled: boolean;+ /** Mirrors the owning chunk's index status. */+ status: number;+ /** Owning chunk creation time (ISO 8601). */+ created_at: string;+ /** Owning chunk last-update time (ISO 8601). */+ updated_at: string;+}++export type ImageSortOrder = 'asc' | 'desc';++/** Query parameters accepted by GET /knowledge-bases/:id/images. */+export interface ImageListParams {+ /** Case-insensitive substring match against the union of searchIn fields. */+ keyword?: string;+ /**+ * Namespaced attribute ids to search ("builtin:caption"). Must be+ * in_searchfield=true in the contract; the backend drops anything else.+ * Omit to use the backend default (builtin caption + ocr_text).+ */+ searchIn?: string[];+ /** Namespaced attribute id to sort by; must be in_sortfield=true. */+ sortBy?: string;+ sortOrder?: ImageSortOrder;+ /** Restrict to chunks with this enabled state. Omit to include both. */+ isEnabled?: boolean;+ /**+ * Attribute filters keyed by namespaced attribute id. Values within one+ * attribute are OR-ed; attributes are AND-ed. Sent as one `attr_filters`+ * JSON query param.+ */+ attrFilters?: Record<string, string[]>;+ /**+ * Per-value verdicts keyed by namespaced attribute id, each mapping a value+ * to "off" (hide images carrying it) or "on" (show them regardless). An+ * omitted value stays neutral. Sent as one `attr_rules` JSON query param;+ * "on" outranks "off" when both speak about the same image.+ */+ attrRules?: Record<string, Record<string, string>>;+ page?: number;+ pageSize?: number;+}++export interface ImageListResult {+ items: ImageAsset[];+ total: number;+ page: number;+ pageSize: number;+}++/**+ * List image assets for a knowledge base. Attribute references use the+ * namespaced ids from the gallery contract; the backend validates them+ * against the contract and silently drops ineligible ones.+ */+export async function listGalleryImages(+ kbId: string,+ params: ImageListParams = {},+): Promise<ImageListResult> {+ const query = new URLSearchParams();+ if (params.keyword) query.set('keyword', params.keyword);+ if (params.searchIn && params.searchIn.length) {+ query.set('search_in', params.searchIn.join(','));+ }+ if (params.sortBy) query.set('sort_by', params.sortBy);+ if (params.sortOrder) query.set('sort_order', params.sortOrder);+ if (typeof params.isEnabled === 'boolean') {+ query.set('is_enabled', String(params.isEnabled));+ }+ if (params.attrFilters && Object.keys(params.attrFilters).length) {+ query.set('attr_filters', JSON.stringify(params.attrFilters));+ }+ if (params.attrRules && Object.keys(params.attrRules).length) {+ query.set('attr_rules', JSON.stringify(params.attrRules));+ }+ if (params.page) query.set('page', String(params.page));+ if (params.pageSize) query.set('page_size', String(params.pageSize));++ const qs = query.toString();+ const res = await get<{+ success: boolean;+ data: ImageAsset[];+ total: number;+ page: number;+ page_size: number;+ }>(`/api/v1/knowledge-bases/${kbId}/images${qs ? `?${qs}` : ''}`);++ return {+ items: res.data,+ total: res.total,+ page: res.page,+ pageSize: res.page_size,+ };+}++// ---------------------------------------------------------------------------+// Gallery contract (GET /knowledge-bases/:id/gallery-config)+// ---------------------------------------------------------------------------++/** Resolved per-attribute usage flags after all config tiers merged. */+export interface GalleryAttrUsage {+ in_filter: boolean;+ in_searchfield: boolean;+ in_sortfield: boolean;+}++/**+ * One attribute as the contract serves it: the source's declaration with+ * every config tier's overrides merged in. `id` is namespaced+ * ("<sourceID>:<name>"); `usage_from` names the highest tier that touched+ * the usage ("source" | "system" | "kb" | "user").+ */+/**+ * One allowed value of an attribute.+ *+ * Display text is deliberately split: `label` is the short name that fits a+ * filter checkbox, `description` is the sentence shown where there is room+ * (a tooltip). `value` stays the raw machine value — it is what gets+ * filtered and searched, and it is never localized.+ */+export interface GalleryAttrValue {+ value: string;+ label: string;+ description?: string;+}++export interface GalleryResolvedAttr {+ id: string;+ source: string;+ /** Source-local attribute name, as stored in image_info attrs. */+ name: string;+ /** "text" | "date" | "extent" | "presence" | "keywords" */+ type: string;+ values?: GalleryAttrValue[];+ /** Short on-screen name; falls back to the attribute id when absent. */+ label: string;+ /** Sentence explaining the attribute; shown where there is room. */+ description?: string;+ usage: GalleryAttrUsage;+ usage_from: string;+}++/** The self-describing contract the gallery UI renders from. */+export interface GalleryConfig {+ /** Live source ids in priority order. */+ attribute_sources: string[];+ attributes: GalleryResolvedAttr[];+ /** Search activation mode: "all" (default) or "custom". */+ mode: 'all' | 'custom';+ /** Per-attribute search toggles ("on"/"off"); consulted in custom mode. */+ status: Record<string, string>;+}++/** Fetch the gallery contract for a knowledge base. */+export async function fetchGalleryConfig(kbId: string): Promise<GalleryConfig> {+ const res = await get<{ success: boolean; data: GalleryConfig }>(+ `/api/v1/knowledge-bases/${kbId}/gallery-config`,+ );+ return {+ attribute_sources: res.data.attribute_sources ?? [],+ attributes: res.data.attributes ?? [],+ mode: res.data.mode === 'custom' ? 'custom' : 'all',+ status: res.data.status ?? {},+ };+}diff --git a/frontend/src/api/knowledge-base/index.ts b/frontend/src/api/knowledge-base/index.tsindex 26af0d99b..c4ae43a69 100644--- a/frontend/src/api/knowledge-base/index.ts+++ b/frontend/src/api/knowledge-base/index.ts@@ -72,6 +72,156 @@ export function listKnowledgeBases(params?: {// (deleted row, registry miss, transient infra// failure). Operators recover via the global// Vector Stores settings page.+// ---------------------------------------------------------------------------+// Image attribute observation (route 3). Mirrors backend types in+// internal/types/image_attrs.go. The backend registry is the single source of+// truth; the frontend fetches it from GET /image-attrs/schema and renders the+// attribute panel dynamically. The types/constants below mirror the v1 shape+// so the UI still compiles and can render a fallback before the schema loads.+// ---------------------------------------------------------------------------++// One allowed value of an image attribute.+//+// Display text is split for the same reasons the gallery splits it: `label` is+// what fits on a checkbox or a table cell, `description` is the sentence that+// explains the value where there is room. `value` stays the raw machine value.+export interface ImageAttrValue {+ value: string;+ label: string;+ description?: string;+}++// One observable image attribute, as returned by the schema endpoint. The+// registry is authoritative for both the behaviour and the wording: label,+// description and the per-value texts are what the settings panel shows to an+// operator who does not read identifiers like "contain.text".+export interface ImageAttrSpec {+ name: string;+ type: 'extent' | 'presence';+ values?: ImageAttrValue[];+ question: string;+ label: string;+ description?: string;+ consumers?: string[];+}++// One attribute match: attribute `prop` equals `is`.+export interface ImageAttrCondition {+ prop: string;+ is: string;+}++// The OCR clause of the attribute -> work policy.+export interface ImageOCRAction {+ on: ImageAttrCondition[];+ on_unobserved: boolean;+}++// The attribute -> work policy sent back to the API (snake_case JSON).+export interface ImageActionsConfig {+ ocr: ImageOCRAction;+}++// Canonical registry + built-in actions returned by GET /image-attrs/schema.+export interface ImageAttrSchema {+ version: string;+ prompt: string;+ attributes: ImageAttrSpec[];+ default_actions: ImageActionsConfig;+}++// Mirrors backend types.DefaultImageActions. The schema endpoint returns the+// authoritative copy; this is the fallback used before the schema loads (e.g.+// in create mode, where no knowledge base id exists yet to query).+export const DEFAULT_IMAGE_ACTIONS: ImageActionsConfig = {+ ocr: {+ on: [+ { prop: 'contain.text', is: 'block' },+ { prop: 'contain.data_visual', is: 'true' },+ ],+ on_unobserved: true,+ },+};++// Display-only fallback used before a KB exists (create mode) so the panel can+// render without a network call. It mirrors the registry for layout and wording+// only; the endpoint response is authoritative whenever it loads.+export const FALLBACK_IMAGE_ATTR_SCHEMA: ImageAttrSchema = {+ version: 'attrs/2',+ prompt: 'observe/1',+ attributes: [+ {+ name: 'contain.text',+ type: 'extent',+ values: [+ { value: 'none', label: 'None', description: 'no text at all' },+ { value: 'sparse', label: 'Sparse', description: 'a few words — a logo, a road sign, a single label' },+ { value: 'block', label: 'Block', description: 'a block of body text — a screenshot, a table, a document page' },+ ],+ question: '',+ label: 'Text in the image',+ description: 'How much body text the picture itself carries.',+ consumers: ['ocr'],+ },+ {+ name: 'contain.data_visual',+ type: 'presence',+ values: [+ { value: 'true', label: 'Yes', description: 'a chart, graph or diagram with plotted values' },+ { value: 'false', label: 'No', description: 'a photo, drawing, icon or decoration' },+ ],+ question: '',+ label: 'Data visual',+ description: 'Whether the picture conveys data as a chart, graph, diagram or infographic.',+ consumers: ['ocr'],+ },+ ],+ default_actions: DEFAULT_IMAGE_ACTIONS,+};++// Mirrors backend types.MergeImageActions: a custom OCR.On replaces the default+// OCR.On wholesale (the "on" list is a unit); a config that only sets+// on_unobserved keeps the default On. The result is what the form seeds with+// and what makes an empty custom table safe to open.+export function mergeImageActions(+ custom?: ImageActionsConfig | null,+): ImageActionsConfig {+ if (custom && custom.ocr && custom.ocr.on && custom.ocr.on.length > 0) {+ return { ocr: { on: custom.ocr.on, on_unobserved: custom.ocr.on_unobserved } };+ }+ return {+ ocr: {+ on: DEFAULT_IMAGE_ACTIONS.ocr.on.map((c) => ({ ...c })),+ on_unobserved: DEFAULT_IMAGE_ACTIONS.ocr.on_unobserved,+ },+ };+}++// Fetch the canonical image-attribute registry + default actions from the+// backend. The registry drives the attribute panel; the default actions seed+// the OCR-condition display.+export async function fetchImageAttrSchema(kbId: string): Promise<ImageAttrSchema> {+ // The registry is global, not per-KB. The backend exposes it at a top-level+ // route, the same shape as the other read-only KB-editor helpers+ // (GET /api/v1/chunker/preview, GET /api/v1/system/parser-engines). kbId is+ // kept in the signature for callers that pass KB context.+ void kbId;+ const res = await get<{ success: boolean; data: ImageAttrSchema }>(+ `/api/v1/image-attrs/schema`,+ );+ return res.data;+}++// Mirrors backend types.ImageProcessingConfig (snake_case JSON). The UI edits+// the attribute-observation switch and the on_unobserved toggle; saving sends+// the snapshot back with those fields updated so API-side settings survive a+// UI edit.+export interface ImageProcessingConfig {+ model_id?: string;+ image_actions?: ImageActionsConfig;+ image_attrs_enabled?: boolean;+}+export type VectorStoreSource = 'env' | 'user' | 'shared' | 'unavailable';export type VectorStoreStatus = 'available' | 'unavailable';@@ -88,6 +238,7 @@ export function createKnowledgeBase(data: {description?: string;type?: 'document' | 'faq';chunking_config?: any;+ image_processing_config?: ImageProcessingConfig;embedding_model_id?: string;summary_model_id?: string;auto_tag_config?: { enabled: boolean; model_id?: string; max_tags?: number; skip_if_tagged?: boolean };@@ -144,7 +295,7 @@ export function updateKnowledgeBase(id: string, data: {description?: string;config?: {chunking_config?: any;- image_processing_config?: any;+ image_processing_config?: ImageProcessingConfig;faq_config?: any;wiki_config?: {synthesis_model_id?: string;diff --git a/frontend/src/i18n/localeKeyAudit.ts b/frontend/src/i18n/localeKeyAudit.tsindex 952afdae4..c3079374d 100644--- a/frontend/src/i18n/localeKeyAudit.ts+++ b/frontend/src/i18n/localeKeyAudit.ts@@ -104,6 +104,17 @@ const EXTRA_PREFIXES = ['organization.role.','inviteRegister.','modelSettings.builtinModels.',+ // Image-attribute display text is keyed by the backend attribute registry+ // (imageAttr.contain_text.label …), built from the schema response at runtime,+ // so it is registered as a whole prefix: a new backend attribute must keep+ // being translated without touching the audit.+ 'imageAttr.',+ // Gallery attribute labels are keyed by the namespaced attribute id from+ // the gallery contract, likewise runtime-built; static labels for the few+ // builtin attributes ship in the locale files as+ // knowledgeEditor.wikiBrowser.gallery.attr.builtin_caption …, and+ // everything else falls back to the contract wording.+ 'knowledgeEditor.wikiBrowser.gallery.attr.',] as const/** Keys that must survive pruning even when static analysis misses them. */diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.tsindex 98320984d..5c0d877a5 100755--- a/frontend/src/i18n/locales/en-US.ts+++ b/frontend/src/i18n/locales/en-US.ts@@ -2999,8 +2999,8 @@ export default {duplicate: 'Duplicate'},pin: {- pin: 'Pin to Top',- unpin: 'Unpin',+ pin: 'Pin to Top',+ unpin: 'Unpin',pinSuccess: 'Pinned',unpinSuccess: 'Unpinned',failed: 'Operation failed'@@ -3462,6 +3462,71 @@ export default {editingBadge: 'Editing',pageActions: 'Page actions',tabDocuments: 'Documents',+ tabGallery: 'Gallery',+ gallery: {+ panelFilter: 'Filter',+ panelSearch: 'Search',+ enableFilter: 'Enable filter',+ searchAll: 'Search all fields',+ verdictDefault: '-',+ verdictOff: 'off',+ verdictOn: 'on',+ searchScope: 'Search scope',+ scopeAll: 'All',+ scopeCustom: 'Custom',+ filterScope: 'Filter',+ filterOff: 'Show all',+ filterOn: 'Custom',+ editSearch: 'Open search settings',+ editFilter: 'Open filter settings',+ pin: 'Pin to the right',+ unpin: 'Unpin',+ title: 'Gallery',+ searchPlaceholder: 'Search image content',+ sortByLabel: 'Sort by',+ orderAsc: 'Ascending',+ orderDesc: 'Descending',+ filtersTitle: 'Filters',+ searchFields: 'Search fields',+ modeAll: 'All fields',+ modeCustom: 'Custom',+ keywordsPlaceholder: 'Separate keywords with commas',+ applyAll: 'Apply to all attributes',+ count: '{count} images',+ empty: 'No images in this knowledge base yet',+ emptyFiltered: 'No images match the current filters',+ attrSection: 'Image attributes',+ noAttrs: 'No image attributes available',+ attributes: 'Attributes',+ caption: 'Caption',+ ocr: 'OCR text',+ source: 'Source',+ noCaption: 'No caption',+ noOcr: 'No OCR text',+ chunkType: 'Type',+ viewerClose: 'Close',+ prev: 'Previous',+ next: 'Next',+ openSource: 'Open source document',+ imageLoadError: 'Image failed to load',+ // Display names for the builtin attributes the gallery itself+ // declares. Attributes contributed by other sources fall back to the+ // pipeline's own wording (see the imageAttr namespace).+ attr: {+ builtin_caption: 'Caption',+ builtin_caption_description: 'The model-generated description of the image.',+ builtin_ocr_text: 'OCR text',+ builtin_ocr_text_description: 'Text extracted from the image by OCR.',+ builtin_created_at: 'Created time',+ builtin_created_at_description: 'When the owning document chunk was created.',+ builtin_updated_at: 'Updated time',+ builtin_updated_at_description: 'When the owning document chunk was last updated.',+ builtin_is_enabled: 'Enabled',+ builtin_is_enabled_description: 'Whether the owning document chunk takes part in retrieval.',+ builtin_is_enabled_value_true: 'Enabled',+ builtin_is_enabled_value_false: 'Disabled',+ },+ },tabGraph: 'Graph',tabGraphTip: 'A graph of links between Wiki pages (page-link graph). This is NOT the same as the LLM-extracted entity-relationship Knowledge Graph configured under "KB Settings → Knowledge Graph".',searchPlaceholder: 'Search wiki pages...',@@ -3879,7 +3944,16 @@ export default {descriptionLanguageAuto: 'Follow document language',customInstructionsLabel: 'Image Processing Instructions',customInstructionsDescription: 'Add visual priorities while OCR and Markdown output contracts remain fixed',- customInstructionsPlaceholder: 'For example: prioritize nameplates, model numbers, alarm codes, and table units…'+ customInstructionsPlaceholder: 'For example: prioritize nameplates, model numbers, alarm codes, and table units…',+ imageAttrsLabel: 'Image attribute observation',+ imageAttrsDescription: 'When on, each image is first observed for attributes and described, then the attributes decide whether an OCR round runs for the text in the image. When off, the basic mode applies: every image is described and OCR runs for all of them',+ imageAttrsSchemaLabel: 'Observable image attributes',+ imageAttrsSchemaDescription: 'The model observes the attributes below (defined by the backend registry) to drive the OCR policy',+ imageAttrsOcrConditions: 'Trigger OCR based on the observed attribute conditions',+ imageAttrsOcrConditionsDesc: 'When the observed attributes match the conditions below, OCR runs on the image',+ imageAttrsOcrOnUnobserved: 'Run OCR when image-attribute observation fails',+ imageAttrsOcrOnUnobservedDesc: 'When the model fails to observe the image attributes correctly, OCR runs by default so body text is never lost; turn off to skip. (A small vision model such as 4B, or custom image-instruction prompts that conflict with the system prompt, can cause the observation to fail; 8B and above rarely fail, so leaving this on is recommended)',+ imagePipelineKbNote: 'Defaults follow the knowledge base settings; adjust them for this task'}}},@@ -7009,7 +7083,7 @@ export default {empty: 'No MCP endpoints yet',disabled: 'Disabled',cardSummary: '{tools} tools · {scope}',- scopeAll: 'All knowledge bases',+ scopeAll: 'All knowledge bases',scopeCount: '{count} knowledge bases',create: 'New endpoint',editTitle: 'Edit MCP endpoint',@@ -7657,5 +7731,34 @@ export default {capabilityRequired: 'Select at least one capability',loadFailed: 'Failed to load platform API keys',createFailed: 'Failed to create platform API key'+ },+ // Display text for the observed image attributes, keyed by attribute name.+ // Attribute names escape their dots (contain.text → contain_text) because+ // vue-i18n walks a key segment by segment on the dots, so a literal+ // 'contain.text' key would never resolve. An attribute without a translation+ // falls back to the registry's own wording.+ //+ // Every value carries a short label for compact controls (a filter+ // checkbox) and a description for wherever there is room (a tooltip). One+ // bundle therefore serves both the settings panel and the image gallery,+ // including the gallery's fallback for attributes it does not declare.+ imageAttr: {+ contain_text: {+ label: 'Text in the image',+ description: 'How much body text the picture itself carries. Decides whether reading its text is worth a separate OCR pass.',+ values: {+ none: { label: 'None', description: 'no text at all' },+ sparse: { label: 'Sparse', description: 'a few words — a logo, a road sign, a single label' },+ block: { label: 'Block', description: 'a block of body text — a screenshot, a table, a document page' }+ }+ },+ contain_data_visual: {+ label: 'Data visual',+ description: 'Whether the picture conveys data as a chart, graph, diagram or infographic. Such images keep their labels on the OCR path even when the text looks sparse.',+ values: {+ 'true': { label: 'Yes', description: 'a chart, graph or diagram with plotted values' },+ 'false': { label: 'No', description: 'a photo, drawing, icon or decoration' }+ }+ }}}diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.tsindex baed7c5f9..cb3c6938d 100644--- a/frontend/src/i18n/locales/ja-JP.ts+++ b/frontend/src/i18n/locales/ja-JP.ts@@ -2999,8 +2999,8 @@ export default {duplicate: '複製'},pin: {- pin: '先頭に固定',- unpin: '固定を解除',+ pin: '先頭に固定',+ unpin: '固定を解除',pinSuccess: '固定しました',unpinSuccess: '固定を解除しました',failed: '操作に失敗しました'@@ -3462,6 +3462,71 @@ export default {editingBadge: '編集中',pageActions: 'ページ操作',tabDocuments: 'ドキュメント',+ tabGallery: 'ギャラリー',+ gallery: {+ panelFilter: 'フィルター設定',+ panelSearch: '検索設定',+ enableFilter: 'フィルター有効',+ searchAll: '全フィールド検索',+ verdictDefault: '-',+ verdictOff: 'off',+ verdictOn: 'on',+ searchScope: '検索範囲',+ scopeAll: 'すべて',+ scopeCustom: 'カスタム',+ filterScope: 'フィルター',+ filterOff: 'すべて表示',+ filterOn: 'カスタム',+ editSearch: '検索設定を開く',+ editFilter: 'フィルター設定を開く',+ pin: '右側に固定',+ unpin: '固定を解除',+ title: 'ギャラリー',+ searchPlaceholder: '画像の内容を検索',+ sortByLabel: '並べ替え',+ orderAsc: '昇順',+ orderDesc: '降順',+ filtersTitle: 'フィルター',+ searchFields: '検索フィールド',+ modeAll: 'すべてのフィールド',+ modeCustom: 'カスタム',+ keywordsPlaceholder: 'キーワードはカンマで区切る',+ applyAll: '全属性に一括設定',+ count: '{count} 枚の画像',+ empty: 'このナレッジベースに画像はまだありません',+ emptyFiltered: '現在のフィルターに一致する画像はありません',+ attrSection: '画像属性',+ noAttrs: '画像属性はありません',+ attributes: '属性',+ caption: '説明',+ ocr: 'OCR テキスト',+ source: 'ソース',+ noCaption: '説明なし',+ noOcr: 'OCR テキストなし',+ chunkType: '種類',+ viewerClose: '閉じる',+ prev: '前へ',+ next: '次へ',+ openSource: 'ソース文書を開く',+ imageLoadError: '画像の読み込みに失敗しました',+ // Display names for the builtin attributes the gallery itself+ // declares. Attributes contributed by other sources fall back to the+ // pipeline's own wording (see the imageAttr namespace).+ attr: {+ builtin_caption: '説明',+ builtin_caption_description: 'モデルが生成した画像の説明',+ builtin_ocr_text: 'OCR テキスト',+ builtin_ocr_text_description: 'OCR で画像から抽出した文字',+ builtin_created_at: '作成日時',+ builtin_created_at_description: '所属ドキュメントチャンクの作成日時',+ builtin_updated_at: '更新日時',+ builtin_updated_at_description: '所属ドキュメントチャンクの最終更新日時',+ builtin_is_enabled: '有効状態',+ builtin_is_enabled_description: '所属ドキュメントチャンクが検索対象かどうか',+ builtin_is_enabled_value_true: '有効',+ builtin_is_enabled_value_false: '無効',+ },+ },tabGraph: 'グラフ',tabGraphTip: 'Wikiページ間のリンクを表したグラフ(ページリンクグラフ)です。「ナレッジベース設定 → ナレッジグラフ」で設定する、LLMが抽出するエンティティ・リレーションのナレッジグラフとは異なります。',searchPlaceholder: 'Wikiページを検索...',@@ -3879,7 +3944,16 @@ export default {descriptionLanguageAuto: 'ドキュメントの言語に従う',customInstructionsLabel: '画像処理の指示',customInstructionsDescription: 'OCRとMarkdown出力の仕様は固定したまま、視覚的に優先する対象を追加できます',- customInstructionsPlaceholder: '例: 銘板、型番、アラームコード、表の単位を優先する…'+ customInstructionsPlaceholder: '例: 銘板、型番、アラームコード、表の単位を優先する…',+ imageAttrsLabel: '画像属性の観察',+ imageAttrsDescription: 'オンにすると各画像を先に「属性観察+説明」し、その属性で画像内テキストへの OCR 実行可否を決定します。オフは基本モード:全画像を1枚ずつ説明し全て OCR します',+ imageAttrsSchemaLabel: '観察可能な画像属性',+ imageAttrsSchemaDescription: 'モデルは以下の属性(バックエンドのレジストリで定義)を観察して OCR ポリシーを決めます',+ imageAttrsOcrConditions: '観察した属性条件に基づいて OCR を実行',+ imageAttrsOcrConditionsDesc: '観察した属性が以下の条件を満たす場合、その画像に OCR を実行します',+ imageAttrsOcrOnUnobserved: '画像属性の観察に失敗した場合も OCR を実行',+ imageAttrsOcrOnUnobservedDesc: 'モデルが画像属性を正しく観察できなかった場合、本文テキストを逃さないようデフォルトで OCR を実行します。オフにするとスキップします。(4B など小規模な視覚モデルを使う場合や、カスタムの画像指示がシステムプロンプトと衝突する場合に観察が失敗することがあります。8B 以上は失敗の可能性が低く、オフは推奨しません)',+ imagePipelineKbNote: 'デフォルトはナレッジベースの設定に従い、今回のタスク向けに調整できます'}}},@@ -7009,7 +7083,7 @@ export default {empty: 'MCP エンドポイントはまだありません',disabled: '停止中',cardSummary: '{tools} 個のツール · {scope}',- scopeAll: 'すべてのナレッジベース',+ scopeAll: 'すべてのナレッジベース',scopeCount: '{count} 個のナレッジベース',create: 'エンドポイントを作成',editTitle: 'MCP エンドポイントを編集',@@ -7657,5 +7731,28 @@ export default {capabilityRequired: '権限を1つ以上選択してください',loadFailed: 'プラットフォームAPIキーの読み込みに失敗しました',createFailed: 'プラットフォームAPIキーの作成に失敗しました'+ },+ // 観察属性の表示文言。属性名で索引し、ここでは翻訳のみを担当します。+ // 属性名のドットはアンダースコアにエスケープします(contain.text → contain_text)——+ // vue-i18n はキーをドットで辿るため、リテラルの 'contain.text' は解決できません。+ // 未翻訳の属性はバックエンド登録表の説明にフォールバックします。+ imageAttr: {+ contain_text: {+ label: '画像内のテキスト量',+ description: '画像自体がどれだけ本文テキストを含むか。テキスト読み取りのために別途 OCR を行う価値があるかを判断します。',+ values: {+ none: { label: 'テキストなし', description: 'テキストは一切含まれていません' },+ sparse: { label: 'わずかな文字', description: 'わずかな文字のみ —— ロゴ、道路標識、単一のラベル' },+ block: { label: 'まとまった本文', description: 'まとまった本文 —— スクリーンショット、表、文書ページ' }+ }+ },+ contain_data_visual: {+ label: 'データ可視化',+ description: '画像がグラフ・図表・ダイアグラム・インフォグラフィックとしてデータを伝えているか。文字が少なく見えても OCR の対象に残します。',+ values: {+ 'true': { label: 'はい', description: 'はい —— グラフ・図表・ダイアグラム' },+ 'false': { label: 'いいえ', description: 'いいえ —— 写真・イラスト・アイコン・装飾' }+ }+ }}}diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.tsindex cfa180c66..32256a356 100755--- a/frontend/src/i18n/locales/ko-KR.ts+++ b/frontend/src/i18n/locales/ko-KR.ts@@ -845,7 +845,7 @@ export default {empty: '아직 MCP 엔드포인트가 없습니다',disabled: '비활성',cardSummary: '도구 {tools}개 · {scope}',- scopeAll: '모든 지식 베이스',+ scopeAll: '모든 지식 베이스',scopeCount: '지식 베이스 {count}개',create: '새 엔드포인트',editTitle: 'MCP 엔드포인트 편집',@@ -4067,7 +4067,16 @@ export default {descriptionLanguageAuto: '문서 언어 자동 사용',customInstructionsLabel: '이미지 처리 지침',customInstructionsDescription: 'OCR 및 Markdown 형식은 유지하면서 시각적 우선순위를 추가합니다',- customInstructionsPlaceholder: '예: 명판, 모델 번호, 경고 코드 및 표 단위를 중점적으로 인식…'+ customInstructionsPlaceholder: '예: 명판, 모델 번호, 경고 코드 및 표 단위를 중점적으로 인식…',+ imageAttrsLabel: '이미지 속성 관찰',+ imageAttrsDescription: '켜면 각 이미지를 먼저 속성 관찰+설명한 뒤, 속성에 따라 이미지 내 텍스트에 OCR을 실행할지 결정합니다. 끄면 기본 모드: 모든 이미지를 하나씩 설명하고 모두 OCR합니다',+ imageAttrsSchemaLabel: '관찰 가능한 이미지 속성',+ imageAttrsSchemaDescription: '모델은 아래 속성(백엔드 레지스트리 정의)을 관찰해 OCR 정책을 결정합니다',+ imageAttrsOcrConditions: '관찰된 속성 조건에 따라 OCR 실행',+ imageAttrsOcrConditionsDesc: '관찰된 속성이 아래 조건을 충족하면 해당 이미지에 OCR을 실행합니다',+ imageAttrsOcrOnUnobserved: '이미지 속성 관찰에 실패해도 OCR 실행',+ imageAttrsOcrOnUnobservedDesc: '모델이 이미지 속성을 올바르게 관찰하지 못하면 본문 텍스트 손실을 막기 위해 기본적으로 OCR을 실행합니다. 끄면 건너뜁니다. (4B 등 소형 비전 모델을 쓰거나, 사용자 지정 이미지 지시문이 시스템 프롬프트와 충돌할 때 관찰에 실패할 수 있습니다. 8B 이상은 실패 가능성이 낮아 끄지 않는 것을 권장합니다)',+ imagePipelineKbNote: '기본값은 지식베이스 설정을 따르며 이번 작업에 맞게 조정할 수 있습니다'},tableMetadataInstructions: {label: '테이블 메타데이터 지침',@@ -4433,6 +4442,71 @@ export default {editingBadge: '편집 중',pageActions: '페이지 작업',tabDocuments: '문서',+ tabGallery: '갤러리',+ gallery: {+ panelFilter: '필터 설정',+ panelSearch: '검색 설정',+ enableFilter: '필터 사용',+ searchAll: '전체 필드 검색',+ verdictDefault: '-',+ verdictOff: 'off',+ verdictOn: 'on',+ searchScope: '검색 범위',+ scopeAll: '전체',+ scopeCustom: '사용자 지정',+ filterScope: '필터',+ filterOff: '전체 표시',+ filterOn: '사용자 지정',+ editSearch: '검색 설정 열기',+ editFilter: '필터 설정 열기',+ pin: '오른쪽에 고정',+ unpin: '고정 해제',+ title: '갤러리',+ searchPlaceholder: '이미지 내용 검색',+ sortByLabel: '정렬',+ orderAsc: '오름차순',+ orderDesc: '내림차순',+ filtersTitle: '필터',+ searchFields: '검색 필드',+ modeAll: '전체 필드',+ modeCustom: '사용자 지정',+ keywordsPlaceholder: '쉼표로 키워드 구분',+ applyAll: '모든 속성에 일괄 적용',+ count: '{count}개의 이미지',+ empty: '이 지식 베이스에는 아직 이미지가 없습니다',+ emptyFiltered: '현재 필터와 일치하는 이미지가 없습니다',+ attrSection: '이미지 속성',+ noAttrs: '사용 가능한 이미지 속성이 없습니다',+ attributes: '속성',+ caption: '설명',+ ocr: 'OCR 텍스트',+ source: '출처',+ noCaption: '설명 없음',+ noOcr: 'OCR 텍스트 없음',+ chunkType: '유형',+ viewerClose: '닫기',+ prev: '이전',+ next: '다음',+ openSource: '출처 문서 열기',+ imageLoadError: '이미지를 불러오지 못했습니다',+ // Display names for the builtin attributes the gallery itself+ // declares. Attributes contributed by other sources fall back to the+ // pipeline's own wording (see the imageAttr namespace).+ attr: {+ builtin_caption: '설명',+ builtin_caption_description: '모델이 생성한 이미지 설명',+ builtin_ocr_text: 'OCR 텍스트',+ builtin_ocr_text_description: 'OCR 로 이미지에서 추출한 텍스트',+ builtin_created_at: '생성 시간',+ builtin_created_at_description: '소유 문서 조각이 생성된 시각',+ builtin_updated_at: '수정 시간',+ builtin_updated_at_description: '소유 문서 조각이 마지막으로 수정된 시각',+ builtin_is_enabled: '활성 상태',+ builtin_is_enabled_description: '소유 문서 조각이 검색에 참여하는지 여부',+ builtin_is_enabled_value_true: '활성화',+ builtin_is_enabled_value_false: '비활성화',+ },+ },tabGraph: '그래프',tabGraphTip: 'Wiki 페이지 간의 링크 관계 그래프(페이지 링크 그래프)입니다. \'지식 베이스 설정 → 지식 그래프\'에서 구성하는 LLM 기반 엔티티-관계 지식 그래프와는 다른 개념입니다.',searchPlaceholder: 'Wiki 페이지 검색...',@@ -4933,8 +5007,8 @@ export default {sharedReadonly: '공유받음 · 읽기 전용'},pin: {- pin: '상단 고정',- unpin: '고정 해제',+ pin: '상단 고정',+ unpin: '고정 해제',pinSuccess: '상단에 고정됨',unpinSuccess: '고정 해제됨',failed: '작업 실패'@@ -7657,5 +7731,28 @@ export default {myChats: '내 대화',apiChats: 'API 세션',noSessions: '대화가 없습니다'+ },+ // 관찰 속성의 표시 문구. 속성 이름으로 색인하며 여기서는 번역만 담당합니다.+ // 속성 이름의 점은 밑줄로 이스케이프합니다(contain.text → contain_text) —— vue-i18n 은+ // 키를 점 단위로 순회하므로 리터럴 'contain.text' 키는 해석되지 않습니다.+ // 번역이 없는 속성은 백엔드 등록표의 설명으로 대체됩니다.+ imageAttr: {+ contain_text: {+ label: '이미지 내 텍스트 양',+ description: '이미지 자체가 담고 있는 본문 텍스트의 양입니다. 텍스트를 읽기 위해 별도 OCR을 돌릴 가치가 있는지 판단합니다.',+ values: {+ none: { label: '텍스트 없음', description: '텍스트가 전혀 없습니다' },+ sparse: { label: '약간의 글자', description: '약간의 글자만 —— 로고, 도로 표지판, 단일 라벨' },+ block: { label: '문단 단위 본문', description: '문단 단위 본문 —— 스크린샷, 표, 문서 페이지' }+ }+ },+ contain_data_visual: {+ label: '데이터 시각화',+ description: '이미지가 차트, 그래프, 도표, 인포그래픽으로 데이터를 전달하는지 여부입니다. 글자가 적어 보여도 OCR 대상으로 유지합니다.',+ values: {+ 'true': { label: '예', description: '예 —— 차트, 그래프, 도표' },+ 'false': { label: '아니오', description: '아니오 —— 사진, 삽화, 아이콘, 장식' }+ }+ }}}diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.tsindex 3a3281dfa..b05603bf4 100755--- a/frontend/src/i18n/locales/ru-RU.ts+++ b/frontend/src/i18n/locales/ru-RU.ts@@ -845,7 +845,7 @@ export default {empty: 'Конечных точек MCP пока нет',disabled: 'Отключена',cardSummary: 'Инструментов: {tools} · {scope}',- scopeAll: 'Все базы знаний',+ scopeAll: 'Все базы знаний',scopeCount: 'Баз знаний: {count}',create: 'Новая конечная точка',editTitle: 'Изменить конечную точку MCP',@@ -4067,7 +4067,16 @@ export default {descriptionLanguageAuto: 'Следовать языку документа',customInstructionsLabel: 'Инструкции обработки изображений',customInstructionsDescription: 'Добавьте визуальные приоритеты, сохраняя правила OCR и Markdown',- customInstructionsPlaceholder: 'Например: распознавать шильдики, модели, коды ошибок и единицы таблиц…'+ customInstructionsPlaceholder: 'Например: распознавать шильдики, модели, коды ошибок и единицы таблиц…',+ imageAttrsLabel: 'Наблюдение атрибутов изображений',+ imageAttrsDescription: 'Когда включено, каждое изображение сначала наблюдается на атрибуты и описывается, затем атрибуты решают, нужен ли OCR текста в изображении. Когда выключено — базовый режим: каждое изображение описывается и распознаётся',+ imageAttrsSchemaLabel: 'Наблюдаемые атрибуты изображений',+ imageAttrsSchemaDescription: 'Модель наблюдает перечисленные ниже атрибуты (определены реестром бэкенда), чтобы управлять политикой OCR',+ imageAttrsOcrConditions: 'Запуск OCR по наблюдаемым условиям атрибутов',+ imageAttrsOcrConditionsDesc: 'Когда наблюдаемые атрибуты соответствуют условиям ниже, для изображения выполняется OCR',+ imageAttrsOcrOnUnobserved: 'Запускать OCR при сбое наблюдения атрибутов изображения',+ imageAttrsOcrOnUnobservedDesc: 'Если модель не смогла корректно наблюдать атрибуты изображения, OCR по умолчанию всё равно выполняется, чтобы не потерять текст; выключите, чтобы пропустить. (Небольшая визуальная модель вроде 4B или пользовательские инструкции к изображениям, конфликтующие с системным промптом, могут привести к сбою наблюдения; модели 8B и выше ошибаются редко, поэтому отключать не рекомендуется)',+ imagePipelineKbNote: 'По умолчанию следуют настройкам базы знаний; можно изменить для этой задачи'},tableMetadataInstructions: {label: 'Инструкции метаданных таблиц',@@ -4433,6 +4442,71 @@ export default {editingBadge: 'Редактирование',pageActions: 'Действия со страницей',tabDocuments: 'Документы',+ tabGallery: 'Галерея',+ gallery: {+ panelFilter: 'Фильтр',+ panelSearch: 'Поиск',+ enableFilter: 'Включить фильтр',+ searchAll: 'Искать во всех полях',+ verdictDefault: '-',+ verdictOff: 'off',+ verdictOn: 'on',+ searchScope: 'Область поиска',+ scopeAll: 'Все',+ scopeCustom: 'Вручную',+ filterScope: 'Фильтр',+ filterOff: 'Показывать все',+ filterOn: 'Вручную',+ editSearch: 'Открыть настройки поиска',+ editFilter: 'Открыть настройки фильтра',+ pin: 'Закрепить справа',+ unpin: 'Открепить',+ title: 'Галерея',+ searchPlaceholder: 'Поиск по содержимому изображений',+ sortByLabel: 'Сортировка',+ orderAsc: 'По возрастанию',+ orderDesc: 'По убыванию',+ filtersTitle: 'Фильтры',+ searchFields: 'Поля поиска',+ modeAll: 'Все поля',+ modeCustom: 'Свои поля',+ keywordsPlaceholder: 'Разделяйте ключевые слова запятыми',+ applyAll: 'Применить ко всем атрибутам',+ count: '{count} изображений',+ empty: 'В этой базе знаний пока нет изображений',+ emptyFiltered: 'Нет изображений, соответствующих фильтрам',+ attrSection: 'Атрибуты изображения',+ noAttrs: 'Атрибуты изображения отсутствуют',+ attributes: 'Атрибуты',+ caption: 'Описание',+ ocr: 'OCR-текст',+ source: 'Источник',+ noCaption: 'Нет описания',+ noOcr: 'Нет OCR-текста',+ chunkType: 'Тип',+ viewerClose: 'Закрыть',+ prev: 'Назад',+ next: 'Вперёд',+ openSource: 'Открыть исходный документ',+ imageLoadError: 'Не удалось загрузить изображение',+ // Display names for the builtin attributes the gallery itself+ // declares. Attributes contributed by other sources fall back to the+ // pipeline's own wording (see the imageAttr namespace).+ attr: {+ builtin_caption: 'Описание',+ builtin_caption_description: 'Описание изображения, сгенерированное моделью.',+ builtin_ocr_text: 'OCR-текст',+ builtin_ocr_text_description: 'Текст, извлечённый из изображения OCR.',+ builtin_created_at: 'Время создания',+ builtin_created_at_description: 'Когда был создан фрагмент исходного документа.',+ builtin_updated_at: 'Время изменения',+ builtin_updated_at_description: 'Когда фрагмент исходного документа был изменён последний раз.',+ builtin_is_enabled: 'Состояние',+ builtin_is_enabled_description: 'Участвует ли фрагмент исходного документа в поиске.',+ builtin_is_enabled_value_true: 'Включено',+ builtin_is_enabled_value_false: 'Отключено',+ },+ },tabGraph: 'Граф',tabGraphTip: 'Граф связей между Wiki-страницами (граф ссылок страниц). Это НЕ то же самое, что граф знаний на основе сущностей и отношений, настраиваемый в «Настройки БЗ → Граф знаний».',searchPlaceholder: 'Поиск Wiki-страниц...',@@ -4933,8 +5007,8 @@ export default {sharedReadonly: 'Доступно мне · Только просмотр'},pin: {- pin: 'Закрепить',- unpin: 'Открепить',+ pin: 'Закрепить',+ unpin: 'Открепить',pinSuccess: 'Закреплено',unpinSuccess: 'Откреплено',failed: 'Операция не удалась'@@ -7657,5 +7731,28 @@ export default {myChats: 'Мои чаты',apiChats: 'Сессии API',noSessions: 'Пока нет диалогов'+ },+ // Тексты для наблюдаемых атрибутов изображения, с ключом по имени атрибута.+ // Точки в имени атрибута экранируются подчёркиванием (contain.text → contain_text):+ // vue-i18n разбирает ключ по точкам, поэтому литеральный ключ 'contain.text'+ // никогда не найдётся. Атрибут без перевода отображается описанием из реестра.+ imageAttr: {+ contain_text: {+ label: 'Количество текста на изображении',+ description: 'Сколько основного текста содержит само изображение. Определяет, стоит ли запускать для него отдельный проход OCR.',+ values: {+ none: { label: 'Нет текста', description: 'текста нет' },+ sparse: { label: 'Немного текста', description: 'несколько слов —— логотип, дорожный знак, одна надпись' },+ block: { label: 'Блок текста', description: 'блок основного текста —— скриншот, таблица, страница документа' }+ }+ },+ contain_data_visual: {+ label: 'Визуализация данных',+ description: 'Передаёт ли изображение данные в виде графика, диаграммы, схемы или инфографики. Такие изображения остаются в очереди OCR, даже если текста на вид немного.',+ values: {+ 'true': { label: 'Да', description: 'да —— график, диаграмма или схема' },+ 'false': { label: 'Нет', description: 'нет —— фото, рисунок, значок или декор' }+ }+ }}}diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.tsindex 0b76196fc..504cf33a0 100755--- a/frontend/src/i18n/locales/zh-CN.ts+++ b/frontend/src/i18n/locales/zh-CN.ts@@ -845,7 +845,7 @@ export default {empty: '暂无 MCP 端点',disabled: '已停用',cardSummary: '{tools} 个工具 · {scope}',- scopeAll: '全部知识库',+ scopeAll: '全部知识库',scopeCount: '{count} 个知识库',create: '新建端点',editTitle: '编辑 MCP 端点',@@ -4069,7 +4069,16 @@ export default {descriptionLanguageAuto: '自动跟随文档语言',customInstructionsLabel: '图片解析要求',customInstructionsDescription: '补充需要重点识别的视觉信息,OCR 和 Markdown 格式协议保持不变',- customInstructionsPlaceholder: '例如:重点识别设备铭牌、型号、告警代码和表格中的单位…'+ customInstructionsPlaceholder: '例如:重点识别设备铭牌、型号、告警代码和表格中的单位…',+ imageAttrsLabel: '图片属性观察',+ imageAttrsDescription: '开启后,解析时对每张图片先「观察属性+描述」,再按属性决定是否对图内文字再跑一轮 OCR;关闭则沿用基础模式:所有图片逐张描述并全部 OCR',+ imageAttrsSchemaLabel: '可观察的图片属性',+ imageAttrsSchemaDescription: '模型会观察以下属性(由后端注册表定义)以驱动 OCR 策略',+ imageAttrsOcrConditions: '根据观察到的属性条件触发 OCR',+ imageAttrsOcrConditionsDesc: '当观察到的属性满足以下条件时,对图片进行 OCR',+ imageAttrsOcrOnUnobserved: '图片属性观察失败时仍执行 OCR',+ imageAttrsOcrOnUnobservedDesc: '当模型未能正确观察到图片属性时,默认仍执行 OCR 兜底,以免漏掉正文文字;关闭则跳过。(采用 4B 等小参数视觉模型,或自定义的图片解析提示词与系统提示词冲突时,可能造成观察失败;8B 及以上模型的失败概率很低,不建议关闭)',+ imagePipelineKbNote: '默认跟随知识库设置,可针对本次任务调整'},tableMetadataInstructions: {label: '表格元数据生成要求',@@ -4435,6 +4444,71 @@ export default {editingBadge: '编辑中',pageActions: '页面操作',tabDocuments: '文档',+ tabGallery: '图库',+ gallery: {+ panelFilter: '筛选设置',+ panelSearch: '搜索设置',+ enableFilter: '开启筛选',+ searchAll: '搜索全部字段',+ verdictDefault: '-',+ verdictOff: 'off',+ verdictOn: 'on',+ searchScope: '搜索范围',+ scopeAll: '全部',+ scopeCustom: '自定义',+ filterScope: '筛选',+ filterOff: '全显示',+ filterOn: '自定义',+ editSearch: '打开搜索设置',+ editFilter: '打开筛选设置',+ pin: '固定到右侧',+ unpin: '取消固定',+ title: '图库',+ searchPlaceholder: '搜索图片内容',+ sortByLabel: '排序',+ orderAsc: '升序',+ orderDesc: '降序',+ filtersTitle: '筛选',+ searchFields: '搜索字段',+ modeAll: '全部字段',+ modeCustom: '自定义',+ keywordsPlaceholder: '多个关键词用逗号分隔',+ applyAll: '全部属性统一设置',+ count: '{count} 张图片',+ empty: '该知识库暂无可浏览的图片',+ emptyFiltered: '没有符合当前筛选条件的图片',+ attrSection: '图片属性',+ noAttrs: '暂无图片属性',+ attributes: '属性',+ caption: '描述',+ ocr: 'OCR 文本',+ source: '来源',+ noCaption: '无描述',+ noOcr: '无 OCR 文本',+ chunkType: '类型',+ viewerClose: '关闭',+ prev: '上一张',+ next: '下一张',+ openSource: '打开来源文档',+ imageLoadError: '图片加载失败',+ // Display names for the builtin attributes the gallery itself+ // declares. Attributes contributed by other sources fall back to the+ // pipeline's own wording (see the imageAttr namespace).+ attr: {+ builtin_caption: '描述',+ builtin_caption_description: '模型生成的图片描述',+ builtin_ocr_text: 'OCR 文本',+ builtin_ocr_text_description: 'OCR 从图片中提取的文字',+ builtin_created_at: '创建时间',+ builtin_created_at_description: '所属文档片段的创建时间',+ builtin_updated_at: '更新时间',+ builtin_updated_at_description: '所属文档片段的最后更新时间',+ builtin_is_enabled: '启用状态',+ builtin_is_enabled_description: '所属文档片段是否参与检索',+ builtin_is_enabled_value_true: '已启用',+ builtin_is_enabled_value_false: '已停用',+ },+ },tabGraph: '图谱',tabGraphTip: 'Wiki 页面之间的引用关系图(即页面链接图谱),与「知识库设置 → 知识图谱」中基于 LLM 抽取的实体-关系图谱不是同一个概念',searchPlaceholder: '搜索 Wiki 页面...',@@ -4935,8 +5009,8 @@ export default {sharedReadonly: '共享给我 · 仅查看'},pin: {- pin: '置顶',- unpin: '取消置顶',+ pin: '置顶',+ unpin: '取消置顶',pinSuccess: '已置顶',unpinSuccess: '已取消置顶',failed: '操作失败'@@ -7659,5 +7733,28 @@ export default {myChats: '我的对话',apiChats: 'API 会话',noSessions: '暂无对话'+ },+ // 图片属性的展示文案,按属性名索引(后端注册表给出属性名,这里只做翻译)。+ // 注意:属性名里的点号要转义成下划线(contain.text → contain_text)——vue-i18n 按点号+ // 逐段下钻,写成字面量 'contain.text' 的键永远取不到。+ // 未翻译的属性会回落到后端注册表自带的说明,所以新增属性不会显示成空行。+ imageAttr: {+ contain_text: {+ label: '图中文字量',+ description: '图片自身承载多少正文文字,决定是否值得为它单独跑一轮 OCR。',+ values: {+ none: { label: '无文字', description: '完全没有文字' },+ sparse: { label: '少量文字', description: '只有少量文字 —— 图标、路牌、单个标签' },+ block: { label: '成段正文', description: '成段正文 —— 截图、表格、文档页面' }+ }+ },+ contain_data_visual: {+ label: '数据可视化',+ description: '图片是否以图表、曲线、示意图或信息图的方式承载数据;这类图即使看起来文字很少,也会保留在 OCR 路径上。',+ values: {+ 'true': { label: '是', description: '是 —— 图表、曲线或示意图' },+ 'false': { label: '否', description: '否 —— 照片、插画、图标或装饰图' }+ }+ }}}diff --git a/frontend/src/types/knowledgeProcess.ts b/frontend/src/types/knowledgeProcess.tsindex 386528e9a..8f5e3f326 100644--- a/frontend/src/types/knowledgeProcess.ts+++ b/frontend/src/types/knowledgeProcess.ts@@ -1,5 +1,7 @@/** Matches backend types.KnowledgeProcessOverrides (snake_case JSON). */+import type { ImageActionsConfig } from '@/api/knowledge-base'+export interface ParserEngineRule {file_types: string[]engine: string@@ -69,5 +71,11 @@ export interface KnowledgeProcessOverrides {question_generation_config?: QuestionGenerationConfigOverridegraph_enabled?: booleanextract_config?: ExtractConfigOverride+ // Per-upload override of the knowledge base's attribute-observed image+ // pipeline switch.+ image_attrs_enabled?: boolean+ // Per-task attribute -> work table; merged per action key on top of the+ // knowledge base's table.+ image_actions?: ImageActionsConfigparser_engine_overrides?: Record<string, string>}diff --git a/frontend/src/utils/imageAttrDisplay.test.ts b/frontend/src/utils/imageAttrDisplay.test.tsnew file mode 100644index 000000000..11ece6bc8--- /dev/null+++ b/frontend/src/utils/imageAttrDisplay.test.ts@@ -0,0 +1,257 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import { createI18n } from 'vue-i18n'++import type { ImageAttrSchema, ImageAttrSpec } from '@/api/knowledge-base'+import enUS from '../i18n/locales/en-US.ts'+import jaJP from '../i18n/locales/ja-JP.ts'+import koKR from '../i18n/locales/ko-KR.ts'+import ruRU from '../i18n/locales/ru-RU.ts'+import zhCN from '../i18n/locales/zh-CN.ts'+import { imageAttrConditionDisplay, imageAttrDisplay, imageAttrKeyBase } from './imageAttrDisplay.ts'++const SPEC: ImageAttrSpec = {+ name: 'contain.text',+ type: 'extent',+ values: [+ { value: 'none', label: 'no text at all', description: 'the image carries no text at all' },+ { value: 'sparse', label: 'a few words', description: 'a logo, a road sign, a single label' },+ { value: 'block', label: 'a block of body text', description: 'a screenshot, a table, a document page' },+ ],+ question: '',+ label: 'Text in the image',+ description: 'How much body text the picture carries.',+}++const PRESENCE: ImageAttrSpec = {+ name: 'contain.data_visual',+ type: 'presence',+ question: '',+ label: 'Data visual',+ description: 'Whether the picture conveys data as a chart.',+ values: [+ { value: 'true', label: 'yes' },+ { value: 'false', label: 'no' },+ ],+}++const SCHEMA: ImageAttrSchema = {+ version: 'attrs/2',+ prompt: 'observe/1',+ attributes: [SPEC, PRESENCE],+ default_actions: {+ ocr: {+ on: [+ { prop: 'contain.text', is: 'block' },+ { prop: 'contain.data_visual', is: 'true' },+ ],+ on_unobserved: true,+ },+ },+}++/** No translations at all: the registry's own wording has to carry the panel. */+const noI18n = { t: (key: string) => key, te: () => false }++test('falls back to the registry wording when nothing is translated', () => {+ const display = imageAttrDisplay(SPEC, noI18n.t, noI18n.te)++ assert.equal(display.name, 'contain.text')+ assert.equal(display.label, 'Text in the image')+ assert.equal(display.description, 'How much body text the picture carries.')+ assert.deepEqual(+ display.values.map((value) => value.value),+ ['none', 'sparse', 'block'],+ )+ assert.equal(display.values[2].label, 'a block of body text')+})++test('prefers the translation overlay, keyed by attribute name', () => {+ // Keys escape the dots in the attribute name (see imageAttrKeyBase).+ const zh: Record<string, string> = {+ 'imageAttr.contain_text.label': '图中文字量',+ 'imageAttr.contain_text.values.block.label': '成段正文',+ 'imageAttr.contain_text.values.block.description': '成段正文 —— 截图、表格或文档页面',+ }+ const display = imageAttrDisplay(SPEC, (key) => zh[key] ?? key, (key) => key in zh)++ assert.equal(display.label, '图中文字量')+ // Untranslated pieces keep the registry wording instead of exposing the key.+ assert.equal(display.description, 'How much body text the picture carries.')+ assert.equal(display.values[0].label, 'no text at all')+ assert.equal(display.values[2].label, '成段正文')+ // The same split applies to a value's longer text.+ assert.equal(display.values[2].description, '成段正文 —— 截图、表格或文档页面')+ assert.equal(display.values[0].description, 'the image carries no text at all')+})++test('never shows a blank label when the registry omits display text', () => {+ const bare: ImageAttrSpec = {+ ...SPEC,+ label: '',+ description: undefined,+ values: [+ { value: 'none', label: '', description: '' },+ { value: 'sparse', label: '', description: '' },+ { value: 'block', label: '', description: '' },+ ],+ }+ const display = imageAttrDisplay(bare, noI18n.t, noI18n.te)++ assert.equal(display.label, 'contain.text')+ assert.equal(display.description, '')+ assert.deepEqual(+ display.values.map((value) => value.label),+ ['none', 'sparse', 'block'],+ )+})++test('a presence attribute without an explicit value list offers true/false', () => {+ const display = imageAttrDisplay(PRESENCE, noI18n.t, noI18n.te)++ assert.deepEqual(+ display.values.map((value) => value.value),+ ['true', 'false'],+ )+ assert.equal(display.values[0].label, 'yes')+})++test('renders a policy condition in words next to its raw pair', () => {+ const zh: Record<string, string> = {+ 'imageAttr.contain_text.label': '图中文字量',+ 'imageAttr.contain_text.values.block.label': '成段正文',+ }+ const condition = imageAttrConditionDisplay(+ { prop: 'contain.text', is: 'block' },+ SCHEMA,+ (key) => zh[key] ?? key,+ (key) => key in zh,+ )++ assert.equal(condition.label, '图中文字量 = 成段正文')+ assert.equal(condition.raw, 'contain.text = block')+})++test('an unknown attribute or value degrades to its raw form', () => {+ const unknownProp = imageAttrConditionDisplay(+ { prop: 'contain.mystery', is: 'x' },+ SCHEMA,+ noI18n.t,+ noI18n.te,+ )+ assert.equal(unknownProp.label, 'contain.mystery = x')+ assert.equal(unknownProp.raw, 'contain.mystery = x')++ const unknownValue = imageAttrConditionDisplay(+ { prop: 'contain.text', is: 'huge' },+ SCHEMA,+ noI18n.t,+ noI18n.te,+ )+ assert.equal(unknownValue.label, 'Text in the image = huge')+})++// ---------------------------------------------------------------------------+// The real bundles, resolved by the real vue-i18n.+//+// The faked translators above answer a flat key lookup, so they would happily+// "translate" a key the real bundle can never resolve — which is exactly how a+// literal `'contain.text'` message key slipped through once (vue-i18n walks a+// key segment by segment on the dots, so it looked for `imageAttr` → `contain`).+// These tests therefore use createI18n, the same resolver the app runs.+// ---------------------------------------------------------------------------++// Each bundle is wired with a literal locale key, the same shape the app's own+// createI18n call uses, so the messages argument keeps a checkable type.+const MESSAGES_BY_LOCALE = {+ 'zh-CN': { 'zh-CN': zhCN },+ 'en-US': { 'en-US': enUS },+ 'ja-JP': { 'ja-JP': jaJP },+ 'ko-KR': { 'ko-KR': koKR },+ 'ru-RU': { 'ru-RU': ruRU },+}++type TestLocale = keyof typeof MESSAGES_BY_LOCALE++const LOCALES = Object.keys(MESSAGES_BY_LOCALE) as TestLocale[]++function translator(locale: TestLocale) {+ const i18n = createI18n({+ legacy: false,+ locale,+ fallbackLocale: locale,+ warnHtmlMessage: false,+ messages: MESSAGES_BY_LOCALE[locale],+ })+ const global = i18n.global as unknown as {+ t: (key: string) => string+ te: (key: string) => boolean+ }+ return {+ t: (key: string) => global.t(key),+ te: (key: string) => global.te(key),+ }+}++test('every shipped locale translates every attribute key', () => {+ for (const locale of LOCALES) {+ const { te, t } = translator(locale)++ for (const spec of SCHEMA.attributes) {+ const base = imageAttrKeyBase(spec.name)+ const keys = [+ `${base}.label`,+ `${base}.description`,+ ...imageAttrDisplay(spec, t, te).values.map(+ (value) => `${base}.values.${value.value}.label`,+ ),+ ]+ for (const key of keys) {+ assert.equal(te(key), true, `${locale}: ${key} does not resolve`)+ assert.ok(t(key).length > 0, `${locale}: ${key} is empty`)+ }+ }+ }+})++test('every shipped locale translates every OCR condition key', () => {+ for (const locale of LOCALES) {+ const { te } = translator(locale)++ for (const cond of SCHEMA.default_actions.ocr.on) {+ const base = imageAttrKeyBase(cond.prop)+ assert.equal(te(`${base}.label`), true, `${locale}: ${base}.label does not resolve`)+ assert.equal(+ te(`${base}.values.${cond.is}.label`),+ true,+ `${locale}: ${base}.values.${cond.is}.label does not resolve`,+ )+ }+ }+})++test('the panel actually renders the translated text, not the registry fallback', () => {+ const { t, te } = translator('zh-CN')++ for (const spec of SCHEMA.attributes) {+ const display = imageAttrDisplay(spec, t, te)++ assert.match(display.label, /[\u4e00-\u9fa5]/, `${spec.name}: label is not Chinese`)+ assert.match(display.description, /[\u4e00-\u9fa5]/, `${spec.name}: description is not Chinese`)+ for (const value of display.values) {+ assert.match(+ value.label,+ /[\u4e00-\u9fa5]/,+ `${spec.name}.${value.value}: value is not Chinese`,+ )+ }+ }++ for (const cond of SCHEMA.default_actions.ocr.on) {+ const display = imageAttrConditionDisplay(cond, SCHEMA, t, te)+ assert.match(display.label, /[\u4e00-\u9fa5]/, `${cond.prop}=${cond.is}: condition is not Chinese`)+ // The raw pair stays alongside, so the panel still lines up with the trace.+ assert.equal(display.raw, `${cond.prop} = ${cond.is}`)+ }+})diff --git a/frontend/src/utils/imageAttrDisplay.ts b/frontend/src/utils/imageAttrDisplay.tsnew file mode 100644index 000000000..4894aa333--- /dev/null+++ b/frontend/src/utils/imageAttrDisplay.ts@@ -0,0 +1,135 @@+import type {+ ImageAttrCondition,+ ImageAttrSchema,+ ImageAttrSpec,+ ImageAttrValue,+} from '@/api/knowledge-base'++// ---------------------------------------------------------------------------+// Display text for the image-attribute panel.+//+// The registry returned by GET /image-attrs/schema is the single source of+// truth — it carries the attribute's name, what it measures, and what each of+// its values means. That is what lets a non-technical operator read+// "Text in the image: a block of body text" instead of+// "contain.text: block", and it is why adding an attribute to the backend shows+// up here with no frontend change.+//+// Translations are an overlay keyed by the attribute name, applied on top of+// the registry text. Anything not translated yet falls back to the registry+// wording, so a brand-new attribute still reads as words rather than as a bare+// key. (The i18n keys are built at runtime from the attribute name, which is+// why the `imageAttr.` prefix is registered in localeKeyAudit's EXTRA_PREFIXES.)+// ---------------------------------------------------------------------------++type Translate = (key: string) => string+type HasTranslation = (key: string) => boolean++/** One allowed value of an attribute, with its meaning in words. */+export interface ImageAttrValueDisplay {+ /** The raw value as it appears in the registry and the processing trace. */+ value: string+ /** The short, on-screen name for this value. */+ label: string+ /** The sentence explaining the value; empty when the registry has none. */+ description: string+}++/** One attribute as the settings panel shows it. */+export interface ImageAttrDisplay {+ /** Stable attribute key, e.g. "contain.text". Shown small, to line up with the trace. */+ name: string+ /** Human-readable name, e.g. "Text in the image". */+ label: string+ /** One line saying what the attribute measures. Empty when unavailable. */+ description: string+ /** Every allowed value with its meaning, in the registry's order. */+ values: ImageAttrValueDisplay[]+}++/** One OCR policy condition, in words plus the raw pair. */+export interface ImageAttrConditionDisplay {+ /** e.g. "Text in the image = a block of body text" */+ label: string+ /** e.g. "contain.text = block" — keeps the panel aligned with the trace. */+ raw: string+}++/** The values a spec declares; presence attributes list true/false implicitly. */+function specValues(attr: ImageAttrSpec): ImageAttrValue[] {+ if (attr.values && attr.values.length) return attr.values+ return attr.type === 'presence' ? [{ value: 'true', label: 'true' }, { value: 'false', label: 'false' }] : []+}++/**+ * The i18n namespace for one attribute.+ *+ * vue-i18n resolves a key by walking it segment by segment on the dots, so a+ * literal `'contain.text'` message key is unreachable through+ * `imageAttr.contain.text.label` — the lookup goes looking for `imageAttr` →+ * `contain` → `text` and stops. Attribute names therefore escape their dots+ * (`contain.text` → `contain_text`) to become a single resolvable segment. The+ * same mapping is applied in every locale bundle, so a new attribute only needs+ * its name spelled the same way.+ */+export function imageAttrKeyBase(name: string): string {+ return `imageAttr.${name.replace(/\./g, '_')}`+}++/** Look up `key`, falling back to the registry's own wording. */+function pick(key: string, fallback: string, t: Translate, te: HasTranslation): string {+ return te(key) ? t(key) : fallback+}++/**+ * Render one registry attribute for the settings panel. Never returns an empty+ * label: an attribute that arrives without display text still shows its name,+ * so the panel degrades to identifiers rather than to blanks.+ */+export function imageAttrDisplay(+ attr: ImageAttrSpec,+ t: Translate,+ te: HasTranslation,+): ImageAttrDisplay {+ const base = imageAttrKeyBase(attr.name)+ return {+ name: attr.name,+ label: pick(`${base}.label`, attr.label || attr.name, t, te),+ description: pick(`${base}.description`, attr.description ?? '', t, te),+ values: specValues(attr).map((value) => ({+ value: value.value,+ label: pick(+ `${base}.values.${value.value}.label`,+ value.label || value.value,+ t,+ te,+ ),+ description: pick(+ `${base}.values.${value.value}.description`,+ value.description ?? '',+ t,+ te,+ ),+ })),+ }+}++/**+ * Render one OCR policy condition in the same words as the attribute list,+ * keeping the raw `prop = value` pair so an operator can still match the panel+ * against the processing trace.+ */+export function imageAttrConditionDisplay(+ cond: ImageAttrCondition,+ schema: ImageAttrSchema,+ t: Translate,+ te: HasTranslation,+): ImageAttrConditionDisplay {+ const raw = `${cond.prop} = ${cond.is}`+ const attr = schema.attributes.find((candidate) => candidate.name === cond.prop)+ if (!attr) return { label: raw, raw }++ const display = imageAttrDisplay(attr, t, te)+ const value = display.values.find((candidate) => candidate.value === cond.is)+ return { label: `${display.label} = ${value ? value.label : cond.is}`, raw }+}diff --git a/frontend/src/utils/imageProcessingConfig.test.ts b/frontend/src/utils/imageProcessingConfig.test.tsnew file mode 100644index 000000000..56178c21b--- /dev/null+++ b/frontend/src/utils/imageProcessingConfig.test.ts@@ -0,0 +1,48 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import { buildImageProcessingConfig } from './imageProcessingConfig.ts'++const DEFAULT_ON = [+ { prop: 'contain.text', is: 'block' },+ { prop: 'contain.data_visual', is: 'true' },+]++test('saving keeps OCR conditions customised through the API', () => {+ // Regression: the editor always wrote the registry default into `on`, so an+ // unrelated edit replaced a KB's custom OCR conditions with the default table.+ const custom = [{ prop: 'contain.text', is: 'sparse' }]+ const built = buildImageProcessingConfig(+ { model_id: 'vlm-1', image_attrs_enabled: true, image_actions: { ocr: { on: custom, on_unobserved: true } } },+ { imageAttrsEnabled: true, onUnobserved: false, defaultOn: DEFAULT_ON },+ )++ assert.deepEqual(built, {+ model_id: 'vlm-1',+ image_attrs_enabled: true,+ image_actions: { ocr: { on: custom, on_unobserved: false } },+ })+})++test('a KB without custom conditions gets the registry default alongside on_unobserved', () => {+ const built = buildImageProcessingConfig(+ { model_id: 'vlm-1' },+ { imageAttrsEnabled: true, onUnobserved: false, defaultOn: DEFAULT_ON },+ )++ assert.deepEqual(built, {+ model_id: 'vlm-1',+ image_attrs_enabled: true,+ image_actions: { ocr: { on: DEFAULT_ON, on_unobserved: false } },+ })+})++test('an unchanged configuration is not sent', () => {+ const custom = [{ prop: 'contain.text', is: 'sparse' }]+ const snapshot = { image_attrs_enabled: true, image_actions: { ocr: { on: custom, on_unobserved: true } } }++ assert.equal(+ buildImageProcessingConfig(snapshot, { imageAttrsEnabled: true, onUnobserved: true, defaultOn: DEFAULT_ON }),+ null,+ )+})diff --git a/frontend/src/utils/imageProcessingConfig.ts b/frontend/src/utils/imageProcessingConfig.tsnew file mode 100644index 000000000..400b06191--- /dev/null+++ b/frontend/src/utils/imageProcessingConfig.ts@@ -0,0 +1,44 @@+/** One OCR trigger condition: attribute `prop` equals `is`. */+export interface ImageAttrConditionLike {+ prop: string+ is: string+}++/** The fields of the KB editor that feed image_processing_config. */+export interface ImageProcessingEdits {+ imageAttrsEnabled: boolean+ onUnobserved: boolean+ /** The registry's current default OCR conditions (GET /image-attrs/schema). */+ defaultOn: ImageAttrConditionLike[]+}++/**+ * Builds the image_processing_config the KB editor saves, or null when nothing+ * changed. The backend replaces the whole object, so every field the editor+ * does not own (model_id, ...) is carried over from the snapshot.+ *+ * The editor only edits the observation switch and on_unobserved, but+ * on_unobserved must travel with a non-empty `on`: the backend adopts a custom+ * OCR clause only when `on` is set. A knowledge base whose `on` was customised+ * through the API keeps it; one without a custom list gets the registry's+ * current default, so it still follows the default as it evolves.+ */+export function buildImageProcessingConfig(+ snapshot: Record<string, unknown> | null | undefined,+ edits: ImageProcessingEdits,+): Record<string, unknown> | null {+ const snap = snapshot || {}+ const storedOn = (snap.image_actions as { ocr?: { on?: unknown } } | undefined)?.ocr?.on+ const on = Array.isArray(storedOn) && storedOn.length > 0 ? storedOn : edits.defaultOn+ const built = {+ ...snap,+ image_attrs_enabled: edits.imageAttrsEnabled,+ image_actions: {+ ocr: {+ on,+ on_unobserved: edits.onUnobserved,+ },+ },+ }+ return JSON.stringify(built) === JSON.stringify(snap) ? null : built+}diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vueindex f93198a38..d97984c55 100644--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue@@ -4010,4 +4010,10 @@ const handleAddToKnowledge = (answerEvent: any) => {}</style>-<style lang="less" src="@/components/css/wiki-graph-drawer.less"></style>+<!-- Inlined @import instead of <style src>: plugin-vue 6.0.6 keys unscoped+ src-style descriptors by the imported file path, so two SFCs sharing the+ same src style (this file and WikiBrowser.vue) overwrite each other's+ descriptor during the build and crash with "reading 'scoped'". -->+<style lang="less">+@import "@/components/css/wiki-graph-drawer.less";+</style>diff --git a/frontend/src/views/knowledge/KnowledgeBase.vue b/frontend/src/views/knowledge/KnowledgeBase.vueindex d39564aed..d8170d671 100644--- a/frontend/src/views/knowledge/KnowledgeBase.vue+++ b/frontend/src/views/knowledge/KnowledgeBase.vue@@ -54,6 +54,7 @@ import type { KnowledgeProcessOverrides } from '@/types/knowledgeProcess';import { useUploadConfirmStore, type UploadConfirmResult } from '@/stores/uploadConfirm';import { useUploadTasksStore } from '@/stores/uploadTasks';import WikiBrowser from './wiki/WikiBrowser.vue';+import ImageGallery from './gallery/ImageGallery.vue';import { getWikiStats } from '@/api/wiki';import {isKnowledgeParseInFlight,@@ -91,7 +92,7 @@ const kbLoading = ref(false);const docListLoading = ref(true);const isFAQ = computed(() => (kbInfo.value?.type || '') === 'faq');const isWiki = computed(() => !!kbInfo.value?.indexing_strategy?.wiki_enabled);-const validTabs = ['documents', 'wiki', 'graph'] as const+const validTabs = ['documents', 'wiki', 'graph', 'gallery'] as consttype KbTab = typeof validTabs[number]const initTab = validTabs.includes(route.query.tab as any) ? (route.query.tab as KbTab) : 'documents'const activeKbTab = ref<KbTab>(initTab);@@ -2257,9 +2258,9 @@ const handleKBEditorSuccess = (kbIdValue: string) => {</template></button><t-icon name="chevron-right" class="breadcrumb-separator" />+ <span :class="['breadcrumb-tab', { active: activeKbTab === 'documents' }]"+ @click="activeKbTab = 'documents'">{{ $t('knowledgeEditor.wikiBrowser.tabDocuments') }}</span><template v-if="isWiki">- <span :class="['breadcrumb-tab', { active: activeKbTab === 'documents' }]"- @click="activeKbTab = 'documents'">{{ $t('knowledgeEditor.wikiBrowser.tabDocuments') }}</span><span class="breadcrumb-tab-sep">/</span><span :class="['breadcrumb-tab', { active: activeKbTab === 'wiki', indexing: wikiIsIndexing }]"@click="activeKbTab = 'wiki'">@@ -2278,8 +2279,12 @@ const handleKBEditorSuccess = (kbIdValue: string) => {</t-tooltip></span></t-tooltip>+ <span class="breadcrumb-tab-sep">/</span></template>- <span v-else class="breadcrumb-current">{{ $t('knowledgeEditor.document.title') }}</span>+ <span :class="['breadcrumb-tab', { active: activeKbTab === 'gallery' }]"+ @click="activeKbTab = 'gallery'">+ {{ $t('knowledgeEditor.wikiBrowser.tabGallery') }}+ </span></h2><!-- 标题行右侧的动作锚点:聚拢"信息"和"设置"两个圆形按钮。 --><div class="kb-title-actions">@@ -2316,7 +2321,12 @@ const handleKBEditorSuccess = (kbIdValue: string) => {@view-graph="onViewWikiInGraph" /></div>- <template v-if="activeKbTab === 'documents' || !isWiki">+ <!-- Image Gallery (4th tab) -->+ <ImageGallery v-if="activeKbTab === 'gallery' && kbId" :knowledge-base-id="kbId" />++ <!-- wiki/graph tabs only exist on wiki KBs; a stale tab (?tab= or one+ carried over from a previous KB) falls back to documents. -->+ <template v-if="activeKbTab === 'documents' || (!isWiki && activeKbTab !== 'gallery')"><div class="knowledge-main"><KbFolderTree v-if="showFolderTree && !folderTreeCollapsed" :tree="folderTree" :selected-path="selectedFolderPath":loading="folderTreeLoading" :can-edit="canEdit" :root-label="kbInfo?.name"diff --git a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.test.mjs b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.test.mjsindex 224b955e2..e5de2d805 100644--- a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.test.mjs+++ b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.test.mjs@@ -30,3 +30,23 @@ test('shows a post-create hint after the first successful save', () => {assert.match(source, /settings-footer-note/)assert.match(source, /knowledgeEditor\.postCreateHint\.followUpDesc/)})++test('create mode seeds the full default image actions table', () => {+ // Regression: an empty imageActions in initFormData made the attribute panel+ // read `undefined.ocr.on_unobserved` the moment the attribute switch was turned+ // on in the create dialog, crashing the modal.+ const initBlock = source.match(/const initFormData[\s\S]*?imageActions: ([^,]+),/)?.[1]+ assert.ok(initBlock, 'expected to find imageActions in initFormData')+ assert.match(initBlock, /mergeImageActions\(\)/)+})++test('edit mode forwards image_processing_config in the update payload', () => {+ // Regression: the edit branch built data.image_processing_config but never+ // put it into updateConfig, so KB-editor changes to the image classification+ // settings were silently dropped (create worked, later edits did not).+ const editBranch = source.match(+ /(\/\/ 编辑模式:分别更新基本信息[\s\S]*?await updateKnowledgeBase\(kbId, \{)/+ )?.[1]+ assert.ok(editBranch, 'expected to find the edit-mode update block')+ assert.match(editBranch, /if \(data\.image_processing_config\) \{\s*updateConfig\.image_processing_config = data\.image_processing_config\s*\}/)+})diff --git a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vueindex f12eb8f61..f7fdd0555 100644--- a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue+++ b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue@@ -363,6 +363,67 @@:maxlength="4000" :autosize="{ minRows: 3, maxRows: 8 }" /></div></div>++ <div v-if="formData.multimodalConfig.enabled" class="setting-row">+ <div class="setting-info">+ <label>{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsLabel') }}</label>+ <p class="desc">{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsDescription') }}</p>+ </div>+ <t-switch v-model="formData.imageAttrsEnabled" size="medium" />+ </div>++ <div v-if="formData.multimodalConfig.enabled && formData.imageAttrsEnabled"+ class="setting-row setting-row-vertical">+ <div class="setting-info">+ <label>{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsSchemaLabel') }}</label>+ <!-- 实现说明(不放 UI):面板完全由后端属性注册表驱动 —— 属性名、说明、每个取值的+ 含义都随 schema 端点下发,前端只按属性名覆盖翻译。所以新增属性仍是+ 「后端加一行 / 前端自动跟随」,属性集合随版本演进不需要改这里。 -->+ <p class="desc">{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsSchemaDescription') }}</p>+ </div>+ <div class="image-attr-panel">+ <ul v-if="imageAttrDisplays.length" class="image-attr-list">+ <li v-for="attr in imageAttrDisplays" :key="attr.name" class="image-attr-row">+ <div class="image-attr-head">+ <span class="image-attr-label">{{ attr.label }}</span>+ <code class="image-attr-name">{{ attr.name }}</code>+ </div>+ <p v-if="attr.description" class="image-attr-desc">{{ attr.description }}</p>+ <ul class="image-attr-value-list">+ <li v-for="v in attr.values" :key="v.value" class="image-attr-value">+ <code>{{ v.value }}</code>+ <span class="image-attr-value-label">{{ v.label }}</span>+ </li>+ </ul>+ </li>+ </ul>+ <div class="image-attr-section">+ <div class="setting-info">+ <label>{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsOcrConditions') }}</label>+ <p class="desc">{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsOcrConditionsDesc') }}</p>+ </div>+ <ul class="image-attr-condition-list">+ <li v-for="(cond, i) in imageAttrConditionDisplays" :key="i" class="image-attr-condition">+ <span class="image-attr-condition-label">{{ cond.label }}</span>+ <code class="image-attr-condition-raw">{{ cond.raw }}</code>+ </li>+ </ul>+ </div>+ </div>++ <!-- 观察失败兜底:与上方整块开关同级(不再嵌在属性面板里)。+ 开关仍包在 setting-control 里,与其它开关行共用同一套+ 右对齐 / 垂直居中 / 预留右列的排版,避免顶到行首 -->+ <div class="setting-row">+ <div class="setting-info">+ <label>{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsOcrOnUnobserved') }}</label>+ <p class="desc">{{ $t('knowledgeEditor.advanced.multimodal.imageAttrsOcrOnUnobservedDesc') }}</p>+ </div>+ <div class="setting-control">+ <t-switch v-model="formData.imageActions.ocr.on_unobserved" size="medium" />+ </div>+ </div>+ </div></div></div></div>@@ -503,8 +564,29 @@ import {updateKnowledgeBase,rebuildKBIndex,generateKnowledgeBaseProfile,+ mergeImageActions,+ fetchImageAttrSchema,+ FALLBACK_IMAGE_ATTR_SCHEMA,+ type ImageActionsConfig,+ type ImageAttrSchema,type KnowledgeBaseProfile,} from '@/api/knowledge-base'+import { buildImageProcessingConfig } from '@/utils/imageProcessingConfig'+import { imageAttrDisplay, imageAttrConditionDisplay } from '@/utils/imageAttrDisplay'++// The image-attribute registry, fetched from the backend (single source of+// truth). Falls back to the static registry until the endpoint answers.+const imageAttrSchema = ref<ImageAttrSchema | null>(null)+const displaySchema = computed<ImageAttrSchema>(+ () => imageAttrSchema.value ?? FALLBACK_IMAGE_ATTR_SCHEMA,+)+async function loadImageAttrSchema(kbId: string) {+ try {+ imageAttrSchema.value = await fetchImageAttrSchema(kbId)+ } catch {+ imageAttrSchema.value = null+ }+}import { updateKBConfig, type KBModelConfigRequest } from '@/api/initialization'import { useChatResourcesStore } from '@/stores/chatResources'import { selectInitialModelId } from '@/utils/modelDefaults'@@ -529,7 +611,22 @@ const uiStore = useUIStore()const authStore = useAuthStore()const chatResources = useChatResourcesStore()const editorResources = useEditorResourcesStore()-const { t } = useI18n()+const { t, te } = useI18n()++// The attribute panel and the OCR conditions are both rendered from the+// registry, in the operator's language: the registry supplies the wording and+// the i18n overlay translates it, so a new backend attribute shows up here+// without a frontend change.+const imageAttrDisplays = computed(() =>+ displaySchema.value.attributes.map((attr) => imageAttrDisplay(attr, t, te)),+)+// The conditions the knowledge base actually runs with: a list customised through the+// API is shown as is, otherwise mergeImageActions filled in the default.+const imageAttrConditionDisplays = computed(() =>+ (formData.value.imageActions as ImageActionsConfig).ocr.on.map((cond) =>+ imageAttrConditionDisplay(cond, displaySchema.value, t, te),+ ),+)// Propsconst props = defineProps<{@@ -807,6 +904,13 @@ const initFormData = (type: 'document' | 'faq' = 'document') => {descriptionLanguage: '',customInstructions: ''},+ // 图片属性观察管线:开关 + on_unobserved 兜底切换由 UI 编辑;其余配置+ // (model_id 等)按加载时的快照原样回传,避免把 API 侧写入的设置洗掉。+ // 新建模式也必须用完整默认动作初始化——imageActions.ocr.on_unobserved+ // 直接被开关绑定,缺省会让打开开关的瞬间渲染崩溃。+ imageAttrsEnabled: false,+ imageActions: mergeImageActions(),+ imageProcessingConfigSnapshot: null as Record<string, unknown> | null,asrConfig: {enabled: false,modelId: '',@@ -956,6 +1060,13 @@ const loadKBData = async (descriptionLanguage: kb.vlm_config?.description_language || '',customInstructions: kb.vlm_config?.custom_instructions || ''},+ imageAttrsEnabled:+ !!(kb as Record<string, any>).image_processing_config?.image_attrs_enabled,+ imageActions: mergeImageActions(+ (kb as Record<string, any>).image_processing_config?.image_actions,+ ),+ imageProcessingConfigSnapshot:+ (kb as Record<string, any>).image_processing_config || null,asrConfig: {enabled: !!kb.asr_config?.enabled,modelId: kb.asr_config?.model_id || '',@@ -1022,6 +1133,8 @@ const loadKBData = async (status: kb.vector_store_status,},}+ // 拉取后端属性注册表,驱动属性面板的动态渲染(编辑模式有 kbId)。+ loadImageAttrSchema(kbId)initialStorageProvider.value = formData.value.storageProviderinitialIndexingStrategy.value = { ...formData.value.indexingStrategy }} catch (error) {@@ -1337,6 +1450,20 @@ const buildSubmitData = () => {custom_instructions: formData.value.multimodalConfig.customInstructions || ''}+ // 图片属性观察配置:后端是整体替换语义(payload 不带该字段 = 保持不变)。+ // UI 只编辑观察开关与 on_unobserved;快照里用 API 自定义过的 on 原样保留,+ // 没有自定义时才取注册表默认值。合并规则见 buildImageProcessingConfig。+ {+ const built = buildImageProcessingConfig(formData.value.imageProcessingConfigSnapshot, {+ imageAttrsEnabled: formData.value.imageAttrsEnabled,+ onUnobserved: formData.value.imageActions.ocr.on_unobserved,+ defaultOn: displaySchema.value.default_actions.ocr.on,+ })+ if (built) {+ data.image_processing_config = built+ }+ }+// 添加ASR语音识别配置data.asr_config = {enabled: formData.value.asrConfig?.enabled || false,@@ -1523,6 +1650,12 @@ const doSubmit = async () => {graph_enabled: formData.value.indexingStrategy?.graphEnabled ?? false,}}+ // 图片分类配置:buildSubmitData 只在与快照有差异时才产出该字段,带上即+ // 整体替换(后端语义:字段缺失 = 保持不变)。编辑模式此前漏带,导致 KB+ // 编辑器里对图片分类的修改被静默丢弃(新建时能存、之后再改无效)。+ if (data.image_processing_config) {+ updateConfig.image_processing_config = data.image_processing_config+ }await updateKnowledgeBase(kbId, {name: data.name,description: data.description,@@ -1726,6 +1859,103 @@ watch(() => chatResources.allModels, (list) => {</script><style scoped lang="less">+// 图片属性面板(可观察属性 / OCR 触发条件 / 观察失败兜底)+// 文案全部来自后端属性注册表(人话名 + 每个取值的含义),前端只做翻译覆盖,+// 因此新增属性无需改这里。铺在所在设置区里、不套独立底色块(与整体风格一致)。+.image-attr-panel {+ margin-top: 4px;+}+.image-attr-list,+.image-attr-value-list,+.image-attr-condition-list {+ margin: 0;+ padding: 0;+ list-style: none;+}+.image-attr-row + .image-attr-row {+ margin-top: 12px;+ padding-top: 12px;+ border-top: 1px solid var(--td-component-border);+}+.image-attr-head {+ display: flex;+ align-items: baseline;+ gap: 6px;+ flex-wrap: wrap;+}+.image-attr-label {+ font-weight: 600;+ color: var(--td-text-color-primary);+}+// 原始属性名缩小并加括号,便于与处理轨迹里的字段对上,又不干扰阅读+.image-attr-name {+ font-family: ui-monospace, Menlo, Consolas, monospace;+ font-size: var(--app-text-xs);+ color: var(--td-text-color-placeholder);++ &::before {+ content: '(';+ }++ &::after {+ content: ')';+ }+}+.image-attr-desc {+ margin: 2px 0 0;+ font-size: var(--app-text-sm);+ line-height: 20px;+ color: var(--td-text-color-secondary);+}+// 每个取值一行:值(等宽,左列对齐)+ 冒号 + 人话解释+.image-attr-value-list {+ display: grid;+ grid-template-columns: max-content 1fr;+ column-gap: 2px;+ row-gap: 2px;+ margin-top: 6px;+ font-size: var(--app-text-sm);+}+// display: contents 让值与解释分别落进上面两列,取值因此左对齐成列+.image-attr-value {+ display: contents;++ code {+ font-family: ui-monospace, Menlo, Consolas, monospace;+ color: var(--td-text-color-primary);++ // 冒号紧跟取值,不留空隙:none: 没有文字+ &::after {+ content: ':';+ }+ }+}+.image-attr-value-label {+ color: var(--td-text-color-secondary);+}+.image-attr-section {+ margin-top: 14px;+}+// 一条 OCR 条件两行:人话在上,原始 property = value 在下+.image-attr-condition-list {+ margin-top: 6px;+ font-size: var(--app-text-sm);+}+.image-attr-condition + .image-attr-condition {+ margin-top: 6px;+}+.image-attr-condition-label {+ display: block;+ color: var(--td-text-color-primary);+}+.image-attr-condition-raw {+ display: block;+ margin-top: 1px;+ font-family: ui-monospace, Menlo, Consolas, monospace;+ font-size: var(--app-text-xs);+ color: var(--td-text-color-placeholder);+}+// 复用创建知识库的样式/* 左侧导航:与 AgentEditorModal 对齐 */.content-wrapper {@@ -1982,6 +2212,17 @@ watch(() => chatResources.allModels, (list) => {}}+ // 纵向行(类别 OCR 策略表用):说明文字占满整行,表格换到下一行+ .setting-row-vertical {+ flex-direction: column;+ align-items: stretch;++ > .setting-info {+ max-width: 100%;+ padding-right: 0;+ }+ }+.setting-info {flex: 1;max-width: 65%;diff --git a/frontend/src/views/knowledge/components/UploadConfirmDialog.vue b/frontend/src/views/knowledge/components/UploadConfirmDialog.vueindex 0f00c9e5d..4c02e16f3 100644--- a/frontend/src/views/knowledge/components/UploadConfirmDialog.vue+++ b/frontend/src/views/knowledge/components/UploadConfirmDialog.vue@@ -421,6 +421,74 @@/></div></div>+ <div v-if="uiState.multimodalConfig.enabled" class="setting-row">+ <div class="setting-info">+ <label>{{ t('knowledgeEditor.advanced.multimodal.imageAttrsLabel') }}</label>+ <p class="desc">{{ t('knowledgeEditor.advanced.multimodal.imageAttrsDescription') }}</p>+ </div>+ <t-switch v-model="uiState.imageAttrsEnabled" size="medium" />+ </div>+ <div+ v-if="uiState.multimodalConfig.enabled && uiState.imageAttrsEnabled"+ class="setting-row setting-row-vertical"+ >+ <div class="setting-info">+ <label>{{ t('knowledgeEditor.advanced.multimodal.imageAttrsSchemaLabel') }}</label>+ <!-- 实现说明(不放 UI):面板完全由后端属性注册表驱动 —— 属性名、说明、+ 每个取值的含义都随 schema 端点下发,前端只按属性名覆盖翻译。所以新增+ 属性仍是「后端加一行 / 前端自动跟随」,属性集合随版本演进无需改这里。 -->+ <p class="desc">{{ t('knowledgeEditor.advanced.multimodal.imageAttrsSchemaDescription') }}</p>+ </div>+ <div class="image-attr-panel">+ <ul v-if="imageAttrDisplays.length" class="image-attr-list">+ <li v-for="attr in imageAttrDisplays" :key="attr.name" class="image-attr-row">+ <div class="image-attr-head">+ <span class="image-attr-label">{{ attr.label }}</span>+ <code class="image-attr-name">{{ attr.name }}</code>+ </div>+ <p v-if="attr.description" class="image-attr-desc">{{ attr.description }}</p>+ <ul class="image-attr-value-list">+ <li v-for="v in attr.values" :key="v.value" class="image-attr-value">+ <code>{{ v.value }}</code>+ <span class="image-attr-value-label">{{ v.label }}</span>+ </li>+ </ul>+ </li>+ </ul>+ <div class="image-attr-section">+ <div class="setting-info">+ <label>{{ t('knowledgeEditor.advanced.multimodal.imageAttrsOcrConditions') }}</label>+ <p class="desc">{{ t('knowledgeEditor.advanced.multimodal.imageAttrsOcrConditionsDesc') }}</p>+ </div>+ <ul class="image-attr-condition-list">+ <li v-for="(cond, i) in imageAttrConditionDisplays" :key="i" class="image-attr-condition">+ <span class="image-attr-condition-label">{{ cond.label }}</span>+ <code class="image-attr-condition-raw">{{ cond.raw }}</code>+ </li>+ </ul>+ </div>+ </div>+ </div>++ <!-- 观察失败兜底:真正与上方属性面板行同级。此前它嵌在+ setting-row-vertical 里,而垂直行的后代选择器把所有+ .setting-info / .setting-control 都撑成 100% 宽,水平+ 排布必然溢出,开关被顶到容器右缘之外。挪出来后与其它+ 开关行共用同一套排版,右缘与「图片属性观察」对齐 -->+ <template v-if="uiState.multimodalConfig.enabled && uiState.imageAttrsEnabled">+ <div class="setting-row">+ <div class="setting-info">+ <label>{{ t('knowledgeEditor.advanced.multimodal.imageAttrsOcrOnUnobserved') }}</label>+ <p class="desc">{{ t('knowledgeEditor.advanced.multimodal.imageAttrsOcrOnUnobservedDesc') }}</p>+ </div>+ <div class="setting-control">+ <t-switch v-model="uiState.imageActions.ocr.on_unobserved" size="medium" />+ </div>+ </div>+ <div class="image-pipeline-kb-note">+ {{ t('knowledgeEditor.advanced.multimodal.imagePipelineKbNote') }}+ </div>+ </template></div></div></div>@@ -581,7 +649,8 @@ import { useEditorResourcesStore } from '@/stores/editorResources'import { useUIStore } from '@/stores/ui'import { formatFileSize, getFileIcon } from '@/utils/files'import { getUploadFileKey } from '../utils/uploadSources'-import { listKnowledgeTags } from '@/api/knowledge-base'+import { listKnowledgeTags, mergeImageActions, fetchImageAttrSchema, FALLBACK_IMAGE_ATTR_SCHEMA, type ImageActionsConfig, type ImageAttrSchema } from '@/api/knowledge-base'+import { imageAttrDisplay, imageAttrConditionDisplay } from '@/utils/imageAttrDisplay'import KbUploadSourceDropdown from './KbUploadSourceDropdown.vue'import FolderPickerMenu, { type FolderOption } from './FolderPickerMenu.vue'import { folderOptionFromPath, sortFolderOptions } from '../folderTree'@@ -596,6 +665,20 @@ import type {const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp']const AUDIO_EXTENSIONS = ['mp3', 'wav', 'm4a', 'flac', 'ogg']+// The image-attribute registry, fetched from the backend (single source of+// truth). Falls back to the static registry until the endpoint answers.+const imageAttrSchema = ref<ImageAttrSchema | null>(null)+const displaySchema = computed<ImageAttrSchema>(+ () => imageAttrSchema.value ?? FALLBACK_IMAGE_ATTR_SCHEMA,+)+async function loadImageAttrSchema(kbId: string) {+ try {+ imageAttrSchema.value = await fetchImageAttrSchema(kbId)+ } catch {+ imageAttrSchema.value = null+ }+}+type ConfigSectionKey = 'tags' | 'parser' | 'chunking' | 'multimodal' | 'asr' | 'summary' | 'question' | 'graph'type IssueSectionKey = 'multimodal' | 'asr'@@ -621,6 +704,8 @@ interface UploadUIState {summaryEnabled: booleanchunkingConfig: ChunkingUIConfigmultimodalConfig: { enabled: boolean; vllmModelId: string; descriptionLanguage?: string; customInstructions?: string }+ imageAttrsEnabled: boolean+ imageActions: ImageActionsConfigasrConfig: { enabled: boolean; modelId: string; language: string }questionGenerationConfig: { enabled: boolean; questionCount: number; customInstructions?: string }nodeExtractConfig: {@@ -670,7 +755,21 @@ const emit = defineEmits<{cancel: []}>()-const { t } = useI18n()+const { t, te } = useI18n()++// The attribute panel and the OCR conditions are rendered from the registry in+// the operator's language: the registry supplies the wording, the i18n overlay+// translates it, so a new backend attribute needs no change here.+const imageAttrDisplays = computed(() =>+ displaySchema.value.attributes.map((attr) => imageAttrDisplay(attr, t, te)),+)+// The conditions this upload actually runs with: a list customised through the+// API is shown as is, otherwise mergeImageActions filled in the default.+const imageAttrConditionDisplays = computed(() =>+ uiState.value.imageActions.ocr.on.map((cond) =>+ imageAttrConditionDisplay(cond, displaySchema.value, t, te),+ ),+)const chatResources = useChatResourcesStore()const editorResources = useEditorResourcesStore()const uiStore = useUIStore()@@ -1097,6 +1196,8 @@ function createDefaultUIState(): UploadUIState {tableMetadataInstructions: '',},multimodalConfig: { enabled: false, vllmModelId: '', descriptionLanguage: '', customInstructions: '' },+ imageAttrsEnabled: false,+ imageActions: mergeImageActions(),asrConfig: { enabled: false, modelId: '', language: '' },questionGenerationConfig: { enabled: true, questionCount: 3, customInstructions: '' },nodeExtractConfig: {@@ -1139,6 +1240,9 @@ function initFromKbInfo(kb: any) {descriptionLanguage: kb.vlm_config?.description_language || '',customInstructions: kb.vlm_config?.custom_instructions || '',},+ // 默认跟随知识库的图片属性观察设置;用户可对本次任务单独覆盖。+ imageAttrsEnabled: !!kb.image_processing_config?.image_attrs_enabled,+ imageActions: mergeImageActions(kb.image_processing_config?.image_actions),asrConfig: {enabled: !!kb.asr_config?.enabled,modelId: kb.asr_config?.model_id || '',@@ -1163,6 +1267,8 @@ function initFromKbInfo(kb: any) {graphEnabled: kb.indexing_strategy?.graph_enabled ?? false,pdfForceScanned: false,}+ // 拉取后端属性注册表,驱动属性面板的动态渲染(已有 kbId)。+ if (kb.id) loadImageAttrSchema(kb.id)}function buildProcessOverrides(): KnowledgeProcessOverrides {@@ -1185,6 +1291,15 @@ function buildProcessOverrides(): KnowledgeProcessOverrides {table_metadata_instructions: chunking.tableMetadataInstructions,},enable_multimodel: state.multimodalConfig.enabled,+ image_attrs_enabled: state.imageAttrsEnabled,+ image_actions: {+ ocr: {+ // The KB's own conditions (mergeImageActions keeps a custom list), so+ // an upload never swaps an API-customised table for the default one.+ on: state.imageActions.ocr.on,+ on_unobserved: state.imageActions.ocr.on_unobserved,+ },+ },vlm_config: {enabled: state.multimodalConfig.enabled,model_id: state.multimodalConfig.vllmModelId,@@ -1241,6 +1356,8 @@ function applyOverridesToState(o?: KnowledgeProcessOverrides | null) {}if (o.parser_engine_rules) s.chunkingConfig.parserEngineRules = o.parser_engine_rulesif (o.enable_multimodel != null) s.multimodalConfig.enabled = o.enable_multimodel+ if (o.image_attrs_enabled != null) s.imageAttrsEnabled = o.image_attrs_enabled+ if (o.image_actions) s.imageActions = mergeImageActions(o.image_actions)if (o.vlm_config) {if (o.vlm_config.enabled != null) s.multimodalConfig.enabled = o.vlm_config.enabledif (o.vlm_config.model_id != null) s.multimodalConfig.vllmModelId = o.vlm_config.model_id@@ -1473,6 +1590,109 @@ const handleConfirm = () => {</script><style lang="less" scoped>+// 图片属性面板(可观察属性 / OCR 触发条件 / 观察失败兜底)+// 文案全部来自后端属性注册表(人话名 + 每个取值的含义),前端只做翻译覆盖,+// 因此新增属性无需改这里。与知识库编辑器同款:铺在所在设置区里、不套独立底色块。+.image-attr-panel {+ margin-top: 4px;+}+.image-attr-list,+.image-attr-value-list,+.image-attr-condition-list {+ margin: 0;+ padding: 0;+ list-style: none;+}+.image-attr-row + .image-attr-row {+ margin-top: 12px;+ padding-top: 12px;+ border-top: 1px solid var(--td-component-border);+}+.image-attr-head {+ display: flex;+ align-items: baseline;+ gap: 6px;+ flex-wrap: wrap;+}+.image-attr-label {+ font-weight: 600;+ color: var(--td-text-color-primary);+}+// 原始属性名缩小并加括号,便于与处理轨迹里的字段对上,又不干扰阅读+.image-attr-name {+ font-family: ui-monospace, Menlo, Consolas, monospace;+ font-size: var(--app-text-xs);+ color: var(--td-text-color-placeholder);++ &::before {+ content: '(';+ }++ &::after {+ content: ')';+ }+}+.image-attr-desc {+ margin: 2px 0 0;+ font-size: var(--app-text-sm);+ line-height: 20px;+ color: var(--td-text-color-secondary);+}+// 每个取值一行:值(等宽,左列对齐)+ 冒号 + 人话解释+.image-attr-value-list {+ display: grid;+ grid-template-columns: max-content 1fr;+ column-gap: 2px;+ row-gap: 2px;+ margin-top: 6px;+ font-size: var(--app-text-sm);+}+// display: contents 让值与解释分别落进上面两列,取值因此左对齐成列+.image-attr-value {+ display: contents;++ code {+ font-family: ui-monospace, Menlo, Consolas, monospace;+ color: var(--td-text-color-primary);++ // 冒号紧跟取值,不留空隙:none: 没有文字+ &::after {+ content: ':';+ }+ }+}+.image-attr-value-label {+ color: var(--td-text-color-secondary);+}+.image-attr-section {+ margin-top: 14px;+}+// 一条 OCR 条件两行:人话在上,原始 property = value 在下+.image-attr-condition-list {+ margin-top: 6px;+ font-size: var(--app-text-sm);+}+.image-attr-condition + .image-attr-condition {+ margin-top: 6px;+}+.image-attr-condition-label {+ display: block;+ color: var(--td-text-color-primary);+}+.image-attr-condition-raw {+ display: block;+ margin-top: 1px;+ font-family: ui-monospace, Menlo, Consolas, monospace;+ font-size: var(--app-text-xs);+ color: var(--td-text-color-placeholder);+}++.image-pipeline-kb-note {+ margin-top: 4px;+ font-size: var(--app-text-sm);+ color: var(--td-text-color-placeholder);+}+.upload-confirm-overlay {position: fixed;inset: 0;diff --git a/frontend/src/views/knowledge/gallery/ImageGallery.vue b/frontend/src/views/knowledge/gallery/ImageGallery.vuenew file mode 100644index 000000000..ba1c34e91--- /dev/null+++ b/frontend/src/views/knowledge/gallery/ImageGallery.vue@@ -0,0 +1,1535 @@+<script setup lang="ts">+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'+import { useI18n } from 'vue-i18n'+import {+ listGalleryImages,+ fetchGalleryConfig,+ type GalleryConfig,+ type GalleryResolvedAttr,+ type ImageAsset,+ type ImageListParams,+} from '@/api/image-gallery'+import { updateMyPreferences } from '@/api/auth'+import { galleryImageRequest } from './galleryImageSrc'++const props = defineProps<{+ knowledgeBaseId: string+}>()++const { t, te } = useI18n()++// ---------------------------------------------------------------------------+// Data state+// ---------------------------------------------------------------------------+const loading = ref(false)+const error = ref('')+const items = ref<ImageAsset[]>([])+const total = ref(0)+const page = ref(1)+const pageSize = ref(24)++const keyword = ref('')+const sortBy = ref('')+const sortOrder = ref<'asc' | 'desc'>('desc')++// The two scope switches in the toolbar row. Each has the same shape: the+// inclusive position drops the constraint entirely, the custom position+// opens the panel that edits it. "筛选:全显示" therefore really is a+// switch — when it reads "全显示", no attribute constraint is sent at all.+const searchScope = ref<'all' | 'custom'>('all')+const filterScope = ref<'all' | 'custom'>('all')++// Which settings panel is on screen. A panel opens as a popover under the+// arrow that summoned it, and a pin moves it into the right-hand rail,+// where the two panels take turns as tabs instead of both eating space.+const openPanel = ref<'search' | 'filter' | ''>('')+const pinnedPanel = ref<'search' | 'filter' | ''>('')+const panelTab = ref<'search' | 'filter'>('search')+// Where the floating panel hangs: captured from the arrow that opened it,+// so it sits directly beneath that control instead of at a guessed spot.+const panelPos = ref<{ top: number; left: number } | null>(null)+const rootEl = ref<HTMLElement | null>(null)++// Attribute selections: namespaced attr id -> selected allowed values (OR+// within the attribute, AND across attributes). Free-text attributes have no+// value list to pick from, so they carry their own literal selection.+const attrSelections = ref<Record<string, string[]>>({})++// Per-value verdicts, namespaced attr id -> value -> "off" | "on". An absent+// key is the middle position: an image carrying that value stays exactly as+// visible as it was, which is what makes the default state show everything.+const attrVerdicts = ref<Record<string, Record<string, string>>>({})++// ---------------------------------------------------------------------------+// Gallery contract (self-describing, fetched once per mount)+//+// Everything the UI offers — filter panel sections, searchable fields, sort+// options — comes from the contract. No gallery rule is hardcoded here, so+// new backend attributes and runtime policy edits light up on reload.+// ---------------------------------------------------------------------------+const configLoaded = ref(false)+const config = ref<GalleryConfig>({+ attribute_sources: [],+ attributes: [],+ mode: 'all',+ status: {},+})+const searchMode = ref<'all' | 'custom'>('all')+// Per-attribute search toggle, keyed by namespaced attr id ("on"/"off").+// Unrecorded fields are off in custom mode; source declarations carry no+// on/off — activation is always the user's own record.+const searchStatus = ref<Record<string, string>>({})++const filterAttrs = computed(() => config.value.attributes.filter((a) => a.usage.in_filter))+const searchAttrs = computed(() => config.value.attributes.filter((a) => a.usage.in_searchfield))+const sortAttrs = computed(() => config.value.attributes.filter((a) => a.usage.in_sortfield))++// The fields actually searched right now: every eligible field in "all"+// mode; the user's on-record in custom mode.+const activeSearchIds = computed(() => {+ if (searchMode.value === 'all') return searchAttrs.value.map((a) => a.id)+ return searchAttrs.value.filter((a) => searchStatus.value[a.id] === 'on').map((a) => a.id)+})++// ---------------------------------------------------------------------------+// Viewer state+// ---------------------------------------------------------------------------+const viewerOpen = ref(false)+const viewerIndex = ref(0)+const imageFailed = ref(false)++const current = computed<ImageAsset | null>(() =>+ viewerOpen.value && items.value.length ? items.value[viewerIndex.value] ?? null : null,+)++// ---------------------------------------------------------------------------+// Image URL resolution+//+// Backend returns storage handles (local://, minio://, resource://, ...) which+// the browser cannot render directly. They must be fetched through the KB file+// proxy (galleryImageRequest) and turned into object URLs first.+// Normal http(s) URLs pass through untouched.+// ---------------------------------------------------------------------------+const thumbUrls = ref<Record<string, string>>({})+const thumbBroken = ref<Record<string, boolean>>({})+const viewerUrl = ref('')+// Object URLs keyed by the raw storage URL they were fetched for, so a+// thumbnail and the viewer share one blob and a reload reuses what is already+// on screen instead of fetching (and leaking) a fresh copy.+const blobByRawUrl = new Map<string, string>()++/** Revoke every cached object URL whose raw URL is not in keep. */+function releaseBlobs(keep: Set<string> = new Set()): void {+ for (const [raw, objectUrl] of blobByRawUrl) {+ if (keep.has(raw)) continue+ URL.revokeObjectURL(objectUrl)+ blobByRawUrl.delete(raw)+ }+}++async function resolveImageSrc(rawUrl: string): Promise<string> {+ const req = galleryImageRequest(rawUrl, props.knowledgeBaseId)+ if (!req) return rawUrl+ const cached = blobByRawUrl.get(rawUrl)+ if (cached) return cached+ try {+ const resp = await fetch(req.url, { headers: req.headers })+ if (!resp.ok) return rawUrl+ const blob = await resp.blob()+ // A concurrent resolve may have cached this URL meanwhile; keep one blob.+ const raced = blobByRawUrl.get(rawUrl)+ if (raced) return raced+ const objectUrl = URL.createObjectURL(blob)+ blobByRawUrl.set(rawUrl, objectUrl)+ return objectUrl+ } catch {+ return rawUrl+ }+}++function thumbUrl(img: ImageAsset): string {+ return thumbUrls.value[img.id] || img.url+}++async function resolveThumbnails(token: number) {+ const imgs = items.value+ const urls = await Promise.all(imgs.map((img) => resolveImageSrc(img.url)))+ // A newer listing owns the grid now; its own pass maps the thumbnails.+ if (token !== listToken) return+ const next: Record<string, string> = {}+ imgs.forEach((img, i) => {+ next[img.id] = urls[i]+ })+ // Revoke blob URLs that are no longer on screen to avoid leaks.+ releaseBlobs(new Set(imgs.map((img) => img.url)))+ thumbUrls.value = next+ thumbBroken.value = {}+}++function onThumbError(id: string) {+ thumbBroken.value = { ...thumbBroken.value, [id]: true }+}++let viewerToken = 0++watch(+ () => current.value,+ async (img) => {+ if (!img) {+ viewerUrl.value = ''+ return+ }+ // Opening the viewer renders the <img> at once, while the blob the+ // browser can actually display only exists after the proxy fetch below.+ // In the meantime the element still shows the previous (or empty)+ // source, whose error event flipped the failure flag — and the real+ // image then arrived to a viewer already showing its failure state.+ // The token keeps a stale fetch from winning a fast navigation race,+ // and the flag is reset here, after the real source is in hand.+ const token = ++viewerToken+ const url = await resolveImageSrc(img.url)+ if (token !== viewerToken) return+ imageFailed.value = false+ viewerUrl.value = url+ },+)++// ---------------------------------------------------------------------------+// Label helpers+//+// The contract carries the backend's default-language wording. Locale files+// overlay translations keyed by the (sanitized) attribute id; anything not+// translated falls back to the contract text.+//+// Every attribute and value carries two pieces of text on purpose: a short+// `label` for space-constrained controls (a filter checkbox, a sort option)+// and a `description` sentence for wherever there is room. The helpers below+// always return the short one and expose the long one separately, so a compact+// panel never has to stretch to a full sentence.+//+// A translation always wins: the contract's wording is only the fallback for+// attributes no locale knows yet. Asking the locale first matters, because a+// source carries its own default-language text and would otherwise shadow the+// translation for every locale but its own.+// ---------------------------------------------------------------------------+/** Where the gallery's own attribute wording lives in the locale files. */+const ATTR_NAMESPACE = 'knowledgeEditor.wikiBrowser.gallery.attr'++const sanitizeKey = (id: string) => id.replace(/[:.]/g, '_')++/** The pipeline's own wording for an attribute, keyed by its source-local name. */+function pipelineKey(attr: GalleryResolvedAttr, suffix = ''): string {+ return `imageAttr.${(attr.name || '').replace(/[.\s]/g, '_')}${suffix}`+}++function attrLabel(attr: GalleryResolvedAttr): string {+ const key = `${ATTR_NAMESPACE}.${sanitizeKey(attr.id)}`+ if (te(key)) return t(key)+ // Overlay the attribute pipeline's own translations when present.+ const legacy = pipelineKey(attr, '.label')+ if (te(legacy)) return t(legacy)+ return attr.label || attr.id+}++/** The sentence explaining an attribute, in words where the source gave one. */+function attrDescription(attr: GalleryResolvedAttr): string {+ const key = `${ATTR_NAMESPACE}.${sanitizeKey(attr.id)}_description`+ if (te(key)) return t(key)+ // Attributes contributed by an attribute pipeline ship no gallery-specific+ // text, so fall through to the pipeline's own translations.+ const legacy = pipelineKey(attr, '.description')+ if (te(legacy)) return t(legacy)+ return attr.description || ''+}++/**+ * The short display name of one allowed value. The locale wins over the+ * wording the source shipped; only a value no locale knows about falls back to+ * the source text, and one that spelled nothing out reads as the raw value.+ */+function attrValueLabel(attr: GalleryResolvedAttr, value: string): string {+ const key = `${ATTR_NAMESPACE}.${sanitizeKey(attr.id)}_value_${value}`+ if (te(key)) return t(key)+ const legacy = pipelineKey(attr, `.values.${value}.label`)+ if (te(legacy)) return t(legacy)+ return attr.values?.find((v) => v.value === value)?.label || value+}++/** The sentence explaining one allowed value; empty when the source has none. */+function attrValueDescription(attr: GalleryResolvedAttr, value: string): string {+ const key = `${ATTR_NAMESPACE}.${sanitizeKey(attr.id)}_value_${value}_description`+ if (te(key)) return t(key)+ const legacy = pipelineKey(attr, `.values.${value}.description`)+ if (te(legacy)) return t(legacy)+ return attr.values?.find((v) => v.value === value)?.description || ''+}++/** One observed attribute value of an image, in words where possible. */+function displayObservedValue(attr: GalleryResolvedAttr | undefined, raw: unknown): string {+ const normalized = typeof raw === 'boolean' ? String(raw) : String(raw ?? '')+ if (!attr) return normalized+ return attrValueLabel(attr, normalized)+}++function findAttrByRawName(name: string): GalleryResolvedAttr | undefined {+ return config.value.attributes.find((a) => a.name === name)+}++const currentAttrs = computed(() => {+ if (!current.value) return [] as Array<{ key: string; label: string; value: string }>+ return Object.entries(current.value.attrs).map(([name, raw]) => {+ const attr = findAttrByRawName(name)+ return {+ key: name,+ label: attr ? attrLabel(attr) : name,+ value: displayObservedValue(attr, raw),+ }+ })+})++// ---------------------------------------------------------------------------+// Filter verdicts+//+// One attribute value moves through three positions by click: neutral (leave+// those images alone), "off" (hide them), "on" (show them whatever else says).+// The middle position is the one a user starts at and returns to, so a value+// the user never touched is absent from the map rather than stored as a word,+// and never reaches the server.+// ---------------------------------------------------------------------------+// The filter panel's own switch: off means the verdicts are not imposed at+// all, which is what the toolbar's 全显示 position shows.+const filterScopeOn = computed({+ get: () => filterScope.value === 'custom',+ set: (on: boolean) => onFilterScopeChange(on ? 'custom' : 'all'),+})++const VERDICTS = ['default', 'off', 'on'] as const+type Verdict = (typeof VERDICTS)[number]++/** The verdicts that carry meaning, i.e. the ones worth putting on the wire. */+const activeRules = computed(() => {+ const out: Record<string, Record<string, string>> = {}+ for (const [id, perValue] of Object.entries(attrVerdicts.value)) {+ const clean: Record<string, string> = {}+ for (const [value, verdict] of Object.entries(perValue)) {+ if (verdict === 'off' || verdict === 'on') clean[value] = verdict+ }+ if (Object.keys(clean).length > 0) out[id] = clean+ }+ return out+})++function verdictOf(attrId: string, value: string): Verdict {+ return (attrVerdicts.value[attrId]?.[value] as Verdict) || 'default'+}++function setVerdict(attrId: string, value: string, verdict: Verdict): void {+ const perValue = { ...(attrVerdicts.value[attrId] || {}) }+ if (verdict === 'default') delete perValue[value]+ else perValue[value] = verdict+ attrVerdicts.value = { ...attrVerdicts.value, [attrId]: perValue }+ // A verdict the user just expressed must take effect immediately: staying+ // in "全显示" while the panel shows an off/on would silently ignore it.+ // Clearing the last meaningful verdict returns to "全显示", since custom+ // mode with no rules constrains nothing anyway.+ const hasRules = Object.values(attrVerdicts.value).some((perValueInner) =>+ Object.values(perValueInner).some((v) => v === 'off' || v === 'on'),+ )+ filterScope.value = hasRules ? 'custom' : 'all'+ resetPageAndReload()+}++function verdictLabel(v: Verdict): string {+ if (v === 'off') return t('knowledgeEditor.wikiBrowser.gallery.verdictOff')+ if (v === 'on') return t('knowledgeEditor.wikiBrowser.gallery.verdictOn')+ return t('knowledgeEditor.wikiBrowser.gallery.verdictDefault')+}++// ---------------------------------------------------------------------------+// Settings panels+//+// Both panels answer the same question — what may the gallery show — and both+// open the same way: an arrow beside the toolbar control summons them as a+// popover, and the pin on the panel's header moves it into the right-hand+// rail. Pinning one keeps the other out of the rail, so the two never split+// the image area between them.+// ---------------------------------------------------------------------------+function openSettingsPanel(panel: 'search' | 'filter', ev?: MouseEvent): void {+ // A pinned rail already holds both panels as tabs; an arrow click merely+ // turns to the requested one instead of spawning a second surface.+ if (pinnedPanel.value) {+ panelTab.value = panel+ openPanel.value = ''+ return+ }+ // The arrow is a toggle: a second press on the same arrow retracts the+ // panel, which is also why its icon points up while the panel is out.+ if (openPanel.value === panel) {+ openPanel.value = ''+ return+ }+ openPanel.value = panel+ panelTab.value = panel+ if (ev) updatePanelPosition(ev)+}++/** Anchor the floating panel just below the arrow that summoned it. */+function updatePanelPosition(ev: MouseEvent): void {+ const root = rootEl.value?.getBoundingClientRect()+ const btn = (ev.currentTarget as HTMLElement | null)?.getBoundingClientRect()+ if (!root || !btn) return+ const width = 320+ const left = Math.max(8, Math.min(btn.left - root.left, root.width - width - 12))+ panelPos.value = { top: btn.bottom - root.top + 6, left }+}++const floatingStyle = computed(() =>+ panelPos.value+ ? { top: `${panelPos.value.top}px`, left: `${panelPos.value.left}px`, right: 'auto' }+ : {},+)++// Any click landing outside the floating panel and outside the arrows closes+// it: moving on to another toolbar control means leaving the panel. Clicks+// inside the panel itself, and on the toggling arrows, are left alone.+function onDocClick(e: MouseEvent): void {+ if (!openPanel.value || pinnedPanel.value) return+ const target = e.target as HTMLElement | null+ if (!target) return+ if (target.closest('.ig-panel-slot')) return+ if (target.closest('.ig-scope-arrow')) return+ openPanel.value = ''+}++function togglePin(panel: 'search' | 'filter'): void {+ if (pinnedPanel.value === panel) {+ pinnedPanel.value = ''+ return+ }+ pinnedPanel.value = panel+ panelTab.value = panel+ openPanel.value = ''+}++function onFilterScopeChange(value: string | number | boolean): void {+ filterScope.value = value === 'custom' ? 'custom' : 'all'+ resetPageAndReload()+}++// ---------------------------------------------------------------------------+// Loading+// ---------------------------------------------------------------------------+function buildParams(): ImageListParams {+ const attrFilters: Record<string, string[]> = {}+ for (const [id, values] of Object.entries(attrSelections.value)) {+ if (values && values.length) attrFilters[id] = values+ }+ // The filter switch decides whether verdicts are imposed at all: reading+ // "全显示" means the panel's verdicts are not applied, whatever is set in it.+ const rules = filterScope.value === 'custom' ? activeRules.value : {}+ const params: ImageListParams = {+ keyword: keyword.value.trim() || undefined,+ searchIn: activeSearchIds.value,+ sortBy: sortBy.value || undefined,+ sortOrder: sortOrder.value,+ attrFilters: Object.keys(attrFilters).length ? attrFilters : undefined,+ attrRules: Object.keys(rules).length ? rules : undefined,+ page: page.value,+ pageSize: pageSize.value,+ }+ return params+}++// Bumped by every listing, so a slower earlier response (a debounced search+// overtaken by a page change) cannot overwrite the grid of a newer query.+let listToken = 0++async function reload() {+ if (!props.knowledgeBaseId) return+ const token = ++listToken+ // Searching with every field switched off would silently fall back to the+ // server default — not what a custom-mode user asked for. Short-circuit.+ if (keyword.value.trim() && activeSearchIds.value.length === 0) {+ items.value = []+ total.value = 0+ loading.value = false+ return+ }+ loading.value = true+ error.value = ''+ try {+ const res = await listGalleryImages(props.knowledgeBaseId, buildParams())+ if (token !== listToken) return+ items.value = res.items+ total.value = res.total+ if (viewerOpen.value && viewerIndex.value >= res.items.length) closeViewer()+ void resolveThumbnails(token)+ } catch (e) {+ if (token !== listToken) return+ error.value = e instanceof Error ? e.message : String(e)+ items.value = []+ total.value = 0+ thumbUrls.value = {}+ } finally {+ if (token === listToken) loading.value = false+ }+}++function resetPageAndReload() {+ page.value = 1+ reload()+}++// ---------------------------------------------------------------------------+// Personal state persistence (mode + per-field search toggles)+// ---------------------------------------------------------------------------+let prefsTimer: ReturnType<typeof setTimeout> | undefined+function persistSearchPrefs() {+ if (!configLoaded.value) return+ if (prefsTimer) clearTimeout(prefsTimer)+ prefsTimer = setTimeout(() => {+ void updateMyPreferences({+ gallery: { mode: searchMode.value, status: { ...searchStatus.value } },+ })+ }, 500)+}++// The search panel's master switch: on searches every eligible field, off+// restricts the search to the fields the user switched on below it.+const searchAllOn = computed({+ get: () => searchMode.value === 'all',+ set: (on: boolean) => onSearchModeChange(on ? 'all' : 'custom'),+})++function onSearchModeChange(value: string | number | boolean) {+ searchMode.value = value === 'custom' ? 'custom' : 'all'+ persistSearchPrefs()+ resetPageAndReload()+}++// Reconcile the whole on/off map from one checkbox-group change, then+// persist and re-query. In "all" mode every field is searched and the+// checkboxes are only decorative (dimmed): touching one means the user+// wants a custom selection, so the master switch drops to custom with+// every field still on except the one just unticked.+function onSearchFieldsChange(vals: Array<string | number | boolean>) {+ const next: Record<string, string> = { ...searchStatus.value }+ for (const attr of searchAttrs.value) {+ next[attr.id] = vals.includes(attr.id) ? 'on' : 'off'+ }+ searchStatus.value = next+ if (searchMode.value === 'all') searchMode.value = 'custom'+ persistSearchPrefs()+ resetPageAndReload()+}++// ---------------------------------------------------------------------------+// Filter interactions+// ---------------------------------------------------------------------------+function onSearch() {+ resetPageAndReload()+}++let searchTimer: ReturnType<typeof setTimeout> | undefined+function onSearchInput() {+ if (searchTimer) clearTimeout(searchTimer)+ searchTimer = setTimeout(() => resetPageAndReload(), 350)+}++function onAttrGroupChange(attrId: string, values: Array<string | number | boolean>) {+ attrSelections.value = {+ ...attrSelections.value,+ [attrId]: values.map((v) => String(v)),+ }+ resetPageAndReload()+}++function onKeywordsInput(attrId: string, raw: string) {+ const values = raw+ .split(/[,,;;\n]/)+ .map((s) => s.trim())+ .filter(Boolean)+ attrSelections.value = { ...attrSelections.value, [attrId]: values }+ resetPageAndReload()+}++function keywordsInputValue(attrId: string): string {+ return (attrSelections.value[attrId] || []).join(', ')+}++// Apply one verdict to every value of every value-typed filter attribute.+// The "-" position clears all verdicts, which also drops the scope back to+// "全显示": custom mode with no rules constrains nothing.+function setAllVerdicts(verdict: Verdict): void {+ const next: Record<string, Record<string, string>> = {}+ for (const attr of filterAttrs.value) {+ if (attr.type === 'keywords') continue+ const perValue: Record<string, string> = { ...(attrVerdicts.value[attr.id] || {}) }+ for (const v of attr.values || []) {+ if (verdict === 'default') delete perValue[v.value]+ else perValue[v.value] = verdict+ }+ if (Object.keys(perValue).length > 0) next[attr.id] = perValue+ }+ attrVerdicts.value = next+ const hasRules = Object.values(next).some((perValue) =>+ Object.values(perValue).some((v) => v === 'off' || v === 'on'),+ )+ filterScope.value = hasRules ? 'custom' : 'all'+ resetPageAndReload()+}++function hasActiveFilters(): boolean {+ return !!keyword.value.trim() || Object.values(attrSelections.value).some((v) => v.length)+}++function onPageChange(next: number) {+ page.value = next+ reload()+}++// ---------------------------------------------------------------------------+// Viewer+// ---------------------------------------------------------------------------+function openViewer(index: number) {+ viewerIndex.value = index+ imageFailed.value = false+ viewerOpen.value = true+}++function closeViewer() {+ viewerOpen.value = false+}++function prevImage() {+ if (!items.value.length) return+ viewerIndex.value = (viewerIndex.value - 1 + items.value.length) % items.value.length+ imageFailed.value = false+}++function nextImage() {+ if (!items.value.length) return+ viewerIndex.value = (viewerIndex.value + 1) % items.value.length+ imageFailed.value = false+}++function onViewerKey(e: KeyboardEvent) {+ if (!viewerOpen.value) return+ if (e.key === 'Escape') closeViewer()+ else if (e.key === 'ArrowLeft') prevImage()+ else if (e.key === 'ArrowRight') nextImage()+}++function sourceLabel(img: ImageAsset): string {+ return img.source_name || img.knowledge_id+}++// ---------------------------------------------------------------------------+// Lifecycle+// ---------------------------------------------------------------------------+onMounted(() => {+ document.addEventListener('click', onDocClick)+})++onBeforeUnmount(() => {+ document.removeEventListener('click', onDocClick)+ if (searchTimer) clearTimeout(searchTimer)+ // Orphan any in-flight listing so it cannot map new blobs after unmount.+ listToken+++ releaseBlobs()+})++// Newest first unless the contract no longer offers it; picking by id keeps+// the default independent of source registration order.+const DEFAULT_SORT_ID = 'builtin:created_at'++let initToken = 0++// Loads the contract and the first page for the current knowledge base. It+// also runs on a knowledge base switch: the component instance is reused, so+// everything scoped to the previous knowledge base is dropped first.+async function initGallery() {+ const token = ++initToken+ closeViewer()+ items.value = []+ total.value = 0+ page.value = 1+ keyword.value = ''+ sortBy.value = ''+ attrSelections.value = {}+ attrVerdicts.value = {}+ filterScope.value = 'all'+ thumbUrls.value = {}+ thumbBroken.value = {}+ releaseBlobs()+ configLoaded.value = false+ config.value = { attribute_sources: [], attributes: [], mode: 'all', status: {} }+ try {+ const cfg = await fetchGalleryConfig(props.knowledgeBaseId)+ if (token !== initToken) return+ config.value = cfg+ searchMode.value = cfg.mode+ searchStatus.value = { ...cfg.status }+ configLoaded.value = true+ } catch {+ if (token !== initToken) return+ // Degraded mode: no contract, no attribute UI — builtin listing and+ // default search still work.+ }+ if (!sortBy.value && sortAttrs.value.length) {+ sortBy.value = sortAttrs.value.find((a) => a.id === DEFAULT_SORT_ID)?.id ?? sortAttrs.value[0].id+ }+ await reload()+}++onMounted(initGallery)++watch(+ () => props.knowledgeBaseId,+ (next, prev) => {+ if (next && next !== prev) void initGallery()+ },+)+</script>++<template>+ <div ref="rootEl" class="image-gallery" @keydown="onViewerKey">+ <div class="ig-layout" :class="{ 'has-rail': !!pinnedPanel }">+ <!--+ One settings panel, two placements: pinning it moves it out of the+ grid and into the right-hand rail, where the two panels take turns as+ tabs. Only one can hold the rail, so the image area never has to share+ its width with both of them.+ -->+ <aside+ v-if="openPanel || pinnedPanel"+ class="ig-panel-slot"+ :class="{ 'is-floating': openPanel && !pinnedPanel }"+ :style="openPanel && !pinnedPanel ? floatingStyle : undefined"+ >+ <div class="ig-panel-head">+ <t-tabs v-model="panelTab" class="ig-panel-tabs">+ <!-- Same order as the toolbar: search on the left, filter on the right. -->+ <t-tab-panel value="search" :label="t('knowledgeEditor.wikiBrowser.gallery.panelSearch')" />+ <t-tab-panel value="filter" :label="t('knowledgeEditor.wikiBrowser.gallery.panelFilter')" />+ </t-tabs>+ <button+ class="ig-pin"+ :class="{ 'is-pinned': !!pinnedPanel }"+ :title="pinnedPanel === panelTab ? t('knowledgeEditor.wikiBrowser.gallery.unpin') : t('knowledgeEditor.wikiBrowser.gallery.pin')"+ @click="togglePin(panelTab)"+ >+ <t-icon :name="pinnedPanel === panelTab ? 'pin-filled' : 'pin'" />+ </button>+ </div>++ <div class="ig-panel-body">+ <template v-if="panelTab === 'filter'">+ <div class="ig-row">+ <span class="ig-row-label">{{ t('knowledgeEditor.wikiBrowser.gallery.enableFilter') }}</span>+ <t-switch v-model="filterScopeOn" />+ </div>++ <div v-if="filterAttrs.length" class="ig-attr-blocks">+ <div v-for="attr in filterAttrs" :key="attr.id" class="ig-attr-block">+ <div class="ig-attr-name" :title="attrDescription(attr)">{{ attrLabel(attr) }}</div>++ <!--+ An attribute that declares values gets one row per value,+ each with three positions: leave the images carrying it+ alone, hide them, or force them back in.+ -->+ <div v-if="attr.type !== 'keywords'" class="ig-verdict-rows" :class="{ 'is-idle': !filterScopeOn }">+ <div v-for="v in attr.values || []" :key="v.value" class="ig-verdict-row">+ <t-tooltip :content="attrValueDescription(attr, v.value)">+ <span class="ig-verdict-value">{{ attrValueLabel(attr, v.value) }}</span>+ </t-tooltip>+ <div class="ig-verdict-group">+ <button+ v-for="verdict in VERDICTS"+ :key="verdict"+ type="button"+ class="ig-verdict"+ :class="['is-' + verdict, { 'is-active': verdictOf(attr.id, v.value) === verdict }]"+ @click="setVerdict(attr.id, v.value, verdict)"+ >+ {{ verdictLabel(verdict) }}+ </button>+ </div>+ </div>+ </div>+ <!--+ A free-text attribute has no value list to position, so it+ keeps the plain keyword box.+ -->+ <t-input+ v-else+ :value="keywordsInputValue(attr.id)"+ clearable+ class="ig-keywords"+ :placeholder="t('knowledgeEditor.wikiBrowser.gallery.keywordsPlaceholder')"+ @change="(v: string) => onKeywordsInput(attr.id, v)"+ @enter="(v: string) => onKeywordsInput(attr.id, v)"+ />+ </div>+ </div>+ <div v-else class="ig-no-attrs">{{ t('knowledgeEditor.wikiBrowser.gallery.noAttrs') }}</div>++ <!--+ One row to speak for every attribute at once: the same three+ positions as a per-value row, applied to all of them in one+ click.+ -->+ <div class="ig-row ig-apply-all">+ <span class="ig-row-label">{{ t('knowledgeEditor.wikiBrowser.gallery.applyAll') }}</span>+ <div class="ig-verdict-group">+ <button+ v-for="verdict in VERDICTS"+ :key="verdict"+ type="button"+ class="ig-verdict"+ :class="['is-' + verdict]"+ @click="setAllVerdicts(verdict)"+ >+ {{ verdictLabel(verdict) }}+ </button>+ </div>+ </div>+ </template>++ <template v-else>+ <div class="ig-row">+ <span class="ig-row-label">{{ t('knowledgeEditor.wikiBrowser.gallery.searchAll') }}</span>+ <t-switch v-model="searchAllOn" />+ </div>++ <div v-if="searchAttrs.length">+ <!--+ The checkboxes stay visible next to the master switch like the+ filter panel's verdicts do. In "all" mode they are dimmed —+ every field is searched, so the ticks carry no weight — yet+ still clickable: touching one drops the mode to custom. No+ caption above them: showing and hiding it would shift them+ when the switch is flipped.+ -->+ <t-checkbox-group+ :value="activeSearchIds"+ class="ig-search-fields"+ :class="{ 'is-idle': searchMode === 'all' }"+ @change="(vals: Array<string | number | boolean>) => onSearchFieldsChange(vals)"+ >+ <t-checkbox v-for="attr in searchAttrs" :key="attr.id" :value="attr.id" :label="attrLabel(attr)" />+ </t-checkbox-group>+ </div>+ </template>+ </div>+ </aside>++ <!-- Main content -->+ <section class="ig-main">+ <!--+ Everything that controls the list sits on one horizontal bar, so+ the image area below keeps all the vertical space it can get. The+ two scope switches read as 全显示 / 自定义: the inclusive position+ drops the constraint, and only the custom one has an arrow that+ opens the panel editing it.+ -->+ <div class="ig-toolbar">+ <t-input+ v-model="keyword"+ :placeholder="t('knowledgeEditor.wikiBrowser.gallery.searchPlaceholder')"+ clearable+ class="ig-search"+ @enter="onSearch"+ @input="onSearchInput"+ @clear="onSearch"+ >+ <template #prefix-icon><t-icon name="search" /></template>+ </t-input>++ <div class="ig-scope">+ <span class="ig-scope-name">{{ t('knowledgeEditor.wikiBrowser.gallery.searchScope') }}</span>+ <!--+ The scope word is a status, not a control: it names the mode+ the search is in, and only the arrow beside it opens the panel+ that changes it.+ -->+ <span class="ig-scope-value">+ {{ searchScope === 'all' ? t('knowledgeEditor.wikiBrowser.gallery.scopeAll') : t('knowledgeEditor.wikiBrowser.gallery.scopeCustom') }}+ </span>+ <button+ class="ig-scope-arrow"+ :title="t('knowledgeEditor.wikiBrowser.gallery.editSearch')"+ @click="openSettingsPanel('search', $event)"+ >+ <t-icon :name="openPanel === 'search' && !pinnedPanel ? 'chevron-up' : 'chevron-down'" />+ </button>+ </div>++ <div class="ig-scope">+ <span class="ig-scope-name">{{ t('knowledgeEditor.wikiBrowser.gallery.filterScope') }}</span>+ <span class="ig-scope-value">+ {{ filterScope === 'all' ? t('knowledgeEditor.wikiBrowser.gallery.filterOff') : t('knowledgeEditor.wikiBrowser.gallery.filterOn') }}+ </span>+ <button+ class="ig-scope-arrow"+ :title="t('knowledgeEditor.wikiBrowser.gallery.editFilter')"+ @click="openSettingsPanel('filter', $event)"+ >+ <t-icon :name="openPanel === 'filter' && !pinnedPanel ? 'chevron-up' : 'chevron-down'" />+ </button>+ </div>++ <span class="ig-scope-sep" />++ <t-select v-if="sortAttrs.length" v-model="sortBy" class="ig-sort" @change="resetPageAndReload">+ <t-option v-for="attr in sortAttrs" :key="attr.id" :value="attr.id" :label="attrLabel(attr)" />+ </t-select>++ <t-button theme="default" variant="outline" class="ig-order" @click="sortOrder = sortOrder === 'asc' ? 'desc' : 'asc'; resetPageAndReload()">+ <t-icon :name="sortOrder === 'asc' ? 'arrow-up' : 'arrow-down'" />+ {{ sortOrder === 'asc' ? t('knowledgeEditor.wikiBrowser.gallery.orderAsc') : t('knowledgeEditor.wikiBrowser.gallery.orderDesc') }}+ </t-button>++ <span class="ig-count">{{ t('knowledgeEditor.wikiBrowser.gallery.count', { count: total }) }}</span>+ </div>++ <t-loading :loading="loading" class="ig-loading-area">+ <div v-if="error" class="ig-error">{{ error }}</div>++ <div v-else-if="!items.length" class="ig-empty">+ {{ hasActiveFilters()+ ? t('knowledgeEditor.wikiBrowser.gallery.emptyFiltered')+ : t('knowledgeEditor.wikiBrowser.gallery.empty') }}+ </div>++ <div v-else class="ig-grid">+ <button+ v-for="(img, idx) in items"+ :key="img.id"+ type="button"+ class="ig-card"+ @click="openViewer(idx)"+ >+ <div class="ig-card-thumb">+ <img+ v-if="!thumbBroken[img.id]"+ :src="thumbUrl(img)"+ :alt="img.caption"+ loading="lazy"+ @error="onThumbError(img.id)"+ />+ <div v-else class="ig-thumb-error">+ {{ t('knowledgeEditor.wikiBrowser.gallery.imageLoadError') }}+ </div>+ </div>+ <div class="ig-card-meta">+ <div class="ig-card-caption">{{ img.caption || t('knowledgeEditor.wikiBrowser.gallery.noCaption') }}</div>+ <div class="ig-card-source">{{ sourceLabel(img) }}</div>+ </div>+ </button>+ </div>+ </t-loading>++ <t-pagination+ v-if="total > pageSize"+ :total="total"+ :page-size="pageSize"+ :current="page"+ class="ig-pagination"+ @current-change="onPageChange"+ />+ </section>+ </div>++ <!-- Single-image viewer -->+ <div v-if="viewerOpen && current" class="ig-viewer-overlay" @click.self="closeViewer">+ <div class="ig-viewer">+ <button class="ig-viewer-close" :title="t('knowledgeEditor.wikiBrowser.gallery.viewerClose')" @click="closeViewer">+ <t-icon name="close" />+ </button>+ <button class="ig-nav ig-nav-prev" :title="t('knowledgeEditor.wikiBrowser.gallery.prev')" @click="prevImage">+ <t-icon name="chevron-left" />+ </button>++ <div class="ig-viewer-image">+ <!--+ Rendered only once a displayable source exists: the raw+ resource:// handle (or an empty string) would fire the error+ handler and mask the image that is still being fetched.+ -->+ <img v-if="viewerUrl && !imageFailed" :src="viewerUrl" :alt="current.caption" @error="imageFailed = true" />+ <div v-else-if="imageFailed" class="ig-viewer-image-error">{{ t('knowledgeEditor.wikiBrowser.gallery.imageLoadError') }}</div>+ </div>++ <button class="ig-nav ig-nav-next" :title="t('knowledgeEditor.wikiBrowser.gallery.next')" @click="nextImage">+ <t-icon name="chevron-right" />+ </button>++ <aside class="ig-viewer-info">+ <h3>{{ t('knowledgeEditor.wikiBrowser.gallery.attributes') }}</h3>+ <div v-if="currentAttrs.length">+ <div v-for="a in currentAttrs" :key="a.key" class="ig-info-row">+ <span class="ig-info-key">{{ a.label }}</span>+ <span class="ig-info-val">{{ a.value }}</span>+ </div>+ </div>+ <div v-else class="ig-info-muted">{{ t('knowledgeEditor.wikiBrowser.gallery.noAttrs') }}</div>++ <h3>{{ t('knowledgeEditor.wikiBrowser.gallery.caption') }}</h3>+ <p class="ig-info-text">{{ current.caption || t('knowledgeEditor.wikiBrowser.gallery.noCaption') }}</p>++ <h3>{{ t('knowledgeEditor.wikiBrowser.gallery.ocr') }}</h3>+ <p class="ig-info-text">{{ current.ocr_text || t('knowledgeEditor.wikiBrowser.gallery.noOcr') }}</p>++ <h3>{{ t('knowledgeEditor.wikiBrowser.gallery.source') }}</h3>+ <p class="ig-info-text">+ {{ sourceLabel(current) }}+ <span class="ig-info-sub">{{ current.knowledge_id }}</span>+ </p>+ </aside>+ </div>+ </div>+ </div>+</template>++<style scoped>+.image-gallery {+ position: relative;+ display: flex;+ flex-direction: column;+ height: 100%;+ padding: 16px;+ box-sizing: border-box;+}++.ig-layout {+ display: grid;+ grid-template-columns: 1fr;+ gap: 16px;+ flex: 1;+ min-height: 0;+}++/* A pinned panel takes the right column; the image area keeps the rest.+ The panel precedes the main section in the DOM, so the columns it lands+ in are pinned down explicitly instead of left to source order. */+.ig-layout.has-rail {+ grid-template-columns: minmax(0, 1fr) 300px;+}+.ig-layout.has-rail .ig-main {+ grid-row: 1;+ grid-column: 1;+}+.ig-layout.has-rail .ig-panel-slot {+ grid-row: 1;+ grid-column: 2;+}++/* -------------------------------------------------------------------------+ Settings panel+ One element, two placements: pinned it sits in the rail, otherwise it is+ lifted out of the grid and floats over the image area near its toolbar+ control. Keeping a single element means the two never drift apart.+ ------------------------------------------------------------------------- */+.ig-panel-slot {+ display: none;+ align-self: start;+ max-height: 100%;+}+.ig-layout.has-rail .ig-panel-slot {+ display: block;+}++.ig-panel-slot.is-floating {+ display: block;+ position: absolute;+ top: 92px;+ right: 28px;+ width: 320px;+ z-index: 20;+ max-height: calc(100% - 120px);+ overflow: auto;+ background: var(--td-bg-color-container);+ border: 1px solid var(--td-component-border);+ border-radius: var(--td-radius-medium);+ box-shadow: var(--td-shadow-card));+}++.ig-panel-head {+ display: flex;+ align-items: center;+ gap: 8px;+ padding: 8px 12px;+ /* No bottom border here: the tab bar already draws one, and a second+ divider under it just reads as visual noise. */+}+.ig-panel-tabs {+ flex: 1 1 0;+ min-width: 0;+}+.ig-pin {+ /* The tab bar would otherwise stretch and shove the pin out of the head. */+ flex-shrink: 0;+ display: inline-flex;+ align-items: center;+ justify-content: center;+ width: 28px;+ height: 28px;+ padding: 0;+ border: 1px solid transparent;+ border-radius: var(--app-radius-sm);+ background: transparent;+ color: var(--td-text-color-secondary);+ cursor: pointer;+}+.ig-pin:hover {+ background: var(--td-bg-color-container-hover);+}+.ig-pin.is-pinned {+ color: var(--td-brand-color);+}++.ig-panel-body {+ padding: 12px;+}++.ig-row {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 12px;+ margin-bottom: 14px;+}+.ig-row-label {+ font-size: var(--app-text-md);+ color: var(--td-text-color-primary);+}+.ig-hint {+ font-size: var(--app-text-sm);+ color: var(--td-text-color-placeholder);+}+.ig-attr-blocks {+ display: flex;+ flex-direction: column;+ gap: 14px;+}+.ig-attr-block {+ display: flex;+ flex-direction: column;+ gap: 6px;+}+.ig-attr-name {+ font-size: var(--app-text-md);+ font-weight: 600;+ color: var(--td-text-color-primary);+}+.ig-verdict-rows {+ display: flex;+ flex-direction: column;+ gap: 4px;+}+/* A gated block reads as inactive: dimmed text and buttons, but still+ clickable so the first touch can activate the master switch. */+.ig-verdict-rows.is-idle,+.ig-search-fields.is-idle {+ opacity: 0.4;+}+.ig-search-fields {+ display: flex;+ flex-direction: column;+ gap: 4px;+}+.ig-verdict-row {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 8px;+}+.ig-verdict-value {+ font-size: var(--app-text-md);+ color: var(--td-text-color-primary);+ cursor: default;+}+.ig-verdict-group {+ display: inline-flex;+ border: 1px solid var(--td-component-border);+ border-radius: var(--app-radius-sm);+ overflow: hidden;+}+.ig-verdict {+ min-width: 30px;+ padding: 2px 6px;+ border: none;+ border-right: 1px solid var(--td-component-border);+ background: var(--td-bg-color-container);+ font-size: var(--app-text-sm);+ line-height: 20px;+ color: var(--td-text-color-secondary);+ cursor: pointer;+}+.ig-verdict:last-child {+ border-right: none;+}+.ig-verdict:hover {+ background: var(--td-bg-color-container-hover);+}+.ig-verdict.is-active.is-default {+ background: var(--td-bg-color-secondary);+ color: var(--td-text-color-primary);+ font-weight: 600;+}+.ig-verdict.is-active.is-off {+ background: var(--td-error-color-1);+ color: var(--td-error-color);+ font-weight: 600;+}+.ig-verdict.is-active.is-on {+ background: var(--td-success-color-1);+ color: var(--td-success-color);+ font-weight: 600;+}++/* Toolbar: one row, so nothing steals vertical space from the grid. */+.ig-toolbar {+ display: flex;+ align-items: center;+ gap: 10px;+ margin-bottom: 12px;+ flex-wrap: wrap;+}+.ig-search {+ width: 200px;+ max-width: 260px;+}+.ig-scope {+ display: inline-flex;+ align-items: center;+ gap: 4px;+}+.ig-scope-name {+ font-size: var(--app-text-md);+ color: var(--td-text-color-secondary);+ white-space: nowrap;+}+.ig-scope-value {+ font-size: var(--app-text-md);+ color: var(--td-text-color-primary);+ white-space: nowrap;+}+.ig-scope-arrow {+ display: inline-flex;+ align-items: center;+ justify-content: center;+ width: 24px;+ height: 28px;+ padding: 0;+ border: 1px solid var(--td-component-border);+ border-radius: var(--td-radius-medium);+ background: var(--td-bg-color-container);+ color: var(--td-text-color-secondary);+ cursor: pointer;+}+.ig-scope-arrow:hover:not(:disabled) {+ border-color: var(--td-brand-color);+ color: var(--td-brand-color);+}+.ig-scope-arrow:disabled {+ opacity: 0.45;+ cursor: not-allowed;+}+.ig-scope-sep {+ width: 1px;+ height: 20px;+ margin: 0 2px;+ background: var(--td-component-border);+}+.ig-sort {+ width: 140px;+}+.ig-order {+ white-space: nowrap;+}+/* The button wraps its content in .t-button__text, an inline-flex box whose+ default stretch pins the explicitly-sized 16px icon to the top of the 22px+ line box, so the arrow reads as riding high; center it instead. */+.ig-order :deep(.t-button__text) {+ align-items: center;+}+.ig-count {+ margin-left: auto;+ font-size: var(--app-text-md);+ color: var(--td-text-color-secondary);+ white-space: nowrap;+}++.ig-filter-group {+ margin-bottom: 18px;+}+.ig-filter-label {+ display: block;+ font-size: var(--app-text-md);+ color: var(--td-text-color-secondary);+ margin-bottom: 8px;+}+.ig-search-hint {+ font-size: var(--app-text-sm);+ color: var(--td-text-color-placeholder);+ margin-top: 6px;+}+.ig-search-fields {+ margin-top: 6px;+ display: flex;+ flex-direction: column;+ gap: 2px;+}+.ig-attr-filter {+ margin-bottom: 12px;+}+.ig-attr-name {+ font-size: var(--app-text-md);+ font-weight: 500;+ margin-bottom: 4px;+}+.ig-no-attrs {+ font-size: var(--app-text-md);+}+.ig-apply-all {+ margin-top: 4px;+}+.ig-apply-all .ig-verdict-group {+ flex-shrink: 0;+}++/* Main */+.ig-main {+ display: flex;+ flex-direction: column;+ min-width: 0;+ min-height: 0;+}+.ig-toolbar {+ display: flex;+ align-items: center;+ gap: 12px;+ margin-bottom: 14px;+ flex-wrap: wrap;+}+.ig-search {+ flex: 1;+ min-width: 220px;+}+.ig-sort {+ width: 160px;+}+.ig-count {+ font-size: var(--app-text-md);+ color: var(--td-text-color-secondary);+ white-space: nowrap;+}+.ig-loading-area {+ flex: 1;+ min-height: 0;+ overflow: auto;+}+.ig-error {+ color: var(--td-error-color);+ padding: 16px 0;+}+.ig-empty {+ color: var(--td-text-color-placeholder);+ padding: 48px 0;+ text-align: center;+}++/* Grid */+.ig-grid {+ display: grid;+ grid-template-columns: repeat(auto-fill, minmax(168px, 1fr));+ gap: 14px;+}+.ig-card {+ border: 1px solid var(--td-component-border);+ border-radius: var(--app-radius-md);+ overflow: hidden;+ background: var(--td-bg-color-container);+ cursor: pointer;+ padding: 0;+ text-align: left;+ transition: box-shadow var(--app-motion-fast), transform var(--app-motion-fast);+ display: flex;+ flex-direction: column;+}+.ig-card:hover {+ box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);+ transform: translateY(-2px);+}+.ig-card-thumb {+ aspect-ratio: 4 / 3;+ background: #f3f3f3;+ display: flex;+ align-items: center;+ justify-content: center;+ overflow: hidden;+}+.ig-card-thumb img {+ width: 100%;+ height: 100%;+ object-fit: cover;+}+.ig-thumb-error {+ font-size: var(--app-text-sm);+ color: var(--td-text-color-placeholder);+ padding: 0 8px;+ text-align: center;+}+.ig-card-meta {+ padding: 8px 10px;+}+.ig-card-caption {+ font-size: var(--app-text-md);+ line-height: 1.4;+ display: -webkit-box;+ -webkit-line-clamp: 2;+ -webkit-box-orient: vertical;+ overflow: hidden;+}+.ig-card-source {+ font-size: var(--app-text-sm);+ color: var(--td-text-color-secondary);+ margin-top: 4px;+ white-space: nowrap;+ overflow: hidden;+ text-overflow: ellipsis;+}++.ig-pagination {+ margin-top: 16px;+ justify-content: center;+}++/* Viewer */+.ig-viewer-overlay {+ position: fixed;+ inset: 0;+ background: rgba(0, 0, 0, 0.72);+ z-index: 2000;+ display: flex;+ align-items: center;+ justify-content: center;+ padding: 24px;+ box-sizing: border-box;+}+.ig-viewer {+ position: relative;+ display: grid;+ grid-template-columns: 1fr 340px;+ gap: 0;+ width: min(1100px, 96vw);+ height: min(80vh, 760px);+ background: var(--td-bg-color-container);+ border-radius: var(--app-radius-xl);+ overflow: hidden;+}+.ig-viewer-image {+ display: flex;+ align-items: center;+ justify-content: center;+ background: #1a1a1a;+ padding: 12px;+ min-width: 0;+}+.ig-viewer-image img {+ max-width: 100%;+ max-height: 100%;+ object-fit: contain;+}+.ig-viewer-image-error {+ color: #ddd;+}+.ig-viewer-info {+ padding: 20px;+ overflow: auto;+ border-left: 1px solid var(--td-component-border);+}+.ig-viewer-info h3 {+ font-size: var(--app-text-md);+ text-transform: uppercase;+ letter-spacing: 0.04em;+ color: var(--td-text-color-secondary);+ margin: 16px 0 8px;+}+.ig-viewer-info h3:first-child {+ margin-top: 0;+}+.ig-info-row {+ display: flex;+ justify-content: space-between;+ gap: 12px;+ padding: 4px 0;+ font-size: var(--app-text-base);+}+.ig-info-key {+ color: var(--td-text-color-secondary);+}+.ig-info-val {+ font-weight: 500;+ text-align: right;+}+.ig-info-text {+ font-size: var(--app-text-base);+ line-height: 1.6;+ white-space: pre-wrap;+ word-break: break-word;+ margin: 0;+}+.ig-info-muted {+ color: var(--td-text-color-placeholder);+ font-size: var(--app-text-base);+}+.ig-info-sub {+ display: block;+ font-size: var(--app-text-sm);+ color: var(--td-text-color-placeholder);+ margin-top: 2px;+ word-break: break-all;+}+.ig-viewer-close {+ position: absolute;+ top: 10px;+ right: 10px;+ z-index: 2;+ border: none;+ background: rgba(0, 0, 0, 0.45);+ color: #fff;+ width: 32px;+ height: 32px;+ border-radius: 50%;+ cursor: pointer;+ display: flex;+ align-items: center;+ justify-content: center;+}+.ig-nav {+ position: absolute;+ top: 50%;+ transform: translateY(-50%);+ z-index: 2;+ border: none;+ background: rgba(0, 0, 0, 0.45);+ color: #fff;+ width: 40px;+ height: 40px;+ border-radius: 50%;+ cursor: pointer;+ display: flex;+ align-items: center;+ justify-content: center;+}+.ig-nav-prev {+ left: 12px;+}+.ig-nav-next {+ right: 352px;+}+</style>diff --git a/frontend/src/views/knowledge/gallery/galleryImageSrc.test.ts b/frontend/src/views/knowledge/gallery/galleryImageSrc.test.tsnew file mode 100644index 000000000..20473e33b--- /dev/null+++ b/frontend/src/views/knowledge/gallery/galleryImageSrc.test.ts@@ -0,0 +1,26 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import { galleryImageRequest } from './galleryImageSrc.ts'++const KB_PROXY = '/api/v1/knowledge-bases/kb-1/files?file_path='++// The default local storage writes local:// handles; they, and every other+// storage scheme, must reach the knowledge-base proxy instead of <img src>.+for (const url of [+ 'local://10001/exports/a.png',+ 'minio://bucket/a.png',+ 'cos://bucket/a.png',+ 's3://bucket/a.png',+ 'resource://AbCdEfGhIjKlMnOpQrStUv',+ 'storage://backend-1/local://10001/a.png',+]) {+ test(`${url.split('://')[0]}:// images load through the knowledge-base file proxy`, () => {+ assert.equal(galleryImageRequest(url, 'kb-1')?.url, `${KB_PROXY}${encodeURIComponent(url)}`)+ })+}++test('browser-renderable URLs are used as is', () => {+ assert.equal(galleryImageRequest('https://cdn.example.com/a.png', 'kb-1'), null)+ assert.equal(galleryImageRequest('', 'kb-1'), null)+})diff --git a/frontend/src/views/knowledge/gallery/galleryImageSrc.ts b/frontend/src/views/knowledge/gallery/galleryImageSrc.tsnew file mode 100644index 000000000..c91f95c1b--- /dev/null+++ b/frontend/src/views/knowledge/gallery/galleryImageSrc.ts@@ -0,0 +1,21 @@+import {+ buildProtectedFileRequest,+ isProviderFileURL,+ resolveProtectedFileAccess,+ type ProtectedFileRequest,+} from '../../../utils/protectedFileAccess.ts'++/**+ * The proxy request that loads one gallery image, or null when the browser can+ * render the URL as is.+ *+ * Stored images are storage handles (local://, minio://, cos://, s3://,+ * storage://<backend>/..., resource://) that no browser can open; they go+ * through the knowledge-base file proxy, which is also what authorises a+ * viewer of a KB shared from another tenant. The scheme list is the one+ * protectedFileAccess owns, so the gallery cannot drift from chat and wiki.+ */+export function galleryImageRequest(rawUrl: string, kbId: string): ProtectedFileRequest | null {+ if (!rawUrl || !isProviderFileURL(rawUrl)) return null+ return buildProtectedFileRequest(rawUrl, resolveProtectedFileAccess({ mode: 'knowledgeBase', kbId }))+}diff --git a/internal/application/repository/chunk_image_assets.go b/internal/application/repository/chunk_image_assets.gonew file mode 100644index 000000000..d4d3d3986--- /dev/null+++ b/internal/application/repository/chunk_image_assets.go@@ -0,0 +1,212 @@+package repository++import (+ "context"+ "strings"++ "github.com/Tencent/WeKnora/internal/types"+)++// ListImageAssets returns one page of a knowledge base's images from+// chunk_images, the projection of chunks.image_info that database triggers+// maintain (migrations versioned/000113, sqlite/000032). An image copied onto+// several chunks is listed once, as the copy no other copy beats (see+// winnerClause), which an index probe per candidate row decides. A plain+// listing therefore reads the page off the listing index and stops; filters+// narrow the candidates before the probe.+func (r *chunkRepository) ListImageAssets(+ ctx context.Context, tenantID uint64, kbID string, q *types.ImageAssetQuery,+) ([]types.ImageAssetRow, int64, error) {+ if q == nil {+ q = &types.ImageAssetQuery{}+ }+ limit := q.Limit+ if limit <= 0 {+ limit = 20+ }+ offset := max(q.Offset, 0)++ d := imageAssetDialect{postgres: r.db.Name() == "postgres"}+ where, args, filtered := d.where(tenantID, kbID, q)+ // Unfiltered, the total is the number of distinct images, which the+ // copies index answers without probing every row.+ count, countArgs := "SELECT COUNT(*) FROM chunk_images i WHERE "+where, args+ if !filtered {+ countArgs = args[:2]+ // DISTINCT in a subquery, not COUNT(DISTINCT): postgres always sorts+ // for the latter, while the former walks the copies index in order.+ count = "SELECT COUNT(*) FROM (SELECT DISTINCT i.image_key FROM chunk_images i " ++ "WHERE i.knowledge_base_id = ? AND i.tenant_id = ?) d"+ }+ dir := " ASC"+ if q.SortDesc {+ dir = " DESC"+ }+ // Ties (every image of one chunk shares its timestamps) follow the sort+ // direction, so a created_at listing is one backward walk of the index.+ order := d.sortKey(q.SortField) + dir + ", i.chunk_id" + dir + ", i.image_index" + dir+ query := "SELECT i.chunk_id, i.knowledge_id, i.chunk_type, i.is_enabled, i.status, i.created_at, " ++ "i.updated_at, i.image_index, i.url, i.original_url, i.caption, i.ocr_text, " + d.attrsText() ++ " AS attrs_json, (" + count + ") AS total_count " ++ "FROM chunk_images i WHERE " + where + " ORDER BY " + order + " LIMIT ? OFFSET ?"++ var rows []types.ImageAssetRow+ pageArgs := make([]any, 0, len(countArgs)+len(args)+2)+ pageArgs = append(append(append(pageArgs, countArgs...), args...), limit, offset)+ if err := r.db.WithContext(ctx).Raw(query, pageArgs...).Scan(&rows).Error; err != nil {+ return nil, 0, err+ }+ if len(rows) > 0 {+ return rows, rows[0].TotalCount, nil+ }+ if offset == 0 {+ return rows, 0, nil+ }+ // A page past the end carries no row to read the total from.+ var total int64+ err := r.db.WithContext(ctx).Raw(count, countArgs...).Scan(&total).Error+ return rows, total, err+}++// winnerClause keeps one copy per image: the one on the most recently updated+// chunk, ties broken by chunk id and then array position. The copies index+// serves the probe.+const winnerClause = "NOT EXISTS (SELECT 1 FROM chunk_images o " ++ "WHERE o.knowledge_base_id = i.knowledge_base_id AND o.tenant_id = i.tenant_id " ++ "AND o.image_key = i.image_key AND (o.updated_at > i.updated_at " ++ "OR (o.updated_at = i.updated_at AND (o.chunk_id < i.chunk_id " ++ "OR (o.chunk_id = i.chunk_id AND o.image_index < i.image_index)))))"++// imageAssetDialect holds the expressions postgres and sqlite spell+// differently: reading the attrs JSON and matching the keyword.+type imageAssetDialect struct {+ postgres bool+}++// where is the predicate selecting the query's images: the listed copy of+// each image of the knowledge base that passes the filters. Filters judge the+// listed copy, as if the other copies did not exist. Every clause is written+// to be non-NULL, so the NOT in the verdict clause cannot turn an unobserved+// image into a hidden one. filtered reports whether anything beyond the+// knowledge base scope constrains the result.+func (d imageAssetDialect) where(+ tenantID uint64, kbID string, q *types.ImageAssetQuery,+) (sql string, args []any, filtered bool) {+ clauses := []string{"i.knowledge_base_id = ?", "i.tenant_id = ?"}+ args = []any{kbID, tenantID}+ if q.IsEnabled != nil {+ clauses = append(clauses, "i.is_enabled = ?")+ args = append(args, *q.IsEnabled)+ }+ if kw := strings.TrimSpace(q.Keyword); kw != "" {+ pattern := "%" + escapeLikeKeyword(kw) + "%"+ var matches []string+ for _, f := range q.SearchFields {+ expr, ok := d.value(f)+ if !ok {+ continue+ }+ if d.postgres {+ // ILIKE with the default backslash escape, the form the+ // trigram indexes on caption / ocr_text can serve.+ matches = append(matches, expr+" ILIKE ?")+ } else {+ // sqlite's LIKE folds ASCII case only, so non-ASCII keywords+ // match case-sensitively there.+ matches = append(matches, expr+" LIKE ? ESCAPE '"+likeEscapeChar+"'")+ }+ args = append(args, pattern)+ }+ if len(matches) == 0 {+ matches = []string{"1 = 0"}+ }+ clauses = append(clauses, "("+strings.Join(matches, " OR ")+")")+ }+ for _, set := range q.AttrFilters {+ expr, ok := d.value(set.Field)+ if !ok || len(set.Values) == 0 {+ continue+ }+ // An image never observed for the attribute is not constrained by+ // it: absence is silence, not a mismatch.+ clauses = append(clauses, "("+expr+" IS NULL OR "+expr+" IN ?)")+ args = append(args, set.Values)+ }+ if off, offArgs := d.anyCarries(q.OffRules); off != "" {+ // An "off" hides the images carrying its value unless an "on" claims+ // the same image: a forced display outranks a forced hide.+ on, onArgs := d.anyCarries(q.OnRules)+ if on == "" {+ on = "1 = 0"+ }+ clauses = append(clauses, "(("+on+") OR NOT ("+off+"))")+ args = append(append(args, onArgs...), offArgs...)+ }+ filtered = len(clauses) > 2+ return strings.Join(append(clauses, winnerClause), " AND "), args, filtered+}++// anyCarries is true for an image carrying any of the sets' values. An image+// without a value for a field never matches.+func (d imageAssetDialect) anyCarries(sets []types.ImageAssetValueSet) (string, []any) {+ var clauses []string+ var args []any+ for _, set := range sets {+ expr, ok := d.value(set.Field)+ if !ok || len(set.Values) == 0 {+ continue+ }+ clauses = append(clauses, "("+expr+" IS NOT NULL AND "+expr+" IN ?)")+ args = append(args, set.Values)+ }+ return strings.Join(clauses, " OR "), args+}++// sortKey is the value images are ordered by. An image without a value for+// the field sorts as the empty string.+func (d imageAssetDialect) sortKey(f types.ImageAssetField) string {+ switch f.Builtin {+ case "created_at", "updated_at", "is_enabled":+ return "i." + f.Builtin+ }+ if expr, ok := d.value(f); ok {+ return "LOWER(COALESCE(" + expr + ", ''))"+ }+ return "i.created_at"+}++// value is the normalized text of a field for one image, NULL when the image+// carries none. Booleans read as "true"/"false" on both backends, the same+// form the gallery contract lists values in. Timestamps are sort-only: they+// have no text form to search or filter on.+func (d imageAssetDialect) value(f types.ImageAssetField) (string, bool) {+ switch f.Builtin {+ case "":+ case "caption", "ocr_text":+ return "i." + f.Builtin, true+ case "is_enabled":+ return "(CASE WHEN i.is_enabled THEN 'true' ELSE 'false' END)", true+ default:+ return "", false+ }+ name := f.Attr+ // The name is embedded as a literal (validated against the gallery+ // contract upstream); refuse anything that could leave the JSON path.+ if name == "" || strings.ContainsAny(name, `'"\`) {+ return "", false+ }+ if d.postgres {+ return "(i.attrs->>'" + name + "')", true+ }+ path := `'$."` + name + `"'`+ return "(CASE json_type(i.attrs, " + path + ") WHEN 'true' THEN 'true' WHEN 'false' THEN 'false' " ++ "ELSE CAST(json_extract(i.attrs, " + path + ") AS TEXT) END)", true+}++// attrsText reads the attrs column back as JSON text.+func (d imageAssetDialect) attrsText() string {+ if d.postgres {+ return "i.attrs::text"+ }+ return "i.attrs"+}diff --git a/internal/application/repository/chunk_image_assets_test.go b/internal/application/repository/chunk_image_assets_test.gonew file mode 100644index 000000000..ec938497a--- /dev/null+++ b/internal/application/repository/chunk_image_assets_test.go@@ -0,0 +1,372 @@+package repository++import (+ "context"+ "encoding/json"+ "os"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/google/uuid"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/postgres"+ "gorm.io/gorm"+)++// imageAssetBackends runs fn against in-memory SQLite and, when+// WEKNORA_REPOSITORY_TEST_POSTGRES_DSN points at a disposable database, against+// PostgreSQL too — the gallery query is spelled differently per dialect, so+// both spellings need the same assertions. For example:+//+// docker run -d --rm -e POSTGRES_PASSWORD=pg -e POSTGRES_DB=weknora -p 55432:5432 \+// paradedb/paradedb:v0.22.6-pg17+// WEKNORA_REPOSITORY_TEST_POSTGRES_DSN=postgres://postgres:pg@localhost:55432/weknora?sslmode=disable+//+// Both runs apply the real chunk_images migration, so the triggers and the+// backfill under test are the ones that ship.+func imageAssetBackends(t *testing.T, fn func(t *testing.T, db *gorm.DB)) {+ t.Run("sqlite", func(t *testing.T) {+ db := setupChunkTestDB(t)+ applyChunkImagesMigration(t, db)+ fn(t, db)+ })+ t.Run("postgres", func(t *testing.T) {+ dsn := os.Getenv("WEKNORA_REPOSITORY_TEST_POSTGRES_DSN")+ if dsn == "" {+ t.Skip("set WEKNORA_REPOSITORY_TEST_POSTGRES_DSN to run the PostgreSQL gallery query")+ }+ db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})+ require.NoError(t, err)+ require.NoError(t, db.AutoMigrate(&types.Chunk{}))+ applyChunkImagesMigration(t, db)+ fn(t, db)+ })+}++// applyChunkImagesMigration runs the dialect's chunk_images up migration. It+// is idempotent, which is also what lets a test re-run it to exercise the+// backfill.+func applyChunkImagesMigration(t *testing.T, db *gorm.DB) {+ t.Helper()+ path := "../../../migrations/sqlite/000032_chunk_images.up.sql"+ if db.Name() == "postgres" {+ path = "../../../migrations/versioned/000113_chunk_images.up.sql"+ }+ sql, err := os.ReadFile(path)+ require.NoError(t, err)+ require.NoError(t, db.Exec(string(sql)).Error)+}++// imageFixture writes chunks for one fresh knowledge base; every test gets its+// own kbID so the postgres run needs no cleanup between tests.+type imageFixture struct {+ t *testing.T+ db *gorm.DB+ kbID string+ base time.Time+}++func newImageFixture(t *testing.T, db *gorm.DB) *imageFixture {+ return &imageFixture{t: t, db: db, kbID: uuid.NewString(), base: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}+}++// fixtureImage is one image_info entry, written in the persisted shape: the+// observed attributes nest under attrs.attrs.+type fixtureImage struct {+ URL string+ Caption string+ OCRText string+ Attrs map[string]any+}++func (f fixtureImage) MarshalJSON() ([]byte, error) {+ out := map[string]any{"url": f.URL, "original_url": f.URL, "caption": f.Caption, "ocr_text": f.OCRText}+ if f.Attrs != nil {+ out["attrs"] = map[string]any{"schema": "attrs/2", "attrs": f.Attrs}+ }+ return json.Marshal(out)+}++// add inserts one chunk carrying images, updated minute minutes after base.+func (fx *imageFixture) add(chunkType string, minute int, images ...fixtureImage) *types.Chunk {+ fx.t.Helper()+ raw, err := json.Marshal(images)+ require.NoError(fx.t, err)+ return fx.addRaw(chunkType, minute, string(raw))+}++func (fx *imageFixture) addRaw(chunkType string, minute int, imageInfo string) *types.Chunk {+ fx.t.Helper()+ at := fx.base.Add(time.Duration(minute) * time.Minute)+ c := &types.Chunk{+ ID: uuid.NewString(),+ TenantID: 1,+ KnowledgeBaseID: fx.kbID,+ KnowledgeID: "doc-" + fx.kbID[:8],+ Content: "x",+ ChunkType: chunkType,+ IsEnabled: true,+ ImageInfo: imageInfo,+ CreatedAt: at,+ UpdatedAt: at,+ }+ require.NoError(fx.t, fx.db.Create(c).Error)+ return c+}++func (fx *imageFixture) list(q types.ImageAssetQuery) ([]types.ImageAssetRow, int64) {+ fx.t.Helper()+ if q.Limit == 0 {+ q.Limit = 100+ }+ rows, total, err := NewChunkRepository(fx.db).ListImageAssets(context.Background(), 1, fx.kbID, &q)+ require.NoError(fx.t, err)+ return rows, total+}++func rowURLs(t *testing.T, rows []types.ImageAssetRow) []string {+ t.Helper()+ urls := make([]string, 0, len(rows))+ for _, r := range rows {+ urls = append(urls, r.URL)+ }+ return urls+}++var (+ fieldCaption = types.ImageAssetField{Builtin: "caption"}+ fieldOCR = types.ImageAssetField{Builtin: "ocr_text"}+ fieldText = types.ImageAssetField{Attr: "contain.text"}+ fieldVisual = types.ImageAssetField{Attr: "contain.data_visual"}+)++func TestListImageAssets_DedupsAndExpandsArrays(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ // The multimodal pipeline writes the same image to its OCR and caption+ // children; the most recently updated copy is the one listed.+ fx.add("image_ocr", 1, fixtureImage{URL: "local://a.png", Caption: "old"})+ caption := fx.add("image_caption", 2, fixtureImage{URL: "local://a.png", Caption: "new"})+ // A pre-2026-02 text chunk carrying several images, one of them shared.+ legacy := fx.add("text", 0,+ fixtureImage{URL: "local://b.png"}, fixtureImage{URL: "local://c.png"}, fixtureImage{URL: "local://a.png"})++ rows, total := fx.list(types.ImageAssetQuery{SortField: types.ImageAssetField{Builtin: "created_at"}})+ require.EqualValues(t, 3, total)+ require.ElementsMatch(t, []string{"local://a.png", "local://b.png", "local://c.png"}, rowURLs(t, rows))+ for _, r := range rows {+ switch rowURLs(t, []types.ImageAssetRow{r})[0] {+ case "local://a.png":+ require.Equal(t, caption.ID, r.ChunkID)+ require.Equal(t, "new", r.Caption)+ case "local://c.png":+ require.Equal(t, legacy.ID, r.ChunkID)+ require.Equal(t, 1, r.ImageIndex)+ }+ }+ })+}++func TestListImageAssets_SkipsForeignDeletedAndMalformedRows(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ fx.add("image_caption", 0, fixtureImage{URL: "local://keep.png"})+ deleted := fx.add("image_caption", 0, fixtureImage{URL: "local://deleted.png"})+ require.NoError(t, db.Delete(deleted).Error)+ fx.addRaw("text", 0, "")+ fx.addRaw("text", 0, `{"url":"local://object.png"}`)+ other := newImageFixture(t, db)+ other.add("image_caption", 0, fixtureImage{URL: "local://other-kb.png"})+ // A malformed row must neither fail the chunk write nor the listing.+ fx.addRaw("text", 0, `[{"url": broken`)++ rows, total := fx.list(types.ImageAssetQuery{})+ require.EqualValues(t, 1, total)+ require.Equal(t, []string{"local://keep.png"}, rowURLs(t, rows))+ })+}++func TestListImageAssets_PagesStablyThroughTies(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ // Every image of one chunk shares its timestamps: a desc sort on+ // created_at is all ties and must still page without repeats or gaps.+ var imgs []fixtureImage+ for _, name := range []string{"p0", "p1", "p2", "p3", "p4"} {+ imgs = append(imgs, fixtureImage{URL: "local://" + name + ".png"})+ }+ fx.add("text", 0, imgs...)++ var seen []string+ for offset := 0; offset < 6; offset += 2 {+ rows, total := fx.list(types.ImageAssetQuery{+ SortField: types.ImageAssetField{Builtin: "created_at"}, SortDesc: true, Offset: offset, Limit: 2,+ })+ require.EqualValues(t, 5, total, "offset %d", offset)+ seen = append(seen, rowURLs(t, rows)...)+ }+ // Ties follow the sort direction, so newest-first walks the chunk's+ // images from the last one, like images of separate chunks.+ require.Equal(t, []string{+ "local://p4.png", "local://p3.png", "local://p2.png", "local://p1.png", "local://p0.png",+ }, seen)++ rows, total := fx.list(types.ImageAssetQuery{Offset: 10, Limit: 2})+ require.Empty(t, rows)+ require.EqualValues(t, 5, total, "a page past the end still reports the total")+ })+}++func TestListImageAssets_KeywordSearch(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ fx.add("image_caption", 0, fixtureImage{URL: "local://chart.png", Caption: "Quarterly Revenue chart"})+ fx.add("image_caption", 1, fixtureImage{URL: "local://scan.png", OCRText: "growth 50% year over year"})+ fx.add("image_caption", 2, fixtureImage{URL: "local://logo.png", Caption: "company logo"})++ search := func(kw string, fields ...types.ImageAssetField) []string {+ rows, _ := fx.list(types.ImageAssetQuery{Keyword: kw, SearchFields: fields})+ return rowURLs(t, rows)+ }+ require.Equal(t, []string{"local://chart.png"}, search("revenue", fieldCaption, fieldOCR),+ "matching is case-insensitive")+ require.Equal(t, []string{"local://scan.png"}, search("50%", fieldCaption, fieldOCR),+ "LIKE wildcards in the keyword are literal")+ require.Empty(t, search("50%", fieldCaption), "only the requested fields are searched")+ require.Empty(t, search("local://"), "no searchable field means no match")+ _, total := fx.list(types.ImageAssetQuery{Keyword: "local://"})+ require.Zero(t, total, "and the total agrees")+ })+}++func TestListImageAssets_AttributeFiltersAndRules(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ fx.add("image_caption", 0, fixtureImage{+ URL: "local://block.png",+ Attrs: map[string]any{"contain.text": "block", "contain.data_visual": true},+ })+ fx.add("image_caption", 1, fixtureImage{+ URL: "local://none.png",+ Attrs: map[string]any{"contain.text": "none", "contain.data_visual": false},+ })+ // Never observed: no attribute keys at all.+ fx.add("image_caption", 2, fixtureImage{URL: "local://blank.png"})++ list := func(q types.ImageAssetQuery) []string {+ q.SortField = types.ImageAssetField{Builtin: "created_at"}+ rows, _ := fx.list(q)+ return rowURLs(t, rows)+ }++ require.Equal(t, []string{"local://block.png", "local://blank.png"}, list(types.ImageAssetQuery{+ AttrFilters: []types.ImageAssetValueSet{{Field: fieldText, Values: []string{"block"}}},+ }), "a filter narrows observed images and leaves unobserved ones alone")++ require.Equal(t, []string{"local://block.png", "local://blank.png"}, list(types.ImageAssetQuery{+ AttrFilters: []types.ImageAssetValueSet{{Field: fieldVisual, Values: []string{"true"}}},+ }), "JSON booleans compare as \"true\"/\"false\" on both backends")++ require.Equal(t, []string{"local://none.png", "local://blank.png"}, list(types.ImageAssetQuery{+ OffRules: []types.ImageAssetValueSet{{Field: fieldText, Values: []string{"block"}}},+ }), "off hides the images carrying the value and nothing else")++ require.Equal(t, []string{"local://block.png", "local://blank.png"}, list(types.ImageAssetQuery{+ OffRules: []types.ImageAssetValueSet{{Field: fieldText, Values: []string{"none", "block"}}},+ OnRules: []types.ImageAssetValueSet{{Field: fieldVisual, Values: []string{"true"}}},+ }), "on outranks off for the same image, even across attributes")++ disabled := false+ require.Empty(t, list(types.ImageAssetQuery{IsEnabled: &disabled}))+ })+}++func TestListImageAssets_SortsByAttribute(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ fx.add("image_caption", 0, fixtureImage{URL: "local://s.png", Attrs: map[string]any{"contain.text": "sparse"}})+ fx.add("image_caption", 1, fixtureImage{URL: "local://b.png", Attrs: map[string]any{"contain.text": "block"}})+ fx.add("image_caption", 2, fixtureImage{URL: "local://u.png"})++ rows, _ := fx.list(types.ImageAssetQuery{SortField: fieldText})+ require.Equal(t, []string{"local://u.png", "local://b.png", "local://s.png"}, rowURLs(t, rows),+ "an image without the attribute sorts as the empty string")+ })+}++func TestListImageAssets_TriggersFollowChunkWrites(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ older := fx.add("image_ocr", 1, fixtureImage{URL: "local://a.png", Caption: "old"})+ newer := fx.add("image_caption", 2, fixtureImage{URL: "local://a.png", Caption: "new"})+ keep := fx.add("image_caption", 3, fixtureImage{URL: "local://b.png", Caption: "b"})+ captions := func() []string {+ rows, _ := fx.list(types.ImageAssetQuery{SortField: types.ImageAssetField{Builtin: "created_at"}})+ out := make([]string, 0, len(rows))+ for _, r := range rows {+ out = append(out, r.Caption)+ }+ return out+ }+ require.Equal(t, []string{"new", "b"}, captions())++ // A status-only write (no image change) still moves the image to the+ // copy that is now the most recently updated.+ require.NoError(t, db.Model(older).Updates(map[string]any{+ "status": 2, "updated_at": fx.base.Add(time.Hour),+ }).Error)+ require.Equal(t, []string{"old", "b"}, captions())+ require.NoError(t, db.Model(newer).Updates(map[string]any{+ "status": 2, "updated_at": fx.base.Add(2 * time.Hour),+ }).Error)+ require.Equal(t, []string{"new", "b"}, captions())++ // Soft-deleting the winning copy hands the image to the other copy.+ require.NoError(t, db.Delete(newer).Error)+ require.Equal(t, []string{"old", "b"}, captions())++ // An edit to image_info shows up at once.+ raw, _ := json.Marshal([]fixtureImage{{URL: "local://a.png", Caption: "edited"}})+ require.NoError(t, db.Model(older).Update("image_info", string(raw)).Error)+ require.Equal(t, []string{"edited", "b"}, captions())++ // So does the enabled flag.+ require.NoError(t, db.Model(keep).Update("is_enabled", false).Error)+ disabled := false+ rows, _ := fx.list(types.ImageAssetQuery{IsEnabled: &disabled})+ require.Equal(t, []string{"local://b.png"}, rowURLs(t, rows))++ // Moving a document to another knowledge base moves its images.+ target := newImageFixture(t, db)+ require.NoError(t, db.Model(keep).Update("knowledge_base_id", target.kbID).Error)+ require.Equal(t, []string{"edited"}, captions())+ rows, _ = target.list(types.ImageAssetQuery{})+ require.Equal(t, []string{"local://b.png"}, rowURLs(t, rows))++ // A hard delete removes the image entirely.+ require.NoError(t, db.Unscoped().Delete(older).Error)+ require.Empty(t, captions())+ })+}++func TestListImageAssets_MigrationBackfillsExistingChunks(t *testing.T) {+ imageAssetBackends(t, func(t *testing.T, db *gorm.DB) {+ fx := newImageFixture(t, db)+ fx.add("image_ocr", 1, fixtureImage{URL: "local://a.png", Caption: "old"})+ fx.add("image_caption", 2, fixtureImage{URL: "local://a.png", Caption: "new"})+ fx.add("text", 0, fixtureImage{URL: "local://b.png"}, fixtureImage{URL: "local://c.png"})+ // Forget the projection, as a database that predates the migration.+ require.NoError(t, db.Exec("DELETE FROM chunk_images WHERE knowledge_base_id = ?", fx.kbID).Error)+ applyChunkImagesMigration(t, db)++ rows, total := fx.list(types.ImageAssetQuery{})+ require.EqualValues(t, 3, total)+ require.ElementsMatch(t, []string{"local://a.png", "local://b.png", "local://c.png"}, rowURLs(t, rows))+ for _, r := range rows {+ if r.URL == "local://a.png" {+ require.Equal(t, "new", r.Caption, "the backfill elects the most recently updated copy")+ }+ }+ })+}diff --git a/internal/application/service/chunk.go b/internal/application/service/chunk.goindex 8727ca040..bfe770d56 100644--- a/internal/application/service/chunk.go+++ b/internal/application/service/chunk.go@@ -5,9 +5,11 @@ package serviceimport ("context"+ "encoding/json""errors""fmt""sort"+ "strconv""strings""time"@@ -209,6 +211,93 @@ func (s *chunkService) ListPagedChunksByKnowledgeID(ctx context.Context,return types.NewPageResult(total, page, chunks), nil}+// ListImagesByKnowledgeBaseID lists one page of a KB's image assets. Each image+// is one entry of a chunk's image_info array (a chunk may hold several),+// de-duplicated by URL. The repository answers from the chunk_images+// projection, so filtering, sorting and paging cost one indexed query and the+// total reflects the filter.+func (s *chunkService) ListImagesByKnowledgeBaseID(+ ctx context.Context,+ kbID string,+ page *types.Pagination,+ filter *types.ImageListFilter,+) (*types.PageResult, error) {+ tenantID := types.MustTenantIDFromContext(ctx)++ rows, total, err := s.chunkRepository.ListImageAssets(ctx, tenantID, kbID, buildImageAssetQuery(filter, page))+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"kb_id": kbID, "tenant_id": tenantID})+ return nil, err+ }++ assets := make([]types.ImageAsset, 0, len(rows))+ for _, row := range rows {+ attrs := map[string]any{}+ if err := json.Unmarshal([]byte(row.AttrsJSON), &attrs); err != nil || attrs == nil {+ attrs = map[string]any{}+ }+ assets = append(assets, types.ImageAsset{+ ID: row.ChunkID + "#" + strconv.Itoa(row.ImageIndex),+ ChunkID: row.ChunkID,+ KnowledgeID: row.KnowledgeID,+ ChunkType: row.ChunkType,+ URL: row.URL,+ OriginalURL: row.OriginalURL,+ Caption: row.Caption,+ OCRText: row.OCRText,+ Attrs: attrs,+ IsEnabled: row.IsEnabled,+ Status: row.Status,+ CreatedAt: row.CreatedAt,+ UpdatedAt: row.UpdatedAt,+ })+ }++ // Resolve the human-readable name of each source knowledge item in one+ // batch so the viewer can show "来源" without a per-image round trip.+ sourceNames := resolveImageAssetSourceNames(ctx, s, tenantID, assets)+ for i := range assets {+ assets[i].SourceName = sourceNames[assets[i].KnowledgeID]+ }+ return types.NewPageResult(total, page, assets), nil+}++// resolveImageAssetSourceNames maps each distinct KnowledgeID among the assets+// to its knowledge item's display name. Missing items (deleted) simply yield an+// empty name, and the UI falls back to the raw KnowledgeID.+func resolveImageAssetSourceNames(+ ctx context.Context,+ s *chunkService,+ tenantID uint64,+ assets []types.ImageAsset,+) map[string]string {+ names := make(map[string]string)+ ids := make([]string, 0, len(assets))+ seenID := make(map[string]bool)+ for _, a := range assets {+ if a.KnowledgeID == "" || seenID[a.KnowledgeID] {+ continue+ }+ seenID[a.KnowledgeID] = true+ ids = append(ids, a.KnowledgeID)+ }+ if len(ids) == 0 || s.knowledgeRepo == nil {+ return names+ }+ items, err := s.knowledgeRepo.GetKnowledgeBatch(ctx, tenantID, ids)+ if err != nil {+ logger.WarnWithFields(ctx, logger.Fields{+ "knowledge_ids": ids,+ "error": err.Error(),+ }, "failed to resolve image source names")+ return names+ }+ for _, item := range items {+ names[item.ID] = item.Title+ }+ return names+}+// updateChunk updates a chunk// This method updates an existing chunk in the repository// Parameters:diff --git a/internal/application/service/gallery_attrs.go b/internal/application/service/gallery_attrs.gonew file mode 100644index 000000000..7d448c018--- /dev/null+++ b/internal/application/service/gallery_attrs.go@@ -0,0 +1,137 @@+package service++import (+ "sort"+ "strings"++ "github.com/Tencent/WeKnora/internal/types"+)++// ---------------------------------------------------------------------------+// Gallery attribute plumbing+//+// The gallery addresses every attribute by its namespaced id+// ("<sourceID>:<name>"). Builtin attributes map onto the asset's own fields;+// every other source reads the generic attribute map stored in image_info.+// The repository evaluates both in SQL. This keeps the gallery decoupled from+// any particular attribute pipeline: it compiles and runs whether or not the+// observation feature is deployed, and new sources light up without changes+// here.+// ---------------------------------------------------------------------------++// galleryBuiltinSourceID is the id of the builtin attribute source the types+// package registers; its values come from asset fields, not image_info.+const galleryBuiltinSourceID = "builtin"++// galleryDefaultSearchFields is the search field set used when the request+// does not name one (older clients, API callers).+var galleryDefaultSearchFields = []string{+ types.GalleryAttrID(galleryBuiltinSourceID, "caption"),+ types.GalleryAttrID(galleryBuiltinSourceID, "ocr_text"),+}++// galleryField maps a namespaced gallery attribute id onto the field the+// repository query reads: builtin ids address the asset's own columns, every+// other source reads the source-local name from the image_info attrs map.+func galleryField(id string) (types.ImageAssetField, bool) {+ source, name, ok := types.SplitGalleryAttrID(id)+ if !ok {+ return types.ImageAssetField{}, false+ }+ if source == galleryBuiltinSourceID {+ return types.ImageAssetField{Builtin: name}, true+ }+ return types.ImageAssetField{Attr: name}, true+}++// buildImageAssetQuery translates the gallery request into the storage-neutral+// query the repository compiles into SQL. Map iteration is sorted so the same+// request always produces the same statement.+func buildImageAssetQuery(filter *types.ImageListFilter, page *types.Pagination) *types.ImageAssetQuery {+ q := &types.ImageAssetQuery{+ SortField: types.ImageAssetField{Builtin: "created_at"},+ SortDesc: true,+ Offset: page.Offset(),+ Limit: page.GetPageSize(),+ }+ if filter == nil {+ return q+ }+ q.Keyword = strings.TrimSpace(filter.Keyword)+ q.IsEnabled = filter.IsEnabled++ searchIn := filter.SearchIn+ if len(searchIn) == 0 {+ searchIn = galleryDefaultSearchFields+ }+ for _, id := range searchIn {+ if f, ok := galleryField(id); ok {+ q.SearchFields = append(q.SearchFields, f)+ }+ }++ for _, id := range sortedKeys(filter.AttrFilters) {+ f, ok := galleryField(id)+ if !ok {+ continue+ }+ var values []string+ for _, v := range filter.AttrFilters[id] {+ values = append(values, strings.TrimSpace(v))+ }+ if len(values) > 0 {+ q.AttrFilters = append(q.AttrFilters, types.ImageAssetValueSet{Field: f, Values: values})+ }+ }++ for _, id := range sortedKeys(filter.AttrRules) {+ f, ok := galleryField(id)+ if !ok {+ continue+ }+ var on, off []string+ verdicts := filter.AttrRules[id]+ for _, value := range sortedKeys(verdicts) {+ switch verdicts[value] {+ case galleryRuleOn:+ on = append(on, value)+ case galleryRuleOff:+ off = append(off, value)+ }+ }+ if len(on) > 0 {+ q.OnRules = append(q.OnRules, types.ImageAssetValueSet{Field: f, Values: on})+ }+ if len(off) > 0 {+ q.OffRules = append(q.OffRules, types.ImageAssetValueSet{Field: f, Values: off})+ }+ }++ switch filter.SortBy {+ case "":+ case "created_at", "updated_at", "caption":+ // Legacy bare field names map onto their builtin ids.+ q.SortField = types.ImageAssetField{Builtin: filter.SortBy}+ default:+ if f, ok := galleryField(filter.SortBy); ok {+ q.SortField = f+ }+ }+ q.SortDesc = filter.SortOrder != "asc"+ return q+}++// The two verdicts an attribute rule can carry.+const (+ galleryRuleOff = "off"+ galleryRuleOn = "on"+)++func sortedKeys[V any](m map[string]V) []string {+ keys := make([]string, 0, len(m))+ for k := range m {+ keys = append(keys, k)+ }+ sort.Strings(keys)+ return keys+}diff --git a/internal/application/service/gallery_attrs_test.go b/internal/application/service/gallery_attrs_test.gonew file mode 100644index 000000000..6e74bd0b0--- /dev/null+++ b/internal/application/service/gallery_attrs_test.go@@ -0,0 +1,58 @@+package service++import (+ "testing"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++// The filter semantics themselves (unobserved images pass, "on" outranks+// "off", ...) are pinned against real databases in the repository's+// ListImageAssets tests; these cases pin how a gallery request is translated.++func TestBuildImageAssetQuery_Defaults(t *testing.T) {+ q := buildImageAssetQuery(nil, &types.Pagination{Page: 3, PageSize: 24})++ require.Equal(t, types.ImageAssetField{Builtin: "created_at"}, q.SortField)+ require.True(t, q.SortDesc, "newest first")+ require.Equal(t, 48, q.Offset)+ require.Equal(t, 24, q.Limit)++ q = buildImageAssetQuery(&types.ImageListFilter{Keyword: " chart "}, &types.Pagination{})+ require.Equal(t, "chart", q.Keyword)+ require.Equal(t, []types.ImageAssetField{{Builtin: "caption"}, {Builtin: "ocr_text"}}, q.SearchFields,+ "no search_in searches caption and OCR text")+}++func TestBuildImageAssetQuery_TranslatesNamespacedIDs(t *testing.T) {+ q := buildImageAssetQuery(&types.ImageListFilter{+ SearchIn: []string{"builtin:caption", "system:contain.text", "no-separator"},+ AttrFilters: map[string][]string{"system:contain.text": {" block ", "sparse"}},+ AttrRules: map[string]map[string]string{+ "system:contain.data_visual": {"true": "on", "false": "maybe"},+ "system:contain.text": {"none": "off", "block": "off"},+ },+ SortBy: "system:contain.text",+ SortOrder: "asc",+ }, &types.Pagination{})++ text := types.ImageAssetField{Attr: "contain.text"}+ visual := types.ImageAssetField{Attr: "contain.data_visual"}+ require.Equal(t, []types.ImageAssetField{{Builtin: "caption"}, text}, q.SearchFields,+ "ids without a source are dropped")+ require.Equal(t, []types.ImageAssetValueSet{{Field: text, Values: []string{"block", "sparse"}}}, q.AttrFilters)+ require.Equal(t, []types.ImageAssetValueSet{{Field: visual, Values: []string{"true"}}}, q.OnRules,+ "unknown verdicts are ignored")+ require.Equal(t, []types.ImageAssetValueSet{{Field: text, Values: []string{"block", "none"}}}, q.OffRules,+ "values are sorted so one request always yields one statement")+ require.Equal(t, text, q.SortField)+ require.False(t, q.SortDesc)+}++func TestBuildImageAssetQuery_LegacySortNames(t *testing.T) {+ for _, name := range []string{"created_at", "updated_at", "caption"} {+ q := buildImageAssetQuery(&types.ImageListFilter{SortBy: name}, &types.Pagination{})+ require.Equal(t, types.ImageAssetField{Builtin: name}, q.SortField, name)+ }+}diff --git a/internal/application/service/image_action_loop.go b/internal/application/service/image_action_loop.gonew file mode 100644index 000000000..a24560ba5--- /dev/null+++ b/internal/application/service/image_action_loop.go@@ -0,0 +1,124 @@+package service++import (+ "context"+ "strings"++ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/models/vlm"+ "github.com/Tencent/WeKnora/internal/types"+)++// ActionRound is one dispatch step: a set of actions executed together. The+// dispatch layer may physically merge co-scheduled actions (observation and+// caption share one VLM call); the set is what the loop reasons about.+type ActionRound struct {+ Actions []types.ActionKind+}++// Contains reports whether the round schedules the given action.+func (r ActionRound) Contains(k types.ActionKind) bool {+ for _, a := range r.Actions {+ if a == k {+ return true+ }+ }+ return false+}++// selectImageActionRounds turns the payload switches into the initial plan.+// Observation mode opens with an observation+caption round and lets the result+// processor append an OCR round; caption+OCR mode schedules caption and OCR as+// independent rounds (caption first, then OCR) with no observation. Default+// action membership lives in types.DefaultEnabledActions; the whole-task+// switches (EnableCaption/EnableOCR) only gate caption and OCR on top of it.+func selectImageActionRounds(p *types.ImageMultimodalPayload) []ActionRound {+ on := types.DefaultEnabledActions(p.ImageAttrsEnabled)+ if !p.EnableCaption {+ on[types.ActionCaption] = false+ }+ if !p.EnableOCR {+ on[types.ActionOCR] = false+ }++ if p.ImageAttrsEnabled {+ // Observation and caption share one VLM call in attribute mode.+ r := ActionRound{}+ if on[types.ActionCaption] {+ r.Actions = append(r.Actions, types.ActionCaption)+ }+ if on[types.ActionObservation] {+ r.Actions = append(r.Actions, types.ActionObservation)+ }+ if len(r.Actions) == 0 {+ return nil+ }+ return []ActionRound{r}+ }++ var rounds []ActionRound+ if on[types.ActionCaption] {+ rounds = append(rounds, ActionRound{Actions: []types.ActionKind{types.ActionCaption}})+ }+ if on[types.ActionOCR] {+ rounds = append(rounds, ActionRound{Actions: []types.ActionKind{types.ActionOCR}})+ }+ return rounds+}++// executeActionRound runs one dispatch step. Observation and caption are+// physically merged into a single VLM call (the describe round); a caption-only+// round (caption+OCR mode) uses the plain caption prompt; an OCR-only round uses+// prompt. The transport here is the direct vlmModel.Predict shim — PR-E will+// route it through a VLM request manager without touching this dispatch logic.+func (s *ImageMultimodalService) executeActionRound(+ ctx context.Context,+ payload *types.ImageMultimodalPayload,+ model vlm.VLM,+ imgBytes []byte,+ vlmCfg types.VLMConfig,+ imageInfo *types.ImageInfo,+ out types.JSONMap,+ round ActionRound,+) {+ if round.Contains(types.ActionObservation) {+ raw, capErr := model.Predict(ctx, [][]byte{imgBytes}, buildImageAttrsPrompt(ctx, vlmCfg))+ if capErr != nil {+ logger.Warnf(ctx, "[ImageMultimodal] Describe and observe failed for %s: %v", payload.ImageURL, capErr)+ out["caption_error"] = capErr.Error()+ return+ }+ obs, ok := types.ParseImageAttrsResponse(raw)+ applyImageObservation(imageInfo, obs.Attrs, obs.Description, out, payload.EnableCaption)+ if !obs.Observed {+ // The model ignored the attribute protocol — a user custom+ // instruction may have derailed the format, or it answered in prose.+ // Nothing is invented to fill the gap: the attribute table stays+ // empty and the OCR policy falls back to its conservative+ // OnUnobserved clause. Flag it so the trace shows the observation+ // did not actually happen, instead of the empty table being read as+ // a confident "nothing to see here".+ out["observation_failed"] = true+ }+ if !ok {+ out["caption_missing"] = true+ }+ return+ }+ if round.Contains(types.ActionCaption) {+ raw, capErr := model.Predict(ctx, [][]byte{imgBytes}, buildVLMCaptionPrompt(ctx, vlmCfg))+ if capErr != nil {+ out["caption_error"] = capErr.Error()+ return+ }+ if text := strings.TrimSpace(raw); text != "" {+ imageInfo.Caption = text+ out["caption_chars"] = len([]rune(text))+ out["caption_preview"] = previewText(text, 200)+ }+ return+ }+ if round.Contains(types.ActionOCR) {+ s.runImageOCR(ctx, payload, model, imgBytes, imageInfo, out, vlmCfg)+ }+}diff --git a/internal/application/service/image_attr_decision.go b/internal/application/service/image_attr_decision.gonew file mode 100644index 000000000..df2486907--- /dev/null+++ b/internal/application/service/image_attr_decision.go@@ -0,0 +1,58 @@+package service++import (+ "fmt"++ "github.com/Tencent/WeKnora/internal/types"+)++// DecideOCR is a pure function: no ctx, no repo, no model. Input the observed+// attributes and the policy; output whether OCR runs. It is the single place+// the "need OCR" decision lives, so it can be unit-tested and replayed.+//+// The default policy encodes, for every attribute the table reads:+//+// ocr = (contain.text == "block")+// || (contain.data_visual == true)+// || the attribute was not observed (conservative: OnUnobserved)+//+// where "not observed" covers both a line the model never wrote and a value that+// was not one of the allowed ones — the parser leaves such an attribute absent+// rather than inventing a default. An incomplete observation therefore keeps+// extracting, so a missed block of text costs one extra call instead of being+// lost.+//+// The result is equivalent to the old 7-class table: decorative / logo / photo+// (text reliably absent or captured by the description) skip OCR;+// text_screenshot / table / chart / other run OCR.+func DecideOCR(attrs types.ImageAttrs, actions types.ImageActionsConfig) bool {+ if len(actions.OCR.On) == 0 {+ // An empty condition list is never a resolved policy (ResolveImageActions+ // always fills it), only a payload that carries none — its zero-value+ // OnUnobserved=false would silently drop OCR. Fall back to the built-in+ // table, the same conservative policy the payload field promises.+ actions = types.DefaultImageActions()+ }+ incomplete := false+ for _, cond := range actions.OCR.On {+ v, ok := attrs.Attrs[cond.Prop]+ if !ok {+ // The observation does not answer for this attribute, so it cannot+ // decide on its own — and it cannot be read as "condition not met"+ // either, which would silently treat a failed observation as a+ // confident negative. Remember it and let OnUnobserved decide.+ incomplete = true+ continue+ }+ if fmt.Sprint(v) == cond.Is {+ return true+ }+ }+ // Nothing matched. Either the observation answered for every attribute the+ // policy reads (a real, complete negative), or it did not — in which case+ // the conservative clause decides.+ if incomplete {+ return actions.OCR.OnUnobserved+ }+ return false+}diff --git a/internal/application/service/image_multimodal.go b/internal/application/service/image_multimodal.goindex 67b9fc4eb..2b11c3f23 100644--- a/internal/application/service/image_multimodal.go+++ b/internal/application/service/image_multimodal.go@@ -154,8 +154,9 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) ereturn fmt.Errorf("unmarshal image multimodal payload: %w", err)}- logger.Infof(ctx, "[ImageMultimodal] Processing image: chunk=%s, url=%s, ocr=%v, caption=%v",- payload.ChunkID, payload.ImageURL, payload.EnableOCR, payload.EnableCaption)+ logger.Infof(ctx,+ "[ImageMultimodal] Processing image: chunk=%s, url=%s, ocr=%v, caption=%v, attrs=%v",+ payload.ChunkID, payload.ImageURL, payload.EnableOCR, payload.EnableCaption, payload.ImageAttrsEnabled)ctx = context.WithValue(ctx, types.TenantIDContextKey, payload.TenantID)if payload.Language != "" {@@ -173,62 +174,26 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) elogger.Infof(ctx,"[ImageMultimodal] Dropping task chunk=%s knowledge=%s kb=%s image=%s",payload.ChunkID, payload.KnowledgeID, payload.KnowledgeBaseID, payload.ImageURL)- // Still count this image toward the parent finalize gate so a batch+ // Still count this image toward the parent finalize gate so a task// of dropped orphans cannot strand multimodal:pending forever.s.checkAndFinalizeAllImages(ctx, payload)return nil}- // Open a per-image subspan under the parent attempt's multimodal- // stage. If the parent stage row is missing (legacy in-flight- // task, or the upstream code shipped without span tracking), the- // tracker is a no-op so we silently fall back to the existing- // counter-based finalize semantics.tracker := s.tracker()- var imgSpan *Span- if payload.Attempt > 0 {- parent := tracker.LookupStage(ctx, payload.KnowledgeID, payload.Attempt, types.StageMultimodal)- if parent != nil {- name := fmt.Sprintf("multimodal.image[%d]", payload.ImageIndex)- imgSpan = tracker.BeginSubSpan(ctx, parent, name, types.SpanKindGeneration, types.JSONMap{- "image_url": payload.ImageURL,- "image_source_type": payload.ImageSourceType,- "enable_ocr": payload.EnableOCR,- "enable_caption": payload.EnableCaption,- "parent_chunk_id": payload.ChunkID,- })- }- }-- // Output map populated as we go — the deferred close picks it up.- // Captures real VLM results (model id, byte count, OCR/caption- // previews, downstream chunk counts) so the trace viewer can answer- // "what did this image actually produce?" without joining back to- // the chunks table.+ // The trace map is shared with the per-image stage below: fields Handle+ // knows before the pipeline starts (which VLM ran) and fields the pipeline+ // discovers (attributes, policy, caption/OCR outcome) land on the same span.imgOut := types.JSONMap{}// finalize-once semantics: on success we always decrement the parent's// pending counter. On failure we only decrement when this is the last- // asynq retry, so a permanently-failing single image cannot leave the- // parent knowledge stuck in "processing" forever — which was the #1- // cause of "stuck parsing" reports. Intermediate retries skip finalize- // so we don't double-count and prematurely trigger post-process.+ // asynq retry, so a permanently-failing image cannot leave the parent+ // knowledge stuck in "processing" forever — which was the #1 cause of+ // "stuck parsing" reports. Intermediate retries skip finalize so we don't+ // double-count and prematurely trigger post-process.var handleErr errordefer func() {- // Finalize the image subspan with the actual outcome — not the- // finalize-counter outcome. The counter logic counts a "tried"- // image regardless of inner success; the span surface tells the- // UI whether THIS specific image worked.- if imgSpan != nil {- if handleErr == nil {- tracker.EndSpan(ctx, imgSpan, imgOut)- } else if isFinalAsynqAttempt(ctx) {- tracker.FailSpan(ctx, imgSpan,- "MULTIMODAL_VLM_FAILED",- handleErr.Error(),- handleErr)- }- }if handleErr == nil || isFinalAsynqAttempt(ctx) {s.checkAndFinalizeAllImages(ctx, payload)} else {@@ -243,71 +208,140 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) ehandleErr = fmt.Errorf("resolve VLM: %w", err)return handleErr}- // Capture the resolved VLM model id (or "legacy_inline" for the- // legacy inline-config path) so the trace shows WHICH model handled- // this image. Without this, debugging "VLM is slow" requires a- // separate hop to the KB config.+ // Capture the resolved VLM model id (or "legacy_inline" for the legacy+ // inline-config path) so the trace shows WHICH model handled this image.+ // Without this, debugging "VLM is slow" requires a separate hop to the KB+ // config.if id := strings.TrimSpace(vlmCfg.ModelID); id != "" {imgOut["vlm_model_id"] = id} else {imgOut["vlm_model_id"] = "legacy_inline"}+ handleErr = s.processImage(ctx, &payload, vlmModel, vlmCfg, tracker, imgOut)+ return handleErr+}++// processImage runs the unified image action loop for one image. The selector+// plans rounds from the payload switches; the dispatcher runs each round+// (observation and caption share one VLM call); the result processor reads the+// observation and, when the OCR policy wants it, appends an OCR round. The+// observation must be known before any OCR call is spent — that ordering is+// what makes "observe first, then act" possible: an image whose text is+// reliably absent does not pay for OCR.+//+// An observation (describe) failure is not fatal. The attributes then stay at+// their conservative defaults, which keeps OCR running, so a model that cannot+// observe costs one extra call rather than losing the text. This mirrors the+// upstream caption path, where a failed caption is also just a warning.+//+// out is the per-image trace map, owned by the caller and closed by the span+// this function ends; every field the pipeline discovers is written into it.+func (s *ImageMultimodalService) processImage(+ ctx context.Context,+ payload *types.ImageMultimodalPayload,+ vlmModel vlm.VLM,+ vlmCfg types.VLMConfig,+ tracker SpanTracker,+ out types.JSONMap,+) error {+ // Open a per-image subspan under the parent attempt's multimodal stage.+ // If the parent stage row is missing (legacy in-flight task, or the+ // upstream code shipped without span tracking), the tracker is a no-op so+ // we silently fall back to the existing counter-based finalize semantics.+ var imgSpan *Span+ if payload.Attempt > 0 {+ parent := tracker.LookupStage(ctx, payload.KnowledgeID, payload.Attempt, types.StageMultimodal)+ if parent != nil {+ name := fmt.Sprintf("multimodal.image[%d]", payload.ImageIndex)+ // The observation, and the policy it resolves to, are only known+ // after the describe round, so they land on the span's output (see+ // out["image_attrs"] and out["attr_policy"]) instead of here.+ imgSpan = tracker.BeginSubSpan(ctx, parent, name, types.SpanKindGeneration, types.JSONMap{+ "image_url": payload.ImageURL,+ "image_source_type": payload.ImageSourceType,+ "parent_chunk_id": payload.ChunkID,+ // Which pipeline the trace is looking at: observation_driven+ // (a describe round that also observes the attributes, then OCR+ // only if the policy says so) or caption_ocr (caption then OCR,+ // no observation). Reading image_info alone cannot tell a+ // caption_ocr run from an observation_driven run that skipped+ // OCR.+ "pipeline": string(types.PipelineModeFor(payload.ImageAttrsEnabled)),+ })+ }+ }++ var handleErr error+ defer func() {+ // Finalize the image subspan with the actual outcome — not the+ // finalize-counter outcome. The counter logic counts a "tried" image+ // regardless of inner success; the span surface tells the UI whether+ // THIS specific image worked.+ if imgSpan == nil {+ return+ }+ if handleErr == nil {+ tracker.EndSpan(ctx, imgSpan, out)+ } else if isFinalAsynqAttempt(ctx) {+ tracker.FailSpan(ctx, imgSpan,+ "MULTIMODAL_VLM_FAILED",+ handleErr.Error(),+ handleErr)+ }+ }()+// Read image bytes. A provider:// URL must be resolved via FileService —// it must NEVER be handed to the HTTP downloader (which would fail with- // "unsupported URL scheme"). On unrecoverable read failure for a single- // image, skip it (deferred finalize will count it).- imgBytes, readErr := s.readImageBytes(ctx, payload)+ // "unsupported URL scheme"). On unrecoverable read failure the image is+ // skipped (the deferred finalize still counts it).+ imgBytes, readErr := s.readImageBytes(ctx, *payload)if readErr != nil {logger.Errorf(ctx, "[ImageMultimodal] Skip unreadable image %s: %v", payload.ImageURL, readErr)- imgOut["skipped"] = "unreadable_image"- imgOut["read_error"] = readErr.Error()+ out["skipped"] = "unreadable_image"+ out["read_error"] = readErr.Error()return nil}- imgOut["image_bytes"] = len(imgBytes)+ out["image_bytes"] = len(imgBytes)imageInfo := types.ImageInfo{URL: payload.ImageURL,OriginalURL: payload.ImageURL,}- if payload.EnableOCR {- prompt := buildVLMOCRPrompt(payload.ImageSourceType, vlmCfg)- if payload.ImageSourceType == "scanned_pdf" {- logger.Infof(ctx, "[ImageMultimodal] Using scanned PDF prompt for OCR: %s", payload.ImageURL)- imgOut["ocr_prompt"] = "scanned_pdf"- } else {- imgOut["ocr_prompt"] = "default"- }-- ocrText, ocrErr := vlmModel.Predict(ctx, [][]byte{imgBytes}, prompt)- if ocrErr != nil {- logger.Warnf(ctx, "[ImageMultimodal] OCR failed for %s: %v", payload.ImageURL, ocrErr)- imgOut["ocr_error"] = ocrErr.Error()- } else {- ocrText = sanitizeOCRText(ocrText)- if ocrText != "" {- imageInfo.OCRText = ocrText- imgOut["ocr_chars"] = len([]rune(ocrText))- imgOut["ocr_preview"] = previewText(ocrText, 200)+ // --- Unified action loop: the decision + dispatch half of the image+ // pipeline framework. Every image step is a normal action (caption,+ // observation, ocr). The selector plans rounds from the payload switches;+ // the dispatcher runs each round (observation + caption share one VLM call);+ // the result processor reads the observation and, when OCR is wanted,+ // appends an ocr round - the "observe, decide, then act" closure. The VLM+ // transport here is a direct-call shim; PR-E routes it through a request+ // manager without touching this dispatch logic.+ if !payload.ImageAttrsEnabled && !payload.EnableOCR {+ // Caption+OCR mode with OCR off: recorded so the trace explains the+ // missing OCR chunk rather than leaving it to be inferred from an+ // absence.+ out["ocr_skipped"] = "disabled"+ }+ plan := selectImageActionRounds(payload)+ for i := 0; i < len(plan); i++ {+ round := plan[i]+ s.executeActionRound(ctx, payload, vlmModel, imgBytes, vlmCfg, &imageInfo, out, round)+ // Result processor: only an observation round feeds the OCR decision.+ if round.Contains(types.ActionObservation) {+ ocrWanted := payload.EnableOCR && DecideOCR(imageInfo.Attrs, payload.ImageActions)+ out["attr_policy"] = types.JSONMap{"ocr": ocrWanted}+ out["image_attrs"] = imageInfo.Attrs.Attrs+ if ocrWanted {+ plan = append(plan, ActionRound{Actions: []types.ActionKind{types.ActionOCR}})} else {- logger.Warnf(ctx, "[ImageMultimodal] OCR returned empty/invalid content for %s, discarded", payload.ImageURL)- imgOut["ocr_chars"] = 0- imgOut["ocr_skipped"] = "empty_or_invalid"+ logger.Infof(ctx, "[ImageMultimodal] Skipping OCR for %s (attrs=%v)",+ payload.ImageURL, imageInfo.Attrs.Attrs)+ out["ocr_skipped"] = "attr_policy"}}}- caption, capErr := vlmModel.Predict(ctx, [][]byte{imgBytes}, buildVLMCaptionPrompt(ctx, vlmCfg))- if capErr != nil {- logger.Warnf(ctx, "[ImageMultimodal] Caption failed for %s: %v", payload.ImageURL, capErr)- imgOut["caption_error"] = capErr.Error()- } else if caption != "" {- imageInfo.Caption = caption- imgOut["caption_chars"] = len([]rune(caption))- imgOut["caption_preview"] = previewText(caption, 200)- }-// Build child chunks for OCR and caption resultsimageInfoJSON, _ := json.Marshal([]types.ImageInfo{imageInfo})var newChunks []*types.Chunk@@ -329,7 +363,7 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) e})}- if imageInfo.Caption != "" {+ if payload.EnableCaption && imageInfo.Caption != "" {newChunks = append(newChunks, &types.Chunk{ID: uuid.New().String(),TenantID: payload.TenantID,@@ -345,11 +379,11 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) eUpdatedAt: time.Now(),})}- imgOut["chunks_created"] = len(newChunks)+ out["chunks_created"] = len(newChunks)if len(newChunks) == 0 {// Deferred finalize will count this image on success.- imgOut["skipped"] = "no_extracted_content"+ out["skipped"] = "no_extracted_content"return nil}@@ -364,19 +398,113 @@ func (s *ImageMultimodalService) Handle(ctx context.Context, task *asynq.Task) e}// Index chunks so they can be retrieved- s.indexChunks(ctx, payload, newChunks)- imgOut["indexed"] = true-- // Enqueue question generation for the caption/OCR content if KB has it enabled.- // During initial processChunks, question generation is skipped for image-type- // knowledge because the text chunk is just a markdown reference. Now that we- // have real textual content (caption/OCR), we can generate questions.- // Note: for documents with multiple images (e.g. PDFs), we also wait until- // all images are processed before triggering summary/question generation.- // Deferred finalize handles the parent knowledge counter.+ s.indexChunks(ctx, *payload, newChunks)+ out["indexed"] = true+return nil}+// buildImageAttrsPrompt asks the model to observe the registered image+// attributes and describe the image in the same answer, so the attributes are+// known before the image's OCR call is spent. The attribute list and questions+// come from the registry, so the prompt cannot drift from the attributes the+// parser folds answers back onto.+func buildImageAttrsPrompt(ctx context.Context, cfg types.VLMConfig) string {+ language := strings.TrimSpace(cfg.DescriptionLanguage)+ if language == "" {+ language = types.LanguageNameFromContext(ctx)+ }+ var b strings.Builder+ fmt.Fprintf(&b,+ "Observe the following about the image, then describe its main content in %s.\n\n"++ "Output one line per observation using exactly this format, then a DESCRIPTION line:\n\n",+ language)+ for _, spec := range types.ImageAttrRegistry {+ allowed := make([]string, 0, len(spec.Values))+ for _, value := range spec.Values {+ allowed = append(allowed, value.Value)+ }+ fmt.Fprintf(&b, "%s: <%s>\n", spec.Name, strings.Join(allowed, " | "))+ }+ b.WriteString("DESCRIPTION: <one or two sentences>\n\nRules:\n")+ for _, spec := range types.ImageAttrRegistry {+ fmt.Fprintf(&b, "- %s: %s\n", spec.Name, spec.Question)+ }+ b.WriteString("- Output only those lines. No preamble, no summary, no extra commentary.\n")+ return types.AppendCustomPromptInstructions(b.String(), cfg.CustomInstructions, "image_description")+}++// applyImageObservation copies a parsed verdict onto the image record so it is+// persisted with the chunk, and mirrors it into the trace map. The attributes+// are always kept — they are what the OCR policy reads next — while the+// description is stored only when this run wants a caption: the observe round is+// not optional even with captions off, because the attributes are the whole+// point of it.+func applyImageObservation(+ imageInfo *types.ImageInfo,+ attrs types.ImageAttrs,+ description string,+ out types.JSONMap,+ wantCaption bool,+) {+ if attrs.Attrs != nil {+ imageInfo.Attrs = attrs+ }+ if description == "" {+ return+ }+ if !wantCaption {+ out["caption_skipped"] = "disabled"+ return+ }+ imageInfo.Caption = description+ out["caption_chars"] = len([]rune(description))+ out["caption_preview"] = previewText(description, 200)+}++// runImageOCR runs the second pipeline round: text extraction at full+// resolution. Both pipelines share it — the observation-driven one reaches it+// only when the attribute policy allows it, caption+OCR mode runs it for every+// image.+func (s *ImageMultimodalService) runImageOCR(+ ctx context.Context,+ payload *types.ImageMultimodalPayload,+ vlmModel vlm.VLM,+ imgBytes []byte,+ imageInfo *types.ImageInfo,+ out types.JSONMap,+ vlmCfg types.VLMConfig,+) {+ // The OCR prompt is system-owned: knowledge base custom instructions must+ // never reach it, or free-form business rules compete with the "No text+ // content" contract and poison image_ocr chunks. buildVLMOCRPrompt picks+ // the scanned-PDF or default prompt and ignores vlmCfg on purpose.+ prompt := buildVLMOCRPrompt(payload.ImageSourceType, vlmCfg)+ if payload.ImageSourceType == "scanned_pdf" {+ logger.Infof(ctx, "[ImageMultimodal] Using scanned PDF prompt for OCR: %s", payload.ImageURL)+ out["ocr_prompt"] = "scanned_pdf"+ } else {+ out["ocr_prompt"] = "default"+ }++ ocrText, ocrErr := vlmModel.Predict(ctx, [][]byte{imgBytes}, prompt)+ if ocrErr != nil {+ logger.Warnf(ctx, "[ImageMultimodal] OCR failed for %s: %v", payload.ImageURL, ocrErr)+ out["ocr_error"] = ocrErr.Error()+ return+ }+ ocrText = sanitizeOCRText(ocrText)+ if ocrText != "" {+ imageInfo.OCRText = ocrText+ out["ocr_chars"] = len([]rune(ocrText))+ out["ocr_preview"] = previewText(ocrText, 200)+ } else {+ logger.Warnf(ctx, "[ImageMultimodal] OCR returned empty/invalid content for %s, discarded", payload.ImageURL)+ out["ocr_chars"] = 0+ out["ocr_skipped"] = "empty_or_invalid"+ }+}+// shouldDropOrphanedMultimodal reports whether the task should exit without// retrying. True for user-cancelled/deleting knowledge, or when the parent// knowledge / knowledge-base row no longer exists (deleted while queue entries@@ -524,7 +652,8 @@ func (s *ImageMultimodalService) indexChunks(ctx context.Context, payload types.}}- logger.Infof(ctx, "[ImageMultimodal] Indexed %d multimodal chunks for image %s", len(chunks), payload.ImageURL)+ logger.Infof(ctx, "[ImageMultimodal] Indexed %d multimodal chunks for knowledge %s",+ len(chunks), payload.KnowledgeID)}// resolveVLM creates a vlm.VLM instance for the given knowledge base,@@ -616,13 +745,17 @@ func (s *ImageMultimodalService) resolveFileServiceForPayload(ctx context.Contexreturn fileSvc}-// readImageBytes loads the image bytes for a multimodal payload.+// readImageBytes loads the image bytes for one image of a multimodal payload.// - For provider:// URLs (local://, minio://, s3://, cos://, ...) it reads via// the resolved FileService and NEVER falls back to HTTP — handing a// provider:// URL to the HTTP downloader is what caused issue #1282.// - For legacy in-flight payloads with ImageLocalPath set, it tries the local// file before falling back to the URL.// - For plain http(s):// URLs it uses the SSRF-safe downloader.+//+// imageURL is passed explicitly (instead of read from payload.ImageURL) because+// a batched payload carries several images and only the first one is mirrored+// onto the legacy single-image fields.func (s *ImageMultimodalService) readImageBytes(ctx context.Context, payload types.ImageMultimodalPayload) ([]byte, error) {_, isResourceRef := types.ParseResourcePath(payload.ImageURL)if isResourceRef || types.ParseProviderScheme(payload.ImageURL) != "" {@@ -671,6 +804,8 @@ func multimodalPendingKey(knowledgeID string) string {return fmt.Sprintf("multimodal:pending:%s", knowledgeID)}+// checkAndFinalizeAllImages decrements the parent's pending-image counter and+// enqueues post-process once the counter reaches zero.func (s *ImageMultimodalService) checkAndFinalizeAllImages(ctx context.Context, payload types.ImageMultimodalPayload) {if s.redisClient == nil {s.enqueueKnowledgePostProcessTask(ctx, payload)diff --git a/internal/application/service/image_multimodal_attrs_test.go b/internal/application/service/image_multimodal_attrs_test.gonew file mode 100644index 000000000..36f78e85f--- /dev/null+++ b/internal/application/service/image_multimodal_attrs_test.go@@ -0,0 +1,691 @@+package service++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "io"+ "strings"+ "testing"++ "github.com/Tencent/WeKnora/internal/models/vlm"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+)++// ---------------------------------------------------------------------------+// Test doubles for the attribute-observed multimodal path.+// ---------------------------------------------------------------------------++// attrsVLMCall records one Predict invocation so a test can assert which+// prompt a step used and how many images it carried.+type attrsVLMCall struct {+ prompt string+ images int+}++type attrsFakeVLM struct {+ calls []attrsVLMCall+ reply func(prompt string, images int) (string, error)+}++func (f *attrsFakeVLM) Predict(_ context.Context, imgBytes [][]byte, prompt string) (string, error) {+ f.calls = append(f.calls, attrsVLMCall{prompt: prompt, images: len(imgBytes)})+ if f.reply == nil {+ return "", nil+ }+ return f.reply(prompt, len(imgBytes))+}++func (f *attrsFakeVLM) GetModelName() string { return "attrs-fake-vlm" }+func (f *attrsFakeVLM) GetModelID() string { return "attrs-fake-vlm-id" }++var _ vlm.VLM = (*attrsFakeVLM)(nil)++// attrsFileService serves every read from memory so readImageBytes resolves+// a local:// reference without touching disk or the network.+type attrsFileService struct {+ interfaces.FileService+ body []byte+ err error+ gets []string+}++func (s *attrsFileService) GetFile(_ context.Context, filePath string) (io.ReadCloser, error) {+ s.gets = append(s.gets, filePath)+ if s.err != nil {+ return nil, s.err+ }+ return io.NopCloser(bytes.NewReader(s.body)), nil+}++// attrsTenantRepo reports "no tenant" so resolveFileServiceForPayload falls+// back to the service's default FileService.+type attrsTenantRepo struct {+ interfaces.TenantRepository+}++func (r *attrsTenantRepo) GetTenantByID(_ context.Context, _ uint64) (*types.Tenant, error) {+ return nil, nil+}++type attrsChunkRepo struct {+ interfaces.ChunkRepository+ created []*types.Chunk+}++func (r *attrsChunkRepo) CreateChunks(_ context.Context, chunks []*types.Chunk) error {+ r.created = append(r.created, chunks...)+ return nil+}++type attrsChunkService struct {+ interfaces.ChunkService+ repo *attrsChunkRepo+}++func (s *attrsChunkService) GetRepository() interfaces.ChunkRepository { return s.repo }++// newAttrsTestService wires a service whose file reads come from memory and+// whose knowledge base lookup returns nil, which makes indexChunks skip vector+// work (it bails out on a nil KB). That keeps the test focused on the image+// pipeline rather than on the retrieval engine.+func newAttrsTestService(fileSvc interfaces.FileService, repo *attrsChunkRepo) *ImageMultimodalService {+ return &ImageMultimodalService{+ chunkService: &attrsChunkService{repo: repo},+ kbService: &orphanKBService{},+ tenantRepo: &attrsTenantRepo{},+ fileSvc: fileSvc,+ }+}++// runProcessImage drives one image through the pipeline and returns the trace+// map the per-image span is closed with — the same map Handle owns.+func runProcessImage(+ t *testing.T,+ svc *ImageMultimodalService,+ payload *types.ImageMultimodalPayload,+ fake *attrsFakeVLM,+) types.JSONMap {+ t.Helper()+ out := types.JSONMap{}+ err := svc.processImage(context.Background(), payload, fake, types.VLMConfig{}, noopSpanTracker{}, out)+ if err != nil {+ t.Fatalf("processImage: %v", err)+ }+ return out+}++// persistedAttrCounts counts a single observed attribute value written onto+// each persisted chunk — how the "the observation is stored, not just logged"+// contract is checked.+func persistedAttrCounts(t *testing.T, chunks []*types.Chunk, key string) map[string]int {+ t.Helper()+ counts := map[string]int{}+ for _, chunk := range chunks {+ var infos []types.ImageInfo+ if err := json.Unmarshal([]byte(chunk.ImageInfo), &infos); err != nil {+ t.Fatalf("decode chunk image_info: %v", err)+ }+ for _, info := range infos {+ if info.Attrs.Attrs == nil {+ counts["<unset>"]+++ continue+ }+ if v, ok := info.Attrs.Attrs[key]; ok {+ counts[fmt.Sprint(v)]+++ } else {+ counts["<unset>"]+++ }+ }+ }+ return counts+}++func equalCounts(got, want map[string]int) bool {+ if len(got) != len(want) {+ return false+ }+ for k, v := range want {+ if got[k] != v {+ return false+ }+ }+ return true+}++// countCallsWith returns how many recorded calls used a prompt containing+// needle, which is how a test tells the observe round from the OCR round.+func countCallsWith(calls []attrsVLMCall, needle string) int {+ n := 0+ for _, c := range calls {+ if strings.Contains(c.prompt, needle) {+ n+++ }+ }+ return n+}++// observedAttrs builds a complete attribute table — the shape the parser+// produces from an observe round the model answered in full.+func observedAttrs(text string, dataVisual bool) types.ImageAttrs {+ return types.ImageAttrs{Attrs: map[string]any{+ "contain.text": text,+ "contain.data_visual": dataVisual,+ }}+}++// ---------------------------------------------------------------------------+// Prompt / parser / decision unit tests+// ---------------------------------------------------------------------------++func TestBuildImageAttrsPrompt(t *testing.T) {+ t.Parallel()+ got := buildImageAttrsPrompt(context.Background(), types.VLMConfig{+ DescriptionLanguage: "English",+ CustomInstructions: "Focus on alarm codes.",+ })++ for _, want := range []string{+ "in English",+ "contain.text:",+ "contain.data_visual:",+ "DESCRIPTION:",+ "Focus on alarm codes.",+ } {+ if !strings.Contains(got, want) {+ t.Errorf("attrs prompt missing %q:\n%s", want, got)+ }+ }++ // Every attribute the parser understands must be offered to the model,+ // otherwise a label the prompt never mentions can never be produced.+ for _, spec := range types.ImageAttrRegistry {+ if !strings.Contains(got, spec.Name) {+ t.Errorf("attrs prompt does not mention attribute %q", spec.Name)+ }+ }++ ctx := context.WithValue(context.Background(), types.LanguageContextKey, "ko-KR")+ if got := buildImageAttrsPrompt(ctx, types.VLMConfig{}); !strings.Contains(got, "in Korean") {+ t.Errorf("attrs prompt should fall back to the context language:\n%s", got)+ }+}++// TestDecideOCR pins the pure OCR decision: a block of text, a data visual, or+// an attribute the observation did not answer for all trigger OCR; sparse (a+// logo) and an explicit absence do not. The decision is a function of observed+// attributes and the policy only — no model, no repo.+func TestDecideOCR(t *testing.T) {+ t.Parallel()+ def := types.DefaultImageActions()++ cases := []struct {+ name string+ attrs types.ImageAttrs+ want bool+ }{+ {"block of text", observedAttrs("block", false), true},+ {"sparse logo", observedAttrs("sparse", false), false},+ {"data visual", observedAttrs("sparse", true), true},+ {"none", observedAttrs("none", false), false},+ // Incomplete observations: the parser leaves an unanswered attribute+ // absent, so the conservative clause has to carry the decision — these+ // must never be read as a confident negative.+ {+ "unobserved text is conservative",+ types.ImageAttrs{Attrs: map[string]any{"contain.data_visual": false}},+ true,+ },+ {+ "unobserved data visual is conservative",+ types.ImageAttrs{Attrs: map[string]any{"contain.text": "none"}},+ true,+ },+ {"empty observation is conservative", types.ImageAttrs{}, true},+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ if got := DecideOCR(tc.attrs, def); got != tc.want {+ t.Errorf("DecideOCR = %v, want %v", got, tc.want)+ }+ })+ }++ // A policy that does not OCR on an unobserved attribute flips the+ // conservative path for both of the incomplete cases above.+ strict := types.ImageActionsConfig{+ OCR: types.ImageOCRAction{+ On: []types.ImageAttrCondition{+ {Prop: "contain.text", Is: "block"},+ {Prop: "contain.data_visual", Is: "true"},+ },+ OnUnobserved: false,+ },+ }+ for _, attrs := range []types.ImageAttrs{+ {Attrs: map[string]any{"contain.data_visual": false}},+ {Attrs: map[string]any{"contain.text": "none"}},+ {},+ } {+ if DecideOCR(attrs, strict) {+ t.Errorf("with OnUnobserved=false an incomplete observation (%v) must not trigger OCR", attrs.Attrs)+ }+ }+}++// ---------------------------------------------------------------------------+// Pipeline execution+// ---------------------------------------------------------------------------++// TestProcessImageObservesAndDescribes pins the attribute pipeline: one observe+// round returns both attributes and a description, the observation is persisted+// with the image, and an attribute the policy keeps still gets its OCR round.+func TestProcessImageObservesAndDescribes(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("table-bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "Q1 Q2 Q3", nil+ }+ return "contain.text: block\ncontain.data_visual: false\nDESCRIPTION: A pricing table.", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ attrs, ok := out["image_attrs"].(map[string]any)+ if !ok {+ t.Fatalf("image_attrs = %v, want the observed attribute map", out["image_attrs"])+ }+ if attrs["contain.text"] != "block" {+ t.Errorf("contain.text = %v, want block", attrs["contain.text"])+ }+ if got, ok := out["attr_policy"].(types.JSONMap); !ok || got["ocr"] != true {+ t.Errorf("attr_policy = %v, want {ocr:true}", out["attr_policy"])+ }+ if _, skipped := out["ocr_skipped"]; skipped {+ t.Errorf("a block of text must be OCR'd, got %v", out["ocr_skipped"])+ }+ // One observe call (never the legacy caption prompt) plus one OCR call.+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1", n)+ }+ if n := countCallsWith(fake.calls, "contain.text:"); n != 1 {+ t.Errorf("observe calls = %d, want 1", n)+ }+ if len(repo.created) != 2 {+ t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))+ }+ if got := persistedAttrCounts(t, repo.created, "contain.text"); !equalCounts(got, map[string]int{"block": 2}) {+ t.Errorf("persisted contain.text = %v, want block on both chunks", got)+ }+}++// TestProcessImageMarksObservationFailed pins the defensive signal: when the+// model answers in prose and ignores the attribute protocol (e.g. a user+// custom instruction derails the format), the pipeline must flag+// observation_failed in the trace instead of passing an empty attribute table+// off as a confident read. Nothing is invented to fill the table, so the OCR+// policy falls back to its conservative OnUnobserved clause (OCR on) and the+// image is not lost — only the observation is recorded as having failed.+func TestProcessImageMarksObservationFailed(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "some text", nil+ }+ // Prose only — no contain.text: / contain.data_visual: lines.+ return "这是一张示意图,展示了系统整体的数据流向与模块划分。", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ if out["observation_failed"] != true {+ t.Errorf("observation_failed = %v, want true for a prose-only answer", out["observation_failed"])+ }+ // No attribute is invented for the unanswered questions: the table stays+ // empty, and the conservative clause is what keeps OCR running.+ if attrs, ok := out["image_attrs"].(map[string]any); !ok || len(attrs) != 0 {+ t.Errorf("image_attrs = %v, want an empty table for a prose-only answer", out["image_attrs"])+ }+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1 (the conservative clause must still extract)", n)+ }+ // And the description was kept, so caption_missing must NOT be set.+ if _, missing := out["caption_missing"]; missing {+ t.Errorf("caption_missing should be unset for a prose answer that has a description")+ }+}++// TestProcessImageSkipsOCRForQuietAttr is the payoff of the feature: an image+// whose observed text is absent (none) must not cost an OCR call, and its+// description must survive as the only child chunk.+func TestProcessImageSkipsOCRForQuietAttr(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("decorative-bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "SHOULD-NOT-BE-ASKED", nil+ }+ return "contain.text: none\ncontain.data_visual: false\nDESCRIPTION: A plain divider rule.", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true, // whole-task switch stays on; the observation is what vetoes+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ if n := countCallsWith(fake.calls, "OCR assistant"); n != 0 {+ t.Fatalf("a quiet image must not be OCR'd, got %d OCR call(s)", n)+ }+ if got := out["ocr_skipped"]; got != "attr_policy" {+ t.Errorf("ocr_skipped = %v, want attr_policy", got)+ }+ if got, ok := out["attr_policy"].(types.JSONMap); !ok || got["ocr"] != false {+ t.Errorf("attr_policy = %v, want {ocr:false}", out["attr_policy"])+ }+ if len(repo.created) != 1 {+ t.Fatalf("persisted chunks = %d, want 1 (caption only)", len(repo.created))+ }+ if got := repo.created[0].ChunkType; got != types.ChunkTypeImageCaption {+ t.Errorf("persisted chunk type = %v, want the caption chunk", got)+ }+ if got := repo.created[0].Content; !strings.Contains(got, "A plain divider rule.") {+ t.Errorf("persisted caption chunk missing the description: %q", got)+ }+}++// TestProcessImageKeepsAttrsButDropsCaptionWhenCaptionsAreOff pins how the two+// whole-task switches compose in the attribute pipeline: the observe round is+// not optional, because the observation is what the OCR policy reads — but when+// captions are turned off the description that round produced must not be+// stored, or the switch would be a no-op on this path.+func TestProcessImageKeepsAttrsButDropsCaptionWhenCaptionsAreOff(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("chart-bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "OCR-TEXT", nil+ }+ return "contain.text: block\ncontain.data_visual: true\nDESCRIPTION: A bar chart of quarterly revenue.", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: false,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ attrs, ok := out["image_attrs"].(map[string]any)+ if !ok {+ t.Fatalf("image_attrs = %v, want the observed attribute map", out["image_attrs"])+ }+ if attrs["contain.data_visual"] != true {+ t.Errorf("contain.data_visual = %v, want true (needed even without captions)",+ attrs["contain.data_visual"])+ }+ if got := out["caption_skipped"]; got != "disabled" {+ t.Errorf("caption_skipped = %v, want disabled", got)+ }+ if got, present := out["caption_preview"]; present {+ t.Errorf("a caption must not be recorded when captions are off, got %v", got)+ }+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1 (data visual keeps OCR)", n)+ }+ if len(repo.created) != 1 {+ t.Fatalf("persisted chunks = %d, want the OCR chunk alone", len(repo.created))+ }+ if got := repo.created[0].ChunkType; got != types.ChunkTypeImageOCR {+ t.Errorf("persisted chunk type = %v, want the OCR chunk", got)+ }+}++// TestProcessImageProseAnswerIsStillCaptionedAndOCRed pins the safety half of+// the observation contract. A model that answers the question in prose, without+// the attribute protocol, has still described the image: the prose becomes the+// caption, no attribute is claimed, and the conservative clause decides OCR the+// safe way. A missed block of text costs more than one extra call.+func TestProcessImageProseAnswerIsStillCaptionedAndOCRed(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "OCR-TEXT", nil+ }+ // The model ignored the label protocol.+ return "Sure! Here is a picture of a pump.", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ attrs, _ := out["image_attrs"].(map[string]any)+ if len(attrs) != 0 {+ t.Errorf("image_attrs = %v, want nothing claimed for a prose answer", attrs)+ }+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1 (the conservative clause must not skip OCR)", n)+ }+ if _, skipped := out["ocr_skipped"]; skipped {+ t.Errorf("OCR must not be reported skipped, got %v", out["ocr_skipped"])+ }+ if got, ok := out["attr_policy"].(types.JSONMap); !ok || got["ocr"] != true {+ t.Errorf("attr_policy = %v, want the conservative decision", out["attr_policy"])+ }+ if _, missing := out["caption_missing"]; missing {+ t.Error("prose is a description: caption_missing must not be reported")+ }+ if len(repo.created) != 2 {+ t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))+ }+}++// TestProcessImageLabelOnlyAnswerKeepsAttrsWithoutCaption covers the one reply+// the parser reports as unusable: attributes and nothing else. The attributes+// are real information and are kept — they are what the OCR policy reads — but+// the raw reply must never become the caption, or "contain.text: block" ends up+// in the index as the image's description.+func TestProcessImageLabelOnlyAnswerKeepsAttrsWithoutCaption(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "OCR-TEXT", nil+ }+ // Truncated answer: the attributes arrived, the description never did.+ return "contain.text: block\ncontain.data_visual: true", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ if got := out["caption_missing"]; got != true {+ t.Errorf("caption_missing = %v, want true", got)+ }+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1 (block + data visual keep OCR)", n)+ }+ if len(repo.created) != 1 {+ t.Fatalf("persisted chunks = %d, want OCR only", len(repo.created))+ }+ if got := repo.created[0].ChunkType; got != types.ChunkTypeImageOCR {+ t.Errorf("persisted chunk type = %v, want the OCR chunk", got)+ }+ if got := repo.created[0].Content; strings.Contains(got, "contain.text") {+ t.Errorf("protocol line leaked into the index: %q", got)+ }+}++// TestProcessImageCaptionOCRPipeline pins the upstream behaviour the master+// switch falls back to (PipelineCaptionOCR): no attribute observation, the+// plain caption prompt, and OCR for every image regardless of any action policy.+func TestProcessImageCaptionOCRPipeline(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{body: []byte("bytes")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ fake.reply = func(prompt string, _ int) (string, error) {+ if strings.Contains(prompt, "OCR assistant") {+ return "PLAIN-OCR", nil+ }+ return "A pump on a bench.", nil+ }++ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: false,+ // An action table is present but must be ignored: caption+OCR mode has+ // no observation to feed it.+ ImageActions: types.DefaultImageActions(),+ }+ out := runProcessImage(t, svc, payload, fake)++ if n := countCallsWith(fake.calls, "contain.text:"); n != 0 {+ t.Errorf("caption+OCR mode must not observe, got %d observe call(s)", n)+ }+ if n := countCallsWith(fake.calls, "OCR assistant"); n != 1 {+ t.Errorf("OCR calls = %d, want 1 (caption+OCR mode OCRs every image)", n)+ }+ if _, present := out["image_attrs"]; present {+ t.Errorf("caption+OCR mode must not record attributes, got %v", out["image_attrs"])+ }+ if _, present := out["attr_policy"]; present {+ t.Errorf("caption+OCR mode must not evaluate an action policy, got %v", out["attr_policy"])+ }+ if len(repo.created) != 2 {+ t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))+ }+}++// TestProcessImageSkipsUnreadableImage checks that an unreadable object is+// reported and counted rather than failing the task.+func TestProcessImageSkipsUnreadableImage(t *testing.T) {+ t.Parallel()++ fileSvc := &attrsFileService{err: fmt.Errorf("object is gone")}+ repo := &attrsChunkRepo{}+ svc := newAttrsTestService(fileSvc, repo)++ fake := &attrsFakeVLM{}+ payload := &types.ImageMultimodalPayload{+ TenantID: 1,+ KnowledgeID: "k-1",+ KnowledgeBaseID: "kb-1",+ ImageURL: "local://img/0.png",+ ChunkID: "chunk-a",+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: true,+ ImageActions: types.DefaultImageActions(),+ }++ out := runProcessImage(t, svc, payload, fake)+ if got := out["skipped"]; got != "unreadable_image" {+ t.Errorf("skipped = %v, want unreadable_image", got)+ }+ if len(fake.calls) != 0 {+ t.Errorf("no VLM call should be made for an unreadable image, got %d", len(fake.calls))+ }+ if len(repo.created) != 0 {+ t.Errorf("no chunk should be persisted, got %d", len(repo.created))+ }+}diff --git a/internal/application/service/knowledge_process.go b/internal/application/service/knowledge_process.goindex 9cf4ad1b7..b3edb8d61 100644--- a/internal/application/service/knowledge_process.go+++ b/internal/application/service/knowledge_process.go@@ -792,10 +792,12 @@ func (s *knowledgeService) processChunks(ctx context.Context,// Enqueue multimodal tasks for images (async, non-blocking)if options.EnableMultimodel && len(options.StoredImages) > 0 {+ // Counts only, no policy claims: whether a given image is OCR'd is+ // decided per image once its attributes are observed, so a boolean here+ // would assert something the pipeline has not decided yet — and would+ // drift from what actually happened.s.beginStage(ctx, knowledge.ID, types.StageMultimodal, types.JSONMap{- "image_count": len(options.StoredImages),- "enable_ocr": true,- "enable_caption": true,+ "image_count": len(options.StoredImages),})s.enqueueImageMultimodalTasks(ctx, knowledge, kb, options.StoredImages, chunks, options.Metadata)} else {@@ -4155,6 +4157,13 @@ func (s *knowledgeService) enqueueImageMultimodalTasks(}}+ // Resolve the image pipeline settings once for the whole fan-out: the image+ // action policy and the pipeline switch travel with each task so the worker+ // needs no second config lookup, and so a task keeps the policy it was+ // enqueued with even if the knowledge base is reconfigured meanwhile.+ overrides, _ := knowledge.ProcessOverrides()+ eff := ResolveProcessConfig(kb, overrides)+enqueued := 0for idx, img := range images {// Match image to the ParsedChunk whose content contains the image URL.@@ -4171,17 +4180,19 @@ func (s *knowledgeService) enqueueImageMultimodalTasks(}payload := types.ImageMultimodalPayload{- TenantID: knowledge.TenantID,- KnowledgeID: knowledge.ID,- KnowledgeBaseID: kb.ID,- ChunkID: chunkID,- ImageURL: img.ServingURL,- EnableOCR: true,- EnableCaption: true,- Language: lang,- ImageSourceType: metadata["image_source_type"],- Attempt: attempt,- ImageIndex: idx,+ TenantID: knowledge.TenantID,+ KnowledgeID: knowledge.ID,+ KnowledgeBaseID: kb.ID,+ ChunkID: chunkID,+ ImageURL: img.ServingURL,+ EnableOCR: true,+ EnableCaption: true,+ ImageAttrsEnabled: eff.ImageAttrsEnabled,+ ImageActions: eff.ImageActions,+ Language: lang,+ ImageSourceType: metadata["image_source_type"],+ Attempt: attempt,+ ImageIndex: idx,}langfuse.InjectTracing(ctx, &payload)diff --git a/internal/application/service/knowledge_process_config.go b/internal/application/service/knowledge_process_config.goindex b50fa815c..0137d55f2 100644--- a/internal/application/service/knowledge_process_config.go+++ b/internal/application/service/knowledge_process_config.go@@ -38,6 +38,7 @@ func normalizeParserFileType(fileType string) string {// ResolveProcessConfig merges KB defaults with per-upload overrides for the parse pipeline.func ResolveProcessConfig(kb *types.KnowledgeBase, overrides *types.KnowledgeProcessOverrides) types.EffectiveProcessConfig {+ imageCfg := kb.ImageProcessingConfigeff := types.EffectiveProcessConfig{SummaryEnabled: true,ChunkingConfig: kb.ChunkingConfig,@@ -47,6 +48,8 @@ func ResolveProcessConfig(kb *types.KnowledgeBase, overrides *types.KnowledgeProQuestionGenerationConfig: defaultQuestionGenerationConfig(kb),GraphEnabled: kb.IsGraphEnabled(),ExtractConfig: derefExtractConfig(kb.ExtractConfig),+ ImageAttrsEnabled: imageCfg.ImageAttrsEnabled,+ ImageActions: types.ResolveImageActions(imageCfg.ImageActions),}if overrides == nil {return eff@@ -87,6 +90,20 @@ func ResolveProcessConfig(kb *types.KnowledgeBase, overrides *types.KnowledgeProif overrides.GraphEnabled != nil {eff.GraphEnabled = *overrides.GraphEnabled}+ if overrides.ImageAttrsEnabled != nil {+ eff.ImageAttrsEnabled = *overrides.ImageAttrsEnabled+ }+ if overrides.ImageActions != nil {+ base := eff.ImageActions+ // Same rule as types.MergeImageActions: the OCR clause is a unit keyed+ // on a non-empty On. OnUnobserved is a plain bool, so an override that+ // omits On cannot tell "false" from "unset" and is ignored rather than+ // flipping the conservative default.+ if len(overrides.ImageActions.OCR.On) > 0 {+ base.OCR = overrides.ImageActions.OCR+ }+ eff.ImageActions = base+ }if overrides.ExtractConfig != nil {eff.ExtractConfig = mergeExtractConfig(eff.ExtractConfig, overrides.ExtractConfig)}diff --git a/internal/application/service/knowledge_process_config_test.go b/internal/application/service/knowledge_process_config_test.goindex 24f664461..e522f3d20 100644--- a/internal/application/service/knowledge_process_config_test.go+++ b/internal/application/service/knowledge_process_config_test.go@@ -59,6 +59,31 @@ func TestResolveProcessConfig_OverrideTogglesParentChild(t *testing.T) {require.True(t, effOn.ChunkingConfig.EnableParentChild)}+// The attribute-observed pipeline switch follows the knowledge base until a+// single upload overrides it, either way. The default is off: a knowledge base+// that never heard of attribute observation keeps describing and OCR-ing every+// image exactly as it did before the pipeline existed.+func TestResolveProcessConfig_ImageAttrsOverride(t *testing.T) {+ t.Parallel()++ kbOff := &types.KnowledgeBase{}+ kbOn := &types.KnowledgeBase{}+ kbOn.ImageProcessingConfig.ImageAttrsEnabled = true++ require.False(t, ResolveProcessConfig(kbOff, nil).ImageAttrsEnabled,+ "attribute observation must be off for a knowledge base that never enabled it")+ require.True(t, ResolveProcessConfig(kbOn, nil).ImageAttrsEnabled,+ "the knowledge base's switch must survive a nil override")++ require.True(t, ResolveProcessConfig(kbOff, &types.KnowledgeProcessOverrides{+ ImageAttrsEnabled: processConfigBoolPtr(true),+ }).ImageAttrsEnabled, "a single upload must be able to turn attribute observation on")++ require.False(t, ResolveProcessConfig(kbOn, &types.KnowledgeProcessOverrides{+ ImageAttrsEnabled: processConfigBoolPtr(false),+ }).ImageAttrsEnabled, "a single upload must be able to turn attribute observation off")+}+func TestResolveProcessConfig_GraphDisabled(t *testing.T) {t.Parallel()@@ -526,6 +551,58 @@ func TestBuildParentChildConfigs_PropagatesStrategy(t *testing.T) {require.Equal(t, base.Separators, child.Separators)}+// A knowledge base can override the OCR action wholesale, and a single upload+// can override it again on top of what the knowledge base already decided. The+// built-in action table is complete, so a knowledge base that only flips one+// condition stays a small configuration.+func TestResolveProcessConfig_ImageActionsOverride(t *testing.T) {+ t.Parallel()++ kbActions := &types.ImageActionsConfig{+ OCR: types.ImageOCRAction{+ On: []types.ImageAttrCondition{+ {Prop: "contain.text", Is: "block"},+ {Prop: "contain.data_visual", Is: "true"},+ },+ OnUnobserved: false,+ },+ }+ kb := &types.KnowledgeBase{+ ImageProcessingConfig: types.ImageProcessingConfig{+ ImageAttrsEnabled: true,+ ImageActions: kbActions,+ },+ }++ // nil override: the knowledge base's custom action wins.+ eff := ResolveProcessConfig(kb, nil)+ require.True(t, eff.ImageAttrsEnabled)+ require.False(t, eff.ImageActions.OCR.OnUnobserved,+ "the knowledge base's action must override the built-in default")++ // An upload override rewrites the OCR action wholesale: the knowledge+ // base's OnUnobserved=false is replaced by the upload's true.+ eff = ResolveProcessConfig(kb, &types.KnowledgeProcessOverrides{+ ImageActions: &types.ImageActionsConfig{+ OCR: types.ImageOCRAction{+ On: []types.ImageAttrCondition{{Prop: "contain.text", Is: "block"}},+ OnUnobserved: true,+ },+ },+ })+ require.True(t, eff.ImageActions.OCR.OnUnobserved,+ "an upload action override must replace the whole OCR action, not merge")+ require.Len(t, eff.ImageActions.OCR.On, 1,+ "the upload's OCR.On replaces the knowledge base's list")++ // With neither a KB config nor an override, the resolved action is the+ // complete built-in default.+ eff = ResolveProcessConfig(&types.KnowledgeBase{}, nil)+ require.Equal(t, types.DefaultImageActions(), eff.ImageActions,+ "the resolved action table must stay complete with no input")+ require.False(t, eff.ImageAttrsEnabled)+}+func TestResolveProcessConfig_SummaryEnabled(t *testing.T) {kb := &types.KnowledgeBase{}require.True(t, ResolveProcessConfig(kb, nil).SummaryEnabled)diff --git a/internal/application/service/knowledgebase.go b/internal/application/service/knowledgebase.goindex a7f1f6254..977166722 100644--- a/internal/application/service/knowledgebase.go+++ b/internal/application/service/knowledgebase.go@@ -531,7 +531,11 @@ func (s *knowledgeBaseService) UpdateKnowledgeBase(ctx context.Context,kb.Description = descriptionif config != nil {kb.ChunkingConfig = config.ChunkingConfig- kb.ImageProcessingConfig = config.ImageProcessingConfig+ // Replaced only when the request carried one, so a caller that does not+ // know about the image settings cannot wipe them.+ if config.ImageProcessingConfig != nil {+ kb.ImageProcessingConfig = *config.ImageProcessingConfig+ }if config.FAQConfig != nil {kb.FAQConfig = config.FAQConfig}diff --git a/internal/application/service/knowledgebase_image_config_test.go b/internal/application/service/knowledgebase_image_config_test.gonew file mode 100644index 000000000..ddef0dc4b--- /dev/null+++ b/internal/application/service/knowledgebase_image_config_test.go@@ -0,0 +1,90 @@+package service++import (+ "testing"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// imageConfiguredKB is a knowledge base whose image settings have been filled+// in: the attribute-observed pipeline is on and the action table carries a value+// that differs from the built-in default, so a reset is visible.+func imageConfiguredKB() *types.KnowledgeBase {+ // OnUnobserved=false is distinguishable from the built-in true, so the test+ // can tell a preserved custom table from a re-applied default.+ customActions := &types.ImageActionsConfig{+ OCR: types.ImageOCRAction{+ On: []types.ImageAttrCondition{+ {Prop: "contain.text", Is: "block"},+ {Prop: "contain.data_visual", Is: "true"},+ },+ OnUnobserved: false,+ },+ }+ return &types.KnowledgeBase{+ ID: "kb-1",+ TenantID: 1,+ Name: "before",+ Type: types.KnowledgeBaseTypeDocument,+ ImageProcessingConfig: types.ImageProcessingConfig{+ ModelID: "vlm-image",+ ImageAttrsEnabled: true,+ ImageActions: customActions,+ },+ }+}++// A request that does not mention image_processing_config must leave the image+// settings alone. Clients that predate the attribute pipeline send no such+// field at all, and without this contract saving such a knowledge base silently+// resets the switch and the action table — which turns "rename a knowledge base"+// into data loss.+func TestUpdateKnowledgeBase_KeepsImageConfigWhenRequestOmitsIt(t *testing.T) {+ t.Parallel()++ repo := newFakeKBRepo()+ svc := newPR3KBService(repo, &fakeRegistry{registered: map[string]struct{}{}}, &fakeOwnership{})+ stored := imageConfiguredKB()+ repo.rows[stored.ID] = stored++ // The whole config is present but the image section is absent — this is the+ // shape every existing client sends.+ updated, err := svc.UpdateKnowledgeBase(ctxWithTenant(1), stored.ID, "renamed", "desc",+ &types.KnowledgeBaseConfig{})+ require.NoError(t, err)++ got := updated.ImageProcessingConfig+ assert.Equal(t, "vlm-image", got.ModelID, "image model was reset")+ assert.True(t, got.ImageAttrsEnabled, "the attribute switch was reset")+ require.NotNil(t, got.ImageActions, "image actions were reset")+ assert.False(t, got.ImageActions.OCR.OnUnobserved, "image action contents were reset")++ // The fields the request did carry still land.+ assert.Equal(t, "renamed", updated.Name)+ assert.Equal(t, "desc", updated.Description)+}++// Sending the object replaces the configuration wholesale, empty included —+// that is how a caller clears the settings on purpose. Pinned so the+// nil-means-unchanged rule is not mistaken for a merge.+func TestUpdateKnowledgeBase_ReplacesImageConfigWhenRequestCarriesIt(t *testing.T) {+ t.Parallel()++ repo := newFakeKBRepo()+ svc := newPR3KBService(repo, &fakeRegistry{registered: map[string]struct{}{}}, &fakeOwnership{})+ stored := imageConfiguredKB()+ repo.rows[stored.ID] = stored++ updated, err := svc.UpdateKnowledgeBase(ctxWithTenant(1), stored.ID, stored.Name, stored.Description,+ &types.KnowledgeBaseConfig{+ ImageProcessingConfig: &types.ImageProcessingConfig{ModelID: "vlm-image-2"},+ })+ require.NoError(t, err)++ got := updated.ImageProcessingConfig+ assert.Equal(t, "vlm-image-2", got.ModelID)+ assert.False(t, got.ImageAttrsEnabled, "an explicit object replaces the whole configuration, it does not merge")+ assert.Nil(t, got.ImageActions)+}diff --git a/internal/application/service/system_setting.go b/internal/application/service/system_setting.goindex 604366e92..3edd34b62 100644--- a/internal/application/service/system_setting.go+++ b/internal/application/service/system_setting.go@@ -161,6 +161,24 @@ var registry = map[string]settingSpec{Description: "是否启用复杂密码。开启后密码必须包含大小写字母、数字和特殊字符。" +"修改后立即生效,只影响新注册用户或新密码修改/重置操作。特殊字符包含:!@#$%^&*()_+-=[]{}|;:,.<>?",},+ // gallery.policy is the platform-wide image-gallery attribute policy:+ // a JSON document (types.GalleryPolicyTier) that can toggle attribute+ // sources and override per-attribute usage flags (in_filter /+ // in_searchfield / in_sortfield) on top of what the sources declare.+ // Read on every gallery request — edits take effect on the next gallery+ // page load, no restart. Empty string = no overrides (use source+ // declarations as-is). See types.ResolveGalleryConfig for the merge+ // semantics (user > KB > system > source).+ "gallery.policy": {+ Type: "string",+ EnvName: "",+ Default: "",+ Category: "gallery",+ Description: "图库属性策略(JSON,可选)。可启停属性来源(sources)或按属性 ID 覆盖用法" ++ "(overrides,字段级:in_filter / in_searchfield / in_sortfield),例如:" ++ "{\"overrides\":{\"system:contain.text\":{\"in_searchfield\":true}}}。" ++ "留空 = 完全使用来源端声明。修改后立即生效,刷新图库页可见。",+ },// tenant.max_owned_per_user caps how many tenants a single non-superuser// can create (and Own) via self-service POST /tenants. Read on every// request — UI edits take effect immediately, no restart required. Thediff --git a/internal/application/service/user.go b/internal/application/service/user.goindex ef3bd388d..bdbd49547 100644--- a/internal/application/service/user.go+++ b/internal/application/service/user.go@@ -653,6 +653,31 @@ func (s *userService) UpdateUserPreferences(merged.LastActiveTenantID = &v}}+ if patch.Gallery != nil {+ // Whole-object replace per key: the gallery sends its complete+ // current state (mode + full status map) on every change, so there+ // is no meaningful partial-merge within the block. Values are+ // clamped so a stray client cannot bloat the column or poison the+ // mode.+ g := merged.Gallery+ if g == nil {+ g = &types.GalleryUserPrefs{}+ }+ if patch.Gallery.Mode == types.GalleryModeAll || patch.Gallery.Mode == types.GalleryModeCustom {+ g.Mode = patch.Gallery.Mode+ }+ if patch.Gallery.Status != nil {+ status := make(map[string]string, len(patch.Gallery.Status))+ for id, v := range patch.Gallery.Status {+ if (v == types.GalleryStatusOn || v == types.GalleryStatusOff) &&+ len(id) <= 128 && len(status) < 200 {+ status[id] = v+ }+ }+ g.Status = status+ }+ merged.Gallery = g+ }user.Preferences = mergeduser.UpdatedAt = time.Now()diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.goindex 42d384711..073e53037 100644--- a/internal/database/migration_sqlite_versioned_schema_test.go+++ b/internal/database/migration_sqlite_versioned_schema_test.go@@ -22,6 +22,7 @@ var versionedSQLiteTables = []string{"task_dead_letters","system_settings","model_catalog_configs",+ "chunk_images","knowledge_processing_spans","knowledge_tag_relations","browser_devices",@@ -67,7 +68,7 @@ var versionedSQLiteColumns = map[string][]string{}, // 000028}-const expectedSQLiteMigrationVersion = 31+const expectedSQLiteMigrationVersion = 32func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {repoRoot := sqliteRepoRoot(t)diff --git a/internal/handler/knowledge.go b/internal/handler/knowledge.goindex 8df5431ba..c675cffac 100644--- a/internal/handler/knowledge.go+++ b/internal/handler/knowledge.go@@ -34,6 +34,9 @@ type KnowledgeHandler struct {kbService interfaces.KnowledgeBaseServicekbShareService interfaces.KBShareServiceagentShareService interfaces.AgentShareService+ chunkService interfaces.ChunkService+ systemSettingSvc interfaces.SystemSettingService+ userSvc interfaces.UserServiceasynqClient interfaces.TaskEnqueuerspanRepo repository.KnowledgeSpanRepositorybacklog backlogProbe@@ -79,6 +82,9 @@ func NewKnowledgeHandler(kbService interfaces.KnowledgeBaseService,kbShareService interfaces.KBShareService,agentShareService interfaces.AgentShareService,+ chunkService interfaces.ChunkService,+ systemSettingSvc interfaces.SystemSettingService,+ userSvc interfaces.UserService,asynqClient interfaces.TaskEnqueuer,spanRepo repository.KnowledgeSpanRepository,housekeeping *service.HousekeepingService,@@ -94,6 +100,9 @@ func NewKnowledgeHandler(kbService: kbService,kbShareService: kbShareService,agentShareService: agentShareService,+ chunkService: chunkService,+ systemSettingSvc: systemSettingSvc,+ userSvc: userSvc,asynqClient: asynqClient,spanRepo: spanRepo,}@@ -1104,6 +1113,234 @@ func (h *KnowledgeHandler) ListKnowledge(c *gin.Context) {})}+// ListImages lists the image assets of a knowledge base for the gallery view.+//+// @Summary 列出知识库图片资产+// @Description 浏览某知识库内的全部图片资产,支持关键字搜索(caption/OCR 文本)、按图片属性筛选(attr_filters / attr_rules)与排序分页。+// @Tags knowledge+// @Accept json+// @Produce json+// @Param id path string true "知识库 ID"+// @Param page query int false "页码,默认 1"+// @Param page_size query int false "每页数量,默认 20,最大 1000"+// @Param keyword query string false "关键字,对 search_in 指定字段做不区分大小写的子串匹配"+// @Param search_in query string false "参与搜索的属性 ID(逗号分隔);须为 in_searchfield=true"+// @Param sort_by query string false "排序属性 ID;须为 in_sortfield=true,默认 created_at"+// @Param sort_order query string false "排序方向:asc / desc,默认 desc"+// @Param is_enabled query bool false "仅包含启用状态的图片"+// @Param attr_filters query string false "属性筛选 JSON,同一属性多值 OR、属性间 AND"+// @Param attr_rules query string false "属性逐值裁决 JSON(off 隐藏 / on 强制显示,on 优先)"+// @Success 200 {object} map[string]interface{} "图片资产分页列表"+// @Failure 400 {object} errors.AppError "请求参数错误"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /knowledge-bases/{id}/images [get]+func (h *KnowledgeHandler) ListImages(c *gin.Context) {+ _, kbID, effectiveTenantID, _, err := h.validateKnowledgeBaseAccess(c)+ if err != nil {+ _ = c.Error(err)+ return+ }+ ctx := types.WithExecutionTenant(c.Request.Context(), effectiveTenantID)++ var pagination types.Pagination+ if err := c.ShouldBindQuery(&pagination); err != nil {+ logger.Error(ctx, "Failed to parse pagination parameters", err)+ _ = c.Error(errors.NewBadRequestError(err.Error()))+ return+ }++ filter := &types.ImageListFilter{+ Keyword: strings.TrimSpace(c.Query("keyword")),+ SortBy: strings.TrimSpace(c.Query("sort_by")),+ SortOrder: c.DefaultQuery("sort_order", "desc"),+ }+ if v := c.Query("is_enabled"); v != "" {+ enabled := v == "true"+ filter.IsEnabled = &enabled+ }++ // Every gallery attribute reference is validated against the resolved+ // contract: a client may only search / sort / filter on fields whose+ // usage flags allow it, so stale or hand-rolled callers cannot smuggle+ // in fields the configuration no longer serves.+ resolved := h.resolveGalleryConfig(ctx, kbID)+ filterable, searchable, sortable := galleryEligibility(resolved)++ // Attribute filters arrive as one JSON object keyed by namespaced+ // attribute id ({"system:contain.text":["block"]}); values within one+ // attribute are OR-ed, attributes are AND-ed.+ if raw := c.Query("attr_filters"); raw != "" {+ var attrFilters map[string][]string+ if err := json.Unmarshal([]byte(raw), &attrFilters); err == nil && len(attrFilters) > 0 {+ kept := make(map[string][]string, len(attrFilters))+ for id, values := range attrFilters {+ if filterable[id] && len(values) > 0 {+ kept[id] = values+ }+ }+ if len(kept) > 0 {+ filter.AttrFilters = kept+ }+ }+ }++ // Attribute rules arrive as one JSON object keyed by namespaced+ // attribute id, each holding a verdict per value+ // ({"system:contain.text":{"block":"on","none":"off"}}). Only values+ // the image actually carries take part; see AttrRules for the+ // precedence between "on" and "off".+ if raw := c.Query("attr_rules"); raw != "" {+ var attrRules map[string]map[string]string+ if err := json.Unmarshal([]byte(raw), &attrRules); err == nil && len(attrRules) > 0 {+ kept := make(map[string]map[string]string, len(attrRules))+ for id, verdicts := range attrRules {+ if !filterable[id] || len(verdicts) == 0 {+ continue+ }+ clean := make(map[string]string, len(verdicts))+ for value, verdict := range verdicts {+ switch verdict {+ case "off", "on":+ clean[value] = verdict+ }+ }+ if len(clean) > 0 {+ kept[id] = clean+ }+ }+ if len(kept) > 0 {+ filter.AttrRules = kept+ }+ }+ }++ // search_in: comma-separated namespaced attribute ids; ineligible ids+ // are dropped, and an empty remainder falls back to the service default+ // (builtin caption + ocr_text).+ if raw := strings.TrimSpace(c.Query("search_in")); raw != "" {+ var searchIn []string+ for _, id := range strings.Split(raw, ",") {+ id = strings.TrimSpace(id)+ if id != "" && searchable[id] {+ searchIn = append(searchIn, id)+ }+ }+ filter.SearchIn = searchIn+ }++ // sort_by must be sort-eligible; anything else falls back to the+ // service default (builtin created_at, descending).+ if filter.SortBy != "" && !sortable[filter.SortBy] {+ filter.SortBy = ""+ }++ result, err := h.chunkService.ListImagesByKnowledgeBaseID(ctx, kbID, &pagination, filter)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"kb_id": kbID})+ _ = c.Error(errors.NewInternalServerError(err.Error()))+ return+ }++ c.JSON(http.StatusOK, gin.H{+ "success": true,+ "data": result.Data,+ "total": result.Total,+ "page": result.Page,+ "page_size": result.PageSize,+ })+}++// galleryEligibility extracts the per-attribute usage sets that incoming+// query parameters are validated against, keyed by namespaced attribute id.+func galleryEligibility(resolved *types.GalleryResolvedConfig) (filterable, searchable, sortable map[string]bool) {+ filterable = map[string]bool{}+ searchable = map[string]bool{}+ sortable = map[string]bool{}+ if resolved == nil {+ return+ }+ for _, attr := range resolved.Attributes {+ if attr.Usage.InFilter {+ filterable[attr.ID] = true+ }+ if attr.Usage.InSearchField {+ searchable[attr.ID] = true+ }+ if attr.Usage.InSortField {+ sortable[attr.ID] = true+ }+ }+ return+}++// resolveGalleryConfig merges the gallery configuration tiers for one+// request: the system tier from system_settings ("gallery.policy"), the user+// tier from the caller's saved preferences. The KB tier slot is reserved for+// the per-KB config (not wired yet — the merge engine already accepts it).+// A missing or malformed tier degrades to "no overrides", never to an error:+// the gallery must render even on a half-configured deployment.+func (h *KnowledgeHandler) resolveGalleryConfig(ctx context.Context, kbID string) *types.GalleryResolvedConfig {+ var systemTier *types.GalleryPolicyTier+ if h.systemSettingSvc != nil {+ if row, err := h.systemSettingSvc.Get(ctx, "gallery.policy"); err == nil && row != nil {+ if raw, err := row.AsString(); err == nil && strings.TrimSpace(raw) != "" {+ tier := &types.GalleryPolicyTier{}+ if err := json.Unmarshal([]byte(raw), tier); err == nil {+ systemTier = tier+ } else {+ logger.Warnf(ctx, "gallery.policy is not valid JSON; ignoring: %v", err)+ }+ }+ }+ }++ var userTier *types.GalleryPolicyTier+ if h.userSvc != nil {+ if userID, ok := types.UserIDFromContext(ctx); ok && userID != "" {+ if u, err := h.userSvc.GetUserByID(ctx, userID); err == nil && u != nil && u.Preferences.Gallery != nil {+ g := u.Preferences.Gallery+ userTier = &types.GalleryPolicyTier{Mode: g.Mode, Status: g.Status}+ }+ }+ }++ return types.ResolveGalleryConfig(kbID, systemTier, nil, userTier)+}++// GetGalleryConfig serves the gallery's self-describing contract: which+// attribute sources are live, every resolved attribute (definition + merged+// usage + which tier decided it), and the caller's search activation state+// (mode + per-field status). The frontend renders its filter panel, search+// field checkboxes and sort dropdown purely from this response — no gallery+// UI rule is hardcoded client-side.+func (h *KnowledgeHandler) GetGalleryConfig(c *gin.Context) {+ ctx := c.Request.Context()++ _, kbID, effectiveTenantID, _, err := h.validateKnowledgeBaseAccess(c)+ if err != nil {+ _ = c.Error(err)+ return+ }+ ctx = types.WithExecutionTenant(ctx, effectiveTenantID)++ resolved := h.resolveGalleryConfig(ctx, kbID)+ status := resolved.Status+ if status == nil {+ status = map[string]string{}+ }++ c.JSON(http.StatusOK, gin.H{+ "success": true,+ "data": gin.H{+ "attribute_sources": resolved.AttributeSources,+ "attributes": resolved.Attributes,+ "mode": resolved.Mode,+ "status": status,+ },+ })+}+// ListKnowledgeFolders godoc// @Summary 获取知识库文件夹目录树// @Description 返回知识库内由文件夹上传形成的目录树,包含每个文件夹的直接文档数与含子目录的总数diff --git a/internal/handler/knowledgebase.go b/internal/handler/knowledgebase.goindex 38878415c..9db3ed2a6 100644--- a/internal/handler/knowledgebase.go+++ b/internal/handler/knowledgebase.go@@ -778,10 +778,12 @@ func (h *KnowledgeBaseHandler) UpdateKnowledgeBase(c *gin.Context) {}if req.Config != nil {probe := &types.KnowledgeBase{- ChunkingConfig: req.Config.ChunkingConfig,- ImageProcessingConfig: req.Config.ImageProcessingConfig,- WikiConfig: req.Config.WikiConfig,- ProfileConfig: req.Config.ProfileConfig,+ ChunkingConfig: req.Config.ChunkingConfig,+ WikiConfig: req.Config.WikiConfig,+ ProfileConfig: req.Config.ProfileConfig,+ }+ if req.Config.ImageProcessingConfig != nil {+ probe.ImageProcessingConfig = *req.Config.ImageProcessingConfig}if err := validateKnowledgeBasePromptInstructions(probe); err != nil {c.Error(err)@@ -1331,3 +1333,22 @@ func (h *KnowledgeBaseHandler) ListMoveTargets(c *gin.Context) {"data": targets,})}++// GetImageAttrsSchema returns the canonical image-attribute registry for this+// release. It is the single source of truth that drives the frontend attribute+// panel — both the attributes and their display text (label, description, the+// meaning of each value) — so adding an attribute later is a backend-only+// change (one registry row) and the UI follows automatically. Read-only; the+// registry is global, not per-KB, so it carries no KB id and only the Viewer+// role is required.+func (h *KnowledgeBaseHandler) GetImageAttrsSchema(c *gin.Context) {+ c.JSON(http.StatusOK, gin.H{+ "success": true,+ "data": gin.H{+ "version": types.ImageAttrSchemaVersion,+ "prompt": types.ImageAttrPromptVersion,+ "attributes": types.ImageAttrRegistry,+ "default_actions": types.DefaultImageActions(),+ },+ })+}diff --git a/internal/router/router.go b/internal/router/router.goindex 1451b3c51..e346c2673 100644--- a/internal/router/router.go+++ b/internal/router/router.go@@ -260,6 +260,7 @@ func NewRouter(params RouterParams) *gin.Engine {RegisterTenantRoutes(v1, params.TenantHandler, params.TenantMemberHandler, params.TenantInvitationHandler, params.AuditLogHandler, rbacGuards)RegisterMyInvitationRoutes(v1, params.TenantInvitationHandler)RegisterKnowledgeBaseRoutes(v1, params.KBHandler, rbacGuards)+ RegisterImageAttrRoutes(v1, params.KBHandler, rbacGuards)RegisterKnowledgeBaseActivityRoutes(v1, params.AuditLogHandler, rbacGuards)// KB-scoped image proxy: lets tenants render images embedded in// org-shared / agent-visible KB content, which the tenant-scopeddiff --git a/internal/router/routes_knowledge.go b/internal/router/routes_knowledge.goindex ff8e7e3bf..c9e9acb64 100644--- a/internal/router/routes_knowledge.go+++ b/internal/router/routes_knowledge.go@@ -83,6 +83,20 @@ func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandlkb.With(apiKeyFullAccess()).DELETE("", g.Admin(), g.KBAccessWrite("id"), handler.ClearKnowledgeBaseContents)}+ // Image gallery: list every image asset of a KB (read-only, Viewer+).+ // Lives directly under /knowledge-bases/:id so it parallels /knowledge,+ // /faq and /tags rather than nesting under /knowledge (documents).+ kbImages := g.apiKeyGroup(r.Group("/knowledge-bases/:id"), apiKeyRetrieve(apiKeyFullAccess()))+ kbImagesRead := kbImages.With(apiKeyRetrieve(apiKeyFullAccess()))+ {+ kbImagesRead.GET("/images", g.Viewer(), g.KBAccessRead("id"), handler.ListImages)+ // Self-describing gallery contract: live attribute sources, the+ // resolved attribute list (definitions + merged usage) and the+ // caller's search activation state. Per-KB because KB-defined+ // attribute sources resolve against :id.+ kbImagesRead.GET("/gallery-config", g.Viewer(), g.KBAccessRead("id"), handler.GetGalleryConfig)+ }+// 知识路由组(URL :id is a knowledge id; the guard walks it to the parent KB)kgrp := r.Group("/knowledge")k := g.apiKeyGroup(kgrp, apiKeyIngest(apiKeyFullAccess()))@@ -250,6 +264,20 @@ func RegisterKnowledgeBaseRoutes(r *gin.RouterGroup, handler *handler.KnowledgeB}}+// RegisterImageAttrRoutes wires the global, read-only image-attribute registry+// that drives the KB editor's attribute panel.+//+// The registry is a single source of truth, so adding an attribute is a+// backend-only change (one registry row) and the UI follows automatically. It+// carries no KB id and needs only the Viewer role, so — like the other+// read-only KB-editor helpers GET /chunker/preview and GET+// /system/parser-engines — it is mounted at the top level rather than under+// the /knowledge-bases collection.+func RegisterImageAttrRoutes(r *gin.RouterGroup, handler *handler.KnowledgeBaseHandler, g *rbacGuards) {+ g.apiKeyRoute(r, http.MethodGet, "/image-attrs/schema",+ apiKeyRetrieve(apiKeyFullAccess()), g.Viewer(), handler.GetImageAttrsSchema)+}+// RegisterKnowledgeBaseActivityRoutes exposes the read-only per-KB activity// feed. It intentionally stays JWT-only: audit history is a sensitive owner// surface and no existing workspace API-key capability grants audit access.diff --git a/internal/types/chunk.go b/internal/types/chunk.goindex 72196d2ef..1651aec25 100644--- a/internal/types/chunk.go+++ b/internal/types/chunk.go@@ -96,6 +96,12 @@ type ImageInfo struct {Caption string `json:"caption"`// 图片OCR文本OCRText string `json:"ocr_text"`+ // Attrs 是描述轮给出的图片属性观察结果(取值见 ImageAttrs / ImageAttrRegistry)。+ // 只记录模型确实回答了的属性:观察失败或取值非法的属性不会写入默认值,而是直接缺键,+ // 因此读取方必须用 ImageAttrs.Observed 区分「未观察到」与「观察到了负值」。+ // 该字段以 JSON 存储在 chunks.image_info 中,无需迁移;属性观察能力上线前写入的+ // 行会缺省为空,读取方必须容忍空值。+ Attrs ImageAttrs `json:"attrs,omitempty"`}// VideoInfo 表示与 Chunk 关联的视频信息diff --git a/internal/types/gallery_attr_source.go b/internal/types/gallery_attr_source.gonew file mode 100644index 000000000..898a31c0a--- /dev/null+++ b/internal/types/gallery_attr_source.go@@ -0,0 +1,149 @@+package types++import (+ "regexp"+ "sync"+)++// GalleryUsage declares how the image gallery may use one attribute. It is+// the "eligibility" layer: an attribute only appears in the gallery UI+// section (filter panel / search-field checkboxes / sort dropdown) that its+// usage flags allow. Whether a search field is actually active is decided+// separately by the user-level status layer, never here.+type GalleryUsage struct {+ // InFilter marks the attribute as renderable in the filter panel.+ InFilter bool `json:"in_filter"`+ // InSearchField marks the attribute as selectable in the search-field+ // checkboxes (the user still chooses per field whether to search it).+ InSearchField bool `json:"in_searchfield"`+ // InSortField marks the attribute as an option in the sort dropdown.+ InSortField bool `json:"in_sortfield"`+}++// GalleryAttrValue is one allowed value of an attribute together with the+// words to show for it. A value carries two pieces of text on purpose:+// Label is the short name that goes on screen (a filter checkbox, a search+// field, a sort option), while Description holds the longer explanation that+// would blow a compact control apart if it were shown inline. Callers pick+// the one they need — the filter panel renders Label and moves Description+// into a tooltip, the detail panel can show both.+//+// Value stays the raw machine value: it is what gets filtered, searched and+// stored in image_info, and it must never be localized.+type GalleryAttrValue struct {+ // Value is the raw string the attribute can hold.+ Value string `json:"value"`+ // Label is the short, on-screen name for this value.+ Label string `json:"label"`+ // Description explains the value in a sentence; empty when the source+ // has nothing more to say.+ Description string `json:"description,omitempty"`+}++// GalleryAttrDef is one gallery-consumable attribute as a source declares+// it. Name is source-local (unprefixed); the gallery namespaces it under the+// declaring source's id when it builds the contract (see GalleryAttrID).+// Type drives frontend rendering: "text" (substring search), "date",+// "extent" (ordered value set -> multi-select), "presence" (boolean ->+// true/false checkboxes) and "keywords" (array of tags -> tag search).+//+// Like values, the attribute itself carries a short Label for the UI and a+// longer Description for wherever there is room for a sentence.+type GalleryAttrDef struct {+ Name string `json:"name"`+ Type string `json:"type"`+ Values []GalleryAttrValue `json:"values,omitempty"`+ Label string `json:"label"`+ Description string `json:"description,omitempty"`+ Usage GalleryUsage `json:"usage"`+}++// GalleryAttrSource is the aggregated view of one registered attribute+// source: the source id plus the attributes it provides for a KB.+type GalleryAttrSource struct {+ ID string `json:"id"`+ Attrs []GalleryAttrDef `json:"attrs"`+}++// gallerySourceIDPattern constrains source ids so the namespaced attribute+// id "<sourceID>:<name>" stays unambiguous (the separator is ":").+var gallerySourceIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)++var (+ galleryAttrSourcesMu sync.RWMutex+ galleryAttrSources []galleryAttrSourceEntry+)++type galleryAttrSourceEntry struct {+ id string+ // fn resolves the attributes the source provides for a KB. kbID lets a+ // future per-KB source (e.g. KB-defined attributes) contribute; global+ // sources ignore it.+ fn func(kbID string) []GalleryAttrDef+}++// RegisterGalleryAttrSource adds an attribute source to the gallery's open+// registry. Registration order is priority order: when two sources declare+// the same source-local attribute name, the namespaced ids keep both alive+// ("system:keyword" vs "kb:keyword"), and earlier-registered sources win+// raw-key lookups on tie. Call from init(); a nil fn or a malformed /+// duplicate id is a programming error and panics loudly.+func RegisterGalleryAttrSource(id string, fn func(kbID string) []GalleryAttrDef) {+ if fn == nil || !gallerySourceIDPattern.MatchString(id) {+ panic("gallery: invalid attribute source registration (id=" + id + ")")+ }+ galleryAttrSourcesMu.Lock()+ defer galleryAttrSourcesMu.Unlock()+ for _, e := range galleryAttrSources {+ if e.id == id {+ panic("gallery: duplicate attribute source id: " + id)+ }+ }+ galleryAttrSources = append(galleryAttrSources, galleryAttrSourceEntry{id: id, fn: fn})+}++// GalleryAttrSources resolves every registered source for a KB, in+// registration (priority) order. A source returning nothing yields an empty+// attribute list, not an error — an absent source is a normal state (e.g.+// the system attribute pipeline not deployed).+func GalleryAttrSources(kbID string) []GalleryAttrSource {+ galleryAttrSourcesMu.RLock()+ defer galleryAttrSourcesMu.RUnlock()+ out := make([]GalleryAttrSource, 0, len(galleryAttrSources))+ for _, e := range galleryAttrSources {+ defs := e.fn(kbID)+ if defs == nil {+ defs = []GalleryAttrDef{}+ }+ out = append(out, GalleryAttrSource{ID: e.id, Attrs: defs})+ }+ return out+}++// GalleryAttrSourceIDs lists the registered source ids in priority order.+func GalleryAttrSourceIDs() []string {+ galleryAttrSourcesMu.RLock()+ defer galleryAttrSourcesMu.RUnlock()+ out := make([]string, 0, len(galleryAttrSources))+ for _, e := range galleryAttrSources {+ out = append(out, e.id)+ }+ return out+}++// GalleryAttrID joins a source id and a source-local attribute name into the+// namespaced id used across the gallery contract and every config tier.+func GalleryAttrID(sourceID, name string) string {+ return sourceID + ":" + name+}++// SplitGalleryAttrID splits a namespaced attribute id back into its source+// id and source-local name. ok is false for ids without a separator.+func SplitGalleryAttrID(id string) (sourceID, name string, ok bool) {+ for i := 0; i < len(id); i++ {+ if id[i] == ':' {+ return id[:i], id[i+1:], i > 0 && i+1 < len(id)+ }+ }+ return "", "", false+}diff --git a/internal/types/gallery_builtin_source.go b/internal/types/gallery_builtin_source.gonew file mode 100644index 000000000..fdf13297e--- /dev/null+++ b/internal/types/gallery_builtin_source.go@@ -0,0 +1,55 @@+package types++// The builtin attribute source models the image fields every gallery has —+// caption, OCR text, timestamps and the chunk enabled flag — as attributes,+// so the gallery's filter / search / sort UI is rendered from one uniform+// contract with no hardcoded special cases. Values of builtin attributes do+// not live in image_info.attrs; the service layer resolves them from the+// asset's own fields (see the service package's galleryAttrs helpers).+//+// Defaults are deliberately useful out of the box: caption and ocr_text are+// searchable, the timestamps sortable, and the enabled flag filterable.+// Every flag can be overridden per tier (system / KB / user) at runtime+// without touching this file.+func init() {+ RegisterGalleryAttrSource("builtin", func(string) []GalleryAttrDef {+ return []GalleryAttrDef{+ {+ Name: "caption",+ Type: "text",+ Label: "Caption",+ Description: "The model-generated description of the image.",+ Usage: GalleryUsage{InSearchField: true, InSortField: true},+ },+ {+ Name: "ocr_text",+ Type: "text",+ Label: "OCR text",+ Description: "Text extracted from the image by OCR.",+ Usage: GalleryUsage{InSearchField: true},+ },+ {+ Name: "created_at",+ Type: "date",+ Label: "Created at",+ Usage: GalleryUsage{InSortField: true},+ },+ {+ Name: "updated_at",+ Type: "date",+ Label: "Updated at",+ Usage: GalleryUsage{InSortField: true},+ },+ {+ Name: "is_enabled",+ Type: "presence",+ Label: "Enabled",+ Values: []GalleryAttrValue{+ {Value: "true", Label: "Enabled"},+ {Value: "false", Label: "Disabled"},+ },+ Usage: GalleryUsage{InFilter: true},+ },+ }+ })+}diff --git a/internal/types/gallery_policy.go b/internal/types/gallery_policy.gonew file mode 100644index 000000000..fc779410d--- /dev/null+++ b/internal/types/gallery_policy.go@@ -0,0 +1,213 @@+package types++// The gallery configuration is resolved from up to four tiers, each more+// specific than the last. Higher tiers override lower ones field by field;+// a tier that does not mention an attribute (or source, or dimension)+// changes nothing about it.+//+// user tier (per-user JSON, users.preferences.gallery) highest+// KB tier (per-KB JSON, knowledge base config) pending+// system tier (platform JSON, system_settings "gallery.policy")+// source tier (what each registered attribute source declares) lowest+//+// The three JSON tiers share one schema (GalleryPolicyTier) so the merge+// engine below is tier-agnostic and new storage homes plug in without+// changing the contract. Only the user tier carries mode/status — the+// search-field activation state is personal by definition.+//+// Only attribute USAGE (eligibility) is configurable here; attribute+// definitions (name / type / values / labels) come exclusively from+// registered sources, so no tier can invent an attribute no pipeline+// produces.++// GalleryUsageOverride is a field-level usage override. A nil field means+// "leave the lower tier's value alone"; a non-nil field replaces it.+type GalleryUsageOverride struct {+ InFilter *bool `json:"in_filter,omitempty"`+ InSearchField *bool `json:"in_searchfield,omitempty"`+ InSortField *bool `json:"in_sortfield,omitempty"`+}++// GalleryPolicyTier is the unified JSON schema shared by the system, KB and+// user configuration tiers. All fields are optional; an empty tier is a+// no-op.+type GalleryPolicyTier struct {+ // Sources toggles whole attribute sources on/off, keyed by source id.+ // The highest tier that mentions a source decides its state; sources+ // nobody mentions are enabled.+ Sources map[string]bool `json:"sources,omitempty"`+ // Overrides adjusts per-attribute usage, keyed by namespaced attribute+ // id ("system:contain.text"). Overrides apply field by field on top of+ // whatever the lower tiers resolved.+ Overrides map[string]GalleryUsageOverride `json:"overrides,omitempty"`+ // Mode is the user-tier search activation mode: "all" (every eligible+ // search field active) or "custom" (per-field status governs). Empty+ // means "all". Only meaningful in the user tier.+ Mode string `json:"mode,omitempty"`+ // Status is the user-tier per-attribute search-field activation,+ // keyed by namespaced attribute id with values "on"/"off". Only+ // meaningful in the user tier.+ Status map[string]string `json:"status,omitempty"`+}++// Gallery resolved-config constants.+const (+ // GalleryModeAll activates every search-eligible field regardless of+ // status; it is the default so a fresh user's search works out of the+ // box. GalleryModeCustom lets the per-field status map decide, with an+ // unrecorded field defaulting to off.+ GalleryModeAll = "all"+ GalleryModeCustom = "custom"+ // GalleryStatusOn / GalleryStatusOff are the user-tier status values.+ GalleryStatusOn = "on"+ GalleryStatusOff = "off"+)++// GalleryResolvedAttr is one attribute as the gallery contract serves it to+// the frontend: the source's declaration with every tier's overrides already+// merged in. ID is the namespaced attribute id; Name stays source-local for+// raw lookups in image_info.+type GalleryResolvedAttr struct {+ ID string `json:"id"`+ Source string `json:"source"`+ Name string `json:"name"`+ Type string `json:"type"`+ // Values keeps each allowed value's raw form plus the short label to+ // show and the sentence to explain it. A source that declares no+ // values (a free-text or date attribute) simply omits the field.+ Values []GalleryAttrValue `json:"values,omitempty"`+ Label string `json:"label"`+ Description string `json:"description,omitempty"`+ Usage GalleryUsage `json:"usage"`+ // UsageFrom names the highest tier that touched this attribute's usage:+ // "source" | "system" | "kb" | "user". Debugging aid for "why does this+ // attribute (not) show up".+ UsageFrom string `json:"usage_from"`+}++// GalleryResolvedConfig is the merged gallery contract: which sources are+// live, the resolved attribute list, and the user's search activation state.+type GalleryResolvedConfig struct {+ // AttributeSources lists the live source ids in priority order.+ AttributeSources []string `json:"attribute_sources"`+ Attributes []GalleryResolvedAttr `json:"attributes"`+ // Mode is the user's search activation mode ("all" by default).+ Mode string `json:"mode"`+ // Status mirrors the user's per-field search toggles; nil means the+ // user has not recorded any yet.+ Status map[string]string `json:"status"`+}++// galleryUsageFrom labels for UsageFrom, ordered low -> high.+const (+ galleryFromSource = "source"+ galleryFromSystem = "system"+ galleryFromKB = "kb"+ galleryFromUser = "user"+)++// ResolveGalleryConfig merges the registered sources with the configuration+// tiers (system -> KB -> user, each overriding field by field) and returns+// the contract the gallery frontend renders from. A nil tier simply does not+// exist; the KB tier is reserved for the per-KB config (not wired yet — the+// engine already accepts it).+func ResolveGalleryConfig(kbID string, system, kb, user *GalleryPolicyTier) *GalleryResolvedConfig {+ res := &GalleryResolvedConfig{+ AttributeSources: []string{},+ Attributes: []GalleryResolvedAttr{},+ Mode: GalleryModeAll,+ }++ // Source on/off: the highest tier that mentions the source wins.+ for _, src := range GalleryAttrSources(kbID) {+ if !gallerySourceEnabled(src.ID, system, kb, user) {+ continue+ }+ res.AttributeSources = append(res.AttributeSources, src.ID)+ for _, def := range src.Attrs {+ attr := GalleryResolvedAttr{+ ID: GalleryAttrID(src.ID, def.Name),+ Source: src.ID,+ Name: def.Name,+ Type: def.Type,+ Values: def.Values,+ Label: def.Label,+ Description: def.Description,+ Usage: def.Usage,+ UsageFrom: galleryFromSource,+ }+ galleryApplyTier(&attr, system, galleryFromSystem)+ galleryApplyTier(&attr, kb, galleryFromKB)+ galleryApplyTier(&attr, user, galleryFromUser)+ res.Attributes = append(res.Attributes, attr)+ }+ }++ // User-tier activation state. Mode is validated; anything else falls+ // back to the inclusive default.+ if user != nil {+ if user.Mode == GalleryModeAll || user.Mode == GalleryModeCustom {+ res.Mode = user.Mode+ }+ if len(user.Status) > 0 {+ status := make(map[string]string, len(user.Status))+ for id, v := range user.Status {+ if v == GalleryStatusOn || v == GalleryStatusOff {+ status[id] = v+ }+ }+ if len(status) > 0 {+ res.Status = status+ }+ }+ }+ return res+}++// gallerySourceEnabled reports whether a source is enabled under the tiers:+// user > KB > system, and an unmentioned source defaults to enabled.+func gallerySourceEnabled(id string, tiers ...*GalleryPolicyTier) bool {+ for i := len(tiers) - 1; i >= 0; i-- {+ t := tiers[i]+ if t == nil {+ continue+ }+ if enabled, mentioned := t.Sources[id]; mentioned {+ return enabled+ }+ }+ return true+}++// galleryApplyTier folds one tier's override for this attribute into the+// resolved usage, field by field, and records the tier in UsageFrom when it+// touched at least one field.+func galleryApplyTier(attr *GalleryResolvedAttr, tier *GalleryPolicyTier, from string) {+ if tier == nil {+ return+ }+ if o, ok := tier.Overrides[attr.ID]; ok {+ applyGalleryOverride(&attr.Usage, &attr.UsageFrom, from, &o)+ }+}++// applyGalleryOverride applies one attribute override; reports whether the+// override existed.+func applyGalleryOverride(usage *GalleryUsage, usageFrom *string, from string, o *GalleryUsageOverride) bool {+ if o == nil {+ return false+ }+ if o.InFilter != nil {+ usage.InFilter = *o.InFilter+ *usageFrom = from+ }+ if o.InSearchField != nil {+ usage.InSearchField = *o.InSearchField+ *usageFrom = from+ }+ if o.InSortField != nil {+ usage.InSortField = *o.InSortField+ *usageFrom = from+ }+ return true+}diff --git a/internal/types/image_actions.go b/internal/types/image_actions.gonew file mode 100644index 000000000..a3176aab5--- /dev/null+++ b/internal/types/image_actions.go@@ -0,0 +1,67 @@+package types++// ActionKind enumerates the normalized image-pipeline actions. Under the+// unified action framework every image step is one of these; the dispatch loop+// treats them uniformly so adding an action is a registry entry, not a new+// if/else branch.+type ActionKind string++const (+ // ActionCaption asks the model for a short description of the image.+ ActionCaption ActionKind = "caption"+ // ActionObservation asks the model to observe the registered attributes+ // (contain.text, contain.data_visual, ...). It is the only action that+ // feeds a later decision — the OCR policy reads its result.+ ActionObservation ActionKind = "observation"+ // ActionOCR extracts the text the image carries, when the policy wants it.+ ActionOCR ActionKind = "ocr"+)++// PipelineMode labels which image pipeline a trace row ran under. It is+// recorded on the per-image subspan input so a reader of the processing trace+// can tell an attribute-observed run from the caption+OCR fallback: reading the+// stored image_info alone cannot, because a run that observed the attributes+// and then skipped OCR looks exactly like one that never observed anything.+type PipelineMode string++const (+ // PipelineObservationDriven observes the registered attributes first, then+ // OCRs only when the attribute policy says so.+ PipelineObservationDriven PipelineMode = "observation_driven"+ // PipelineCaptionOCR is the upstream path: caption every image, then OCR+ // every image, with no observation and no policy.+ PipelineCaptionOCR PipelineMode = "caption_ocr"+)++// PipelineModeFor maps the attribute-observation switch to its trace label, so+// the label and the action table below can never disagree about which pipeline+// a task ran under.+func PipelineModeFor(attrsEnabled bool) PipelineMode {+ if attrsEnabled {+ return PipelineObservationDriven+ }+ return PipelineCaptionOCR+}++// DefaultEnabledActions returns the per-action default-on flags for a pipeline+// mode. Observation mode observes and captions by default and lets the OCR+// decision gate OCR; caption+OCR mode captions and OCRs every image. This is+// the single source of default action membership — a new action is enabled+// here, never scattered across call sites.+//+// Note the deliberate parallel with DefaultImageActions: this is which actions+// run at all, that one is the attribute -> work policy that gates OCR.+func DefaultEnabledActions(attrsEnabled bool) map[ActionKind]bool {+ if attrsEnabled {+ return map[ActionKind]bool{+ ActionCaption: true,+ ActionObservation: true,+ ActionOCR: false,+ }+ }+ return map[ActionKind]bool{+ ActionCaption: true,+ ActionObservation: false,+ ActionOCR: true,+ }+}diff --git a/internal/types/image_attrs.go b/internal/types/image_attrs.gonew file mode 100644index 000000000..4cc282c16--- /dev/null+++ b/internal/types/image_attrs.go@@ -0,0 +1,371 @@+package types++import "strings"++// AttrType is the shape of an observed attribute value.+type AttrType string++const (+ // AttrTypeExtent is an ordered set of values, e.g. none < sparse < block.+ AttrTypeExtent AttrType = "extent"+ // AttrTypePresence is a boolean observation, e.g. true / false.+ AttrTypePresence AttrType = "presence"+)++// AttrSpec is one observable image attribute. The registry is the single source+// of truth for which attributes exist this release; adding an attribute is one+// line here plus a decision clause, and never a struct change elsewhere. That+// is what makes "add an attribute = add a row" a real, low-risk operation. The+// same row also carries the attribute's display text. The settings panel that+// explains the attributes to a non-technical operator is rendered from these+// fields, so adding an attribute needs no frontend change either: Label,+// Description and the per-value texts travel to the UI through the schema+// endpoint. An attribute is always accompanied by a short label for compact+// spaces and a sentence for places with room.+type AttrSpec struct {+ Name string `json:"name"` // stable key, e.g. "contain.text"+ Type AttrType `json:"type"` // extent | presence+ Values []AttrValue `json:"values,omitempty"` // ordered low->high for extent attrs+ Question string `json:"question"` // sentence shown to the model in the describe round+ Label string `json:"label"` // human-readable name for the settings panel+ Description string `json:"description,omitempty"` // one line explaining what the attribute measures+ Consumers []string `json:"consumers,omitempty"` // downstream steps that read this attribute+}++// AttrValue is one allowed value of an attribute: the raw value plus the words+// to show for it.+//+// Display text is split in two on purpose. Label is the short name that fits+// on a filter checkbox or a table cell; Description is the sentence that+// explains the value where there is room (a tooltip, the settings panel).+// Both are written in the project's default language; the frontend overlays+// its translations on top (see imageAttrDisplay in the web app) and falls+// back to these strings for anything not translated yet.+type AttrValue struct {+ Value string `json:"value"` // raw machine value, never localized+ Label string `json:"label"` // short on-screen name+ Description string `json:"description,omitempty"` // sentence explaining the value+}++// ImageAttrRegistry is the canonical, ordered list of observed attributes for+// this release. Two are active:+// - contain.text drives the OCR decision through its "block" value;+// - contain.data_visual keeps charts (sparse axis labels) on the OCR path+// while photos with sparse road signs stay off it, preserving the+// equivalence with the old 7-class model.+var ImageAttrRegistry = []AttrSpec{+ {+ Name: "contain.text",+ Type: AttrTypeExtent,+ Values: []AttrValue{+ {Value: "none", Label: "None", Description: "no text at all"},+ {Value: "sparse", Label: "Sparse", Description: "a few words — a logo, a road sign, a single label"},+ {Value: "block", Label: "Block", Description: "a block of body text: screenshot, table, document page"},+ },+ Question: "How much body text does the image carry? Answer exactly one of: " ++ "none (no text), sparse (a few words such as a logo or a road sign), " ++ "block (a block of body text such as a screenshot, table, or document page).",+ Label: "Text in the image",+ Description: "How much body text the picture itself carries. " ++ "Decides whether reading its text is worth a separate OCR pass.",+ Consumers: []string{"ocr"},+ },+ {+ Name: "contain.data_visual",+ Type: AttrTypePresence,+ Values: []AttrValue{+ {Value: "true", Label: "Yes", Description: "a chart, graph or diagram with plotted values"},+ {Value: "false", Label: "No", Description: "a photo, drawing, icon or decoration"},+ },+ Question: "Does the image present quantitative data as a chart, graph, diagram, or infographic " ++ "(axis labels, legends, plotted values)? Answer exactly one of: true, false.",+ Label: "Data visual",+ Description: "Whether the picture conveys data as a chart, graph, diagram or infographic. " ++ "Such images keep their labels on the OCR path even when the text looks sparse.",+ Consumers: []string{"ocr"},+ },+}++// ImageAttrSchemaVersion marks the shape and the semantics of+// ImageAttrs.Attrs. It is attrs/2 since an unobserved attribute stopped being+// written as a conservative default: an absent key now means "the observation+// did not answer for this attribute" and is read through the OCR policy's+// OnUnobserved clause, so a consumer of stored observations must not assume+// every registered key is present. Bump it when an attribute's semantics+// change, not when one is merely added.+const ImageAttrSchemaVersion = "attrs/2"++// ImageAttrSource records how an observation was produced, so post-split data+// can be bucketed by provenance and evaluations do not mix sources.+type ImageAttrSource struct {+ Schema string `json:"schema"` // ImageAttrSchemaVersion+ Prompt string `json:"prompt"` // prompt fingerprint (version + whether custom instructions were appended)+ Custom bool `json:"custom,omitempty"` // true if the describe prompt carried user custom instructions+}++// ImageAttrs is the persisted observation result. Attrs is a map, not a fixed+// struct, so adding an attribute never breaks storage or rows written before+// the attribute existed. Stored inside chunks.image_info as JSON; no migration.+type ImageAttrs struct {+ Schema string `json:"schema"`+ Source ImageAttrSource `json:"source"`+ Attrs map[string]any `json:"attrs,omitempty"`+}++// Observed reports whether an attribute key was present in the observation.+func (a ImageAttrs) Observed(name string) bool {+ if a.Attrs == nil {+ return false+ }+ _, ok := a.Attrs[name]+ return ok+}++// TextExtent returns the observed contain.text value, or "" when the attribute+// was not observed. Use Observed("contain.text") to tell an absent attribute+// apart from one the model answered; "" is never a legal observed value.+func (a ImageAttrs) TextExtent() string {+ if a.Attrs == nil {+ return ""+ }+ if v, ok := a.Attrs["contain.text"]; ok {+ if s, ok := v.(string); ok {+ return s+ }+ }+ return ""+}++// DataVisual returns the observed contain.data_visual value, or false when the+// attribute was not observed. Absence is not the same as an observed "false" —+// use Observed to distinguish them, which is what DecideOCR does.+func (a ImageAttrs) DataVisual() bool {+ if a.Attrs == nil {+ return false+ }+ if v, ok := a.Attrs["contain.data_visual"]; ok {+ if b, ok := v.(bool); ok {+ return b+ }+ }+ return false+}++// ImageActionsConfig is the attribute -> work policy. It is keyed by downstream+// action (today only "ocr"); each action lists the attribute conditions that+// turn it on, plus the conservative value to use when the driving attribute was+// not observed.+type ImageActionsConfig struct {+ OCR ImageOCRAction `json:"ocr"`+}++// ImageOCRAction is the OCR clause of the image_actions policy.+type ImageOCRAction struct {+ // On is the list of attribute conditions that enable OCR. Matching any one+ // turns OCR on.+ On []ImageAttrCondition `json:"on"`+ // OnUnobserved is the OCR decision used when the observation does not+ // answer for one of the attributes the policy reads — the attribute is+ // absent because the model skipped the line, or because the value it wrote+ // was not one of the allowed ones. The default is true: an incomplete+ // observation keeps extracting, so a missed block of text costs one extra+ // call instead of being lost. Turn it off only with a model reliable enough+ // to answer every attribute line.+ OnUnobserved bool `json:"on_unobserved"`+}++// ImageAttrCondition is one attribute match: attr Prop equals Is.+type ImageAttrCondition struct {+ Prop string `json:"prop"`+ Is string `json:"is"`+}++// DefaultImageActions is the built-in attribute -> work table. It is deliberately+// conservative: OCR runs when contain.text is "block", or contain.data_visual is+// true, or the observation did not answer for an attribute the policy reads (the+// OnUnobserved clause). It is equivalent to the old class table: decorative /+// logo / photo (text reliably absent or captured by the description) skip OCR;+// text_screenshot / table / chart / other run OCR.+func DefaultImageActions() ImageActionsConfig {+ return ImageActionsConfig{+ OCR: ImageOCRAction{+ On: []ImageAttrCondition{+ {Prop: "contain.text", Is: "block"},+ {Prop: "contain.data_visual", Is: "true"},+ },+ OnUnobserved: true,+ },+ }+}++// MergeImageActions folds a knowledge base's custom action table on top of the+// built-in one, per action key. A custom OCR.On replaces the default OCR.On+// wholesale (the "on" list is a unit); anything the custom table does not+// mention keeps the default. This lets a knowledge base tune OCR without+// spelling out every condition, and keeps a future action key added to the+// default from being wiped by an older stored config.+func MergeImageActions(custom ImageActionsConfig) ImageActionsConfig {+ merged := DefaultImageActions()+ if len(custom.OCR.On) > 0 {+ merged.OCR = custom.OCR+ }+ return merged+}++// ResolveImageActions returns the effective policy: a nil config uses the+// default; a non-nil config is merged so forward-compatible.+func ResolveImageActions(p *ImageActionsConfig) ImageActionsConfig {+ if p == nil {+ return DefaultImageActions()+ }+ return MergeImageActions(*p)+}++// ImageAttrPromptVersion is the fingerprint of the describe-round observation+// prompt. It is recorded in ImageAttrSource.Prompt so evaluations can tell+// observations produced by different prompt versions apart.+const ImageAttrPromptVersion = "observe/1"++// AttrObservation is a parsed observe-and-describe answer: the observed+// attributes and the description written for the image.+type AttrObservation struct {+ Attrs ImageAttrs+ Description string+ // Observed reports whether the model returned at least one well-formed+ // attribute line with a usable value. When false no attribute was observed+ // at all and the observation round effectively produced nothing — the+ // caller mirrors this into the trace (observation_failed) so a prompt that+ // derailed the attribute protocol is visible instead of passing for a+ // confident read. It is a runtime signal only and is never persisted: only+ // Attrs is stored with the chunk.+ Observed bool+}++// ParseImageAttrsResponse splits an observe-and-describe answer into its+// attribute lines and its DESCRIPTION. The boolean reports whether the answer+// yielded a description worth storing; false means the image ends up with+// attributes but no caption, which the caller records so the missing caption is+// not read as an observation failure.+//+// Only a reply with no text at all, or one that is nothing but attribute lines,+// yields false. Prose that skips the labels is kept as the description: the+// model answered the question, it just did not format the answer.+//+// An attribute the answer does not spell out — because the model skipped the+// line, or because the value it wrote is not one of the allowed ones — is+// simply absent from Attrs. Nothing is invented in its place: writing a+// conservative default there would make an unanswered question look like a+// confident "block", and would leave the OCR policy's OnUnobserved clause+// unreachable. The absence is what DecideOCR turns into the conservative+// decision instead.+func ParseImageAttrsResponse(raw string) (AttrObservation, bool) {+ obs := AttrObservation{+ Attrs: ImageAttrs{+ Schema: ImageAttrSchemaVersion,+ Source: ImageAttrSource{Schema: ImageAttrSchemaVersion, Prompt: ImageAttrPromptVersion},+ Attrs: map[string]any{},+ },+ }+ seen := map[string]bool{}+ var descriptions []string+ for _, line := range strings.Split(raw, "\n") {+ trimmed := trimAttrMarkers(line)+ if key, val, ok := cutAttrLine(trimmed); ok {+ if spec, found := lookupAttrSpec(key); found {+ // Unusable values are dropped rather than defaulted, so the+ // attribute stays absent and the policy's OnUnobserved clause+ // decides what to do about it.+ if v, usable := coerceAttrValue(spec, val); usable {+ obs.Attrs.Attrs[spec.Name] = v+ seen[spec.Name] = true+ }+ continue+ }+ if strings.EqualFold(key, "DESCRIPTION") {+ descriptions = append(descriptions, val)+ continue+ }+ }+ if strings.EqualFold(trimmed, "DESCRIPTION") {+ continue+ }+ if trimmed != "" {+ descriptions = append(descriptions, trimmed)+ }+ }+ // Observed records whether the model emitted any well-formed attribute+ // line. A prose-only or empty answer yields false; such replies are kept as+ // the description but carry no observation, so the caller must know the+ // attribute table says nothing about the image.+ obs.Observed = len(seen) > 0+ joined := strings.TrimSpace(strings.Join(descriptions, " "))+ // A model may prefix the description with a list marker; drop it so the+ // caption starts with prose.+ obs.Description = strings.TrimSpace(strings.TrimLeft(joined, "-*# "))+ return obs, obs.Description != ""+}++// lookupAttrSpec matches a model-written key (e.g. "CONTAIN.TEXT",+// "contain_text") onto a registry attribute.+func lookupAttrSpec(key string) (AttrSpec, bool) {+ norm := strings.ToLower(strings.TrimSpace(key))+ norm = strings.ReplaceAll(norm, " ", "_")+ norm = strings.ReplaceAll(norm, "-", "_")+ // Models wrap keys in markdown emphasis ("**contain.text**"); strip it so+ // the trailing markers never break the match.+ norm = strings.ReplaceAll(norm, "*", "")+ norm = strings.ReplaceAll(norm, "#", "")+ for _, spec := range ImageAttrRegistry {+ if spec.Name == norm || strings.ReplaceAll(spec.Name, ".", "_") == norm {+ return spec, true+ }+ }+ return AttrSpec{}, false+}++// coerceAttrValue validates a raw value against the attribute's allowed set. It+// reports false when the model wrote nothing usable — an empty value, or one+// outside the allowed set — and the caller then leaves the attribute absent+// instead of substituting a default.+func coerceAttrValue(spec AttrSpec, raw string) (any, bool) {+ v := strings.TrimSpace(strings.ToLower(raw))+ // Models may emphasise the value ("**block**"); strip it before matching.+ v = strings.ReplaceAll(v, "*", "")+ v = strings.ReplaceAll(v, "#", "")+ switch spec.Type {+ case AttrTypeExtent:+ for _, allowed := range spec.Values {+ if v == allowed.Value {+ return allowed.Value, true+ }+ }+ case AttrTypePresence:+ switch v {+ case "true":+ return true, true+ case "false":+ return false, true+ }+ }+ return nil, false+}++// cutAttrLine returns the key and value of a "KEY: value" line.+func cutAttrLine(line string) (key, value string, ok bool) {+ idx := strings.Index(line, ":")+ if idx < 0 {+ return "", "", false+ }+ key = strings.TrimSpace(line[:idx])+ value = strings.TrimSpace(line[idx+1:])+ if key == "" {+ return "", "", false+ }+ return key, value, true+}++// trimAttrMarkers strips the markdown emphasis and list markers models wrap+// around attribute lines.+func trimAttrMarkers(line string) string {+ return strings.TrimLeft(line, "*_#- \t")+}diff --git a/internal/types/image_attrs_gallery.go b/internal/types/image_attrs_gallery.gonew file mode 100644index 000000000..c47efa94e--- /dev/null+++ b/internal/types/image_attrs_gallery.go@@ -0,0 +1,36 @@+package types++// The system attribute registry doubles as a gallery attribute source: every+// attribute declared for the observe-and-describe pipeline is offered to the+// image gallery, defaulting to filterable (the observation values are small+// ordered sets, which is what the gallery's extent / presence filters render+// best). The gallery's config tiers can override these flags at runtime —+// this registration is only the lowest-priority fallback.+//+// This file depends on the gallery's neutral source hook+// (types/gallery_attr_source.go). Merge the gallery PR first, or land the+// hook file together with this commit — both PRs carry byte-identical copies+// of that file so either merge order resolves cleanly.+func init() {+ RegisterGalleryAttrSource("system", func(string) []GalleryAttrDef {+ defs := make([]GalleryAttrDef, 0, len(ImageAttrRegistry))+ for _, spec := range ImageAttrRegistry {+ values := make([]GalleryAttrValue, 0, len(spec.Values))+ for _, value := range spec.Values {+ values = append(values, GalleryAttrValue(value))+ }+ defs = append(defs, GalleryAttrDef{+ Name: spec.Name,+ Type: string(spec.Type),+ Values: values,+ Label: spec.Label,+ Description: spec.Description,+ // Extent / presence observations are filter material by+ // default; searching and sorting on them is an operator+ // decision made through the gallery policy tiers.+ Usage: GalleryUsage{InFilter: true},+ })+ }+ return defs+ })+}diff --git a/internal/types/image_attrs_test.go b/internal/types/image_attrs_test.gonew file mode 100644index 000000000..536403970--- /dev/null+++ b/internal/types/image_attrs_test.go@@ -0,0 +1,215 @@+package types++import (+ "reflect"+ "strings"+ "testing"+)++// TestImageAttrRegistryHasActiveAttributes pins the v1 observation set: the+// registry is the single source of truth that drives both the OCR decision and+// the frontend panel, so adding an attribute later is a one-line change here+// and nowhere else. It also pins that every row can explain itself — the+// settings panel is rendered from these fields, so a row without text would+// reach a non-technical operator as a blank line, and a value without a meaning+// as a bare code like "sparse".+func TestImageAttrRegistryHasActiveAttributes(t *testing.T) {+ t.Parallel()++ var haveText, haveDataVisual bool+ for _, spec := range ImageAttrRegistry {+ if strings.TrimSpace(spec.Label) == "" {+ t.Errorf("%s has no display label", spec.Name)+ }+ if strings.TrimSpace(spec.Description) == "" {+ t.Errorf("%s has no display description", spec.Name)+ }+ if len(spec.Values) == 0 {+ if spec.Type == AttrTypePresence {+ t.Errorf("%s is presence but declares no values", spec.Name)+ continue+ }+ t.Errorf("%s declares no values", spec.Name)+ }+ for _, v := range spec.Values {+ if strings.TrimSpace(v.Label) == "" {+ t.Errorf("%s value %q has no short label", spec.Name, v.Value)+ }+ if strings.TrimSpace(v.Description) == "" {+ t.Errorf("%s value %q has no human explanation", spec.Name, v.Value)+ }+ }+ switch spec.Name {+ case "contain.text":+ haveText = true+ if spec.Type != AttrTypeExtent {+ t.Errorf("contain.text type = %q, want extent", spec.Type)+ }+ if len(spec.Values) != 3 {+ t.Errorf("contain.text values = %v, want none|sparse|block", spec.Values)+ }+ case "contain.data_visual":+ haveDataVisual = true+ if spec.Type != AttrTypePresence {+ t.Errorf("contain.data_visual type = %q, want presence", spec.Type)+ }+ }+ }+ if !haveText || !haveDataVisual {+ t.Fatalf("registry missing an active attribute: text=%v data_visual=%v", haveText, haveDataVisual)+ }+}++// TestParseImageAttrsResponse covers the observe-and-describe parser: it pulls+// attribute lines and the description, drops attributes the model did not+// actually answer for (instead of inventing a default), and never stores+// protocol noise as the caption.+func TestParseImageAttrsResponse(t *testing.T) {+ t.Parallel()++ t.Run("reads attributes and description", func(t *testing.T) {+ obs, ok := ParseImageAttrsResponse(+ "contain.text: block\ncontain.data_visual: true\nDESCRIPTION: A pricing table.")+ if !ok {+ t.Fatal("expected a usable description")+ }+ if obs.Attrs.Attrs["contain.text"] != "block" {+ t.Errorf("contain.text = %v, want block", obs.Attrs.Attrs["contain.text"])+ }+ if obs.Attrs.Attrs["contain.data_visual"] != true {+ t.Errorf("contain.data_visual = %v, want true", obs.Attrs.Attrs["contain.data_visual"])+ }+ if obs.Description != "A pricing table." {+ t.Errorf("description = %q", obs.Description)+ }+ })++ t.Run("joins multi-line descriptions and tolerates emphasis", func(t *testing.T) {+ obs, ok := ParseImageAttrsResponse(+ "**contain.text**: sparse\ncontain.data_visual: false\nDESCRIPTION: first line\nsecond line\n")+ if !ok {+ t.Fatal("expected a usable description")+ }+ if obs.Attrs.Attrs["contain.text"] != "sparse" {+ t.Errorf("contain.text = %v, want sparse", obs.Attrs.Attrs["contain.text"])+ }+ if obs.Description != "first line second line" {+ t.Errorf("description = %q", obs.Description)+ }+ })++ t.Run("keeps a prose answer that ignores the protocol", func(t *testing.T) {+ // No attribute lines at all: the model still described the image, so it+ // becomes the caption, but nothing is claimed about the attributes —+ // they stay absent so the caller's OnUnobserved clause decides.+ obs, ok := ParseImageAttrsResponse("- A wiring diagram.\n")+ if !ok {+ t.Fatal("expected a usable description")+ }+ if obs.Description != "A wiring diagram." {+ t.Errorf("list marker not stripped: %q", obs.Description)+ }+ if obs.Observed {+ t.Error("a prose answer must not count as an observation")+ }+ if _, present := obs.Attrs.Attrs["contain.text"]; present {+ t.Errorf("an unanswered attribute must stay absent, got %v", obs.Attrs.Attrs["contain.text"])+ }+ })++ t.Run("drops a value it cannot read instead of inventing one", func(t *testing.T) {+ obs, _ := ParseImageAttrsResponse("contain.text: maybe_a_lot\nDESCRIPTION: x")+ if _, present := obs.Attrs.Attrs["contain.text"]; present {+ t.Errorf("an unusable value must not be stored, got %v", obs.Attrs.Attrs["contain.text"])+ }+ if obs.Observed {+ t.Error("a line with an unusable value is not an observation")+ }+ })++ t.Run("keeps only the attributes the model answered for", func(t *testing.T) {+ obs, ok := ParseImageAttrsResponse("contain.text: sparse\nDESCRIPTION: A logo.")+ if !ok {+ t.Fatal("expected a usable description")+ }+ if obs.Attrs.Attrs["contain.text"] != "sparse" {+ t.Errorf("contain.text = %v, want sparse", obs.Attrs.Attrs["contain.text"])+ }+ if _, present := obs.Attrs.Attrs["contain.data_visual"]; present {+ t.Errorf("a half-answered observation must not grow the missing attribute, got %v",+ obs.Attrs.Attrs["contain.data_visual"])+ }+ if !obs.Observed {+ t.Error("the answer did observe one attribute")+ }+ })++ t.Run("unformatted response is reported as unusable", func(t *testing.T) {+ if _, ok := ParseImageAttrsResponse(""); ok {+ t.Error("an empty answer must not count as a description")+ }+ })++ t.Run("label-only answer yields no description but real attributes", func(t *testing.T) {+ obs, ok := ParseImageAttrsResponse("contain.text: block\ncontain.data_visual: true")+ if ok {+ t.Error("an answer with no description must be reported as missing caption")+ }+ if obs.Attrs.Attrs["contain.text"] != "block" {+ t.Errorf("contain.text = %v, want block", obs.Attrs.Attrs["contain.text"])+ }+ })+}++// TestDefaultImageActions pins the conservative built-in table: OCR is gated on+// contain.text == block OR contain.data_visual == true, and the fallback for an+// unobserved text attribute is to keep OCR on. This is what makes a missed+// observation cost one extra call rather than losing text.+func TestDefaultImageActions(t *testing.T) {+ t.Parallel()++ actions := DefaultImageActions()++ if !actions.OCR.OnUnobserved {+ t.Error("default OCR.OnUnobserved must be true (conservative)")+ }+ wantOn := []ImageAttrCondition{+ {Prop: "contain.text", Is: "block"},+ {Prop: "contain.data_visual", Is: "true"},+ }+ if len(actions.OCR.On) != len(wantOn) {+ t.Fatalf("default OCR.On = %v, want %v", actions.OCR.On, wantOn)+ }+ for i, c := range wantOn {+ if actions.OCR.On[i] != c {+ t.Errorf("default OCR.On[%d] = %+v, want %+v", i, actions.OCR.On[i], c)+ }+ }+}++// TestMergeImageActions replaces the whole OCR condition list: an explicit+// action row is trusted wholesale, so a knowledge base tunes OCR without+// spelling out every condition, and a future action key added to the default is+// not wiped by an older stored config.+func TestMergeImageActions(t *testing.T) {+ t.Parallel()++ custom := ImageActionsConfig{+ OCR: ImageOCRAction{+ On: []ImageAttrCondition{{Prop: "contain.text", Is: "block"}},+ OnUnobserved: false,+ },+ }+ merged := MergeImageActions(custom)+ if merged.OCR.OnUnobserved {+ t.Error("an explicit OCR.OnUnobserved must replace the default (true)")+ }+ if len(merged.OCR.On) != 1 {+ t.Errorf("custom OCR.On must replace the default list, got %v", merged.OCR.On)+ }++ // A nil/empty custom keeps the default whole.+ if got := MergeImageActions(ImageActionsConfig{}); !reflect.DeepEqual(got, DefaultImageActions()) {+ t.Error("an empty custom table must keep the default image actions")+ }+}diff --git a/internal/types/image_gallery.go b/internal/types/image_gallery.gonew file mode 100644index 000000000..9f83b0402--- /dev/null+++ b/internal/types/image_gallery.go@@ -0,0 +1,140 @@+package types++import "time"++// ImageAsset is a single image projected from a chunk's image_info array.+// It is the unit the gallery lists, filters, sorts and serves.+type ImageAsset struct {+ // ID is stable and unique within a KB: "<chunkID>#<index-in-array>".+ ID string `json:"id"`+ // ChunkID is the owning chunk (text chunk for embedded images, or the+ // image_ocr / image_caption chunk for dedicated image assets).+ ChunkID string `json:"chunk_id"`+ // KnowledgeID is the document/knowledge item the image belongs to.+ KnowledgeID string `json:"knowledge_id"`+ // SourceName is the human-readable name of the source knowledge item+ // (document), resolved from KnowledgeID. Empty when the item no longer+ // exists (e.g. deleted), in which case KnowledgeID is still shown.+ SourceName string `json:"source_name"`+ // ChunkType is the owning chunk's type; empty for images discovered on a+ // text (document) chunk. Helps the UI label the source.+ ChunkType string `json:"chunk_type"`+ // URL is the rendered image URL (COS / storage provider).+ URL string `json:"url"`+ // OriginalURL is the pre-transform source reference, when different.+ OriginalURL string `json:"original_url"`+ // Caption is the model-generated image description.+ Caption string `json:"caption"`+ // OCRText is the extracted text from the image, if any.+ OCRText string `json:"ocr_text"`+ // Attrs is the observed attribute map (e.g. contain.text, contain.data_visual)+ // produced by the attribute pipeline. Absent keys mean "not observed".+ Attrs map[string]any `json:"attrs"`+ // IsEnabled mirrors the owning chunk's enabled flag.+ IsEnabled bool `json:"is_enabled"`+ // Status mirrors the owning chunk's index status.+ Status int `json:"status"`+ // CreatedAt is the owning chunk's creation time.+ CreatedAt time.Time `json:"created_at"`+ // UpdatedAt is the owning chunk's last update time.+ UpdatedAt time.Time `json:"updated_at"`+}++// ImageListFilter holds the gallery query constraints coming from the UI.+// Attribute references use namespaced gallery attribute ids+// ("<sourceID>:<name>", e.g. "builtin:caption", "system:contain.text").+type ImageListFilter struct {+ // Keyword is matched as a case-insensitive substring against the union+ // of the SearchIn fields' values.+ Keyword string+ // SearchIn lists the namespaced attribute ids to search. Empty means+ // the gallery default (builtin caption + ocr_text). The handler only+ // forwards ids whose resolved usage has in_searchfield=true.+ SearchIn []string+ // SortBy is a namespaced attribute id with in_sortfield=true. The bare+ // legacy values ("created_at", "updated_at", "caption") are still+ // accepted and mapped onto their builtin ids.+ SortBy string+ // SortOrder is "asc" or "desc".+ SortOrder string+ // AttrFilters maps a namespaced attribute id to the set of allowed+ // values. Values within one attribute are OR-ed; attributes are+ // AND-ed. An attribute present in this map but with no value on an+ // image fails the match (so "unobserved" is a distinct, filterable+ // state). The older, positional form of attribute filtering; see+ // AttrRules for the per-value verdicts the gallery panel now edits.+ AttrFilters map[string][]string+ // AttrRules maps a namespaced attribute id to a verdict per allowed+ // value: "" (or absent) leaves the image alone, "off" hides it, "on"+ // shows it. A verdict only speaks about images that actually carry+ // that value, so an image is judged by the rules it matches.+ //+ // When more than one rule speaks about the same image, "on" outranks+ // "off": a forced display beats a forced hide. Everything unclaimed+ // stays visible, which is what makes the default state usable — a+ // filter narrows the list, it never empties it.+ AttrRules map[string]map[string]string+ // IsEnabled, when non-nil, restricts to chunks with that enabled state.+ IsEnabled *bool+}++// ImageAssetField names one value of an image the gallery query can search,+// filter or sort on. Exactly one of the two is set.+type ImageAssetField struct {+ // Builtin is one of the builtin source's fields: "caption", "ocr_text",+ // "created_at", "updated_at" or "is_enabled".+ Builtin string+ // Attr is a source-local attribute name read from image_info attrs+ // (e.g. "contain.text").+ Attr string+}++// ImageAssetValueSet pairs a field with a set of raw values.+type ImageAssetValueSet struct {+ Field ImageAssetField+ Values []string+}++// ImageAssetQuery is the storage-neutral form of one gallery page request. The+// service translates namespaced attribute ids into fields; the repository+// compiles it into SQL, so de-duplication, filtering, sorting and paging all+// run in the database and only the requested page leaves it.+type ImageAssetQuery struct {+ // Keyword is matched, lowercased, as a substring of the SearchFields'+ // values joined by spaces. Empty disables the keyword match.+ Keyword string+ SearchFields []ImageAssetField+ // AttrFilters are AND-ed across sets and OR-ed within one; an image+ // without a value for the field is not constrained by it.+ AttrFilters []ImageAssetValueSet+ // OnRules / OffRules are the per-value verdicts: an image carrying an+ // "off" value is hidden unless it also carries an "on" value.+ OnRules []ImageAssetValueSet+ OffRules []ImageAssetValueSet+ // IsEnabled, when non-nil, restricts to chunks with that enabled state.+ IsEnabled *bool+ SortField ImageAssetField+ SortDesc bool+ Offset int+ Limit int+}++// ImageAssetRow is one de-duplicated image as the repository returns it: a+// chunk_images row, the owning chunk's columns plus the image entry's fields.+type ImageAssetRow struct {+ ChunkID string `gorm:"column:chunk_id"`+ KnowledgeID string `gorm:"column:knowledge_id"`+ ChunkType string `gorm:"column:chunk_type"`+ IsEnabled bool `gorm:"column:is_enabled"`+ Status int `gorm:"column:status"`+ CreatedAt time.Time `gorm:"column:created_at"`+ UpdatedAt time.Time `gorm:"column:updated_at"`+ ImageIndex int `gorm:"column:image_index"`+ URL string `gorm:"column:url"`+ OriginalURL string `gorm:"column:original_url"`+ Caption string `gorm:"column:caption"`+ OCRText string `gorm:"column:ocr_text"`+ // AttrsJSON is the observed attribute map as JSON text.+ AttrsJSON string `gorm:"column:attrs_json"`+ TotalCount int64 `gorm:"column:total_count"`+}diff --git a/internal/types/interfaces/chunk.go b/internal/types/interfaces/chunk.goindex 65039df88..6db7bf000 100644--- a/internal/types/interfaces/chunk.go+++ b/internal/types/interfaces/chunk.go@@ -112,6 +112,12 @@ type ChunkRepository interface {DeleteByKnowledgeList(ctx context.Context, tenantID uint64, knowledgeIDs []string) error// ListImageInfoByKnowledgeIDs returns non-empty (knowledge_id, image_info) pairs for image cleanup.ListImageInfoByKnowledgeIDs(ctx context.Context, tenantID uint64, knowledgeIDs []string) ([]ChunkImageInfo, error)+ // ListImageAssets returns one page of a KB's de-duplicated image assets+ // (one per image_info entry, keyed by URL) with the query's filters and+ // sort applied in the database, plus the filtered total.+ ListImageAssets(+ ctx context.Context, tenantID uint64, kbID string, q *types.ImageAssetQuery,+ ) ([]types.ImageAssetRow, int64, error)// MoveChunksByKnowledgeID updates knowledge_base_id for all chunks of a knowledge itemMoveChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string, targetKBID string) error// DeleteChunksByTagID deletes all chunks with the specified tag ID@@ -176,6 +182,14 @@ type ChunkService interface {page *types.Pagination,chunkType []types.ChunkType,) (*types.PageResult, error)+ // ListImagesByKnowledgeBaseID lists the image assets of a KB with keyword+ // search, schema-driven attribute filters, sorting and pagination.+ ListImagesByKnowledgeBaseID(+ ctx context.Context,+ kbID string,+ page *types.Pagination,+ filter *types.ImageListFilter,+ ) (*types.PageResult, error)// UpdateChunk updates a chunkUpdateChunk(ctx context.Context, chunk *types.Chunk) error// UpdateChunks updates chunks in batchdiff --git a/internal/types/knowledge_process.go b/internal/types/knowledge_process.goindex 7dbbde93f..99936c0da 100644--- a/internal/types/knowledge_process.go+++ b/internal/types/knowledge_process.go@@ -11,7 +11,15 @@ type KnowledgeProcessOverrides struct {ASRConfig *ASRConfig `json:"asr_config,omitempty"`QuestionGenerationConfig *QuestionGenerationConfig `json:"question_generation_config,omitempty"`GraphEnabled *bool `json:"graph_enabled,omitempty"`- ExtractConfig *ExtractConfig `json:"extract_config,omitempty"`+ // ImageAttrsEnabled overrides the knowledge base's attribute-observed image+ // pipeline switch for this one document. nil keeps the knowledge base's+ // setting.+ ImageAttrsEnabled *bool `json:"image_attrs_enabled,omitempty"`+ // ImageActions overrides rows of the attribute->work table for this document+ // (merged per action key on top of the knowledge base's table).+ // nil keeps the knowledge base's setting.+ ImageActions *ImageActionsConfig `json:"image_actions,omitempty"`+ ExtractConfig *ExtractConfig `json:"extract_config,omitempty"`// ParserEngineOverrides passes key-value configuration to docreader parsers// (e.g. pdf_force_scanned=true). Merged with workspace-level overrides in the// parse pipeline; per-upload values take priority on conflict.@@ -27,5 +35,7 @@ type EffectiveProcessConfig struct {ASRConfig ASRConfigQuestionGenerationConfig QuestionGenerationConfigGraphEnabled bool+ ImageAttrsEnabled bool+ ImageActions ImageActionsConfigExtractConfig ExtractConfig}diff --git a/internal/types/knowledgebase.go b/internal/types/knowledgebase.goindex 14a1618b9..f92b23ed6 100644--- a/internal/types/knowledgebase.go+++ b/internal/types/knowledgebase.go@@ -159,8 +159,15 @@ type KnowledgeBase struct {type KnowledgeBaseConfig struct {// Chunking configurationChunkingConfig ChunkingConfig `yaml:"chunking_config" json:"chunking_config"`- // Image processing configuration- ImageProcessingConfig ImageProcessingConfig `yaml:"image_processing_config" json:"image_processing_config"`+ // Image processing configuration.+ //+ // nil means "no change" when updating, the same contract IndexingStrategy+ // uses. A request that does not mention this field must leave the image+ // settings alone: the attribute-observation switch and the attribute policy+ // are things a knowledge base accumulates, and a client that predates them+ // would otherwise reset the lot on any save. Sending an object — empty+ // included — replaces the whole configuration.+ ImageProcessingConfig *ImageProcessingConfig `yaml:"image_processing_config" json:"image_processing_config"`// FAQ configuration (only for FAQ type knowledge bases)FAQConfig *FAQConfig `yaml:"faq_config" json:"faq_config"`// Wiki configuration (only for wiki-enabled knowledge bases)@@ -533,6 +540,19 @@ func ParseProviderScheme(filePath string) string {type ImageProcessingConfig struct {// Model IDModelID string `yaml:"model_id" json:"model_id"`+ // ImageActions overrides the built-in attribute→work table (see+ // DefaultImageActions). A nil value keeps the conservative default: run OCR+ // for block text, data visuals, and unobserved images.+ ImageActions *ImageActionsConfig `yaml:"image_actions,omitempty" json:"image_actions,omitempty"`+ // ImageAttrsEnabled turns the attribute-observed image pipeline on for this+ // knowledge base. It is off by default on purpose, so upgrading an+ // existing deployment never changes what happens to documents already+ // being ingested: with it off every image is described and OCR'd exactly+ // as before. When on, the describe round also observes image attributes and+ // the attribute policy decides whether OCR runs for it. A single upload can+ // override it per document through+ // KnowledgeProcessOverrides.ImageAttrsEnabled.+ ImageAttrsEnabled bool `yaml:"image_attrs_enabled,omitempty" json:"image_attrs_enabled,omitempty"` //nolint:lll // one-line struct tag}// Value implements the driver.Valuer interface, used to convert ChunkingConfig to database valuediff --git a/internal/types/task.go b/internal/types/task.goindex 737665a24..5c36517a7 100644--- a/internal/types/task.go+++ b/internal/types/task.go@@ -510,6 +510,10 @@ type ImageMultimodalPayload struct {ChunkID string `json:"chunk_id"` // parent text chunkImageURL string `json:"image_url"` // provider:// URL (e.g. local://..., minio://...)ImageLocalPath string `json:"image_local_path"` // deprecated: kept for backward compat with in-flight tasks+ // EnableOCR and EnableCaption are whole-task switches applied on top of the+ // image-action policy: a step runs only when both this switch and the+ // policy allow it. Normal parsing leaves both true and lets the observed+ // attributes decide.EnableOCR bool `json:"enable_ocr"`EnableCaption bool `json:"enable_caption"`Language string `json:"language,omitempty"` // Request locale for {{language}} in prompt templates@@ -522,6 +526,20 @@ type ImageMultimodalPayload struct {// parent's image set. Used as the subspan name suffix// ("multimodal.image[3]") so the timeline preserves order.ImageIndex int `json:"image_index,omitempty"`+ // ImageAttrsEnabled selects which image pipeline the task runs — see+ // PipelineModeFor and the PipelineMode constants. True is the+ // attribute-observed pipeline: the describe round also observes image+ // attributes, and the attribute policy decides whether OCR runs for it.+ // False is the upstream behaviour: a plain caption, then OCR, no attribute+ // observation. In flight tasks enqueued before the field existed read+ // false, which is what they were enqueued for — the reason the flag travels+ // in the payload rather than being re-read from the knowledge base at handle+ // time.+ ImageAttrsEnabled bool `json:"image_attrs_enabled,omitempty"`+ // ImageActions is the attribute→work table, resolved from the KB config at+ // enqueue time. A task without it — one already in flight when attribute+ // observation shipped — falls back to the conservative policy: run OCR.+ ImageActions ImageActionsConfig `json:"image_actions,omitempty"`}// KnowledgePostProcessPayload represents the knowledge post process task payload.diff --git a/internal/types/user.go b/internal/types/user.goindex 0aed944a5..d4de66f99 100644--- a/internal/types/user.go+++ b/internal/types/user.go@@ -49,6 +49,29 @@ type UserPreferences struct {// UI hides self-service password rotation until the user sets a known// password via ChangePassword (which clears this flag).OidcOnlyLogin *bool `json:"oidc_only_login,omitempty"`++ // Gallery holds the user's image-gallery UI state: the search+ // activation mode and the per-attribute search-field toggles. Written+ // by the gallery's mode / checkbox interactions via the preferences+ // PUT; read back by GET /knowledge-bases/:id/gallery-config so the+ // gallery renders the same activation state on every device. Nil = the+ // user never touched the gallery controls (mode defaults to "all").+ Gallery *GalleryUserPrefs `json:"gallery,omitempty"`+}++// GalleryUserPrefs is the user-tier slice of the gallery configuration. The+// full tier schema (types.GalleryPolicyTier) also allows usage overrides,+// but those are admin/operator concerns; the user layer only records the+// activation mode and which search fields they personally switched on.+type GalleryUserPrefs struct {+ // Mode is "all" (every search-eligible field active) or "custom"+ // (per-field Status governs). Empty = "all".+ Mode string `json:"mode,omitempty"`+ // Status maps a namespaced attribute id ("builtin:caption") to+ // "on"/"off". Only consulted in custom mode; an unrecorded field is+ // off. Source-declared on/off does not exist — activation is always+ // the user's own record.+ Status map[string]string `json:"status,omitempty"`}// Value implements driver.Valuer so GORM persists UserPreferences asdiff --git a/migrations/sqlite/000032_chunk_images.down.sql b/migrations/sqlite/000032_chunk_images.down.sqlnew file mode 100644index 000000000..483d0bef6--- /dev/null+++ b/migrations/sqlite/000032_chunk_images.down.sql@@ -0,0 +1,5 @@+DROP TRIGGER IF EXISTS trg_chunk_images_insert;+DROP TRIGGER IF EXISTS trg_chunk_images_patch;+DROP TRIGGER IF EXISTS trg_chunk_images_update;+DROP TRIGGER IF EXISTS trg_chunk_images_delete;+DROP TABLE IF EXISTS chunk_images;diff --git a/migrations/sqlite/000032_chunk_images.up.sql b/migrations/sqlite/000032_chunk_images.up.sqlnew file mode 100644index 000000000..a7b53820c--- /dev/null+++ b/migrations/sqlite/000032_chunk_images.up.sql@@ -0,0 +1,112 @@+-- Migration 000032: chunk_images, the image gallery's projection of image_info+--+-- SQLite twin of versioned migration 000113; see it for the rationale. One row+-- per image_info entry with caption, OCR text and observed attributes as+-- columns, kept in step with chunks by triggers, so the gallery no longer+-- parses every image chunk's JSON on each request. Copies of one image stay+-- separate rows; the gallery query picks the copy on the most recently updated+-- chunk with an indexed anti-join.++CREATE TABLE IF NOT EXISTS chunk_images (+ chunk_id VARCHAR(36) NOT NULL,+ image_index INTEGER NOT NULL,+ tenant_id BIGINT NOT NULL,+ knowledge_base_id VARCHAR(36) NOT NULL,+ knowledge_id VARCHAR(36) NOT NULL,+ chunk_type VARCHAR(20) NOT NULL DEFAULT '',+ image_key TEXT NOT NULL,+ url TEXT NOT NULL DEFAULT '',+ original_url TEXT NOT NULL DEFAULT '',+ caption TEXT NOT NULL DEFAULT '',+ ocr_text TEXT NOT NULL DEFAULT '',+ attrs TEXT NOT NULL DEFAULT '{}',+ is_enabled BOOLEAN NOT NULL DEFAULT 1,+ status INTEGER NOT NULL DEFAULT 0,+ created_at DATETIME,+ updated_at DATETIME,+ PRIMARY KEY (chunk_id, image_index)+);++CREATE INDEX IF NOT EXISTS idx_chunk_images_listing+ ON chunk_images(knowledge_base_id, tenant_id, created_at, chunk_id, image_index);+CREATE INDEX IF NOT EXISTS idx_chunk_images_copies+ ON chunk_images(knowledge_base_id, tenant_id, image_key, updated_at, chunk_id, image_index);++CREATE TRIGGER IF NOT EXISTS trg_chunk_images_insert AFTER INSERT ON chunks+WHEN NEW.image_info LIKE '[%'+BEGIN+ INSERT INTO chunk_images (chunk_id, image_index, tenant_id, knowledge_base_id, knowledge_id, chunk_type, image_key, url, original_url, caption, ocr_text, attrs, is_enabled, status, created_at, updated_at)+ SELECT NEW.id, CAST(e.key AS INTEGER), NEW.tenant_id, NEW.knowledge_base_id, NEW.knowledge_id,+ COALESCE(NEW.chunk_type, ''),+ COALESCE(NULLIF(json_extract(e.value, '$.url'), ''), NULLIF(json_extract(e.value, '$.original_url'), ''),+ NEW.id || '#' || e.key),+ COALESCE(json_extract(e.value, '$.url'), ''), COALESCE(json_extract(e.value, '$.original_url'), ''),+ COALESCE(json_extract(e.value, '$.caption'), ''), COALESCE(json_extract(e.value, '$.ocr_text'), ''),+ CASE WHEN json_type(e.value, '$.attrs.attrs') = 'object'+ THEN json_extract(e.value, '$.attrs.attrs') ELSE '{}' END,+ NEW.is_enabled, COALESCE(NEW.status, 0), NEW.created_at, NEW.updated_at+ FROM json_each(CASE WHEN json_valid(NEW.image_info) AND json_type(NEW.image_info) = 'array' THEN NEW.image_info ELSE '[]' END) AS e+ WHERE NEW.deleted_at IS NULL AND e.type = 'object';+END;++-- An update that leaves the images alone (status, enabled flag, timestamps)+-- patches the rows in place; any other change to a column the projection+-- copies replaces the chunk's rows.+CREATE TRIGGER IF NOT EXISTS trg_chunk_images_patch AFTER UPDATE ON chunks+WHEN NEW.image_info LIKE '[%' AND OLD.deleted_at IS NULL AND NEW.deleted_at IS NULL+ AND OLD.image_info IS NEW.image_info+ AND OLD.tenant_id IS NEW.tenant_id+ AND OLD.knowledge_base_id IS NEW.knowledge_base_id+ AND OLD.knowledge_id IS NEW.knowledge_id+ AND OLD.chunk_type IS NEW.chunk_type+ AND (OLD.is_enabled IS NOT NEW.is_enabled OR OLD.status IS NOT NEW.status+ OR OLD.created_at IS NOT NEW.created_at OR OLD.updated_at IS NOT NEW.updated_at)+BEGIN+ UPDATE chunk_images+ SET is_enabled = NEW.is_enabled, status = COALESCE(NEW.status, 0),+ created_at = NEW.created_at, updated_at = NEW.updated_at+ WHERE chunk_id = NEW.id;+END;++CREATE TRIGGER IF NOT EXISTS trg_chunk_images_update AFTER UPDATE ON chunks+WHEN (OLD.image_info LIKE '[%' OR NEW.image_info LIKE '[%') AND NOT (OLD.deleted_at IS NULL AND NEW.deleted_at IS NULL+ AND OLD.image_info IS NEW.image_info+ AND OLD.tenant_id IS NEW.tenant_id+ AND OLD.knowledge_base_id IS NEW.knowledge_base_id+ AND OLD.knowledge_id IS NEW.knowledge_id+ AND OLD.chunk_type IS NEW.chunk_type)+BEGIN+ DELETE FROM chunk_images WHERE chunk_id = OLD.id;+ INSERT INTO chunk_images (chunk_id, image_index, tenant_id, knowledge_base_id, knowledge_id, chunk_type, image_key, url, original_url, caption, ocr_text, attrs, is_enabled, status, created_at, updated_at)+ SELECT NEW.id, CAST(e.key AS INTEGER), NEW.tenant_id, NEW.knowledge_base_id, NEW.knowledge_id,+ COALESCE(NEW.chunk_type, ''),+ COALESCE(NULLIF(json_extract(e.value, '$.url'), ''), NULLIF(json_extract(e.value, '$.original_url'), ''),+ NEW.id || '#' || e.key),+ COALESCE(json_extract(e.value, '$.url'), ''), COALESCE(json_extract(e.value, '$.original_url'), ''),+ COALESCE(json_extract(e.value, '$.caption'), ''), COALESCE(json_extract(e.value, '$.ocr_text'), ''),+ CASE WHEN json_type(e.value, '$.attrs.attrs') = 'object'+ THEN json_extract(e.value, '$.attrs.attrs') ELSE '{}' END,+ NEW.is_enabled, COALESCE(NEW.status, 0), NEW.created_at, NEW.updated_at+ FROM json_each(CASE WHEN json_valid(NEW.image_info) AND json_type(NEW.image_info) = 'array' THEN NEW.image_info ELSE '[]' END) AS e+ WHERE NEW.deleted_at IS NULL AND e.type = 'object';+END;++CREATE TRIGGER IF NOT EXISTS trg_chunk_images_delete AFTER DELETE ON chunks+WHEN OLD.image_info LIKE '[%'+BEGIN+ DELETE FROM chunk_images WHERE chunk_id = OLD.id;+END;++-- Backfill every live image chunk.+INSERT OR IGNORE INTO chunk_images (chunk_id, image_index, tenant_id, knowledge_base_id, knowledge_id, chunk_type, image_key, url, original_url, caption, ocr_text, attrs, is_enabled, status, created_at, updated_at)+ SELECT c.id, CAST(e.key AS INTEGER), c.tenant_id, c.knowledge_base_id, c.knowledge_id,+ COALESCE(c.chunk_type, ''),+ COALESCE(NULLIF(json_extract(e.value, '$.url'), ''), NULLIF(json_extract(e.value, '$.original_url'), ''),+ c.id || '#' || e.key),+ COALESCE(json_extract(e.value, '$.url'), ''), COALESCE(json_extract(e.value, '$.original_url'), ''),+ COALESCE(json_extract(e.value, '$.caption'), ''), COALESCE(json_extract(e.value, '$.ocr_text'), ''),+ CASE WHEN json_type(e.value, '$.attrs.attrs') = 'object'+ THEN json_extract(e.value, '$.attrs.attrs') ELSE '{}' END,+ c.is_enabled, COALESCE(c.status, 0), c.created_at, c.updated_at+ FROM chunks c, json_each(CASE WHEN json_valid(c.image_info) AND json_type(c.image_info) = 'array' THEN c.image_info ELSE '[]' END) AS e+ WHERE c.deleted_at IS NULL AND e.type = 'object' AND c.image_info LIKE '[%';diff --git a/migrations/versioned/000113_chunk_images.down.sql b/migrations/versioned/000113_chunk_images.down.sqlnew file mode 100644index 000000000..1867502b8--- /dev/null+++ b/migrations/versioned/000113_chunk_images.down.sql@@ -0,0 +1,6 @@+DROP TRIGGER IF EXISTS trg_chunk_images_insert ON chunks;+DROP TRIGGER IF EXISTS trg_chunk_images_update ON chunks;+DROP TRIGGER IF EXISTS trg_chunk_images_delete ON chunks;+DROP FUNCTION IF EXISTS chunk_images_sync();+DROP FUNCTION IF EXISTS chunk_images_try_jsonb(TEXT);+DROP TABLE IF EXISTS chunk_images;diff --git a/migrations/versioned/000113_chunk_images.up.sql b/migrations/versioned/000113_chunk_images.up.sqlnew file mode 100644index 000000000..bc48e79d1--- /dev/null+++ b/migrations/versioned/000113_chunk_images.up.sql@@ -0,0 +1,177 @@+-- Migration 000113: chunk_images, the image gallery's projection of image_info+--+-- The gallery lists a knowledge base's images: one per URL, filtered by+-- caption / OCR text / observed attributes, sorted and paged. That data lives+-- as JSON inside chunks.image_info (one array per chunk, the same image+-- repeated on its image_ocr and image_caption children), so answering a page+-- from chunks means parsing every image chunk of the knowledge base.+--+-- chunk_images keeps one row per image_info entry with the fields split into+-- columns, and triggers on chunks keep it in step with every write path+-- (insert, edit, enable toggle, soft and hard delete, moving a document). It is+-- a plain projection: copies of one image stay separate rows, and the gallery+-- query picks the copy on the most recently updated chunk with an indexed+-- anti-join. Nothing is decided at write time, so concurrent writers of one+-- image need no coordination.++CREATE TABLE IF NOT EXISTS chunk_images (+ chunk_id VARCHAR(36) NOT NULL,+ image_index INTEGER NOT NULL,+ tenant_id BIGINT NOT NULL,+ knowledge_base_id VARCHAR(36) NOT NULL,+ knowledge_id VARCHAR(36) NOT NULL,+ chunk_type VARCHAR(20) NOT NULL DEFAULT '',+ -- url, else original_url, else "<chunk id>#<index>": what de-duplicates.+ image_key TEXT NOT NULL,+ url TEXT NOT NULL DEFAULT '',+ original_url TEXT NOT NULL DEFAULT '',+ caption TEXT NOT NULL DEFAULT '',+ ocr_text TEXT NOT NULL DEFAULT '',+ -- The observed attribute map (image_info[i].attrs.attrs).+ attrs JSONB NOT NULL DEFAULT '{}'::jsonb,+ is_enabled BOOLEAN NOT NULL DEFAULT true,+ status INTEGER NOT NULL DEFAULT 0,+ created_at TIMESTAMP WITH TIME ZONE,+ updated_at TIMESTAMP WITH TIME ZONE,+ PRIMARY KEY (chunk_id, image_index)+);++-- Listing in upload order, ties by chunk and position.+CREATE INDEX IF NOT EXISTS idx_chunk_images_listing+ ON chunk_images(knowledge_base_id, tenant_id, created_at, chunk_id, image_index);+-- The copies of one image, in the order that decides which one is listed.+CREATE INDEX IF NOT EXISTS idx_chunk_images_copies+ ON chunk_images(knowledge_base_id, tenant_id, image_key, updated_at, chunk_id, image_index);++-- chunk_images_try_jsonb parses image_info, or returns NULL for malformed+-- text so one bad row can neither fail a chunk write nor this backfill.+CREATE OR REPLACE FUNCTION chunk_images_try_jsonb(raw TEXT) RETURNS JSONB+LANGUAGE plpgsql IMMUTABLE AS $$+BEGIN+ IF raw IS NULL OR raw NOT LIKE '[%' THEN+ RETURN NULL;+ END IF;+ RETURN raw::jsonb;+EXCEPTION WHEN others THEN+ RETURN NULL;+END $$;++-- chunk_images_sync re-projects one chunk. An update that leaves the images+-- alone (status, enabled flag, timestamps) patches the rows in place; none of+-- those columns is text-indexed, so it costs no index churn. Anything else+-- replaces the chunk's rows.+CREATE OR REPLACE FUNCTION chunk_images_sync() RETURNS trigger+LANGUAGE plpgsql AS $$+DECLARE+ doc JSONB;+BEGIN+ IF TG_OP = 'UPDATE' AND OLD.deleted_at IS NULL AND NEW.deleted_at IS NULL+ AND OLD.image_info IS NOT DISTINCT FROM NEW.image_info+ AND OLD.tenant_id = NEW.tenant_id AND OLD.knowledge_base_id = NEW.knowledge_base_id+ AND OLD.knowledge_id = NEW.knowledge_id AND OLD.chunk_type IS NOT DISTINCT FROM NEW.chunk_type THEN+ UPDATE chunk_images+ SET is_enabled = NEW.is_enabled, status = COALESCE(NEW.status, 0),+ created_at = NEW.created_at, updated_at = NEW.updated_at+ WHERE chunk_id = NEW.id;+ RETURN NULL;+ END IF;++ IF TG_OP <> 'INSERT' THEN+ DELETE FROM chunk_images WHERE chunk_id = OLD.id;+ END IF;+ IF TG_OP <> 'DELETE' AND NEW.deleted_at IS NULL THEN+ doc := chunk_images_try_jsonb(NEW.image_info);+ IF jsonb_typeof(doc) = 'array' THEN+ INSERT INTO chunk_images (+ chunk_id, image_index, tenant_id, knowledge_base_id, knowledge_id, chunk_type,+ image_key, url, original_url, caption, ocr_text, attrs,+ is_enabled, status, created_at, updated_at+ )+ SELECT NEW.id, (e.idx - 1)::int, NEW.tenant_id, NEW.knowledge_base_id, NEW.knowledge_id,+ COALESCE(NEW.chunk_type, ''),+ COALESCE(NULLIF(e.img->>'url', ''), NULLIF(e.img->>'original_url', ''),+ NEW.id || '#' || (e.idx - 1)),+ COALESCE(e.img->>'url', ''), COALESCE(e.img->>'original_url', ''),+ COALESCE(e.img->>'caption', ''), COALESCE(e.img->>'ocr_text', ''),+ CASE WHEN jsonb_typeof(e.img->'attrs'->'attrs') = 'object'+ THEN e.img->'attrs'->'attrs' ELSE '{}'::jsonb END,+ NEW.is_enabled, COALESCE(NEW.status, 0), NEW.created_at, NEW.updated_at+ FROM jsonb_array_elements(doc) WITH ORDINALITY AS e(img, idx)+ WHERE jsonb_typeof(e.img) = 'object';+ END IF;+ END IF;+ RETURN NULL;+END $$;++DROP TRIGGER IF EXISTS trg_chunk_images_insert ON chunks;+CREATE TRIGGER trg_chunk_images_insert AFTER INSERT ON chunks+ FOR EACH ROW WHEN (NEW.image_info LIKE '[%')+ EXECUTE FUNCTION chunk_images_sync();++-- Only the columns the projection copies re-sync it; a chunk whose image_info+-- neither was nor becomes an array has nothing to project.+DROP TRIGGER IF EXISTS trg_chunk_images_update ON chunks;+CREATE TRIGGER trg_chunk_images_update AFTER UPDATE ON chunks+ FOR EACH ROW WHEN (+ (OLD.image_info LIKE '[%' OR NEW.image_info LIKE '[%') AND (+ OLD.image_info IS DISTINCT FROM NEW.image_info+ OR OLD.is_enabled IS DISTINCT FROM NEW.is_enabled+ OR OLD.status IS DISTINCT FROM NEW.status+ OR OLD.deleted_at IS DISTINCT FROM NEW.deleted_at+ OR OLD.tenant_id IS DISTINCT FROM NEW.tenant_id+ OR OLD.knowledge_base_id IS DISTINCT FROM NEW.knowledge_base_id+ OR OLD.knowledge_id IS DISTINCT FROM NEW.knowledge_id+ OR OLD.chunk_type IS DISTINCT FROM NEW.chunk_type+ OR OLD.created_at IS DISTINCT FROM NEW.created_at+ OR OLD.updated_at IS DISTINCT FROM NEW.updated_at+ )+ )+ EXECUTE FUNCTION chunk_images_sync();++DROP TRIGGER IF EXISTS trg_chunk_images_delete ON chunks;+CREATE TRIGGER trg_chunk_images_delete AFTER DELETE ON chunks+ FOR EACH ROW WHEN (OLD.image_info LIKE '[%')+ EXECUTE FUNCTION chunk_images_sync();++-- Backfill every live image chunk.+INSERT INTO chunk_images (+ chunk_id, image_index, tenant_id, knowledge_base_id, knowledge_id, chunk_type,+ image_key, url, original_url, caption, ocr_text, attrs,+ is_enabled, status, created_at, updated_at+)+SELECT c.id, (e.idx - 1)::int, c.tenant_id, c.knowledge_base_id, c.knowledge_id, COALESCE(c.chunk_type, ''),+ COALESCE(NULLIF(e.img->>'url', ''), NULLIF(e.img->>'original_url', ''), c.id || '#' || (e.idx - 1)),+ COALESCE(e.img->>'url', ''), COALESCE(e.img->>'original_url', ''),+ COALESCE(e.img->>'caption', ''), COALESCE(e.img->>'ocr_text', ''),+ CASE WHEN jsonb_typeof(e.img->'attrs'->'attrs') = 'object'+ THEN e.img->'attrs'->'attrs' ELSE '{}'::jsonb END,+ c.is_enabled, COALESCE(c.status, 0), c.created_at, c.updated_at+FROM chunks c+CROSS JOIN LATERAL jsonb_array_elements(+ CASE WHEN jsonb_typeof(chunk_images_try_jsonb(c.image_info)) = 'array'+ THEN chunk_images_try_jsonb(c.image_info) ELSE '[]'::jsonb END+) WITH ORDINALITY AS e(img, idx)+WHERE c.deleted_at IS NULL AND c.image_info LIKE '[%' AND jsonb_typeof(e.img) = 'object'+ON CONFLICT (chunk_id, image_index) DO NOTHING;++-- Keyword search over caption / OCR text uses trigram indexes when pg_trgm is+-- available. It is optional: without it (no permission to create extensions)+-- the search still works, as a scan. fastupdate is off so a bulk import is+-- searchable at full speed at once instead of after the next vacuum merges+-- the pending list.+DO $$+BEGIN+ CREATE EXTENSION IF NOT EXISTS pg_trgm;+EXCEPTION WHEN others THEN+ RAISE NOTICE '[Migration 000113] pg_trgm unavailable (%); gallery keyword search will scan', SQLERRM;+END $$;++DO $$+BEGIN+ IF EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm') THEN+ CREATE INDEX IF NOT EXISTS idx_chunk_images_caption_trgm+ ON chunk_images USING gin (caption gin_trgm_ops) WITH (fastupdate = off);+ CREATE INDEX IF NOT EXISTS idx_chunk_images_ocr_trgm+ ON chunk_images USING gin (ocr_text gin_trgm_ops) WITH (fastupdate = off);+ END IF;+END $$;diff --git a/website-docs/03-features/02-knowledge-base.md b/website-docs/03-features/02-knowledge-base.mdindex df56bf39a..85a1528ce 100644--- a/website-docs/03-features/02-knowledge-base.md+++ b/website-docs/03-features/02-knowledge-base.md@@ -127,7 +127,8 @@ graph TBKB --> EMB["EmbeddingModelID / SummaryModelID"]KB --> VLM["VLMConfig (视觉模型)"]KB --> ASR["ASRConfig (语音识别)"]- KB --> IMG["ImageProcessingConfig"]+ KB --> IMG["ImageProcessingConfig (图片理解)"]+ IMG --> ICP["ImageAttrsEnabled + ImageActions (属性观察 + 条件 OCR)"]KB --> EXT["ExtractConfig (知识图谱)"]KB --> FAQ["FAQConfig (仅 faq 类型)"]KB --> QG["QuestionGenerationConfig (问题生成)"]@@ -183,7 +184,32 @@ graph TB**ASRConfig**:`enabled` / `model_id` / `language`(语言提示,可选)。-**ImageProcessingConfig**:`model_id`。+**ImageProcessingConfig(图片属性观察与条件 OCR)**:++| 字段 | 类型 | 默认 | 说明 |+| --- | --- | --- | --- |+| `model_id` | string | - | 图片理解使用的 VLM 模型 ID(参与模型用量追踪) |+| `image_attrs_enabled` | bool | false | 图片属性观察管线开关。关闭(默认)=历史行为:每张图片各发一次描述请求、各发一次 OCR 请求,不做属性观察;开启后第一轮「属性观察+描述」,再由代码纯函数按观察结果决定该图是否值得再跑一轮 OCR |+| `image_actions` | object | 见下 | OCR 触发条件:`{ ocr: { on: ImageAttrCondition[], on_unobserved: bool } }`。`on` 为「属性=值」触发条件列表;`on_unobserved` 为属性未被模型观察时的保守兜底(默认 true=仍 OCR) |++开启 `image_attrs_enabled` 后,模型**不再对图片分类**,只逐项「观察」属性并产出描述。本期激活两个观察项(完整注册表见 `GET /api/v1/image-attrs/schema`,只读、需 Viewer 权限;该注册表是全局的,不随知识库变化):++| 属性 | 取值 | 含义 |+| --- | --- | --- |+| `contain.text` | `none` / `sparse` / `block` | 图内成段文字的密集程度。`block`=值得 OCR 的正文 |+| `contain.data_visual` | `true` / `false` | 是否含图表 / 数据可视化(轴标签等也可能含文字) |++OCR 决策是代码纯函数 `DecideOCR`(`internal/application/service/image_attr_decision.go`),不落库:++- 满足 `contain.text == block` **或** `contain.data_visual == true` → 跑 OCR;+- 策略读取到的属性**缺键**(模型漏答该行,或答了非法取值)→ 按 `on_unobserved` 兜底(默认仍 OCR);+- 全部属性都被观察到、且都不命中 → 跳过 OCR。++模型答非所问 / 属性缺失一律按兜底策略处理,观察失误只多花一次调用、不会丢内容。注意**属性缺键是正常结果**:观察失败时不会写入保守默认值(schema 版本 `attrs/2`),因此 `image_attrs` 可能为空对象,读取方需区分「未观察到」与「观察到了负值」。++管线与观察结果记录在每张图的处理轨迹子 span 上,便于核对与排查:input `pipeline` = `observation_driven`(本开关开启)或 `caption_ocr`(关闭,历史行为);output `attr_policy`(本轮 OCR 决策)、`image_attrs`(观察到的属性)、`ocr_skipped`(`attr_policy`=被策略跳过 / `disabled`=OCR 总开关关闭)、`observation_failed`(未形成有效观察)、`chunks_created`。++单次上传 / 重新解析可在请求体的 `process_config`(`KnowledgeProcessOverrides`)里按文档覆盖 `image_attrs_enabled` 与 `image_actions`;未传的项沿用知识库设置。`image_actions` 按 action key 合并(`on` 整体替换)。接口字段见[知识库 API](../04-api/02-api-knowledge.md),管线细节见[文档解析](03-document-parsing.md)。**QuestionGenerationConfig(问题生成)**:`enabled`;`question_count` 每分块生成问题数(默认 3,上限 10);`custom_instructions` 目标受众 / 风格说明。diff --git a/website-docs/03-features/03-document-parsing.md b/website-docs/03-features/03-document-parsing.mdindex 62dda5f44..7c462cd79 100644--- a/website-docs/03-features/03-document-parsing.md+++ b/website-docs/03-features/03-document-parsing.md@@ -307,7 +307,7 @@ docreader 侧的图片契约非常简单:每个解析器把图片以 `Document- unary `Read`:`_resolve_images()` 把全部图片 base64 解码为 `ImageRef.image_data` **内联字节**一次性返回(`image_dir_path` 恒为空——历史上"写共享卷目录"的模式已废弃,注释明确 *"The Go App is solely responsible for persisting images to the configured storage backend (local/minio/cos/tos)"*);- streaming `ReadStream`:`_iter_image_refs()` 逐张 yield,边发边 `pop` 释放内存。-Go 侧接手后(`internal/infrastructure/docparser/image_resolver.go`):将 inline bytes 上传对象存储、把 markdown 中的 `images/...` 引用重写为存储 URL;随后 `internal/application/service/image_multimodal.go` 依据 metadata 的 `image_source_type` 决策——`scanned_pdf` 的整页图走 OCR(带专用 `ocr_prompt`),普通插图走 VLM caption。知识库配置的图片解析自定义指令(`vlm_config.custom_instructions`)只追加到 caption 提示词,不进入 OCR 提示词,以免干扰 OCR 的输出约定(如无文字图片应回复 `No text content`)。+Go 侧接手后(`internal/infrastructure/docparser/image_resolver.go`):将 inline bytes 上传对象存储、把 markdown 中的 `images/...` 引用重写为存储 URL;随后 `internal/application/service/image_multimodal.go` 依据 metadata 的 `image_source_type` 决策——`scanned_pdf` 的整页图走 OCR(带专用 `ocr_prompt`),普通插图走 VLM caption。该服务有两条管线(处理轨迹里 `pipeline` 分别记为 `caption_ocr` / `observation_driven`):历史管线(KB 未开启 `image_attrs_enabled`)对每张图各发一次描述、各发一次 OCR;属性观察管线(开启后)第一轮先用同一张图的「属性观察+描述」结果确定属性(`contain.text` / `contain.data_visual`),再由代码纯函数 `DecideOCR` 按 KB 的 `image_actions` 决定该图是否值得再跑 OCR——`contain.text ∈ {sparse, none}` 且已确认观察、且 `data_visual == false` 的图默认只留描述、不花 OCR。两条管线的**图片理解都在 Go 侧**。知识库配置的图片解析自定义指令(`vlm_config.custom_instructions`)只追加到描述提示词(属性观察管线里即「属性观察+描述」提示词),不进入 OCR 提示词,以免干扰 OCR 的输出约定(如无文字图片应回复 `No text content`)。各解析引擎输出中的内联 HTML `<table>`(常见于 MinerU、PaddleOCR-VL 与 VLM OCR)会在分块前统一转换为 Markdown 表格;含合并单元格等无法转换的表格保留 HTML,但每行单独成行,保证分块器能在行边界切分。**docreader 内没有任何 VLM 调用**;`models/read_config.py` 中的 `vlm_config`/`storage_config` 字段只是为了老构造函数签名兼容而保留的空壳("Legacy config kept for backward compatibility")。diff --git a/website-docs/04-api/02-api-knowledge.md b/website-docs/04-api/02-api-knowledge.mdindex 2e97f7f2c..2327ad801 100644--- a/website-docs/04-api/02-api-knowledge.md+++ b/website-docs/04-api/02-api-knowledge.md@@ -21,7 +21,7 @@| `type` | string | 否 | `document`(默认)/`faq`/`wiki` || `embedding_model_id` | string | 否 | Embedding 模型 ID || `chunking_config` | object | 否 | 分块配置(chunk_size/overlap/separators/strategy…) |-| `image_processing_config` | object | 否 | 图像处理(多模态)配置 |+| `image_processing_config` | object | 否 | 图片属性观察配置:`model_id` / `image_attrs_enabled` / `image_actions`(`{ ocr: { on: [...], on_unobserved: bool } }`) || `storage_provider_config` | object | 否 | 存储配置 || `vector_store_id` | string | 否 | 向量库绑定(非法返回 code 2200/2201) || `faq_config` / `wiki_config` / `extract_config` / `indexing_strategy` | object | 否 | 类型相关配置 |