plugin-document-parser 1.0.1

package/src/client/plugin.tsx

@@ -0,0 +1,34 @@
+import { Plugin, lazy } from '@nocobase/client';
+import { NAMESPACE } from './locale';
+
+const SettingsPage = lazy(() => import('./components/SettingsPage'), 'SettingsPage');
+
+export class PluginDocumentParserClient extends Plugin {
+  async afterAdd() {
+    // Register locale
+    await this.app.i18n.changeLanguage(this.app.i18n.language);
+  }
+
+  async load() {
+    // Add locale resources
+    const locale = this.app.i18n.language || 'en-US';
+    try {
+      const messages = await import(`../locale/${locale}.json`).catch(
+        () => import('../locale/en-US.json'),
+      );
+      this.app.i18n.addResourceBundle(locale, NAMESPACE, messages.default || messages, true, true);
+    } catch {
+      // Locale file may not exist for this language — silently skip
+    }
+
+    // Register the settings page under Plugin Settings
+    this.app.pluginSettingsManager.add(NAMESPACE, {
+      title: '{{t("Document Parser", { ns: "' + NAMESPACE + '" })}}',
+      icon: 'FileTextOutlined',
+      Component: SettingsPage,
+      aclSnippet: `pm.${NAMESPACE}.settings`,
+    });
+  }
+}
+
+export default PluginDocumentParserClient;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './server';
+export { default } from './server';

package/src/locale/en-US.json

@@ -0,0 +1,54 @@
+{
+  "Document Parser": "Document Parser",
+  "Processing Mode": "Processing Mode",
+  "Default (plugin-ai built-in)": "Default (plugin-ai built-in)",
+  "Internal (built-in document loaders)": "Internal (built-in document loaders)",
+  "External (OCR API provider)": "External (OCR API provider)",
+  "Active Provider": "Active Provider",
+  "Fallback to default on error": "Fallback to default on error",
+  "Pass images through to default": "Pass images through to default",
+  "OCR Providers": "OCR Providers",
+  "Add Provider": "Add Provider",
+  "Edit Provider": "Edit Provider",
+  "Delete Provider": "Delete Provider",
+  "Test Connection": "Test Connection",
+  "Provider Title": "Provider Title",
+  "API Endpoint": "API Endpoint",
+  "API Key": "API Key",
+  "Auth Type": "Auth Type",
+  "Bearer Token": "Bearer Token",
+  "API Key Header": "API Key Header",
+  "Basic Auth": "Basic Auth",
+  "Custom Header": "Custom Header",
+  "Header Name": "Header Name",
+  "Username": "Username",
+  "Password": "Password",
+  "Custom Headers": "Custom Headers",
+  "Request Format": "Request Format",
+  "Multipart Form Data": "Multipart Form Data",
+  "JSON Base64": "JSON Base64",
+  "Form Field Name": "Form Field Name",
+  "Base64 Field Path": "Base64 Field Path",
+  "Filename Field Path": "Filename Field Path",
+  "Mimetype Field Path": "Mimetype Field Path",
+  "Extra Request Body": "Extra Request Body",
+  "Response Text Path": "Response Text Path",
+  "Timeout (ms)": "Timeout (ms)",
+  "Supported MIME Types": "Supported MIME Types",
+  "Leave empty to handle all non-image types": "Leave empty to handle all non-image types",
+  "Connection successful": "Connection successful",
+  "Connection failed": "Connection failed",
+  "Global Settings": "Global Settings",
+  "Provider Configuration": "Provider Configuration",
+  "Enabled": "Enabled",
+  "No providers configured": "No providers configured",
+  "Please select a provider": "Please select a provider",
+  "Settings saved": "Settings saved",
+  "Provider saved": "Provider saved",
+  "Provider deleted": "Provider deleted",
+  "mode_default_desc": "Use the built-in attachment processing from plugin-ai (default behavior).",
+  "mode_internal_desc": "Parse documents using built-in loaders (PDF, DOCX, PPT, TXT) or custom parsers registered by other plugins.",
+  "mode_external_desc": "Send files to a configured external OCR/parse API and use the returned text as attachment content.",
+  "Index with DocPixie (when available)": "Index with DocPixie (when available)",
+  "docpixie_mode_desc": "When plugin-docpixie is active, automatically index attached documents and instruct the AI to use the docpixie:query tool instead of reading raw file content. Applies before the processing mode above."
+}

