openlark: Skill for Claude Code

OpenLark 代码规范检查（Skill）

适用场景

• 用户要求“检查项目代码规范”
• 新增 API 前想确认实现套路是否一致
• 评审 PR 时需要快速验证是否遵循 OpenLark 既有约定
• 发现模块风格漂移，想做一次统一体检

目标

输出一份可落地的规范检查结果，包含：

• 规范结论（通过/风险）
• 规则-证据对（每条规则附 path:line）
• 风险分级（P0/P1/P2）
• 新 API 最小检查清单（可直接用于 PR Review）

检查范围

覆盖全部 crates/openlark-*（按 AGENTS.md#STRUCTURE 有 18 个业务/基础设施 crate）。

• 重点核审：核心基础设施（openlark-core、openlark-client、openlark-protocol）与高频业务 crate（openlark-docs、openlark-communication、openlark-hr）。
• Client 命名（XxxClient）权威映射表见 docs/CLIENT_NAMING_CONVENTION.md 的「当前映射」，命名核审以此为准。
• 可按参数缩小为某个 crate 或目录（如 openlark-mail、crates/openlark-hr/src/）。

核心检查项

1) API 实现套路一致性

• 是否使用 Request/Response + Builder 模式
• 是否提供 execute() 与 execute_with_options(RequestOption)
• 是否通过 Transport::request(...) 发送请求

🔴 硬规则（grep 命中即 P0 违规）：

• 业务 crate（除 openlark-core 与 openlark-webhook）不得出现 reqwest::Client::new()——一旦命中，说明有端点绕过了 Transport，必为不一致源头。检查命令：

  rg "reqwest::Client::new" crates/ --type rust -g '!openlark-core/**' -g '!openlark-webhook/**'
  

• 白名单说明：openlark-webhook 是有意例外——自定义机器人不是飞书开放平台 API（目标 URL 为用户配置的绝对地址、用 URL 携带签名密钥鉴权、响应体为非标准 {code,msg}），不适用 Transport 的 /open-apis/ 基址与 token 注入，故保留独立 reqwest 路径（见 issue #214 调研结论，注释位于 crates/openlark-webhook/src/robot/v1/send.rs:13-26）。勿改 webhook 的 reqwest 用法。
• 不得手工 Authorization 头 / get_app_token（token 由 Transport 自动注入）
• Service/Request 不得持有 HTTP client 字段（只持 Config）

🟡 R 语义检查（防止双重嵌套陷阱）：

• ApiRequest<R> 的 R 应是响应 data 字段的内容类型，不是外层包装。
• 可疑信号：某个 XxxResponse struct 带 data: Option<...> 字段、同时又作为 ApiRequest<XxxResponse> 的泛型——大概率双重嵌套（core 已把 R 当作 data 内容解析）。
• 详细契约见 Skill(openlark-api) 的"🔒 核心契约"。

2) 端点定义规范

• 是否使用 per-crate 类型安全端点枚举：每个 crate 在 src/common/api_endpoints.rs 定义各自的 <Domain>ApiV1 枚举，并实现 pub fn to_url(&self) -> String（注意 to_url() 返回的是相对路径 String，形如 /open-apis/mail/v1/...，不带基址）。
• 是否避免手写业务 URL（统一走枚举 to_url()）
• 命名注意：枚举名是 <Domain>ApiV1，Domain 通常但并非总是等于 crate 名——以现况为准：
  • 与 crate 同名：MailApiV1（crates/openlark-mail/src/common/api_endpoints.rs:5）、DocsApiV1（crates/openlark-docs/src/common/api_endpoints.rs:440）、HelpdeskApiV1、AppApiV1（application）。
  • 与 crate 名不同：VcApiV1（meeting，crates/openlark-meeting/src/common/api_endpoints.rs:224）、TaskApiV1/BoardApiV1（workflow）、AdminApiV1（platform）、AuthenApiV1（auth）、HR 多枚举（AttendanceApiV1/HireApiV1/OkrApiV1/...）、Docs 多枚举（BitableApiV1/WikiApiV1/DocxApiV1/MinutesApiV1/...）。
• 新增端点时改枚举与 to_url() match 分支，不要在 Request/Builder 里手写 URL 字面量。