feat(devices): add cloud device connection controls

backend/app/api/endpoints/devices.py

@@ -438,3 +438,100 @@ async def execute_device_command(
         result.get("duration"),
     )
     return DeviceCommandResponse(**result)
+
+
+# ==================== Device Session Endpoints ====================
+
+DEFAULT_DEVICE_SESSION_PATH = "/home/ubuntu/.wegent-executor/workspace"
+
+
+class DeviceSessionResponse(BaseModel):
+    """Response model for device session creation."""
+
+    session_id: str = Field(..., description="Unique session identifier")
+    device_id: str = Field(..., description="Target device ID")
+    type: str = Field(..., description="Session type (terminal or code_server)")
+    path: str = Field(..., description="Working directory path")
+    url: str = Field(default="", description="Browser-accessible session URL")
+
+
+@router.post("/{device_id}/terminal", response_model=DeviceSessionResponse)
+async def start_device_terminal(
+    device_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(security.get_current_user),
+):
+    """Start a terminal session on a device.
+
+    Sends a Socket.IO RPC to the online device executor to start a ttyd
+    terminal session. Requires the device to be online.
+    """
+    from app.services.device.session_service import (
+        DeviceSessionError,
+        local_device_session_service,
+    )
+
+    try:
+        result = await local_device_session_service.start_session(
+            db=db,
+            user_id=current_user.id,
+            device_id=device_id,
+            project_id=0,
+            session_type="terminal",
+            path=DEFAULT_DEVICE_SESSION_PATH,
+            create_if_missing=True,
+        )
+    except DeviceSessionError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+
+    return DeviceSessionResponse(
+        session_id=result.get("session_id", ""),
+        device_id=result.get("device_id", device_id),
+        type="terminal",
+        path=result.get("path", DEFAULT_DEVICE_SESSION_PATH),
+        url=result.get("url", ""),
+    )
+
+
+@router.post("/{device_id}/code-server", response_model=DeviceSessionResponse)
+async def start_device_code_server(
+    device_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(security.get_current_user),
+):
+    """Start a code-server (IDE) session on a device.
+
+    Sends a Socket.IO RPC to the online device executor to start a
+    code-server session. Requires the device to be online.
+    """
+    from app.services.device.session_service import (
+        DeviceSessionError,
+        local_device_session_service,
+    )
+
+    try:
+        result = await local_device_session_service.start_session(
+            db=db,
+            user_id=current_user.id,
+            device_id=device_id,
+            project_id=0,
+            session_type="code_server",
+            path=DEFAULT_DEVICE_SESSION_PATH,
+            create_if_missing=True,
+        )
+    except DeviceSessionError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+
+    return DeviceSessionResponse(
+        session_id=result.get("session_id", ""),
+        device_id=result.get("device_id", device_id),
+        type="code_server",
+        path=result.get("path", DEFAULT_DEVICE_SESSION_PATH),
+        url=result.get("url", ""),
+    )

docs/en/user-guide/ai-devices/local-device-support.md

@@ -234,7 +234,31 @@ Simply change the device selection before sending each message.
 Access your devices through:
 
 1. **Device Selector**: Quick access in chat interface
-2. **API**: `GET /devices` for programmatic access
+2. **Settings Page**: Go to **Settings** → **Connections** to view connectable devices
+3. **API**: `GET /devices` for programmatic access
+
+### Managing Cloud Devices
+
+The **Settings** → **Connections** page lists Claude Code cloud devices that the current account can connect to. It only shows devices with `device_type=cloud` and `bind_shell=claudecode`, and displays online status, executor version, CPU, memory, and disk usage.
+
+When no cloud device exists, click **Add** to create one. After the create request returns, the page keeps a "cloud device creating" notice visible. Initialization usually takes 2-3 minutes, and the device appears in the list automatically when it comes online.
+
+Online cloud devices can open interactive sessions directly:
+
+| Action | Backend API | Description |
+|--------|-------------|-------------|
+| **Terminal** | `POST /api/devices/{device_id}/terminal` | Starts ttyd in the default working directory `/home/ubuntu/.wegent-executor/workspace` |
+| **IDE** | `POST /api/devices/{device_id}/code-server` | Opens a code-server session |
+
+The returned URL includes a short-lived session token and is exposed through the device-side session gateway. Terminal and IDE buttons are disabled while the device is offline.
+
+The more menu contains lower-frequency management actions:
+
+| Action | Description |
+|--------|-------------|
+| **Rename** | Click the device name or edit icon; the list refreshes after saving |
+| **Restart Device** | Requires confirmation; the device briefly goes offline and active connections may be interrupted |
+| **Delete Device** | Requires confirmation; the cloud resources are released |
 
 ### Device Information
 
@@ -244,6 +268,8 @@ Each device shows:
 |-------|-------------|
 | **Name** | Device hostname (e.g., "Darwin - MacBook-Pro.local") |
 | **Status** | Online/Offline indicator |