package/src/locale/vi-VN.json

@@ -0,0 +1,54 @@
+{
+  "Document Parser": "Trình xử lý tài liệu",
+  "Processing Mode": "Chế độ xử lý",
+  "Default (plugin-ai built-in)": "Mặc định (plugin-ai tích hợp sẵn)",
+  "Internal (built-in document loaders)": "Nội bộ (trình đọc tài liệu tích hợp)",
+  "External (OCR API provider)": "Bên ngoài (nhà cung cấp OCR API)",
+  "Active Provider": "Nhà cung cấp đang dùng",
+  "Fallback to default on error": "Dùng mặc định khi lỗi",
+  "Pass images through to default": "Chuyển hình ảnh qua xử lý mặc định",
+  "OCR Providers": "Nhà cung cấp OCR",
+  "Add Provider": "Thêm nhà cung cấp",
+  "Edit Provider": "Chỉnh sửa nhà cung cấp",
+  "Delete Provider": "Xóa nhà cung cấp",
+  "Test Connection": "Kiểm tra kết nối",
+  "Provider Title": "Tên nhà cung cấp",
+  "API Endpoint": "Địa chỉ API",
+  "API Key": "Khóa API",
+  "Auth Type": "Loại xác thực",
+  "Bearer Token": "Bearer Token",
+  "API Key Header": "Header API Key",
+  "Basic Auth": "Basic Auth",
+  "Custom Header": "Header tùy chỉnh",
+  "Header Name": "Tên header",
+  "Username": "Tên đăng nhập",
+  "Password": "Mật khẩu",
+  "Custom Headers": "Headers tùy chỉnh",
+  "Request Format": "Định dạng yêu cầu",
+  "Multipart Form Data": "Multipart Form Data",
+  "JSON Base64": "JSON Base64",
+  "Form Field Name": "Tên trường form",
+  "Base64 Field Path": "Đường dẫn trường Base64",
+  "Filename Field Path": "Đường dẫn tên file",
+  "Mimetype Field Path": "Đường dẫn MIME type",
+  "Extra Request Body": "Body yêu cầu thêm",
+  "Response Text Path": "Đường dẫn text trong phản hồi",
+  "Timeout (ms)": "Timeout (ms)",
+  "Supported MIME Types": "MIME Types được hỗ trợ",
+  "Leave empty to handle all non-image types": "Để trống để xử lý tất cả loại không phải ảnh",
+  "Connection successful": "Kết nối thành công",
+  "Connection failed": "Kết nối thất bại",
+  "Global Settings": "Cài đặt chung",
+  "Provider Configuration": "Cấu hình nhà cung cấp",
+  "Enabled": "Kích hoạt",
+  "No providers configured": "Chưa có nhà cung cấp nào",
+  "Please select a provider": "Vui lòng chọn nhà cung cấp",
+  "Settings saved": "Đã lưu cài đặt",
+  "Provider saved": "Đã lưu nhà cung cấp",
+  "Provider deleted": "Đã xóa nhà cung cấp",
+  "Index with DocPixie (when available)": "Lập chỉ mục qua DocPixie (nếu có)",
+  "docpixie_mode_desc": "Khi plugin-docpixie đang hoạt động, tự động lập chỉ mục tài liệu đính kèm và hướng dẫn AI dùng công cụ docpixie:query thay vì đọc nội dung thô. Được áp dụng trước chế độ xử lý bên trên.",
+  "mode_default_desc": "Dùng chức năng xử lý tệp đính kèm mặc định của plugin-ai.",
+  "mode_internal_desc": "Phân tích tài liệu dùng trình đọc tích hợp (PDF, DOCX, PPT, TXT) hoặc các parser tùy chỉnh từ plugin khác.",
+  "mode_external_desc": "Gửi tệp đến API OCR/parse bên ngoài đã cấu hình và dùng văn bản trả về làm nội dung đính kèm."
+}

package/src/server/collections/doc-parser-providers.ts

