---
sidebar_position: 3
---

# 前端开发指南

前端代码位于 `src/`，使用 React 19 + TypeScript。

## 入口与窗口模型

前端入口在 `src/main.tsx`，它会根据 URL 中的 `?window=` 参数决定加载哪套应用：

- **主窗口**：`AppProvider` + `App.tsx`
- **子窗口**：`ChildAppProvider` + `ChildWindowRouter`

当前子窗口包括：

- settings
- new-session
- quick-command
- auto-upload

如果你要修改这些流程，优先查看：

- `src/main.tsx`
- `src/ChildWindowRouter.tsx`
- `src/lib/windowManager.ts`

## 组件与目录结构

```text
src/
├── components/          # UI 组件
│   ├── dialog/          # 对话框与子窗口相关组件
│   ├── panel/           # 左右侧栏 / 底部区域面板
│   ├── terminal/        # xterm 工作区与终端相关组件
│   ├── layout/          # 外层布局、标题栏、活动栏
│   └── ui/              # 基础 UI 组件（shadcn/ui）
├── context/             # React Context providers
├── hooks/               # 自定义 hooks
├── i18n/                # 国际化
├── lib/                 # invoke、window 管理、工作区模型等工具
├── pages/               # 子窗口页面
├── types/               # 类型定义
├── App.tsx              # 主应用壳层
└── main.tsx             # 前端入口
```

## 状态管理

### AppContext

`src/context/AppContext.tsx` 是主窗口核心状态容器，管理：

- 标签页与 pane 树
- 活动 tab / pane
- 已保存连接 / 分组刷新
- 应用设置与 UI 设置
- 启动恢复工作区
- 左右活动栏和底部区域布局

### ChildAppProvider

`src/context/ChildAppProvider.tsx` 是子窗口用的轻量 Provider：

- 只加载 / 保存设置
- 不持有完整工作区状态
- 通过事件向主窗口同步设置变化

### TransferContext

`src/context/TransferContext.tsx` 监听 `transfer-event`，集中维护：

- 传输队列列表
- 进度 / 暂停 / 取消 / 错误状态
- pause / resume / cancel / retry 操作

## 调用 Tauri 命令

前端应优先通过 `src/lib/invoke.ts` 中的统一包装调用后端，而不是直接到处散写 `@tauri-apps/api/core` 的 `invoke()`。

```ts
import { invoke } from '@/lib/invoke';

const sessionId = await invoke<string>('create_ssh_session', {
  connectionId: 'uuid-here',
});
```

这个包装会统一做错误日志记录，也便于以后集中调整调用行为。

## 监听后端事件

前端大量能力依赖 Tauri 事件系统，例如：

- `terminal-output-{id}`
- `cwd-changed-{id}`
- `session-closed-{id}`
- `transfer-event`
- `sessions-changed`
- `connections-changed`
- `otp-request`
- `cloud-sync-status-changed`
- `cloud-sync-history-changed`
- `cloud-sync-conflict`
- AI 相关流式事件

终端、文件浏览器、资源监控、传输队列、AI Assistant，以及云同步的状态 / 历史 / 冲突提示都建立在这些事件之上。

## 工作区模型

工作区有两层模型：

### `workspaceTabs.ts`

负责“会保存下来的逻辑工作区”：

- 标签页
- pane 树
- 标签页内分屏
- `ui.open_tabs` 序列化 / 恢复

### `tabWindows.ts`

负责“运行时终端布局”：

- 哪些标签当前挂在哪个 leaf
- 每个 leaf 当前的 active tab
- 运行时 split ratio

修改标签 / 分屏 / 多区域终端布局时，先判断你碰的是哪一层。

## 终端集成

`src/components/terminal/XTerminal.tsx` 是 xterm.js 集成核心，负责：

- Search / Fit / WebLinks addon
- shell integration 与命令建议
- gutter（行号 / 时间戳）
- 动作链接与关键词高亮
- 大输出保护
- 会话重连相关行为

如果你改的是终端表现层，这通常是第一落点。

## AI Assistant 前端落点

如果你改的是 AI 相关 UI，优先查看这些文件：

- `src/components/panel/ai/AIAssistantPanel.tsx` — 主 AI 面板、会话列表、消息渲染、命令卡片、执行审批
- `src/components/settings/AiTab.tsx` — AI 总开关、provider、模型、风险与 agent 配置
- `src/lib/aiEvents.ts` — 从终端、文件、快捷命令等入口打开 AI Assistant 的事件桥
- `src/lib/aiSettings.ts` — provider / model 默认值、风险规则和模型发现工具
- `src/components/app/AppPanelContent.tsx` — AI 面板在右侧栏中的挂载方式

这条链路和当前活跃会话耦合较深，改动时要留意 pane / connection 上下文、模型可用性和执行审批状态。

## Cloud Sync 前端落点

如果你改的是云同步相关 UI，优先查看这些文件：

- `src/pages/SettingsPage.tsx` — 设置页 tab 结构、保存拦截和主密码前置逻辑
- `src/components/settings/SyncBackupTab.tsx` — provider 配置、自动策略、手动操作与冲突处理
- `src/components/panel/SyncBackupHistoryPanel.tsx` — 工作区历史面板与冲突快速处理入口
- `src/App.tsx` — 云同步面板在主工作区中的接入方式
- `src/lib/cloudSync.ts` — 前端默认值、格式化和 provider 校验工具

这些文件之间通过设置状态、Tauri commands 和 cloud-sync 事件一起驱动完整体验。

## 国际化

界面文案使用 `react-i18next`，语言包位于：

- `src/i18n/locales/zh-CN.json`
- `src/i18n/locales/zh-TW.json`
- `src/i18n/locales/en.json`
- `src/i18n/locales/ko.json`

新增或修改用户可见文本时，应同时更新所有 locale 文件；提交前运行 `pnpm i18n:check` 校验 JSON 格式。

## UI 组件约定

项目使用 shadcn/ui 作为基础组件层，共享组件位于 `src/components/ui/`。

如果需要新增通用 UI，优先复用现有组件与项目里的样式模式，而不是单独造一套新的基础组件。