From 4c683bec522d60e116f37800fc40fa348d99be27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E9=B1=BC=E5=BC=80=E5=8F=91?= Date: Mon, 4 May 2026 19:40:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS.md=EF=BC=8C?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=E8=BF=91=E6=9C=9F=E6=9E=B6=E6=9E=84=E5=8F=98?= =?UTF-8?q?=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 934f479..1fa7f2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`。