@@ -0,0 +1,107 @@
+import { defineCollection } from '@nocobase/database';
+
+/**
+ * External OCR/document-parse API provider configurations.
+ *
+ * Each provider describes HOW to call an external service:
+ *   - authentication (bearer / api-key-header / basic / custom-headers)
+ *   - request format (multipart | json-base64)
+ *   - response text extraction (dot-path into JSON response)
+ */
+export default defineCollection({
+  name: 'docParserProviders',
+  title: 'Document Parser Providers',
+  fields: [
+    {
+      name: 'title',
+      type: 'string',
+    },
+    {
+      name: 'enabled',
+      type: 'boolean',
+      defaultValue: true,
+    },
+    // ── Endpoint ──────────────────────────────────────────────────────────────
+    {
+      name: 'apiEndpoint',
+      type: 'string',
+      comment: 'Full URL, e.g. https://ocr.example.com/v1/parse',
+    },
+    // ── Authentication ────────────────────────────────────────────────────────
+    {
+      name: 'authType',
+      type: 'string',
+      defaultValue: 'bearer',
+      comment: "'bearer' | 'api-key-header' | 'basic' | 'custom-headers' | 'none'",
+    },
+    {
+      // Encrypted at rest via NocoBase password field
+      name: 'apiKey',
+      type: 'password',
+      allowNull: true,
+      comment: 'Used for bearer / api-key-header auth',
+    },
+    {
+      name: 'authConfig',
+      type: 'json',
+      defaultValue: {},
+      comment: JSON.stringify({
+        headerName: 'X-Api-Key',       // for api-key-header
+        username: '',                   // for basic auth
+        password: '',                   // for basic auth
+        customHeaders: {},              // for custom-headers: { "X-Foo": "bar" }
+      }),
+    },
+    // ── Request format ────────────────────────────────────────────────────────
+    {
+      name: 'requestFormat',
+      type: 'string',
+      defaultValue: 'multipart',
+      comment: "'multipart' | 'json-base64' | 'url'",
+    },
+    {
+      name: 'requestConfig',
+      type: 'json',
+      defaultValue: {},
+      comment: JSON.stringify({
+        // multipart
+        fileFieldName: 'file',
+        filenameFieldName: '',     // optional extra field for filename
+        mimetypeFieldName: '',     // optional extra field for mimetype
+        extraFields: {},           // extra form fields
+        // json-base64
+        base64FieldPath: 'file',   // e.g. "document.content"
+        filenameFieldPath: 'filename',
+        mimetypeFieldPath: 'mimetype',
+        extraBody: {},
+        // url (send download URL instead of file bytes)
+        urlFieldPath: 'url',
+      }),
+    },
+    // ── Response extraction ───────────────────────────────────────────────────
+    {
+      name: 'responseTextPath',
+      type: 'string',
+      defaultValue: 'text',
+      comment: "Dot-path into the JSON response body, e.g. 'data.text' or 'result.pages[0].content'",
+    },
+    // ── Scope ─────────────────────────────────────────────────────────────────
+    {
+      name: 'supportedMimetypes',
+      type: 'json',
+      defaultValue: [],
+      comment: 'Empty = handle everything routed to external. e.g. ["application/pdf"]',
+    },
+    {
+      name: 'timeout',
+      type: 'integer',
+      defaultValue: 60000,
+      comment: 'HTTP request timeout in milliseconds',
+    },
+    {
+      name: 'options',
+      type: 'json',
+      defaultValue: {},
+    },
+  ],
+});

package/src/server/collections/doc-parser-settings.ts

