openlark-api-validation

OpenLark API 覆盖率验证技能

🧭 技能路由指南

本技能适用场景：

• 需要统计某个 crate/bizTag 的 API 覆盖率
• 需要输出缺失 API 清单与完成率报告
• 需要对比 api_list_export.csv 与实际落盘实现

其他技能：

• 项目级规范体检（架构/API/导出/校验一体）→ Skill(openlark-code-standards)
• 新增/重构具体 API → Skill(openlark-api)
• 字段正确性核对（文档 vs 代码）→ Skill(openlark-api-field-verify)
• 审查整体架构与公共 API 收敛 → Skill(openlark-design-review)

关键词触发映射

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

双向跳转规则

• 本技能只回答「文件在不在」；若要核对字段是否与飞书文档一致，转 openlark-api-field-verify。
• 若发现缺失 API 的根因是架构分层/范式混乱，转 openlark-design-review。
• 若发现问题是具体 API 尚未实现，转 openlark-api 落地实现。
• 若需要把覆盖率问题归因到全仓规范一致性，转 openlark-code-standards。

🎯 技能用途

本技能用于验证 OpenLark 项目中各 crate 的 API 实现覆盖率，通过对比 api_list_export.csv 中的 API 定义与实际代码实现，生成详细的覆盖率报告。

📋 快速工作流

1. 验证单个 crate 的 API 覆盖率

# 验证 openlark-docs crate
python3 tools/validate_apis.py --crate openlark-docs

# 验证 openlark-communication crate
python3 tools/validate_apis.py --crate openlark-communication

# 验证 openlark-meeting crate
python3 tools/validate_apis.py --crate openlark-meeting

输出位置： reports/api_validation/{crate}.md

2. 列出所有可用的 crate 映射

# 查看所有 crate → bizTag 映射
python3 tools/validate_apis.py --list-crates

示例输出（以实际 --list-crates 输出为准）：

📄 映射文件: tools/api_coverage.toml

- openlark-analytics: src=crates/openlark-analytics/src biz_tags=[search, report]
- openlark-application: src=crates/openlark-application/src biz_tags=[application, workplace]
- openlark-auth: src=crates/openlark-auth/src biz_tags=[auth, passport, verification_information, human_authentication]
...

映射共 15 个 crate（核对自 tools/api_coverage.toml）。新增 crate 时，在 tools/api_coverage.toml 追加 [crates.<name>] 段（src + biz_tags，可选 dashboard_groups）即自动纳入 --crate/--all-crates/--list-crates，无需改脚本。