413 lines
13 KiB
Markdown
413 lines
13 KiB
Markdown
# Phase 007 — Arco 迁移：其余 20 视图批量
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 目标 | 全仓无 naive-ui；无第二 UI 库 |
|
||
| 前置 | Phase 006 通过 |
|
||
| 产出 | `grep -r "naive-ui" packages/client/src` 零命中 |
|
||
| 参考 | `docs/03-施工蓝图.md` §8.2 |
|
||
|
||
---
|
||
|
||
## 0. 批次划分原则
|
||
|
||
按**耦合度**分批，不按页面重要性。每批独立提交、独立验收，**任何一批都能停下来过夜**。
|
||
|
||
Phase 006 已经把最难的（流式 / 虚拟滚动 / 审批）趟平了，所以下面每批都是体力活。
|
||
|
||
---
|
||
|
||
## 1. 批次一览
|
||
|
||
| 批次 | 范围 | 特征 | 风险 |
|
||
|---|---|---|---|
|
||
| 7a | Settings / Profiles / Models / Logs | 纯表单 + 表格 | 低 |
|
||
| 7b | Skills / Plugins / McpManager / Memory | 卡片列表 + 抽屉 | 低 |
|
||
| 7c | Files / Terminal | 大量 DOM + xterm | **中** |
|
||
| 7d | Usage / Performance / SkillsUsage / Journey | 图表 / 图谱 + 数据表格 | 中 |
|
||
| 7e | Kanban / Jobs / Workflow / Devices | 拖拽 + 复杂交互 | 中高 |
|
||
| 7f | Channels / GroupChat / GlobalAgent | IM 频道 + 群聊 | 中高 |
|
||
| 7g | History / VersionPreview | 历史会话 | 低 |
|
||
|
||
**7f 排在 7e 之后**：群聊也是流式页，虽然比主聊天简单，但仍有 SSE + 增量渲染，靠近 006 的经验更划算。
|
||
|
||
---
|
||
|
||
## 2. 每批的标准动作（**7a 走一遍，之后照抄**）
|
||
|
||
### 2.1 开工前
|
||
|
||
```bash
|
||
cd /Users/jack/source/MyProject/js/hermes-ui
|
||
# 看这批有多少 naive 引用
|
||
grep -rc "naive-ui" <本批文件列表>
|
||
```
|
||
|
||
### 2.2 改法顺序
|
||
|
||
1. **先建/补 `docs/arco-mapping.md`** —— 本批遇到的 Naive 组件若表里没有，先补进去
|
||
2. **Provider 层先换**（`NMessageProvider` → `useMessage()` composable）
|
||
3. **容器 → 布局**（`NLayout` → `a-layout`）
|
||
4. **表单 → 控件**（`NForm` → `a-form`，逐个 `NFormItem`）
|
||
5. **表格 / 列表**（`NDataTable` → `a-table`，差异最大）
|
||
6. **交互层**（`NModal` `NDrawer` `NPopconfirm`）
|
||
7. **删除所有未用的 naive import**（这一步最容易漏，编译器会兜底）
|
||
|
||
### 2.3 收尾
|
||
|
||
```bash
|
||
grep -rn "naive-ui" <本批文件> # 期望零命中
|
||
npm run build
|
||
npm run test
|
||
npm run test:e2e
|
||
git commit -m "feat(ui): migrate <batch> views to Arco Design Vue"
|
||
```
|
||
|
||
### 2.4 每批完成定义（四条全满足）
|
||
|
||
- [ ] 本批文件 `grep -c naive-ui` 归零
|
||
- [ ] `npm run test` 通过
|
||
- [ ] e2e 对应用例通过
|
||
- [ ] 明暗双主题人工过一遍
|
||
|
||
---
|
||
|
||
## 3. 批次内容
|
||
|
||
### 3.1 批次 7a — 纯表单与表格（**先做这批打样**）
|
||
|
||
```
|
||
views/hermes/SettingsView.vue
|
||
views/hermes/ProfilesView.vue
|
||
views/hermes/ModelsView.vue
|
||
views/hermes/LogsView.vue
|
||
components/hermes/settings/** # 约 20 个组件，含 voice/ 子目录
|
||
components/hermes/profiles/** # 6 个
|
||
components/hermes/models/** # 约 12 个，含各种 OAuth 登录弹窗
|
||
components/hermes/settings/SettingRow.vue
|
||
components/layout/ModelSelector.vue
|
||
components/layout/ProfileSelector.vue
|
||
components/layout/LanguageSwitch.vue
|
||
components/layout/ThemeSwitch.vue
|
||
```
|
||
|
||
**本批特有难点**：
|
||
|
||
- `NForm` 的校验规则 API 与 `a-form` 不同，需写适配
|
||
```
|
||
naive: [{ required: true, message: '...' }]
|
||
arco: [{ required: true, message: '...' }] # 规则对象基本一致
|
||
但 field 绑定方式与 error 展示位置不同
|
||
```
|
||
- 各 OAuth 登录弹窗（`AnthropicLoginModal` `CodexLoginModal` `CopilotLoginModal` `GeminiLoginModal` `NousLoginModal` `XaiOAuthLoginModal`）—— 每个都是独立 Modal，改完逐个点
|
||
- `SettingRow.vue` 是所有设置项的骨架容器，先改它
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/client/default-credential-prompt.test.ts
|
||
tests/client/copilot-login-modal.test.ts
|
||
tests/client/platform-card.test.ts
|
||
tests/client/profile-card-config-edit.test.ts
|
||
tests/client/provider-card-built-in-action.test.ts
|
||
tests/client/provider-base-url.test.ts
|
||
tests/client/display-settings.test.ts
|
||
tests/client/gateway-auto-start-settings.test.ts
|
||
tests/client/compression-settings 相关
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 批次 7b — 卡片列表与抽屉
|
||
|
||
```
|
||
views/hermes/SkillsView.vue
|
||
views/hermes/PluginsView.vue
|
||
views/hermes/McpManagerView.vue
|
||
views/hermes/MemoryView.vue
|
||
components/hermes/skills/** # 7 个
|
||
components/hermes/mcp/McpServerCard.vue
|
||
components/hermes/common/RouteLinkItem.vue
|
||
components/hermes/settings/MemorySettings.vue
|
||
components/hermes/settings/CompressionSettings.vue
|
||
```
|
||
|
||
**本批特有难点**：
|
||
- `SkillList` / `SkillDetail` / `SkillImportModal` / `SkillExternalDirsModal` 有复杂表单与文件树
|
||
- `PendingWriteApprovals.vue` 有审批交互（与 Phase 006 的审批同源）
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/client/skills-view.test.ts
|
||
tests/client/skill-list.test.ts
|
||
tests/client/skill-detail-edit.test.ts
|
||
tests/client/plugins-view.test.ts
|
||
tests/client/pending-write-approvals.test.ts
|
||
tests/client/route-link-item.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 批次 7c — 文件与终端（**别把 Arco 塞进来**）
|
||
|
||
```
|
||
views/hermes/FilesView.vue
|
||
views/hermes/TerminalView.vue
|
||
components/hermes/files/** # 9 个
|
||
components/hermes/chat/TerminalPanel.vue # 若 7a/7b 未改
|
||
composables/useDefaultWorkspace.ts
|
||
utils/file-path.ts
|
||
utils/hermes/kanban-assignees.ts
|
||
```
|
||
|
||
**本批特有难点（**本批最特殊**）：
|
||
- **文件树** `FileTree.vue` / `FileList.vue` / `FileBreadcrumb.vue` 是**手写 DOM 结构 + CSS**，不要换成 Arco 的 `a-tree`——会丢掉自定义的文件类型图标、右键菜单、拖拽。
|
||
- **xterm.js** 终端是独立 DOM 树，**外面套任何 Arco 布局都可能引入尺寸问题**。终端容器用固定 flex + 原生 CSS。
|
||
- `FileContextMenu.vue` / `FilePreview.vue` / `FileEditor.vue` / `FileToolbar.vue` 涉及上传、预览、编辑
|
||
- 右键菜单：`a-trigger` 的 `trigger="contextmenu"`
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/e2e/terminal.spec.ts
|
||
tests/client/file-tree-profile-scope.test.ts
|
||
tests/client/file-list-layout.test.ts
|
||
tests/client/file-context-menu.test.ts
|
||
tests/client/folder-picker-windows-drives.test.ts
|
||
tests/client/files-view-profile-config-route.test.ts
|
||
tests/client/file-path.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 批次 7d — 图表与数据密度
|
||
|
||
```
|
||
views/hermes/UsageView.vue
|
||
views/hermes/PerformanceView.vue
|
||
views/hermes/SkillsUsageView.vue
|
||
views/hermes/JourneyView.vue
|
||
components/hermes/usage/** # StatCards DailyTrend ModelBreakdown AgentBreakdown
|
||
api/hermes/journey.ts
|
||
stores/hermes/usage.ts
|
||
```
|
||
|
||
**本批特有难点**：
|
||
- **这是 ArkScope 装饰层的第二个合法落点**：Journey 图谱的背景层可以用装饰位面。但**数据线、节点、文字仍必须原生渲染**，装饰只能垫在最底。
|
||
- 图表组件（若有 echarts / 自绘 SVG）**不要动**，只换外围容器
|
||
- `NDataTable` → `a-table` 在这里是重灾区（数据密度高、列多、有合计行）
|
||
- 表格横向滚动 + 固定列
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/client/usage-components-cache-visuals.test.ts
|
||
tests/client/usage-view-period.test.ts
|
||
tests/client/usage-store.test.ts
|
||
tests/client/skills-usage-view.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 批次 7e — 拖拽与复杂交互
|
||
|
||
```
|
||
views/hermes/KanbanView.vue
|
||
views/hermes/JobsView.vue
|
||
views/hermes/WorkflowView.vue
|
||
views/hermes/DevicesView.vue
|
||
components/hermes/kanban/** # 4 个
|
||
components/hermes/jobs/** # 4 个
|
||
components/hermes/workflow/** # 3 个
|
||
stores/hermes/kanban.ts
|
||
stores/hermes/jobs.ts
|
||
utils/hermes/workflow-skills.ts
|
||
```
|
||
|
||
**本批特有难点**：
|
||
- **拖拽**（Kanban 列间拖卡片）是**手写 drag 事件**，换成 Arco 布局后要重新验证 drop zone 的坐标计算。**这是本批最大风险。**
|
||
- `WorkflowAgentNode.vue` 画的是节点图，坐标计算与容器尺寸耦合
|
||
- `JobRunHistory` 有时间线
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/client/kanban-view.test.ts
|
||
tests/client/kanban-task-card.test.ts
|
||
tests/client/kanban-task-drawer.test.ts
|
||
tests/client/kanban-create-form.test.ts
|
||
tests/client/kanban-store.test.ts
|
||
tests/client/kanban-api.test.ts
|
||
tests/client/jobs.test.ts
|
||
tests/client/job-form-modal.test.ts
|
||
tests/client/workflow-skills.test.ts
|
||
tests/client/workflow-socket.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 批次 7f — IM 频道与群聊
|
||
|
||
```
|
||
views/hermes/ChannelsView.vue
|
||
views/hermes/GroupChatView.vue
|
||
views/hermes/GlobalAgentView.vue
|
||
components/hermes/group-chat/** # GroupChatPanel GroupMessageList GroupMessageItem GroupChatInput CreateRoomForm
|
||
stores/hermes/group-chat.ts
|
||
api/hermes/group-chat.ts
|
||
api/hermes/global-agent.ts
|
||
```
|
||
|
||
**本批特有难点**：
|
||
- `GroupMessageList` / `GroupMessageItem` 也是**流式增量渲染**，Phase 006 的规则同样适用：气泡内禁用 Arco 组件
|
||
- 多 agent 路由的可视化（谁在响应）
|
||
- 会话设置抽屉
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/client/group-chat-store-baseline.test.ts
|
||
tests/client/group-chat-store-streaming.test.ts
|
||
tests/client/group-chat-store-workspace.test.ts
|
||
tests/client/group-chat-view-settings.test.ts
|
||
tests/client/group-chat-workspace-diff.test.ts
|
||
tests/client/group-chat-input-mentions.test.ts
|
||
tests/client/group-chat-mention-options.test.ts
|
||
tests/client/group-chat-panel-workspace-source.test.ts
|
||
tests/client/group-message-list-scroll.test.ts
|
||
tests/client/group-message-item-highlight.test.ts
|
||
tests/e2e/group-chat-room-deeplink.spec.ts
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 批次 7g — 历史与版本预览（**收尾**）
|
||
|
||
```
|
||
views/hermes/HistoryView.vue
|
||
views/hermes/VersionPreviewView.vue
|
||
stores/hermes/app.ts
|
||
data/changelog.ts # Phase 002 已清空
|
||
```
|
||
|
||
**本批特有难点**：
|
||
- `VersionPreviewView` 若 `changelog` 已清空，要么给空态，要么隐藏入口
|
||
|
||
**完成后必须过**：
|
||
```bash
|
||
tests/e2e/history-session-deeplink.spec.ts
|
||
tests/client/chat-view-tab-title.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 收尾（全批次完成后）
|
||
|
||
### 4.1 删依赖
|
||
|
||
`package.json` 删：
|
||
|
||
```jsonc
|
||
"naive-ui": "...",
|
||
"@css-render/vue3-ssr": "...", // naive 的 peer，若直接依赖
|
||
"vdirs": "..." // 若直接依赖
|
||
```
|
||
|
||
先用 `grep -rn "vdirs\|@css-render" packages/client/src` 确认是否真用到。
|
||
|
||
### 4.2 改构建配置
|
||
|
||
`vite.config.ts`：
|
||
|
||
```ts
|
||
// manualChunks
|
||
if (id.includes('naive-ui') || id.includes('vueuc')) return 'ui-vendor'
|
||
// 改为
|
||
if (id.includes('@arco-design')) return 'ui-vendor'
|
||
|
||
// optimizeDeps.include
|
||
// 删掉 'naive-ui', 'vueuc', '@css-render/vue3-ssr'
|
||
// 加上 '@arco-design/web-vue'
|
||
```
|
||
|
||
### 4.3 恢复 `prepare` script
|
||
|
||
Phase 001 摘掉的 `"prepare": "[ -d dist ] || npm run build"` 恢复。
|
||
|
||
### 4.4 重写 `style-system.test.ts`
|
||
|
||
旧版断言的是 Naive 的 theme key。改为断言 Arco token：
|
||
|
||
```ts
|
||
// packages/client/src/styles/arco-theme.ts 导出的令牌完整性
|
||
// colorPrimary / colorBgLayout / colorBgContainer / borderRadius / fontFamily / fontFamilyMono 存在
|
||
// 浅色与深色两套值都定义了
|
||
```
|
||
|
||
### 4.5 新增 `no-naive-ui.test.ts`（**防回流，最强保障**）
|
||
|
||
```ts
|
||
// 递归扫 packages/client/src
|
||
// 任何文件出现 "from 'naive-ui'" 或 "from \"naive-ui\"" 即 fail
|
||
// 同时断言 package.json 的 dependencies 里无 naive-ui
|
||
```
|
||
|
||
### 4.6 更新 `AGENTS.md` 前端规则
|
||
|
||
```
|
||
- 使用 Arco Design Vue。新增控件优先从 @arco-design/web-vue/es/icon 取图标。
|
||
- 禁止引入第二个 UI 库。
|
||
- 消息气泡内部不用 Arco 组件（流式性能）。
|
||
- 装饰层一律 pointer-events: none。
|
||
```
|
||
|
||
### 4.7 更新 `DEVELOPMENT.md` 的依赖说明
|
||
|
||
删掉任何 naive 相关表述。
|
||
|
||
---
|
||
|
||
## 5. 验收
|
||
|
||
```bash
|
||
cd /Users/jack/source/MyProject/js/hermes-ui
|
||
|
||
# 全仓零命中
|
||
grep -rn "naive-ui\|vueuc\|@css-render" packages/client/src/
|
||
grep -n "naive-ui" package.json package-lock.json
|
||
# 期望：零命中
|
||
|
||
# 只 Arco 一个 UI 库
|
||
grep -nE "\"(naive-ui|element-plus|ant-design-vue|primevue|@arco-design/web-vue)\"" package.json
|
||
|
||
npm ci --ignore-scripts
|
||
npm run build
|
||
npm run test:coverage
|
||
npm run test:e2e
|
||
```
|
||
|
||
### 手工
|
||
|
||
- [ ] 全部 24 个视图（20 个 + 登录 + 缺依赖引导）逐个点过
|
||
- [ ] 明暗双主题各过一遍
|
||
- [ ] Kanban 拖拽正常
|
||
- [ ] 文件树正常
|
||
- [ ] 终端正常
|
||
- [ ] 图表正常
|
||
- [ ] 窄屏 / 移动端布局正常
|
||
|
||
---
|
||
|
||
## 6. 风险
|
||
|
||
| # | 风险 | 缓解 |
|
||
|---|---|---|
|
||
| P7-1 | 工作量超预期，7a-7g 拖太久 | 每批独立可停；先做 7a 定模式，再批量 |
|
||
| P7-2 | 批量改中顺手重构业务逻辑，污染 diff | 硬规则：**只换渲染层**。发现逻辑 bug 单独记 issue，不在本次改 |
|
||
| P7-3 | Kanban 拖拽坐标在 Arco 布局下算错 | 7e 单独安排时间手测，不与其他批混做 |
|
||
| P7-4 | 忘记某文件的 naive import | `no-naive-ui.test.ts` 卡住（§4.5） |
|
||
| P7-5 | `a-table` 替换后大数据量卡顿 | 7d 加虚拟滚动（`a-table-virtual`），先测 1000 行 |
|
||
| P7-6 | 依赖删了但 lock 没同步，`npm ci` 失败 | 删依赖后 `rm package-lock.json && npm install --package-lock-only` |
|
||
| P7-7 | 7f 群聊流式性能退化 | 复用 Phase 006 的气泡禁 Arco 规则 |
|
||
|
||
---
|
||
|
||
## 7. 完成标志
|
||
|
||
项目功能完整 + 界面全量 Arco + 无第二 UI 库。进入 Phase 008。
|