# Repository Guidelines
## 项目结构与模块组织
- `src/`：核心 SDK 与服务接口；按 feature 拆分。
- `crates/`：子包（如 `protobuf`）。
- `examples/`：可运行示例：`basic/`、`api/`、`core/`。
- `tools/`：辅助工具二进制（见 `[[bin]]`）。
- 其它：`docs/` 文档，`scripts/` 脚本，`reports/` 报告。
## 构建、测试与开发命令
- 依赖 `just` 作为任务入口：
- `just build`：构建所有特性。
- `just test`：运行单元与文档测试。
- `just lint`：Clippy 零告警检查。
- `just fmt` / `just fmt-check`：格式化/检查。
- `just docs`：生成本地文档。
- `just check-all`：发布前全检。
- `just release 0.x.y`：打 tag 触发 CI 发布。
- 等价 cargo 示例：`cargo build --all-features`、`cargo test --all-features`。
## 代码风格与命名
- Rust 2021；`rustfmt` 默认规则。
- Clippy：在 CI 以 `-D warnings` 严格通过；`.clippy.toml` 已适配大仓阈值。
- 命名：模块/函数用 snake_case，类型用 PascalCase；feature 用 kebab-case（如 `cloud-docs`）。
- 最小公开原则：仅暴露必要 API。
## 测试指南
- 框架：内置 `cargo test` 与 doctest；示例位于 `examples/`。
- 约定：测试函数以 `test_*` 命名；需要凭证的示例请复制 `.env-example` 为 `.env`。
- 覆盖：优先核心路径与错误处理，提交需附测试或示例更新。
## 提交与 Pull Request
- 提交规范：采用 emoji + 类型 + 概述，例如：
- `🐛 fix: restore WebSocket frame parsing`
- `🎨 style: format code`
- `🚀 release: bump version to 0.13.1`
- PR 要求：清晰描述、关联 Issue、影响范围、变更清单、测试/文档更新；API 变更需附迁移说明。
## 安全与配置提示（可选）
- 切勿提交敏感信息；`.env` 已忽略。
- 功能开关：通过 `Cargo.toml` features 精简构建（如 `full`、`websocket`、`cloud-docs`）。