openlark: Skill for Claude Code

权威源：crates/openlark-core/AGENTS.md，本文件与之冲突时以它为准。

OpenLark Validation Style

🧭 技能路由指南

本技能适用场景：

• 需要统一/评审 validate() 方法写法
• 不确定字符串字段是否要 .trim()、空白字符串算不算空
• 列表字段需要同时校验“非空 + 最大长度”
• 多条校验如何组织（连续宏快速失败 / 用构建器聚合）

其他技能：

• 项目级代码规范检查（架构/API/导出/校验一体）→ Skill(openlark-code-standards)
• 添加/重构 API → Skill(openlark-api)
• 审查整体设计规范 → Skill(openlark-design-review)

关键词触发映射

• validate、必填校验、validate_required、validate_required_list、空白字符串、校验聚合 → openlark-validation-style
• 代码规范、规范检查、风格一致性、体检 → openlark-code-standards
• 架构设计、public API、收敛方案、feature gating、兼容策略 → openlark-design-review
• 新增 API、重构 API、Builder、Request/Response、mod.rs 导出 → openlark-api
• 覆盖率、缺失 API、实现数量、CSV 对比 → openlark-api-validation

双向跳转规则

• 若校验问题已扩展到命名/导出/端点体系，转 openlark-code-standards。
• 若校验争议本质是架构范式冲突（例如 Request/Service 边界），转 openlark-design-review。

---

目标

在各 feature crate 的请求/Builder validate(&self) -> SDKResult<()> 中统一：

• 必填字段校验写法（减少样板代码）
• 空白字符串是否视为缺失（避免不同 crate 行为漂移）
• 失败时返回的错误类型与消息风格

规则

1) 字符串字段默认用 validate_required! 宏——字符串已自动 trim，传 self.field 即可

validate_required! 宏内部调用 Validatable::is_empty_trimmed（crates/openlark-core/src/lib.rs:53-59）。 对 &str / String 的实现是 self.trim().is_empty()（crates/openlark-core/src/validation/validatable.rs:7-17，提交 6fe4a6ca6）。

也就是说：字符串字段会自动 trim，纯空白字符串视为空。直接传 self.field，不要再额外 .trim()。

适用场景：必填校验失败就应该立即返回 Err(...)（快速失败）。

fn validate(&self) -> openlark_core::SDKResult<()> {
    // 字符串字段：自动 trim，空白算空，直接传字段本身
    openlark_core::validate_required!(self.app_token, "app_token 不能为空");
    openlark_core::validate_required!(self.table_id, "table_id 不能为空");
    Ok(())
}

现码惯例一致，例如 crates/openlark-ai/src/ai/document_ai/v1/bank_card/recognize.rs:30 validate_required!(self.file, "file 不能为空"); —— 字符串字段未手动 .trim()。

非字符串容器（如 Vec<T> / &[T]）的 is_empty_trimmed 退化为“长度是否为 0”（validatable.rs:25-35），同样直接传字段即可：

fn validate(&self) -> openlark_core::SDKResult<()> {
    openlark_core::validate_required!(self.items, "items 不能为空");
    Ok(())
}