@lumen-public/app

Lumen App - 前端应用层，提供简洁的 API 调用接口

特性

• 🚀 自动单例：全局唯一实例，无需手动管理
• 🔒 类型安全：完整的 TypeScript 支持
• 🎯 简洁调用：直接函数调用，无需关心前后端分离
• 🛡️ 双重安全：JavaScript + Rust 双重路径验证
• 📚 知识库限制：支持设置知识库目录，限制文件操作范围
• 📦 零配置：开箱即用，自动初始化
• 🔧 函数注册：支持"先注册、后调用"的函数管理机制
• 🌐 全局变量：灵活的状态和对象存储管理
• 📡 事件系统：完整的事件发布和订阅功能
• ⚡ 冲突检测：自动防止名称冲突，确保系统稳定性

安装

npm install @lumen-public/app

快速开始

基本使用

import { app, invoke, ready, setKnowledgeBasePath } from "@lumen-public/app";

// 等待应用准备就绪
await ready();

// 设置知识库目录（可选）
await setKnowledgeBasePath("/path/to/knowledge-base");

// 1. 函数注册和调用
await app.register("add", (a, b) => a + b);
const sum = await app.add(5, 3); // 8

// 2. 全局变量管理
await app.setGlobalVariable("config", { theme: "dark", language: "zh-CN" });
const theme = await app.config.theme; // "dark"

// 3. 事件系统
app.on("userLogin", (user) => console.log("用户登录:", user));
await app.emit("userLogin", { id: 1, name: "张三" });

// 4. 底层 API 调用
const result = await invoke("dirInfo", "/path/to/knowledge-base", false, false);
const content = await invoke("readFile", "/path/to/knowledge-base/document.md");
await invoke("writeFile", "/path/to/knowledge-base/note.txt", "Hello World!");

完整示例

import {
  lumenApp,
  invoke,
  ready,
  setKnowledgeBasePath,
} from "@lumen-public/app";

async function example() {
  // 等待应用初始化
  await ready();

  // 设置知识库目录
  await setKnowledgeBasePath("/tmp/my-app");

  // 创建目录
  await invoke("createDir", "/tmp/my-app");

  // 写入文件
  await invoke(
    "writeFile",
    "/tmp/my-app/config.json",
    JSON.stringify({
      name: "My App",
      version: "1.0.0",
    })
  );

  // 读取文件
  const config = await invoke("readFile", "/tmp/my-app/config.json");
  console.log("配置内容:", config.content);

  // 获取文件信息
  const info = await invoke("getFileInfo", "/tmp/my-app/config.json");
  console.log("文件大小:", info.size);

  // 获取目录信息
  const dir = await invoke("dirInfo", "/tmp/my-app", false, false);
  console.log("目录子项:", dir.children.length);

  // 清理
  await invoke("removeFile", "/tmp/my-app/config.json");
}

API 参考

核心函数

invoke<T>(command, ...args)

通用调用函数，支持所有命令。使用驼峰命名和展开参数。

const result = await invoke("dirInfo", "/tmp", false, false);

ready()

等待应用准备就绪。

await ready();

isReady()

检查应用是否已准备就绪。

if (isReady()) {
  // 应用已准备就绪
}

支持的命令

所有命令都使用驼峰命名，通过 invoke 函数调用：

文件系统操作

• dirInfo(path, recursive, expanded) - 获取目录信息
• readFile(path) - 读取文件
• writeFile(path, content) - 写入文件
• getFileOrCreate(path, content?) - 获取文件或创建
• saveFile(path, content) - 保存文件
• getFileInfo(path) - 获取文件信息
• removeFile(path) - 删除文件
• fileExists(path) - 检查文件是否存在

目录操作

• createDir(path) - 创建目录
• removeDir(path) - 删除目录

移动操作

• moveFile(fromPath, toPath) - 移动文件
• moveDir(fromPath, toPath) - 移动目录

图像操作

• saveImage(path, dataUrl) - 保存图像
• downloadImage(url, path) - 下载图像
• readFileDataUrl(path) - 读取文件为 Data URL

存储操作

• loadStore(path, options?) - 加载存储
• setStoreValue(storePath, key, value) - 设置存储值
• getStoreValue(storePath, key) - 获取存储值
• deleteStoreValue(storePath, key) - 删除存储值
• getStoreKeys(storePath) - 获取存储键列表
• getStoreValues(storePath) - 获取存储值列表
• clearStore(storePath) - 清空存储
• saveStore(storePath) - 保存存储
• getStoreInfo(storePath) - 获取存储信息

