docs: 更新 AGENTS.md,同步近期架构变更

This commit is contained in:
小鱼开发
2026-05-04 19:40:05 +08:00
parent 6c0f240369
commit 4c683bec52
+10 -11
View File
@@ -10,7 +10,7 @@
- **产品标识**: `cn.meijiaka.ai-video` / `cn.meijiaka.ai-jian`
- **版本**: `0.1.0`
- **核心功能**: AI 脚本生成、AI 配音(TTS)、数字人视频生成、声音复刻、视频字幕生成、视频合成(FFmpeg)、项目本地持久化
- **核心功能**: AI 脚本生成、AI 配音(TTS)、声音复刻、对口型、视频字幕生成、视频合成(FFmpeg)、项目本地持久化
### 技术栈总览
@@ -57,7 +57,7 @@ python-api/
│ ├── models/ # SQLAlchemy ORM 模型(BaseModel 提供 UUID 主键 + 时间戳)
│ ├── schemas/ # Pydantic Schema(请求/响应校验)
│ ├── services/ # 业务逻辑层
│ ├── scheduler/ # Async Engine 异步任务调度(Slot Manager + Job Registry + Handlers
│ ├── scheduler/ # Async Engine 异步任务调度(Slot Manager + Task Registry + Handlers
│ ├── ai/ # AI 模型封装(providers: volcengine, vidu, generic_llm
│ ├── crud/ # 数据库 CRUD 封装
│ ├── config.py # Pydantic Settings 配置管理
@@ -66,7 +66,6 @@ python-api/
├── alembic/ # 数据库迁移脚本
├── nginx/ # Nginx 反向代理配置(含 acme.sh SSL 证书脚本)
├── Dockerfile # 多阶段构建镜像(builder + production
├── docker-compose.yml # 开发环境编排(api + scheduler,共享外部 db/redis
├── docker-compose.prod.yml # 生产环境编排
├── docker-compose.test.yml # 测试环境编排
├── pyproject.toml # Python 依赖与工具配置(black, ruff, mypy, pytest, bandit
@@ -122,7 +121,8 @@ tauri-app/
采用**混合通信架构**
1. **纯数据 API**脚本生成、配音、视频生成、字幕、任务查询等)→ 前端通过 HTTP **直连 Python 后端**
1. **纯数据 API**配音、字幕、任务查询等)→ 前端通过 HTTP **直连 Python 后端**
- 脚本生成走异步任务调度(`POST /tasks/script` + 轮询),由 Scheduler 独立进程消费。
2. **需要本地系统能力**(FFmpeg 视频合成、文件系统读写、项目本地持久化、认证状态存储)→ 走 **Tauri IPC → Rust 层** 处理。
> 新增纯数据 API 时,**无需修改 Rust 代码**,直接在 `tauri-app/src/api/modules/` 下使用 `client.post/get` 调用即可。只有涉及本地系统能力的 API 才需要在 Rust 层新增 `#[tauri::command]`。
@@ -285,9 +285,8 @@ npm run gen:api # 根据 openapi.json 生成 TypeScript 类型
### 语义层防护网(后端)
Makefile 中 `lint-semantic` 目标会检查以下规则:
- API 层禁止使用 `element_id` 作为字段/参数名(应使用 `provider_element_id``human_id`)。
- Scheduler 层禁止使用 `task_id` 作为内部变量/Redis key(应使`job_id`
- Scheduler 层 Redis key 必须使用 `job:` 前缀而非 `task:`
- API 层禁止使用 `element_id` 作为字段/参数名(应使用 `provider_element_id`)。
- Scheduler 层统一使用 `task` 命名(`TaskRegistry``task_id``task:` Redis key 前缀),禁止混`job`
---
@@ -380,12 +379,12 @@ Makefile 中 `lint-semantic` 目标会检查以下规则:
## 异步任务调度(Async Engine
后端采用自研的**统一异步作业调度引擎**,核心概念:
后端采用自研的**统一异步任务调度引擎**,核心概念:
- **JobRegistry**: 基于 Redis 的作业注册表,维护 running / pending / finished 状态。
- **SlotManager**: 基于 Redis 的并发槽位管理,按 job_type 限制最大并发数。
- **TaskRegistry**: 基于 Redis 的任务注册表,维护 running / pending / finished 状态。
- **SlotManager**: 基于 Redis 的并发槽位管理,按 task_type 限制最大并发数。
- **AsyncHandler**: 各领域的异步任务处理器(如 `script_handler.py`, `subtitle_handler.py`)。
- **Engine Tick**: 定时轮询所有 running 作业,批量查询状态、批量更新。
- **Engine Tick**: 定时轮询所有 running 任务,批量查询状态、批量更新。
调度器需单独启动:`make scheduler``python -m app.scheduler.main`