Skip to content

AGENTS.md

Latest commit

 

History

History
297 lines (251 loc) · 12.5 KB

AGENTS.md

File metadata and controls

297 lines (251 loc) · 12.5 KB
Raw

AI Agent 指南 - PHP-Stack 项目

本文档旨在帮助 AI Agent 快速理解 php-stack 项目的架构设计、代码规范及开发模式。

🏗️ 架构概览

项目采用 Tauri v2 典型的分层架构：

  • Frontend (UI 层): 位于根目录 src/。使用 Vue 3 + TypeScript。
    • App.vue: 主入口，包含侧边栏导航和全局状态管理（如 Docker 可用性、日志流）。
    • style.css: 集成了 Tailwind CSS v4。
  • Backend (逻辑层): 位于 src-tauri/src/。使用 Rust。
    • docker/: 封装 Docker 交互逻辑。
      • manager.rs: 使用 bollard 处理容器列表、启停逻辑。
      • mirror.rs: 处理 Docker 和 PHP 镜像源切换。
    • engine/: 核心业务引擎。
      • env_parser.rs: .env 文件解析器与格式化器（v0.1.0 新增）
      • config_generator.rs: 可视化配置生成器（v0.1.0 新增）
      • mirror_manager.rs: 统一镜像源管理器（v0.1.0 新增）
      • backup_manifest.rs: 备份清单数据模型（v0.1.0 新增）
      • backup_engine.rs: 增强备份引擎（v0.1.0 新增）
      • restore_engine.rs: 恢复引擎（v0.1.0 新增）
      • export.rs: 旧版导出引擎（保留向后兼容）
    • commands/: 暴露给前端的 #[tauri::command] 接口，按业务域拆分为子模块。
      • mod.rs: 模块声明、get_project_root() 共享函数、re-export 所有命令。
      • docker.rs: 容器 CRUD 操作（check_docker、list/start/stop/restart_container）。
      • env_config.rs: 环境配置生成、应用、启动/重启/停止环境。
      • mirror.rs: 镜像源预设管理、自定义配置、连接测试。
      • backup.rs: 备份创建、恢复预览/验证/执行、路径转换。
      • workspace.rs: 工作区管理、版本映射查询、用户覆盖、日志导出。
    • lib.rs: 插件注册与指令分发中心。

✅ v0.1.0 已完成功能

1. 可视化环境配置（EnvConfigPage）

  • 需求覆盖: 需求 1.1-1.9
  • 实现状态: ✅ 完成
  • 核心功能:
    • GUI 界面选择服务类型（PHP、MySQL、Redis、Nginx）及版本
    • 端口配置与实时冲突检测
    • PHP 扩展多选配置
    • 自动生成 .env 文件和 docker-compose.yml
    • 保留用户自定义变量
    • 支持多 PHP 版本独立服务

2. 统一镜像源管理（MirrorPanel）

  • 需求覆盖: 需求 2.1-2.7
  • 实现状态: ✅ 完成
  • 核心功能:
    • 5 个预设方案（阿里云、清华、腾讯云、中科大、官方默认）
    • 4 类镜像源独立配置（Docker Registry、APT、Composer、NPM）
    • 连接测试功能（3 秒超时）
    • 一键应用预设或单独配置

3. 环境备份（BackupPage）

  • 需求覆盖: 需求 3.1-3.8, 6.1-6.4
  • 实现状态: ✅ 完成
  • 核心功能:
    • ZIP 格式备份包，包含 manifest.json
    • 可选：数据库导出（mysqldump）、项目文件（glob 模式）、vhost 配置、日志
    • SHA256 文件完整性校验
    • Tauri 事件进度通知
    • 部分失败容错处理

4. 环境恢复（RestorePage）

  • 需求覆盖: 需求 4.1-4.10
  • 实现状态: ✅ 完成
  • 核心功能:
    • 备份包预览（manifest 解析、文件统计）
    • SHA256 完整性验证
    • 端口冲突检测与自动分配
    • 配置文件还原、数据库 SQL 执行
    • 进度通知与错误汇总

5. 基础设施模块

  • env_parser.rs: .env 文件可靠读写，保留注释和空行（Property 9, 10）
  • backup_manifest.rs: Manifest 序列化/反序列化（Property 11, 12）
  • 测试覆盖: 77 个测试全部通过（74 单元测试 + 3 集成测试），包括属性测试（proptest）

🛠️ 开发规范

