# AGENTS.md

## 项目目标

这个项目要实现一个可被 `aIzhinengti` 数字人 `自主算力机` 模式调用的音频驱动视频口型同步服务。

必须长期保持兼容：

- Gradio 服务地址示例：`http://127.0.0.1:7860/`
- API name：`/process_single`
- 输入参数名：`audio_file`、`video_file`
- 返回值：单个 `gr.Video` 输出，Gradio client 侧应能拿到包含 `video` 路径的数据

## 开发边界

- 不要在未得到用户明确许可前下载模型权重或大文件。
- 不要把模型权重提交到项目中；只写下载/放置说明。
- 默认 `ffmpeg_mux` 后端只用于联调，不代表真实口型同步效果。
- 真实推理应通过 `command` 后端或新增专用后端接入 Wav2Lip、MuseTalk、LstmSync 等模型。
- 保持项目可独立运行，不反向依赖 `aIzhinengti` 源码。

## 代码风格

- Python 目标版本：3.10+。
- 依赖管理使用 `uv`，以 `pyproject.toml` / `uv.lock` 为准，不再新增 `requirements.txt`。
- 保持入口简单：`python -m digital_human_lipsync_service`。
- 后端适配逻辑放在 `src/digital_human_lipsync_service/backends.py` 或后续拆分到 `src/digital_human_lipsync_service/backends/`。
- 配置优先用环境变量；新增变量同步更新 `.env.example` 和文档。
- 错误要包含可定位信息，但不要泄露密钥。

## 验收优先级

1. `aIzhinengti` 的 `scripts/digital_human_process.py` 能调用成功。
2. 服务能在 Windows 本机和局域网 GPU 机器启动。
3. `command` 后端可稳定调用真实模型并产出 mp4。
4. 日志、临时文件、输出文件可控且可清理。