Imported from xjkuchao/tao-player (AGENTS.md). Install upstream with npx skills add xjkuchao/tao-player. Copyright stays with the author.

AGENTS.md

Tao Player 统一 AI 开发规范, 适用于所有 AI 工具。

1. 总体原则

• 项目定位: 跨平台高性能多媒体播放器, 纯 Rust 构建。以广泛的视频格式兼容性和高效播放性能为核心目标, 编解码能力对标 FFmpeg/PotPlayer。
• 多媒体引擎由 tao 项目提供, 本项目专注于播放器应用层。
• 技术栈: Rust + iced(GUI) + wgpu(视频渲染) + cpal(音频输出)。
• 规则优先级: 安全与正确性 > 用户体验 > 跨平台兼容 > 性能 > 开发效率。

2. 语言规范

• 重要: 项目内容统一使用中文(注释、日志、错误信息、AI 输出、文档), 标点用英文标点。
• 所有标识符(变量/函数/类型/文件名/目录名)只能使用英文。
• UI 文本通过 i18n(t!())引用, 禁止硬编码。
• 提交信息使用中文。

3. 项目结构

tao-player/
├── scripts/build.py        # 跨平台构建脚本
├── bin/                     # 运行目录(可执行文件+配置+日志)
│   ├── TaoPlayer            # 编译产物(不入 Git)
│   ├── config.toml          # 运行时配置(入 Git)
│   ├── locales/             # 外置语言文件(社区翻译, 入 Git)
│   │   └── ko.json          # 韩语示例(外部翻译模板)
│   └── logs/                # 日志(不入 Git)
├── src/                     # Rust 源码(iced 应用)
│   ├── app.rs               # 应用主体(状态 + 消息 + 更新 + 视图)
│   ├── main.rs              # 入口(配置加载 + 日志初始化 + i18n)
│   ├── shortcuts.rs         # 全局快捷键映射
│   ├── i18n.rs              # 国际化模块(内嵌 + 外置双轨加载)
│   ├── config/              # 配置模块(TOML 读写)
│   ├── logging/             # 日志模块(tracing 双输出 + 翻滚压缩)
│   ├── player/              # 播放器核心
│   │   ├── pipeline.rs      # 解码管线(独立线程)
│   │   ├── audio.rs         # cpal 音频输出
│   │   └── clock.rs         # 音视频同步时钟(MediaClock)
│   ├── ui/                  # UI 组件
│   │   ├── top_bar.rs       # 标题栏(拖拽 + 窗口控制)
│   │   ├── bottom_bar.rs    # 控制栏(播放/进度/音量)
│   │   ├── video_area.rs    # 视频区(wgpu shader 渲染)
│   │   ├── context_menu.rs  # 右键菜单
│   │   ├── command_palette.rs # 命令面板(Ctrl+K)
│   │   ├── playlist.rs      # 播放列表抽屉
│   │   └── settings/        # 设置面板(基础 + 高级)
│   └── shaders/
│       └── yuv_to_rgb.wgsl  # YUV→RGB 转换着色器
├── locales/                 # 内嵌语言源文件(编译时 include_str!)
│   ├── en-US.json           # 英文(内嵌, fallback)
│   └── zh-CN.json           # 简体中文(内嵌)
├── plans/                   # 执行计划
└── tests/                   # Rust 集成测试

• 依赖方向: UI 层 -> 播放器核心 -> tao 引擎。
• 播放管线: 文件/URL -> Demuxer -> Decoder -> 音视频同步 -> wgpu 渲染 / cpal 输出。
• 严禁在根目录随意新增文件。允许: 项目配置文件、README.md/AGENTS.md/LESSONS_LEARNED.md、LICENSE*。

4. 构建与调试

python scripts/build.py          # 构建(cargo build --release, 部署到 bin/)
cd bin && ./TaoPlayer            # 运行
cd bin && timeout 10 ./TaoPlayer # AI 调试(带超时)

注意: 也可直接 cargo build --release 然后手动拷贝到 bin/, 或用 cargo run 调试。

5. Rust 代码规范

5.1 代码组织

• 应用使用 iced 0.14, 单二进制纯 Rust 架构, 无前后端分离。
• 状态集中在 App 结构体, 按 iced Elm 架构组织: State + Message + update + view。
• UI 组件按功能域分文件(src/ui/), 业务逻辑不直接写在视图函数中。
• 与 tao 引擎交互通过 player/ 模块封装, 解码在独立线程中运行。

5.2 UI/UX

• 沉浸式设计: 内容即 UI, 默认隐藏, 悬停显露。参考 IINA 设计语言。
• 无边框窗口(decorations: false), 自定义 TopBar 支持拖拽和窗口控制。
• 控制栏: 底部浮动, 静止 3 秒自动隐藏。
• 默认暗色主题, Command Palette(Ctrl+K)。
• 视频渲染: 自定义 iced::widget::shader + WGSL 着色器(YUV420p→RGB)。
• 图标规范(强制): 所有 UI 图标统一使用内联 SVG(&[u8] 常量 + iced::widget::svg), 禁止使用 Unicode 字符(如 \u{2715}, \u{25A1} 等)作为图标。SVG 风格要求: 白色描边/填充、圆角线帽(stroke-linecap="round")、viewBox 0 0 12 12 或 0 0 24 24。公共图标(如关闭按钮)定义在 src/ui/mod.rs 中复用。