@@ -0,0 +1,59 @@
+import { defineCollection } from '@nocobase/database';
+
+/**
+ * Global settings for the document parser plugin.
+ * Single-row config table (only one record expected).
+ */
+export default defineCollection({
+  name: 'docParserSettings',
+  title: 'Document Parser Settings',
+  fields: [
+    {
+      name: 'mode',
+      type: 'string',
+      defaultValue: 'default',
+      comment: "'default' | 'internal' | 'external'",
+    },
+    {
+      // FK to docParserProviders — which external provider is active
+      name: 'activeProviderId',
+      type: 'bigInt',
+      allowNull: true,
+    },
+    {
+      // When internal/external parsing fails, fall back to the default provider logic
+      name: 'fallbackToDefault',
+      type: 'boolean',
+      defaultValue: true,
+    },
+    {
+      // Images are always passed through to the default provider (they don't need OCR)
+      name: 'imagePassThrough',
+      type: 'boolean',
+      defaultValue: true,
+    },
+    {
+      // Optional: restrict which extnames this plugin handles (empty = all non-image)
+      name: 'includedExtnames',
+      type: 'json',
+      defaultValue: [],
+      comment: 'e.g. [".pdf", ".docx"] — empty means all non-image files',
+    },
+    {
+      name: 'options',
+      type: 'json',
+      defaultValue: {},
+    },
+    {
+      /**
+       * When true and plugin-docpixie is active:
+       * - Trigger docpixie:processDocument (async indexing)
+       * - Return a metadata reference block instead of full text
+       * - LLM is instructed to call docpixie:query tool for retrieval
+       */
+      name: 'useDocpixie',
+      type: 'boolean',
+      defaultValue: false,
+    },
+  ],
+});

package/src/server/index.ts

@@ -0,0 +1,10 @@
+export { default } from './plugin';
+export { PluginDocumentParserServer } from './plugin';
+export { InternalParserRegistry } from './services/internal-parser-registry';
+export type {
+  InternalParserHandler,
+  InternalParseResult,
+  AttachmentLike,
+} from './services/internal-parser-registry';
+export type { OcrProviderConfig, OcrAuthType, OcrRequestFormat } from './services/external-ocr-client';
+export type { ParsedAttachmentResult } from './services/parse-router';

package/src/server/plugin.ts

