1034 lines
28 KiB
Markdown
1034 lines
28 KiB
Markdown
# Qiming Agent 客户端存储数据结构
|
||
|
||
> 本文档记录了 Qiming Agent Tauri 客户端使用 `@tauri-apps/plugin-store` 存储的所有持久化数据。
|
||
>
|
||
> 存储文件：`qiming_store.bin`（位于应用数据目录）
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [1. 认证信息 (auth)](#1-认证信息-auth)
|
||
- [2. 配置信息 (config)](#2-配置信息-config)
|
||
- [3. 应用设置 (settings)](#3-应用设置-settings)
|
||
- [4. 初始化向导 (setup)](#4-初始化向导-setup)
|
||
- [5. 依赖管理 (deps)](#5-依赖管理-deps)
|
||
- [6. Rust 后端读取示例](#6-rust-后端读取示例)
|
||
- [7. TypeScript/React 前端调用示例](#7-typescriptreact-前端调用示例)
|
||
|
||
---
|
||
|
||
## 1. 认证信息 (auth)
|
||
|
||
用户登录和认证相关的持久化数据。
|
||
|
||
| 键名 | 类型 | 说明 | 示例值 |
|
||
|------|------|------|--------|
|
||
| `auth.username` | `string` | 登录用户名 | `"admin"` |
|
||
| `auth.password` | `string` | 登录密码（建议加密存储） | `"******"` |
|
||
| `auth.config_key` | `string` | 配置密钥（用于服务端验证） | `"abc123..."` |
|
||
| `auth.saved_key` | `string` | 保存的密钥 | `"xyz789..."` |
|
||
| `auth.user_info` | `AuthUserInfo` | 用户详细信息（JSON 对象） | 见下方类型定义 |
|
||
| `auth.online_status` | `boolean` | 在线状态 | `true` |
|
||
|
||
### AuthUserInfo 类型定义
|
||
|
||
```typescript
|
||
interface AuthUserInfo {
|
||
username: string; // 用户名
|
||
displayName?: string; // 显示名称
|
||
avatar?: string; // 头像 URL
|
||
email?: string; // 邮箱
|
||
phone?: string; // 手机号
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 配置信息 (config)
|
||
|
||
场景配置和自定义配置相关数据。
|
||
|
||
| 键名 | 类型 | 说明 | 示例值 |
|
||
|------|------|------|--------|
|
||
| `config.current_scene` | `string` | 当前激活的场景 ID | `"production"` |
|
||
| `config.custom_scenes` | `CustomScene[]` | 自定义场景列表（JSON 数组） | 见下方类型定义 |
|
||
| `config.version` | `string` | 配置版本号（用于数据迁移） | `"1"` |
|
||
|
||
### CustomScene 类型定义
|
||
|
||
```typescript
|
||
interface CustomScene {
|
||
id: string; // 场景唯一标识
|
||
name: string; // 场景名称
|
||
description?: string; // 场景描述
|
||
isDefault?: boolean; // 是否为默认场景
|
||
server: {
|
||
apiUrl: string; // API 服务地址
|
||
apiKey?: string; // API 密钥
|
||
timeout?: number; // 请求超时（毫秒）
|
||
};
|
||
local: {
|
||
agent: {
|
||
host: string; // Agent 主机
|
||
port: number; // Agent 端口
|
||
scheme?: string; // 协议（http/https）
|
||
path?: string; // 路径前缀
|
||
};
|
||
vnc: {
|
||
host: string; // VNC 主机
|
||
port: number; // VNC 端口
|
||
scheme?: string; // 协议
|
||
};
|
||
fileServer: {
|
||
host: string; // 文件服务主机
|
||
port: number; // 文件服务端口
|
||
scheme?: string; // 协议
|
||
path?: string; // 路径前缀
|
||
};
|
||
websocket: {
|
||
host: string; // WebSocket 主机
|
||
port: number; // WebSocket 端口
|
||
scheme?: string; // 协议（ws/wss）
|
||
path?: string; // 路径前缀
|
||
};
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 应用设置 (settings)
|
||
|
||
应用行为相关的设置。
|
||
|
||
| 键名 | 类型 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `settings.auto_connect` | `boolean` | 自动连接服务 | `false` |
|
||
| `settings.notifications` | `boolean` | 启用通知 | `true` |
|
||
|
||
> **注意**：开机自启动功能通过系统 API 实现（LaunchAgent/Registry/XDG Autostart），不存储在此处。
|
||
|
||
---
|
||
|
||
## 4. 初始化向导 (setup)
|
||
|
||
首次启动配置向导的状态和数据。
|
||
|
||
| 键名 | 类型 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `setup.completed` | `boolean` | 是否完成初始化向导 | `false` |
|
||
| `setup.current_step` | `number` | 当前向导步骤（1/2/3） | `1` |
|
||
| `setup.server_host` | `string` | 服务域名 | `"https://agent.qiming.com"` |
|
||
| `setup.server_port` | `number` | 服务 HTTPS 端口 | `443` |
|
||
| `setup.agent_port` | `number` | Agent 服务端口 | `9086` |
|
||
| `setup.file_server_port` | `number` | 文件服务端口 | `60000` |
|
||
| `setup.proxy_port` | `number` | 代理服务端口 | `9099` |
|
||
| `setup.workspace_dir` | `string` | 工作区目录路径 | `""` |
|
||
|
||
### SetupState 类型定义
|
||
|
||
```typescript
|
||
interface SetupState {
|
||
completed: boolean; // 是否完成初始化
|
||
currentStep: number; // 当前步骤 (1/2/3)
|
||
serverHost: string; // 服务域名
|
||
serverPort: number; // 服务 HTTPS 端口
|
||
agentPort: number; // Agent 端口
|
||
fileServerPort: number; // 文件服务端口
|
||
proxyPort: number; // 代理服务端口
|
||
workspaceDir: string; // 工作区目录
|
||
}
|
||
```
|
||
|
||
### 向导步骤说明
|
||
|
||
| 步骤 | 名称 | 说明 |
|
||
|------|------|------|
|
||
| 1 | 基础设置 | 配置服务域名、端口、工作区目录 |
|
||
| 2 | 账号登录 | 用户名密码登录验证 |
|
||
| 3 | 依赖安装 | 检测 Node.js、安装本地 npm 依赖 |
|
||
|
||
---
|
||
|
||
## 5. 依赖管理 (deps)
|
||
|
||
本地 npm 依赖安装相关路径。
|
||
|
||
| 键名 | 类型 | 说明 | 示例值 |
|
||
|------|------|------|--------|
|
||
| `deps.install_dir` | `string` | npm 包安装根目录（应用数据目录） | macOS: `~/Library/Application Support/com.qiming.agent-tauri-client/` |
|
||
| `deps.node_modules_path` | `string` | node_modules 完整路径 | `~/Library/Application Support/com.qiming.agent-tauri-client/node_modules/` |
|
||
|
||
### 本地安装的 npm 依赖
|
||
|
||
| 包名 | 说明 |
|
||
|------|------|
|
||
| `qiming-file-server` | 文件服务器 |
|
||
| `qimingcode` | Qiming 代码服务 |
|
||
| `claude-code-acp-ts` | Claude Code ACP 服务 |
|
||
|
||
### 各平台应用数据目录
|
||
|
||
| 平台 | 路径 |
|
||
|------|------|
|
||
| macOS | `~/Library/Application Support/com.qiming.agent-tauri-client/` |
|
||
| Windows | `C:\Users\<用户名>\AppData\Roaming\com.qiming.agent-tauri-client\` |
|
||
| Linux | `~/.local/share/com.qiming.agent-tauri-client/` |
|
||
|
||
---
|
||
|
||
## 6. Rust 后端读取示例
|
||
|
||
Rust 后端只需读取存储数据，写入操作由前端 UI 负责。
|
||
|
||
### 6.1 依赖配置
|
||
|
||
```toml
|
||
# Cargo.toml
|
||
[dependencies]
|
||
tauri-plugin-store = "2"
|
||
serde = { version = "1", features = ["derive"] }
|
||
serde_json = "1"
|
||
```
|
||
|
||
### 6.2 初始化插件
|
||
|
||
```rust
|
||
// src-tauri/src/lib.rs
|
||
pub fn run() {
|
||
tauri::Builder::default()
|
||
.plugin(tauri_plugin_store::Builder::new().build())
|
||
// ... 其他配置
|
||
.run(tauri::generate_context!())
|
||
.expect("error while running tauri application");
|
||
}
|
||
```
|
||
|
||
### 6.3 数据结构定义
|
||
|
||
```rust
|
||
use serde::{Deserialize, Serialize};
|
||
|
||
/// 用户认证信息
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct AuthUserInfo {
|
||
pub username: String,
|
||
pub display_name: Option<String>,
|
||
pub avatar: Option<String>,
|
||
pub email: Option<String>,
|
||
pub phone: Option<String>,
|
||
}
|
||
|
||
/// 初始化配置状态
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct SetupState {
|
||
pub completed: bool,
|
||
pub current_step: i32,
|
||
pub server_host: String,
|
||
pub server_port: i32,
|
||
pub agent_port: i32,
|
||
pub file_server_port: i32,
|
||
pub proxy_port: i32,
|
||
pub workspace_dir: String,
|
||
}
|
||
|
||
/// 自定义场景配置
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct CustomScene {
|
||
pub id: String,
|
||
pub name: String,
|
||
pub description: Option<String>,
|
||
pub is_default: Option<bool>,
|
||
pub server: ServerConfig,
|
||
pub local: LocalConfig,
|
||
}
|
||
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct ServerConfig {
|
||
pub api_url: String,
|
||
pub api_key: Option<String>,
|
||
pub timeout: Option<u64>,
|
||
}
|
||
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct LocalConfig {
|
||
pub agent: EndpointConfig,
|
||
pub vnc: EndpointConfig,
|
||
pub file_server: EndpointConfig,
|
||
pub websocket: EndpointConfig,
|
||
}
|
||
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct EndpointConfig {
|
||
pub host: String,
|
||
pub port: u16,
|
||
pub scheme: Option<String>,
|
||
pub path: Option<String>,
|
||
}
|
||
```
|
||
|
||
### 6.4 读取函数
|
||
|
||
```rust
|
||
use tauri::Manager;
|
||
use tauri_plugin_store::StoreExt;
|
||
|
||
const STORE_FILE: &str = "qiming_store.bin";
|
||
|
||
/// 读取字符串值
|
||
fn read_string(app: &tauri::AppHandle, key: &str) -> Option<String> {
|
||
app.store(STORE_FILE)
|
||
.ok()
|
||
.and_then(|store| store.get(key))
|
||
.and_then(|v| v.as_str().map(String::from))
|
||
}
|
||
|
||
/// 读取布尔值
|
||
fn read_bool(app: &tauri::AppHandle, key: &str) -> Option<bool> {
|
||
app.store(STORE_FILE)
|
||
.ok()
|
||
.and_then(|store| store.get(key))
|
||
.and_then(|v| v.as_bool())
|
||
}
|
||
|
||
/// 读取数值
|
||
fn read_number(app: &tauri::AppHandle, key: &str) -> Option<i64> {
|
||
app.store(STORE_FILE)
|
||
.ok()
|
||
.and_then(|store| store.get(key))
|
||
.and_then(|v| v.as_i64())
|
||
}
|
||
|
||
/// 读取 JSON 对象
|
||
fn read_object<T: serde::de::DeserializeOwned>(app: &tauri::AppHandle, key: &str) -> Option<T> {
|
||
app.store(STORE_FILE)
|
||
.ok()
|
||
.and_then(|store| store.get(key))
|
||
.and_then(|v| serde_json::from_value(v.clone()).ok())
|
||
}
|
||
```
|
||
|
||
### 6.5 读取初始化配置
|
||
|
||
```rust
|
||
/// 获取初始化状态（用于服务启动）
|
||
pub fn get_setup_state(app: &tauri::AppHandle) -> SetupState {
|
||
SetupState {
|
||
completed: read_bool(app, "setup.completed").unwrap_or(false),
|
||
current_step: read_number(app, "setup.current_step").unwrap_or(1) as i32,
|
||
server_host: read_string(app, "setup.server_host")
|
||
.unwrap_or_else(|| "https://agent.qiming.com".to_string()),
|
||
server_port: read_number(app, "setup.server_port").unwrap_or(443) as i32,
|
||
agent_port: read_number(app, "setup.agent_port").unwrap_or(9086) as i32,
|
||
file_server_port: read_number(app, "setup.file_server_port").unwrap_or(60000) as i32,
|
||
proxy_port: read_number(app, "setup.proxy_port").unwrap_or(9099) as i32,
|
||
workspace_dir: read_string(app, "setup.workspace_dir").unwrap_or_default(),
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
fn start_services(app: &tauri::AppHandle) {
|
||
let config = get_setup_state(app);
|
||
|
||
if !config.completed {
|
||
log::warn!("初始化未完成，跳过服务启动");
|
||
return;
|
||
}
|
||
|
||
log::info!("服务配置: host={}, agent_port={}, file_port={}",
|
||
config.server_host, config.agent_port, config.file_server_port);
|
||
|
||
// 启动 Agent 服务
|
||
// start_agent_service(&config.server_host, config.agent_port);
|
||
|
||
// 启动文件服务
|
||
// start_file_service(config.file_server_port);
|
||
}
|
||
```
|
||
|
||
### 6.6 读取认证信息
|
||
|
||
```rust
|
||
/// 获取用户认证信息
|
||
pub fn get_auth_info(app: &tauri::AppHandle) -> Option<AuthUserInfo> {
|
||
read_object::<AuthUserInfo>(app, "auth.user_info")
|
||
}
|
||
|
||
/// 获取 ConfigKey（用于服务端验证）
|
||
pub fn get_config_key(app: &tauri::AppHandle) -> Option<String> {
|
||
read_string(app, "auth.config_key")
|
||
}
|
||
|
||
/// 检查是否已登录
|
||
pub fn is_logged_in(app: &tauri::AppHandle) -> bool {
|
||
read_bool(app, "auth.online_status").unwrap_or(false)
|
||
}
|
||
|
||
// 使用示例
|
||
fn connect_to_server(app: &tauri::AppHandle) {
|
||
if !is_logged_in(app) {
|
||
log::warn!("用户未登录");
|
||
return;
|
||
}
|
||
|
||
if let Some(config_key) = get_config_key(app) {
|
||
log::info!("使用 ConfigKey 连接服务器");
|
||
// connect_with_key(&config_key);
|
||
}
|
||
|
||
if let Some(user) = get_auth_info(app) {
|
||
log::info!("当前用户: {}", user.username);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.7 读取场景配置
|
||
|
||
```rust
|
||
/// 获取当前场景 ID
|
||
pub fn get_current_scene_id(app: &tauri::AppHandle) -> Option<String> {
|
||
read_string(app, "config.current_scene")
|
||
}
|
||
|
||
/// 获取自定义场景列表
|
||
pub fn get_custom_scenes(app: &tauri::AppHandle) -> Vec<CustomScene> {
|
||
read_object::<Vec<CustomScene>>(app, "config.custom_scenes").unwrap_or_default()
|
||
}
|
||
|
||
/// 获取当前激活的场景配置
|
||
pub fn get_current_scene(app: &tauri::AppHandle) -> Option<CustomScene> {
|
||
let scene_id = get_current_scene_id(app)?;
|
||
let scenes = get_custom_scenes(app);
|
||
scenes.into_iter().find(|s| s.id == scene_id)
|
||
}
|
||
|
||
// 使用示例
|
||
fn get_api_endpoint(app: &tauri::AppHandle) -> String {
|
||
if let Some(scene) = get_current_scene(app) {
|
||
scene.server.api_url
|
||
} else {
|
||
// 使用默认配置
|
||
let setup = get_setup_state(app);
|
||
setup.server_host
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.8 读取依赖路径
|
||
|
||
```rust
|
||
/// 获取 npm 包安装目录
|
||
pub fn get_deps_install_dir(app: &tauri::AppHandle) -> Option<String> {
|
||
read_string(app, "deps.install_dir")
|
||
}
|
||
|
||
/// 获取 node_modules 路径
|
||
pub fn get_node_modules_path(app: &tauri::AppHandle) -> Option<String> {
|
||
read_string(app, "deps.node_modules_path")
|
||
}
|
||
|
||
/// 获取本地 npm 包的 bin 路径
|
||
pub fn get_local_bin_path(app: &tauri::AppHandle, package_name: &str) -> Option<String> {
|
||
let node_modules = get_node_modules_path(app)?;
|
||
let bin_path = std::path::Path::new(&node_modules)
|
||
.join(".bin")
|
||
.join(package_name);
|
||
|
||
if bin_path.exists() {
|
||
Some(bin_path.to_string_lossy().to_string())
|
||
} else {
|
||
None
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
fn start_qiming_services(app: &tauri::AppHandle) {
|
||
// 获取各服务的可执行文件路径
|
||
let file_server_bin = get_local_bin_path(app, "qiming-file-server");
|
||
let qimingcode_bin = get_local_bin_path(app, "qimingcode");
|
||
let claude_code_bin = get_local_bin_path(app, "claude-code-acp-ts");
|
||
|
||
if let Some(bin) = file_server_bin {
|
||
log::info!("文件服务路径: {}", bin);
|
||
// std::process::Command::new(&bin).spawn();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.9 完整使用示例
|
||
|
||
```rust
|
||
use tauri::Manager;
|
||
|
||
/// 应用启动时读取配置并初始化服务
|
||
pub fn on_app_ready(app: &tauri::AppHandle) {
|
||
// 1. 检查初始化状态
|
||
let setup = get_setup_state(app);
|
||
if !setup.completed {
|
||
log::info!("等待用户完成初始化向导");
|
||
return;
|
||
}
|
||
|
||
// 2. 检查登录状态
|
||
if !is_logged_in(app) {
|
||
log::info!("等待用户登录");
|
||
return;
|
||
}
|
||
|
||
// 3. 获取配置
|
||
let config_key = get_config_key(app);
|
||
let workspace = &setup.workspace_dir;
|
||
|
||
log::info!("工作区目录: {}", workspace);
|
||
log::info!("Agent 端口: {}", setup.agent_port);
|
||
log::info!("文件服务端口: {}", setup.file_server_port);
|
||
|
||
// 4. 获取依赖路径
|
||
if let Some(deps_dir) = get_deps_install_dir(app) {
|
||
log::info!("依赖安装目录: {}", deps_dir);
|
||
}
|
||
|
||
// 5. 启动服务
|
||
// start_all_services(app, &setup, config_key);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. TypeScript/React 前端调用示例
|
||
|
||
在前端 UI 中访问存储数据。
|
||
|
||
### 7.1 导入存储服务
|
||
|
||
```typescript
|
||
// 导入存储服务
|
||
import {
|
||
initStore,
|
||
STORAGE_KEYS,
|
||
authStorage,
|
||
configStorage,
|
||
settingsStorage,
|
||
setupStorage,
|
||
getString,
|
||
setString,
|
||
getBoolean,
|
||
setBoolean,
|
||
getNumber,
|
||
setNumber,
|
||
getObject,
|
||
setObject,
|
||
remove,
|
||
save,
|
||
} from './services/store';
|
||
```
|
||
|
||
### 7.2 初始化存储（应用启动时）
|
||
|
||
```typescript
|
||
// App.tsx 或 main.tsx
|
||
import { useEffect, useState } from 'react';
|
||
import { initStore } from './services/store';
|
||
|
||
function App() {
|
||
const [storeReady, setStoreReady] = useState(false);
|
||
|
||
useEffect(() => {
|
||
const init = async () => {
|
||
try {
|
||
await initStore();
|
||
setStoreReady(true);
|
||
} catch (error) {
|
||
console.error('存储初始化失败:', error);
|
||
}
|
||
};
|
||
init();
|
||
}, []);
|
||
|
||
if (!storeReady) {
|
||
return <div>加载中...</div>;
|
||
}
|
||
|
||
return <MainApp />;
|
||
}
|
||
```
|
||
|
||
### 7.3 读取存储数据
|
||
|
||
```typescript
|
||
// 使用模块化 API
|
||
import { authStorage, setupStorage, configStorage } from './services/store';
|
||
|
||
// 获取用户名
|
||
const username = await authStorage.getUsername();
|
||
console.log('用户名:', username);
|
||
|
||
// 获取用户信息对象
|
||
const userInfo = await authStorage.getUserInfo();
|
||
console.log('用户信息:', userInfo);
|
||
|
||
// 获取在线状态
|
||
const isOnline = await authStorage.getOnlineStatus();
|
||
console.log('在线状态:', isOnline);
|
||
|
||
// 获取初始化状态
|
||
const setupState = await setupStorage.getState();
|
||
console.log('初始化状态:', setupState);
|
||
/*
|
||
{
|
||
completed: false,
|
||
currentStep: 1,
|
||
serverHost: 'https://agent.qiming.com',
|
||
serverPort: 443,
|
||
agentPort: 9086,
|
||
fileServerPort: 60000,
|
||
proxyPort: 9099,
|
||
workspaceDir: ''
|
||
}
|
||
*/
|
||
|
||
// 检查是否完成初始化
|
||
const isSetupCompleted = await setupStorage.isCompleted();
|
||
console.log('是否完成初始化:', isSetupCompleted);
|
||
|
||
// 获取当前步骤
|
||
const currentStep = await setupStorage.getCurrentStep();
|
||
console.log('当前步骤:', currentStep);
|
||
|
||
// 获取当前场景
|
||
const sceneId = await configStorage.getCurrentSceneId();
|
||
console.log('当前场景:', sceneId);
|
||
|
||
// 获取自定义场景列表
|
||
const customScenes = await configStorage.getCustomScenes();
|
||
console.log('自定义场景:', customScenes);
|
||
```
|
||
|
||
### 7.4 写入存储数据
|
||
|
||
```typescript
|
||
import { authStorage, setupStorage, configStorage } from './services/store';
|
||
|
||
// 保存用户名和密码
|
||
await authStorage.setUsername('admin');
|
||
await authStorage.setPassword('encrypted_password');
|
||
|
||
// 保存用户信息对象
|
||
await authStorage.setUserInfo({
|
||
username: 'admin',
|
||
displayName: '管理员',
|
||
email: 'admin@example.com',
|
||
});
|
||
|
||
// 保存在线状态
|
||
await authStorage.setOnlineStatus(true);
|
||
|
||
// 保存初始化配置（步骤1）
|
||
await setupStorage.saveStep1({
|
||
serverHost: 'https://api.example.com',
|
||
agentPort: 9086,
|
||
fileServerPort: 60000,
|
||
proxyPort: 9099,
|
||
workspaceDir: '/Users/test/workspace',
|
||
});
|
||
|
||
// 完成步骤2（登录）
|
||
await setupStorage.completeStep2();
|
||
|
||
// 完成初始化
|
||
await setupStorage.complete();
|
||
|
||
// 保存当前场景
|
||
await configStorage.setCurrentSceneId('production');
|
||
|
||
// 添加自定义场景
|
||
await configStorage.addCustomScene({
|
||
id: 'my-scene',
|
||
name: '我的场景',
|
||
description: '测试用场景',
|
||
server: {
|
||
apiUrl: 'https://api.example.com',
|
||
},
|
||
local: {
|
||
agent: { host: 'localhost', port: 9086 },
|
||
vnc: { host: 'localhost', port: 5900 },
|
||
fileServer: { host: 'localhost', port: 60000 },
|
||
websocket: { host: 'localhost', port: 9088 },
|
||
},
|
||
});
|
||
```
|
||
|
||
### 7.5 删除存储数据
|
||
|
||
```typescript
|
||
import { authStorage, configStorage, setupStorage, clear } from './services/store';
|
||
|
||
// 清除认证信息（登出）
|
||
await authStorage.clear();
|
||
|
||
// 清除配置信息
|
||
await configStorage.clear();
|
||
|
||
// 重置初始化向导
|
||
await setupStorage.reset();
|
||
|
||
// 清除所有数据
|
||
await clear();
|
||
```
|
||
|
||
### 7.6 React Hook 示例
|
||
|
||
```typescript
|
||
// hooks/useSetupState.ts
|
||
import { useState, useEffect, useCallback } from 'react';
|
||
import { setupStorage, SetupState } from '../services/store';
|
||
|
||
export function useSetupState() {
|
||
const [state, setState] = useState<SetupState | null>(null);
|
||
const [loading, setLoading] = useState(true);
|
||
|
||
// 加载状态
|
||
const loadState = useCallback(async () => {
|
||
setLoading(true);
|
||
try {
|
||
const data = await setupStorage.getState();
|
||
setState(data);
|
||
} catch (error) {
|
||
console.error('加载初始化状态失败:', error);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}, []);
|
||
|
||
// 初始加载
|
||
useEffect(() => {
|
||
loadState();
|
||
}, [loadState]);
|
||
|
||
// 更新状态
|
||
const updateState = useCallback(async (updates: Partial<SetupState>) => {
|
||
await setupStorage.setState(updates);
|
||
await loadState(); // 重新加载
|
||
}, [loadState]);
|
||
|
||
// 重置状态
|
||
const resetState = useCallback(async () => {
|
||
await setupStorage.reset();
|
||
await loadState();
|
||
}, [loadState]);
|
||
|
||
return {
|
||
state,
|
||
loading,
|
||
updateState,
|
||
resetState,
|
||
reload: loadState,
|
||
};
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// hooks/useAuth.ts
|
||
import { useState, useEffect, useCallback } from 'react';
|
||
import { authStorage, AuthUserInfo } from '../services/store';
|
||
|
||
export function useAuth() {
|
||
const [userInfo, setUserInfo] = useState<AuthUserInfo | null>(null);
|
||
const [isOnline, setIsOnline] = useState<boolean>(false);
|
||
const [loading, setLoading] = useState(true);
|
||
|
||
// 加载认证信息
|
||
const loadAuth = useCallback(async () => {
|
||
setLoading(true);
|
||
try {
|
||
const [info, online] = await Promise.all([
|
||
authStorage.getUserInfo(),
|
||
authStorage.getOnlineStatus(),
|
||
]);
|
||
setUserInfo(info);
|
||
setIsOnline(online ?? false);
|
||
} catch (error) {
|
||
console.error('加载认证信息失败:', error);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}, []);
|
||
|
||
useEffect(() => {
|
||
loadAuth();
|
||
}, [loadAuth]);
|
||
|
||
// 登录
|
||
const login = useCallback(async (username: string, password: string, userInfo: AuthUserInfo) => {
|
||
await authStorage.setUsername(username);
|
||
await authStorage.setPassword(password);
|
||
await authStorage.setUserInfo(userInfo);
|
||
await authStorage.setOnlineStatus(true);
|
||
await loadAuth();
|
||
}, [loadAuth]);
|
||
|
||
// 登出
|
||
const logout = useCallback(async () => {
|
||
await authStorage.clear();
|
||
setUserInfo(null);
|
||
setIsOnline(false);
|
||
}, []);
|
||
|
||
return {
|
||
userInfo,
|
||
isOnline,
|
||
loading,
|
||
login,
|
||
logout,
|
||
reload: loadAuth,
|
||
};
|
||
}
|
||
```
|
||
|
||
### 7.7 React 组件示例
|
||
|
||
```tsx
|
||
// components/SetupWizard.tsx
|
||
import React, { useState, useEffect } from 'react';
|
||
import { Form, Input, InputNumber, Button, Steps, message } from 'antd';
|
||
import { setupStorage, DEFAULT_SETUP_STATE } from '../services/store';
|
||
|
||
export default function SetupWizard({ onComplete }: { onComplete: () => void }) {
|
||
const [currentStep, setCurrentStep] = useState(1);
|
||
const [loading, setLoading] = useState(true);
|
||
const [form] = Form.useForm();
|
||
|
||
// 加载已保存的配置
|
||
useEffect(() => {
|
||
const loadConfig = async () => {
|
||
const state = await setupStorage.getState();
|
||
setCurrentStep(state.currentStep);
|
||
form.setFieldsValue({
|
||
serverHost: state.serverHost,
|
||
agentPort: state.agentPort,
|
||
fileServerPort: state.fileServerPort,
|
||
proxyPort: state.proxyPort,
|
||
workspaceDir: state.workspaceDir,
|
||
});
|
||
setLoading(false);
|
||
};
|
||
loadConfig();
|
||
}, [form]);
|
||
|
||
// 保存步骤1
|
||
const handleStep1Submit = async () => {
|
||
try {
|
||
const values = await form.validateFields();
|
||
await setupStorage.saveStep1(values);
|
||
setCurrentStep(2);
|
||
message.success('基础配置已保存');
|
||
} catch (error) {
|
||
message.error('请填写完整配置');
|
||
}
|
||
};
|
||
|
||
// 完成初始化
|
||
const handleComplete = async () => {
|
||
await setupStorage.complete();
|
||
message.success('初始化完成');
|
||
onComplete();
|
||
};
|
||
|
||
if (loading) {
|
||
return <div>加载中...</div>;
|
||
}
|
||
|
||
return (
|
||
<div>
|
||
<Steps current={currentStep - 1}>
|
||
<Steps.Step title="基础设置" />
|
||
<Steps.Step title="账号登录" />
|
||
<Steps.Step title="依赖安装" />
|
||
</Steps>
|
||
|
||
{currentStep === 1 && (
|
||
<Form form={form} layout="vertical">
|
||
<Form.Item
|
||
name="serverHost"
|
||
label="服务域名"
|
||
rules={[{ required: true }]}
|
||
>
|
||
<Input placeholder="https://api.example.com" />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="agentPort"
|
||
label="Agent 端口"
|
||
rules={[{ required: true }]}
|
||
>
|
||
<InputNumber min={1} max={65535} />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="fileServerPort"
|
||
label="文件服务端口"
|
||
rules={[{ required: true }]}
|
||
>
|
||
<InputNumber min={1} max={65535} />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="proxyPort"
|
||
label="代理服务端口"
|
||
rules={[{ required: true }]}
|
||
>
|
||
<InputNumber min={1} max={65535} />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="workspaceDir"
|
||
label="工作区目录"
|
||
rules={[{ required: true }]}
|
||
>
|
||
<Input placeholder="/path/to/workspace" />
|
||
</Form.Item>
|
||
<Button type="primary" onClick={handleStep1Submit}>
|
||
下一步
|
||
</Button>
|
||
</Form>
|
||
)}
|
||
|
||
{currentStep === 2 && (
|
||
<div>
|
||
{/* 登录表单 */}
|
||
<Button onClick={() => setupStorage.completeStep2().then(() => setCurrentStep(3))}>
|
||
登录完成，下一步
|
||
</Button>
|
||
</div>
|
||
)}
|
||
|
||
{currentStep === 3 && (
|
||
<div>
|
||
{/* 依赖安装界面 */}
|
||
<Button type="primary" onClick={handleComplete}>
|
||
完成初始化
|
||
</Button>
|
||
</div>
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 7.8 前端与 Rust 的职责划分
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端 (TypeScript/React) │
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 读取数据 │ │ 写入数据 │ │ 删除数据 │ │
|
||
│ │ ✅ 支持 │ │ ✅ 支持 │ │ ✅ 支持 │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ │
|
||
│ 使用: store.ts 中的 authStorage / setupStorage / ... │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ Tauri Store Plugin
|
||
│ (qiming_store.bin)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 后端 (Rust) │
|
||
│ │
|
||
│ ┌─────────────┐ │
|
||
│ │ 读取数据 │ 用于服务启动、配置获取等 │
|
||
│ │ ✅ 支持 │ │
|
||
│ └─────────────┘ │
|
||
│ │
|
||
│ 写入/删除: ❌ 不支持（由前端负责） │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**设计原则**：
|
||
- **前端**：负责所有 UI 交互相关的数据读写（用户配置、登录状态等）
|
||
- **Rust 后端**：只读取配置用于服务启动、连接验证等系统级操作
|
||
|
||
这样设计的好处：
|
||
1. 数据流向清晰，避免前后端同时写入导致的冲突
|
||
2. 前端可即时响应用户操作，无需等待 Rust 命令返回
|
||
3. Rust 专注于服务逻辑，不处理 UI 状态
|
||
|
||
---
|
||
|
||
## 存储 API 概览
|
||
|
||
### 通用操作
|
||
|
||
```typescript
|
||
// 初始化存储
|
||
await initStore();
|
||
|
||
// 字符串操作
|
||
await getString(key);
|
||
await setString(key, value);
|
||
|
||
// 布尔值操作
|
||
await getBoolean(key);
|
||
await setBoolean(key, value);
|
||
|
||
// 数值操作
|
||
await getNumber(key);
|
||
await setNumber(key, value);
|
||
|
||
// 对象操作（JSON）
|
||
await getObject<T>(key);
|
||
await setObject<T>(key, value);
|
||
|
||
// 其他操作
|
||
await remove(key);
|
||
await has(key);
|
||
await save();
|
||
await clear();
|
||
await keys();
|
||
```
|
||
|
||
### 模块化存储操作
|
||
|
||
| 模块 | 导出名 | 说明 |
|
||
|------|--------|------|
|
||
| 认证 | `authStorage` | 用户登录信息管理 |
|
||
| 配置 | `configStorage` | 场景配置管理 |
|
||
| 设置 | `settingsStorage` | 应用设置管理 |
|
||
| 向导 | `setupStorage` | 初始化向导状态管理 |
|
||
|
||
---
|
||
|
||
## 数据清理
|
||
|
||
### 清除认证信息
|
||
|
||
```typescript
|
||
await authStorage.clear();
|
||
```
|
||
|
||
### 清除配置信息
|
||
|
||
```typescript
|
||
await configStorage.clear();
|
||
```
|
||
|
||
### 重置初始化向导
|
||
|
||
```typescript
|
||
await setupStorage.reset();
|
||
```
|
||
|
||
### 清除所有数据
|
||
|
||
```typescript
|
||
await clear();
|
||
```
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| 1.3 | 2026-02-05 | 更新默认域名：生产环境为 agent.qiming.com，新增 server_port 字段 |
|
||
| 1.2 | 2026-02-04 | Rust 示例精简为只读操作，明确前后端职责划分 |
|
||
| 1.1 | 2026-02-04 | 添加 Rust 和 TypeScript 调用示例 |
|
||
| 1.0 | 2026-02-04 | 初始版本，包含认证、配置、设置、向导、依赖管理 |
|