openlark AGENTS.md

OpenLark Knowledge Base

Project: OpenLark - 飞书开放平台 Rust SDK
Stack: Rust, Tokio, Reqwest, WebSocket
Version: 0.20.0 Repository: https://github.com/foxzool/openlark

OVERVIEW

OpenLark 是为飞书（Feishu/Lark）开放平台构建的企业级 Rust SDK，提供 1,560+ 个 API 的类型安全访问。采用模块化架构设计，支持按需编译和功能组合。

STRUCTURE

.
├── crates/                    # 18 个业务模块 crates
│   ├── openlark-core/        # 核心基础设施（HTTP、错误处理）
│   ├── openlark-client/      # 高级客户端（meta 链式入口）
│   ├── lark-websocket-protobuf/ # WebSocket protobuf 协议（预生成源码）
│   ├── openlark-auth/        # 认证服务
│   ├── openlark-communication/  # IM 消息和联系人
│   ├── openlark-docs/        # 云文档和表格（158 APIs）
│   ├── openlark-hr/          # HR 和招聘（562 APIs）
│   ├── openlark-workflow/    # 任务和审批
│   ├── openlark-meeting/     # 视频会议
│   └── ... (其他业务模块)
├── src/                      # 根 crate 导出
├── examples/                 # 使用示例
├── tests/                    # 集成测试
└── tools/                    # 开发和维护脚本

WHERE TO LOOK

Task	Location	Notes
添加新 API	crates/openlark-*/src/**/v*/	按业务模块和版本组织
错误处理	crates/openlark-core/src/error/	CoreError 企业级错误系统
HTTP 客户端	crates/openlark-core/src/http.rs	共享 reqwest 配置
模型定义	*/models.rs 或 */models/	Serde 序列化结构体
Feature flags	Cargo.toml [features]	50+ 功能标志

CONVENTIONS

模块组织

• 业务领域驱动: 按功能（HR/Docs/IM）而非技术层次组织
• 版本化 API: v1/, v2/ 子目录管理不同 API 版本
• 模型分离: 请求/响应模型放在 models/ 或 models.rs

代码风格

• 中文优先: 文档和注释使用中文，面向中国开发者
• Builder 模式: API 请求使用流畅的构建器模式
• Feature 条件编译: #[cfg(feature = "...")] 控制模块编译
• 错误处理: 统一使用 CoreError，支持链式错误上下文

API 实现模式

// 1. 定义请求结构体（Builder 模式）
pub struct CreateXxxRequest { config: Config, ... }
impl CreateXxxRequest {
    pub fn new(config: Config) -> Self { ... }
    pub fn field(mut self, value: T) -> Self { ... }
    pub async fn execute(self) -> Result<XxxResponse> { ... }
}

// 2. 模型使用 Serde
#[derive(Debug, Serialize, Deserialize)]
pub struct XxxResponse { ... }

// 3. 验证使用宏
validate_required!(self.field, "字段不能为空");