npm package: @lumen-public/app
Description: Lumen App - 前端应用层，提供简洁的 API 调用接口
Author: Lumen Team
Latest version: 1.1.1

# @lumen-public/app

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

## 特性

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

## 安装

```bash
npm install @lumen-public/app
```

## 快速开始

### 基本使用

```typescript
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!");
```

### 完整示例

```typescript
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)`

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

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

#### `ready()`

等待应用准备就绪。

```typescript
await ready();
```

#### `isReady()`

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

```typescript
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. 函数注册和调用

```typescript
// 注册函数
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. 全局变量管理

```typescript
// 设置全局变量
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. 事件系统

```typescript
// 注册事件
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 调用

```typescript
// 文件操作
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);
```

## 类型定义

```typescript
// 基础结果类型
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;
}
```

## 错误处理

```typescript
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);
  }
}
```

## 开发

### 构建

```bash
npm run build
```

### 版本化构建

```bash
npm run build:versioned
```

### 测试

```bash
npm test
```

### 手动测试

```bash
npm run test:manual
```

## 许可证

MIT

## 详细文档

- [**文档索引**](./DOCS_INDEX.md) - 完整的文档导航和查找指南
- [**完整使用手册**](./USAGE_MANUAL.md) - 详细的使用指南和示例
- [**快速参考**](./QUICK_REFERENCE.md) - 常用 API 快速查找
- [**功能对比**](./FEATURE_COMPARISON.md) - 不同功能的对比和选择建议
- [**简化全局对象功能**](./SIMPLIFIED_GLOBAL_OBJECTS_SUMMARY.md) - 全局变量管理详细说明
- [**构建压缩功能**](./BUILD_COMPRESSION_SUMMARY.md) - 构建和压缩功能说明
- [**API 接口文档**](./API_DOCS.md) - 完整的 API 接口说明
- [**类型定义**](./src/types.ts) - TypeScript 类型定义

## 相关项目

- [@lumen-public/api](../api) - Rust 后端 API
- [Lumen Core](../../plugins-dev/core) - Rust 核心模块