# 贡献指南

感谢参与 BlueArchive Toolkit。这个项目按长期维护的开源工具链标准推进，不接受只为临时通过、不可维护或污染本地资源目录的改动。

## 开始前

1. 阅读 `README.md`、`CURRENT_STATUS.md` 和 `docs/reports/CURRENT_GAPS.md`，确认当前实现状态和优先级。
2. 涉及官方资源同步、Rust 后端、Go CLI 或架构边界时，额外阅读 `docs/guides/development.md`、`docs/guides/official-resource-test-pull.md` 和相关 ADR。
3. AI agent 或自动化助手还必须遵守 `AGENTS.md`。

## 工作流

1. 基于当前开发分支创建功能分支。
2. 先分析现有文档和代码，再决定实现方式。
3. 保持改动聚焦，避免无关重构、批量格式化或元数据 churn。
4. 实现后运行覆盖改动范围的测试、格式化和 lint。
5. 如果用户可见行为、运行命令、架构边界、缺口状态或数据格式发生变化，同步更新文档。

## 提交规范

提交信息使用 Conventional Commits：

- 必须使用 `type(scope): 中文说明` 格式。
- `type` 使用 `feat`、`fix`、`docs`、`test`、`refactor`、`chore` 等 Conventional Commits 类型。
- `scope` 必须写具体模块或文档域，例如 `ffi`、`docs`、`cli`、`cas`、`official-sync`。

提交说明默认使用简体中文。代码标识符和协议字段仍使用英文。

示例：

- `feat(cli): 添加 doctor 命令骨架`
- `fix(docs): 修正官方同步运行说明`
- `refactor(ffi): 降级 FFI 为可选兼容层`

## 验证要求

基础验证命令见 `docs/guides/development.md`。常用最低门禁：

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

如果改动只影响部分 crate，可以先跑更窄的测试，但合并前必须确保影响面被覆盖。官方资源同步、下载、daemon、status、verify 或 repair 相关改动还应运行：

```bash
cargo test -p bat-infrastructure --bin bat -- --nocapture
cargo test -p bat-infrastructure -- --nocapture
```

真实官方网络 smoke run 必须写入隔离目录，禁止写入现有游戏客户端或生产资源目录。

## 资源和数据安全

1. 不要把生产环境当作开发环境。
2. 不要默认读取或修改 `/home/wanye/D/BlueArchive` 等已有资源目录。
3. 不要提交真实账号、token、cookie、私有路径、下载产物、数据库或本地 CAS 数据。
4. 新增 fixture 应尽量最小化，只保留验证解析、校验或错误处理所需的数据。

## PR 要求

PR 描述应包含：

1. 改动摘要。
2. 影响范围。
3. 已运行的验证命令。
4. 未覆盖风险或后续缺口。
5. 相关 issue、ADR 或文档链接。

如果改动关闭缺口或 issue，请在 PR 或提交中明确引用。