hexo-semantic-search-ai 1.0.0

package/index.js

@@ -0,0 +1,201 @@
+/* global hexo */
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const SemanticSearchClient = require('./lib/client');
+const SyncManager = require('./lib/sync');
+const RelatedPostsManager = require('./lib/related');
+const { registerHelpers } = require('./lib/helpers');
+
+/**
+ * hexo-semantic-search-ai
+ *
+ * A Hexo plugin that integrates SemanticSearch for:
+ * - Automatic post indexing with incremental sync
+ * - Related posts generation at build time
+ * - Frontend search component
+ */
+
+const PLUGIN_NAME = 'semantic_search';
+
+// Get config
+const config = hexo.config[PLUGIN_NAME] || {};
+
+// Skip if not enabled
+if (config.enable === false) {
+  hexo.log.debug('[SemanticSearch] Plugin disabled by config');
+} else {
+  // Validate required config
+  const endpoint = config.endpoint;
+  const writerKey = resolveEnvVar(config.writer_key || config.writerKey);
+  const readerKey = resolveEnvVar(config.reader_key || config.readerKey);
+
+  if (!endpoint) {
+    hexo.log.warn('[SemanticSearch] No endpoint configured, plugin disabled');
+  } else {
+    hexo.log.debug('[SemanticSearch] Plugin initializing...');
+
+    // Create client
+    const client = new SemanticSearchClient({
+      endpoint,
+      writerKey,
+      readerKey,
+      timeout: config.timeout || 30000
+    });
+
+    // Create managers
+    const syncManager = new SyncManager(hexo, client, {
+      fields: config.sync?.fields || ['title', 'content', 'excerpt', 'tags', 'categories']
+    });
+
+    const relatedConfig = config.related_posts || config.relatedPosts || {};
+    const relatedManager = new RelatedPostsManager(hexo, client, {
+      limit: relatedConfig.limit || 5,
+      minScore: relatedConfig.min_score || relatedConfig.minScore || 0.3,
+      queryFields: relatedConfig.query_fields || relatedConfig.queryFields || ['title', 'excerpt']
+    });
+
+    // Register helpers
+    registerHelpers(hexo, config);
+
+    // Copy assets to public folder
+    hexo.extend.generator.register('semantic_search_assets', function() {
+      const assetPath = path.join(__dirname, 'assets', 'semantic-search.js');
+      const content = fs.readFileSync(assetPath, 'utf-8');
+
+      return {
+        path: 'js/semantic-search.js',
+        data: content
+      };
+    });
+
+    const autoSync = config.sync?.auto !== false;
+    const relatedEnabled = (relatedConfig.enable !== false) && readerKey;
+
+    // Hook: after_generate - sync posts after all content is generated
+    if (autoSync && writerKey) {
+      hexo.extend.filter.register('after_generate', async function() {
+        try {
+          hexo.log.info('[SemanticSearch] Syncing posts to index...');
+          await syncManager.sync();
+        } catch (error) {
+          hexo.log.error(`[SemanticSearch] Sync failed: ${error.message}`);
+        }
+      });
+    }
+
+    // Hook: after_post_render - fetch related posts with caching and rate limiting
+    // Note: Related posts require posts to already be indexed (from previous builds)
+    // Uses persistent cache to skip API calls for unchanged posts
+    if (relatedEnabled) {
+      // Track pending requests for rate limiting
+      let pendingRequests = 0;
+      const maxConcurrent = 3;
+      const requestQueue = [];
+
+      const processQueue = async () => {
+        while (requestQueue.length > 0 && pendingRequests < maxConcurrent) {
+          const { post, resolve } = requestQueue.shift();
+          pendingRequests++;
+          try {
+            const related = await relatedManager.getRelatedPostsWithCache(post);
+            post.semantic_related = related;
+            resolve(related);
+          } catch (error) {
+            resolve([]);
+          } finally {
+            pendingRequests--;
+            processQueue();
+          }
+        }
+      };
+
+      hexo.extend.filter.register('after_post_render', function(data) {
+        if (data.layout === 'post' || data.layout === 'page') {
+          return new Promise(resolve => {
+            requestQueue.push({
+              post: data,
+              resolve: () => resolve(data)
+            });
+            processQueue();
+          });
+        }
+        return data;
+      });
+
+      // Save cache after generation
+      hexo.extend.filter.register('after_generate', function() {
+        relatedManager.saveCache();
+      });
+    }
+
+    // Command: hexo semantic-search sync
+    hexo.extend.console.register('semantic-search', 'SemanticSearch commands', {
+      usage: '<command>',
+      desc: 'SemanticSearch plugin commands',
+      arguments: [
+        { name: 'command', desc: 'sync | full-sync | status' }
+      ],
+      options: [
+        { name: '--force', desc: 'Force full sync (ignore state)' }
+      ]
+    }, async function(args) {
+      const command = args._[0] || 'sync';
+
+      // Load source files first
+      await hexo.load();
+
+      switch (command) {
+        case 'sync':
+          if (args.force) {
+            hexo.log.info('[SemanticSearch] Running full sync (--force)...');
+            await syncManager.fullSync();
+          } else {
+            hexo.log.info('[SemanticSearch] Running incremental sync...');
+            await syncManager.sync();
+          }
+          break;
+
+        case 'full-sync':
+          hexo.log.info('[SemanticSearch] Running full sync...');
+          await syncManager.fullSync();
+          break;
+
+        case 'status':
+          const state = syncManager.state;
+          const tracked = state.getTrackedSlugs();
+          hexo.log.info(`[SemanticSearch] Tracked posts: ${tracked.length}`);
+          tracked.forEach(slug => {
+            const data = state.state.posts[slug];
+            hexo.log.info(`  - ${slug} (synced: ${data.syncedAt})`);
+          });
+          break;
+
+        default:
+          hexo.log.error(`[SemanticSearch] Unknown command: ${command}`);
+          hexo.log.info('Available commands: sync, full-sync, status');
+      }
+    });
+
+    hexo.log.debug('[SemanticSearch] Plugin initialized');
+  }
+}
+
+/**
+ * Resolve environment variable reference
+ * Supports: ${VAR_NAME} or $VAR_NAME
+ */
+function resolveEnvVar(value) {
+  if (!value || typeof value !== 'string') {
+    return value;
+  }
+
+  // Match ${VAR_NAME} or $VAR_NAME
+  const envMatch = value.match(/^\$\{?([A-Z_][A-Z0-9_]*)\}?$/);
+  if (envMatch) {
+    return process.env[envMatch[1]] || value;
+  }
+
+  return value;
+}