Rust 后端

  1. 错误处理: 统一使用 Result<T, String> 或 Result<T, Box<dyn Error>>。暴露给前端的 Command 必须将错误转换为 String。
  2. 异步处理: 涉及 Docker 或文件 IO 的操作必须使用 async/await。
  3. 测试:
    • 单元测试：放在源文件内的 #[cfg(test)] mod tests { ... } 模块中
    • 集成测试：放在 src-tauri/tests/integration/ 目录下
    • 纯函数模块（env_parser、backup_manifest、config_generator）使用 proptest 进行属性测试
    • 标签格式：// Feature: env-config-and-backup, Property N: {property_text}
    • 运行测试：cargo test
  4. 模块注册:
    • 新增引擎模块需在 engine/mod.rs 中声明 pub mod xxx;
    • 新增命令子模块需在 commands/mod.rs 中声明并 re-export
    • 新增的 #[tauri::command] 函数需在 lib.rs 的 invoke_handler 中注册

Vue 前端

  1. 状态管理: 目前使用 ref 和 reactive 进行局部状态管理。
  2. 样式: 严格遵循 Tailwind CSS v4 规范。在组件内使用 @apply 时必须在 <style scoped> 中声明 @reference "tailwindcss";。
  3. 交互: 所有后端调用必须经过 invoke 封装，并处理 loading 和 error 状态。
  4. 类型定义: 前端 TypeScript 类型需与 Rust 后端的 Serialize/Deserialize 结构体对应，定义在 src/types/ 目录下。
  5. 测试:
    • 测试框架: Vitest + @vue/test-utils
    • 测试位置: 与被测试代码同级目录下的 __tests__/ 文件夹
    • 文件命名: {模块名}.spec.ts
    • 运行测试：npm run test 或 npm run test:run
    • 详细规范参见：doc/guides/TESTING_GUIDE.md

📋 关键模块逻辑

1. 容器识别

系统仅识别以 ps- 为前缀的容器。

  • 过滤逻辑位于 src-tauri/src/docker/manager.rs。

2. Env_File 解析器（v0.1.0 新增）

  • 位置：src-tauri/src/engine/env_parser.rs
  • 功能：可靠读写 .env 文件，保留注释和空行
  • 特性：
    • 支持带引号的值（单引号/双引号）
    • 支持行内注释（#）
    • 支持空行和纯注释行
    • 往返一致性保证（parse → format → parse）

3. 配置生成器（v0.1.0 新增）

  • 位置：src-tauri/src/engine/config_generator.rs
  • 功能：根据 GUI 输入生成 .env 和 docker-compose.yml
  • 特性：
    • 端口冲突检测
    • 保留用户自定义变量
    • 使用 ${VAR} 插值语法生成 Compose 文件
    • 创建 dnmp 风格的目录结构（services/、data/、logs/）

4. 统一镜像源管理（v0.1.0 新增）

  • 位置：src-tauri/src/engine/mirror_manager.rs
  • 功能：统一管理 Docker、APT、Composer、NPM 镜像源
  • 特性：
    • 5 个预设方案
    • 单个类别独立配置
    • 3 秒超时连接测试

5. 备份引擎（v0.1.0 增强）

  • 位置：src-tauri/src/engine/backup_engine.rs
  • 功能：生成包含 manifest 的 ZIP 备份包
  • 特性：
    • SHA256 文件完整性校验
    • 可选：数据库导出、项目文件、vhost 配置、日志
    • Tauri 事件进度通知
    • 部分失败容错处理

6. 恢复引擎（v0.1.0 新增）

  • 位置：src-tauri/src/engine/restore_engine.rs
  • 功能：解析备份包并还原环境
  • 特性：
    • 备份预览（manifest 解析）
    • SHA256 完整性验证
    • 端口冲突检测与自动分配
    • 配置文件、数据库、项目文件还原

7. 备份清单（v0.1.0 新增）

  • 位置：src-tauri/src/engine/backup_manifest.rs
  • 功能：记录备份元数据和文件校验和
  • 特性：
    • serde_json 序列化/反序列化
    • 必需字段验证（version、timestamp、services）
    • 往返一致性保证

📚 文档规范

文档分类与存放位置

项目文档统一存放在 doc/ 目录下，按以下规则分类：

1. doc/architecture/ - 架构设计文档

  • 用途: 系统架构、设计决策、技术方案
  • 示例: ARCHITECTURE.md
  • 何时使用: 记录重要的架构决策和技术方案

2. doc/guides/ - 使用指南和教程

  • 用途: 用户指南、开发指南、快速参考
  • 示例:
    • TESTING_GUIDE.md - 测试指南
    • MIRROR_GUIDE.md - 镜像源配置指南
    • QUICK_REFERENCE.md - 快速参考
  • 何时使用: 编写面向用户或开发者的操作指南

3. doc/history/ - 历史记录和修复报告

  • 用途: 开发日志、Bug 修复记录、历史决策
  • 命名格式: YYYY-MM-DD_标题.md
  • 示例:
    • 2026-04-25_DOCKER_COMPOSE_COMPATIBILITY_FIX.md
    • 2026-04-20_FIX_VERSION_KEY_MATCHING.md
  • 何时使用:
    • Bug 修复记录
    • 功能实施历史
    • 重要问题排查过程
    • 每日开发日志