内存状态管理

• setMemoryState(key, value) - 设置内存状态
• getMemoryState(key) - 获取内存状态
• hasMemoryState(key) - 检查内存状态是否存在
• removeMemoryState(key) - 删除内存状态
• listMemoryStates() - 列出所有内存状态
• clearMemoryStates() - 清空所有内存状态

资源管理

• addResource(resourceType, data) - 添加资源
• getResource(resourceId, resourceType) - 获取资源
• removeResource(resourceId, resourceType) - 删除资源
• listResources() - 列出所有资源
• hasResource(resourceId) - 检查资源是否存在

系统信息

• getSystemInfo() - 获取系统信息

知识库管理

• setKnowledgeBasePath(path) - 设置知识库路径
• getKnowledgeBasePath() - 获取知识库路径

核心功能

1. 函数注册和调用

// 注册函数
await app.register("add", (a, b) => a + b);
await app.register("multiply", (a, b) => a * b);

// 调用函数
const sum = await app.add(5, 3); // 8
const product = await app.multiply(4, 7); // 28

// 管理函数
const hasAdd = await app.has("add");
const functionNames = await app.getServiceNames();
await app.unregister("add");

2. 全局变量管理

// 设置全局变量
await app.setGlobalVariable("config", { theme: "dark", language: "zh-CN" });
await app.setGlobalVariable("user", { name: "张三", role: "admin" });

// 访问全局变量
const theme = await app.config.theme; // "dark"
const userName = await app.user.name; // "张三"

// 管理全局变量
const hasConfig = await app.hasGlobalVariable("config");
const variableNames = await app.getGlobalVariableNames();
await app.unregisterGlobalVariable("config");

3. 事件系统

// 注册事件
app.on("userLogin", (user) => console.log("用户登录:", user));
app.once("appReady", () => console.log("应用准备就绪"));

// 触发事件
await app.emit("userLogin", { id: 1, name: "张三" });

// 管理事件
const hasEvent = await app.hasEvent("userLogin");
const eventNames = await app.getEventNames();
app.off("userLogin");

4. 底层 API 调用

// 文件操作
const content = await invoke("readFile", "/path/to/file.txt");
await invoke("writeFile", "/path/to/file.txt", "Hello World!");

// 目录操作
const dirInfo = await invoke("dirInfo", "/path/to/dir", true, false);
await invoke("createDir", "/path/to/new-dir");

// 存储操作
await invoke("setStoreValue", "/path/to/store.json", "key", "value");
const value = await invoke("getStoreValue", "/path/to/store.json", "key");

// 系统信息
const systemInfo = await invoke("getSystemInfo");
console.log("系统信息:", systemInfo);

类型定义

// 基础结果类型
interface BaseResult {
  success: boolean;
  error: string;
}

// 文件操作结果
interface FileOperationResult extends BaseResult {
  path: string;
  message: string;
  size: number;
  exists: boolean;
  content: string;
  contentLen: number;
}

// 目录信息结果
interface DirInfoResult extends BaseResult {
  path: string;
  name: string;
  isDirectory: boolean;
  isFile: boolean;
  size: number;
  extension: string;
  children: DirInfoResult[];
  childrenLoaded: boolean;
}

// 文件信息结果
interface FileInfoResult extends BaseResult {
  path: string;
  name: string;
  isDirectory: boolean;
  isFile: boolean;
  size: number;
  extension: string;
  exists: boolean;
}

错误处理

import { LumenAppError } from "@lumen-public/app";

try {
  const result = await readFile("/nonexistent/file.txt");
} catch (error) {
  if (error instanceof LumenAppError) {
    console.error("Lumen App 错误:", error.message);
    console.error("命令:", error.command);
    console.error("参数:", error.args);
  } else {
    console.error("未知错误:", error);
  }
}

开发

构建

npm run build

版本化构建

npm run build:versioned

测试

npm test

手动测试

npm run test:manual

许可证

MIT

详细文档

• 文档索引 - 完整的文档导航和查找指南
• 完整使用手册 - 详细的使用指南和示例
• 快速参考 - 常用 API 快速查找
• 功能对比 - 不同功能的对比和选择建议
• 简化全局对象功能 - 全局变量管理详细说明
• 构建压缩功能 - 构建和压缩功能说明
• API 接口文档 - 完整的 API 接口说明
• 类型定义 - TypeScript 类型定义

相关项目

• @lumen-public/api - Rust 后端 API
• Lumen Core - Rust 核心模块