diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0095fff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# 低端影视 (DDYS Client)
+
+原生 SwiftUI 客户端，用于浏览 [ddys.io](https://ddys.io) 影视资源，支持 macOS / iPadOS / iOS。
+
+## 功能
+
+- **首页推荐** — 热门推荐横向滚动 + 最新更新网格展示
+- **分类浏览** — 电影、电视剧、综艺、动漫四大板块，支持排序 / 类型 / 地区 / 年份筛选
+- **全局搜索** — 首页搜索栏，回车触发，支持分页加载更多
+- **详情页** — 海报、评分、年份、地区、类型标签、剧情简介、导演、主演
+- **在线播放** — HLS (m3u8) 原生播放，多播放源切换，剧集选择
+- **播放器** — macOS 独立窗口（可调整大小、全屏），iOS 全屏播放，支持倍速、画中画
+- **观看进度** — 自动保存 / 恢复播放进度
+- **图片缓存** — 双层缓存（NSCache 内存 + URLCache 磁盘），切换页面秒加载
+- **数据缓存** — Tab 切换保留数据，5 分钟 TTL 自动刷新
+- **认证支持** — WebView 登录 或 手动 Cookie 输入
+
+## 技术栈
+
+| 项目 | 选型 |
+|------|------|
+| UI 框架 | SwiftUI (iOS 17+ / macOS 14+) |
+| HTML 解析 | [SwiftSoup](https://github.com/scinfu/SwiftSoup) 2.6.1 (本地包，零外部依赖) |
+| 视频播放 | AVKit (AVPlayerView / AVPlayerViewController) |
+| 网络请求 | URLSession |
+| 数据解析 | JSON-LD + SwiftSoup CSS 选择器 |
+| 持久化 | UserDefaults |
+| 导航 | NavigationSplitView (Mac/iPad) / TabView (iPhone) |
+
+## 项目结构
+
+```
+DDYSClient/
+├── App/                    # 入口 & 根视图
+├── Models/                 # 数据模型 (ContentItem, Episode, StreamSource...)
+├── Services/               # 网络层 & 业务服务
+│   ├── APIClient.swift     # URLSession 请求封装
+│   ├── HTMLParser.swift    # SwiftSoup 解析列表/详情/分页
+│   ├── CookieManager.swift # Cookie 存储与注入
+│   ├── ContentCache.swift  # 数据缓存 (5min TTL)
+│   └── WatchProgressStore.swift  # 观看进度持久化
+├── ViewModels/             # MVVM ViewModel (@Observable)
+├── Views/
+│   ├── Navigation/         # 平台自适应导航
+│   ├── Home/               # 首页 + 搜索
+│   ├── Browse/             # 分类浏览 + 筛选
+│   ├── Detail/             # 详情页 + 剧集列表
+│   ├── Player/             # 视频播放器
+│   ├── Common/             # 通用组件 (CachedAsyncImage)
+│   ├── Auth/               # 认证 (WebView / Cookie 输入)
+│   ├── Search/             # 搜索页
+│   └── Settings/           # 设置页
+└── Utilities/              # 通用扩展
+```
+
+## 构建 & 运行
+
+### 环境要求
+
+- macOS 14.0+
+- Swift 5.9+
+- Xcode 15+ (或 Swift 命令行工具)
+
+### 命令行构建
+
+```bash
+# Debug
+swift build
+
+# Release
+swift build -c release
+```
+
+### 打包为 .app
+
+```bash
+# 构建 Release
+swift build -c release
+
+# 复制到 app bundle
+cp "$(swift build -c release --show-bin-path)/DDYSClient" /path/to/DDYSClient.app/Contents/MacOS/DDYSClient
+```
+
+### 安装
+
+```bash
+cp -R DDYSClient.app /Applications/低端影视.app
+```
+
+## 使用说明
+
+1. 启动应用后首页自动加载热门推荐和最新更新
+2. 通过左侧边栏切换 电影 / 电视剧 / 综艺 / 动漫
+3. 使用顶部筛选栏按 排序 / 类型 / 地区 / 年份 过滤内容
+4. 首页搜索栏输入关键词，按回车搜索
+5. 点击卡片进入详情页，点击「立即播放」打开播放器窗口
+6. 如需登录，在 设置 → 认证 中通过 WebView 或手动输入 Cookie
+
+## 依赖
+
+- [SwiftSoup 2.6.1](https://github.com/scinfu/SwiftSoup/tree/2.6.1) — HTML 解析 (本地包，无网络依赖)
+
+## License
+
+MIT