TraceStudio-dev/docs/web1.1_filemanager/UPDATE_v0.2.1.md

TraceStudio v0.2.1 更新说明

🎉 多用户功能完善

✨ 新增功能

1. 工作流标题管理

• 位置: HeaderBar 顶部栏
• 功能:
  • 显示当前工作流名称
  • 点击标题可编辑
  • 支持 Enter 确认、Escape 取消
  • 默认标题: "未命名工作流"

2. 工作流保存

• 保存位置: cloud/users/{username}/workflows/
• 文件格式: .utrace (JSON)
• 保存内容:
  • 工作流标题
  • 所有节点和连线
  • 全局设置
  • 保存时间戳
• 操作方式: 点击标题旁边的 💾 按钮
• 提示: 保存成功后显示完整路径

3. 工作流加载

• 方式: 在文件浏览器中双击 .utrace 文件
• 效果: 自动加载所有节点、连线和设置
• 提示: 加载成功后显示工作流名称

4. 增强的用户切换器

新增输入框创建用户

┌─────────────────────────┐
│ 切换用户空间             │
├─────────────────────────┤
│ 创建/切换用户           │
│ [输入用户名...] [➕]   │
├─────────────────────────┤
│ ✓ guest                 │
│   admin                 │
│   dev                   │
│   test                  │
└─────────────────────────┘

操作方式

1. 下拉框: 点击用户按钮展开菜单
2. 创建: 在输入框输入用户名，按 Enter 或点击 ➕
3. 切换: 点击列表中的用户名
4. 预设用户: guest, admin, dev, test

特性

• 输入即创建，无需确认
• 自动创建用户目录结构
• 切换后文件浏览器自动刷新

5. 文件路径复制功能

右键菜单新增选项

┌─────────────┐
│ 📥 下载     │
│ 📋 复制路径 │  ← 新增
│ ✏️ 重命名   │
│ 🗑️ 删除    │
└─────────────┘

复制的路径格式

• 格式: 相对于根目录的相对路径
• 示例: users/guest/data/sample.csv
• 用途: 填入节点参数（如 CSVLoader 的 file_path）

使用流程

步骤1: 右键点击文件或文件夹
步骤2: 点击"📋 复制路径"
步骤3: 路径已复制到剪贴板
步骤4: 粘贴到节点参数输入框

---

📖 完整工作流

场景：数据分析工作流

1. 创建用户空间

点击用户按钮 → 输入 "analyst" → Enter
系统自动创建: users/analyst/workflows/

2. 上传数据文件

切换到"📁 文件"标签
导航到 users/analyst/data/
点击"📤 上传" → 选择 sales_data.csv

3. 创建工作流

拖拽 sales_data.csv 到画布
自动生成 CSVLoader 节点
file_path 自动填充: users/analyst/data/sales_data.csv

4. 编辑工作流标题

点击顶部"未命名工作流"
输入"销售数据分析"
按 Enter 确认

5. 添加处理节点

从节点面板拖入 Transform 节点
连接到 CSVLoader 输出
配置转换参数

6. 保存工作流

点击标题旁 💾 按钮
工作流保存到: users/analyst/workflows/销售数据分析.utrace
显示成功提示: ✅ 工作流已保存到: users/analyst/workflows/销售数据分析.utrace

7. 下次加载

切换到"📁 文件"标签
导航到 users/analyst/workflows/
双击 销售数据分析.utrace
工作流自动加载

---

🔧 技术细节

工作流文件格式 (.utrace)

{
  "title": "销售数据分析",
  "nodes": [
    {
      "id": "n_123_456",
      "type": "universal",
      "function": "Loader",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "CSV 数据加载器",
        "file_path": "users/analyst/data/sales_data.csv",
        "delimiter": ",",
        "meta": { ... }
      }
    }
  ],
  "edges": [ ... ],
  "globalSettings": {
    "sampleRate": 0.1,
    "timeRange": { "start": 0, "end": 1000 }
  },
  "savedAt": "2026-01-07T12:34:56.789Z"
}

路径规范

所有路径均为相对于 cloud/ 目录的相对路径：