+| **Version** | Executor version, when available |
+| **Resource Usage** | CPU, memory, and disk usage, when reported by the device |
 | **Slots** | Concurrent task capacity (X/5) |
 | **Default** | Star indicator if set as default |
 
@@ -255,7 +281,7 @@ Each device shows:
 | **Remove Default** | Click star again on current default |
 | **Delete Device** | Click delete icon |
 
-> **Note**: Deleting a device only removes the registration. If the device reconnects, it will automatically re-register.
+> **Note**: Deleting a local device only removes the registration. If the device reconnects, it will automatically re-register. Deleting a cloud device from the Connections settings page releases the corresponding cloud resources.
 
 ### Offline Device Handling
 

docs/zh/user-guide/ai-devices/local-device-support.md

@@ -236,7 +236,31 @@ EXECUTOR_MODE=local wegent-executor
 通过以下方式访问您的设备：
 
 1. **设备选择器**：聊天界面中快速访问
-2. **API**：`GET /devices` 用于程序化访问
+2. **设置页**：进入 **设置** → **连接** 查看可连接设备
+3. **API**：`GET /devices` 用于程序化访问
+
+### 管理云设备
+
+**设置** → **连接** 页面会列出当前账号可连接的 Claude Code 云设备。页面仅展示 `device_type=cloud` 且 `bind_shell=claudecode` 的设备，并显示在线状态、executor 版本、CPU、内存和磁盘使用率。
+
+当没有云设备时，点击 **添加** 可以创建一台新的云设备。创建请求返回后，页面会保留“云设备创建中”的提示；初始化通常需要 2-3 分钟，设备上线后会自动出现在列表中。
+
+在线云设备支持直接打开交互式会话：
+
+| 操作 | 后端接口 | 说明 |
+|------|----------|------|
+| **终端** | `POST /api/devices/{device_id}/terminal` | 在默认工作目录 `/home/ubuntu/.wegent-executor/workspace` 启动 ttyd |
+| **IDE** | `POST /api/devices/{device_id}/code-server` | 打开 code-server 会话 |
+
+返回的访问地址带有短期 session token，并通过设备侧 session gateway 暴露。设备离线时，终端和 IDE 按钮不可用。
+
+更多菜单提供低频管理操作：
+
+| 操作 | 说明 |
+|------|------|
+| **重命名** | 点击设备名称或编辑图标，保存后会刷新列表 |
+| **重启设备** | 需要二次确认；设备会短暂离线，进行中的连接可能中断 |
+| **删除设备** | 需要二次确认；云资源会被释放 |
 
 ### 设备信息
 
@@ -246,6 +270,8 @@ EXECUTOR_MODE=local wegent-executor
 |------|------|
 | **名称** | 设备主机名（如 "Darwin - MacBook-Pro.local"） |
 | **状态** | 在线/离线指示器 |
+| **版本** | executor 版本（如适用） |
+| **资源使用率** | CPU、内存、磁盘使用率（如设备上报） |
 | **槽位** | 并发任务容量（X/5） |
 | **默认** | 如果设为默认则显示星号 |
 
@@ -257,7 +283,7 @@ EXECUTOR_MODE=local wegent-executor
 | **取消默认** | 再次点击当前默认设备的星号 |
 | **删除设备** | 点击删除图标 |
 
-> **注意**：删除设备只是移除注册记录。如果设备重新连接，它会自动重新注册。
+> **注意**：本地设备的删除只是移除注册记录。如果设备重新连接，它会自动重新注册。云设备在连接设置页删除时会释放对应云资源。
 
 ### 离线设备处理
 

wework/src/api/devices.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test, vi } from 'vitest'
+import { createDeviceApi } from './devices'
+import type { HttpClient } from './http'
+
+describe('createDeviceApi', () => {
+  test('uses cloud device endpoints for restart and delete actions', async () => {
+    const client = {
+      delete: vi.fn().mockResolvedValue({ message: 'deleted' }),
+      post: vi.fn().mockResolvedValue({ message: 'restart sent' }),
+    } as unknown as HttpClient
+
+    const api = createDeviceApi(client)
+
+    await api.restartCloudDevice('device/1')
+    await api.deleteCloudDevice('device/1')
+
+    expect(client.post).toHaveBeenCalledWith('/cloud-devices/device%2F1/restart')
+    expect(client.delete).toHaveBeenCalledWith('/cloud-devices/device%2F1')
+  })
+})

wework/src/api/devices.ts

@@ -1,17 +1,23 @@
-import type { DeviceCommandResponse, DeviceInfo } from '@/types/api'
+import type { DeviceCommandResponse } from '@/types/api'
+import type {
+  CloudDeviceResponse,
+  DeviceInfo,
+  DeviceListResponse,
+  DeviceSessionResponse,
+} from '@/types/devices'
 import type { HttpClient } from './http'
 
