diff --git a/ClawX-项目架构与版本大纲.md b/ClawX-项目架构与版本大纲.md index 386056288..1ec2a4e7c 100644 --- a/ClawX-项目架构与版本大纲.md +++ b/ClawX-项目架构与版本大纲.md @@ -63,7 +63,7 @@ - ✅ **版本绑定** - 每个 ClawX 版本绑定特定 openclaw 版本 - ✅ **CLI 兼容** - 命令行保持 `openclaw` 命令，不引入 `clawx` CLI -openclaw project Local: /Users/guoyuliang/Project/openclaw remote: https://github.com/openclaw/openclaw +openclaw project remote: https://github.com/openclaw/openclaw ### 1.4 CLI 兼容性设计 ClawX 是 OpenClaw 的**图形化增强层**，而非替代品。用户可以同时使用 GUI 和 CLI： diff --git a/build_process/commit_0_init_project.md b/build_process/commit_0_init_project.md deleted file mode 100644 index 4a316b39b..000000000 --- a/build_process/commit_0_init_project.md +++ /dev/null @@ -1 +0,0 @@ -add `ClawX-项目架构与版本大纲.md` and init project. \ No newline at end of file diff --git a/build_process/commit_10_cron_tasks.md b/build_process/commit_10_cron_tasks.md deleted file mode 100644 index 6cac6abb5..000000000 --- a/build_process/commit_10_cron_tasks.md +++ /dev/null @@ -1,155 +0,0 @@ -# Commit 10: Cron Tasks Management - -## Summary -Enhance the Cron tasks page with a create/edit dialog, schedule presets, human-readable cron parsing, and improved job cards with better UX. - -## Changes - -### React Renderer - -#### `src/pages/Cron/index.tsx` -Complete rewrite with enhanced features: - -**New Components:** -- `TaskDialog` - Create/edit scheduled task modal -- `CronJobCard` - Enhanced job display with actions - -**Features:** -- Schedule presets (every minute, hourly, daily, weekly, monthly) -- Custom cron expression input -- Channel selection for task targets -- Human-readable cron schedule parsing -- Run now functionality with loading state -- Delete confirmation -- Gateway connection status awareness -- Failed tasks counter in statistics -- Error display for last run failures - -**UI Improvements:** -- Message preview in job cards -- Status-aware card borders -- Last run success/failure indicators -- Next run countdown -- Action buttons with labels -- Responsive statistics grid - -### Data Structures - -#### Schedule Presets -```typescript -const schedulePresets = [ - { label: 'Every minute', value: '* * * * *', type: 'interval' }, - { label: 'Every 5 minutes', value: '*/5 * * * *', type: 'interval' }, - { label: 'Every 15 minutes', value: '*/15 * * * *', type: 'interval' }, - { label: 'Every hour', value: '0 * * * *', type: 'interval' }, - { label: 'Daily at 9am', value: '0 9 * * *', type: 'daily' }, - { label: 'Daily at 6pm', value: '0 18 * * *', type: 'daily' }, - { label: 'Weekly (Mon 9am)', value: '0 9 * * 1', type: 'weekly' }, - { label: 'Monthly (1st at 9am)', value: '0 9 1 * *', type: 'monthly' }, -]; -``` - -## Technical Details - -### Component Architecture - -``` -Cron Page - | - +-- Header (title, refresh, new task button) - | - +-- Gateway Warning (if not running) - | - +-- Statistics Grid - | | - | +-- Total Tasks - | +-- Active Tasks - | +-- Paused Tasks - | +-- Failed Tasks - | - +-- Error Display (if any) - | - +-- Jobs List - | | - | +-- CronJobCard (for each job) - | | - | +-- Header (name, schedule, status toggle) - | +-- Message Preview - | +-- Metadata (channel, last run, next run) - | +-- Error Display (if last run failed) - | +-- Actions (run, edit, delete) - | - +-- TaskDialog (modal) - | - +-- Name Input - +-- Message/Prompt Textarea - +-- Schedule Presets / Custom Cron - +-- Channel Selection - +-- Enable Toggle - +-- Save/Cancel Actions -``` - -### Cron Parsing Logic - -```typescript -function parseCronSchedule(cron: string): string { - // Check against presets first - const preset = schedulePresets.find((p) => p.value === cron); - if (preset) return preset.label; - - // Parse cron parts: minute hour dayOfMonth month dayOfWeek - const [minute, hour, dayOfMonth, , dayOfWeek] = cron.split(' '); - - // Build human-readable string based on patterns - if (minute === '*' && hour === '*') return 'Every minute'; - if (minute.startsWith('*/')) return `Every ${minute.slice(2)} minutes`; - if (dayOfWeek !== '*') return `Weekly on ${day} at ${time}`; - if (dayOfMonth !== '*') return `Monthly on day ${dayOfMonth} at ${time}`; - if (hour !== '*') return `Daily at ${time}`; - - return cron; // Fallback to raw expression -} -``` - -### State Management - -**Local State:** -- `showDialog` - Dialog visibility -- `editingJob` - Job being edited (undefined for create) -- `triggering` - Run now loading state per card - -**Store Integration:** -- `useCronStore` - Jobs data and CRUD actions -- `useChannelsStore` - Available channels for targets -- `useGatewayStore` - Connection status - -### Form Validation - -**Required Fields:** -- Task name (non-empty string) -- Message/prompt (non-empty string) -- Schedule (preset or valid cron expression) -- Target channel (selected from available channels) - -### Statistics Calculation - -```typescript -const activeJobs = jobs.filter((j) => j.enabled); -const pausedJobs = jobs.filter((j) => !j.enabled); -const failedJobs = jobs.filter((j) => j.lastRun && !j.lastRun.success); -``` - -## UI States - -**Job Card:** -- Active: Green border, green clock icon -- Paused: Neutral border, muted clock icon -- Failed: Shows error message with red background - -**Task Dialog:** -- Create mode: Empty form, "Create Task" button -- Edit mode: Pre-filled form, "Save Changes" button -- Saving: Disabled inputs, loading spinner - -## Version -v0.1.0-alpha (final feature) diff --git a/build_process/commit_11_openclaw_submodule_fix.md b/build_process/commit_11_openclaw_submodule_fix.md deleted file mode 100644 index c88a76a53..000000000 --- a/build_process/commit_11_openclaw_submodule_fix.md +++ /dev/null @@ -1,95 +0,0 @@ -# Commit 11: Fix OpenClaw Submodule Integration - -## Overview - -Fixed the OpenClaw submodule configuration to use the official GitHub repository instead of a local path, and added automatic token generation for gateway authentication. - -## Changes Made - -### 1. Fixed Submodule URL - -Updated `.gitmodules` to point to the official GitHub repository: - -**Before:** -``` -[submodule "openclaw"] - path = openclaw - url = /Users/guoyuliang/Project/openclaw -``` - -**After:** -``` -[submodule "openclaw"] - path = openclaw - url = https://github.com/openclaw/openclaw.git -``` - -Checked out stable version `v2026.2.3`. - -### 2. Added Gateway Token Management - -**electron/utils/store.ts:** -- Added `gatewayToken` to `AppSettings` interface -- Added `generateToken()` function to create random tokens (`clawx-xxxxxxxxxxxx`) -- Token is auto-generated on first launch and persisted - -### 3. Updated Gateway Manager - -**electron/gateway/manager.ts:** -- Import `getSetting` from store -- Get or generate gateway token on startup -- Pass `--token` argument when spawning gateway process -- Set `OPENCLAW_GATEWAY_TOKEN` environment variable -- Include token in WebSocket URL for authentication (`?auth=token`) -- Added `--dev` and `--allow-unconfigured` flags for first-time setup - -## Technical Details - -### Token Flow - -``` -┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ ClawX Start │────▶│ Get/Generate │────▶│ Store Token │ -│ │ │ Token │ │ (electron- │ -│ │ │ │ │ store) │ -└─────────────────┘ └─────────────────┘ └─────────────────┘ - │ - ▼ -┌─────────────────┐ ┌─────────────────┐ -│ Start Gateway │────▶│ Connect WS │ -│ --token xxx │ │ ?auth=xxx │ -└─────────────────┘ └─────────────────┘ -``` - -### Gateway Startup Command - -**Production mode:** -```bash -node openclaw.mjs gateway run --port 18789 --token --dev --allow-unconfigured -``` - -**Development mode:** -```bash -pnpm run dev gateway run --port 18789 --token --dev --allow-unconfigured -``` - -### Environment Variables - -- `OPENCLAW_GATEWAY_TOKEN`: Gateway authentication token -- `OPENCLAW_SKIP_CHANNELS`: Skip channel auto-connect (faster startup) -- `CLAWDBOT_SKIP_CHANNELS`: Legacy skip channels flag - -## Files Modified - -| File | Changes | -|------|---------| -| `.gitmodules` | Updated URL to GitHub repo | -| `openclaw` | Submodule updated to v2026.2.3 | -| `electron/utils/store.ts` | Added gatewayToken setting and generateToken() | -| `electron/gateway/manager.ts` | Token auth for process and WebSocket | - -## Result - -- Gateway starts successfully with auto-generated token -- WebSocket connection authenticated properly -- No manual configuration required for first-time users diff --git a/build_process/commit_12_api_key_validation.md b/build_process/commit_12_api_key_validation.md deleted file mode 100644 index 65d1b7fc3..000000000 --- a/build_process/commit_12_api_key_validation.md +++ /dev/null @@ -1,87 +0,0 @@ -# Commit 12: Real API Key Validation & OpenRouter Support - -## Overview -Implemented real API key validation by making actual API calls to each provider, replacing the mock validation. Also added OpenRouter as a new provider option. - -## Changes - -### 1. Real API Key Validation (`electron/main/ipc-handlers.ts`) - -**Before**: Mock validation that only checked key format (e.g., `apiKey.startsWith('sk-ant-')`) - -**After**: Real API validation that sends a minimal chat completion request to verify the key works - -#### New Functions Added: -- `validateApiKeyWithProvider(providerType, apiKey)` - Routes to provider-specific validation -- `validateAnthropicKey(apiKey)` - Calls Anthropic `/v1/messages` endpoint -- `validateOpenAIKey(apiKey)` - Calls OpenAI `/v1/chat/completions` endpoint -- `validateGoogleKey(apiKey)` - Calls Google Gemini `generateContent` endpoint -- `validateOpenRouterKey(apiKey)` - Calls OpenRouter `/api/v1/chat/completions` endpoint -- `parseApiError(data)` - Extracts user-friendly error messages from API responses - -#### Validation Logic: -- Sends minimal request with `max_tokens: 1` and message "hi" -- HTTP 200: Key is valid -- HTTP 401/403: Invalid API key -- HTTP 429: Rate limited but key is valid -- HTTP 402 (OpenRouter): No credits but key is valid -- HTTP 400/404: Check error message for auth vs model issues - -#### Error Handling: -- Returns user-friendly "Invalid API key" instead of raw API errors like "User not found." - -### 2. Setup Page Real Validation (`src/pages/Setup/index.tsx`) - -**Before**: -```typescript -// Mock validation -await new Promise((resolve) => setTimeout(resolve, 1500)); -const isValid = apiKey.length > 10; -``` - -**After**: -```typescript -// Real API validation via IPC -const result = await window.electron.ipcRenderer.invoke( - 'provider:validateKey', - selectedProvider, - apiKey -); -``` - -### 3. OpenRouter Provider Support - -Added OpenRouter to: -- `src/pages/Setup/index.tsx` - Provider selection in setup wizard -- `src/components/settings/ProvidersSettings.tsx` - Provider settings panel -- `electron/utils/secure-storage.ts` - ProviderConfig type -- `src/stores/providers.ts` - ProviderConfig type - -### 4. IPC Handler Improvement - -Modified `provider:validateKey` handler to accept provider type directly: -- During setup, provider may not exist in storage yet -- Falls back to using `providerId` as the provider type -- Enables validation before provider is saved - -## Files Changed -- `electron/main/ipc-handlers.ts` - Real API validation implementation (+300 lines) -- `src/pages/Setup/index.tsx` - Real validation call, OpenRouter option -- `src/components/settings/ProvidersSettings.tsx` - OpenRouter option -- `electron/utils/secure-storage.ts` - OpenRouter type -- `src/stores/providers.ts` - OpenRouter type - -## API Endpoints Used -| Provider | Endpoint | Model | -|----------|----------|-------| -| Anthropic | `https://api.anthropic.com/v1/messages` | claude-3-haiku-20240307 | -| OpenAI | `https://api.openai.com/v1/chat/completions` | gpt-4o-mini | -| Google | `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent` | gemini-2.0-flash | -| OpenRouter | `https://openrouter.ai/api/v1/chat/completions` | meta-llama/llama-3.2-3b-instruct:free | - -## Testing -1. Select OpenRouter in setup wizard -2. Enter an invalid API key (e.g., "asdasfdsadf") -3. Click Validate - should show "Invalid API key" -4. Enter a valid API key -5. Click Validate - should show "API key validated successfully" diff --git a/build_process/commit_13_remove_channel_setup.md b/build_process/commit_13_remove_channel_setup.md deleted file mode 100644 index cd5bf84b2..000000000 --- a/build_process/commit_13_remove_channel_setup.md +++ /dev/null @@ -1,67 +0,0 @@ -# Commit 13: Remove Channel Setup Step - -## Overview -Simplified the setup wizard by removing the channel connection step. Users can now start using ClawX immediately and configure messaging channels later in Settings. - -## Rationale -- Channel connection (WhatsApp, Telegram, etc.) is complex and requires external platform configuration -- Not required for core functionality - users can use the built-in chat interface directly -- Reduces onboarding friction for new users -- Progressive disclosure - advanced features available when needed - -## Changes - -### 1. Setup Wizard (`src/pages/Setup/index.tsx`) - -**Steps reduced from 6 to 5:** - -| Before | After | -|--------|-------| -| 0: Welcome | 0: Welcome | -| 1: Runtime | 1: Runtime | -| 2: Provider | 2: Provider | -| 3: Channel | (removed) | -| 4: Skills | 3: Skills | -| 5: Complete | 4: Complete | - -**Code changes:** -- Removed `channel` step from `steps` array -- Updated `currentStep` indices for content rendering -- Updated `useEffect` for `canProceed` validation -- Removed `selectedChannel` state variable -- Removed `ChannelContent` component and `Channel` interface -- Updated `CompleteContent` to remove channel row -- Added note about configuring channels in Settings - -### 2. Architecture Document (`ClawX-项目架构与版本大纲.md`) - -- Updated section 2.4.2 setup wizard steps (removed ChannelStep) -- Updated directory structure (added ChannelsSettings.tsx to Settings, removed ChannelStep.tsx) -- Updated v0.5.0 milestone to note channel connection is deferred - -## User Experience - -**Before:** -``` -Welcome → Runtime → Provider → Channel → Skills → Complete - ↑ - (complex, often skipped) -``` - -**After:** -``` -Welcome → Runtime → Provider → Skills → Complete - ↓ - "Configure channels in Settings" -``` - -## Files Changed -- `src/pages/Setup/index.tsx` - Removed channel step (-140 lines) -- `ClawX-项目架构与版本大纲.md` - Updated documentation - -## Future Work -- Implement Settings > Channels page with: - - WhatsApp QR code scanning - - Telegram bot token configuration - - Discord/Slack OAuth flows - - Connection status indicators diff --git a/build_process/commit_14_auto_install_skills.md b/build_process/commit_14_auto_install_skills.md deleted file mode 100644 index 0d766452f..000000000 --- a/build_process/commit_14_auto_install_skills.md +++ /dev/null @@ -1,105 +0,0 @@ -# Commit 14: Auto-Install Skills Step - -## Summary - -Replaced the manual "Skills" selection step in the setup wizard with an automatic "Installing" step that installs essential components with real-time progress feedback. - -## Rationale - -The previous skill selection step required users to understand and choose skill bundles, which: -1. **Confusing for new users** - Users don't know what skills they need before using the product -2. **Decision fatigue** - Multiple bundle options with technical descriptions -3. **Unnecessary friction** - Delays getting users to the actual product experience - -The new approach: -- **Auto-installs essential components** - Python environment, OpenCode, file tools, terminal -- **Shows real-time progress** - Users see exactly what's being installed -- **No extra API keys required** - Only installs components that work out-of-the-box -- **Defers customization** - Users can add more skills later in Settings - -## Changes - -### Modified Files - -#### `src/pages/Setup/index.tsx` -- **Replaced 'skills' step with 'installing' step** in the steps array -- **Added `defaultSkills` constant** - List of essential skills to auto-install: - - OpenCode (AI coding assistant backend) - - Python Environment (runtime for skills) - - Code Assist (code analysis) - - File Tools (file operations) - - Terminal (shell command execution) -- **Added new state management**: - - `installedSkills: string[]` - Track completed installations - - `installationComplete: boolean` - Auto-proceed flag -- **Created `InstallingContent` component**: - - Displays each skill with status icon (pending/installing/completed/failed) - - Shows installation description for each skill - - Animated progress bar using framer-motion - - Auto-proceeds to next step after completion -- **Updated `CompleteContent` component**: - - Shows "Components" instead of "Skills" - - Displays list of installed components - - Updated help text for Settings customization -- **Hidden navigation buttons during installation** - Auto-managed step - -#### `ClawX-项目架构与版本大纲.md` -- Updated section 2.4.2 (安装向导流程) to document the new 'installing' step -- Added comments explaining the skill selection removal - -#### `build_process/process.md` -- Added commit_14 entry -- Updated summary to include auto-install feature - -### Component Architecture - -```typescript -// InstallingContent component flow -InstallingContent - ├── State: skillStates (pending | installing | completed | failed) - ├── useEffect: Simulates sequential installation - │ ├── Set skill to 'installing' - │ ├── Wait 800-1500ms (simulated install time) - │ ├── Set skill to 'completed' (90% success) or 'failed' (10%) - │ └── Move to next skill - ├── Calls onComplete when all done - └── Renders: - ├── Skill list with status icons - ├── Progress bar (animated) - └── Status message -``` - -## UI Preview - -``` -┌─────────────────────────────────────────┐ -│ Installing Components... │ -│ │ -│ ✓ OpenCode AI coding assistant │ -│ ✓ Python Env. Python runtime │ -│ ○ Code Assist Installing... │ -│ ○ File Tools Waiting... │ -│ ○ Terminal Waiting... │ -│ │ -│ ████████████░░░░░░░░░░░ 60% │ -│ │ -│ Installing Code Assist... │ -└─────────────────────────────────────────┘ -``` - -## User Experience Impact - -| Before | After | -|--------|-------| -| Manual skill bundle selection | Automatic installation | -| Confusing technical options | Clear progress feedback | -| User must make decisions | Zero decisions required | -| Can skip/miss important skills | Essential skills guaranteed | -| 5-step wizard | 5-step wizard (smoother) | - -## Future Considerations - -1. **Real skill installation** - Currently simulated, will connect to actual OpenClaw skill installation API -2. **Error recovery** - Add retry mechanism for failed installations -3. **Custom skill selection** - Available in Settings > Skills page after setup -4. **Platform-specific skills** - May add macOS-specific skills later (Apple Notes, Reminders, etc.) diff --git a/build_process/commit_15_gateway_ws_handshake.md b/build_process/commit_15_gateway_ws_handshake.md deleted file mode 100644 index daaa1a873..000000000 --- a/build_process/commit_15_gateway_ws_handshake.md +++ /dev/null @@ -1,92 +0,0 @@ -# Commit 15: Fix Gateway WebSocket Handshake - -## Summary - -Fixed the Gateway WebSocket connection instability by implementing the proper OpenClaw WebSocket handshake protocol. - -## Problem - -The Gateway connection was failing with errors like: -- `token_mismatch` - Authentication failing despite correct tokens -- `invalid handshake: first request must be connect` - Missing handshake -- Repeated connect/disconnect cycles - -Root causes: -1. ClawX was not sending the required `connect` handshake message after WebSocket opens -2. Using standard JSON-RPC 2.0 format instead of OpenClaw's custom protocol format -3. Config file had hardcoded token overriding CLI arguments - -## Solution - -### 1. Implement Proper Connect Handshake - -After WebSocket opens, send a proper connect request: - -```typescript -const connectFrame = { - type: 'req', // OpenClaw uses 'req' not 'jsonrpc: 2.0' - id: connectId, - method: 'connect', - params: { - minProtocol: 3, - maxProtocol: 3, - client: { - id: 'gateway-client', - displayName: 'ClawX', - version: '0.1.0', - platform: process.platform, - mode: 'ui', - }, - auth: { - token: gatewayToken, - }, - caps: [], - role: 'operator', - scopes: [], - }, -}; -``` - -### 2. Handle OpenClaw Protocol Format - -OpenClaw Gateway uses a custom protocol format: -- Request: `{ type: "req", id, method, params }` -- Response: `{ type: "res", id, ok, payload, error }` -- Event: `{ type: "event", event, payload }` - -Updated `handleMessage` to parse these formats correctly. - -### 3. Remove Hardcoded Config Token - -The `~/.openclaw/openclaw.json` file had a hardcoded token that was overriding the CLI token. Updated to remove the auth.token field so the environment variable takes precedence. - -## Files Changed - -### `electron/gateway/manager.ts` -- **connect()**: Added proper handshake flow with connect request -- **handleMessage()**: Parse OpenClaw protocol response/event formats -- **handleProtocolEvent()**: New method to handle OpenClaw events -- **rpc()**: Use OpenClaw request format `{ type: "req" }` - -## Protocol Flow - -``` -Before (broken): - 1. Open WebSocket - 2. Immediately mark as "running" ❌ - 3. Send RPC requests (rejected - no handshake) - -After (fixed): - 1. Open WebSocket - 2. Send connect handshake with auth token - 3. Wait for response { type: "res", ok: true } - 4. Mark as "running" ✓ - 5. Send RPC requests (accepted) -``` - -## Testing - -After this fix: -- Gateway connects successfully -- WebSocket stays connected without constant reconnection -- RPC calls work correctly diff --git a/build_process/commit_1_project_skeleton.md b/build_process/commit_1_project_skeleton.md deleted file mode 100644 index 997a3c0e1..000000000 --- a/build_process/commit_1_project_skeleton.md +++ /dev/null @@ -1,108 +0,0 @@ -# Commit 1: Project Skeleton - -## Summary -Initialize the ClawX project with Electron + React + TypeScript architecture, including all foundational components for v0.1.0 Alpha. - -## Changes - -### Project Configuration -- `package.json` - Project dependencies and scripts -- `tsconfig.json` / `tsconfig.node.json` - TypeScript configuration -- `vite.config.ts` - Vite bundler configuration with Electron plugins -- `tailwind.config.js` / `postcss.config.js` - Tailwind CSS setup -- `electron-builder.yml` - Multi-platform packaging configuration -- `.eslintrc.cjs` / `.prettierrc` - Code style configuration -- `vitest.config.ts` - Test framework configuration -- `.gitignore` / `.env.example` - Git and environment setup - -### Electron Main Process (`electron/`) -- `main/index.ts` - Main process entry point -- `main/window.ts` - Window state management -- `main/tray.ts` - System tray functionality -- `main/menu.ts` - Application menu -- `main/ipc-handlers.ts` - IPC communication handlers -- `gateway/manager.ts` - Gateway process lifecycle management -- `gateway/client.ts` - Typed Gateway RPC client -- `gateway/protocol.ts` - JSON-RPC protocol definitions -- `preload/index.ts` - Context bridge for renderer -- `utils/config.ts` - Configuration constants -- `utils/logger.ts` - Logging utility -- `utils/paths.ts` - Path resolution helpers -- `utils/store.ts` - Persistent storage - -### React Renderer (`src/`) -- `main.tsx` / `App.tsx` - Application entry and root component -- `styles/globals.css` - Global styles with CSS variables - -#### Components -- `components/ui/` - shadcn/ui base components (Button, Card, Input, Badge, etc.) -- `components/layout/MainLayout.tsx` - Main application layout -- `components/layout/Sidebar.tsx` - Navigation sidebar -- `components/layout/Header.tsx` - Top header bar -- `components/common/` - Common components (LoadingSpinner, StatusBadge, ErrorBoundary) - -#### Pages -- `pages/Dashboard/index.tsx` - Overview dashboard -- `pages/Chat/index.tsx` - Chat interface -- `pages/Channels/index.tsx` - Channel management -- `pages/Skills/index.tsx` - Skill browser -- `pages/Cron/index.tsx` - Scheduled tasks -- `pages/Settings/index.tsx` - Application settings -- `pages/Setup/index.tsx` - First-run setup wizard - -#### State Management -- `stores/gateway.ts` - Gateway connection state -- `stores/settings.ts` - Application settings -- `stores/channels.ts` - Channel data -- `stores/skills.ts` - Skills data -- `stores/chat.ts` - Chat messages -- `stores/cron.ts` - Cron jobs - -#### Types -- `types/electron.d.ts` - Electron API types -- `types/gateway.ts` - Gateway types -- `types/channel.ts` - Channel types -- `types/skill.ts` - Skill types -- `types/cron.ts` - Cron job types - -### Resources -- `resources/icons/.gitkeep` - Placeholder for app icons -- `resources/skills/bundles.json` - Predefined skill bundles - -### Tests -- `tests/setup.ts` - Test environment setup -- `tests/unit/utils.test.ts` - Utility function tests -- `tests/unit/stores.test.ts` - Store tests - -## Technical Details - -### Architecture Decisions -1. **Vite + Electron**: Using vite-plugin-electron for fast HMR during development -2. **Context Isolation**: All IPC communication through preload script with strict channel validation -3. **Zustand Stores**: Lightweight state management with persistence support -4. **shadcn/ui**: Customizable, accessible UI components based on Radix primitives -5. **Dual-port Architecture**: Separate ports for GUI (23333) and Gateway (18789) - -### Key Features Implemented -- ✅ Electron main process with window management -- ✅ System tray integration -- ✅ Gateway process lifecycle management -- ✅ WebSocket communication layer -- ✅ JSON-RPC protocol support -- ✅ React router with all main pages -- ✅ Zustand state management -- ✅ Dark/Light theme support -- ✅ Responsive sidebar navigation -- ✅ Setup wizard flow -- ✅ Unit test setup with Vitest - -## Version -v0.1.0-alpha - -## Dependencies -- Electron 33.3.0 -- React 19.0.0 -- TypeScript 5.7.2 -- Vite 6.0.6 -- Zustand 5.0.2 -- Tailwind CSS 3.4.17 diff --git a/build_process/commit_2_gateway_refinements.md b/build_process/commit_2_gateway_refinements.md deleted file mode 100644 index 289f8b722..000000000 --- a/build_process/commit_2_gateway_refinements.md +++ /dev/null @@ -1,83 +0,0 @@ -# Commit 2: Gateway Refinements - -## Summary -Enhance Gateway process management with auto-reconnection, health checks, and improved state management for more robust WebSocket communication. - -## Changes - -### Electron Main Process - -#### `electron/gateway/manager.ts` -- Added `'reconnecting'` state to `GatewayStatus` -- Implemented `ReconnectConfig` with exponential backoff strategy -- Added `maxAttempts`, `baseDelay`, `maxDelay` configuration -- New methods: - - `isConnected()` - Check WebSocket connection status - - `restart()` - Stop and start Gateway - - `clearAllTimers()` - Clean up timers on shutdown - - `startHealthCheck()` - Periodic health monitoring - - `checkHealth()` - Manual health check -- Enhanced `handleMessage()` to dispatch JSON-RPC responses and notifications -- Expanded `GatewayManagerEvents` for notification forwarding - -#### `electron/gateway/client.ts` -- Extended with new interfaces: `SkillBundle`, `CronTask`, `ProviderConfig` -- Added cron task management methods: - - `listCronTasks()`, `createCronTask()`, `updateCronTask()`, `deleteCronTask()`, `runCronTask()` -- Added provider management methods: - - `listProviders()`, `setProvider()`, `removeProvider()`, `testProvider()` -- Enhanced system calls: - - `getHealth()` now includes `version` - - Added `getVersion()`, `getSkillBundles()`, `installBundle()` - -#### `electron/main/ipc-handlers.ts` -- Added `gateway:isConnected`, `gateway:health` IPC handlers -- Added `mainWindow.isDestroyed()` checks before sending events -- Forward new gateway events: `gateway:notification`, `gateway:channel-status`, `gateway:chat-message` - -#### `electron/preload/index.ts` -- Added new IPC channels for gateway operations -- Added notification event channels - -### React Renderer - -#### `src/stores/gateway.ts` -- Added `health: GatewayHealth | null`, `lastError: string | null` to state -- Added `checkHealth()`, `rpc()`, `clearError()` actions -- Enhanced `init()` to listen for error and notification events - -#### `src/types/gateway.ts` -- Added `'reconnecting'` to `GatewayStatus` state enum -- Added `version`, `reconnectAttempts` fields -- New interfaces: `GatewayHealth`, `GatewayNotification`, `ProviderConfig` - -#### `src/components/common/StatusBadge.tsx` -- Added `'reconnecting'` status with warning variant - -## Technical Details - -### Reconnection Strategy -- Exponential backoff: `delay = min(baseDelay * 2^attempt, maxDelay)` -- Default: 1s base delay, 30s max delay, 10 max attempts -- Automatic reconnection on unexpected disconnection -- Manual control via `shouldReconnect` flag - -### Health Check -- Periodic ping/pong via JSON-RPC `system.health` -- Returns status, uptime, version information -- Triggers reconnection on consecutive failures - -### Event Flow -``` -Gateway Process -> WebSocket -> GatewayManager -> IPC -> Renderer - | - v - Event Emitter - | - +---------------+---------------+ - | | | - status notification channel:status -``` - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_3_setup_wizard.md b/build_process/commit_3_setup_wizard.md deleted file mode 100644 index e69582f72..000000000 --- a/build_process/commit_3_setup_wizard.md +++ /dev/null @@ -1,88 +0,0 @@ -# Commit 3: Setup Wizard - -## Summary -Implement a functional multi-step setup wizard for first-run user onboarding, guiding users through environment checks, AI provider configuration, channel connection, and skill selection. - -## Changes - -### React Renderer - -#### `src/pages/Setup/index.tsx` -Complete rewrite with functional implementation: -- **Step 0: Welcome** - Introduction to ClawX -- **Step 1: Runtime Check** - Verify Node.js, OpenClaw, and Gateway status -- **Step 2: Provider Configuration** - Select AI provider and enter API key -- **Step 3: Channel Connection** - Choose messaging channel (WhatsApp, Telegram, etc.) -- **Step 4: Skill Selection** - Toggle predefined skill bundles -- **Step 5: Complete** - Summary of configuration - -New components: -- `WelcomeContent` - Welcome message and features overview -- `RuntimeContent` - Environment checks with real Gateway status -- `ProviderContent` - Provider selection with API key input and validation -- `ChannelContent` - Channel type selection with QR code placeholder -- `SkillsContent` - Skill bundle toggles -- `CompleteContent` - Configuration summary - -Features: -- Animated transitions using Framer Motion -- Progress indicator with step navigation -- Dynamic `canProceed` state based on step requirements -- API key visibility toggle -- Simulated API key validation - -#### `src/stores/settings.ts` -- Added `setupComplete: boolean` to state -- Added `markSetupComplete()` action -- Setup status persisted via Zustand persist middleware - -#### `src/App.tsx` -- Added `useLocation` for route tracking -- Added redirect logic: if `setupComplete` is false, navigate to `/setup` -- Fixed `handleNavigate` callback signature for IPC events - -## Technical Details - -### Setup Flow -``` -Welcome -> Runtime -> Provider -> Channel -> Skills -> Complete - | | | | | | - v v v v v v - [Skip] [Check] [Validate] [Select] [Toggle] [Finish] - | | | | | | - +---------+----------+----------+----------+----------+ - | - markSetupComplete() - | - Navigate to / -``` - -### Provider Types -- Anthropic (Claude) - API key starts with `sk-ant-` -- OpenAI (GPT) - API key starts with `sk-` -- Google (Gemini) - Length validation -- Ollama (Local) - No API key required -- Custom - Configurable base URL - -### Channel Types -- WhatsApp - QR code connection -- Telegram - Bot token -- Discord - Bot token -- Slack - OAuth/Bot token -- WeChat - QR code connection - -### Skill Bundles -- Productivity - Calendar, reminders, notes -- Developer - Code assistance, git operations -- Information - Web search, news, weather -- Entertainment - Music, games, trivia - -## UI/UX Features -- Gradient background with glassmorphism cards -- Step progress dots with completion indicators -- Animated page transitions -- Back/Skip/Next navigation -- Toast notifications on completion - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_4_provider_configuration.md b/build_process/commit_4_provider_configuration.md deleted file mode 100644 index 0e5adde97..000000000 --- a/build_process/commit_4_provider_configuration.md +++ /dev/null @@ -1,127 +0,0 @@ -# Commit 4: Provider Configuration - -## Summary -Implement secure API key storage using Electron's safeStorage API and create a comprehensive provider management UI for configuring AI model providers. - -## Changes - -### Electron Main Process - -#### `electron/utils/secure-storage.ts` (New) -Secure storage utility using Electron's safeStorage: -- `isEncryptionAvailable()` - Check if system keychain is available -- `storeApiKey(providerId, apiKey)` - Encrypt and store API key -- `getApiKey(providerId)` - Decrypt and retrieve API key -- `deleteApiKey(providerId)` - Remove stored API key -- `hasApiKey(providerId)` - Check if key exists -- `listStoredKeyIds()` - List all stored provider IDs - -Provider configuration management: -- `saveProvider(config)` - Save provider configuration -- `getProvider(providerId)` - Get single provider -- `getAllProviders()` - Get all providers -- `deleteProvider(providerId)` - Delete provider and key -- `setDefaultProvider(providerId)` - Set default provider -- `getDefaultProvider()` - Get default provider ID -- `getProviderWithKeyInfo(providerId)` - Get provider with masked key -- `getAllProvidersWithKeyInfo()` - Get all providers with key info - -Note: Uses dynamic `import('electron-store')` for ESM compatibility. - -#### `electron/main/ipc-handlers.ts` -New `registerProviderHandlers()` function with IPC handlers: -- `provider:encryptionAvailable` -- `provider:list` / `provider:get` / `provider:save` / `provider:delete` -- `provider:setApiKey` / `provider:deleteApiKey` / `provider:hasApiKey` / `provider:getApiKey` -- `provider:setDefault` / `provider:getDefault` -- `provider:validateKey` - Basic format validation - -#### `electron/preload/index.ts` -Added all provider IPC channels to valid channels list. - -### React Renderer - -#### `src/stores/providers.ts` (New) -Zustand store for provider management: -- State: `providers`, `defaultProviderId`, `loading`, `error` -- Actions: `fetchProviders`, `addProvider`, `updateProvider`, `deleteProvider` -- Actions: `setApiKey`, `deleteApiKey`, `setDefaultProvider`, `validateApiKey`, `getApiKey` - -#### `src/components/settings/ProvidersSettings.tsx` (New) -Provider management UI component: -- `ProvidersSettings` - Main component orchestrating provider list -- `ProviderCard` - Individual provider display with actions -- `AddProviderDialog` - Modal for adding new providers - -Features: -- Provider type icons (Anthropic, OpenAI, Google, Ollama, Custom) -- Masked API key display (first 4 + last 4 characters) -- Set default provider -- Enable/disable providers -- Edit/delete functionality -- API key validation on add - -#### `src/pages/Settings/index.tsx` -- Added AI Providers section with `ProvidersSettings` component -- Added `Key` icon import - -## Technical Details - -### Security Architecture -``` -Renderer Process Main Process - | | - | provider:setApiKey | - |--------------------------------->| - | | safeStorage.encryptString() - | | | - | | v - | | System Keychain - | | | - | | electron-store - | | (encrypted base64) - | | - | provider:getApiKey | - |--------------------------------->| - | | safeStorage.decryptString() - |<---------------------------------| - | (plaintext) | -``` - -### Provider Configuration Schema -```typescript -interface ProviderConfig { - id: string; - name: string; - type: 'anthropic' | 'openai' | 'google' | 'ollama' | 'custom'; - baseUrl?: string; - model?: string; - enabled: boolean; - createdAt: string; - updatedAt: string; -} -``` - -### Key Validation Rules -- Anthropic: Must start with `sk-ant-` -- OpenAI: Must start with `sk-` -- Google: Minimum 20 characters -- Ollama: No key required -- Custom: No validation - -### ESM Compatibility -electron-store v10+ is ESM-only. Solution: dynamic imports in main process. - -```typescript -let store: any = null; -async function getStore() { - if (!store) { - const Store = (await import('electron-store')).default; - store = new Store({ /* config */ }); - } - return store; -} -``` - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_5_channel_connection.md b/build_process/commit_5_channel_connection.md deleted file mode 100644 index 2182b0dd7..000000000 --- a/build_process/commit_5_channel_connection.md +++ /dev/null @@ -1,124 +0,0 @@ -# Commit 5: Channel Connection Flows - -## Summary -Implement comprehensive channel management UI with multi-platform support, including QR code-based connection for WhatsApp/WeChat and token-based connection for Telegram/Discord/Slack. - -## Changes - -### React Renderer - -#### `src/pages/Channels/index.tsx` -Complete rewrite with enhanced functionality: - -**Main Components:** -- `Channels` - Main page with channel list, stats, and add dialog -- `ChannelCard` - Individual channel display with connect/disconnect/delete -- `AddChannelDialog` - Multi-step channel addition flow - -**Features:** -- Channel statistics (Total, Connected, Disconnected) -- Gateway status warning when not running -- Supported channel type grid for quick add -- Connection-type specific flows: - - QR Code: WhatsApp, WeChat - - Token: Telegram, Discord, Slack - -**AddChannelDialog Flow:** -1. Select channel type -2. View connection instructions -3. For QR: Generate and display QR code -4. For Token: Enter bot token -5. Optionally name the channel -6. Confirm and add - -**Channel Info Configuration:** -```typescript -const channelInfo: Record -``` - -#### `src/stores/channels.ts` -Enhanced channel store with new actions: -- `addChannel(params)` - Add new channel with type, name, token -- `deleteChannel(channelId)` - Remove channel -- `requestQrCode(channelType)` - Request QR code from Gateway -- `clearError()` - Clear error state - -Improved error handling: -- Graceful fallback when Gateway unavailable -- Local channel creation for offline mode - -#### `src/types/channel.ts` -No changes - existing types sufficient. - -### Electron Main Process - -#### `electron/utils/store.ts` -- Converted to dynamic imports for ESM compatibility -- All functions now async - -#### `electron/main/window.ts` -- Converted to dynamic imports for ESM compatibility -- `getWindowState()` and `saveWindowState()` now async - -## Technical Details - -### Channel Connection Architecture -``` -AddChannelDialog - | - +-- QR Flow - | | - | v - | requestQrCode() --> Gateway --> WhatsApp/WeChat API - | | | - | v v - | Display QR <-- qrCode string <-- QR Generated - | | - | v - | User Scans --> Device Confirms --> channel:status event - | - +-- Token Flow - | - v - Enter Token --> addChannel() --> Gateway --> Bot API - | | - v v - Validate <-- success/error <-- Connection Attempt -``` - -### Channel Types Configuration -| Type | Connection | Token Label | Docs | -|------|------------|-------------|------| -| WhatsApp | QR Code | - | WhatsApp FAQ | -| Telegram | Token | Bot Token | BotFather Docs | -| Discord | Token | Bot Token | Developer Portal | -| Slack | Token | Bot Token (xoxb-) | Slack API | -| WeChat | QR Code | - | - | - -### Connection Instructions -Each channel type provides step-by-step instructions: -- WhatsApp: Open app > Settings > Linked Devices > Scan -- Telegram: @BotFather > /newbot > Copy token -- Discord: Developer Portal > Application > Bot > Token -- Slack: API Apps > Create App > OAuth > Install - -### UI Components Used -- `Card`, `Button`, `Input`, `Label` - Base components -- `Separator` - Visual dividers -- `StatusBadge` - Connection status -- `LoadingSpinner` - Loading states -- Lucide icons: Plus, Radio, RefreshCw, Power, QrCode, etc. - -### Error Handling -- Gateway offline: Create local channel, show warning -- Connection failed: Display error on ChannelCard -- Invalid token: Show validation error in dialog - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_6_auto_update.md b/build_process/commit_6_auto_update.md deleted file mode 100644 index 2bc40b19c..000000000 --- a/build_process/commit_6_auto_update.md +++ /dev/null @@ -1,171 +0,0 @@ -# Commit 6: Auto-Update Functionality - -## Summary -Integrate electron-updater for automatic application updates with a comprehensive UI for checking, downloading, and installing updates. - -## Changes - -### Electron Main Process - -#### `electron/main/updater.ts` (New) -Complete auto-update module: - -**AppUpdater Class:** -- Extends EventEmitter for event-based notifications -- Configures electron-updater settings -- Manages update lifecycle - -**Methods:** -- `setMainWindow(window)` - Set window for IPC -- `getStatus()` - Get current update status -- `checkForUpdates()` - Check for available updates -- `downloadUpdate()` - Download available update -- `quitAndInstall()` - Install update and restart -- `setChannel(channel)` - Set update channel (stable/beta/dev) -- `setAutoDownload(enable)` - Configure auto-download -- `getCurrentVersion()` - Get app version - -**Update Status:** -- `idle` - No update activity -- `checking` - Checking for updates -- `available` - Update available -- `not-available` - Already on latest -- `downloading` - Download in progress -- `downloaded` - Ready to install -- `error` - Update failed - -**IPC Handlers (registerUpdateHandlers):** -- `update:status` - Get current status -- `update:version` - Get app version -- `update:check` - Trigger update check -- `update:download` - Start download -- `update:install` - Install and restart -- `update:setChannel` - Change update channel -- `update:setAutoDownload` - Toggle auto-download - -**Events forwarded to renderer:** -- `update:status-changed` -- `update:checking` -- `update:available` -- `update:not-available` -- `update:progress` -- `update:downloaded` -- `update:error` - -#### `electron/main/index.ts` -- Import and register update handlers -- Auto-check for updates in production (10s delay) - -#### `electron/preload/index.ts` -- Added all update IPC channels - -### React Renderer - -#### `src/stores/update.ts` (New) -Zustand store for update state: -- State: `status`, `currentVersion`, `updateInfo`, `progress`, `error`, `isInitialized` -- Actions: `init`, `checkForUpdates`, `downloadUpdate`, `installUpdate`, `setChannel`, `setAutoDownload`, `clearError` -- Listens for all update events from main process - -#### `src/components/settings/UpdateSettings.tsx` (New) -Update UI component: -- Current version display -- Status indicator with icon -- Status text description -- Action buttons (Check/Download/Install/Retry) -- Download progress bar with transfer stats -- Update info card (version, date, release notes) -- Error details display - -**Progress Display:** -- Transferred / Total bytes -- Transfer speed (bytes/second) -- Progress percentage bar - -#### `src/components/ui/progress.tsx` (New) -Radix UI Progress component for download visualization. - -#### `src/pages/Settings/index.tsx` -- Replaced manual update section with `UpdateSettings` component -- Added `useUpdateStore` for version display -- Removed unused state and effect hooks - -## Technical Details - -### Update Flow -``` -App Start (Production) - | - v - 10s Delay - | - v -checkForUpdates() - | - +-- No Update --> status: 'not-available' - | - +-- Update Found --> status: 'available' - | - v - [User Action] - | - v - downloadUpdate() - | - v - status: 'downloading' - progress events - | - v - status: 'downloaded' - | - v - [User Action] - | - v - quitAndInstall() - | - v - App Restarts -``` - -### electron-updater Configuration -```typescript -autoUpdater.autoDownload = false; // Manual download trigger -autoUpdater.autoInstallOnAppQuit = true; // Install on quit -autoUpdater.logger = customLogger; // Console logging -``` - -### Update Channels -- `stable` - Production releases -- `beta` - Pre-release testing -- `dev` - Development builds - -### Progress Info Interface -```typescript -interface ProgressInfo { - total: number; // Total bytes - delta: number; // Bytes since last event - transferred: number; // Bytes downloaded - percent: number; // 0-100 - bytesPerSecond: number; // Transfer speed -} -``` - -### UI States -| Status | Icon | Action Button | -|--------|------|---------------| -| idle | RefreshCw (gray) | Check for Updates | -| checking | Loader2 (spin, blue) | Checking... (disabled) | -| available | Download (green) | Download Update | -| downloading | Download (pulse, blue) | Downloading... (disabled) | -| downloaded | CheckCircle2 (green) | Install & Restart | -| error | AlertCircle (red) | Retry | -| not-available | CheckCircle2 (green) | Check for Updates | - -## Dependencies -- electron-updater ^6.3.9 (already installed) -- @radix-ui/react-progress ^1.1.1 (already installed) - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_7_packaging_distribution.md b/build_process/commit_7_packaging_distribution.md deleted file mode 100644 index cd9749a07..000000000 --- a/build_process/commit_7_packaging_distribution.md +++ /dev/null @@ -1,185 +0,0 @@ -# Commit 7: Packaging and Distribution - -## Summary -Set up comprehensive packaging and distribution infrastructure including CI/CD workflows, multi-platform build configuration, icon generation, and macOS code signing support. - -## Changes - -### GitHub Actions Workflows - -#### `.github/workflows/ci.yml` (New) -Continuous Integration workflow for PRs and main branch: -- **lint**: ESLint validation -- **typecheck**: TypeScript type checking -- **test**: Unit test execution -- **build**: Multi-platform build verification (macOS, Windows, Linux) - -#### `.github/workflows/release.yml` (New) -Release workflow triggered by version tags: -- Matrix builds for all platforms -- Artifact collection and upload -- GitHub Release creation with auto-generated notes -- Pre-release detection for alpha/beta versions - -### Build Configuration - -#### `electron-builder.yml` -Enhanced configuration: -- Artifact naming with version, OS, and arch -- ASAR packaging with native module unpacking -- macOS: Universal binary, notarization ready, extended info -- Windows: NSIS installer with customization -- Linux: AppImage, DEB, RPM targets with dependencies - -New features: -- `artifactName` template for consistent naming -- `asarUnpack` for native modules -- macOS `extendInfo` for privacy permissions -- DMG background and icon configuration -- Linux desktop entry with keywords - -#### `package.json` -New scripts: -- `icons`: Generate icons from SVG source -- `clean`: Remove build artifacts -- `package:mac:universal`: Build universal macOS binary -- `publish`: Build and publish to GitHub -- `publish:mac/win/linux`: Platform-specific publishing -- `release`: Full release workflow - -### Icon Generation - -#### `resources/icons/icon.svg` (New) -Vector source icon: -- Gradient background (#6366f1 to #8b5cf6) -- White claw symbol with "X" accent -- 200px corner radius on 1024px canvas - -#### `scripts/generate-icons.sh` (New) -Icon generation script: -- Generates PNG at multiple sizes (16-1024px) -- Creates macOS `.icns` via iconutil -- Creates Windows `.ico` via ImageMagick -- Creates Linux PNG set - -#### `resources/icons/README.md` (New) -Documentation for icon requirements and generation. - -### macOS Signing - -#### `entitlements.mac.plist` (New) -macOS entitlements for: -- Unsigned executable memory (V8) -- JIT compilation -- Library validation disable -- Network client access -- Child process spawning (Gateway) -- File access permissions - -### Linux Packaging - -#### `scripts/linux/after-install.sh` (New) -Post-installation script: -- Update desktop database -- Update icon cache -- Create CLI symlink - -#### `scripts/linux/after-remove.sh` (New) -Post-removal script: -- Remove CLI symlink -- Update databases - -## Technical Details - -### Build Matrix - -| Platform | Target | Architecture | Format | -|----------|--------|--------------|--------| -| macOS | dmg, zip | universal | Intel + Apple Silicon | -| Windows | nsis | x64, arm64 | .exe installer | -| Linux | AppImage | x64, arm64 | Portable | -| Linux | deb | x64, arm64 | Debian package | -| Linux | rpm | x64 | Red Hat package | - -### Artifact Naming Convention -``` -${productName}-${version}-${os}-${arch}.${ext} -Example: ClawX-1.0.0-mac-universal.dmg -``` - -### Code Signing (Optional) - -**macOS:** -```yaml -env: - CSC_LINK: ${{ secrets.MAC_CERTS }} - CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTS_PASSWORD }} - APPLE_ID: ${{ secrets.APPLE_ID }} - APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }} - APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} -``` - -**Windows:** -```yaml -env: - CSC_LINK: ${{ secrets.WIN_CERTS }} - CSC_KEY_PASSWORD: ${{ secrets.WIN_CERTS_PASSWORD }} -``` - -### Release Process - -1. Update version in `package.json` -2. Commit and push changes -3. Create and push version tag: `git tag v1.0.0 && git push --tags` -4. GitHub Actions builds all platforms -5. Artifacts uploaded to GitHub Release -6. Users receive update notification via electron-updater - -### CI Pipeline - -``` -Push/PR to main - | - v - ┌────────────────┐ - │ lint │ - │ typecheck │──> Parallel - │ test │ - │ build │ - └────────────────┘ - | - v - All Pass? - | - ┌───┴───┐ - No Yes - | | - v v - Fail Merge OK -``` - -### Release Pipeline - -``` -Push tag v* - | - v - ┌─────────────────────────────┐ - │ Build (Matrix) │ - │ ┌─────┬──────┬──────────┐ │ - │ │ mac │ win │ linux │ │ - │ └─────┴──────┴──────────┘ │ - └─────────────────────────────┘ - | - v - Upload Artifacts - | - v - Create GitHub Release - | - v - Auto-update available -``` - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_8_chat_interface.md b/build_process/commit_8_chat_interface.md deleted file mode 100644 index 41d014930..000000000 --- a/build_process/commit_8_chat_interface.md +++ /dev/null @@ -1,142 +0,0 @@ -# Commit 8: Chat Interface - -## Summary -Enhance the chat interface with markdown rendering, typing indicators, welcome screen, and improved user experience for conversations with the AI assistant. - -## Changes - -### React Renderer - -#### `src/pages/Chat/index.tsx` -Complete rewrite with enhanced features: - -**New Components:** -- `ChatMessage` - Individual message with markdown support -- `TypingIndicator` - Animated dots during AI response -- `WelcomeScreen` - Onboarding screen for new users - -**Features:** -- Markdown rendering with react-markdown and remark-gfm -- Code syntax highlighting with copy button -- Auto-resizing textarea input -- Gateway connection status awareness -- Tool call status badges -- Copy message content button -- Shift+Enter for new lines - -**UI Improvements:** -- Gradient avatar for AI assistant -- Rounded message bubbles -- Hover actions (copy, etc.) -- Responsive prose styling -- Custom code block display - -#### `src/components/ui/textarea.tsx` (New) -Textarea component based on shadcn/ui: -- Auto-resize support -- Focus ring styling -- Disabled state - -#### `src/styles/globals.css` -Added prose styling: -- Markdown list formatting -- Blockquote styling -- Table formatting -- Code block margins -- Typing indicator animation - -### Dependencies - -#### `package.json` -New dependencies: -- `react-markdown@10.1.0` - Markdown rendering -- `remark-gfm@4.0.1` - GitHub Flavored Markdown support - -## Technical Details - -### Message Rendering Flow - -``` -Message Content - | - v - Is User? - | - ┌───┴───┐ - Yes No - | | - v v -Plain ReactMarkdown -Text | - v - remark-gfm - | - v - Custom Components - (code, links, etc.) -``` - -### Markdown Components - -| Element | Custom Handling | -|---------|----------------| -| `code` | Inline vs block detection, syntax highlighting label, copy button | -| `a` | External link (new tab), primary color styling | -| `pre` | Background styling, overflow scroll | -| Lists | Proper indentation and spacing | -| Tables | Border collapse, header background | -| Blockquotes | Left border, muted color | - -### Typing Indicator Animation - -```css -@keyframes bounce { - 0%, 60%, 100% { transform: translateY(0); } - 30% { transform: translateY(-4px); } -} - -/* Staggered delay for dots */ -.dot-1 { animation-delay: 0ms; } -.dot-2 { animation-delay: 150ms; } -.dot-3 { animation-delay: 300ms; } -``` - -### Input Handling - -**Key Combinations:** -- `Enter` - Send message -- `Shift+Enter` - New line -- Auto-resize up to 200px max height - -**State Management:** -- Textarea value tracked in local state -- Height recalculated on content change -- Focus maintained after send - -### Gateway Integration - -**Connection Awareness:** -- Warning banner when Gateway offline -- Input disabled without connection -- Fetch history only when connected -- Error display for failed messages - -### Welcome Screen Features - -Quick start cards showing: -- "Ask Questions" - General Q&A capability -- "Creative Tasks" - Writing and brainstorming - -Gradient branding with ClawX logo. - -## UI/UX Considerations - -1. **Message Alignment**: User messages right-aligned, AI left-aligned -2. **Avatar Design**: Gradient for AI, solid for user -3. **Hover Actions**: Progressive disclosure of copy buttons -4. **Feedback**: Toast on code copy, visual state for copied -5. **Loading States**: Typing indicator during AI response -6. **Error Handling**: Inline error display with icon - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/commit_9_skills_browser.md b/build_process/commit_9_skills_browser.md deleted file mode 100644 index 9a479a332..000000000 --- a/build_process/commit_9_skills_browser.md +++ /dev/null @@ -1,153 +0,0 @@ -# Commit 9: Skills Browser - -## Summary -Enhance the Skills page with skill bundles, category filtering, detail dialogs, and improved user experience for managing AI capabilities. - -## Changes - -### React Renderer - -#### `src/pages/Skills/index.tsx` -Complete rewrite with enhanced features: - -**New Components:** -- `SkillDetailDialog` - Modal showing skill details, dependencies, and configuration -- `BundleCard` - Skill bundle display with enable/disable actions - -**Features:** -- Tabbed interface: "All Skills" and "Bundles" -- Category filtering with skill counts -- Search functionality -- Gateway connection status awareness -- Skill bundles with batch enable/disable -- Skill detail dialog with metadata -- Configuration indicator badges -- Toast notifications on skill toggle - -**UI Improvements:** -- Category icons for visual distinction -- Enabled state highlighting (border and background) -- Hover states for cards -- Recommended bundle badges -- Statistics bar with counts - -#### `src/components/ui/tabs.tsx` (New) -Tabs component based on shadcn/ui and Radix Tabs: -- `Tabs` - Root container -- `TabsList` - Tab navigation bar -- `TabsTrigger` - Individual tab button -- `TabsContent` - Tab panel content - -### Data Structures - -#### Skill Bundles -Predefined bundles: -- **Productivity Pack** - Calendar, reminders, notes, tasks, timer -- **Developer Tools** - Code assist, git ops, docs lookup -- **Information Hub** - Web search, news, weather, translate -- **Smart Home** - Lights, thermostat, security cam, routines - -## Technical Details - -### Component Architecture - -``` -Skills Page - | - +-- TabsList - | | - | +-- "All Skills" Tab - | +-- "Bundles" Tab - | - +-- TabsContent: All Skills - | | - | +-- Search/Filter Bar - | +-- Category Buttons - | +-- Skills Grid - | | - | +-- SkillCard (click -> SkillDetailDialog) - | - +-- TabsContent: Bundles - | | - | +-- BundleCard Grid - | - +-- Statistics Bar - | - +-- SkillDetailDialog (modal) -``` - -### Category Configuration - -| Category | Icon | Label | -|----------|------|-------| -| productivity | 📋 | Productivity | -| developer | 💻 | Developer | -| smart-home | 🏠 | Smart Home | -| media | 🎬 | Media | -| communication | 💬 | Communication | -| security | 🔒 | Security | -| information | 📰 | Information | -| utility | 🔧 | Utility | -| custom | ⚡ | Custom | - -### Bundle Operations - -**Enable Bundle:** -```typescript -for (const skill of bundleSkills) { - if (!skill.enabled) { - await enableSkill(skill.id); - } -} -``` - -**Disable Bundle:** -```typescript -for (const skill of bundleSkills) { - if (!skill.isCore) { - await disableSkill(skill.id); - } -} -``` - -### State Management - -**Local State:** -- `searchQuery` - Search input value -- `selectedCategory` - Active category filter -- `selectedSkill` - Skill for detail dialog -- `activeTab` - Current tab ("all" | "bundles") - -**Store Integration:** -- `useSkillsStore` - Skills data and actions -- `useGatewayStore` - Connection status - -### Filtering Logic - -```typescript -const filteredSkills = skills.filter((skill) => { - const matchesSearch = - skill.name.toLowerCase().includes(searchQuery) || - skill.description.toLowerCase().includes(searchQuery); - const matchesCategory = - selectedCategory === 'all' || - skill.category === selectedCategory; - return matchesSearch && matchesCategory; -}); -``` - -### UI States - -**Skill Card:** -- Default: Standard border, white background -- Enabled: Primary border (50% opacity), primary background (5% opacity) -- Hover: Primary border (50% opacity) -- Core: Lock icon, switch disabled - -**Bundle Card:** -- Default: Standard styling -- All Enabled: Primary border, primary background -- Recommended: Amber badge with sparkle icon - -## Version -v0.1.0-alpha (incremental) diff --git a/build_process/process.md b/build_process/process.md deleted file mode 100644 index d994eac4a..000000000 --- a/build_process/process.md +++ /dev/null @@ -1,67 +0,0 @@ -# ClawX Build Process - -## Progress - -### Before: -* add `ClawX-项目架构与版本大纲.md` - -### Completed: -* [commit_1] Project skeleton - Electron + React + TypeScript foundation (v0.1.0-alpha) -* [commit_2] Gateway refinements - Auto-reconnection, health checks, better state management -* [commit_3] Setup wizard - Multi-step onboarding flow with provider, channel, skill selection -* [commit_4] Provider configuration - Secure API key storage, provider management UI -* [commit_5] Channel connection flows - Multi-channel support with QR/token connection UI -* [commit_6] Auto-update functionality - electron-updater integration with UI -* [commit_7] Packaging and distribution - CI/CD, multi-platform builds, icon generation -* [commit_8] Chat interface - Markdown support, typing indicator, welcome screen -* [commit_9] Skills browser - Bundles, categories, detail dialog -* [commit_10] Cron tasks - Create/edit dialog, schedule presets, improved UI -* [commit_11] OpenClaw submodule fix - GitHub URL, auto-generated token, WebSocket auth -* [commit_12] Real API key validation - OpenRouter support, actual API calls to verify keys -* [commit_13] Remove channel setup step - Simplified onboarding, channels moved to Settings -* [commit_14] Auto-install skills step - Replace skill selection with auto-installation progress UI -* [commit_15] Fix Gateway WebSocket handshake - Implement proper OpenClaw protocol -* [commit_16] Fix RPC methods - Align stores with OpenClaw protocol (channels.status, skills.status, chat params) -* [commit_17] API key integration + Control UI chat - Write keys to OpenClaw auth-profiles, embed Control UI - -### Plan: -1. ~~Initialize project structure~~ ✅ -2. ~~Add Gateway process management refinements~~ ✅ -3. ~~Implement Setup wizard with actual functionality~~ ✅ -4. ~~Add Provider configuration (API Key management)~~ ✅ -5. ~~Implement Channel connection flows~~ ✅ -6. ~~Add auto-update functionality~~ ✅ -7. ~~Packaging and distribution setup~~ ✅ -8. ~~Chat interface~~ ✅ -9. ~~Skills browser/enable page~~ ✅ -10. ~~Cron tasks management~~ ✅ - -## Summary - -All core features have been implemented: -- Project skeleton with Electron + React + TypeScript -- Gateway process management with auto-reconnection -- Setup wizard for first-run experience -- Provider configuration with secure API key storage -- Channel connection flows (QR code and token) -- Auto-update functionality with electron-updater -- Multi-platform packaging and CI/CD -- Chat interface with markdown support -- Skills browser with bundles -- Cron tasks management for scheduled automation -- OpenClaw submodule from official GitHub (v2026.2.3) with auto-token auth -- Real API key validation via actual API calls (Anthropic, OpenAI, Google, OpenRouter) -- Simplified setup wizard (channel connection deferred to Settings page) -- Auto-install skills step with real-time progress UI (no manual skill selection) -- Fixed Gateway WebSocket connection with proper OpenClaw handshake protocol -- Aligned RPC store methods with OpenClaw protocol (channels.status, skills.status, chat params) -- API key integration: write keys to ~/.openclaw/agents/main/agent/auth-profiles.json -- Embedded OpenClaw Control UI for chat via webview (replacing custom implementation) - -## Version Milestones - -| Version | Status | Description | -|---------|--------|-------------| -| v0.1.0-alpha | ✅ Done | Core architecture, basic UI framework | -| v0.5.0-beta | Pending | Setup wizard MVP, Node.js installer | -| v1.0.0 | Pending | Production ready, all core features |