William
e8c3e4644e
CI / lint-and-build (push) Has been cancelled
- Swift 6 + SwiftUI + SwiftData 直接调用阿里云 VOD API - 自实现 POP 签名，无需 Node 后端 - 视频列表、搜索、批量下载到用户选择目录 - 下载文件自动使用视频标题重命名 - 浏览器下载与下载工具（aria2/wget）两种方式 - Web 版标记为废弃，README/AGENTS/MEMORY 更新
2.7 KiB
2.7 KiB
AGENTS.md
本项目（火炬 VOD 管理器）的代理开发指南。
项目背景
一个轻量、开源的阿里云视频点播（VOD）媒体资源管理工具，核心目标是解决阿里云官方 VOD 控制台在查看、批量下载、批量删除大量视频时操作繁琐的问题。
- 名称：火炬 VOD 管理器
- 许可证：MIT
- 用户群体：开发者、内容运营人员
- 部署方式：macOS 原生应用（目标上架 Mac App Store）
技术栈
- 客户端：Swift 6 + SwiftUI + SwiftData
- 阿里云 API：自实现 POP 签名，直接调用 VOD OpenAPI
- 网络：URLSession
- 持久化：SwiftData（SQLite）
历史版本（已废弃）：React 18 + Express + SQLite 的 Web 版保留在
apps/web和apps/server，不再维护。
目录结构
.
├── apps/
│ ├── macos/ # macOS 原生 SwiftUI 应用
│ │ └── VODManager/
│ ├── web/ # React 前端（已废弃，历史参考）
│ └── server/ # Express 后端（已废弃，历史参考）
├── docs/ # 部署与使用文档
├── PRD.md # 产品需求文档
├── README.md
└── AGENTS.md # 本文件
开发规范
代码风格
- 使用 Swift 6，严格并发检查。
- SwiftData 模型类使用
@Model，避免在并发任务中直接传递@Model实例。 - UI 使用 SwiftUI，状态管理使用
@StateObject/@ObservedObject/@Query。 - 阿里云 API 调用统一封装在
VODClientactor 中。 - 下载任务使用
URLSessionDownloadTask，文件名自动清理非法字符。
安全要求
- AccessKey Secret 存储在 SwiftData 中，建议后续接入 Keychain 加密存储。
- 阿里云 API 调用直接从客户端发起，不经过第三方后端。
- 建议用户创建最小权限 RAM 子用户。
常用命令
# 构建 macOS 应用
cd apps/macos/VODManager
swift build
# 运行
cd apps/macos/VODManager
swift run
# 在 Xcode 中打开
open apps/macos/VODManager/Package.swift
App Store 注意事项
- 必须开启 App Sandbox。
- 使用
com.apple.security.network.client访问阿里云 API。 - 使用
com.apple.security.files.user-selected.read-write让用户选择下载目录。 - 默认下载到应用沙盒内部，提供「导出」功能让用户移动到外部目录。
数据库模型
Account：阿里云账号配置OperationLog：操作日志DownloadTask：下载任务历史
贡献注意事项
- macOS 修改后必须能通过
swift build。 - 提交信息使用中文，描述清晰。
- 涉及 SwiftData schema 变更时，需考虑现有用户数据迁移。