nyaKazuha
43e1a33b88
改为在 linux runner 中手动 fetch 当前提交，避免自托管 runner 准备阶段通过 gh-proxy 克隆 actions/checkout 和 dtolnay/rust-toolchain 时被 403 拦截，并同步开发文档与缺口说明。
6.6 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
go test ./...
go vet ./...
Go 产品入口尚未完成，但仓库已有 cmd/bat 与 internal/ffi 骨架。提交前应运行 go test ./... 和 go vet ./...；目前输出可能只有 [no test files]，这代表缺少 Go 产品测试覆盖，不代表 Go CLI 已完成。
常用聚焦命令
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 产品入口和生产同步默认应通过 Rust bat --json 或 daemon RPC 进程边界集成。
集成测试
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 产品入口集成优先运行 Rust bat --json 或调用 daemon RPC。
重新构建兼容库：
cd crates/bat-ffi
cargo build