类型	路径格式	示例
共享资源	shared/...	shared/examples/sample.csv
用户数据	users/{username}/data/...	users/guest/data/test.csv
工作流	users/{username}/workflows/...	users/admin/workflows/分析.utrace
结果	users/{username}/results/...	users/dev/results/output.csv
临时文件	temp/...	temp/cache_123.tmp

API 调用

保存工作流

const saveWorkflow = async () => {
  const blob = new Blob([JSON.stringify(workflowData)], { 
    type: 'application/json' 
  })
  const file = new File([blob], `${title}.utrace`, { 
    type: 'application/json' 
  })
  
  const formData = new FormData()
  formData.append('file', file)
  
  await fetch(`/api/files/upload?path=users/${user}/workflows&username=${user}`, {
    method: 'POST',
    body: formData
  })
}

加载工作流

const loadWorkflow = async (path: string) => {
  const response = await fetch(`/api/files/download?path=${encodeURIComponent(path)}`)
  const workflowData = await response.json()
  
  // 恢复状态
  setNodes(workflowData.nodes)
  setEdges(workflowData.edges)
  setWorkflowTitle(workflowData.title)
  setGlobalSettings(workflowData.globalSettings)
}

复制路径

const copyPath = async (path: string) => {
  await navigator.clipboard.writeText(path)
  // 路径格式: users/guest/data/file.csv
}

---

🎯 使用技巧

1. 工作流命名建议

• ✅ 使用描述性名称: 销售数据分析
• ✅ 包含日期: 数据清洗_20260107
• ✅ 区分版本: 模型训练_v1, 模型训练_v2
• ❌ 避免特殊字符: /\:*?"<>|

2. 文件组织建议

users/analyst/
├── workflows/
│   ├── 销售分析.utrace
│   ├── 库存统计.utrace
│   └── 月度报告.utrace
├── data/
│   ├── raw/          # 原始数据
│   ├── processed/    # 处理后的数据
│   └── backup/       # 备份
└── results/
    ├── 2026-01/      # 按月归档
    └── 2026-02/

3. 快捷键

• Enter: 确认编辑（标题、用户名）
• Escape: 取消编辑
• 双击: 加载 .utrace 工作流
• 右键: 打开文件菜单

4. 路径使用示例

CSVLoader 节点

file_path: users/guest/data/sales.csv

Transform 节点（如果需要输出）

output_path: users/guest/results/transformed.csv

共享数据

file_path: shared/examples/sample.csv

---

🐛 故障排除

问题1: 工作流保存失败

症状: 点击 💾 按钮后显示"❌ 保存失败"

原因:

• 后端服务未启动
• 用户目录不存在

解决:

# 检查后端是否运行
python -m uvicorn server.main:app --reload

# 检查 cloud 目录结构
ls cloud/users/{username}/workflows

问题2: 工作流加载失败

症状: 双击 .utrace 文件无响应

原因:

• 文件格式错误
• 文件损坏

解决:

• 用文本编辑器检查 .utrace 文件是否为有效 JSON
• 重新保存工作流

问题3: 路径复制不工作

症状: 右键点击"复制路径"无反应

原因:

• 浏览器不支持剪贴板 API
• 权限不足

解决:

• 使用现代浏览器（Chrome, Edge, Firefox）
• 允许剪贴板权限
• 降级方案会自动使用 execCommand

问题4: 用户切换后文件不见了

症状: 切换用户后文件列表为空

原因:

• 新用户目录尚未创建
• 正常隔离机制

解决:

• 上传文件到新用户空间
• 或从共享目录访问公共资源

---

📊 版本对比

功能	v0.2.0	v0.2.1
用户切换	✅ 按钮菜单	✅ 下拉框 + 输入框
工作流标题	❌	✅ 可编辑
工作流保存	❌	✅ 保存到服务器
工作流加载	❌	✅ 双击加载
路径复制	❌	✅ 右键菜单
文件浏览器	✅ 基础功能	✅ 增强交互

---

🚀 下一步计划

• 工作流版本管理（自动备份）
• 工作流模板系统
• 用户间共享工作流
• 工作流执行历史
• 文件搜索功能
• 批量文件操作
• 工作流预览图生成

---

版本: v0.2.1
更新日期: 2026-01-07
向后兼容: 是
需要后端更新: 否