@ohos-cpf/3rdloop 0.0.8 → 0.0.10

package/vendor/Archive/src/search/snippet.js

@@ -0,0 +1,64 @@
+/**
+ * snippet.js — 搜索结果摘要提取
+ *
+ * 以查询词命中位置为中心，截取内容片段作为摘要。
+ * 在词边界截断，前后加省略号标记。
+ */
+
+import { SNIPPET_MAX_CHARS, SNIPPET_CONTEXT_CHARS } from '../constants.js';
+
+/**
+ * 提取摘要。
+ * @param {string} content  原始内容
+ * @param {string} query    查询词（用于定位中心）
+ * @param {number} [maxLen] 摘要最大字符数
+ * @param {number} [contextChars] 命中位置前的上下文字符数
+ * @returns {string}
+ */
+export function extractSnippet(
+  content,
+  query,
+  maxLen = SNIPPET_MAX_CHARS,
+  contextChars = SNIPPET_CONTEXT_CHARS
+) {
+  if (!content) return '';
+  const normalized = content.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= maxLen) return normalized;
+
+  // 找到查询词在内容中的位置
+  const tokens = query.split(/\s+/).filter(Boolean);
+  let bestIndex = -1;
+  const lowerContent = normalized.toLowerCase();
+  for (const token of tokens) {
+    const idx = lowerContent.indexOf(token.toLowerCase());
+    if (idx >= 0) {
+      bestIndex = idx;
+      break;
+    }
+  }
+
+  // 没命中则从头截取
+  const start = bestIndex >= 0 ? Math.max(0, bestIndex - contextChars) : 0;
+  let end = Math.min(normalized.length, start + maxLen);
+
+  // 在窗口内找词边界截断
+  const lastBreak = findLastWordBoundary(normalized.slice(start, end), maxLen - 25);
+  if (lastBreak >= 0) end = start + lastBreak;
+
+  const prefix = start > 0 ? '...' : '';
+  const suffix = end < normalized.length ? '...' : '';
+  return `${prefix}${normalized.slice(start, end).trim()}${suffix}`;
+}
+
+/**
+ * 在文本中找最后一个词边界位置（空格或标点）。
+ * @param {string} text
+ * @param {number} minPos 最小位置
+ * @returns {number}
+ */
+function findLastWordBoundary(text, minPos) {
+  for (let i = text.length - 1; i >= minPos; i--) {
+    if (/\s|[，。；,.;!?、]/.test(text[i])) return i;
+  }
+  return -1;
+}

package/vendor/Archive/src/store/dir-store.js

@@ -0,0 +1,103 @@
+/**
+ * dir-store.js — 目录存储方案
+ *
+ * 将文档以 .md 文件形式存放在 docs/{catalog}/{path}.md。
+ * 优势：写入快、调试方便、可 git 管理。
+ *
+ * 路径穿越防护：documentId 中禁止 .. 和绝对路径。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import DocStore from './doc-store.js';
+import { PathSafetyError } from '../utils/path-safety.js';
+
+export default class DirectoryDocStore extends DocStore {
+  /**
+   * @param {string} docsDir 文档根目录
+   */
+  constructor(docsDir) {
+    super();
+    this.docsDir = docsDir;
+  }
+
+  /**
+   * 写入文档（自动创建父目录）。
+   * @param {string} documentId
+   * @param {string} content
+   * @returns {Promise<void>}
+   */
+  async write(documentId, content) {
+    const filePath = this.resolvePath(documentId);
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.promises.writeFile(filePath, content, 'utf-8');
+  }
+
+  /**
+   * 读取文档。不存在时返回 null。
+   * @param {string} documentId
+   * @returns {Promise<string|null>}
+   */
+  async read(documentId) {
+    const filePath = this.resolvePath(documentId);
+    try {
+      return await fs.promises.readFile(filePath, 'utf-8');
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return null;
+      throw error;
+    }
+  }
+
+  /**
+   * 删除文档（不存在时静默）。
+   * @param {string} documentId
+   * @returns {Promise<void>}
+   */
+  async delete(documentId) {
+    const filePath = this.resolvePath(documentId);
+    await fs.promises.rm(filePath, { force: true });
+  }
+
+  /**
+   * 列出所有文档 ID（递归遍历）。
+   * @returns {Promise<string[]>}
+   */
+  async list() {
+    /** @type {string[]} */
+    const results = [];
+
+    const walk = async (dir, prefix) => {
+      let entries;
+      try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true });
+      } catch (error) {
+        if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return;
+        throw error;
+      }
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(fullPath, `${prefix}${entry.name}/`);
+        } else if (entry.name.endsWith('.md')) {
+          results.push(`${prefix}${entry.name.replace(/\.md$/, '')}`);
+        }
+      }
+    };
+
+    await walk(this.docsDir, '');
+    return results;
+  }
+
+  /**
+   * 将 documentId 解析为文件路径（含路径穿越防护）。
+   * @param {string} documentId
+   * @returns {string}
+   */
+  resolvePath(documentId) {
+    const normalized = documentId.replace(/\\/g, '/');
+    if (normalized.split('/').includes('..')) {
+      throw new PathSafetyError('Invalid document ID: path traversal detected.');
+    }
+    return path.join(this.docsDir, `${normalized}.md`);
+  }
+}

