Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
161 lines (120 loc) · 6.52 KB

DEVELOPMENT.md

File metadata and controls

161 lines (120 loc) · 6.52 KB

maa-cli 开发文档

许可证

本项目采用 AGPL-3.0-only 许可证。您的所有贡献都将被纳入本项目，并遵循相同的许可证。

贡献指南

贡献流程

  1. Fork 本仓库：在 GitHub 上 fork 本项目到你的个人账户。

  2. 创建分支：从主分支（main 或 master）拉取最新代码，并基于此创建分支（如 feature/xxx、fix/xxx）。

  3. 开发与提交：按照代码规范进行开发，确保代码格式、质量和测试覆盖率达标。建议每次提交前运行 cargo +nightly fmt 和 cargo clippy。

  4. 推送分支并发起 PR：将你的分支推送到 fork 仓库，并发起 Pull Request（PR）。PR 标题和描述需遵循 Conventional Commits 规范，简明扼要说明变更内容和动机，并在 PR 中关联相关 Issue。

  5. 代码评审与修改：项目维护者会尽快进行代码评审，并提出修改建议。

  6. 合并与发布：通过评审后，PR 会以 squash 方式合并，你的贡献将被记录在 Change Log 中。

注意事项

  • 避免直接向主分支提交代码，始终通过 PR 进行贡献。
  • 提交 PR 前，确保自己的分支已经与主分支同步，避免合并冲突。
  • 对于较大或影响范围广的变更，建议先在 Issue 中充分讨论方案。
  • 如对现有代码有任何疑问，可以在 Issue 中提出，以获得帮助和反馈。
  • 欢迎任何形式的贡献，包括文档、测试、CI 配置等。

开发环境

环境要求

  • Rust 工具链：需要 1.84 版本或更高。推荐使用 rustup 安装。
    • 安装 nightly 版本的 rustfmt：rustup component add rustfmt --toolchain nightly
  • C 编译器：如需在 Linux 上从源码编译 OpenSSL，或启用 git2 功能（默认启用）时需要。建议关闭 git2 功能以避免依赖 C 编译器和额外的 OpenSSL 库。待 gix 完全替代 git2 后，将移除该依赖。

构建项目

# 调试构建
cargo build

# 发布构建
cargo build --release

# 构建特定 crate
cargo build -p maa-cli

运行测试

# 运行所有测试
cargo test

# 运行特定 crate 的测试
cargo test -p maa-cli

# 运行特定测试
cargo test <测试名称>

Workspace 架构

分层概览

graph TD
    CLI["maa-cli"]

    subgraph Domain
        DIRS["maa-dirs"]
        VERSION["maa-version"]
        INSTALLER["maa-installer"]
        VALUE["maa-value"]
        VALMACRO["maa-value-macro"]
    end

    subgraph Core["Core / FFI"]
        CORE["maa-core"]
        SYS["maa-sys"]
        FFISTR["maa-ffi-string"]
        TYPES["maa-types"]
        FFITYPES["maa-ffi-types"]
    end

    subgraph Utils
        STREXT["maa-str-ext"]
    end
    
    subgraph Xtask
        XTASK["xtask"]
        X["x"]
    end

    CLI --> CORE
    CLI --> DIRS
    CLI --> INSTALLER
    CLI --> TYPES
    CLI --> VALUE
    CLI --> VALMACRO
    CLI --> VERSION

    CORE --> SYS
    CORE --> TYPES
    CORE --> FFISTR
    CORE --> FFITYPES

    SYS --> FFITYPES
    TYPES --> FFISTR

    FFISTR --> STREXT
    VALUE --> STREXT
    VALUE --> VALMACRO
    
    XTASK --> DIRS
    XTASK --> VERSION
    X -.shells out to.-> XTASK
Loading

各 crate 的职责

  • maa-cli：最终的 CLI 应用，负责命令解析、任务编排、配置加载、安装更新入口，以及把各个库拼装成面向用户的行为。
  • maa-core：MaaCore 的安全 Rust 封装，提供 Assistant、错误类型和 callback 抽象。
  • maa-sys：MaaCore 的原始 FFI bindings，只负责暴露 C API 和链接行为，不提供高层接口。
  • maa-types：共享类型定义层，包含任务类型、客户端类型、消息类型、Option key 等可被 CLI 和封装层共同使用的枚举与基础类型。
  • maa-ffi-types：最底层的 FFI primitive aliases，如 AsstBool、AsstId、AsstSize 等。
  • maa-ffi-string：面向 MaaCore FFI 的字符串转换层，把 Rust 字符串安全地转成 CString。
  • maa-str-ext：通用 UTF-8 / OsStr / Path 字符串工具 crate，属于基础工具层。
  • maa-value：配置值模型，支持条件参数、用户输入和动态合并，主要服务于任务参数与配置系统。
  • maa-value-macro：maa-value 的 proc-macro 辅助 crate，用于更方便地在代码中构造复杂值。
  • maa-dirs：路径定位层，负责配置目录、缓存目录、资源目录、MaaCore 库目录等平台相关路径逻辑。
  • maa-installer：下载、解压、校验、安装等通用能力，主要服务于 CLI 的安装与更新流程。
  • maa-version：版本号与 manifest 解析、比较逻辑。
  • xtask：仓库内部自动化工具，负责 build/test/release/CI 辅助流程。
  • x：极薄的启动器，用来把 cargo x ... 转发到 cargo run -p xtask -- ...。

代码规范

  • 格式化：使用 nightly 版 rustfmt 格式化代码。提交前请运行 cargo +nightly fmt 保证格式一致。
  • 质量检查：使用 cargo clippy 检查代码质量。任何警告都会导致 CI 失败。不可避免的警告请用 #[allow] 或 #[expect] 注明原因。
  • Unsafe：尽量避免 unsafe。如必须使用，请添加注释解释原因。
  • 错误处理：
    • maa-cli 使用 anyhow。
    • 其他组件使用 thiserror 或者自行编写错误类型来处理错误。
    • 避免 unwrap 和 expect，如必须使用请注释说明原因。
  • 测试规范：
    • 新代码应尽量编写测试，修复旧代码时请添加相关 bug 测试。
    • MaaCore FFI 功能可省略测试，但需本地实际运行验证。
    • 需网络或读写系统/用户文件的测试请用 #[ignore] 标记，避免在本地和沙盒环境运行。可用 cargo test -- --ignored 运行这些测试。
    • 项目用 cargo llvm-cov 生成测试覆盖率报告，并通过 codecov 跟踪。PR 会自动生成覆盖率报告，不建议本地运行。
  • 依赖管理：如需新增依赖，请优先考虑社区活跃、维护良好的库，并在 PR 说明中注明用途。

文档规范

  • 命令及配置的新增或修改需同步更新文档。
  • 文档以简体中文为主，英文为辅，其他语言（繁体、韩文、日文）尽量翻译，无法翻译时可用简体中文占位。
  • 所有文档为 Markdown 格式，使用 markdownlint-cli2 检查。
  • 段落内不换行，每段仅一行，段落间空行分隔。非段落换行请用 <br>，不要用尾随空格。