5.3 国际化(i18n)

• 自定义实现(src/i18n.rs), 不依赖 rust-i18n crate。采用内嵌 + 外置双轨加载架构。
• 内嵌语言(编译进二进制): locales/en-US.json 和 locales/zh-CN.json, 通过 include_str! 嵌入, 确保单可执行文件即可运行。
• 外置语言(运行时加载): bin/locales/*.json, 用于社区翻译的额外语言。外置语言文件必须包含三个元数据字段: _tao_i18n(标识符), _locale(语言代码), _locale_name(界面显示名)。若 locale 代码与内嵌语言冲突则自动跳过。
• bin/locales/ko.json 为韩语翻译示例, 作为外部翻译模板。
• 所有界面文本必须用 t!() 宏引用翻译 key, 禁止硬编码。
• key 用点分命名空间(如 contextMenu.openFile)。新增文本须同时更新三个文件: locales/en-US.json、locales/zh-CN.json、bin/locales/ko.json。
• 缺失翻译自动 fallback 到 en-US 对应值。
• 运行时可通过右键菜单或设置面板切换语言, 切换后立即保存配置。
• 技术性标识(快捷键、倍速、比例)无需翻译。

6. Rust 编码规范

• 重量级操作(文件打开、解码)在独立线程中运行, 通过 channel 通信, 不阻塞 UI。
• 错误处理用 anyhow(应用层) + thiserror(库层), 禁止无依据 unwrap()/expect()。
• 核心状态用 Arc<Mutex<>> 或原子类型, 确保线程安全。
• 禁止 todo!() 进入可执行路径。
• unsafe 必须有 // SAFETY: 注释。
• rustfmt 行宽 100, 缩进 4 空格。

7. 配置与窗口管理

• 配置: TOML 格式, 从可执行文件目录加载, 不存在时自动生成, 所有字段有 Default。
• 窗口状态持久化: 位置、大小、最大化状态保存到 config.toml, 下次启动自动恢复。

8. 日志规范

• 使用 tracing。日志内容中文。
• 级别: error(不可恢复) / warn(可恢复) / info(生命周期) / debug(内部状态) / trace(每帧)。
• 禁止热路径用 info! 以上, 禁止正常流程记为 error!/warn!。
• 双输出: Console(彩色 debug) + File(无 ANSI), 日期翻滚, 历史压缩(flate2), 过期清理(默认 30 天)。

9. 质量与安全

• 所有 I/O 显式处理错误, 禁止吞错。媒体解码错误降级(跳帧/静音), 不崩溃。
• 禁止保留调试代码(println!/调试分支/未使用导入)。
• 禁止硬编码密钥/令牌/密码, 禁止提交敏感文件。
• 所有外部输入必须校验。
• 注释用中文, 公开 API 用 ///。unsafe 必须 // SAFETY:。

10. 性能规范

• 视频渲染路径减少分配, 优先借用与复用, 大数据零拷贝。
• 音视频同步精度毫秒级。热路径避免多余分支与格式化开销。
• 性能优化需可测量。

11. 测试规范

• 测试文件: tests/{feature}_test.rs, 函数: test_{component}_{scenario}。
• 单元测试(#[cfg(test)]) + 集成测试(tests/)。
• 测试数据来源: 代码内构造 > 固定远程 URL。禁止依赖本地临时文件。
• 大型测试用 #[ignore] 并说明触发条件。

12. 跨平台规范

• Windows/macOS/Linux 功能一致。平台特有行为通过 iced API 或 #[cfg] 抽象。
• 平台相关代码用 #[cfg(target_os = "...")] 隔离。
• 路径用 std::path::PathBuf, 禁止硬编码分隔符。

13. 提交规范

完成功能后必须按序执行以下全部检查, 全部通过后方可提交代码。

Rust — 4 项

1. cargo fmt --all -- --check — 格式化检查
2. cargo clippy --all-targets --all-features -- -D warnings — Lint 检查
3. cargo check --all-targets --all-features — 编译检查
4. cargo test --all-targets --all-features --no-fail-fast — 测试

提交信息

格式: feat/fix/refactor/style/chore/test/docs/ui: 中文描述。仅包含本轮任务相关文件。

14. 执行计划

多步骤或跨模块任务须在 plans/ 写计划文件({模块}_{描述}.md), 含: 背景目标、分步任务、依赖、验收标准、进度标记。

15. 冲突优先级

安全与稳定性 > 用户体验 > 跨平台兼容 > 架构一致性 > 性能 > 开发效率。