package/vendor/Archive/src/store/doc-store.js

@@ -0,0 +1,36 @@
+/**
+ * doc-store.js — 文档仓库抽象接口
+ *
+ * 定义文档存储的统一接口（write / read / delete / list），
+ * 使存储方式可插拔（目录、zip、内存等），上层不感知具体实现。
+ */
+
+/**
+ * @typedef {Object} DocStore
+ * @property {(documentId:string, content:string) => Promise<void>} write
+ * @property {(documentId:string) => Promise<string|null>} read
+ * @property {(documentId:string) => Promise<void>} delete
+ * @property {() => Promise<string[]>} list
+ */
+
+export default class DocStore {
+  /** @param {string} _documentId @param {string} _content */
+  async write(_documentId, _content) {
+    throw new Error('DocStore.write() not implemented');
+  }
+
+  /** @param {string} _documentId @returns {Promise<string|null>} */
+  async read(_documentId) {
+    throw new Error('DocStore.read() not implemented');
+  }
+
+  /** @param {string} _documentId */
+  async delete(_documentId) {
+    throw new Error('DocStore.delete() not implemented');
+  }
+
+  /** @returns {Promise<string[]>} */
+  async list() {
+    throw new Error('DocStore.list() not implemented');
+  }
+}

package/vendor/Archive/src/tokenizer/lexicon.js