-interface DeviceListResponse {
-  items: DeviceInfo[]
-  total: number
-}
-
 export function createDeviceApi(client: HttpClient) {
+  async function fetchDevices(): Promise<DeviceInfo[]> {
+    const response = await client.get<DeviceListResponse>('/devices')
+    return response.items
+  }
+
   return {
-    async listDevices(): Promise<DeviceInfo[]> {
-      const response = await client.get<DeviceListResponse>('/devices')
-      return response.items
-    },
+    listDevices: fetchDevices,
+
+    getAllDevices: fetchDevices,
+
     async listDirectories(deviceId: string, path: string): Promise<string[]> {
       const response = await client.post<DeviceCommandResponse>(
         `/devices/${encodeURIComponent(deviceId)}/commands`,
@@ -27,5 +33,40 @@ export function createDeviceApi(client: HttpClient) {
       }
       return Array.isArray(response.stdout) ? response.stdout : []
     },
+
+    async startTerminal(deviceId: string): Promise<DeviceSessionResponse> {
+      return client.post<DeviceSessionResponse>(
+        `/devices/${encodeURIComponent(deviceId)}/terminal`,
+      )
+    },
+
+    async startCodeServer(deviceId: string): Promise<DeviceSessionResponse> {
+      return client.post<DeviceSessionResponse>(
+        `/devices/${encodeURIComponent(deviceId)}/code-server`,
+      )
+    },
+
+    async createCloudDevice(): Promise<CloudDeviceResponse> {
+      return client.post<CloudDeviceResponse>('/cloud-devices')
+    },
+
+    async restartCloudDevice(deviceId: string): Promise<{ message: string }> {
+      return client.post<{ message: string }>(
+        `/cloud-devices/${encodeURIComponent(deviceId)}/restart`,
+      )
+    },
+
+    async deleteCloudDevice(deviceId: string): Promise<{ message: string }> {
+      return client.delete<{ message: string }>(
+        `/cloud-devices/${encodeURIComponent(deviceId)}`,
+      )
+    },
+
+    async renameDevice(deviceId: string, alias: string): Promise<void> {
+      await client.put<{ message: string }>(
+        `/devices/${encodeURIComponent(deviceId)}/alias`,
+        { alias },
+      )
+    },
   }
 }

wework/src/components/layout/DesktopWorkbenchLayout.test.tsx

@@ -1,12 +1,50 @@
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { createDeviceApi } from '@/api/devices'
 import { DesktopWorkbenchLayout } from './DesktopWorkbenchLayout'
 
+vi.mock('@/config/runtime', () => ({
+  getRuntimeConfig: () => ({ apiBaseUrl: '/api' }),
+}))
+
+vi.mock('@/api/http', () => ({
+  createHttpClient: vi.fn(() => ({})),
+}))
+
+vi.mock('@/api/devices', () => ({
+  createDeviceApi: vi.fn(),
+}))
+
+const createDeviceApiMock = vi.mocked(createDeviceApi)
+
 describe('DesktopWorkbenchLayout', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     localStorage.clear()
+    createDeviceApiMock.mockReturnValue({
+      getAllDevices: vi.fn().mockResolvedValue([
+        {
+          id: 1,
+          device_id: '24a59054-4638-4744-983d-372706c30fcd',
+          name: 'yunpeng7-executor-372706c30fcd',
+          status: 'online',
+          is_default: false,
+          device_type: 'cloud',
+          bind_shell: 'claudecode',
+          executor_version: '1.712',
+          cpu_usage: 42,
+          memory_usage: 68,
+          disk_usage: 57,
+        },
+      ]),
+      startTerminal: vi.fn(),
+      startCodeServer: vi.fn(),
+      createCloudDevice: vi.fn(),
+      renameDevice: vi.fn(),
+      restartCloudDevice: vi.fn(),
+      deleteCloudDevice: vi.fn(),
+    })
   })
 
   const baseProps = {
@@ -416,13 +454,10 @@ describe('DesktopWorkbenchLayout', () => {
     expect(screen.queryByText('Linux-Device-481b616e8e0b')).not.toBeInTheDocument()
     expect(screen.getByText('可连接的设备')).toBeInTheDocument()
     expect(screen.queryByText('可连接这台设备的云设备')).not.toBeInTheDocument()
-    expect(screen.getByText('云设备')).toBeInTheDocument()
+    expect(await screen.findByText('云设备')).toBeInTheDocument()
     expect(
-      screen.getByTestId('connection-device-icon-24a59054-4638-4744-983d-372706c30fcd'),
-    ).toHaveClass('text-[#3c4043]')
-    expect(
-      screen.getByTestId('connection-device-icon-24a59054-4638-4744-983d-372706c30fcd'),
-    ).not.toHaveClass('bg-[#f7f7f8]')
+      screen.getByTestId('connection-device-24a59054-4638-4744-983d-372706c30fcd'),
+    ).toBeInTheDocument()
     expect(screen.getByText('yunpeng7-executor-372706c30fcd')).toBeInTheDocument()
     expect(screen.getByText('v1.712')).toBeInTheDocument()
     expect(screen.getByText('在线')).toBeInTheDocument()