feat(ui): 重设计文件管理器书签与传输面板

新增书签作用域与连接关联，后端为 favorite_paths 补充 scope 和 connection_id 字段及查询写入支持前端重构书签弹窗与编辑表单，支持本地/云端筛选、作用域选择与多语言文案更新文件管理器工具栏改为紧凑图标样式，上传入口合并为下拉菜单，并新增底部传输面板统一展示上传任务同时优化 SSH 终端运行态为显式状态机，并为短命令补充最短可见时间，避免运行中标记闪烁难以感知
2026-05-01 22:54:29 +08:00
parent 96d9950c6b
commit 2233e3fa4f
33 changed files with 1868 additions and 1541 deletions
@@ -2,6 +2,9 @@

 ## [Unreleased]

+- **[frontend]**: 将 SSH 终端 `%` 运行中提示从单布尔派生升级为显式 `commandRuntimePhase` 状态机，并为极短命令补上最短可见窗口，避免标签提示一闪而过几乎不可感知 — by yinjianm
+  - 方案: [202604210531_ssh-terminal-runtime-state-machine](archive/2026-04/202604210531_ssh-terminal-runtime-state-machine/)
+
 - **[frontend]**: 将 `packages/frontend` 的 Vite 开发代理改为支持通过 `VITE_DEV_PROXY_TARGET`、`VITE_DEV_WS_PROXY_TARGET` 与 `VITE_API_BASE_URL` 切换远端联调目标，并验证 `focus-switcher-sequence`、登录链路与默认白色主题可在本地前端联调时正常工作 — by yinjianm
  - 方案: [202604210440_frontend-dev-api-theme-verification](archive/2026-04/202604210440_frontend-dev-api-theme-verification/)

