BlueArchiveToolkit/CONTRIBUTING.md

贡献指南

感谢参与 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。常用最低门禁：

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

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

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 或提交中明确引用。