@@ -0,0 +1,172 @@
+import { Plugin } from '@nocobase/server';
+import { resolve } from 'path';
+import { Context } from '@nocobase/actions';
+import axios from 'axios';
+import { InternalParserRegistry } from './services/internal-parser-registry';
+import { BuiltinAIDocumentHandler } from './services/builtin-ai-handler';
+import { ParseRouter } from './services/parse-router';
+import { testConnection, getSettings, saveSettings } from './resource/docParserProviders';
+import type { AttachmentLike } from './services/internal-parser-registry';
+
+export class PluginDocumentParserServer extends Plugin {
+  /**
+   * Public registry — other plugins register their format handlers here:
+   *
+   *   const docParser = this.pm.get(PluginDocumentParserServer);
+   *   docParser.internalParserRegistry.register({ name, supports, parse });
+   */
+  readonly internalParserRegistry = new InternalParserRegistry();
+
+  parseRouter!: ParseRouter;
+
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+
+  async beforeLoad() {
+    // Register the built-in AI document handler (lowest priority — appended last)
+    // Done in beforeLoad so other plugins' load() can prepend higher-priority handlers
+    this.internalParserRegistry.register(
+      new BuiltinAIDocumentHandler(() => {
+        const aiPlugin = this.pm.get('@nocobase/plugin-ai') as any;
+        return aiPlugin?.documentLoaders;
+      }),
+    );
+  }
+
+  async load() {
+    // 1. Load collections
+    await this.importCollections(resolve(__dirname, 'collections'));
+
+    // 2. Wire up the parse router
+    this.parseRouter = new ParseRouter(
+      () => this.db.getRepository('docParserSettings'),
+      () => this.db.getRepository('docParserProviders'),
+      this.internalParserRegistry,
+      this.fetchFileBuffer.bind(this),
+      () => {
+        const p = this.pm.get('@nocobase/plugin-docpixie') as any;
+        return p?.service ? p : null;
+      },
+    );
+
+    // 3. Patch AIManager to intercept parseAttachment on ALL providers
+    this.wrapAIManager();
+
+    // 4. Register resources
+    this.app.resourceManager.define({
+      name: 'docParserProviders',
+      actions: {
+        testConnection,
+      },
+    });
+
+    this.app.resourceManager.define({
+      name: 'docParserSettings',
+      actions: {
+        get: getSettings,
+        save: saveSettings,
+      },
+    });
+
+    // 5. ACL — allow admins to manage settings & providers
+    this.app.acl.allow('docParserProviders', ['list', 'create', 'update', 'destroy', 'get', 'testConnection'], 'loggedIn');
+    this.app.acl.allow('docParserSettings', ['get', 'save'], 'loggedIn');
+  }
+
+  // ── AIManager patching ────────────────────────────────────────────────────
+
+  /**
+   * Wrap AIManager.registerLLMProvider so that every provider class — including
+   * those registered AFTER this plugin loads (e.g. plugin-custom-llm) — gets
+   * its `parseAttachment` intercepted.
+   *
+   * Additionally, iterate providers already registered (plugin-ai built-ins:
+   * OpenAI, Anthropic, etc.) and wrap them immediately.
+   */
+  private wrapAIManager() {
+    const aiPlugin = this.pm.get('@nocobase/plugin-ai') as any;
+    if (!aiPlugin?.aiManager) {
+      this.log.warn('[DocumentParser] plugin-ai not found — parseAttachment interception skipped');
+      return;
+    }
+
+    const aiManager = aiPlugin.aiManager;
+    const self = this;
+
+    // Wrap the registration method (future registrations)
+    const originalRegister = aiManager.registerLLMProvider.bind(aiManager);
+    aiManager.registerLLMProvider = (name: string, meta: any) => {
+      return originalRegister(name, { ...meta, provider: self.wrapProviderClass(meta.provider) });
+    };
+
+    // Wrap already-registered providers (built-ins)
+    for (const [name, meta] of aiManager.llmProviders.entries()) {
+      aiManager.llmProviders.set(name, { ...meta, provider: self.wrapProviderClass(meta.provider) });
+    }
+
+    this.log.info(`[DocumentParser] Wrapped ${aiManager.llmProviders.size} LLM providers`);
+  }
+
+  /**
+   * Create a subclass of `OriginalProviderClass` that overrides `parseAttachment`
+   * to go through our router first.  Uses `super.parseAttachment` as the default
+   * parser fallback — this correctly handles providers that already override the
+   * method (e.g. CustomLLMProvider, AnthropicProvider…).
+   */
+  private wrapProviderClass(OriginalClass: new (...args: any[]) => any) {
+    const self = this;
+    return class extends OriginalClass {
+      async parseAttachment(ctx: Context, attachment: any) {
+        return self.parseRouter.route(ctx, attachment, () =>
+          super.parseAttachment(ctx, attachment),
+        );
+      }
+    };
+  }
+
+  // ── File buffer helper ────────────────────────────────────────────────────
+
+  /**
+   * Fetch the raw bytes of an attachment using the file-manager plugin,
+   * returning both the buffer and the resolved URL.
+   */
+  private async fetchFileBuffer(
+    ctx: Context,
+    attachment: AttachmentLike,
+  ): Promise<{ buffer: Buffer; url: string }> {
+    const fileManager = this.app.pm.get('file-manager') as any;
+    const rawUrl: string = await fileManager.getFileURL(attachment);
+    const url = decodeURIComponent(rawUrl);
+
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+      const referer = ctx.get?.('referer') || '';
+      const ua = ctx.get?.('user-agent') || '';
+      const response = await axios.get(url, {
+        responseType: 'arraybuffer',
+        timeout: 60_000,
+        headers: { referer, 'User-Agent': ua },
+      });
+      return { buffer: Buffer.from(response.data), url };
+    }
+
+    // Local file — strip APP_PUBLIC_PATH before joining
+    const { resolve: resolvePath, sep } = require('path');
+    const { readFile } = require('fs/promises');
+
+    let localPath = url;
+    const appPublicPath = (process.env.APP_PUBLIC_PATH || '/').replace(/\/+$/, '');
+    if (appPublicPath && localPath.startsWith(appPublicPath + '/')) {
+      localPath = localPath.slice(appPublicPath.length);
+    }
+
+    const storageRoot = resolvePath(process.cwd());
+    const absPath = resolvePath(storageRoot, localPath.replace(/^\//, ''));
+    if (!absPath.startsWith(storageRoot + sep) && absPath !== storageRoot) {
+      throw new Error(`[DocumentParser] Attachment path escapes storage root: ${localPath}`);
+    }
+
+    const buffer = await readFile(absPath);
+    return { buffer, url };
+  }
+}
+
+export default PluginDocumentParserServer;

package/src/server/resource/docParserProviders.ts

@@ -0,0 +1,72 @@
+import { Context, Next } from '@nocobase/actions';
+import { testOcrProviderConnection } from '../services/external-ocr-client';
+
+/**
+ * Extra actions for the docParserProviders resource.
+ * Standard CRUD (list/create/update/destroy/get) is handled by NocoBase's
+ * default resource manager — we only need to add the custom `testConnection`.
+ */
+
+export async function testConnection(ctx: Context, next: Next) {
+  const { filterByTk } = ctx.action.params;
+
+  const repo = ctx.db.getRepository('docParserProviders');
+  const record = await repo.findById(filterByTk);
+
+  if (!record) {
+    ctx.throw(404, 'Provider not found');
+    return;
+  }
+
+  const result = await testOcrProviderConnection({
+    apiEndpoint: record.get('apiEndpoint'),
+    authType: record.get('authType'),
+    apiKey: record.get('apiKey'),
+    authConfig: record.get('authConfig') ?? {},
+    timeout: Math.min(record.get('timeout') ?? 10000, 15000), // cap at 15s for test
+  });
+
+  ctx.body = result;
+  await next();
+}
+
+/**
+ * Get/update the single global settings record.
+ * Returns existing record or auto-creates with defaults.
+ */
+export async function getSettings(ctx: Context, next: Next) {
+  const repo = ctx.db.getRepository('docParserSettings');
+  let record = await repo.findOne({});
+  if (!record) {
+    record = await repo.create({
+      values: {
+        mode: 'default',
+        fallbackToDefault: true,
+        imagePassThrough: true,
+        includedExtnames: [],
+      },
+    });
+  }
+  ctx.body = record;
+  await next();
+}
+
+export async function saveSettings(ctx: Context, next: Next) {
+  const repo = ctx.db.getRepository('docParserSettings');
+  const body = ctx.request.body as Record<string, any>;
+
+  let record = await repo.findOne({});
+  if (!record) {
+    record = await repo.create({ values: body });
+  } else {
+    await repo.update({ filter: { id: record.get('id') }, values: body });
+    record = await repo.findOne({});
+  }
+
+  // Invalidate the router's settings cache
+  const plugin = ctx.app.pm.get('@nocobase/plugin-document-parser') as any;
+  plugin?.parseRouter?.invalidateSettingsCache?.();
+
+  ctx.body = record;
+  await next();
+}

package/src/server/services/builtin-ai-handler.ts

@@ -0,0 +1,49 @@
+import { Context } from '@nocobase/actions';
+import type { InternalParserHandler, InternalParseResult, AttachmentLike } from './internal-parser-registry';
+
+// Extnames that plugin-ai's CachedDocumentLoader natively handles
+const AI_SUPPORTED_EXTNAMES = new Set(['.pdf', '.ppt', '.pptx', '.doc', '.docx', '.txt']);
+
+/**
+ * Built-in internal parser handler that delegates to plugin-ai's
+ * `DocumentLoaders.cached` — the same infrastructure used by the
+ * Knowledge Base feature.
+ *
+ * This handler is registered automatically during plugin load with the
+ * lowest priority (appended last) so custom handlers from other plugins
+ * can take precedence.
+ */
+export class BuiltinAIDocumentHandler implements InternalParserHandler {
+  readonly name = 'builtin-ai-document-loader';
+
+  constructor(
+    /** Lazy getter — resolved at call time to avoid circular dep during init */
+    private readonly getDocumentLoaders: () => { cached: { load(file: any): Promise<any> } },
+  ) {}
+
+  supports(attachment: AttachmentLike): boolean {
+    const ext = this.resolveExtname(attachment);
+    return AI_SUPPORTED_EXTNAMES.has(ext);
+  }
+
+  async parse(attachment: AttachmentLike, _ctx: Context): Promise<InternalParseResult> {
+    const loaders = this.getDocumentLoaders();
+    const result = await loaders.cached.load(attachment);
+
+    if (!result.supported) {
+      return { text: '', handled: false };
+    }
+
+    return {
+      text: result.text ?? '',
+      handled: true,
+    };
+  }
+
+  private resolveExtname(attachment: AttachmentLike): string {
+    if (attachment.extname) return attachment.extname.toLowerCase();
+    const name = attachment.filename ?? attachment.name ?? '';
+    const idx = name.lastIndexOf('.');
+    return idx >= 0 ? name.slice(idx).toLowerCase() : '';
+  }
+}