package/lib/client.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * SemanticSearch API Client
+ */
+class SemanticSearchClient {
+  constructor(options) {
+    this.endpoint = options.endpoint?.replace(/\/$/, '');
+    this.writerKey = options.writerKey;
+    this.readerKey = options.readerKey;
+    this.timeout = options.timeout || 30000;
+  }
+
+  async _request(method, path, body, useWriterKey = true) {
+    const url = `${this.endpoint}${path}`;
+    const key = useWriterKey ? this.writerKey : this.readerKey;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${key}`
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`SemanticSearch API error: ${response.status} - ${error}`);
+      }
+
+      const contentType = response.headers.get('content-type');
+      if (contentType?.includes('application/json')) {
+        return await response.json();
+      }
+      return await response.text();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`SemanticSearch API timeout after ${this.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create or update a document
+   * SemanticSearch API format: POST /v1/documents with { id, text, metadata }
+   */
+  async upsertDocument(id, document) {
+    // Get text content, use title as fallback if no content
+    const text = document.content || document.text || document.title || '';
+
+    // Skip if no meaningful text
+    if (!text || text.trim().length < 10) {
+      throw new Error('Document text is too short or empty');
+    }
+
+    // Transform to SemanticSearch format
+    const payload = {
+      id,
+      text,
+      metadata: {
+        title: document.title,
+        url: document.url,
+        date: document.date,
+        updated: document.updated,
+        excerpt: document.excerpt,
+        tags: document.tags,
+        categories: document.categories
+      }
+    };
+    return this._request('POST', '/v1/documents', payload);
+  }
+
+  /**
+   * Delete a document
+   */
+  async deleteDocument(id) {
+    return this._request('DELETE', `/v1/documents/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * Get a document by ID
+   */
+  async getDocument(id) {
+    return this._request('GET', `/v1/documents/${encodeURIComponent(id)}`, null, false);
+  }
+
+  /**
+   * Search documents
+   */
+  async search(query, options = {}) {
+    return this._request('POST', '/v1/search', {
+      query,
+      limit: options.limit || 10,
+      ...options
+    }, false);
+  }
+
+  /**
+   * Batch upsert documents
+   */
+  async batchUpsert(documents) {
+    // If the API supports batch, use it; otherwise do sequentially
+    const results = [];
+    for (const doc of documents) {
+      try {
+        const result = await this.upsertDocument(doc.id, doc.data);
+        results.push({ id: doc.id, success: true, result });
+      } catch (error) {
+        results.push({ id: doc.id, success: false, error: error.message });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Batch delete documents
+   */
+  async batchDelete(ids) {
+    const results = [];
+    for (const id of ids) {
+      try {
+        await this.deleteDocument(id);
+        results.push({ id, success: true });
+      } catch (error) {
+        results.push({ id, success: false, error: error.message });
+      }
+    }
+    return results;
+  }
+}
+
+module.exports = SemanticSearchClient;

package/lib/helpers.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Register Hexo helpers for semantic search
+ */
+function registerHelpers(hexo, config) {
+  const readerKey = config.reader_key || config.readerKey;
+  const endpoint = config.endpoint?.replace(/\/$/, '');
+
+  /**
+   * Output search config as JSON for frontend
+   */
+  hexo.extend.helper.register('semantic_search_config', function() {
+    return JSON.stringify({
+      endpoint,
+      readerKey,
+      placeholder: config.search?.placeholder || 'Search...'
+    });
+  });
+
+  /**
+   * Render search box HTML
+   */
+  hexo.extend.helper.register('semantic_search_box', function(options = {}) {
+    const id = options.id || 'semantic-search';
+    const placeholder = options.placeholder || config.search?.placeholder || 'Search...';
+    const className = options.class || 'semantic-search-box';
+    const resultClass = options.resultClass || 'semantic-search-results';
+
+    return `
+<div class="${className}" id="${id}">
+  <input type="text" class="semantic-search-input" placeholder="${placeholder}" />
+  <div class="${resultClass}"></div>
+</div>
+<script>
+  window.SEMANTIC_SEARCH_CONFIG = ${JSON.stringify({ endpoint, readerKey })};
+</script>
+<script src="/js/semantic-search.js"></script>
+    `.trim();
+  });
+
+  /**
+   * Render related posts for current post
+   */
+  hexo.extend.helper.register('semantic_related_posts', function(options = {}) {
+    const post = this.post || this.page;
+    if (!post || !post.semantic_related || post.semantic_related.length === 0) {
+      return '';
+    }
+
+    const limit = options.limit || post.semantic_related.length;
+    const className = options.class || 'semantic-related-posts';
+    const title = options.title !== undefined ? options.title : 'Related Posts';
+    const showExcerpt = options.excerpt !== false;
+
+    const items = post.semantic_related.slice(0, limit);
+
+    let html = `<div class="${className}">`;
+
+    if (title) {
+      html += `<h3 class="semantic-related-title">${title}</h3>`;
+    }
+
+    html += '<ul class="semantic-related-list">';
+    for (const item of items) {
+      html += `<li class="semantic-related-item">`;
+      html += `<a href="${item.url}" class="semantic-related-link">${item.title}</a>`;
+      if (showExcerpt && item.excerpt) {
+        const excerpt = item.excerpt.substring(0, 100) + (item.excerpt.length > 100 ? '...' : '');
+        html += `<p class="semantic-related-excerpt">${excerpt}</p>`;
+      }
+      html += `</li>`;
+    }
+    html += '</ul></div>';
+
+    return html;
+  });
+
+  /**
+   * Check if related posts exist for current post
+   */
+  hexo.extend.helper.register('has_semantic_related', function() {
+    const post = this.post || this.page;
+    return post?.semantic_related?.length > 0;
+  });
+
+  /**
+   * Get raw related posts data
+   */
+  hexo.extend.helper.register('get_semantic_related', function() {
+    const post = this.post || this.page;
+    return post?.semantic_related || [];
+  });
+}
+
+module.exports = { registerHelpers };