BlueArchiveToolkit/docs/guides/development.md

开发指南

本指南是本地开发流程的权威入口。贡献协作规则见 ../../CONTRIBUTING.md，AI agent 长期规则见 ../../AGENTS.md。

环境准备

安装依赖

Go

# 安装 Go 1.22+
# 参考：https://golang.org/doc/install

go version  # 验证安装

Rust

# 安装 Rust 1.75+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustc --version  # 验证安装
cargo --version

Docker

# 安装 Docker 和 Docker Compose
# 参考：https://docs.docker.com/get-docker/

docker --version
docker compose version

---

项目结构

请参考 架构文档 了解完整的项目结构。

---

开发工作流

1. 创建功能分支

git checkout -b feature/your-feature-name

2. 开发

# 实时编译检查
make check

# 运行测试
make test

# 格式化代码
make fmt

开发约束：

1. 先阅读相关文档和代码，再判断实现方式。
2. 跨模块、架构、数据格式或用户工作流变更必须先说明设计取舍。
3. 保持改动聚焦，不做无关重构、批量格式化或元数据 churn。
4. 公共接口、状态文件、manifest、catalog、patch 和下载流程变更必须补充测试或 fixture。
5. 用户可见命令、运行路径、配置、状态文件、日志或缺口状态变化时，同步更新 README、指南、架构文档或 docs/reports/CURRENT_GAPS.md。

3. 提交

git add .
git commit -m "feat: 添加新功能"

提交信息遵循 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式（不影响功能）
• refactor: 重构
• test: 测试相关
• chore: 构建工具或辅助工具

4. 推送和 PR

git push origin feature/your-feature-name
# 然后在 GitHub 创建 Pull Request

---

代码规范

默认使用简体中文写文档、提交说明、开发日志和面向用户的说明。代码标识符、协议字段、数据库字段、包名和命令参数保持英文命名规范。

禁止使用 demo、临时实现、硬编码路径或只为当前测试通过的伪实现。确实未完成的能力应写入当前缺口文档，而不是用 TODO 或 FIXME 隐藏。

Go

• 遵循 Effective Go
• 使用 gofmt 格式化
• 使用 golangci-lint 进行静态检查

Rust

• 遵循 Rust API Guidelines
• 使用 cargo fmt 格式化
• 使用 cargo clippy 进行静态检查

TypeScript

• 遵循 TypeScript Style Guide
• 使用 ESLint 和 Prettier

---

测试

合并前通用门禁

cargo fmt --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Go CLI 尚未实现时，go test ./... 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。

常用聚焦命令

cargo test -p bat-core -- --nocapture
cargo test -p bat-adapters -- --nocapture
cargo test -p bat-ffi -- --nocapture
cargo test -p bat-infrastructure -- --nocapture
cargo test -p bat-infrastructure --bin bat -- --nocapture
cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets -- -D warnings

官方资源同步、下载、daemon、status、verify 或 repair 相关改动必须至少覆盖 bat-infrastructure 和 bat 二进制测试。

bat-ffi 只是可选无状态 C ABI 兼容层。修改 FFI 导出、JSON schema、错误返回或 internal/ffi CGO 包装时必须运行 cargo test -p bat-ffi -- --nocapture；Go CLI 和生产同步默认应通过 bat --json 进程边界集成。

集成测试

cargo test --workspace

带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 BAT_REAL_* 环境变量读取隔离样本路径。不要默认读取 /home/wanye/D/BlueArchive 或任何已有客户端目录。

官方资源同步手动检查

查看参数：

cargo run -p bat-infrastructure --bin bat -- --help

dry-run：

cargo run -p bat-infrastructure --bin bat -- \
  --auto-discover \
  --dry-run

开发环境真实下载默认写入 ./bat-resources；如果要覆盖，必须使用 /tmp 或其他隔离目录，不要写入现有资源目录。

生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。

基准测试

make bench

---

调试

Go

使用 Delve 调试器：

go install github.com/go-delve/delve/cmd/dlv@latest
dlv debug ./cmd/bat

Rust

使用 rust-lldb 或 rust-gdb：

rust-lldb target/debug/bat-cas-engine

---

常见问题

1. 编译失败

确保安装了所有依赖：

go mod download
cargo fetch

2. 测试失败

先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。

3. FFI 兼容层问题

bat-ffi 不是主集成边界，只用于需要 C ABI 的兼容场景。默认 Go CLI 集成优先运行 Rust bat --json。

重新构建兼容库：

cd crates/bat-ffi
cargo build

---

更多当前状态请查看 当前状态 和 当前缺口清单。