# Kwai-Video-Assistant
**Repository Path**: yangleduo7788/kwai-video-assistant
## Basic Information
- **Project Name**: Kwai-Video-Assistant
- **Description**: 快手视频助手是一个基于 Flet 的桌面端快手视频检索与播放工具,提供扫码登录、关键词搜索、沉浸式播放、上下切换视频等能力,适用于本地内容检索与辅助浏览场景。
项目当前采用 Python 单体结构,界面层由 Flet 实现,登录、搜索和本地视频代理能力由业务模块统一承载。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: Python, flet
## README
# 快手视频助手





## 1. 项目简介
快手视频助手是一个基于 `Flet` 的桌面端快手视频检索与播放工具,提供扫码登录、关键词搜索、沉浸式播放、上下切换视频等能力,适用于本地内容检索与辅助浏览场景。
项目当前采用 Python 单体结构,界面层由 `Flet` 实现,登录、搜索和本地视频代理能力由业务模块统一承载。
## 2. 版本信息
| 项目 | 信息 |
| --- | --- |
| 项目名称 | 快手视频助手 |
| 当前版本 | v1.0.0 |
| 版本阶段 | Release Candidate |
| 文档版本 | v1.1 |
| 文档更新日期 | 2026-07-06 |
| UI 技术栈 | Flet |
| 视频播放组件 | flet-video |
| 自动化能力 | Playwright |
| 运行模式 | Windows 本地桌面应用 |
说明:
- 当前 README 已按 Gitee 常见项目展示方式补充版本信息。
- 当前版本号用于项目发布说明与仓库展示,建议后续与代码内常量或发布标签保持一致。
- 后续建议按 `SemVer` 维护,例如 `v1.0.0`、`v1.1.0`、`v1.1.1`。
## 3. 真机截图
### 3.1 截图展示位

## 4. 核心功能
- 扫码登录快手并持久化本地登录态
- 基于关键词搜索快手视频内容
- 使用右侧播放器区域进行沉浸式视频播放
- 支持视频上下切换与连续浏览
- 通过本地代理提升视频播放稳定性
- 展示作者、封面、基础统计信息等内容
## 5. 技术架构
### 5.1 架构说明
项目采用单体桌面应用架构,核心模块职责如下:
- `kuaishou_gui.py`:界面渲染、交互事件处理、播放器控制
- `kuaishou_api.py`:登录态管理、搜索请求、本地代理服务、浏览器驱动
- `kuaishou_crawler.py`:爬取或辅助请求相关逻辑
- `icons/`:界面图标资源目录
### 5.2 运行链路
1. 启动 `Flet` 桌面界面
2. 检查本地 `cookies.json` 登录态
3. 未登录时通过 `Playwright` 拉起浏览器扫码登录
4. 登录成功后保存登录态并执行搜索请求
5. 通过本地代理地址向播放器提供视频流
## 6. 目录结构
```text
.
├─ assets/
│ └─ screenshots/ # 真机截图资源目录
├─ icons/ # SVG 图标资源
├─ cookies.json # 本地登录态文件,仅本机使用,不可提交
├─ kuaishou_api.py # 登录、搜索、代理服务
├─ kuaishou_crawler.py # 抓取辅助模块
├─ kuaishou_gui.py # Flet 图形界面主程序
├─ requirements.txt # Python 依赖清单
└─ README.md # 项目说明文档
```
## 7. 运行环境
### 7.1 基础环境
- 操作系统:Windows
- Python:建议 `3.11+`
- 浏览器依赖:`Playwright Chromium`
### 7.2 依赖版本
基于 [requirements.txt](file:///d:/yangleduo/Code/Python/快手/requirements.txt) 当前配置:
- `flet>=0.85.0`
- `flet-video>=0.85.0`
- `pycryptodome>=3.19.0`
- `requests>=2.31.0`
- `playwright>=1.40.0`
## 8. 安装部署
### 8.1 安装步骤
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium
```
### 8.2 启动方式
```bash
python kuaishou_gui.py
```
## 9. 使用说明
1. 启动应用后,点击界面中的“立即登录”。
2. 系统将拉起浏览器并展示快手登录页面。
3. 使用快手 App 扫码完成登录。
4. 登录成功后,在顶部输入关键词并执行搜索。
5. 点击搜索结果后,视频会在主界面播放器区域播放。
6. 可通过界面按钮进行上下切换视频。
## 10. 登录态说明
- 本地登录态默认保存在 `cookies.json`
- 删除 `cookies.json` 不会导致功能失效,但会丢失已保存的登录状态
- 当 `cookies.json` 不存在时,系统会要求重新扫码登录
- `cookies.json` 属于敏感本地文件,禁止提交到代码仓库
## 11. 开发规范
### 11.1 基本要求
- 所有说明文档统一使用中文
- 代码提交信息优先使用中文
- 本地登录态、缓存文件、调试产物不得入库
- 修改功能时优先保证可维护性和稳定性
### 11.2 提交规范
推荐使用中文语义化提交信息,例如:
```text
feat: 优化快手视频搜索与播放交互
fix: 修复视频切换后黑屏问题
docs: 重写项目说明文档并补充版本信息
```
## 12. 安全说明
- `cookies.json` 包含本地登录态信息,仅允许本机保存
- 不要将登录态文件发送给他人或上传到远程仓库
- 提交代码前应确认 `.gitignore` 已正确忽略敏感文件
## 13. 发布规范
- 建议 `git tag`、README 版本号、发布包版本保持一致
- 建议发布命名格式使用 `v主版本.次版本.修订版本`
- 建议每次发版同步维护“版本信息”和“更新记录”
示例:
```text
v1.0.0 首个可用版本
v1.1.0 新增功能发布
v1.1.1 缺陷修复发布
```
## 14. 更新记录
### v1.0.0
- 完成基于 `Flet` 的桌面端界面重构
- 支持扫码登录、搜索视频、沉浸式播放
- 支持本地代理视频流播放
- 支持上下切换视频及基础信息展示
## 15. 已知说明
- 当前项目主界面已完全切换为 `Flet`
- 应用运行依赖本地浏览器能力与 `Playwright`
- 若首次运行浏览器失败,请先执行 `playwright install chromium`