ecb36f0ed8
- Changed the OpenClaw submodule URL to the official GitHub repository for proper integration. - Implemented automatic gateway token generation on first launch, ensuring seamless authentication for users. - Updated the gateway manager to utilize the generated token for WebSocket connections.
4297 lines
144 KiB
Markdown
4297 lines
144 KiB
Markdown
# ClawX 项目架构与版本大纲
|
||
|
||
> 基于 OpenClaw 的图形化 AI 助手应用
|
||
> 技术栈：Electron + React + TypeScript
|
||
> 代码规范：全部英文注释、
|
||
> 开发规范：每一个模块开发完成后，写好完整单测，在{project}/build_process/目录中，更新proecess.md, 增加当前feature.md文档(保持commit_X_feat.md格式)，提交commit。
|
||
> 图形支持语言：与openClaw保持一致
|
||
> 如果有疑问请重新参考当前文档
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 项目定位
|
||
|
||
**ClawX** 是 OpenClaw 的图形化封装层，旨在提供：
|
||
|
||
- 🎯 **零命令行体验** - 通过 GUI 完成所有安装、配置和使用
|
||
- 🎨 **现代化 UI** - 美观、直观的桌面应用界面
|
||
- 📦 **开箱即用** - 预装精选技能包，即刻可用
|
||
- 🖥️ **跨平台** - macOS / Windows / Linux 统一体验
|
||
- 🔄 **无缝集成** - 与 OpenClaw 生态完全兼容
|
||
|
||
### 1.2 目标用户
|
||
|
||
| 用户群体 | 痛点 | ClawX 解决方案 |
|
||
|----------|------|----------------|
|
||
| 非技术用户 | 命令行恐惧 | 可视化安装向导 |
|
||
| 效率追求者 | 配置繁琐 | 一键预设技能包 |
|
||
| 跨平台用户 | 体验不一致 | 统一 UI 设计语言 |
|
||
| AI 尝鲜者 | 门槛高 | 引导式 onboarding |
|
||
|
||
### 1.3 与 OpenClaw 的关系
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ClawX App │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ Electron Main Process │ │
|
||
│ │ - 窗口管理、系统托盘、自动更新 │ │
|
||
│ │ - Gateway 进程管理 │ │
|
||
│ │ - Node.js 环境检测/安装 │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ React Renderer Process │ │
|
||
│ │ - 现代化 UI 界面 │ │
|
||
│ │ - WebSocket 通信层 │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
└────────────────────────┬────────────────────────────────┘
|
||
│ WebSocket (JSON-RPC)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ OpenClaw Gateway (上游) │
|
||
│ - 消息通道管理 (WhatsApp/Telegram/Discord...) │
|
||
│ - AI Agent 运行时 │
|
||
│ - 技能/插件系统 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**核心原则**：
|
||
- ✅ **封装而非 Fork** - 通过 npm 依赖引入 openclaw
|
||
- ✅ **不修改上游** - 所有定制通过配置、插件实现
|
||
- ✅ **版本绑定** - 每个 ClawX 版本绑定特定 openclaw 版本
|
||
- ✅ **CLI 兼容** - 命令行保持 `openclaw` 命令，不引入 `clawx` CLI
|
||
|
||
openclaw project remote: https://github.com/openclaw/openclaw
|
||
### 1.4 CLI 兼容性设计
|
||
|
||
ClawX 是 OpenClaw 的**图形化增强层**，而非替代品。用户可以同时使用 GUI 和 CLI：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ClawX + OpenClaw 共存模式 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 用户交互方式 │
|
||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||
│ │ ClawX GUI │ │ openclaw CLI │ │
|
||
│ │ (图形界面) │ │ (命令行) │ │
|
||
│ │ │ │ │ │
|
||
│ │ • 点击操作 │ │ • openclaw doctor │ │
|
||
│ │ • 可视化配置 │ │ • openclaw plugins │ │
|
||
│ │ • 安装向导 │ │ • openclaw config │ │
|
||
│ │ • 普通用户首选 │ │ • 高级用户/脚本 │ │
|
||
│ └──────────┬──────────┘ └──────────┬──────────┘ │
|
||
│ │ │ │
|
||
│ └────────────┬─────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────┐ │
|
||
│ │ OpenClaw Gateway │ │
|
||
│ │ (共享同一实例) │ │
|
||
│ └─────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────┴────────────┐ │
|
||
│ ▼ ▼ │
|
||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||
│ │ ~/.openclaw/ │ │ OpenClaw 配置/数据 │ │
|
||
│ │ (共享配置目录) │ │ (技能/插件/会话) │ │
|
||
│ └─────────────────────┘ └─────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### CLI 兼容性原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **命令一致** | 使用 `openclaw` 命令，不引入 `clawx` CLI |
|
||
| **配置共享** | GUI 和 CLI 共享 `~/.openclaw/` 配置目录 |
|
||
| **Gateway 共享** | GUI 和 CLI 连接同一个 Gateway 实例 |
|
||
| **功能互补** | GUI 简化常用操作，CLI 支持高级/自动化场景 |
|
||
|
||
#### 用户使用场景
|
||
|
||
**场景 A: 纯 GUI 用户 (新手)**
|
||
```
|
||
1. 安装 ClawX.app
|
||
2. 通过安装向导完成配置
|
||
3. 日常使用 GUI 界面
|
||
4. 无需接触命令行
|
||
```
|
||
|
||
**场景 B: GUI + CLI 混合用户 (进阶)**
|
||
```
|
||
1. 安装 ClawX.app (自动包含 openclaw CLI)
|
||
2. 日常使用 GUI 界面
|
||
3. 需要时打开终端使用 CLI:
|
||
- openclaw doctor # 健康检查
|
||
- openclaw plugins list # 查看插件
|
||
- openclaw config get # 查看配置
|
||
```
|
||
|
||
**场景 C: CLI 优先用户 (开发者)**
|
||
```
|
||
1. 安装 ClawX.app 或单独安装 openclaw CLI
|
||
2. 主要使用命令行操作
|
||
3. 偶尔打开 GUI 查看状态或配置复杂选项
|
||
```
|
||
|
||
#### ClawX 安装时的 CLI 处理
|
||
|
||
```typescript
|
||
// electron/installer/cli-setup.ts
|
||
|
||
/**
|
||
* ClawX 安装时确保 openclaw CLI 可用
|
||
* 不创建 clawx 命令，保持与上游一致
|
||
*/
|
||
export async function ensureOpenClawCli(): Promise<void> {
|
||
const isInstalled = await checkCliInstalled('openclaw');
|
||
|
||
if (!isInstalled) {
|
||
// 通过 npm 全局安装 openclaw
|
||
await privilegeManager.execAsAdmin(
|
||
'npm install -g openclaw',
|
||
{ reason: '安装 OpenClaw 命令行工具' }
|
||
);
|
||
}
|
||
|
||
// 确保 PATH 包含 npm 全局目录
|
||
await pathManager.ensureNpmGlobalPath();
|
||
|
||
// 验证安装
|
||
const version = await exec('openclaw --version');
|
||
console.log(`OpenClaw CLI installed: ${version}`);
|
||
}
|
||
|
||
/**
|
||
* ClawX 不创建自己的 CLI 命令
|
||
* 所有命令行操作都通过 openclaw 完成
|
||
*/
|
||
// ❌ 不会有 clawx CLI
|
||
// ✅ 只有 openclaw CLI
|
||
```
|
||
|
||
#### GUI 与 CLI 的功能映射
|
||
|
||
| 操作 | ClawX GUI | openclaw CLI |
|
||
|------|-----------|--------------|
|
||
| 健康检查 | 设置 → 诊断 → 运行检查 | `openclaw doctor` |
|
||
| 安装插件 | 技能市场 → 安装 | `openclaw plugins install <name>` |
|
||
| 查看配置 | 设置 → 高级 | `openclaw config get` |
|
||
| 修改配置 | 设置页面表单 | `openclaw config set <key> <value>` |
|
||
| 查看状态 | Dashboard | `openclaw status` |
|
||
| 查看日志 | 设置 → 日志 | `openclaw logs` |
|
||
| 连接通道 | 通道 → 添加 → 扫码 | `openclaw channels add whatsapp` |
|
||
| 发送消息 | 对话界面 | `openclaw message send <target> <msg>` |
|
||
|
||
#### 开发者模式: 终端集成
|
||
|
||
```typescript
|
||
// src/pages/Settings/DeveloperSettings.tsx
|
||
|
||
export function DeveloperSettings() {
|
||
const openTerminal = async () => {
|
||
// 在内置终端或系统终端中打开，预设好环境
|
||
await window.electron.ipcRenderer.invoke('terminal:open', {
|
||
cwd: '~/.openclaw',
|
||
env: {
|
||
// 确保 openclaw 命令可用
|
||
PATH: `${process.env.PATH}:${npmGlobalBinPath}`,
|
||
},
|
||
});
|
||
};
|
||
|
||
return (
|
||
<Card>
|
||
<CardHeader>
|
||
<CardTitle>开发者工具</CardTitle>
|
||
</CardHeader>
|
||
<CardContent className="space-y-4">
|
||
{/* 快捷命令按钮 */}
|
||
<div className="grid grid-cols-2 gap-2">
|
||
<Button variant="outline" onClick={() => runCommand('openclaw doctor')}>
|
||
<Terminal className="w-4 h-4 mr-2" />
|
||
运行健康检查
|
||
</Button>
|
||
<Button variant="outline" onClick={() => runCommand('openclaw status --all')}>
|
||
<Activity className="w-4 h-4 mr-2" />
|
||
查看完整状态
|
||
</Button>
|
||
<Button variant="outline" onClick={() => runCommand('openclaw plugins list')}>
|
||
<Puzzle className="w-4 h-4 mr-2" />
|
||
列出插件
|
||
</Button>
|
||
<Button variant="outline" onClick={() => runCommand('openclaw config get')}>
|
||
<Settings className="w-4 h-4 mr-2" />
|
||
查看配置
|
||
</Button>
|
||
</div>
|
||
|
||
<Separator />
|
||
|
||
{/* 打开终端 */}
|
||
<Button variant="outline" className="w-full" onClick={openTerminal}>
|
||
<Terminal className="w-4 h-4 mr-2" />
|
||
打开终端 (已配置 openclaw 环境)
|
||
</Button>
|
||
|
||
<p className="text-xs text-muted-foreground">
|
||
ClawX 与 OpenClaw CLI 完全兼容，您可以在终端中使用 <code>openclaw</code> 命令进行高级操作。
|
||
</p>
|
||
</CardContent>
|
||
</Card>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 配置同步机制
|
||
|
||
```typescript
|
||
// electron/config/sync.ts
|
||
|
||
/**
|
||
* ClawX 和 openclaw CLI 共享同一配置文件
|
||
* 任何一方的修改都会实时反映到另一方
|
||
*/
|
||
export class ConfigSync {
|
||
private configPath = join(homedir(), '.openclaw', 'config.json');
|
||
private watcher: FSWatcher | null = null;
|
||
|
||
/**
|
||
* 监听配置文件变化 (CLI 修改时同步到 GUI)
|
||
*/
|
||
startWatching(): void {
|
||
this.watcher = watch(this.configPath, async () => {
|
||
const config = await this.readConfig();
|
||
// 通知渲染进程配置已更新
|
||
mainWindow?.webContents.send('config:updated', config);
|
||
});
|
||
}
|
||
|
||
/**
|
||
* GUI 修改配置时，写入共享配置文件 (CLI 可读取)
|
||
*/
|
||
async updateConfig(updates: Partial<OpenClawConfig>): Promise<void> {
|
||
const current = await this.readConfig();
|
||
const merged = deepMerge(current, updates);
|
||
await writeFile(this.configPath, JSON.stringify(merged, null, 2));
|
||
}
|
||
|
||
/**
|
||
* 配置文件位置说明
|
||
*
|
||
* ~/.openclaw/
|
||
* ├── config.json # 主配置 (GUI 和 CLI 共享)
|
||
* ├── credentials/ # 凭证存储
|
||
* ├── sessions/ # 会话数据
|
||
* └── skills/ # 用户技能
|
||
*
|
||
* ~/.clawx/
|
||
* ├── presets.json # ClawX 专属配置 (技能包选择等)
|
||
* └── ui-state.json # GUI 状态 (窗口位置等)
|
||
*/
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技术架构
|
||
|
||
### 2.1 技术栈选型
|
||
|
||
| 层级 | 技术 | 版本 | 选型理由 |
|
||
|------|------|------|----------|
|
||
| **运行时** | Electron | 33+ | 跨平台、嵌入 Node.js |
|
||
| **前端框架** | React | 19 | 生态丰富、hooks 模式 |
|
||
| **UI 组件** | shadcn/ui | latest | 可定制、现代设计 |
|
||
| **样式** | Tailwind CSS | 4.x | 原子化、快速开发 |
|
||
| **状态管理** | Zustand | 5.x | 轻量、TypeScript 友好 |
|
||
| **路由** | React Router | 7.x | 声明式、嵌套路由 |
|
||
| **构建工具** | Vite | 6.x | 极速 HMR |
|
||
| **打包工具** | electron-builder | latest | 多平台打包、自动更新 |
|
||
| **测试** | Vitest + Playwright | latest | 单元测试 + E2E |
|
||
| **语言** | TypeScript | 5.x | 类型安全 |
|
||
|
||
### 2.2 双端口架构与开发者模式
|
||
|
||
ClawX 采用**双端口分层架构**，区分普通用户界面与开发者管理后台：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 用户访问入口 │
|
||
├─────────────────────────────┬───────────────────────────────────┤
|
||
│ │ │
|
||
│ ┌─────────────────────┐ │ ┌─────────────────────────┐ │
|
||
│ │ ClawX GUI │ │ │ OpenClaw Control UI │ │
|
||
│ │ Port: 23333 │ │ │ Port: 18789 │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ 🎨 现代化界面 │ │ │ ⚙️ 原生管理后台 │ │
|
||
│ │ 📦 预装技能包 │──▶│ │ 🔧 高级配置 │ │
|
||
│ │ 🚀 一键安装向导 │ │ │ 📊 调试日志 │ │
|
||
│ │ 👤 普通用户 │ │ │ 👨💻 开发者/高级用户 │ │
|
||
│ └─────────────────────┘ │ └─────────────────────────┘ │
|
||
│ │ │
|
||
│ [开发者模式] ────────┼──────────────▶ │
|
||
│ │ │
|
||
└─────────────────────────────┴───────────────────────────────────┘
|
||
│
|
||
│ WebSocket (JSON-RPC)
|
||
▼
|
||
┌────────────────────────┐
|
||
│ OpenClaw Gateway │
|
||
│ 内部服务端口: 18789 │
|
||
└────────────────────────┘
|
||
```
|
||
|
||
#### 端口分配
|
||
|
||
| 端口 | 服务 | 用途 | 目标用户 |
|
||
|------|------|------|----------|
|
||
| **23333** | ClawX GUI | 默认图形化界面 | 所有用户 |
|
||
| **18789** | OpenClaw Control UI | Gateway 管理后台 | 开发者/高级用户 |
|
||
|
||
> **端口选择说明**：
|
||
> - `23333` - ClawX 专属端口，易记且不与常见服务冲突
|
||
> - `18789` - OpenClaw 原生端口，保持上游兼容
|
||
|
||
#### 开发者模式入口
|
||
|
||
```typescript
|
||
// src/components/layout/Sidebar.tsx
|
||
export function Sidebar() {
|
||
const [devModeClicks, setDevModeClicks] = useState(0);
|
||
|
||
// 连续点击 5 次版本号解锁开发者模式
|
||
const handleVersionClick = () => {
|
||
const clicks = devModeClicks + 1;
|
||
setDevModeClicks(clicks);
|
||
|
||
if (clicks >= 5) {
|
||
toast.success('开发者模式已解锁');
|
||
setDevModeClicks(0);
|
||
}
|
||
};
|
||
|
||
return (
|
||
<aside className="w-64 border-r flex flex-col h-full">
|
||
{/* 导航菜单 */}
|
||
<nav className="flex-1 p-4 space-y-1">
|
||
<NavItem href="/" icon={<Home />} label="概览" />
|
||
<NavItem href="/chat" icon={<MessageSquare />} label="对话" />
|
||
<NavItem href="/channels" icon={<Radio />} label="通道" />
|
||
<NavItem href="/skills" icon={<Puzzle />} label="技能" />
|
||
<NavItem href="/cron" icon={<Clock />} label="定时任务" />
|
||
<NavItem href="/settings" icon={<Settings />} label="设置" />
|
||
</nav>
|
||
|
||
{/* 底部版本信息 */}
|
||
<footer className="p-4 border-t">
|
||
<button onClick={handleVersionClick} className="text-xs text-muted">
|
||
ClawX v1.0.0
|
||
</button>
|
||
|
||
{/* 开发者模式入口 - 解锁后显示 */}
|
||
{isDevModeUnlocked && (
|
||
<Button
|
||
variant="ghost"
|
||
size="sm"
|
||
onClick={() => window.electron.openExternal('http://localhost:18789')}
|
||
>
|
||
<Terminal className="w-4 h-4 mr-2" />
|
||
开发者模式
|
||
</Button>
|
||
)}
|
||
</footer>
|
||
</aside>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 设置页面快捷入口
|
||
|
||
```typescript
|
||
// src/pages/Settings/AdvancedSettings.tsx
|
||
export function AdvancedSettings() {
|
||
return (
|
||
<Card>
|
||
<CardHeader>
|
||
<CardTitle>高级设置</CardTitle>
|
||
</CardHeader>
|
||
<CardContent className="space-y-4">
|
||
{/* 其他设置项 */}
|
||
|
||
<Separator />
|
||
|
||
{/* 开发者工具区域 */}
|
||
<div className="space-y-2">
|
||
<Label className="text-sm font-medium">开发者工具</Label>
|
||
<p className="text-xs text-muted-foreground">
|
||
访问 OpenClaw 原生管理后台，进行高级配置和调试
|
||
</p>
|
||
<Button
|
||
variant="outline"
|
||
onClick={() => window.electron.openExternal('http://localhost:18789')}
|
||
>
|
||
<ExternalLink className="w-4 h-4 mr-2" />
|
||
打开 OpenClaw 管理后台
|
||
</Button>
|
||
<p className="text-xs text-muted-foreground">
|
||
将在浏览器中打开 http://localhost:18789
|
||
</p>
|
||
</div>
|
||
</CardContent>
|
||
</Card>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 配置文件
|
||
|
||
```typescript
|
||
// electron/utils/config.ts
|
||
export const PORTS = {
|
||
/** ClawX 默认 GUI 端口 */
|
||
CLAWX_GUI: 23333,
|
||
|
||
/** OpenClaw Gateway 端口 (上游默认) */
|
||
OPENCLAW_GATEWAY: 18789,
|
||
} as const;
|
||
|
||
// 环境变量覆盖
|
||
export function getPort(key: keyof typeof PORTS): number {
|
||
const envKey = `CLAWX_PORT_${key}`;
|
||
const envValue = process.env[envKey];
|
||
return envValue ? parseInt(envValue, 10) : PORTS[key];
|
||
}
|
||
```
|
||
|
||
#### 使用场景对比
|
||
|
||
| 场景 | ClawX GUI (23333) | OpenClaw 后台 (18789) |
|
||
|------|-------------------|----------------------|
|
||
| 日常对话 | ✅ | ❌ |
|
||
| 查看消息记录 | ✅ | ✅ |
|
||
| 添加/管理通道 | ✅ (简化版) | ✅ (完整版) |
|
||
| 安装技能包 | ✅ | ❌ |
|
||
| 编辑技能配置 | ❌ | ✅ |
|
||
| 查看原始日志 | ❌ | ✅ |
|
||
| 插件管理 | ❌ | ✅ |
|
||
| JSON 配置编辑 | ❌ | ✅ |
|
||
| WebSocket 调试 | ❌ | ✅ |
|
||
| Cron 任务管理 | ✅ | ✅ |
|
||
|
||
### 2.3 目录结构
|
||
|
||
```
|
||
clawx/
|
||
├── .github/
|
||
│ ├── workflows/
|
||
│ │ ├── ci.yml # 持续集成
|
||
│ │ ├── release.yml # 自动发布
|
||
│ │ └── test.yml # 测试流水线
|
||
│ └── ISSUE_TEMPLATE/
|
||
│
|
||
├── electron/ # Electron 主进程
|
||
│ ├── main/
|
||
│ │ ├── index.ts # 主入口
|
||
│ │ ├── window.ts # 窗口管理
|
||
│ │ ├── tray.ts # 系统托盘
|
||
│ │ ├── menu.ts # 原生菜单
|
||
│ │ └── ipc-handlers.ts # IPC 处理器
|
||
│ │
|
||
│ ├── updater/ # 自动更新模块
|
||
│ │ ├── index.ts # 更新管理器入口
|
||
│ │ ├── checker.ts # 版本检查器
|
||
│ │ ├── downloader.ts # 下载管理
|
||
│ │ ├── notifier.ts # 更新通知
|
||
│ │ └── channels.ts # 更新通道配置
|
||
│ │
|
||
│ ├── gateway/
|
||
│ │ ├── manager.ts # Gateway 进程生命周期
|
||
│ │ ├── client.ts # WebSocket 客户端
|
||
│ │ ├── protocol.ts # JSON-RPC 协议定义
|
||
│ │ └── health.ts # 健康检查
|
||
│ │
|
||
│ ├── installer/
|
||
│ │ ├── node-installer.ts # Node.js 自动安装
|
||
│ │ ├── openclaw-installer.ts # openclaw npm 安装
|
||
│ │ ├── skill-installer.ts # 技能包安装
|
||
│ │ └── platform/
|
||
│ │ ├── darwin.ts # macOS 特定逻辑
|
||
│ │ ├── win32.ts # Windows 特定逻辑
|
||
│ │ └── linux.ts # Linux 特定逻辑
|
||
│ │
|
||
│ ├── privilege/ # 权限提升模块
|
||
│ │ ├── index.ts # 统一权限管理器
|
||
│ │ ├── darwin-admin.ts # macOS 管理员权限 (osascript)
|
||
│ │ ├── win32-admin.ts # Windows UAC 提升
|
||
│ │ └── linux-admin.ts # Linux pkexec/polkit
|
||
│ │
|
||
│ ├── env-config/ # 环境配置模块
|
||
│ │ ├── index.ts # 环境配置管理器
|
||
│ │ ├── path-manager.ts # PATH 环境变量管理
|
||
│ │ ├── api-keys.ts # API Key 安全存储
|
||
│ │ └── shell-profile.ts # Shell 配置文件管理
|
||
│ │
|
||
│ ├── preload/
|
||
│ │ └── index.ts # 预加载脚本 (contextBridge)
|
||
│ │
|
||
│ └── utils/
|
||
│ ├── logger.ts # 日志
|
||
│ ├── paths.ts # 路径管理
|
||
│ └── store.ts # 持久化存储 (electron-store)
|
||
│
|
||
├── src/ # React 渲染进程
|
||
│ ├── main.tsx # React 入口
|
||
│ ├── App.tsx # 根组件
|
||
│ │
|
||
│ ├── pages/ # 页面组件
|
||
│ │ ├── Dashboard/
|
||
│ │ │ ├── index.tsx
|
||
│ │ │ ├── StatusCard.tsx
|
||
│ │ │ └── QuickActions.tsx
|
||
│ │ ├── Chat/
|
||
│ │ │ ├── index.tsx
|
||
│ │ │ ├── MessageList.tsx
|
||
│ │ │ ├── InputArea.tsx
|
||
│ │ │ └── ToolCallCard.tsx
|
||
│ │ ├── Channels/
|
||
│ │ │ ├── index.tsx
|
||
│ │ │ ├── ChannelCard.tsx
|
||
│ │ │ └── QRScanner.tsx
|
||
│ │ ├── Skills/
|
||
│ │ │ ├── index.tsx
|
||
│ │ │ ├── SkillCard.tsx
|
||
│ │ │ ├── SkillMarket.tsx
|
||
│ │ │ └── BundleSelector.tsx
|
||
│ │ ├── Cron/ # 定时任务
|
||
│ │ │ ├── index.tsx # 任务列表页
|
||
│ │ │ ├── CronJobCard.tsx # 任务卡片组件
|
||
│ │ │ ├── CronEditor.tsx # 任务编辑器
|
||
│ │ │ ├── CronSchedulePicker.tsx # Cron 表达式选择器
|
||
│ │ │ └── CronHistory.tsx # 执行历史
|
||
│ │ ├── Settings/
|
||
│ │ │ ├── index.tsx
|
||
│ │ │ ├── GeneralSettings.tsx
|
||
│ │ │ ├── ProviderSettings.tsx
|
||
│ │ │ ├── ChannelsSettings.tsx # 通道连接配置 (从安装向导移出)
|
||
│ │ │ └── AdvancedSettings.tsx
|
||
│ │ └── Setup/ # 安装向导 (简化版，不含通道连接)
|
||
│ │ ├── index.tsx
|
||
│ │ ├── WelcomeStep.tsx
|
||
│ │ ├── RuntimeStep.tsx
|
||
│ │ ├── ProviderStep.tsx
|
||
│ │ └── SkillStep.tsx
|
||
│ │
|
||
│ ├── components/ # 通用组件
|
||
│ │ ├── ui/ # shadcn/ui 组件
|
||
│ │ │ ├── button.tsx
|
||
│ │ │ ├── card.tsx
|
||
│ │ │ ├── dialog.tsx
|
||
│ │ │ └── ...
|
||
│ │ ├── layout/
|
||
│ │ │ ├── Sidebar.tsx
|
||
│ │ │ ├── Header.tsx
|
||
│ │ │ └── MainLayout.tsx
|
||
│ │ └── common/
|
||
│ │ ├── LoadingSpinner.tsx
|
||
│ │ ├── ErrorBoundary.tsx
|
||
│ │ └── StatusBadge.tsx
|
||
│ │
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ │ ├── useGateway.ts # Gateway 连接状态
|
||
│ │ ├── useChannels.ts # 通道数据
|
||
│ │ ├── useSkills.ts # 技能数据
|
||
│ │ ├── useChat.ts # 聊天会话
|
||
│ │ ├── useCron.ts # 定时任务数据
|
||
│ │ └── useElectron.ts # IPC 通信
|
||
│ │
|
||
│ ├── stores/ # Zustand 状态管理
|
||
│ │ ├── gateway.ts # Gateway 状态
|
||
│ │ ├── channels.ts # 通道状态
|
||
│ │ ├── chat.ts # 聊天状态
|
||
│ │ ├── skills.ts # 技能状态
|
||
│ │ ├── cron.ts # 定时任务状态
|
||
│ │ └── settings.ts # 设置状态
|
||
│ │
|
||
│ ├── services/ # 服务层
|
||
│ │ ├── gateway-rpc.ts # Gateway RPC 调用封装
|
||
│ │ ├── skill-service.ts # 技能服务
|
||
│ │ ├── cron-service.ts # 定时任务服务
|
||
│ │ └── update-service.ts # 更新服务
|
||
│ │
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ │ ├── gateway.ts # Gateway 协议类型
|
||
│ │ ├── channel.ts # 通道类型
|
||
│ │ ├── skill.ts # 技能类型
|
||
│ │ ├── cron.ts # 定时任务类型
|
||
│ │ └── electron.d.ts # Electron API 类型
|
||
│ │
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── format.ts
|
||
│ │ └── platform.ts
|
||
│ │
|
||
│ └── styles/
|
||
│ ├── globals.css # 全局样式
|
||
│ └── themes/ # 主题定义
|
||
│ ├── light.css
|
||
│ └── dark.css
|
||
│
|
||
├── resources/ # 静态资源
|
||
│ ├── icons/ # 应用图标
|
||
│ │ ├── icon.icns # macOS
|
||
│ │ ├── icon.ico # Windows
|
||
│ │ └── icon.png # Linux
|
||
│ ├── skills/ # 预装技能包
|
||
│ │ ├── productivity.json
|
||
│ │ ├── developer.json
|
||
│ │ └── smart-home.json
|
||
│ └── locales/ # 国际化 (可选)
|
||
│ ├── en.json
|
||
│ └── zh-CN.json
|
||
│
|
||
├── scripts/ # 构建/工具脚本
|
||
│ ├── build.ts # 构建脚本
|
||
│ ├── release.ts # 发布脚本
|
||
│ ├── notarize.ts # macOS 公证
|
||
│ └── dev.ts # 开发脚本
|
||
│
|
||
├── tests/ # 测试
|
||
│ ├── unit/ # 单元测试
|
||
│ ├── integration/ # 集成测试
|
||
│ └── e2e/ # E2E 测试
|
||
│ ├── setup.spec.ts # 安装向导测试
|
||
│ ├── chat.spec.ts # 聊天功能测试
|
||
│ └── channels.spec.ts # 通道配置测试
|
||
│
|
||
├── .env.example # 环境变量示例
|
||
├── .eslintrc.cjs # ESLint 配置
|
||
├── .prettierrc # Prettier 配置
|
||
├── electron-builder.yml # 打包配置
|
||
├── package.json
|
||
├── tsconfig.json # TypeScript 配置 (主)
|
||
├── tsconfig.node.json # TypeScript 配置 (Node)
|
||
├── vite.config.ts # Vite 配置
|
||
├── tailwind.config.js # Tailwind 配置
|
||
├── CHANGELOG.md
|
||
├── LICENSE
|
||
└── README.md
|
||
```
|
||
|
||
### 2.4 核心模块设计
|
||
|
||
#### 2.4.1 Gateway 管理器
|
||
|
||
```typescript
|
||
// electron/gateway/manager.ts
|
||
import { spawn, ChildProcess } from 'child_process';
|
||
import { EventEmitter } from 'events';
|
||
import WebSocket from 'ws';
|
||
|
||
export interface GatewayStatus {
|
||
state: 'stopped' | 'starting' | 'running' | 'error';
|
||
port: number;
|
||
pid?: number;
|
||
uptime?: number;
|
||
error?: string;
|
||
}
|
||
|
||
export class GatewayManager extends EventEmitter {
|
||
private process: ChildProcess | null = null;
|
||
private ws: WebSocket | null = null;
|
||
private status: GatewayStatus = { state: 'stopped', port: 18789 };
|
||
|
||
// 启动 Gateway
|
||
async start(): Promise<void> {
|
||
if (this.status.state === 'running') return;
|
||
|
||
this.setStatus({ state: 'starting' });
|
||
|
||
try {
|
||
// 检查已有进程
|
||
const existing = await this.findExisting();
|
||
if (existing) {
|
||
await this.connect(existing.port);
|
||
return;
|
||
}
|
||
|
||
// 启动新进程
|
||
this.process = spawn('openclaw', [
|
||
'gateway', 'run',
|
||
'--port', String(this.status.port),
|
||
'--force'
|
||
], {
|
||
stdio: ['ignore', 'pipe', 'pipe'],
|
||
detached: true,
|
||
});
|
||
|
||
this.process.on('exit', (code) => {
|
||
this.setStatus({ state: 'stopped' });
|
||
this.emit('exit', code);
|
||
});
|
||
|
||
// 等待就绪并连接
|
||
await this.waitForReady();
|
||
await this.connect(this.status.port);
|
||
|
||
} catch (error) {
|
||
this.setStatus({ state: 'error', error: String(error) });
|
||
throw error;
|
||
}
|
||
}
|
||
|
||
// 停止 Gateway
|
||
async stop(): Promise<void> {
|
||
this.ws?.close();
|
||
this.process?.kill();
|
||
this.setStatus({ state: 'stopped' });
|
||
}
|
||
|
||
// RPC 调用
|
||
async rpc<T>(method: string, params?: unknown): Promise<T> {
|
||
return new Promise((resolve, reject) => {
|
||
if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
|
||
reject(new Error('Gateway not connected'));
|
||
return;
|
||
}
|
||
|
||
const id = crypto.randomUUID();
|
||
const handler = (data: WebSocket.Data) => {
|
||
const msg = JSON.parse(data.toString());
|
||
if (msg.id === id) {
|
||
this.ws?.off('message', handler);
|
||
if (msg.error) reject(msg.error);
|
||
else resolve(msg.result as T);
|
||
}
|
||
};
|
||
|
||
this.ws.on('message', handler);
|
||
this.ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
|
||
});
|
||
}
|
||
|
||
private setStatus(update: Partial<GatewayStatus>): void {
|
||
this.status = { ...this.status, ...update };
|
||
this.emit('status', this.status);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.4.2 安装向导流程
|
||
|
||
```typescript
|
||
// src/pages/Setup/index.tsx
|
||
import { useState } from 'react';
|
||
import { motion, AnimatePresence } from 'framer-motion';
|
||
|
||
interface SetupStep {
|
||
id: string;
|
||
title: string;
|
||
description: string;
|
||
component: React.ComponentType<StepProps>;
|
||
}
|
||
|
||
const steps: SetupStep[] = [
|
||
{
|
||
id: 'welcome',
|
||
title: '欢迎使用 ClawX',
|
||
description: '您的 AI 助手，即将启程',
|
||
component: WelcomeStep,
|
||
},
|
||
{
|
||
id: 'runtime',
|
||
title: '环境检测',
|
||
description: '检测并安装必要运行环境',
|
||
component: RuntimeStep,
|
||
},
|
||
{
|
||
id: 'provider',
|
||
title: '选择 AI 模型',
|
||
description: '配置您的 AI 服务提供商',
|
||
component: ProviderStep,
|
||
},
|
||
// NOTE: Channel step removed - 通道连接移至 Settings > Channels 页面
|
||
// 用户可在完成初始设置后自行配置消息通道
|
||
// NOTE: Skills selection step removed - 自动安装必要组件
|
||
// 用户无需手动选择，核心组件自动安装
|
||
{
|
||
id: 'installing',
|
||
title: '安装组件',
|
||
description: '正在安装必要的 AI 组件',
|
||
component: InstallingStep,
|
||
},
|
||
{
|
||
id: 'complete',
|
||
title: '设置完成',
|
||
description: '一切就绪，开始使用吧！',
|
||
component: CompleteStep,
|
||
},
|
||
];
|
||
|
||
export function SetupWizard() {
|
||
const [currentStep, setCurrentStep] = useState(0);
|
||
const [setupData, setSetupData] = useState<SetupData>({});
|
||
|
||
const step = steps[currentStep];
|
||
const StepComponent = step.component;
|
||
|
||
const handleNext = (data: Partial<SetupData>) => {
|
||
setSetupData({ ...setupData, ...data });
|
||
setCurrentStep((i) => Math.min(i + 1, steps.length - 1));
|
||
};
|
||
|
||
return (
|
||
<div className="min-h-screen bg-gradient-to-br from-slate-900 to-slate-800">
|
||
{/* 进度指示器 */}
|
||
<div className="flex justify-center pt-8">
|
||
{steps.map((s, i) => (
|
||
<div key={s.id} className="flex items-center">
|
||
<div className={cn(
|
||
'w-3 h-3 rounded-full transition-colors',
|
||
i <= currentStep ? 'bg-blue-500' : 'bg-slate-600'
|
||
)} />
|
||
{i < steps.length - 1 && (
|
||
<div className={cn(
|
||
'w-12 h-0.5 transition-colors',
|
||
i < currentStep ? 'bg-blue-500' : 'bg-slate-600'
|
||
)} />
|
||
)}
|
||
</div>
|
||
))}
|
||
</div>
|
||
|
||
{/* 步骤内容 */}
|
||
<AnimatePresence mode="wait">
|
||
<motion.div
|
||
key={step.id}
|
||
initial={{ opacity: 0, x: 20 }}
|
||
animate={{ opacity: 1, x: 0 }}
|
||
exit={{ opacity: 0, x: -20 }}
|
||
className="max-w-2xl mx-auto p-8"
|
||
>
|
||
<h1 className="text-3xl font-bold text-white mb-2">{step.title}</h1>
|
||
<p className="text-slate-400 mb-8">{step.description}</p>
|
||
|
||
<StepComponent
|
||
data={setupData}
|
||
onNext={handleNext}
|
||
onBack={() => setCurrentStep((i) => Math.max(i - 1, 0))}
|
||
/>
|
||
</motion.div>
|
||
</AnimatePresence>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 2.4.3 预装技能包定义
|
||
|
||
```typescript
|
||
// resources/skills/bundles.ts
|
||
export interface SkillBundle {
|
||
id: string;
|
||
name: string;
|
||
nameZh: string;
|
||
description: string;
|
||
descriptionZh: string;
|
||
icon: string;
|
||
skills: string[];
|
||
recommended?: boolean;
|
||
}
|
||
|
||
export const skillBundles: SkillBundle[] = [
|
||
{
|
||
id: 'productivity',
|
||
name: 'Productivity',
|
||
nameZh: '效率办公',
|
||
description: 'Calendar, reminders, notes, email management',
|
||
descriptionZh: '日历、提醒、笔记、邮件管理',
|
||
icon: '📋',
|
||
skills: [
|
||
'apple-reminders',
|
||
'apple-notes',
|
||
'himalaya',
|
||
'notion',
|
||
'obsidian',
|
||
'trello',
|
||
],
|
||
recommended: true,
|
||
},
|
||
{
|
||
id: 'developer',
|
||
name: 'Developer Tools',
|
||
nameZh: '开发者工具',
|
||
description: 'GitHub, coding assistant, terminal management',
|
||
descriptionZh: 'GitHub、代码助手、终端管理',
|
||
icon: '💻',
|
||
skills: [
|
||
'github',
|
||
'coding-agent',
|
||
'tmux',
|
||
],
|
||
recommended: true,
|
||
},
|
||
{
|
||
id: 'smart-home',
|
||
name: 'Smart Home',
|
||
nameZh: '智能家居',
|
||
description: 'Lights, music, device control',
|
||
descriptionZh: '灯光、音乐、设备控制',
|
||
icon: '🏠',
|
||
skills: [
|
||
'openhue',
|
||
'sonoscli',
|
||
'spotify-player',
|
||
],
|
||
},
|
||
{
|
||
id: 'media',
|
||
name: 'Media & Creative',
|
||
nameZh: '多媒体创作',
|
||
description: 'Image generation, video processing, audio transcription',
|
||
descriptionZh: '图片生成、视频处理、音频转写',
|
||
icon: '🎨',
|
||
skills: [
|
||
'openai-image-gen',
|
||
'nano-banana-pro',
|
||
'video-frames',
|
||
'openai-whisper-api',
|
||
],
|
||
},
|
||
{
|
||
id: 'communication',
|
||
name: 'Communication',
|
||
nameZh: '通讯增强',
|
||
description: 'Messaging, voice calls, notifications',
|
||
descriptionZh: '消息管理、语音通话、通知',
|
||
icon: '💬',
|
||
skills: [
|
||
'discord',
|
||
'slack',
|
||
'voice-call',
|
||
'imsg',
|
||
],
|
||
},
|
||
{
|
||
id: 'security',
|
||
name: 'Security & Privacy',
|
||
nameZh: '安全隐私',
|
||
description: 'Password management, secrets',
|
||
descriptionZh: '密码管理、密钥存储',
|
||
icon: '🔐',
|
||
skills: [
|
||
'1password',
|
||
],
|
||
},
|
||
{
|
||
id: 'information',
|
||
name: 'Information',
|
||
nameZh: '信息获取',
|
||
description: 'Weather, news, web browsing',
|
||
descriptionZh: '天气、新闻、网页浏览',
|
||
icon: '🌐',
|
||
skills: [
|
||
'weather',
|
||
'blogwatcher',
|
||
'summarize',
|
||
],
|
||
},
|
||
];
|
||
```
|
||
|
||
### 2.5 默认预装机制设计
|
||
|
||
ClawX 需要在代码层面实现**默认技能**和**默认扩展**的预装机制，确保用户开箱即用。
|
||
|
||
#### 2.5.1 预装配置定义
|
||
|
||
```typescript
|
||
// electron/presets/defaults.ts
|
||
|
||
/**
|
||
* ClawX 预装配置
|
||
* 定义首次安装时默认启用的技能和扩展
|
||
*/
|
||
export interface ClawXPresets {
|
||
/** 默认启用的技能 ID 列表 */
|
||
skills: string[];
|
||
|
||
/** 默认启用的扩展 ID 列表 */
|
||
extensions: string[];
|
||
|
||
/** 默认技能包 (用户可在安装向导中选择) */
|
||
defaultBundles: string[];
|
||
|
||
/** 核心技能 (始终启用，用户不可禁用) */
|
||
coreSkills: string[];
|
||
|
||
/** 核心扩展 (始终启用，用户不可禁用) */
|
||
coreExtensions: string[];
|
||
}
|
||
|
||
/**
|
||
* ClawX 默认预装配置
|
||
*/
|
||
export const CLAWX_PRESETS: ClawXPresets = {
|
||
// 默认启用的技能 (首次安装自动启用)
|
||
skills: [
|
||
// Tier 1: 核心体验技能
|
||
'coding-agent', // 代码助手 (类似 opencode)
|
||
'canvas', // Canvas UI
|
||
'summarize', // 内容摘要
|
||
|
||
// Tier 2: 常用工具技能
|
||
'weather', // 天气查询
|
||
'github', // GitHub 集成
|
||
'clawhub', // 技能市场
|
||
],
|
||
|
||
// 默认启用的扩展
|
||
extensions: [
|
||
'lobster', // UI 美化
|
||
'memory-core', // 记忆系统
|
||
],
|
||
|
||
// 默认推荐的技能包 (安装向导中预选)
|
||
defaultBundles: [
|
||
'productivity',
|
||
'developer',
|
||
],
|
||
|
||
// 核心技能 (不可禁用)
|
||
coreSkills: [
|
||
'coding-agent', // 代码能力是核心体验
|
||
],
|
||
|
||
// 核心扩展 (不可禁用)
|
||
coreExtensions: [
|
||
'memory-core', // 记忆是核心功能
|
||
],
|
||
};
|
||
```
|
||
|
||
#### 2.5.2 预装加载器
|
||
|
||
```typescript
|
||
// electron/installer/preset-loader.ts
|
||
|
||
import { CLAWX_PRESETS } from '../presets/defaults';
|
||
import { GatewayManager } from '../gateway/manager';
|
||
|
||
export interface PresetLoadResult {
|
||
skills: { id: string; status: 'loaded' | 'failed'; error?: string }[];
|
||
extensions: { id: string; status: 'loaded' | 'failed'; error?: string }[];
|
||
}
|
||
|
||
export class PresetLoader {
|
||
constructor(private gateway: GatewayManager) {}
|
||
|
||
/**
|
||
* 首次安装时加载所有预装项
|
||
*/
|
||
async loadInitialPresets(): Promise<PresetLoadResult> {
|
||
const result: PresetLoadResult = { skills: [], extensions: [] };
|
||
|
||
// 1. 加载核心扩展 (优先级最高)
|
||
for (const extId of CLAWX_PRESETS.coreExtensions) {
|
||
const status = await this.loadExtension(extId, { required: true });
|
||
result.extensions.push({ id: extId, ...status });
|
||
}
|
||
|
||
// 2. 加载默认扩展
|
||
for (const extId of CLAWX_PRESETS.extensions) {
|
||
if (!CLAWX_PRESETS.coreExtensions.includes(extId)) {
|
||
const status = await this.loadExtension(extId, { required: false });
|
||
result.extensions.push({ id: extId, ...status });
|
||
}
|
||
}
|
||
|
||
// 3. 加载核心技能
|
||
for (const skillId of CLAWX_PRESETS.coreSkills) {
|
||
const status = await this.loadSkill(skillId, { required: true });
|
||
result.skills.push({ id: skillId, ...status });
|
||
}
|
||
|
||
// 4. 加载默认技能
|
||
for (const skillId of CLAWX_PRESETS.skills) {
|
||
if (!CLAWX_PRESETS.coreSkills.includes(skillId)) {
|
||
const status = await this.loadSkill(skillId, { required: false });
|
||
result.skills.push({ id: skillId, ...status });
|
||
}
|
||
}
|
||
|
||
return result;
|
||
}
|
||
|
||
/**
|
||
* 加载用户选择的技能包
|
||
*/
|
||
async loadBundles(bundleIds: string[]): Promise<void> {
|
||
const { skillBundles } = await import('../../resources/skills/bundles');
|
||
|
||
for (const bundleId of bundleIds) {
|
||
const bundle = skillBundles.find(b => b.id === bundleId);
|
||
if (bundle) {
|
||
for (const skillId of bundle.skills) {
|
||
await this.loadSkill(skillId, { required: false });
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
private async loadSkill(
|
||
skillId: string,
|
||
opts: { required: boolean }
|
||
): Promise<{ status: 'loaded' | 'failed'; error?: string }> {
|
||
try {
|
||
// 通过 Gateway RPC 启用技能
|
||
await this.gateway.rpc('skills.enable', { skillId });
|
||
return { status: 'loaded' };
|
||
} catch (error) {
|
||
if (opts.required) {
|
||
throw new Error(`Failed to load required skill: ${skillId}`);
|
||
}
|
||
return { status: 'failed', error: String(error) };
|
||
}
|
||
}
|
||
|
||
private async loadExtension(
|
||
extId: string,
|
||
opts: { required: boolean }
|
||
): Promise<{ status: 'loaded' | 'failed'; error?: string }> {
|
||
try {
|
||
// 通过 Gateway RPC 启用扩展
|
||
await this.gateway.rpc('plugins.enable', { pluginId: extId });
|
||
return { status: 'loaded' };
|
||
} catch (error) {
|
||
if (opts.required) {
|
||
throw new Error(`Failed to load required extension: ${extId}`);
|
||
}
|
||
return { status: 'failed', error: String(error) };
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.5.3 预装状态管理
|
||
|
||
```typescript
|
||
// src/stores/presets.ts
|
||
|
||
import { create } from 'zustand';
|
||
import { persist } from 'zustand/middleware';
|
||
|
||
interface PresetState {
|
||
/** 是否已完成首次预装 */
|
||
initialized: boolean;
|
||
|
||
/** 用户选择的技能包 */
|
||
selectedBundles: string[];
|
||
|
||
/** 用户额外启用的技能 */
|
||
enabledSkills: string[];
|
||
|
||
/** 用户禁用的默认技能 (不包括核心技能) */
|
||
disabledSkills: string[];
|
||
|
||
/** 用户额外启用的扩展 */
|
||
enabledExtensions: string[];
|
||
|
||
/** 用户禁用的默认扩展 (不包括核心扩展) */
|
||
disabledExtensions: string[];
|
||
|
||
// Actions
|
||
setInitialized: (value: boolean) => void;
|
||
setSelectedBundles: (bundles: string[]) => void;
|
||
toggleSkill: (skillId: string, enabled: boolean) => void;
|
||
toggleExtension: (extId: string, enabled: boolean) => void;
|
||
|
||
// Computed
|
||
getEffectiveSkills: () => string[];
|
||
getEffectiveExtensions: () => string[];
|
||
}
|
||
|
||
export const usePresetStore = create<PresetState>()(
|
||
persist(
|
||
(set, get) => ({
|
||
initialized: false,
|
||
selectedBundles: [],
|
||
enabledSkills: [],
|
||
disabledSkills: [],
|
||
enabledExtensions: [],
|
||
disabledExtensions: [],
|
||
|
||
setInitialized: (value) => set({ initialized: value }),
|
||
|
||
setSelectedBundles: (bundles) => set({ selectedBundles: bundles }),
|
||
|
||
toggleSkill: (skillId, enabled) => {
|
||
const { enabledSkills, disabledSkills } = get();
|
||
if (enabled) {
|
||
set({
|
||
enabledSkills: [...enabledSkills, skillId],
|
||
disabledSkills: disabledSkills.filter(id => id !== skillId),
|
||
});
|
||
} else {
|
||
set({
|
||
enabledSkills: enabledSkills.filter(id => id !== skillId),
|
||
disabledSkills: [...disabledSkills, skillId],
|
||
});
|
||
}
|
||
},
|
||
|
||
toggleExtension: (extId, enabled) => {
|
||
const { enabledExtensions, disabledExtensions } = get();
|
||
if (enabled) {
|
||
set({
|
||
enabledExtensions: [...enabledExtensions, extId],
|
||
disabledExtensions: disabledExtensions.filter(id => id !== extId),
|
||
});
|
||
} else {
|
||
set({
|
||
enabledExtensions: enabledExtensions.filter(id => id !== extId),
|
||
disabledExtensions: [...disabledExtensions, extId],
|
||
});
|
||
}
|
||
},
|
||
|
||
// 计算实际生效的技能列表
|
||
getEffectiveSkills: () => {
|
||
const { selectedBundles, enabledSkills, disabledSkills } = get();
|
||
const { CLAWX_PRESETS } = require('../../electron/presets/defaults');
|
||
const { skillBundles } = require('../../resources/skills/bundles');
|
||
|
||
// 1. 核心技能 (始终包含)
|
||
const skills = new Set(CLAWX_PRESETS.coreSkills);
|
||
|
||
// 2. 默认技能
|
||
CLAWX_PRESETS.skills.forEach((id: string) => skills.add(id));
|
||
|
||
// 3. 选中的技能包
|
||
for (const bundleId of selectedBundles) {
|
||
const bundle = skillBundles.find((b: any) => b.id === bundleId);
|
||
bundle?.skills.forEach((id: string) => skills.add(id));
|
||
}
|
||
|
||
// 4. 用户额外启用的
|
||
enabledSkills.forEach(id => skills.add(id));
|
||
|
||
// 5. 移除用户禁用的 (但不能移除核心技能)
|
||
disabledSkills.forEach(id => {
|
||
if (!CLAWX_PRESETS.coreSkills.includes(id)) {
|
||
skills.delete(id);
|
||
}
|
||
});
|
||
|
||
return Array.from(skills);
|
||
},
|
||
|
||
getEffectiveExtensions: () => {
|
||
// 类似逻辑...
|
||
const { enabledExtensions, disabledExtensions } = get();
|
||
const { CLAWX_PRESETS } = require('../../electron/presets/defaults');
|
||
|
||
const extensions = new Set(CLAWX_PRESETS.coreExtensions);
|
||
CLAWX_PRESETS.extensions.forEach((id: string) => extensions.add(id));
|
||
enabledExtensions.forEach(id => extensions.add(id));
|
||
disabledExtensions.forEach(id => {
|
||
if (!CLAWX_PRESETS.coreExtensions.includes(id)) {
|
||
extensions.delete(id);
|
||
}
|
||
});
|
||
|
||
return Array.from(extensions);
|
||
},
|
||
}),
|
||
{
|
||
name: 'clawx-presets',
|
||
}
|
||
)
|
||
);
|
||
```
|
||
|
||
#### 2.5.4 安装向导集成
|
||
|
||
```typescript
|
||
// src/pages/Setup/SkillStep.tsx
|
||
|
||
import { usePresetStore } from '@/stores/presets';
|
||
import { skillBundles } from '@/resources/skills/bundles';
|
||
import { CLAWX_PRESETS } from '@electron/presets/defaults';
|
||
|
||
export function SkillStep({ onNext, onBack }: StepProps) {
|
||
const { selectedBundles, setSelectedBundles } = usePresetStore();
|
||
|
||
// 默认预选推荐的技能包
|
||
const [selected, setSelected] = useState<string[]>(
|
||
selectedBundles.length > 0
|
||
? selectedBundles
|
||
: CLAWX_PRESETS.defaultBundles
|
||
);
|
||
|
||
const handleToggle = (bundleId: string) => {
|
||
setSelected(prev =>
|
||
prev.includes(bundleId)
|
||
? prev.filter(id => id !== bundleId)
|
||
: [...prev, bundleId]
|
||
);
|
||
};
|
||
|
||
const handleNext = () => {
|
||
setSelectedBundles(selected);
|
||
onNext({ bundles: selected });
|
||
};
|
||
|
||
return (
|
||
<div className="space-y-6">
|
||
<div className="grid grid-cols-2 gap-4">
|
||
{skillBundles.map(bundle => (
|
||
<Card
|
||
key={bundle.id}
|
||
className={cn(
|
||
'cursor-pointer transition-all',
|
||
selected.includes(bundle.id) && 'ring-2 ring-primary'
|
||
)}
|
||
onClick={() => handleToggle(bundle.id)}
|
||
>
|
||
<CardHeader>
|
||
<div className="flex items-center gap-3">
|
||
<span className="text-3xl">{bundle.icon}</span>
|
||
<div>
|
||
<CardTitle className="text-lg">{bundle.nameZh}</CardTitle>
|
||
<CardDescription>{bundle.descriptionZh}</CardDescription>
|
||
</div>
|
||
</div>
|
||
</CardHeader>
|
||
<CardContent>
|
||
<div className="flex flex-wrap gap-1">
|
||
{bundle.skills.slice(0, 4).map(skill => (
|
||
<Badge key={skill} variant="secondary" className="text-xs">
|
||
{skill}
|
||
</Badge>
|
||
))}
|
||
{bundle.skills.length > 4 && (
|
||
<Badge variant="outline" className="text-xs">
|
||
+{bundle.skills.length - 4}
|
||
</Badge>
|
||
)}
|
||
</div>
|
||
</CardContent>
|
||
{bundle.recommended && (
|
||
<div className="absolute top-2 right-2">
|
||
<Badge>推荐</Badge>
|
||
</div>
|
||
)}
|
||
</Card>
|
||
))}
|
||
</div>
|
||
|
||
{/* 核心技能提示 */}
|
||
<Alert>
|
||
<Info className="h-4 w-4" />
|
||
<AlertDescription>
|
||
以下核心技能将始终启用：
|
||
{CLAWX_PRESETS.coreSkills.map(id => (
|
||
<Badge key={id} variant="outline" className="ml-1">{id}</Badge>
|
||
))}
|
||
</AlertDescription>
|
||
</Alert>
|
||
|
||
<div className="flex justify-between">
|
||
<Button variant="ghost" onClick={onBack}>上一步</Button>
|
||
<Button onClick={handleNext}>下一步</Button>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 2.5.5 预装层级与优先级
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ClawX 预装层级架构 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Layer 0: 核心层 (Core) - 不可禁用 │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Skills: coding-agent │ │
|
||
│ │ Extensions: memory-core │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ▲ │
|
||
│ │ 始终启用 │
|
||
│ │
|
||
│ Layer 1: 默认层 (Default) - 可禁用 │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Skills: canvas, summarize, weather, github, clawhub │ │
|
||
│ │ Extensions: lobster │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ▲ │
|
||
│ │ 首次安装自动启用 │
|
||
│ │
|
||
│ Layer 2: 技能包层 (Bundle) - 用户选择 │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ productivity: apple-reminders, notion, obsidian... │ │
|
||
│ │ developer: github, coding-agent, tmux... │ │
|
||
│ │ smart-home: openhue, sonoscli, spotify-player... │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ▲ │
|
||
│ │ 安装向导中选择 │
|
||
│ │
|
||
│ Layer 3: 用户层 (User) - 完全自定义 │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ 用户手动启用/禁用的技能和扩展 │ │
|
||
│ │ (通过设置页面或技能市场) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
优先级: Layer 3 > Layer 2 > Layer 1 > Layer 0 (不可覆盖)
|
||
```
|
||
|
||
#### 2.5.6 配置文件结构
|
||
|
||
```json5
|
||
// ~/.clawx/presets.json (用户本地配置)
|
||
{
|
||
"version": 1,
|
||
"initialized": true,
|
||
"initializedAt": "2026-02-05T12:00:00Z",
|
||
|
||
// 用户选择的技能包
|
||
"bundles": ["productivity", "developer"],
|
||
|
||
// 用户自定义覆盖
|
||
"overrides": {
|
||
"skills": {
|
||
"enabled": ["custom-skill-1"], // 额外启用
|
||
"disabled": ["weather"] // 禁用默认
|
||
},
|
||
"extensions": {
|
||
"enabled": ["custom-ext-1"],
|
||
"disabled": []
|
||
}
|
||
},
|
||
|
||
// 同步到 OpenClaw 的配置 (生成后写入 ~/.openclaw/config.json)
|
||
"syncedConfig": {
|
||
"skills": {
|
||
"enabled": ["coding-agent", "canvas", "github", "notion", "custom-skill-1"]
|
||
},
|
||
"plugins": {
|
||
"entries": {
|
||
"memory-core": { "enabled": true },
|
||
"lobster": { "enabled": true }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.6 跨平台自动更新系统
|
||
|
||
ClawX 需要实现**主动式**自动更新机制，在新版本发布后主动通知用户，同时支持用户手动检查更新。
|
||
|
||
#### 2.6.1 更新策略设计
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ClawX 自动更新流程 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 启动检查 │ │ 定时检查 │ │ 手动检查 │ │
|
||
│ │ (App Start) │ │ (每6小时) │ │ (用户触发) │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ └───────────────────┼───────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────┐ │
|
||
│ │ Version Checker │ │
|
||
│ │ 检查 GitHub/CDN │ │
|
||
│ └──────────┬──────────┘ │
|
||
│ │ │
|
||
│ ┌──────────────┴──────────────┐ │
|
||
│ ▼ ▼ │
|
||
│ ┌────────────────┐ ┌────────────────┐ │
|
||
│ │ 无新版本 │ │ 有新版本 │ │
|
||
│ │ 静默结束 │ │ │ │
|
||
│ └────────────────┘ └───────┬────────┘ │
|
||
│ │ │
|
||
│ ┌───────────┴───────────┐ │
|
||
│ ▼ ▼ │
|
||
│ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 主动通知弹窗 │ │ 静默下载 │ │
|
||
│ │ (询问用户) │ │ (后台进行) │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │
|
||
│ ┌────────────┴────────────┐ │ │
|
||
│ ▼ ▼ │ │
|
||
│ ┌────────────────┐ ┌────────────────┐ │ │
|
||
│ │ 立即更新 │ │ 稍后提醒 │ │ │
|
||
│ │ (下载安装) │ │ (记录时间) │ │ │
|
||
│ └───────┬────────┘ └────────────────┘ │ │
|
||
│ │ │ │
|
||
│ └────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────┐ │
|
||
│ │ 下载完成通知 │ │
|
||
│ │ "重启以完成更新" │ │
|
||
│ └─────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 2.6.2 更新管理器实现
|
||
|
||
```typescript
|
||
// electron/updater/index.ts
|
||
|
||
import { autoUpdater, UpdateInfo } from 'electron-updater';
|
||
import { app, BrowserWindow, dialog, Notification } from 'electron';
|
||
import { EventEmitter } from 'events';
|
||
import log from 'electron-log';
|
||
|
||
export interface UpdateConfig {
|
||
/** 更新通道: stable | beta | dev */
|
||
channel: 'stable' | 'beta' | 'dev';
|
||
|
||
/** 是否自动下载 */
|
||
autoDownload: boolean;
|
||
|
||
/** 是否允许降级 */
|
||
allowDowngrade: boolean;
|
||
|
||
/** 检查间隔 (毫秒) */
|
||
checkInterval: number;
|
||
|
||
/** 是否显示主动通知 */
|
||
showNotification: boolean;
|
||
}
|
||
|
||
export interface UpdateStatus {
|
||
state: 'idle' | 'checking' | 'available' | 'downloading' | 'downloaded' | 'error';
|
||
currentVersion: string;
|
||
latestVersion?: string;
|
||
releaseNotes?: string;
|
||
downloadProgress?: number;
|
||
error?: string;
|
||
}
|
||
|
||
const DEFAULT_CONFIG: UpdateConfig = {
|
||
channel: 'stable',
|
||
autoDownload: false, // 默认不自动下载，先询问用户
|
||
allowDowngrade: false,
|
||
checkInterval: 6 * 60 * 60 * 1000, // 6小时
|
||
showNotification: true,
|
||
};
|
||
|
||
export class UpdateManager extends EventEmitter {
|
||
private config: UpdateConfig;
|
||
private status: UpdateStatus;
|
||
private checkTimer: NodeJS.Timeout | null = null;
|
||
private mainWindow: BrowserWindow | null = null;
|
||
|
||
constructor(config: Partial<UpdateConfig> = {}) {
|
||
super();
|
||
this.config = { ...DEFAULT_CONFIG, ...config };
|
||
this.status = {
|
||
state: 'idle',
|
||
currentVersion: app.getVersion(),
|
||
};
|
||
|
||
this.setupAutoUpdater();
|
||
}
|
||
|
||
private setupAutoUpdater(): void {
|
||
// 配置 electron-updater
|
||
autoUpdater.logger = log;
|
||
autoUpdater.autoDownload = this.config.autoDownload;
|
||
autoUpdater.allowDowngrade = this.config.allowDowngrade;
|
||
|
||
// 设置更新通道
|
||
autoUpdater.channel = this.config.channel;
|
||
|
||
// GitHub Releases 作为更新源
|
||
autoUpdater.setFeedURL({
|
||
provider: 'github',
|
||
owner: 'clawx',
|
||
repo: 'clawx',
|
||
});
|
||
|
||
// 事件监听
|
||
autoUpdater.on('checking-for-update', () => {
|
||
this.setStatus({ state: 'checking' });
|
||
});
|
||
|
||
autoUpdater.on('update-available', (info: UpdateInfo) => {
|
||
this.setStatus({
|
||
state: 'available',
|
||
latestVersion: info.version,
|
||
releaseNotes: this.formatReleaseNotes(info.releaseNotes),
|
||
});
|
||
|
||
// 主动通知用户
|
||
if (this.config.showNotification) {
|
||
this.showUpdateNotification(info);
|
||
}
|
||
});
|
||
|
||
autoUpdater.on('update-not-available', () => {
|
||
this.setStatus({ state: 'idle' });
|
||
});
|
||
|
||
autoUpdater.on('download-progress', (progress) => {
|
||
this.setStatus({
|
||
state: 'downloading',
|
||
downloadProgress: Math.round(progress.percent),
|
||
});
|
||
});
|
||
|
||
autoUpdater.on('update-downloaded', (info: UpdateInfo) => {
|
||
this.setStatus({ state: 'downloaded' });
|
||
this.showDownloadedNotification(info);
|
||
});
|
||
|
||
autoUpdater.on('error', (error) => {
|
||
this.setStatus({ state: 'error', error: error.message });
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 初始化更新器 (应用启动时调用)
|
||
*/
|
||
initialize(mainWindow: BrowserWindow): void {
|
||
this.mainWindow = mainWindow;
|
||
|
||
// 启动时检查更新 (延迟5秒，避免影响启动速度)
|
||
setTimeout(() => this.checkForUpdates(true), 5000);
|
||
|
||
// 定时检查
|
||
this.startPeriodicCheck();
|
||
}
|
||
|
||
/**
|
||
* 启动定时检查
|
||
*/
|
||
private startPeriodicCheck(): void {
|
||
if (this.checkTimer) {
|
||
clearInterval(this.checkTimer);
|
||
}
|
||
|
||
this.checkTimer = setInterval(() => {
|
||
this.checkForUpdates(true);
|
||
}, this.config.checkInterval);
|
||
}
|
||
|
||
/**
|
||
* 检查更新
|
||
* @param silent 是否静默 (不显示"已是最新版本"提示)
|
||
*/
|
||
async checkForUpdates(silent: boolean = false): Promise<void> {
|
||
try {
|
||
const result = await autoUpdater.checkForUpdates();
|
||
|
||
if (!result?.updateInfo && !silent) {
|
||
// 手动检查且无更新时，显示提示
|
||
this.showNoUpdateDialog();
|
||
}
|
||
} catch (error) {
|
||
if (!silent) {
|
||
this.showErrorDialog(error as Error);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 下载更新
|
||
*/
|
||
async downloadUpdate(): Promise<void> {
|
||
if (this.status.state !== 'available') return;
|
||
await autoUpdater.downloadUpdate();
|
||
}
|
||
|
||
/**
|
||
* 安装更新并重启
|
||
*/
|
||
quitAndInstall(): void {
|
||
autoUpdater.quitAndInstall(false, true);
|
||
}
|
||
|
||
/**
|
||
* 显示更新可用通知
|
||
*/
|
||
private showUpdateNotification(info: UpdateInfo): void {
|
||
// 系统通知
|
||
if (Notification.isSupported()) {
|
||
const notification = new Notification({
|
||
title: 'ClawX 有新版本可用',
|
||
body: `版本 ${info.version} 已发布，点击查看详情`,
|
||
icon: app.isPackaged
|
||
? undefined
|
||
: 'resources/icons/icon.png',
|
||
});
|
||
|
||
notification.on('click', () => {
|
||
this.showUpdateDialog(info);
|
||
});
|
||
|
||
notification.show();
|
||
}
|
||
|
||
// 同时发送到渲染进程
|
||
this.mainWindow?.webContents.send('update:available', {
|
||
version: info.version,
|
||
releaseNotes: this.formatReleaseNotes(info.releaseNotes),
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 显示更新对话框 (主动询问用户)
|
||
*/
|
||
private async showUpdateDialog(info: UpdateInfo): Promise<void> {
|
||
const releaseNotes = this.formatReleaseNotes(info.releaseNotes);
|
||
|
||
const result = await dialog.showMessageBox(this.mainWindow!, {
|
||
type: 'info',
|
||
title: '发现新版本',
|
||
message: `ClawX ${info.version} 已发布`,
|
||
detail: `当前版本: ${this.status.currentVersion}\n\n更新内容:\n${releaseNotes}`,
|
||
buttons: ['立即更新', '稍后提醒', '跳过此版本'],
|
||
defaultId: 0,
|
||
cancelId: 1,
|
||
});
|
||
|
||
switch (result.response) {
|
||
case 0: // 立即更新
|
||
this.downloadUpdate();
|
||
break;
|
||
case 1: // 稍后提醒
|
||
// 30分钟后再次提醒
|
||
setTimeout(() => this.showUpdateNotification(info), 30 * 60 * 1000);
|
||
break;
|
||
case 2: // 跳过此版本
|
||
this.skipVersion(info.version);
|
||
break;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 显示下载完成通知
|
||
*/
|
||
private showDownloadedNotification(info: UpdateInfo): void {
|
||
if (Notification.isSupported()) {
|
||
const notification = new Notification({
|
||
title: '更新已就绪',
|
||
body: `ClawX ${info.version} 已下载完成，点击重启应用以完成更新`,
|
||
});
|
||
|
||
notification.on('click', () => {
|
||
this.showRestartDialog();
|
||
});
|
||
|
||
notification.show();
|
||
}
|
||
|
||
this.mainWindow?.webContents.send('update:downloaded', {
|
||
version: info.version,
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 显示重启对话框
|
||
*/
|
||
private async showRestartDialog(): Promise<void> {
|
||
const result = await dialog.showMessageBox(this.mainWindow!, {
|
||
type: 'info',
|
||
title: '更新已就绪',
|
||
message: '重启应用以完成更新',
|
||
detail: '更新已下载完成，是否立即重启应用？',
|
||
buttons: ['立即重启', '稍后'],
|
||
defaultId: 0,
|
||
});
|
||
|
||
if (result.response === 0) {
|
||
this.quitAndInstall();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 显示无更新对话框 (手动检查时)
|
||
*/
|
||
private showNoUpdateDialog(): void {
|
||
dialog.showMessageBox(this.mainWindow!, {
|
||
type: 'info',
|
||
title: '检查更新',
|
||
message: '已是最新版本',
|
||
detail: `当前版本 ${this.status.currentVersion} 已是最新`,
|
||
buttons: ['确定'],
|
||
});
|
||
}
|
||
|
||
private showErrorDialog(error: Error): void {
|
||
dialog.showMessageBox(this.mainWindow!, {
|
||
type: 'error',
|
||
title: '更新检查失败',
|
||
message: '无法检查更新',
|
||
detail: error.message,
|
||
buttons: ['确定'],
|
||
});
|
||
}
|
||
|
||
private formatReleaseNotes(notes: string | any): string {
|
||
if (typeof notes === 'string') return notes;
|
||
if (Array.isArray(notes)) {
|
||
return notes.map(n => n.note || n).join('\n');
|
||
}
|
||
return '';
|
||
}
|
||
|
||
private skipVersion(version: string): void {
|
||
// 存储跳过的版本
|
||
const store = require('electron-store');
|
||
const settings = new store();
|
||
const skipped = settings.get('update.skippedVersions', []) as string[];
|
||
if (!skipped.includes(version)) {
|
||
settings.set('update.skippedVersions', [...skipped, version]);
|
||
}
|
||
}
|
||
|
||
private setStatus(update: Partial<UpdateStatus>): void {
|
||
this.status = { ...this.status, ...update };
|
||
this.emit('status', this.status);
|
||
this.mainWindow?.webContents.send('update:status', this.status);
|
||
}
|
||
|
||
getStatus(): UpdateStatus {
|
||
return this.status;
|
||
}
|
||
|
||
setConfig(config: Partial<UpdateConfig>): void {
|
||
this.config = { ...this.config, ...config };
|
||
autoUpdater.channel = this.config.channel;
|
||
autoUpdater.autoDownload = this.config.autoDownload;
|
||
|
||
// 重启定时检查
|
||
this.startPeriodicCheck();
|
||
}
|
||
}
|
||
|
||
// 导出单例
|
||
export const updateManager = new UpdateManager();
|
||
```
|
||
|
||
#### 2.6.3 渲染进程更新 UI
|
||
|
||
```typescript
|
||
// src/hooks/useUpdate.ts
|
||
|
||
import { useState, useEffect } from 'react';
|
||
|
||
interface UpdateStatus {
|
||
state: 'idle' | 'checking' | 'available' | 'downloading' | 'downloaded' | 'error';
|
||
currentVersion: string;
|
||
latestVersion?: string;
|
||
releaseNotes?: string;
|
||
downloadProgress?: number;
|
||
error?: string;
|
||
}
|
||
|
||
export function useUpdate() {
|
||
const [status, setStatus] = useState<UpdateStatus>({
|
||
state: 'idle',
|
||
currentVersion: '0.0.0',
|
||
});
|
||
|
||
useEffect(() => {
|
||
// 监听主进程更新状态
|
||
const handleStatus = (_: any, newStatus: UpdateStatus) => {
|
||
setStatus(newStatus);
|
||
};
|
||
|
||
window.electron.ipcRenderer.on('update:status', handleStatus);
|
||
|
||
// 获取初始状态
|
||
window.electron.ipcRenderer.invoke('update:getStatus').then(setStatus);
|
||
|
||
return () => {
|
||
window.electron.ipcRenderer.off('update:status', handleStatus);
|
||
};
|
||
}, []);
|
||
|
||
const checkForUpdates = () => {
|
||
window.electron.ipcRenderer.invoke('update:check');
|
||
};
|
||
|
||
const downloadUpdate = () => {
|
||
window.electron.ipcRenderer.invoke('update:download');
|
||
};
|
||
|
||
const installUpdate = () => {
|
||
window.electron.ipcRenderer.invoke('update:install');
|
||
};
|
||
|
||
return {
|
||
status,
|
||
checkForUpdates,
|
||
downloadUpdate,
|
||
installUpdate,
|
||
};
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/components/UpdateNotification.tsx
|
||
|
||
import { useUpdate } from '@/hooks/useUpdate';
|
||
import { motion, AnimatePresence } from 'framer-motion';
|
||
import { Download, RefreshCw, X, Loader2 } from 'lucide-react';
|
||
|
||
export function UpdateNotification() {
|
||
const { status, downloadUpdate, installUpdate } = useUpdate();
|
||
const [dismissed, setDismissed] = useState(false);
|
||
|
||
// 只在有更新可用或已下载时显示
|
||
const shouldShow =
|
||
!dismissed &&
|
||
(status.state === 'available' || status.state === 'downloaded');
|
||
|
||
return (
|
||
<AnimatePresence>
|
||
{shouldShow && (
|
||
<motion.div
|
||
initial={{ opacity: 0, y: -20 }}
|
||
animate={{ opacity: 1, y: 0 }}
|
||
exit={{ opacity: 0, y: -20 }}
|
||
className="fixed top-4 right-4 z-50 max-w-sm"
|
||
>
|
||
<Card className="border-primary/50 shadow-lg">
|
||
<CardHeader className="pb-2">
|
||
<div className="flex items-center justify-between">
|
||
<CardTitle className="text-sm font-medium flex items-center gap-2">
|
||
{status.state === 'available' ? (
|
||
<>
|
||
<Download className="w-4 h-4 text-primary" />
|
||
新版本可用
|
||
</>
|
||
) : (
|
||
<>
|
||
<RefreshCw className="w-4 h-4 text-green-500" />
|
||
更新已就绪
|
||
</>
|
||
)}
|
||
</CardTitle>
|
||
<Button
|
||
variant="ghost"
|
||
size="icon"
|
||
className="h-6 w-6"
|
||
onClick={() => setDismissed(true)}
|
||
>
|
||
<X className="w-4 h-4" />
|
||
</Button>
|
||
</div>
|
||
</CardHeader>
|
||
<CardContent className="pt-0">
|
||
<p className="text-sm text-muted-foreground mb-3">
|
||
ClawX {status.latestVersion} 已发布
|
||
</p>
|
||
|
||
{status.state === 'downloading' && (
|
||
<div className="mb-3">
|
||
<Progress value={status.downloadProgress} className="h-2" />
|
||
<p className="text-xs text-muted-foreground mt-1">
|
||
下载中 {status.downloadProgress}%
|
||
</p>
|
||
</div>
|
||
)}
|
||
|
||
<div className="flex gap-2">
|
||
{status.state === 'available' && (
|
||
<Button size="sm" onClick={downloadUpdate}>
|
||
立即下载
|
||
</Button>
|
||
)}
|
||
{status.state === 'downloaded' && (
|
||
<Button size="sm" onClick={installUpdate}>
|
||
重启更新
|
||
</Button>
|
||
)}
|
||
<Button
|
||
variant="ghost"
|
||
size="sm"
|
||
onClick={() => setDismissed(true)}
|
||
>
|
||
稍后
|
||
</Button>
|
||
</div>
|
||
</CardContent>
|
||
</Card>
|
||
</motion.div>
|
||
)}
|
||
</AnimatePresence>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 2.6.4 设置页面手动检查入口
|
||
|
||
```typescript
|
||
// src/pages/Settings/GeneralSettings.tsx
|
||
|
||
import { useUpdate } from '@/hooks/useUpdate';
|
||
|
||
export function GeneralSettings() {
|
||
const { status, checkForUpdates } = useUpdate();
|
||
|
||
return (
|
||
<Card>
|
||
<CardHeader>
|
||
<CardTitle>通用设置</CardTitle>
|
||
</CardHeader>
|
||
<CardContent className="space-y-6">
|
||
{/* 版本与更新 */}
|
||
<div className="space-y-4">
|
||
<Label className="text-sm font-medium">版本与更新</Label>
|
||
|
||
<div className="flex items-center justify-between p-4 rounded-lg border">
|
||
<div>
|
||
<p className="font-medium">ClawX</p>
|
||
<p className="text-sm text-muted-foreground">
|
||
当前版本: {status.currentVersion}
|
||
</p>
|
||
{status.latestVersion && status.state === 'available' && (
|
||
<p className="text-sm text-primary">
|
||
新版本可用: {status.latestVersion}
|
||
</p>
|
||
)}
|
||
</div>
|
||
<Button
|
||
variant="outline"
|
||
onClick={checkForUpdates}
|
||
disabled={status.state === 'checking'}
|
||
>
|
||
{status.state === 'checking' ? (
|
||
<>
|
||
<Loader2 className="w-4 h-4 mr-2 animate-spin" />
|
||
检查中...
|
||
</>
|
||
) : (
|
||
'检查更新'
|
||
)}
|
||
</Button>
|
||
</div>
|
||
|
||
{/* 更新设置 */}
|
||
<div className="space-y-3 pt-2">
|
||
<div className="flex items-center justify-between">
|
||
<div>
|
||
<p className="text-sm font-medium">自动检查更新</p>
|
||
<p className="text-xs text-muted-foreground">
|
||
启动时和每6小时自动检查
|
||
</p>
|
||
</div>
|
||
<Switch defaultChecked />
|
||
</div>
|
||
|
||
<div className="flex items-center justify-between">
|
||
<div>
|
||
<p className="text-sm font-medium">自动下载更新</p>
|
||
<p className="text-xs text-muted-foreground">
|
||
发现新版本后在后台自动下载
|
||
</p>
|
||
</div>
|
||
<Switch />
|
||
</div>
|
||
|
||
<div className="flex items-center justify-between">
|
||
<div>
|
||
<p className="text-sm font-medium">更新通道</p>
|
||
<p className="text-xs text-muted-foreground">
|
||
选择接收更新的类型
|
||
</p>
|
||
</div>
|
||
<Select defaultValue="stable">
|
||
<SelectTrigger className="w-32">
|
||
<SelectValue />
|
||
</SelectTrigger>
|
||
<SelectContent>
|
||
<SelectItem value="stable">稳定版</SelectItem>
|
||
<SelectItem value="beta">测试版</SelectItem>
|
||
</SelectContent>
|
||
</Select>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<Separator />
|
||
|
||
{/* 其他设置... */}
|
||
</CardContent>
|
||
</Card>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 2.6.5 跨平台配置
|
||
|
||
```typescript
|
||
// electron/updater/channels.ts
|
||
|
||
import { Platform } from 'electron-builder';
|
||
|
||
export interface PlatformUpdateConfig {
|
||
/** 更新源 URL */
|
||
feedUrl: string;
|
||
|
||
/** 是否支持差量更新 */
|
||
supportsDelta: boolean;
|
||
|
||
/** 安装方式 */
|
||
installMethod: 'nsis' | 'dmg' | 'appimage' | 'deb' | 'rpm';
|
||
}
|
||
|
||
export const PLATFORM_CONFIGS: Record<NodeJS.Platform, PlatformUpdateConfig> = {
|
||
darwin: {
|
||
feedUrl: 'https://releases.clawx.app/mac',
|
||
supportsDelta: true, // macOS 支持 Sparkle 差量更新
|
||
installMethod: 'dmg',
|
||
},
|
||
win32: {
|
||
feedUrl: 'https://releases.clawx.app/win',
|
||
supportsDelta: true, // Windows NSIS 支持差量
|
||
installMethod: 'nsis',
|
||
},
|
||
linux: {
|
||
feedUrl: 'https://releases.clawx.app/linux',
|
||
supportsDelta: false, // AppImage 不支持差量
|
||
installMethod: 'appimage',
|
||
},
|
||
} as Record<NodeJS.Platform, PlatformUpdateConfig>;
|
||
|
||
// electron-builder.yml 配置示例
|
||
export const ELECTRON_BUILDER_CONFIG = `
|
||
appId: app.clawx.desktop
|
||
productName: ClawX
|
||
copyright: Copyright © 2026 ClawX
|
||
|
||
publish:
|
||
- provider: github
|
||
owner: clawx
|
||
repo: clawx
|
||
releaseType: release
|
||
|
||
mac:
|
||
category: public.app-category.productivity
|
||
target:
|
||
- target: dmg
|
||
arch: [universal]
|
||
- target: zip
|
||
arch: [universal]
|
||
notarize:
|
||
teamId: \${env.APPLE_TEAM_ID}
|
||
|
||
win:
|
||
target:
|
||
- target: nsis
|
||
arch: [x64, arm64]
|
||
publisherName: ClawX Inc.
|
||
|
||
nsis:
|
||
oneClick: false
|
||
allowToChangeInstallationDirectory: true
|
||
differentialPackage: true # 启用差量更新
|
||
|
||
linux:
|
||
target:
|
||
- target: AppImage
|
||
arch: [x64, arm64]
|
||
- target: deb
|
||
arch: [x64]
|
||
category: Utility
|
||
`;
|
||
```
|
||
|
||
#### 2.6.6 更新时间线与用户交互
|
||
|
||
```
|
||
用户视角的更新流程:
|
||
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 场景 A: 有新版本时主动通知 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. 用户正在使用 ClawX │
|
||
│ │ │
|
||
│ 2. 系统检测到新版本 (启动时/定时检查) │
|
||
│ │ │
|
||
│ 3. 右上角弹出通知卡片 ────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ ┌─────────────────────────────┐ │ │
|
||
│ │ │ 🔔 新版本可用 │ │ │
|
||
│ │ │ ClawX 1.2.0 已发布 │ │ │
|
||
│ │ │ [立即下载] [稍后] │ │ │
|
||
│ │ └─────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ 4. 用户点击"立即下载" │
|
||
│ │ │
|
||
│ 5. 后台下载，通知卡片显示进度 │
|
||
│ │ │
|
||
│ 6. 下载完成，通知"重启以完成更新" │
|
||
│ │ │
|
||
│ 7. 用户选择"立即重启"或继续工作后重启 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 场景 B: 用户手动检查更新 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. 用户打开 设置 → 通用 → 检查更新 │
|
||
│ │ │
|
||
│ 2. 显示"检查中..." │
|
||
│ │ │
|
||
│ 3a. 无更新 → 弹窗提示"已是最新版本 (1.1.0)" │
|
||
│ │ │
|
||
│ 3b. 有更新 → 弹窗显示更新详情 │
|
||
│ │ │
|
||
│ │ ┌─────────────────────────────────────┐ │
|
||
│ │ │ 发现新版本 │ │
|
||
│ │ │ │ │
|
||
│ │ │ ClawX 1.2.0 已发布 │ │
|
||
│ │ │ 当前版本: 1.1.0 │ │
|
||
│ │ │ │ │
|
||
│ │ │ 更新内容: │ │
|
||
│ │ │ • 新增技能市场 │ │
|
||
│ │ │ • 修复 Windows 启动问题 │ │
|
||
│ │ │ • 性能优化 │ │
|
||
│ │ │ │ │
|
||
│ │ │ [立即更新] [稍后提醒] [跳过此版本] │ │
|
||
│ │ └─────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.7 GUI 权限提升机制
|
||
|
||
ClawX 需要在某些操作时获取管理员权限（如全局安装 Node.js、修改系统 PATH），必须通过**图形化密码弹窗**而非命令行 `sudo`。
|
||
|
||
#### 2.7.1 需要管理员权限的场景
|
||
|
||
| 场景 | 操作 | 原因 |
|
||
|------|------|------|
|
||
| Node.js 安装 | 写入 `/usr/local/bin` (macOS/Linux) | 系统目录需要 root |
|
||
| 全局 npm 安装 | `npm install -g openclaw` | 系统 node_modules |
|
||
| PATH 配置 | 修改 `/etc/paths.d/` | 系统级环境变量 |
|
||
| 端口 < 1024 | Gateway 使用低端口 | 特权端口 |
|
||
| 系统服务注册 | LaunchDaemon / systemd | 开机自启 |
|
||
|
||
#### 2.7.2 跨平台权限提升架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ClawX 权限提升流程 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ 需要管理员权限 │ │
|
||
│ │ 的操作触发 │ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ │
|
||
│ │ PrivilegeManager │ │
|
||
│ │ 检测当前平台 │ │
|
||
│ └────────┬─────────┘ │
|
||
│ │ │
|
||
│ ┌─────┴─────┬─────────────┐ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────┐ ┌──────┐ ┌──────┐ │
|
||
│ │macOS │ │Windows│ │Linux │ │
|
||
│ └──┬───┘ └──┬───┘ └──┬───┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||
│ │osascript│ │ UAC │ │pkexec │ │
|
||
│ │密码弹窗 │ │提升弹窗│ │密码弹窗│ │
|
||
│ └────────┘ └────────┘ └────────┘ │
|
||
│ │ │ │ │
|
||
│ └──────────┴───────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────┐ │
|
||
│ │ 以管理员身份执行命令 │ │
|
||
│ │ (无需终端 sudo 输入) │ │
|
||
│ └──────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 2.7.3 权限管理器实现
|
||
|
||
```typescript
|
||
// electron/privilege/index.ts
|
||
|
||
import { dialog } from 'electron';
|
||
import { platform } from 'os';
|
||
import { DarwinAdmin } from './darwin-admin';
|
||
import { Win32Admin } from './win32-admin';
|
||
import { LinuxAdmin } from './linux-admin';
|
||
|
||
export interface PrivilegeResult {
|
||
success: boolean;
|
||
stdout?: string;
|
||
stderr?: string;
|
||
error?: string;
|
||
}
|
||
|
||
export interface PrivilegeOptions {
|
||
/** 向用户展示的操作说明 */
|
||
reason: string;
|
||
|
||
/** 图标路径 */
|
||
icon?: string;
|
||
|
||
/** 超时时间 (毫秒) */
|
||
timeout?: number;
|
||
}
|
||
|
||
/**
|
||
* 跨平台权限提升管理器
|
||
* 通过 GUI 弹窗获取管理员权限，而非命令行 sudo
|
||
*/
|
||
export class PrivilegeManager {
|
||
private admin: DarwinAdmin | Win32Admin | LinuxAdmin;
|
||
|
||
constructor() {
|
||
switch (platform()) {
|
||
case 'darwin':
|
||
this.admin = new DarwinAdmin();
|
||
break;
|
||
case 'win32':
|
||
this.admin = new Win32Admin();
|
||
break;
|
||
case 'linux':
|
||
this.admin = new LinuxAdmin();
|
||
break;
|
||
default:
|
||
throw new Error(`Unsupported platform: ${platform()}`);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 检查是否已有管理员权限
|
||
*/
|
||
async hasAdminPrivilege(): Promise<boolean> {
|
||
return this.admin.hasAdminPrivilege();
|
||
}
|
||
|
||
/**
|
||
* 以管理员权限执行命令 (会弹出密码框)
|
||
*/
|
||
async execAsAdmin(
|
||
command: string,
|
||
options: PrivilegeOptions
|
||
): Promise<PrivilegeResult> {
|
||
// 先检查是否真的需要提权
|
||
if (await this.hasAdminPrivilege()) {
|
||
// 已经是 admin，直接执行
|
||
return this.admin.exec(command);
|
||
}
|
||
|
||
// 显示确认对话框
|
||
const confirmed = await this.showConfirmDialog(options.reason);
|
||
if (!confirmed) {
|
||
return { success: false, error: 'User cancelled' };
|
||
}
|
||
|
||
// 通过平台特定方式获取权限并执行
|
||
return this.admin.execWithPrivilege(command, options);
|
||
}
|
||
|
||
/**
|
||
* 显示权限请求确认对话框
|
||
*/
|
||
private async showConfirmDialog(reason: string): Promise<boolean> {
|
||
const result = await dialog.showMessageBox({
|
||
type: 'warning',
|
||
title: '需要管理员权限',
|
||
message: 'ClawX 需要管理员权限来完成此操作',
|
||
detail: `${reason}\n\n点击"继续"后将弹出系统密码输入框。`,
|
||
buttons: ['继续', '取消'],
|
||
defaultId: 0,
|
||
cancelId: 1,
|
||
});
|
||
|
||
return result.response === 0;
|
||
}
|
||
}
|
||
|
||
export const privilegeManager = new PrivilegeManager();
|
||
```
|
||
|
||
#### 2.7.4 macOS 实现 (osascript)
|
||
|
||
```typescript
|
||
// electron/privilege/darwin-admin.ts
|
||
|
||
import { exec } from 'child_process';
|
||
import { promisify } from 'util';
|
||
|
||
const execAsync = promisify(exec);
|
||
|
||
export class DarwinAdmin {
|
||
/**
|
||
* 检查是否以 root 运行
|
||
*/
|
||
async hasAdminPrivilege(): Promise<boolean> {
|
||
try {
|
||
await execAsync('test -w /usr/local/bin');
|
||
return true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 直接执行命令
|
||
*/
|
||
async exec(command: string): Promise<PrivilegeResult> {
|
||
try {
|
||
const { stdout, stderr } = await execAsync(command);
|
||
return { success: true, stdout, stderr };
|
||
} catch (error: any) {
|
||
return { success: false, error: error.message };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 通过 osascript 弹出系统密码框执行命令
|
||
* 这会显示 macOS 原生的授权对话框
|
||
*/
|
||
async execWithPrivilege(
|
||
command: string,
|
||
options: PrivilegeOptions
|
||
): Promise<PrivilegeResult> {
|
||
// 使用 osascript 调用 Authorization Services
|
||
// 这会弹出 macOS 原生密码输入框
|
||
const escapedCommand = command.replace(/"/g, '\\"');
|
||
const escapedReason = options.reason.replace(/"/g, '\\"');
|
||
|
||
const appleScript = `
|
||
do shell script "${escapedCommand}" \\
|
||
with administrator privileges \\
|
||
with prompt "${escapedReason}"
|
||
`;
|
||
|
||
try {
|
||
const { stdout, stderr } = await execAsync(
|
||
`osascript -e '${appleScript.replace(/'/g, "'\"'\"'")}'`,
|
||
{ timeout: options.timeout || 60000 }
|
||
);
|
||
return { success: true, stdout, stderr };
|
||
} catch (error: any) {
|
||
// 用户取消会抛出错误
|
||
if (error.message.includes('User canceled')) {
|
||
return { success: false, error: 'User cancelled' };
|
||
}
|
||
return { success: false, error: error.message };
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.7.5 Windows 实现 (UAC)
|
||
|
||
```typescript
|
||
// electron/privilege/win32-admin.ts
|
||
|
||
import { exec, spawn } from 'child_process';
|
||
import { promisify } from 'util';
|
||
import { writeFileSync, unlinkSync } from 'fs';
|
||
import { tmpdir } from 'os';
|
||
import { join } from 'path';
|
||
|
||
const execAsync = promisify(exec);
|
||
|
||
export class Win32Admin {
|
||
/**
|
||
* 检查是否以管理员运行
|
||
*/
|
||
async hasAdminPrivilege(): Promise<boolean> {
|
||
try {
|
||
// 尝试写入 System32，如果成功说明有管理员权限
|
||
await execAsync('fsutil dirty query %systemdrive%');
|
||
return true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
async exec(command: string): Promise<PrivilegeResult> {
|
||
try {
|
||
const { stdout, stderr } = await execAsync(command, { shell: 'powershell.exe' });
|
||
return { success: true, stdout, stderr };
|
||
} catch (error: any) {
|
||
return { success: false, error: error.message };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 通过 UAC 提升权限执行命令
|
||
* 这会弹出 Windows UAC 确认对话框
|
||
*/
|
||
async execWithPrivilege(
|
||
command: string,
|
||
options: PrivilegeOptions
|
||
): Promise<PrivilegeResult> {
|
||
return new Promise((resolve) => {
|
||
// 创建临时 PowerShell 脚本
|
||
const scriptPath = join(tmpdir(), `clawx-admin-${Date.now()}.ps1`);
|
||
const outputPath = join(tmpdir(), `clawx-admin-${Date.now()}.txt`);
|
||
|
||
// PowerShell 脚本内容
|
||
const script = `
|
||
try {
|
||
${command}
|
||
"SUCCESS" | Out-File -FilePath "${outputPath}"
|
||
} catch {
|
||
$_.Exception.Message | Out-File -FilePath "${outputPath}"
|
||
exit 1
|
||
}
|
||
`;
|
||
|
||
writeFileSync(scriptPath, script, 'utf-8');
|
||
|
||
// 使用 PowerShell 的 Start-Process 触发 UAC
|
||
const elevateCommand = `
|
||
Start-Process powershell.exe \
|
||
-ArgumentList '-ExecutionPolicy Bypass -File "${scriptPath}"' \
|
||
-Verb RunAs \
|
||
-Wait
|
||
`;
|
||
|
||
const child = spawn('powershell.exe', ['-Command', elevateCommand], {
|
||
stdio: 'pipe',
|
||
});
|
||
|
||
child.on('close', (code) => {
|
||
try {
|
||
const output = require('fs').readFileSync(outputPath, 'utf-8').trim();
|
||
unlinkSync(scriptPath);
|
||
unlinkSync(outputPath);
|
||
|
||
if (output === 'SUCCESS') {
|
||
resolve({ success: true });
|
||
} else {
|
||
resolve({ success: false, error: output });
|
||
}
|
||
} catch (error: any) {
|
||
resolve({ success: false, error: 'UAC cancelled or failed' });
|
||
}
|
||
});
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.7.6 Linux 实现 (pkexec/polkit)
|
||
|
||
```typescript
|
||
// electron/privilege/linux-admin.ts
|
||
|
||
import { exec, spawn } from 'child_process';
|
||
import { promisify } from 'util';
|
||
|
||
const execAsync = promisify(exec);
|
||
|
||
export class LinuxAdmin {
|
||
async hasAdminPrivilege(): Promise<boolean> {
|
||
return process.getuid?.() === 0;
|
||
}
|
||
|
||
async exec(command: string): Promise<PrivilegeResult> {
|
||
try {
|
||
const { stdout, stderr } = await execAsync(command);
|
||
return { success: true, stdout, stderr };
|
||
} catch (error: any) {
|
||
return { success: false, error: error.message };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 通过 pkexec 弹出图形化密码框
|
||
* pkexec 是 polkit 的一部分，大多数 Linux 桌面都支持
|
||
*/
|
||
async execWithPrivilege(
|
||
command: string,
|
||
options: PrivilegeOptions
|
||
): Promise<PrivilegeResult> {
|
||
return new Promise((resolve) => {
|
||
// 检查 pkexec 是否可用
|
||
exec('which pkexec', (error) => {
|
||
if (error) {
|
||
// 回退到 gksudo 或 kdesudo
|
||
this.execWithFallback(command, options).then(resolve);
|
||
return;
|
||
}
|
||
|
||
// 使用 pkexec (会弹出 polkit 密码框)
|
||
const child = spawn('pkexec', ['bash', '-c', command], {
|
||
stdio: ['ignore', 'pipe', 'pipe'],
|
||
env: {
|
||
...process.env,
|
||
// 设置 polkit 显示的描述
|
||
POLKIT_AGENT_HELPER_NAME: 'ClawX',
|
||
},
|
||
});
|
||
|
||
let stdout = '';
|
||
let stderr = '';
|
||
|
||
child.stdout.on('data', (data) => { stdout += data; });
|
||
child.stderr.on('data', (data) => { stderr += data; });
|
||
|
||
child.on('close', (code) => {
|
||
if (code === 0) {
|
||
resolve({ success: true, stdout, stderr });
|
||
} else if (code === 126) {
|
||
// 用户取消
|
||
resolve({ success: false, error: 'User cancelled' });
|
||
} else {
|
||
resolve({ success: false, error: stderr || `Exit code: ${code}` });
|
||
}
|
||
});
|
||
});
|
||
});
|
||
}
|
||
|
||
/**
|
||
* pkexec 不可用时的回退方案
|
||
*/
|
||
private async execWithFallback(
|
||
command: string,
|
||
options: PrivilegeOptions
|
||
): Promise<PrivilegeResult> {
|
||
// 尝试 gksudo (GNOME) 或 kdesudo (KDE)
|
||
const fallbacks = ['gksudo', 'kdesudo', 'sudo -A'];
|
||
|
||
for (const fallback of fallbacks) {
|
||
try {
|
||
const { stdout, stderr } = await execAsync(`${fallback} ${command}`);
|
||
return { success: true, stdout, stderr };
|
||
} catch {
|
||
continue;
|
||
}
|
||
}
|
||
|
||
return {
|
||
success: false,
|
||
error: 'No GUI sudo helper available. Please run ClawX as root.'
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.7.7 使用示例
|
||
|
||
```typescript
|
||
// electron/installer/node-installer.ts
|
||
|
||
import { privilegeManager } from '../privilege';
|
||
|
||
export async function installNodeGlobally(): Promise<void> {
|
||
const isNodeInstalled = await checkNodeInstalled();
|
||
|
||
if (!isNodeInstalled) {
|
||
// 通过 GUI 弹窗获取管理员权限安装 Node.js
|
||
const result = await privilegeManager.execAsAdmin(
|
||
// macOS: 使用 Homebrew
|
||
process.platform === 'darwin'
|
||
? '/opt/homebrew/bin/brew install node@22'
|
||
// Windows: 使用 winget
|
||
: process.platform === 'win32'
|
||
? 'winget install OpenJS.NodeJS.LTS'
|
||
// Linux: 使用包管理器
|
||
: 'apt-get install -y nodejs',
|
||
{
|
||
reason: '安装 Node.js 运行时环境，这是 ClawX 运行的必要组件。',
|
||
}
|
||
);
|
||
|
||
if (!result.success) {
|
||
throw new Error(`Node.js 安装失败: ${result.error}`);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.8 GUI 环境变量配置
|
||
|
||
ClawX 需要管理多种环境变量（API Keys、PATH、代理设置等），必须通过**图形界面**配置，而非要求用户编辑 `.env` 文件或终端。
|
||
|
||
#### 2.8.1 环境变量分类
|
||
|
||
| 类型 | 示例 | 存储位置 | 安全级别 |
|
||
|------|------|----------|----------|
|
||
| **API Keys** | `ANTHROPIC_API_KEY` | 系统密钥链 | 🔐 加密存储 |
|
||
| **PATH** | Node.js/npm 路径 | Shell Profile | 普通 |
|
||
| **代理** | `HTTP_PROXY` | 应用配置 | 普通 |
|
||
| **应用配置** | `CLAWX_PORT` | 应用配置 | 普通 |
|
||
|
||
#### 2.8.2 环境配置管理器
|
||
|
||
```typescript
|
||
// electron/env-config/index.ts
|
||
|
||
import { safeStorage, app } from 'electron';
|
||
import Store from 'electron-store';
|
||
import { PathManager } from './path-manager';
|
||
import { ApiKeyManager } from './api-keys';
|
||
import { ShellProfileManager } from './shell-profile';
|
||
|
||
export interface EnvConfig {
|
||
// API Keys (加密存储)
|
||
apiKeys: {
|
||
anthropic?: string;
|
||
openai?: string;
|
||
google?: string;
|
||
[key: string]: string | undefined;
|
||
};
|
||
|
||
// 代理设置
|
||
proxy: {
|
||
http?: string;
|
||
https?: string;
|
||
noProxy?: string[];
|
||
};
|
||
|
||
// 应用配置
|
||
app: {
|
||
port?: number;
|
||
logLevel?: string;
|
||
dataDir?: string;
|
||
};
|
||
}
|
||
|
||
export class EnvConfigManager {
|
||
private store: Store;
|
||
private pathManager: PathManager;
|
||
private apiKeyManager: ApiKeyManager;
|
||
private shellProfileManager: ShellProfileManager;
|
||
|
||
constructor() {
|
||
this.store = new Store({ name: 'env-config' });
|
||
this.pathManager = new PathManager();
|
||
this.apiKeyManager = new ApiKeyManager();
|
||
this.shellProfileManager = new ShellProfileManager();
|
||
}
|
||
|
||
/**
|
||
* 获取所有环境配置 (API Keys 脱敏)
|
||
*/
|
||
getConfig(): EnvConfig {
|
||
return {
|
||
apiKeys: this.apiKeyManager.getMaskedKeys(),
|
||
proxy: this.store.get('proxy', {}) as EnvConfig['proxy'],
|
||
app: this.store.get('app', {}) as EnvConfig['app'],
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 设置 API Key (自动加密存储)
|
||
*/
|
||
async setApiKey(provider: string, key: string): Promise<void> {
|
||
await this.apiKeyManager.setKey(provider, key);
|
||
|
||
// 同步到 OpenClaw 配置
|
||
await this.syncToOpenClaw();
|
||
}
|
||
|
||
/**
|
||
* 设置代理
|
||
*/
|
||
setProxy(proxy: EnvConfig['proxy']): void {
|
||
this.store.set('proxy', proxy);
|
||
this.applyProxy(proxy);
|
||
}
|
||
|
||
/**
|
||
* 确保 PATH 包含必要的路径
|
||
*/
|
||
async ensurePath(): Promise<void> {
|
||
const requiredPaths = [
|
||
'/usr/local/bin',
|
||
'/opt/homebrew/bin', // macOS ARM
|
||
`${app.getPath('home')}/.nvm/versions/node/*/bin`, // nvm
|
||
`${app.getPath('home')}/.local/bin`, // pip install --user
|
||
];
|
||
|
||
for (const p of requiredPaths) {
|
||
await this.pathManager.addToPath(p);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 同步配置到 OpenClaw
|
||
*/
|
||
private async syncToOpenClaw(): Promise<void> {
|
||
const openclawConfigPath = `${app.getPath('home')}/.openclaw/config.json`;
|
||
// 读取现有配置，合并 API keys，写回
|
||
// ...
|
||
}
|
||
|
||
private applyProxy(proxy: EnvConfig['proxy']): void {
|
||
if (proxy.http) process.env.HTTP_PROXY = proxy.http;
|
||
if (proxy.https) process.env.HTTPS_PROXY = proxy.https;
|
||
if (proxy.noProxy) process.env.NO_PROXY = proxy.noProxy.join(',');
|
||
}
|
||
}
|
||
|
||
export const envConfigManager = new EnvConfigManager();
|
||
```
|
||
|
||
#### 2.8.3 API Key 安全存储
|
||
|
||
```typescript
|
||
// electron/env-config/api-keys.ts
|
||
|
||
import { safeStorage } from 'electron';
|
||
import Store from 'electron-store';
|
||
import keytar from 'keytar';
|
||
|
||
const SERVICE_NAME = 'ClawX';
|
||
|
||
/**
|
||
* API Key 管理器
|
||
* 使用系统密钥链安全存储敏感信息
|
||
*/
|
||
export class ApiKeyManager {
|
||
private store: Store;
|
||
|
||
constructor() {
|
||
this.store = new Store({ name: 'api-keys-meta' });
|
||
}
|
||
|
||
/**
|
||
* 安全存储 API Key
|
||
* - macOS: 使用 Keychain
|
||
* - Windows: 使用 Credential Manager
|
||
* - Linux: 使用 libsecret (GNOME Keyring / KWallet)
|
||
*/
|
||
async setKey(provider: string, key: string): Promise<void> {
|
||
try {
|
||
// 首选: 系统密钥链 (通过 keytar)
|
||
await keytar.setPassword(SERVICE_NAME, provider, key);
|
||
this.store.set(`providers.${provider}`, { stored: true, method: 'keychain' });
|
||
} catch {
|
||
// 回退: Electron safeStorage (本地加密)
|
||
if (safeStorage.isEncryptionAvailable()) {
|
||
const encrypted = safeStorage.encryptString(key);
|
||
this.store.set(`providers.${provider}`, {
|
||
stored: true,
|
||
method: 'safeStorage',
|
||
encrypted: encrypted.toString('base64'),
|
||
});
|
||
} else {
|
||
throw new Error('No secure storage available');
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 获取 API Key
|
||
*/
|
||
async getKey(provider: string): Promise<string | null> {
|
||
const meta = this.store.get(`providers.${provider}`) as any;
|
||
if (!meta?.stored) return null;
|
||
|
||
if (meta.method === 'keychain') {
|
||
return keytar.getPassword(SERVICE_NAME, provider);
|
||
} else if (meta.method === 'safeStorage' && meta.encrypted) {
|
||
const buffer = Buffer.from(meta.encrypted, 'base64');
|
||
return safeStorage.decryptString(buffer);
|
||
}
|
||
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* 删除 API Key
|
||
*/
|
||
async deleteKey(provider: string): Promise<void> {
|
||
const meta = this.store.get(`providers.${provider}`) as any;
|
||
if (!meta?.stored) return;
|
||
|
||
if (meta.method === 'keychain') {
|
||
await keytar.deletePassword(SERVICE_NAME, provider);
|
||
}
|
||
|
||
this.store.delete(`providers.${provider}`);
|
||
}
|
||
|
||
/**
|
||
* 获取所有已配置的 Key (脱敏显示)
|
||
*/
|
||
getMaskedKeys(): Record<string, string | undefined> {
|
||
const result: Record<string, string | undefined> = {};
|
||
const providers = this.store.get('providers', {}) as Record<string, any>;
|
||
|
||
for (const [provider, meta] of Object.entries(providers)) {
|
||
if (meta?.stored) {
|
||
result[provider] = '••••••••••••'; // 脱敏显示
|
||
}
|
||
}
|
||
|
||
return result;
|
||
}
|
||
|
||
/**
|
||
* 检查 Key 是否已配置
|
||
*/
|
||
hasKey(provider: string): boolean {
|
||
const meta = this.store.get(`providers.${provider}`) as any;
|
||
return meta?.stored === true;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.8.4 PATH 环境变量管理
|
||
|
||
```typescript
|
||
// electron/env-config/path-manager.ts
|
||
|
||
import { exec } from 'child_process';
|
||
import { promisify } from 'util';
|
||
import { existsSync, writeFileSync, readFileSync } from 'fs';
|
||
import { join } from 'path';
|
||
import { homedir, platform } from 'os';
|
||
import { privilegeManager } from '../privilege';
|
||
|
||
const execAsync = promisify(exec);
|
||
|
||
export class PathManager {
|
||
/**
|
||
* 添加路径到 PATH 环境变量
|
||
* 通过 GUI 完成，用户无需手动编辑 shell 配置文件
|
||
*/
|
||
async addToPath(newPath: string): Promise<void> {
|
||
// 检查路径是否已存在
|
||
const currentPath = process.env.PATH || '';
|
||
if (currentPath.includes(newPath)) return;
|
||
|
||
// 检查路径是否有效
|
||
if (!existsSync(newPath) && !newPath.includes('*')) return;
|
||
|
||
switch (platform()) {
|
||
case 'darwin':
|
||
await this.addToPathMacOS(newPath);
|
||
break;
|
||
case 'win32':
|
||
await this.addToPathWindows(newPath);
|
||
break;
|
||
case 'linux':
|
||
await this.addToPathLinux(newPath);
|
||
break;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* macOS: 添加到 /etc/paths.d/ (系统级) 或 shell profile (用户级)
|
||
*/
|
||
private async addToPathMacOS(newPath: string): Promise<void> {
|
||
// 优先使用用户级配置 (~/.zshrc 或 ~/.bash_profile)
|
||
const shellProfile = this.getShellProfile();
|
||
|
||
if (shellProfile) {
|
||
const content = existsSync(shellProfile)
|
||
? readFileSync(shellProfile, 'utf-8')
|
||
: '';
|
||
|
||
if (!content.includes(newPath)) {
|
||
const exportLine = `\nexport PATH="${newPath}:$PATH"\n`;
|
||
writeFileSync(shellProfile, content + exportLine);
|
||
}
|
||
} else {
|
||
// 回退到系统级 (需要管理员权限)
|
||
const pathFile = `/etc/paths.d/clawx`;
|
||
await privilegeManager.execAsAdmin(
|
||
`echo "${newPath}" >> ${pathFile}`,
|
||
{ reason: '配置系统 PATH 环境变量' }
|
||
);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Windows: 修改用户环境变量 (通过注册表)
|
||
*/
|
||
private async addToPathWindows(newPath: string): Promise<void> {
|
||
// 使用 PowerShell 修改用户级 PATH (无需管理员权限)
|
||
const command = `
|
||
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
|
||
if ($currentPath -notlike "*${newPath}*") {
|
||
[Environment]::SetEnvironmentVariable("Path", "${newPath};$currentPath", "User")
|
||
}
|
||
`;
|
||
|
||
await execAsync(`powershell -Command "${command}"`);
|
||
|
||
// 通知系统环境变量已更改
|
||
await execAsync('setx CLAWX_PATH_UPDATED 1');
|
||
}
|
||
|
||
/**
|
||
* Linux: 添加到 shell profile
|
||
*/
|
||
private async addToPathLinux(newPath: string): Promise<void> {
|
||
const shellProfile = this.getShellProfile();
|
||
|
||
if (shellProfile) {
|
||
const content = existsSync(shellProfile)
|
||
? readFileSync(shellProfile, 'utf-8')
|
||
: '';
|
||
|
||
if (!content.includes(newPath)) {
|
||
const exportLine = `\nexport PATH="${newPath}:$PATH"\n`;
|
||
writeFileSync(shellProfile, content + exportLine);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 获取当前用户的 shell profile 文件
|
||
*/
|
||
private getShellProfile(): string | null {
|
||
const home = homedir();
|
||
const shell = process.env.SHELL || '';
|
||
|
||
if (shell.includes('zsh')) {
|
||
return join(home, '.zshrc');
|
||
} else if (shell.includes('bash')) {
|
||
const bashProfile = join(home, '.bash_profile');
|
||
const bashrc = join(home, '.bashrc');
|
||
return existsSync(bashProfile) ? bashProfile : bashrc;
|
||
} else if (shell.includes('fish')) {
|
||
return join(home, '.config/fish/config.fish');
|
||
}
|
||
|
||
// 默认
|
||
return join(home, '.profile');
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.8.5 设置页面 UI
|
||
|
||
```typescript
|
||
// src/pages/Settings/ProviderSettings.tsx
|
||
|
||
import { useState, useEffect } from 'react';
|
||
import { Eye, EyeOff, Check, AlertCircle } from 'lucide-react';
|
||
|
||
interface ApiKeyInputProps {
|
||
provider: string;
|
||
label: string;
|
||
placeholder: string;
|
||
hasKey: boolean;
|
||
onSave: (key: string) => Promise<void>;
|
||
onDelete: () => Promise<void>;
|
||
}
|
||
|
||
function ApiKeyInput({ provider, label, placeholder, hasKey, onSave, onDelete }: ApiKeyInputProps) {
|
||
const [value, setValue] = useState('');
|
||
const [showKey, setShowKey] = useState(false);
|
||
const [saving, setSaving] = useState(false);
|
||
const [error, setError] = useState<string | null>(null);
|
||
|
||
const handleSave = async () => {
|
||
if (!value.trim()) return;
|
||
|
||
setSaving(true);
|
||
setError(null);
|
||
|
||
try {
|
||
await onSave(value);
|
||
setValue(''); // 清空输入，显示"已配置"状态
|
||
} catch (e: any) {
|
||
setError(e.message);
|
||
} finally {
|
||
setSaving(false);
|
||
}
|
||
};
|
||
|
||
return (
|
||
<div className="space-y-2">
|
||
<Label className="text-sm font-medium">{label}</Label>
|
||
|
||
{hasKey ? (
|
||
// 已配置状态
|
||
<div className="flex items-center gap-2 p-3 rounded-lg border bg-green-50 dark:bg-green-950 border-green-200">
|
||
<Check className="w-4 h-4 text-green-600" />
|
||
<span className="text-sm text-green-700 dark:text-green-400">已配置</span>
|
||
<span className="text-sm text-muted-foreground">••••••••••••</span>
|
||
<div className="flex-1" />
|
||
<Button variant="ghost" size="sm" onClick={onDelete}>
|
||
删除
|
||
</Button>
|
||
<Button variant="ghost" size="sm" onClick={() => setShowKey(true)}>
|
||
重新配置
|
||
</Button>
|
||
</div>
|
||
) : (
|
||
// 未配置状态
|
||
<div className="flex gap-2">
|
||
<div className="relative flex-1">
|
||
<Input
|
||
type={showKey ? 'text' : 'password'}
|
||
value={value}
|
||
onChange={(e) => setValue(e.target.value)}
|
||
placeholder={placeholder}
|
||
className="pr-10"
|
||
/>
|
||
<Button
|
||
type="button"
|
||
variant="ghost"
|
||
size="icon"
|
||
className="absolute right-0 top-0 h-full"
|
||
onClick={() => setShowKey(!showKey)}
|
||
>
|
||
{showKey ? <EyeOff className="w-4 h-4" /> : <Eye className="w-4 h-4" />}
|
||
</Button>
|
||
</div>
|
||
<Button onClick={handleSave} disabled={saving || !value.trim()}>
|
||
{saving ? '保存中...' : '保存'}
|
||
</Button>
|
||
</div>
|
||
)}
|
||
|
||
{error && (
|
||
<div className="flex items-center gap-2 text-sm text-red-600">
|
||
<AlertCircle className="w-4 h-4" />
|
||
{error}
|
||
</div>
|
||
)}
|
||
|
||
<p className="text-xs text-muted-foreground">
|
||
API Key 将安全存储在系统密钥链中，不会以明文保存。
|
||
</p>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
export function ProviderSettings() {
|
||
const [config, setConfig] = useState<any>(null);
|
||
|
||
useEffect(() => {
|
||
// 从主进程获取配置
|
||
window.electron.ipcRenderer.invoke('env:getConfig').then(setConfig);
|
||
}, []);
|
||
|
||
const handleSaveApiKey = async (provider: string, key: string) => {
|
||
await window.electron.ipcRenderer.invoke('env:setApiKey', provider, key);
|
||
// 刷新配置
|
||
const newConfig = await window.electron.ipcRenderer.invoke('env:getConfig');
|
||
setConfig(newConfig);
|
||
};
|
||
|
||
const handleDeleteApiKey = async (provider: string) => {
|
||
await window.electron.ipcRenderer.invoke('env:deleteApiKey', provider);
|
||
const newConfig = await window.electron.ipcRenderer.invoke('env:getConfig');
|
||
setConfig(newConfig);
|
||
};
|
||
|
||
if (!config) return <LoadingSpinner />;
|
||
|
||
return (
|
||
<Card>
|
||
<CardHeader>
|
||
<CardTitle>AI 模型配置</CardTitle>
|
||
<CardDescription>
|
||
配置您的 AI 服务提供商 API Key
|
||
</CardDescription>
|
||
</CardHeader>
|
||
<CardContent className="space-y-6">
|
||
<ApiKeyInput
|
||
provider="anthropic"
|
||
label="Anthropic (Claude)"
|
||
placeholder="sk-ant-api03-..."
|
||
hasKey={!!config.apiKeys.anthropic}
|
||
onSave={(key) => handleSaveApiKey('anthropic', key)}
|
||
onDelete={() => handleDeleteApiKey('anthropic')}
|
||
/>
|
||
|
||
<Separator />
|
||
|
||
<ApiKeyInput
|
||
provider="openai"
|
||
label="OpenAI (GPT)"
|
||
placeholder="sk-..."
|
||
hasKey={!!config.apiKeys.openai}
|
||
onSave={(key) => handleSaveApiKey('openai', key)}
|
||
onDelete={() => handleDeleteApiKey('openai')}
|
||
/>
|
||
|
||
<Separator />
|
||
|
||
<ApiKeyInput
|
||
provider="google"
|
||
label="Google (Gemini)"
|
||
placeholder="AIza..."
|
||
hasKey={!!config.apiKeys.google}
|
||
onSave={(key) => handleSaveApiKey('google', key)}
|
||
onDelete={() => handleDeleteApiKey('google')}
|
||
/>
|
||
</CardContent>
|
||
</Card>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 2.8.6 安装向导集成
|
||
|
||
```typescript
|
||
// src/pages/Setup/ProviderStep.tsx
|
||
|
||
export function ProviderStep({ onNext, onBack }: StepProps) {
|
||
const [selectedProvider, setSelectedProvider] = useState<string>('anthropic');
|
||
const [apiKey, setApiKey] = useState('');
|
||
const [validating, setValidating] = useState(false);
|
||
const [error, setError] = useState<string | null>(null);
|
||
|
||
const providers = [
|
||
{ id: 'anthropic', name: 'Anthropic', model: 'Claude', icon: '🤖' },
|
||
{ id: 'openai', name: 'OpenAI', model: 'GPT-4', icon: '💚' },
|
||
{ id: 'google', name: 'Google', model: 'Gemini', icon: '🔷' },
|
||
];
|
||
|
||
const handleNext = async () => {
|
||
if (!apiKey.trim()) {
|
||
setError('请输入 API Key');
|
||
return;
|
||
}
|
||
|
||
setValidating(true);
|
||
setError(null);
|
||
|
||
try {
|
||
// 验证 API Key 是否有效
|
||
const valid = await window.electron.ipcRenderer.invoke(
|
||
'provider:validateKey',
|
||
selectedProvider,
|
||
apiKey
|
||
);
|
||
|
||
if (!valid) {
|
||
setError('API Key 无效，请检查后重试');
|
||
return;
|
||
}
|
||
|
||
// 安全存储 API Key
|
||
await window.electron.ipcRenderer.invoke(
|
||
'env:setApiKey',
|
||
selectedProvider,
|
||
apiKey
|
||
);
|
||
|
||
onNext({ provider: selectedProvider });
|
||
} catch (e: any) {
|
||
setError(e.message);
|
||
} finally {
|
||
setValidating(false);
|
||
}
|
||
};
|
||
|
||
return (
|
||
<div className="space-y-6">
|
||
<div className="space-y-4">
|
||
<Label>选择 AI 服务提供商</Label>
|
||
<div className="grid grid-cols-3 gap-4">
|
||
{providers.map((p) => (
|
||
<Card
|
||
key={p.id}
|
||
className={cn(
|
||
'cursor-pointer transition-all p-4',
|
||
selectedProvider === p.id && 'ring-2 ring-primary'
|
||
)}
|
||
onClick={() => setSelectedProvider(p.id)}
|
||
>
|
||
<div className="text-center">
|
||
<span className="text-3xl">{p.icon}</span>
|
||
<p className="font-medium mt-2">{p.name}</p>
|
||
<p className="text-sm text-muted-foreground">{p.model}</p>
|
||
</div>
|
||
</Card>
|
||
))}
|
||
</div>
|
||
</div>
|
||
|
||
<div className="space-y-2">
|
||
<Label>API Key</Label>
|
||
<Input
|
||
type="password"
|
||
value={apiKey}
|
||
onChange={(e) => setApiKey(e.target.value)}
|
||
placeholder={`输入您的 ${providers.find(p => p.id === selectedProvider)?.name} API Key`}
|
||
/>
|
||
{error && (
|
||
<p className="text-sm text-red-600">{error}</p>
|
||
)}
|
||
<p className="text-xs text-muted-foreground">
|
||
您的 API Key 将安全存储在系统密钥链中，不会上传到任何服务器。
|
||
</p>
|
||
</div>
|
||
|
||
<div className="flex justify-between">
|
||
<Button variant="ghost" onClick={onBack}>上一步</Button>
|
||
<Button onClick={handleNext} disabled={validating}>
|
||
{validating ? '验证中...' : '下一步'}
|
||
</Button>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、UI/UX 设计规范
|
||
|
||
### 3.1 设计原则
|
||
|
||
| 原则 | 描述 |
|
||
|------|------|
|
||
| **简洁优先** | 隐藏复杂性，暴露必要功能 |
|
||
| **渐进式披露** | 基础功能易达，高级功能可探索 |
|
||
| **一致性** | 跨页面/组件保持视觉和交互一致 |
|
||
| **响应式反馈** | 所有操作有即时视觉反馈 |
|
||
| **原生感** | 遵循各平台设计语言 |
|
||
|
||
### 3.2 色彩系统
|
||
|
||
```css
|
||
/* src/styles/themes/tokens.css */
|
||
:root {
|
||
/* Primary */
|
||
--color-primary-50: #eff6ff;
|
||
--color-primary-500: #3b82f6;
|
||
--color-primary-600: #2563eb;
|
||
|
||
/* Semantic */
|
||
--color-success: #22c55e;
|
||
--color-warning: #f59e0b;
|
||
--color-error: #ef4444;
|
||
--color-info: #3b82f6;
|
||
|
||
/* Neutral (Light) */
|
||
--color-bg-primary: #ffffff;
|
||
--color-bg-secondary: #f8fafc;
|
||
--color-text-primary: #0f172a;
|
||
--color-text-secondary: #64748b;
|
||
--color-border: #e2e8f0;
|
||
}
|
||
|
||
[data-theme="dark"] {
|
||
--color-bg-primary: #0f172a;
|
||
--color-bg-secondary: #1e293b;
|
||
--color-text-primary: #f8fafc;
|
||
--color-text-secondary: #94a3b8;
|
||
--color-border: #334155;
|
||
}
|
||
```
|
||
|
||
### 3.3 核心页面线框图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ClawX ─ □ × │
|
||
├──────────┬──────────────────────────────────────────────┤
|
||
│ │ │
|
||
│ ● 概览 │ ┌─────────────┐ ┌─────────────┐ │
|
||
│ ○ 对话 │ │ Gateway │ │ Channels │ │
|
||
│ ○ 通道 │ │ ● 运行中 │ │ 3 已连接 │ │
|
||
│ ○ 技能 │ └─────────────┘ └─────────────┘ │
|
||
│ ○ 设置 │ │
|
||
│ ○ 定时任务│ ┌───────────────────────────────────────┐ │
|
||
│ │ │ 最近对话 │ │
|
||
│ │ ├───────────────────────────────────────┤ │
|
||
│ │ │ 📱 WhatsApp · 用户A · 2分钟前 │ │
|
||
│ │ │ 💬 Telegram · 用户B · 15分钟前 │ │
|
||
│ │ │ 💬 Discord · 用户C · 1小时前 │ │
|
||
│ │ └───────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ ┌───────────────────────────────────────┐ │
|
||
│ │ │ 快捷操作 │ │
|
||
│ │ │ [添加通道] [浏览技能] [查看日志] │ │
|
||
│ │ └───────────────────────────────────────┘ │
|
||
│ │ │
|
||
├──────────┴──────────────────────────────────────────────┤
|
||
│ Gateway: 运行中 · 3 通道 · 12 技能 · v2026.2.3 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.4 定时任务页面设计
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ClawX ─ □ × │
|
||
├──────────┬──────────────────────────────────────────────┤
|
||
│ │ │
|
||
│ ○ 概览 │ 定时任务 [+ 新建任务] │
|
||
│ ○ 对话 │ │
|
||
│ ○ 通道 │ ┌───────────────────────────────────────┐ │
|
||
│ ○ 技能 │ │ 📋 每日天气播报 ● 已启用 │ │
|
||
│ ● 定时 │ │ ⏰ 每天 08:00 │ │
|
||
│ ○ 设置 │ │ 📍 发送到: WhatsApp - 家庭群 │ │
|
||
│ │ │ 上次执行: 今天 08:00 ✓ │ │
|
||
│ │ │ [编辑] [暂停] [删除] │ │
|
||
│ │ └───────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ ┌───────────────────────────────────────┐ │
|
||
│ │ │ 📊 周报汇总 ○ 已暂停 │ │
|
||
│ │ │ ⏰ 每周五 18:00 │ │
|
||
│ │ │ 📍 发送到: Telegram - 工作频道 │ │
|
||
│ │ │ 上次执行: 上周五 18:00 ✓ │ │
|
||
│ │ │ [编辑] [启用] [删除] │ │
|
||
│ │ └───────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ ┌───────────────────────────────────────┐ │
|
||
│ │ │ 🔔 服务器健康检查 ● 已启用 │ │
|
||
│ │ │ ⏰ 每 30 分钟 │ │
|
||
│ │ │ 📍 发送到: Discord - 运维通知 │ │
|
||
│ │ │ 上次执行: 10分钟前 ✓ │ │
|
||
│ │ │ [编辑] [暂停] [删除] │ │
|
||
│ │ └───────────────────────────────────────┘ │
|
||
│ │ │
|
||
├──────────┴──────────────────────────────────────────────┤
|
||
│ 3 个任务 · 2 个运行中 · 1 个暂停 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 定时任务编辑器弹窗
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 新建定时任务 [×] │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 任务名称 │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ 每日天气播报 │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 执行内容 (发送给 AI 的消息) │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ 请查询北京今天的天气，并生成一条适合发送到群里 │ │
|
||
│ │ 的天气播报消息，包含穿衣建议。 │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 执行时间 │
|
||
│ ┌──────────────┐ ┌────────────────────────────┐ │
|
||
│ │ ○ 每天 │ │ 08 : 00 │ │
|
||
│ │ ○ 每周 │ └────────────────────────────┘ │
|
||
│ │ ○ 每月 │ │
|
||
│ │ ○ 自定义Cron │ Cron: 0 8 * * * │
|
||
│ └──────────────┘ │
|
||
│ │
|
||
│ 发送到 │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ WhatsApp - 家庭群 ▼ │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ☑ 启用任务 │
|
||
│ │
|
||
│ [取消] [保存] │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 定时任务类型定义
|
||
|
||
```typescript
|
||
// src/types/cron.ts
|
||
|
||
export interface CronJob {
|
||
/** 任务 ID */
|
||
id: string;
|
||
|
||
/** 任务名称 */
|
||
name: string;
|
||
|
||
/** 发送给 AI 的消息内容 */
|
||
message: string;
|
||
|
||
/** Cron 表达式 */
|
||
schedule: string;
|
||
|
||
/** 目标通道 */
|
||
target: {
|
||
channelType: 'whatsapp' | 'telegram' | 'discord' | 'slack';
|
||
channelId: string;
|
||
channelName: string;
|
||
};
|
||
|
||
/** 是否启用 */
|
||
enabled: boolean;
|
||
|
||
/** 创建时间 */
|
||
createdAt: string;
|
||
|
||
/** 更新时间 */
|
||
updatedAt: string;
|
||
|
||
/** 上次执行信息 */
|
||
lastRun?: {
|
||
time: string;
|
||
success: boolean;
|
||
error?: string;
|
||
};
|
||
|
||
/** 下次执行时间 */
|
||
nextRun?: string;
|
||
}
|
||
|
||
export interface CronJobCreateInput {
|
||
name: string;
|
||
message: string;
|
||
schedule: string;
|
||
target: CronJob['target'];
|
||
enabled?: boolean;
|
||
}
|
||
|
||
export interface CronJobUpdateInput {
|
||
name?: string;
|
||
message?: string;
|
||
schedule?: string;
|
||
target?: CronJob['target'];
|
||
enabled?: boolean;
|
||
}
|
||
```
|
||
|
||
#### 定时任务 Hook
|
||
|
||
```typescript
|
||
// src/hooks/useCron.ts
|
||
|
||
import { useState, useEffect, useCallback } from 'react';
|
||
import type { CronJob, CronJobCreateInput, CronJobUpdateInput } from '@/types/cron';
|
||
|
||
export function useCron() {
|
||
const [jobs, setJobs] = useState<CronJob[]>([]);
|
||
const [loading, setLoading] = useState(true);
|
||
const [error, setError] = useState<string | null>(null);
|
||
|
||
// 加载任务列表
|
||
const fetchJobs = useCallback(async () => {
|
||
try {
|
||
setLoading(true);
|
||
const result = await window.electron.ipcRenderer.invoke('cron:list');
|
||
setJobs(result);
|
||
setError(null);
|
||
} catch (e: any) {
|
||
setError(e.message);
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
}, []);
|
||
|
||
useEffect(() => {
|
||
fetchJobs();
|
||
|
||
// 监听任务更新事件
|
||
const handleUpdate = (_: any, updatedJobs: CronJob[]) => {
|
||
setJobs(updatedJobs);
|
||
};
|
||
|
||
window.electron.ipcRenderer.on('cron:updated', handleUpdate);
|
||
|
||
return () => {
|
||
window.electron.ipcRenderer.off('cron:updated', handleUpdate);
|
||
};
|
||
}, [fetchJobs]);
|
||
|
||
// 创建任务
|
||
const createJob = async (input: CronJobCreateInput): Promise<CronJob> => {
|
||
const job = await window.electron.ipcRenderer.invoke('cron:create', input);
|
||
await fetchJobs();
|
||
return job;
|
||
};
|
||
|
||
// 更新任务
|
||
const updateJob = async (id: string, input: CronJobUpdateInput): Promise<void> => {
|
||
await window.electron.ipcRenderer.invoke('cron:update', id, input);
|
||
await fetchJobs();
|
||
};
|
||
|
||
// 删除任务
|
||
const deleteJob = async (id: string): Promise<void> => {
|
||
await window.electron.ipcRenderer.invoke('cron:delete', id);
|
||
await fetchJobs();
|
||
};
|
||
|
||
// 启用/禁用任务
|
||
const toggleJob = async (id: string, enabled: boolean): Promise<void> => {
|
||
await window.electron.ipcRenderer.invoke('cron:toggle', id, enabled);
|
||
await fetchJobs();
|
||
};
|
||
|
||
// 手动触发任务
|
||
const triggerJob = async (id: string): Promise<void> => {
|
||
await window.electron.ipcRenderer.invoke('cron:trigger', id);
|
||
};
|
||
|
||
return {
|
||
jobs,
|
||
loading,
|
||
error,
|
||
createJob,
|
||
updateJob,
|
||
deleteJob,
|
||
toggleJob,
|
||
triggerJob,
|
||
refresh: fetchJobs,
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 定时任务页面组件
|
||
|
||
```typescript
|
||
// src/pages/Cron/index.tsx
|
||
|
||
import { useState } from 'react';
|
||
import { useCron } from '@/hooks/useCron';
|
||
import { CronJobCard } from './CronJobCard';
|
||
import { CronEditor } from './CronEditor';
|
||
import { Plus, Clock } from 'lucide-react';
|
||
|
||
export function CronPage() {
|
||
const { jobs, loading, createJob, updateJob, deleteJob, toggleJob } = useCron();
|
||
const [editorOpen, setEditorOpen] = useState(false);
|
||
const [editingJob, setEditingJob] = useState<CronJob | null>(null);
|
||
|
||
const activeJobs = jobs.filter(j => j.enabled);
|
||
const pausedJobs = jobs.filter(j => !j.enabled);
|
||
|
||
const handleCreate = () => {
|
||
setEditingJob(null);
|
||
setEditorOpen(true);
|
||
};
|
||
|
||
const handleEdit = (job: CronJob) => {
|
||
setEditingJob(job);
|
||
setEditorOpen(true);
|
||
};
|
||
|
||
const handleSave = async (input: CronJobCreateInput) => {
|
||
if (editingJob) {
|
||
await updateJob(editingJob.id, input);
|
||
} else {
|
||
await createJob(input);
|
||
}
|
||
setEditorOpen(false);
|
||
};
|
||
|
||
if (loading) return <LoadingSpinner />;
|
||
|
||
return (
|
||
<div className="p-6 space-y-6">
|
||
{/* 页头 */}
|
||
<div className="flex items-center justify-between">
|
||
<div>
|
||
<h1 className="text-2xl font-bold">定时任务</h1>
|
||
<p className="text-muted-foreground">
|
||
设置自动执行的 AI 任务，按计划发送消息
|
||
</p>
|
||
</div>
|
||
<Button onClick={handleCreate}>
|
||
<Plus className="w-4 h-4 mr-2" />
|
||
新建任务
|
||
</Button>
|
||
</div>
|
||
|
||
{/* 统计卡片 */}
|
||
<div className="grid grid-cols-3 gap-4">
|
||
<Card>
|
||
<CardContent className="pt-6">
|
||
<div className="flex items-center gap-4">
|
||
<div className="p-3 rounded-full bg-primary/10">
|
||
<Clock className="w-6 h-6 text-primary" />
|
||
</div>
|
||
<div>
|
||
<p className="text-2xl font-bold">{jobs.length}</p>
|
||
<p className="text-sm text-muted-foreground">总任务数</p>
|
||
</div>
|
||
</div>
|
||
</CardContent>
|
||
</Card>
|
||
<Card>
|
||
<CardContent className="pt-6">
|
||
<div className="flex items-center gap-4">
|
||
<div className="p-3 rounded-full bg-green-100">
|
||
<Play className="w-6 h-6 text-green-600" />
|
||
</div>
|
||
<div>
|
||
<p className="text-2xl font-bold">{activeJobs.length}</p>
|
||
<p className="text-sm text-muted-foreground">运行中</p>
|
||
</div>
|
||
</div>
|
||
</CardContent>
|
||
</Card>
|
||
<Card>
|
||
<CardContent className="pt-6">
|
||
<div className="flex items-center gap-4">
|
||
<div className="p-3 rounded-full bg-yellow-100">
|
||
<Pause className="w-6 h-6 text-yellow-600" />
|
||
</div>
|
||
<div>
|
||
<p className="text-2xl font-bold">{pausedJobs.length}</p>
|
||
<p className="text-sm text-muted-foreground">已暂停</p>
|
||
</div>
|
||
</div>
|
||
</CardContent>
|
||
</Card>
|
||
</div>
|
||
|
||
{/* 任务列表 */}
|
||
{jobs.length === 0 ? (
|
||
<Card className="p-12 text-center">
|
||
<Clock className="w-12 h-12 mx-auto text-muted-foreground mb-4" />
|
||
<h3 className="text-lg font-medium mb-2">暂无定时任务</h3>
|
||
<p className="text-muted-foreground mb-4">
|
||
创建您的第一个定时任务，让 AI 自动为您工作
|
||
</p>
|
||
<Button onClick={handleCreate}>
|
||
<Plus className="w-4 h-4 mr-2" />
|
||
新建任务
|
||
</Button>
|
||
</Card>
|
||
) : (
|
||
<div className="space-y-4">
|
||
{jobs.map(job => (
|
||
<CronJobCard
|
||
key={job.id}
|
||
job={job}
|
||
onEdit={() => handleEdit(job)}
|
||
onDelete={() => deleteJob(job.id)}
|
||
onToggle={(enabled) => toggleJob(job.id, enabled)}
|
||
/>
|
||
))}
|
||
</div>
|
||
)}
|
||
|
||
{/* 编辑器弹窗 */}
|
||
<CronEditor
|
||
open={editorOpen}
|
||
onClose={() => setEditorOpen(false)}
|
||
onSave={handleSave}
|
||
initialData={editingJob}
|
||
/>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Cron 表达式选择器
|
||
|
||
```typescript
|
||
// src/pages/Cron/CronSchedulePicker.tsx
|
||
|
||
import { useState, useEffect } from 'react';
|
||
|
||
interface CronSchedulePickerProps {
|
||
value: string;
|
||
onChange: (cron: string) => void;
|
||
}
|
||
|
||
type ScheduleType = 'daily' | 'weekly' | 'monthly' | 'interval' | 'custom';
|
||
|
||
export function CronSchedulePicker({ value, onChange }: CronSchedulePickerProps) {
|
||
const [type, setType] = useState<ScheduleType>('daily');
|
||
const [time, setTime] = useState('08:00');
|
||
const [weekday, setWeekday] = useState(1); // 周一
|
||
const [monthday, setMonthday] = useState(1);
|
||
const [interval, setInterval] = useState(30); // 分钟
|
||
const [customCron, setCustomCron] = useState(value);
|
||
|
||
// 解析现有 cron 表达式
|
||
useEffect(() => {
|
||
// 简单解析，实际可用 cron-parser 库
|
||
if (value.match(/^\d+ \d+ \* \* \*$/)) {
|
||
setType('daily');
|
||
const [min, hour] = value.split(' ');
|
||
setTime(`${hour.padStart(2, '0')}:${min.padStart(2, '0')}`);
|
||
}
|
||
// ... 其他模式解析
|
||
}, []);
|
||
|
||
// 生成 cron 表达式
|
||
useEffect(() => {
|
||
let cron = '';
|
||
const [hour, min] = time.split(':');
|
||
|
||
switch (type) {
|
||
case 'daily':
|
||
cron = `${parseInt(min)} ${parseInt(hour)} * * *`;
|
||
break;
|
||
case 'weekly':
|
||
cron = `${parseInt(min)} ${parseInt(hour)} * * ${weekday}`;
|
||
break;
|
||
case 'monthly':
|
||
cron = `${parseInt(min)} ${parseInt(hour)} ${monthday} * *`;
|
||
break;
|
||
case 'interval':
|
||
cron = `*/${interval} * * * *`;
|
||
break;
|
||
case 'custom':
|
||
cron = customCron;
|
||
break;
|
||
}
|
||
|
||
if (cron !== value) {
|
||
onChange(cron);
|
||
}
|
||
}, [type, time, weekday, monthday, interval, customCron]);
|
||
|
||
const weekdays = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
|
||
|
||
return (
|
||
<div className="space-y-4">
|
||
{/* 类型选择 */}
|
||
<RadioGroup value={type} onValueChange={(v) => setType(v as ScheduleType)}>
|
||
<div className="flex items-center space-x-2">
|
||
<RadioGroupItem value="daily" id="daily" />
|
||
<Label htmlFor="daily">每天</Label>
|
||
</div>
|
||
<div className="flex items-center space-x-2">
|
||
<RadioGroupItem value="weekly" id="weekly" />
|
||
<Label htmlFor="weekly">每周</Label>
|
||
</div>
|
||
<div className="flex items-center space-x-2">
|
||
<RadioGroupItem value="monthly" id="monthly" />
|
||
<Label htmlFor="monthly">每月</Label>
|
||
</div>
|
||
<div className="flex items-center space-x-2">
|
||
<RadioGroupItem value="interval" id="interval" />
|
||
<Label htmlFor="interval">间隔执行</Label>
|
||
</div>
|
||
<div className="flex items-center space-x-2">
|
||
<RadioGroupItem value="custom" id="custom" />
|
||
<Label htmlFor="custom">自定义 Cron</Label>
|
||
</div>
|
||
</RadioGroup>
|
||
|
||
{/* 时间选择 */}
|
||
{(type === 'daily' || type === 'weekly' || type === 'monthly') && (
|
||
<div className="flex items-center gap-2">
|
||
<Label>执行时间:</Label>
|
||
<Input
|
||
type="time"
|
||
value={time}
|
||
onChange={(e) => setTime(e.target.value)}
|
||
className="w-32"
|
||
/>
|
||
</div>
|
||
)}
|
||
|
||
{/* 周几选择 */}
|
||
{type === 'weekly' && (
|
||
<div className="flex items-center gap-2">
|
||
<Label>星期:</Label>
|
||
<Select value={String(weekday)} onValueChange={(v) => setWeekday(parseInt(v))}>
|
||
<SelectTrigger className="w-32">
|
||
<SelectValue />
|
||
</SelectTrigger>
|
||
<SelectContent>
|
||
{weekdays.map((day, i) => (
|
||
<SelectItem key={i} value={String(i)}>{day}</SelectItem>
|
||
))}
|
||
</SelectContent>
|
||
</Select>
|
||
</div>
|
||
)}
|
||
|
||
{/* 日期选择 */}
|
||
{type === 'monthly' && (
|
||
<div className="flex items-center gap-2">
|
||
<Label>日期:</Label>
|
||
<Select value={String(monthday)} onValueChange={(v) => setMonthday(parseInt(v))}>
|
||
<SelectTrigger className="w-32">
|
||
<SelectValue />
|
||
</SelectTrigger>
|
||
<SelectContent>
|
||
{Array.from({ length: 31 }, (_, i) => i + 1).map((day) => (
|
||
<SelectItem key={day} value={String(day)}>{day} 日</SelectItem>
|
||
))}
|
||
</SelectContent>
|
||
</Select>
|
||
</div>
|
||
)}
|
||
|
||
{/* 间隔选择 */}
|
||
{type === 'interval' && (
|
||
<div className="flex items-center gap-2">
|
||
<Label>每隔:</Label>
|
||
<Input
|
||
type="number"
|
||
min={1}
|
||
max={1440}
|
||
value={interval}
|
||
onChange={(e) => setInterval(parseInt(e.target.value))}
|
||
className="w-20"
|
||
/>
|
||
<span>分钟</span>
|
||
</div>
|
||
)}
|
||
|
||
{/* 自定义 Cron */}
|
||
{type === 'custom' && (
|
||
<div className="space-y-2">
|
||
<Input
|
||
value={customCron}
|
||
onChange={(e) => setCustomCron(e.target.value)}
|
||
placeholder="分 时 日 月 周 (如: 0 8 * * 1-5)"
|
||
/>
|
||
<p className="text-xs text-muted-foreground">
|
||
Cron 表达式格式: 分钟(0-59) 小时(0-23) 日(1-31) 月(1-12) 周(0-6)
|
||
</p>
|
||
</div>
|
||
)}
|
||
|
||
{/* 预览 */}
|
||
<div className="p-3 rounded-lg bg-muted">
|
||
<p className="text-sm">
|
||
<span className="text-muted-foreground">Cron 表达式: </span>
|
||
<code className="font-mono">{value}</code>
|
||
</p>
|
||
<p className="text-sm">
|
||
<span className="text-muted-foreground">下次执行: </span>
|
||
{getNextRunTime(value)}
|
||
</p>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
function getNextRunTime(cron: string): string {
|
||
// 使用 croner 或类似库计算下次执行时间
|
||
// 这里简化处理
|
||
return '今天 08:00';
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、版本规划
|
||
|
||
### 4.1 版本号策略
|
||
|
||
```
|
||
ClawX 版本: X.Y.Z[-prerelease]
|
||
│ │ │
|
||
│ │ └── Patch: Bug 修复、性能优化
|
||
│ └──── Minor: 新功能、新技能包、UI 改进
|
||
└────── Major: 重大变更、不兼容更新
|
||
|
||
示例:
|
||
- 1.0.0 首个稳定版
|
||
- 1.1.0 新增技能市场功能
|
||
- 1.1.1 修复 Windows 安装问题
|
||
- 2.0.0 UI 重构、新架构
|
||
- 1.2.0-beta.1 下一版本测试版
|
||
```
|
||
|
||
### 4.2 OpenClaw 兼容性矩阵
|
||
|
||
| ClawX 版本 | OpenClaw 版本 | Node.js 版本 | 备注 |
|
||
|------------|---------------|--------------|------|
|
||
| 1.0.x | 2026.2.x | 22.x | 首发版本 |
|
||
| 1.1.x | 2026.3.x | 22.x | 功能增强 |
|
||
| 2.0.x | 2026.6.x | 24.x | 大版本升级 |
|
||
|
||
### 4.3 里程碑规划
|
||
|
||
#### 🚀 v0.1.0 - Alpha (内部测试)
|
||
|
||
**目标**: 核心架构验证
|
||
|
||
| 任务 | 优先级 | 状态 |
|
||
|------|--------|------|
|
||
| Electron + React 项目骨架 | P0 | ⬜ |
|
||
| Gateway 进程管理 | P0 | ⬜ |
|
||
| 基础 UI 框架 (侧边栏/布局) | P0 | ⬜ |
|
||
| WebSocket 通信层 | P0 | ⬜ |
|
||
| 状态管理 (Zustand) | P1 | ⬜ |
|
||
|
||
**交付物**:
|
||
- 可运行的桌面应用
|
||
- 能启动/停止 Gateway
|
||
- 基础 Dashboard 页面
|
||
|
||
---
|
||
|
||
#### 🎯 v0.5.0 - Beta (公开测试)
|
||
|
||
**目标**: 安装向导 MVP
|
||
|
||
| 任务 | 优先级 | 状态 |
|
||
|------|--------|------|
|
||
| 安装向导 UI | P0 | ⬜ |
|
||
| Node.js 自动检测/安装 | P0 | ⬜ |
|
||
| openclaw npm 安装 | P0 | ⬜ |
|
||
| Provider 配置 (API Key) | P0 | ⬜ |
|
||
| 错误处理与提示 | P1 | ⬜ |
|
||
|
||
> **注意**: 通道连接功能 (WhatsApp/Telegram 等) 已从安装向导移至 Settings > Channels 页面。
|
||
> 用户可在完成初始设置后，根据需要自行配置消息通道，降低首次使用门槛。
|
||
|
||
**交付物**:
|
||
- 简化版安装向导流程 (不含通道连接)
|
||
- 支持 macOS (Apple Silicon + Intel)
|
||
- 可配置 Anthropic/OpenAI/OpenRouter
|
||
|
||
---
|
||
|
||
#### 📦 v1.0.0 - Stable (首个正式版)
|
||
|
||
**目标**: 生产可用
|
||
|
||
| 任务 | 优先级 | 状态 |
|
||
|------|--------|------|
|
||
| 完整 Dashboard | P0 | ⬜ |
|
||
| 通道管理页面 | P0 | ⬜ |
|
||
| 对话界面 | P0 | ⬜ |
|
||
| 技能浏览/启用 | P0 | ⬜ |
|
||
| 设置页面 | P0 | ⬜ |
|
||
| 预装技能包选择 | P1 | ⬜ |
|
||
| 自动更新 (Sparkle/electron-updater) | P1 | ⬜ |
|
||
| Windows 支持 | P1 | ⬜ |
|
||
| 深色模式 | P2 | ⬜ |
|
||
| 崩溃报告 | P2 | ⬜ |
|
||
|
||
**交付物**:
|
||
- macOS + Windows 安装包
|
||
- 自动更新能力
|
||
- 用户文档
|
||
|
||
---
|
||
|
||
#### 🌟 v1.1.0 - 功能增强
|
||
|
||
**目标**: 技能生态
|
||
|
||
| 任务 | 优先级 | 状态 |
|
||
|------|--------|------|
|
||
| 技能市场 UI | P0 | ⬜ |
|
||
| 在线技能安装 | P0 | ⬜ |
|
||
| 技能配置界面 | P1 | ⬜ |
|
||
| 技能使用统计 | P2 | ⬜ |
|
||
| Linux 支持 | P2 | ⬜ |
|
||
|
||
---
|
||
|
||
#### 🚀 v2.0.0 - 重大升级
|
||
|
||
**目标**: 多 Agent / 高级功能
|
||
|
||
| 任务 | 优先级 | 状态 |
|
||
|------|--------|------|
|
||
| 多 Agent 支持 | P0 | ⬜ |
|
||
| 工作流编排 | P1 | ⬜ |
|
||
| 插件 SDK | P1 | ⬜ |
|
||
| 自定义主题 | P2 | ⬜ |
|
||
| 性能监控面板 | P2 | ⬜ |
|
||
|
||
---
|
||
|
||
## 五、开发规范
|
||
|
||
### 5.1 代码风格
|
||
|
||
```typescript
|
||
// ✅ 命名约定
|
||
const MY_CONSTANT = 'value'; // 常量: SCREAMING_SNAKE_CASE
|
||
function getUserData() {} // 函数: camelCase
|
||
class GatewayManager {} // 类: PascalCase
|
||
interface ChannelConfig {} // 接口: PascalCase
|
||
type StatusType = 'running'; // 类型: PascalCase
|
||
|
||
// ✅ 文件命名
|
||
// 组件: PascalCase.tsx
|
||
// Dashboard.tsx, SkillCard.tsx
|
||
|
||
// 工具/hooks: kebab-case.ts
|
||
// gateway-manager.ts, use-gateway.ts
|
||
|
||
// ✅ 目录命名
|
||
// kebab-case
|
||
// src/pages/skill-market/
|
||
|
||
// ✅ React 组件
|
||
export function SkillCard({ skill, onSelect }: SkillCardProps) {
|
||
// hooks 在顶部
|
||
const [loading, setLoading] = useState(false);
|
||
|
||
// handlers
|
||
const handleClick = () => { /* ... */ };
|
||
|
||
// render
|
||
return (
|
||
<Card onClick={handleClick}>
|
||
{/* ... */}
|
||
</Card>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 5.2 Git 提交规范
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
**Type**:
|
||
- `feat`: 新功能
|
||
- `fix`: Bug 修复
|
||
- `docs`: 文档
|
||
- `style`: 格式调整
|
||
- `refactor`: 重构
|
||
- `perf`: 性能优化
|
||
- `test`: 测试
|
||
- `chore`: 构建/工具
|
||
|
||
**示例**:
|
||
```
|
||
feat(setup): add Node.js auto-installer for Windows
|
||
|
||
- Detect existing Node.js installation
|
||
- Download and install via winget if missing
|
||
- Show progress indicator during installation
|
||
|
||
Closes #123
|
||
```
|
||
|
||
### 5.3 测试策略
|
||
|
||
```
|
||
/\
|
||
/ \ E2E 测试 (10%)
|
||
/ \ - Playwright
|
||
/──────\ - 完整用户流程
|
||
/ \ - CI 慢速运行
|
||
/──────────\ 集成测试 (20%)
|
||
/ \ - Gateway 通信
|
||
/ \ - IPC 调用
|
||
/────────────────\ 单元测试 (70%)
|
||
/ \ - Vitest
|
||
\ - 组件/函数
|
||
```
|
||
|
||
---
|
||
|
||
## 六、发布流程
|
||
|
||
### 6.1 发布清单
|
||
|
||
```bash
|
||
# 1. 版本更新
|
||
pnpm version <major|minor|patch>
|
||
|
||
# 2. 更新 Changelog
|
||
# 手动编辑 CHANGELOG.md
|
||
|
||
# 3. 构建检查
|
||
pnpm lint && pnpm test && pnpm build
|
||
|
||
# 4. 打包各平台
|
||
pnpm package:mac # macOS
|
||
pnpm package:win # Windows
|
||
pnpm package:linux # Linux
|
||
|
||
# 5. 签名 & 公证 (macOS)
|
||
pnpm notarize
|
||
|
||
# 6. 创建 Release
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
# GitHub Actions 自动发布
|
||
```
|
||
|
||
### 6.2 更新通道
|
||
|
||
| 通道 | 用途 | 更新频率 |
|
||
|------|------|----------|
|
||
| `stable` | 正式版 | 每月/按需 |
|
||
| `beta` | 测试版 | 每周 |
|
||
| `dev` | 开发版 | 每次提交 |
|
||
|
||
---
|
||
|
||
## 七、附录
|
||
|
||
### 7.1 参考资源
|
||
|
||
| 资源 | 链接 |
|
||
|------|------|
|
||
| OpenClaw 仓库 | https://github.com/openclaw/openclaw |
|
||
| OpenClaw 文档 | https://docs.openclaw.ai |
|
||
| Electron 文档 | https://www.electronjs.org/docs |
|
||
| shadcn/ui | https://ui.shadcn.com |
|
||
| Tailwind CSS | https://tailwindcss.com |
|
||
|
||
### 7.2 环境变量
|
||
|
||
```bash
|
||
# .env.example
|
||
|
||
# OpenClaw 配置
|
||
OPENCLAW_GATEWAY_PORT=18789
|
||
|
||
# 开发配置
|
||
VITE_DEV_SERVER_PORT=5173
|
||
|
||
# 发布配置 (CI)
|
||
APPLE_ID=your@email.com
|
||
APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
|
||
CSC_LINK=path/to/certificate.p12
|
||
CSC_KEY_PASSWORD=certificate_password
|
||
GH_TOKEN=github_personal_access_token
|
||
```
|
||
|
||
### 7.3 常用命令
|
||
|
||
```bash
|
||
# 开发
|
||
pnpm dev # 启动开发服务器
|
||
pnpm dev:main # 仅启动 Electron 主进程
|
||
pnpm dev:renderer # 仅启动 React 开发服务器
|
||
|
||
# 构建
|
||
pnpm build # 构建生产版本
|
||
pnpm build:main # 构建主进程
|
||
pnpm build:renderer # 构建渲染进程
|
||
|
||
# 打包
|
||
pnpm package # 打包当前平台
|
||
pnpm package:mac # 打包 macOS
|
||
pnpm package:win # 打包 Windows
|
||
pnpm package:linux # 打包 Linux
|
||
pnpm package:all # 打包所有平台
|
||
|
||
# 测试
|
||
pnpm test # 运行单元测试
|
||
pnpm test:e2e # 运行 E2E 测试
|
||
pnpm test:coverage # 生成覆盖率报告
|
||
|
||
# 代码质量
|
||
pnpm lint # 检查代码规范
|
||
pnpm lint:fix # 自动修复
|
||
pnpm typecheck # TypeScript 类型检查
|
||
```
|
||
|
||
---
|