4. doc/history/ - 历史记录和归档文档

  • 用途: 功能实施总结、优化进度、测试结果、问题修复记录，更新文档时不需要更新此目录下的文档
  • 示例:
    • 2026-04-17_IMPLEMENTATION_SUMMARY.md - 实施总结
    • 2026-04-23_TEST_RESULTS_REPORT.md - 测试结果报告
    • 2026-04-17_VERSION_SCOPE.md - 版本范围定义
    • YYYY-MM-DD_*.md - 按日期归档的历史文档
  • 何时使用:
    • 功能完成后的实施总结
    • 阶段性进度报告
    • 测试和验证结果
    • Bug 修复记录
    • 所有需要归档的文档

5. doc/README.md - 文档索引

  • 用途: 文档目录和导航
  • 维护: 新增文档后更新此索引

6. 根目录文档

  • README.md - 项目介绍和快速开始
  • CHANGELOG.md - 版本变更日志
  • AGENTS.md - AI Agent 开发指南（本文档）

文档编写规范

  1. 命名规范:

    • 使用英文文件名
    • 单词间用下划线分隔
    • 历史文档使用日期前缀：YYYY-MM-DD_标题.md

  2. 内容结构:

    • 使用 Markdown 格式
    • 包含清晰的标题层级
    • 添加代码示例时使用语法高亮
    • 重要信息使用引用块或列表

  3. 语言:

    • 技术文档使用中文
    • 代码注释使用中文
    • 变量名和函数名使用英文

  4. 更新原则:

    • 修改代码后及时更新相关文档
    • Bug 修复后记录到 doc/history/
    • 新功能完成后编写实施总结到 doc/history/（带日期前缀）
    • 所有文档最终都归档到 doc/history/

🚀 Agent 任务接入建议

如果你被分派了新任务，请遵循以下流程：

  1. 理解 Scope: 确认是前端 UI 调整还是后端 Rust 逻辑变更。
  2. 安全检查: 涉及 Docker 修改的操作应先调用 check_docker 指令。
  3. 权限校验: 若新增了 Tauri 插件调用，请务必更新 src-tauri/capabilities/default.json。
  4. TDD 流程:
    • 优先编写单元测试
    • 纯函数模块使用 proptest 进行属性测试
    • 运行 cargo test 确保所有测试通过
  5. 类型同步: 修改 Rust 数据结构后，同步更新 src/types/ 中的 TypeScript 类型定义。

🗺️ 后续开发重点 (给下个 Agent 的 Tip)

v0.1.0 已完成的功能

✅ 环境可视化配置 - 完整实现需求 1.1-1.9 ✅ 统一镜像源管理 - 完整实现需求 2.1-2.7 ✅ 环境备份 - 完整实现需求 3.1-3.8, 6.1-6.4 ✅ 环境恢复 - 完整实现需求 4.1-4.10 ✅ 基础设施模块 - env_parser、backup_manifest、测试框架

当前版本定位（v0.1.0 内测发布版）

核心定位: PHP-Stack v0.1.0 是一个环境配置管理与迁移工具，专注于：

  • ✅ 可视化配置生成（替代手动编辑 .env 和 docker-compose.yml）
  • ✅ 镜像源统一管理（加速国内开发体验）
  • ✅ 环境备份与恢复（快速迁移开发环境到新机器）

不包含的功能（未来版本可能考虑）:

  • ❌ 软件管理中心（多版本一键安装）- 用户需自行准备 Docker 镜像
  • ❌ 虚拟主机管理（Nginx 站点配置）- 用户需手动配置 Nginx

设计理念:

  • 轻量级: 专注于配置管理和环境迁移，不做复杂的容器编排
  • 透明性: 生成的配置文件完全可见可编辑，不隐藏任何细节
  • 兼容性: 与 dnmp 等项目保持兼容，便于团队协作

待完善功能

v1.3 - 一键导入恢复优化（低优先级）

  • 目标：完善 restore_engine.rs 中的 mysqldump 执行逻辑
  • 当前状态：✅ 核心框架已实现，数据库导出为占位符
  • 待完善：
    • 完整的 mysqldump 执行（使用 bollard exec API）
    • 更智能的环境差异处理
    • 事务性恢复（失败时回滚）
  • 优先级: 低（当前版本可使用手动方式恢复数据库）

开发建议

  1. 稳定优先: v0.1.0 作为内测发布版，重点是稳定性和用户体验优化
  2. Bug 修复: 优先处理用户反馈的问题和边界情况
  3. 性能优化: 大文件备份的流式处理、增量备份支持
  4. 文档完善: 用户手册、常见问题、最佳实践指南
  5. 国际化: 如需支持多语言，可添加 i18n 支持