7.0 KiB
开发指南
本指南是本地开发流程的权威入口。贡献协作规则见 ../../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
自托管 Gitea runner
.gitea/workflows/bat.yml 使用 runs-on: linux，并且不依赖 actions/checkout、dtolnay/rust-toolchain 等外部 GitHub Action。runner 需要在执行环境中预装以下命令：
git --version
rustc --version
cargo --version
rustfmt --version
cargo clippy --version
该 workflow 会用 GITHUB_SERVER_URL、GITHUB_REPOSITORY、GITHUB_REF 和 GITHUB_SHA 手动 git fetch 当前提交，再执行 Rust workspace 的格式化、检查、构建、clippy 和测试。这样可以避免自托管 runner 在准备阶段通过代理克隆第三方 action 仓库。
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
开发约束：
- 先阅读相关文档和代码，再判断实现方式。
- 跨模块、架构、数据格式或用户工作流变更必须先说明设计取舍。
- 保持改动聚焦，不做无关重构、批量格式化或元数据 churn。
- 公共接口、状态文件、manifest、catalog、patch 和下载流程变更必须补充测试或 fixture。
- 用户可见命令、运行路径、配置、状态文件、日志或缺口状态变化时，同步更新 README、指南、架构文档或
docs/reports/CURRENT_GAPS.md。
3. 提交
git add .
git commit -m "feat(cli): 添加 doctor 命令骨架"
提交信息遵循 Conventional Commits 规范：
- 必须使用
type(scope): 中文说明格式。 type使用feat、fix、docs、style、refactor、test、chore等 Conventional Commits 类型。scope必须写具体模块或文档域，例如ffi、docs、cli、cas、official-sync。- 提交标题和正文默认使用简体中文；代码标识符、协议字段和命令参数仍保持英文。
示例：
feat(cli): 添加 doctor 命令骨架fix(docs): 修正官方同步运行说明refactor(ffi): 降级 FFI 为可选兼容层
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
make test-go-api
make build-go-api
go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
Go 边界与进度以 docs/reports/GO_STATUS.md 为准：
- 同步/运维命令行 = Rust
bat（近乎全自动） - 资源分发服务 =
cmd/bat-api（make build-go-api） - 默认 Go 门禁 =
make test-go-api（无 FFI） - 试验 CLI 产物为
bin/bat-go（make build-go-cli），禁止与 Rustbat重名 - 修改 FFI 时再跑
make test-go-ffi
常用聚焦命令
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 时必须运行 cargo test -p bat-ffi -- --nocapture。Go 服务层默认经 internal/backendrpc 调 daemon；同步任务由 Rust bat 执行，不由 Go 试验 CLI 承担。
集成测试
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；汉化产物默认写入独立的 ./bat-localized。如果要覆盖，官方原版资源使用 --output / BAT_OUTPUT，汉化产物使用 --localized-output / BAT_LOCALIZED_OUTPUT。两者都必须使用 /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 产品入口集成优先运行 Rust bat --json 或调用 daemon RPC。
重新构建兼容库：
cd crates/bat-ffi
cargo build