@@ -0,0 +1,12 @@
+{
+  "status": "completed",
+  "completed": 5,
+  "failed": 0,
+  "skipped": 0,
+  "pending": 0,
+  "total": 5,
+  "done": 5,
+  "percent": 100,
+  "current": "-",
+  "updated_at": "2026-04-21 05:43:00"
+}
@@ -0,0 +1,150 @@
+# 变更提案: ssh-terminal-runtime-state-machine
+
+## 元信息
+```yaml
+类型: 修复/优化
+方案类型: implementation
+优先级: P1
+状态: 实施中
+创建: 2026-04-21
+```
+
+---
+
+## 1. 需求
+
+### 背景
+仓库已经在 2026-04-19 做过一轮 `%` 运行中提示增强，当前 [TerminalTabBar.vue](/E:/code/vue/nexus-terminal/packages/frontend/src/components/TerminalTabBar.vue) 和 [LayoutRenderer.vue](/E:/code/vue/nexus-terminal/packages/frontend/src/components/LayoutRenderer.vue) 也已经接上了 `%` UI。但现有实现仍把运行态建模成单个 `isCommandRunning` 布尔值，再叠加 `terminalInputBuffer` 和 prompt 正则做启停判断。这个模型无法区分“刚提交命令但还没输出”“命令正在持续输出”“连接异常断开”“错误导致提前结束”等阶段，导致一些真实场景下 `%` 要么瞬时闪烁，要么被过早清掉，用户体感上接近“没有实际作用”。
+
+### 目标
+- 将 SSH 命令运行态从单个布尔值升级成显式状态机，至少能区分 `idle / typing / pending / running / disconnected / error`。
+- 继续基于发送命令、shell prompt、断连与错误链路派生运行态，但收口到统一的状态转移逻辑，而不是分散地手改布尔值。
+- 让顶部服务器标签和服务器内部终端标签继续显示 `%`，但由“运行态处于活动阶段”统一派生，确保两层显示一致。
+- 解决“快速命令根本看不到 `%`”的问题，让极短命令也能有足够短但可感知的可视反馈。
+
+### 约束条件
+```yaml
+时间约束: 本轮限定在 packages/frontend 内完成，不扩展 backend WebSocket 协议
+性能约束: 继续沿用轻量字符串缓冲与尾部 prompt 检测，不引入全终端内容扫描
+兼容性约束: RDP/VNC 标签行为不变，现有 WorkspaceView / Terminal / session getter 数据流尽量少破坏
+业务约束: `%` 仍是前端派生提示，不承诺成为服务端权威任务状态
+```
+
+### 验收标准
+- [ ] SSH 会话在底部命令输入框、快捷指令、文件管理器和终端内回车等现有发送入口触发后，会进入显式运行态活动阶段并显示 `%`
+- [ ] shell prompt 返回、连接断开、SSH 错误和 `Ctrl+C` 中断后，运行态会按统一状态机退出活动阶段，顶部服务器标签和内部终端标签同步消失 `%`
+- [ ] 极短命令不会因为“提交后立刻命中 prompt”而完全看不到 `%`，标签上至少存在一个可感知的短暂运行中提示
+- [ ] `npm --workspace @nexus-terminal/frontend run build` 通过，且没有新增类型或模板错误
+
+---
+
+## 2. 方案
+
+### 技术方案
+本轮不再继续扩展旧的 `isCommandRunning` 布尔值，而是引入一层显式 SSH 运行态模型，并把发送输入、输出探测、断连和错误全部收口到同一套 reducer 风格的状态转移函数中。
+
+实现分成三层：
+
+1. 在 `session` 模块中新增 SSH 运行态类型与状态字段，至少包含 `phase`、`lastTransitionAt`、`lastCompletedAt` 和输入缓冲；`isCommandRunning` 改为从 `phase` 派生，而不是作为主状态独立维护。
+2. 在 `useSshTerminal.ts` 中把“发送非空命令”“收到输出”“命中 prompt”“中断”“断连”“错误”统一转换成状态机事件，避免旧实现那种一边写布尔、一边清空输入缓存的分散逻辑。
+3. 在标签 UI 层继续复用 `%`，但由 `isRuntimeActive(phase)` 统一判定。对于极快结束的命令，增加一个很短的最小可见窗口，让 `%` 不至于只闪过一个渲染帧。
+
+### 影响范围
+```yaml
+涉及模块:
+  - frontend/session: 调整 SSH 会话运行态模型与 getter 派生字段
+  - frontend/composables: 重写 useSshTerminal.ts 内的运行态转移逻辑
+  - frontend/ui: 顶部服务器标签与服务器内终端标签改为消费新的派生活动态
+  - frontend/knowledge: 同步 frontend.md 与 CHANGELOG.md 中的运行态描述
+预计变更文件: 6-8
+```
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| prompt 检测仍可能覆盖不到个别定制 shell | 中 | 保持 prompt 识别只负责“退出活动态”，同时由断连、错误和中断链路兜底清理 |
+| 新状态机与旧 getter 混用导致 UI 不更新或语义冲突 | 中 | 收敛 getter，只保留一个派生活动态出口，模板层继续吃布尔结果以减小改动面 |
+| 为了让短命令可见而增加最短展示时间后，可能让极快命令多亮几百毫秒 | 低 | 将最短窗口控制在短阈值，只解决“完全看不到”的问题，不把标签做成长时延迟态 |
+
+---
+
+## 3. 技术设计
+
+### 架构设计
+```mermaid
+flowchart TD
+    A[CommandInputBar / QuickCommands / FileManager / Terminal] --> B[terminalManager.sendData or handleTerminalData]
+    B --> C[SSH Runtime Reducer]
+    C --> D[session.commandRuntimePhase]
+    E[ssh:output] --> C
+    F[ssh:disconnected / ssh:error / Ctrl+C] --> C
+    D --> G[session getter 派生 isCommandRunning]
+    G --> H[TerminalTabBar 服务器标签 %]
+    G --> I[LayoutRenderer 内部终端标签 %]
+```
+
+### 数据模型
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `commandRuntimePhase` | `Ref<'idle' \| 'typing' \| 'pending' \| 'running' \| 'disconnected' \| 'error'>` | SSH 终端当前所处的显式运行阶段 |
+| `commandRuntimeReason` | `Ref<'init' \| 'input' \| 'submit' \| 'output' \| 'prompt' \| 'interrupt' \| 'disconnect' \| 'error' \| 'connected'>` | 最近一次状态迁移的原因，便于调试与后续扩展 |
+| `commandRuntimeVisibleUntil` | `Ref<number>` | 运行中提示至少显示到的时间点，用于避免极短命令完全不可见 |
+| `terminalInputBuffer` | `Ref<string>` | 当前一行尚未提交的终端输入缓冲，继续用于判断回车是否提交了非空命令 |
+
+---
+
+## 4. 核心场景
+
+### 场景: 快捷命令或底部命令输入框发送非空命令
+**模块**: frontend
+**条件**: 用户在某个 SSH 会话上通过底部命令输入框、快捷指令、命令历史或文件管理器触发 `terminalManager.sendData(...)`
+**行为**: 状态机收到“提交命令”事件，切换到 `pending`，并立即打开 `%` 运行中提示
+**结果**: 顶部服务器标签和当前服务器内部终端标签都能同步看到 `%`
+
+### 场景: 命令快速结束但提示仍可见
+**模块**: frontend
+**条件**: 用户发送一个几乎立即返回 prompt 的短命令
+**行为**: 状态机在提交后进入 `pending`，即使命中 prompt 也会遵守最短可见窗口再退出活动阶段
+**结果**: `%` 不会只闪过一个渲染帧，用户能明确感知“刚刚执行过”
+
+### 场景: shell prompt、断连和错误统一退出活动态
+**模块**: frontend
+**条件**: SSH 会话收到 prompt 尾部、`ssh:disconnected`、`ssh:error` 或 `Ctrl+C`
+**行为**: 状态机依据事件原因切换到 `idle / disconnected / error` 等非活动阶段
+**结果**: 顶部服务器标签与内部终端标签的 `%` 同步消失，不再残留旧状态
+
+---
+
+## 5. 技术决策
+
+### ssh-terminal-runtime-state-machine#D001: 用显式运行态阶段替代单一 `isCommandRunning` 布尔值
+**日期**: 2026-04-21
+**状态**: ✅采纳
+**背景**: 当前 `%` 标签虽然已经渲染到 UI，但旧实现只能用 `true/false` 表达“正在运行”，导致“刚提交命令但还没输出”“命令执行中”“连接已断开”“错误终止”等语义全部混在一个布尔值里，既难维护，也难稳定派生 UI。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: 继续沿用布尔值并追加更多 if/else | 改动最少 | 状态语义继续混乱，问题很容易回归 |
+| B: 引入显式运行态阶段和统一转移函数 | 状态来源清晰，便于覆盖 prompt/断连/错误等链路 | 需要调整 session 类型和 useSshTerminal 逻辑 |
+**决策**: 选择方案 B
+**理由**: 用户当前反馈的根因不是“少一个 if 判断”，而是模型过弱。只有把 SSH 运行态从布尔提升为阶段状态，才能真正稳定地驱动 `%`。
+**影响**: 影响 `session` 类型定义、getter 派生逻辑、`useSshTerminal.ts` 的输入/输出处理以及两个标签组件的消费方式
+
+### ssh-terminal-runtime-state-machine#D002: 为极短命令增加最短可见窗口，而不是 prompt 一到就立刻灭掉 `%`
+**日期**: 2026-04-21
+**状态**: ✅采纳
+**背景**: 用户明确反馈“整个没看到实际作用”，说明仅靠“提交置位、prompt 清除”的旧策略在短命令场景下可见性太差，即便逻辑成立也没有体感价值。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: prompt 命中后立即清除 `%` | 语义最直接 | 短命令常常一闪而过，用户几乎感知不到 |
+| B: 运行态活动阶段增加一个很短的最小可见窗口 | 保持真实链路派生，同时确保用户能看到反馈 | 极快命令会多保留极短时间 |
+**决策**: 选择方案 B
+**理由**: 本轮目标不是做“理论上存在过”的状态，而是让用户真的看到 `%` 起作用。短暂的最小展示时间能显著提升感知质量，而且不需要改变后端协议。
+**影响**: 需要在前端状态机里记录时间戳，并在 prompt/错误/断连清理时考虑延迟退出
+
+---
+
+## 6. 成果设计
+
+N/A。本轮不新增视觉体系，只保持现有深色终端工作台内的 `%` 提示语义，并增强其可见性与状态来源准确度。
@@ -0,0 +1,53 @@
+# 任务清单: ssh-terminal-runtime-state-machine
+
+> **@status:** completed | 2026-04-21 05:47
+
+```yaml
+@feature: ssh-terminal-runtime-state-machine
+@created: 2026-04-21
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 5 | 0 | 0 | 5 |
+
+---
+
+## 任务列表
+
+### 1. 运行态模型重构
+
+- [√] 1.1 在 `packages/frontend/src/stores/session/types.ts` 与 `packages/frontend/src/stores/session/actions/sessionActions.ts` 中引入 SSH 显式运行态字段，并移除旧的主布尔状态入口 | depends_on: []
+- [√] 1.2 在 `packages/frontend/src/composables/useSshTerminal.ts` 中收口发送、prompt、断连、错误与中断链路，改为统一状态机转移逻辑 | depends_on: [1.1]
+
+### 2. 标签派生与可见性修复
+
+- [√] 2.1 在 `packages/frontend/src/stores/session/getters.ts` 中改为从 `commandRuntimePhase` 派生活动态，并保持 `TerminalTabBar.vue` 与 `LayoutRenderer.vue` 继续复用现有 `%` 模板显示一致 | depends_on: [1.2]
+- [√] 2.2 为极短命令加入最短可见窗口，确保 `%` 不会只闪烁一个渲染帧 | depends_on: [1.2]
+
+### 3. 验证与知识库同步
+
+- [√] 3.1 运行 `npm --workspace @nexus-terminal/frontend run build` 验证前端编译通过，并同步 `.helloagents/modules/frontend.md` 与 `.helloagents/CHANGELOG.md` | depends_on: [2.1, 2.2]
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-21 05:31 | 方案包创建 | 完成 | 已创建 `202604210531_ssh-terminal-runtime-state-machine`，准备进入开发实施 |
+| 2026-04-21 05:40 | 1.1 / 1.2 | 完成 | 已引入 `commandRuntimePhase` 显式状态，并将发送、prompt、断连、错误与中断链路统一收口到状态转移逻辑 |
+| 2026-04-21 05:41 | 2.1 / 2.2 | 完成 | getter 现已从 `commandRuntimePhase` 派生活动态，并为极短命令补上最短可见窗口，保持两层 `%` 继续复用现有模板 |
+| 2026-04-21 05:43 | 3.1 | 完成 | `npm --workspace @nexus-terminal/frontend run build` 通过，并同步 `frontend.md` 与 `CHANGELOG.md` |
+
+---
+
+## 执行备注
+
+- 本轮为前端单包修复，不修改 backend WebSocket 协议。
+- 历史方案 `202604192106_terminal-running-indicator` 已完成，但现场反馈显示旧布尔模型体感无效，本轮在其基础上做显式状态机收敛。
+- 顶部服务器标签与内部终端标签继续保留 `%` 设计，不新增新的运行态 UI 组件。
@@ -7,6 +7,7 @@

 | 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 |
 |--------|------|------|---------|------|------|
+| 202604210531 | ssh-terminal-runtime-state-machine | - | - | - | ✅完成 |
 | 202604210440 | frontend-dev-api-theme-verification | - | - | - | ✅完成 |
 | 202604192106 | terminal-running-indicator | - | - | - | ✅完成 |
 | 202604190520 | status-monitor-cpu-summary-modal | - | - | - | ✅完成 |
@@ -9,5 +9,5 @@
  "done": 6,
  "percent": 100,
  "current": "-",
-  "updated_at": "2026-04-21 04:28:38"
+  "updated_at": "2026-05-01 21:07:56"
 }
@@ -41,8 +41,8 @@

 | 时间 | 事件 | 详情 |
 |------|------|------|
-| 2026-03-26 04:05 | 2.2 | 完成 | 拖拽上传前新增目标目录确认，并在当前可见目录上传完成后主动刷新 |
-| 2026-03-26 04:08 | 3.1 | 完成 | 目录删除改为“仅删空目录 / 强制递归删除”双确认，后端 `sftp:rmdir` 接收 `recursive` 标志 |
-| 2026-03-26 04:10 | 3.2 | 完成 | 删除目录后若当前/待加载路径失效，前端自动回退父目录，终止持续 `No such file` 重试 |
 | 2026-03-26 04:14 | 4.1 | 完成 | `npm run build --workspace @nexus-terminal/frontend` 与 `@nexus-terminal/backend` 均通过 |
 | 2026-04-21 04:28:38 | 进度快照(自动) | 完成:6 失败:0 跳过:0 待做:0 (100%) |
+| 2026-05-01 21:01:18 | 进度快照(自动) | 完成:6 失败:0 跳过:0 待做:0 (100%) |
+| 2026-05-01 21:02:20 | 进度快照(自动) | 完成:6 失败:0 跳过:0 待做:0 (100%) |
+| 2026-05-01 21:07:56 | PreCompact快照 | 完成:6 失败:0 跳过:0 待做:0 (100%) |
@@ -0,0 +1,13 @@
+{
+  "status": "pending",
+  "completed": 0,
+  "failed": 0,
+  "skipped": 0,
+  "pending": 10,
+  "uncertain": 0,
+  "total": 10,
+  "done": 0,
+  "percent": 0,
+  "current": "重设计目录树样式 — 紧凑树视图",
+  "updated_at": "2026-05-01 21:35:15"
+}
@@ -0,0 +1,98 @@
+# 方案包: file-manager-ui-redesign
+
+- 创建日期: 2026-05-01 21:11
+- 类型: implementation
+- 决策ID: file-manager-ui-redesign#D001
+
+## 1. 需求
+
+### 背景
+用户提供了 5 张目标截图，要求重新设计工作台文件管理器的 UI，涵盖目录树、工具栏、书签系统、新增书签弹窗、传输管理面板五个区域。当前实现使用卡片式行布局和文字+图标按钮，与目标的紧凑树视图和纯图标工具栏存在较大差异。
+
+### 目标
+- 目录树：从卡片行布局转为紧凑传统文件树（黄色文件夹图标、绿色高亮活动目录、符号链接显示目标、更紧密间距、无卡片边框）
+- 工具栏：从文字+图标按钮转为紧凑纯图标工具栏（tooltip 提示），上传按钮合并为下拉菜单（"上传文件"/"上传文件夹"）
+- 书签系统：重新设计为"书签列表 N"头部、"本地"/"云端"标签切换（本地=仅当前服务器、云端=全局共享）、scope 标签、更丰富的卡片布局和操作按钮
+- 新增书签弹窗：新增"记录位置"scope 选择器（仅当前服务器/全局共享）
+- 传输管理面板：新增底部抽屉面板，含"全部/上传/下载"标签，统一展示上传和传输任务，空态"暂无传输任务"
+
+### 约束条件
+- 使用项目现有技术栈：Vue 3 + Composition API、Pinia、Tailwind CSS、vue-i18n
+- 书签 scope 功能需要后端数据库 migration（新增 scope 和 connection_id 字段）
+- 保持所有现有功能不变，仅改变 UI 呈现和增加 scope 功能
+- 遵循项目现有主题变量系统
+
+### 验收标准
+- 目录树视觉效果匹配目标截图：紧凑行高、黄色文件夹图标、绿色活动行高亮
+- 工具栏为纯图标按钮，上传按钮为下拉菜单
+- 书签支持本地/云端 scope 切换和筛选
+- 传输面板在底部以抽屉形式展开，支持三个 tab 筛选
+- 所有 i18n 键已添加（zh-CN、en-US、ja-JP）
+
+## 2. 方案
+
+### 技术方案
+
+#### 任务1：目录树 UI 重设计
+- 修改 `FileManager.vue` 模板中的 `explorerTreeRows` 渲染区域
+- 移除卡片样式（`rounded-lg border`），改为紧凑行（`py-0.5`）
+- 图标颜色：目录用 `text-yellow-500`（黄色文件夹），文件保持现有图标
+- 活动行：使用 `bg-green-600/20 text-green-400` 高亮
+- 符号链接：在文件名后显示 `→ target`
+- 调整树头部样式使其更紧凑
+
+#### 任务2：工具栏重设计
+- 将工具栏区域的文字+图标按钮改为纯图标按钮（统一 `w-7 h-7`）
+- 为每个按钮添加 `title` tooltip
+- 上传文件和上传文件夹合并为单个按钮 + 下拉菜单
+- 新增 `uploadMenuOpen` ref 控制下拉菜单显隐
+
+#### 任务3：书签系统重构
+- 后端：`favorite_paths` 表新增 `scope` (TEXT, DEFAULT 'global') 和 `connection_id` (INTEGER, NULLABLE) 字段
+- 后端：API 支持 `?scope=local&connectionId=X` 查询参数
+- 前端 store：扩展 `FavoritePathItem` 类型，添加 scope 和 connectionId 字段
+- 前端 `FavoritePathsModal.vue`：重设计为含头部计数、本地/云端 tab、scope 标签的布局
+- 前端 `AddEditFavoritePathForm.vue`：新增 scope 选择器
+
+#### 任务4：传输管理面板
+- 新建 `TransferPanel.vue` 组件：底部抽屉面板
+- 含"全部/上传/下载"标签切换
+- 统一展示 `uploads`（来自 FileUploadPopup）和 `transferTasks`（来自 TransferProgressModal）
+- 空态显示"暂无传输任务"
+- 集成到 `FileManager.vue` 底部
+
+### 影响范围
+- `packages/frontend/src/components/FileManager.vue` — 目录树+工具栏+传输面板集成
+- `packages/frontend/src/components/FavoritePathsModal.vue` — 书签列表重设计
+- `packages/frontend/src/components/AddEditFavoritePathForm.vue` — 新增 scope 选择器
+- `packages/frontend/src/components/TransferPanel.vue` — 新组件
+- `packages/frontend/src/stores/favoritePaths.store.ts` — scope 支持
+- `packages/backend/src/database/schema.ts` — 数据库 migration
+- `packages/backend/src/favorite-paths/` — API 扩展
+- `packages/frontend/src/locales/` — i18n 键
+
+### 风险评估
+- 数据库 migration 需谨慎处理现有数据兼容性（现有书签默认 scope='global'）
+- FileManager.vue 文件较大（~2570 行），修改需精确定位避免副作用
+- 传输面板需同时消费两个不同数据源（uploads + transferTasks）
+
+### 方案取舍
+- 选择在 `FileManager.vue` 内直接修改而非拆分子组件，因为目录树渲染与父组件状态紧密耦合，拆分成本高于收益
+- 书签 scope 选择直接内联到现有表单而非独立组件，保持简单
+- 传输面板选择新建独立组件，因为它的数据源和生命周期独立于文件管理器其他部分
+
+### 验证策略
+- verifyMode: review-first
+- reviewerFocus: UI 视觉匹配目标截图、样式一致性、响应式表现
+- testerFocus: 书签 CRUD 功能完整性、scope 筛选正确性、传输面板数据展示
+- 风险边界: 数据库 migration 回滚方案为手动删除新增字段
+
+## 成果设计
+
+### 美学基调
+延续项目现有的暗色终端风格，紧凑高信息密度，使用项目主题变量系统保持一致性。
+
+### 视觉要素
+- 配色：遵循项目现有 `--color-*` CSS 变量体系；目录树活动行使用绿色系，文件夹图标使用黄色系
+- 布局：紧凑垂直排列，减少 padding 和 margin，提升信息密度
+- 交互：hover 状态使用 `bg-background` 微弱高亮，保持轻量
@@ -0,0 +1,104 @@
+@feature: file-manager-ui-redesign
+@created: 2026-05-01 21:11
+@status: pending
+@mode: implementation
+
+## 进度概览
+
+- 完成: 0 / 失败: 0 / 跳过: 0 / 总数: 9
+
+## 任务列表
+
+### 阶段1: 目录树与工具栏 UI 重设计
+
+- [ ] 1.1 重设计目录树样式 — 紧凑树视图
+  - 文件: `packages/frontend/src/components/FileManager.vue` (模板 lines 2476-2530)
+  - 预期变更: 移除卡片边框和圆角，改为紧凑行布局；文件夹图标改为黄色；活动行改为绿色高亮；调整缩进和行高；优化树头部样式
+  - 完成标准: 目录树视觉匹配目标截图（紧凑行、黄色文件夹、绿色活动高亮、无卡片边框）
+  - 验证方式: 视觉对比目标截图
+  - depends_on: []
+
+- [ ] 1.2 重设计工具栏 — 紧凑纯图标按钮
+  - 文件: `packages/frontend/src/components/FileManager.vue` (模板 lines 2371-2441)
+  - 预期变更: 移除按钮文字标签，保留纯图标；统一按钮尺寸 `w-7 h-7`；上传文件和上传文件夹合并为下拉菜单按钮
+  - 完成标准: 工具栏为纯图标按钮行，上传为下拉菜单
+  - 验证方式: 视觉对比目标截图，检查 tooltip 显示
+  - depends_on: []
+
+### 阶段2: 传输管理面板
+
+- [ ] 2.1 创建 TransferPanel.vue 组件
+  - 文件: `packages/frontend/src/components/TransferPanel.vue` (新建)
+  - 预期变更: 底部抽屉面板组件，含"全部/上传/下载"tab，统一展示上传和传输任务，空态"暂无传输任务"
+  - 完成标准: 组件独立运行，支持 tab 切换和空态展示
+  - 验证方式: 组件接收 props 正确渲染
+  - depends_on: []
+
+- [ ] 2.2 集成 TransferPanel 到 FileManager
+  - 文件: `packages/frontend/src/components/FileManager.vue`
+  - 预期变更: 在文件管理器底部集成 TransferPanel，替代原 FileUploadPopup 的固定定位弹窗；添加传输面板展开/收起切换
+  - 完成标准: 传输面板在文件管理器底部正确展示，上传任务和传输任务统一显示
+  - 验证方式: 触发上传后传输面板展示任务
+  - depends_on: [2.1]
+
+### 阶段3: 书签系统重构
+
+- [ ] 3.1 后端数据库 migration — 添加 scope 字段
+  - 文件: `packages/backend/src/database/schema.ts`, `packages/backend/src/database/migrations/`
+  - 预期变更: `favorite_paths` 表新增 `scope` TEXT 字段（默认 'global'）和 `connection_id` INTEGER 字段（nullable）；编写 migration 脚本确保现有数据兼容
+  - 完成标准: 数据库表结构包含新字段，现有数据 scope 默认为 'global'
+  - 验证方式: 检查 schema 定义和 migration 逻辑
+  - depends_on: []
+
+- [ ] 3.2 后端 API 扩展 — scope 查询支持
+  - 文件: `packages/backend/src/favorite-paths/favorite-paths.routes.ts`, `packages/backend/src/favorite-paths/favorite-paths.repository.ts`
+  - 预期变更: GET /favorite-paths 支持 `?scope=local&connectionId=X` 查询参数；POST/PUT 支持 scope 和 connection_id 字段
+  - 完成标准: API 正确按 scope 和 connectionId 过滤/保存书签
+  - 验证方式: API 请求测试
+  - depends_on: [3.1]
+
+- [ ] 3.3 前端 store 扩展 — scope 支持
+  - 文件: `packages/frontend/src/stores/favoritePaths.store.ts`
+  - 预期变更: `FavoritePathItem` 类型添加 `scope` 和 `connectionId` 字段；CRUD 方法传递 scope 参数；新增 `activeTab` 状态和 `fetchByScope` 方法
+  - 完成标准: Store 支持按 scope 筛选和保存书签
+  - 验证方式: Store 方法调用正确传参
+  - depends_on: [3.2]
+
+- [ ] 3.4 重设计 FavoritePathsModal — 书签列表 UI
+  - 文件: `packages/frontend/src/components/FavoritePathsModal.vue`
+  - 预期变更: 头部显示"书签列表 N"；添加"本地"/"云端"tab 切换；每个书签卡片显示 scope 标签和操作按钮
+  - 完成标准: 书签列表 UI 匹配目标截图，支持 tab 切换筛选
+  - 验证方式: 视觉对比目标截图
+  - depends_on: [3.3]
+
+- [ ] 3.5 重设计 AddEditFavoritePathForm — 添加 scope 选择器
+  - 文件: `packages/frontend/src/components/AddEditFavoritePathForm.vue`
+  - 预期变更: 在表单中新增"记录位置"scope 选择器（仅当前服务器/全局共享），保存时传递 scope 和 connectionId
+  - 完成标准: 表单支持选择书签 scope
+  - 验证方式: 创建书签时 scope 正确保存
+  - depends_on: [3.3]
+
+### 阶段4: i18n 与收尾
+
+- [ ] 4.1 添加 i18n 键
+  - 文件: `packages/frontend/src/locales/zh-CN.json`, `en-US.json`, `ja-JP.json`
+  - 预期变更: 添加传输面板、书签 scope、工具栏 tooltip 相关的所有新 i18n 键
+  - 完成标准: 所有新增 UI 文本均使用 i18n 键，三种语言文件同步更新
+  - 验证方式: 搜索硬编码字符串
+  - depends_on: [1.1, 1.2, 2.1, 3.4, 3.5]
+
+## 执行日志
+
+| 时间 | 事件 | 详情 |
+|------|------|------|
+| 2026-05-01 21:25:50 | 进度快照(自动) | 完成:0 失败:0 跳过:0 待做:10 (0%) |
+| 2026-05-01 21:27:46 | 进度快照(自动) | 完成:0 失败:0 跳过:0 待做:10 (0%) |
+| 2026-05-01 21:28:56 | 进度快照(自动) | 完成:0 失败:0 跳过:0 待做:10 (0%) |
+| 2026-05-01 21:33:06 | 进度快照(自动) | 完成:0 失败:0 跳过:0 待做:10 (0%) |
+| 2026-05-01 21:35:15 | 进度快照(自动) | 完成:0 失败:0 跳过:0 待做:10 (0%) |
+
+## 执行备注
+
+- FileManager.vue 约 2570 行，修改时需精确定位模板区域避免副作用
+- 数据库 migration 需确保 SQLite 兼容（ALTER TABLE ADD COLUMN）
+- 传输面板需同时消费 uploads（本地 ref）和 transferTasks（API 轮询）两个数据源
@@ -0,0 +1 @@
+2026-05-01T21:36:14.234134