William
e8c3e4644e
CI / lint-and-build (push) Has been cancelled
- Swift 6 + SwiftUI + SwiftData 直接调用阿里云 VOD API - 自实现 POP 签名，无需 Node 后端 - 视频列表、搜索、批量下载到用户选择目录 - 下载文件自动使用视频标题重命名 - 浏览器下载与下载工具（aria2/wget）两种方式 - Web 版标记为废弃，README/AGENTS/MEMORY 更新
87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# 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 调用统一封装在 `VODClient` actor 中。
|
||
- 下载任务使用 `URLSessionDownloadTask`，文件名自动清理非法字符。
|
||
|
||
### 安全要求
|
||
|
||
- AccessKey Secret 存储在 SwiftData 中，建议后续接入 Keychain 加密存储。
|
||
- 阿里云 API 调用直接从客户端发起，不经过第三方后端。
|
||
- 建议用户创建最小权限 RAM 子用户。
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 构建 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`：下载任务历史
|
||
|
||
## 贡献注意事项
|
||
|
||
1. macOS 修改后必须能通过 `swift build`。
|
||
2. 提交信息使用中文，描述清晰。
|
||
3. 涉及 SwiftData schema 变更时，需考虑现有用户数据迁移。
|