@@ -0,0 +1,151 @@
+/**
+ * lexicon.js — 词典文件管理
+ *
+ * 读取领域术语词典、同义词表、停用词表；
+ * 支持同义词扩展与词典指纹计算（用于判断是否需要重建索引）。
+ *
+ * 词典文件位置由 lexiconDir 指定，支持自定义覆盖内置默认词典。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { sha256Text } from '../utils/hash.js';
+
+export default class Lexicon {
+  /**
+   * @param {string} lexiconDir 词典目录
+   */
+  constructor(lexiconDir) {
+    this.lexiconDir = lexiconDir;
+    /** @type {Map<string, Set<string>>|null} */
+    this.synonymMap = null;
+    /** @type {Set<string>|null} */
+    this.stopWords = null;
+    this.termsHash = null;
+    this.synonymsHash = null;
+  }
+
+  /**
+   * 读取术语词典（一行一个）。
+   * 文件不存在时返回空数组。
+   * @returns {string[]}
+   */
+  readTerms() {
+    try {
+      const content = fs.readFileSync(path.join(this.lexiconDir, 'terms.txt'), 'utf-8');
+      return content.split('\n').map((l) => l.trim()).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * 读取同义词表（JSON 数组）。
+   * @returns {string[][]}
+   */
+  readSynonyms() {
+    try {
+      const content = fs.readFileSync(path.join(this.lexiconDir, 'synonyms.json'), 'utf-8');
+      const parsed = JSON.parse(content);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * 读取停用词表。
+   * @returns {Set<string>}
+   */
+  readStopWords() {
+    if (this.stopWords) return this.stopWords;
+    try {
+      const content = fs.readFileSync(path.join(this.lexiconDir, 'stopwords.txt'), 'utf-8');
+      this.stopWords = new Set(content.split('\n').map((l) => l.trim()).filter(Boolean));
+    } catch {
+      this.stopWords = new Set();
+    }
+    return this.stopWords;
+  }
+
+  /**
+   * 构建同义词映射（双向）。
+   * @returns {Map<string, Set<string>>}
+   */
+  getSynonymMap() {
+    if (this.synonymMap) return this.synonymMap;
+
+    this.synonymMap = new Map();
+    const groups = this.readSynonyms();
+    for (const group of groups) {
+      if (!Array.isArray(group) || group.length < 2) continue;
+      for (const word of group) {
+        const key = word.toLowerCase();
+        if (!this.synonymMap.has(key)) {
+          this.synonymMap.set(key, new Set());
+        }
+        for (const other of group) {
+          if (other !== word) this.synonymMap.get(key).add(other);
+        }
+      }
+    }
+    return this.synonymMap;
+  }
+
+  /**
+   * 同义词扩展：将查询中的词扩展为同义词集合。
+   * @param {string} query 原始查询（空格分隔）
+   * @param {number} [maxParts=8] 最大扩展词条数
+   * @returns {string} 扩展后的查询（空格分隔）
+   */
+  expandSynonyms(query, maxParts = 8) {
+    const map = this.getSynonymMap();
+    const parts = query.split(/\s+/).filter(Boolean);
+    /** @type {Set<string>} */
+    const expanded = new Set();
+
+    for (let i = 0; i < parts.length && expanded.size < maxParts; i++) {
+      expanded.add(parts[i]);
+      const syns = map.get(parts[i].toLowerCase());
+      if (syns) {
+        for (const s of syns) {
+          if (expanded.size >= maxParts) break;
+          expanded.add(s);
+        }
+      }
+    }
+    return [...expanded].join(' ');
+  }
+
+  /**
+   * 术语词典指纹（SHA256）。
+   * @returns {string}
+   */
+  getTermsHash() {
+    if (!this.termsHash) {
+      try {
+        const content = fs.readFileSync(path.join(this.lexiconDir, 'terms.txt'), 'utf-8');
+        this.termsHash = sha256Text(content);
+      } catch {
+        this.termsHash = 'empty';
+      }
+    }
+    return this.termsHash;
+  }
+
+  /**
+   * 同义词表指纹（SHA256）。
+   * @returns {string}
+   */
+  getSynonymsHash() {
+    if (!this.synonymsHash) {
+      try {
+        const content = fs.readFileSync(path.join(this.lexiconDir, 'synonyms.json'), 'utf-8');
+        this.synonymsHash = sha256Text(content);
+      } catch {
+        this.synonymsHash = 'empty';
+      }
+    }
+    return this.synonymsHash;
+  }
+}

package/vendor/Archive/src/tokenizer/tokenizer.js

@@ -0,0 +1,167 @@
+/**
+ * tokenizer.js — jieba-wasm 分词器
+ *
+ * 职责：
+ *   - 索引时使用搜索引擎模式（cutForSearch，更细粒度，高召回）。
+ *   - 查询时使用精确模式（cut，高准确率）。
+ *   - 合并装饰器（@ + Component → @Component）。
+ *   - 去停用词、保留大小写变体。
+ *
+ * WASM 模块懒加载 + 单例缓存；若 jieba-wasm 未安装，
+ * 回退到基于正则的简易分词（中英文按词切分），保证可用性。
+ */
+
+import path from 'node:path';
+
+export default class Tokenizer {
+  /**
+   * @param {string} lexiconDir 词典目录
+   * @param {import('../tokenizer/lexicon.js').default} lexicon 词典管理器
+   * @param {string[]} [customTerms=[]] 自定义术语
+   */
+  constructor(lexiconDir, lexicon, customTerms = []) {
+    this.lexiconDir = lexiconDir;
+    this.lexicon = lexicon;
+    this.customTerms = customTerms;
+    /** @type {any|null} */
+    this.jieba = null;
+    this.initPromise = null;
+  }
+
+  /**
+   * 初始化 jieba-wasm（懒加载单例）。
+   * @returns {Promise<void>}
+   */
+  async init() {
+    await this.getJieba();
+  }
+
+  /**
+   * 获取 jieba 实例（带并发安全）。
+   * @returns {Promise<any>}
+   */
+  async getJieba() {
+    if (this.jieba) return this.jieba;
+    if (!this.initPromise) {
+      this.initPromise = this.createJieba().then((j) => {
+        this.jieba = j;
+        return j;
+      });
+    }
+    return this.initPromise;
+  }
+
+  /**
+   * 创建 jieba 实例，加载领域词典。
+   * 失败时回退到简易分词。
+   * @returns {Promise<any>}
+   */
+  async createJieba() {
+    try {
+      const mod = await import('jieba-wasm');
+      const { cut, cut_for_search, with_dict } = mod;
+
+      // 加载领域词典
+      const terms = this.lexicon.readTerms();
+      const allTerms = [...terms, ...this.customTerms];
+      if (allTerms.length > 0 && typeof with_dict === 'function') {
+        with_dict(allTerms.join('\n'));
+      }
+
+      return {
+        cut: (text, hmm) => cut(text, hmm),
+        cutForSearch: (text, hmm) => cut_for_search(text, hmm),
+      };
+    } catch {
+      // 回退：简易分词
+      return {
+        cut: (text) => simpleTokenize(text),
+        cutForSearch: (text) => simpleTokenize(text),
+      };
+    }
+  }
+
+  /**
+   * 索引时分词（搜索引擎模式，细粒度）。
+   * @param {string} text
+   * @returns {Promise<string[]>}
+   */
+  async tokenizeForIndex(text) {
+    const jieba = await this.getJieba();
+    return this.normalize(jieba.cutForSearch(text, true));
+  }
+
+  /**
+   * 查询时分词（精确模式）。
+   * @param {string} text
+   * @returns {Promise<string[]>}
+   */
+  async tokenizeForQuery(text) {
+    const jieba = await this.getJieba();
+    return this.normalize(jieba.cut(text, true));
+  }
+
+  /**
+   * 添加自定义术语（影响 jieba 分词）。
+   * @param {string[]} words
+   */
+  addTerms(words) {
+    this.customTerms.push(...words);
+    // 重置 jieba 以便下次重新加载词典
+    this.jieba = null;
+    this.initPromise = null;
+  }
+
+  /**
+   * 规范化 token：合并装饰器、去停用词、保留大小写变体。
+   * @param {string[]} tokens
+   * @returns {string[]}
+   */
+  normalize(tokens) {
+    const stops = this.lexicon.readStopWords();
+    /** @type {string[]} */
+    const out = [];
+    for (const raw of this.mergeDecorators(tokens)) {
+      const token = raw.trim();
+      if (!token || stops.has(token)) continue;
+      out.push(token.toLowerCase());
+      // 保留原始大小写（FTS5 对大小写敏感）
+      if (/[A-Z]/.test(token)) out.push(token);
+    }
+    return out;
+  }
+
+  /**
+   * 合并 "@" + "Component" → "@Component"。
+   * @param {string[]} tokens
+   * @returns {string[]}
+   */
+  mergeDecorators(tokens) {
+    /** @type {string[]} */
+    const merged = [];
+    for (let i = 0; i < tokens.length; i++) {
+      const current = tokens[i]?.trim();
+      const next = tokens[i + 1]?.trim();
+      if (current === '@' && next && /^[A-Z][a-zA-Z0-9]*$/.test(next)) {
+        merged.push(`@${next}`);
+        i++;
+      } else if (current) {
+        merged.push(current);
+      }
+    }
+    return merged;
+  }
+}
+
+/**
+ * 简易分词回退方案（jieba-wasm 不可用时使用）。
+ * 中文按字符切分，英文/数字按词切分。
+ * @param {string} text
+ * @returns {string[]}
+ */
+function simpleTokenize(text) {
+  if (!text) return [];
+  // 匹配：英文词、数字、中文字符
+  const matches = text.match(/[a-zA-Z_][a-zA-Z0-9_]*|\d+|[\u4e00-\u9fa5]/g);
+  return matches || [];
+}

package/vendor/Archive/src/types.js

@@ -0,0 +1,86 @@
+/**
+ * types.js — 类型定义（JSDoc 形式）
+ *
+ * 本文件以 JSDoc typedef 定义对外接口的数据结构，
+ * 供 IDE 智能提示和调用方文档参考，不产生运行时副作用。
+ */
+
+/**
+ * @typedef {Object} CatalogConfig
+ * @property {string} id            目录标识，如 'guides'
+ * @property {string} title         目录中文名
+ * @property {number} [searchBoost] 搜索权重倍数（>1 提升）
+ * @property {boolean} [tailInGlobalSearch] 全局搜索时是否排到尾部
+ */
+
+/**
+ * @typedef {Object} EngineOptions
+ * @property {string} dataDir           数据根目录
+ * @property {CatalogConfig[]} [catalogs] 目录配置
+ * @property {string} [lexiconDir]      词典目录（不传用内置默认）
+ * @property {'directory'|'zip'} [storageMode] 存储方式，默认 directory
+ * @property {string} [dbPath]          索引数据库路径
+ * @property {boolean} [autoIndex=true] 写入时自动分词建索引
+ * @property {number} [maxSectionsPerDoc=28] 单文档最大段数
+ * @property {number} [defaultLimit=10] 搜索默认上限
+ */
+
+/**
+ * @typedef {Object} DocumentInput
+ * @property {string} documentId        文档唯一标识
+ * @property {string} catalog           所属目录 ID
+ * @property {string} [title]           文档标题
+ * @property {string} content           Markdown 原文
+ * @property {Record<string,string>} [metadata] 自定义元数据
+ */
+
+/**
+ * @typedef {Object} SearchQuery
+ * @property {string} query              搜索关键词（空格分隔）
+ * @property {string} [catalog]          限定目录
+ * @property {number} [limit]            结果数量上限
+ * @property {boolean} [includeSnippet=true] 是否包含摘要
+ * @property {number} [snippetMaxChars=200] 摘要最大字符数
+ */
+
+/**
+ * @typedef {Object} SearchOptions
+ * @property {boolean} [preferAnd]       是否优先 AND 匹配
+ * @property {boolean} [expandSynonyms=true] 是否启用同义词扩展
+ * @property {number} [synonymExpandLimit=8] 同义词扩展上限
+ */
+
+/**
+ * @typedef {Object} SearchResult
+ * @property {string} documentId
+ * @property {string} title
+ * @property {string} sectionTitle
+ * @property {string} snippet
+ * @property {number} score              相关度（越小越相关）
+ * @property {string} catalog
+ * @property {number} [rawScore]         Rerank 前 BM25 分数
+ */
+
+/**
+ * @typedef {Object} DocumentRecord
+ * @property {string} documentId
+ * @property {string} title
+ * @property {string} catalog
+ * @property {string} content
+ * @property {number} segmentCount
+ * @property {Record<string,string>} [metadata]
+ * @property {number} createdAt
+ * @property {number} updatedAt
+ */
+
+/**
+ * @typedef {Object} EngineStatus
+ * @property {boolean} ready
+ * @property {number} documentCount
+ * @property {number} segmentCount
+ * @property {number} dbSizeBytes
+ * @property {string} indexVersion
+ * @property {number|null} lastBuiltAt
+ * @property {boolean} isWriting
+ * @property {boolean} dbSizeWarning — DB 大小超过 GIT_WARN_BYTES 时为 true
+ */

package/vendor/Archive/src/utils/hash.js

@@ -0,0 +1,16 @@
+/**
+ * hash.js — SHA256 文本哈希工具
+ *
+ * 用于词典指纹计算（判断是否需要重建索引）。
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * 计算文本的 SHA256 指纹（十六进制字符串）。
+ * @param {string} text
+ * @returns {string} 64 位十六进制哈希
+ */
+export function sha256Text(text) {
+  return createHash('sha256').update(text, 'utf-8').digest('hex');
+}

package/vendor/Archive/src/utils/lock.js

@@ -0,0 +1,73 @@
+/**
+ * lock.js — 简易文件锁
+ *
+ * 基于原子性 `fs.open(..., 'wx')` 实现独占写入锁。
+ * 写入 PID 与时间戳，崩溃后可通过 stale 时间自动复用。
+ *
+ * 返回 release 函数供 finally 调用，确保锁释放。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { LOCK_STALE_MS } from '../constants.js';
+
+/**
+ * 获取一个文件锁。
+ * @param {string} lockPath 锁文件路径
+ * @param {number} [staleMs] stale 时间（毫秒）
+ * @returns {Promise<() => Promise<void>>} release 函数
+ */
+export async function acquireLock(lockPath, staleMs = LOCK_STALE_MS) {
+  await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+
+  // 轮询获取锁（带 stale 检测）
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      const handle = await fs.promises.open(lockPath, 'wx');
+      const payload = JSON.stringify({ pid: process.pid, ts: Date.now() });
+      await handle.writeFile(payload, 'utf-8');
+      await handle.close();
+      return () => fs.promises.unlink(lockPath).catch(() => {});
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') {
+        throw error;
+      }
+    }
+
+    // 锁已被占用，判断是否 stale
+    const stale = await isStale(lockPath, staleMs);
+    if (stale) {
+      // 强制释放后下一轮重试
+      await fs.promises.unlink(lockPath).catch(() => {});
+      continue;
+    }
+
+    // 等待后重试
+    await sleep(200);
+  }
+}
+
+/**
+ * 判断锁是否过期。
+ * @param {string} lockPath
+ * @param {number} staleMs
+ * @returns {Promise<boolean>}
+ */
+async function isStale(lockPath, staleMs) {
+  try {
+    const raw = await fs.promises.readFile(lockPath, 'utf-8');
+    const info = JSON.parse(raw);
+    return Date.now() - info.ts > staleMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}