OpenLark 代码规范检查（Skill）

适用场景

• 用户要求“检查项目代码规范”

• 新增 API 前想确认实现套路是否一致

• 评审 PR 时需要快速验证是否遵循 OpenLark 既有约定

• 发现模块风格漂移，想做一次统一体检

目标

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

• 规范结论（通过/风险）

• 规则-证据对（每条规则附 path:line ）

• 风险分级（P0/P1/P2）

• 新 API 最小检查清单（可直接用于 PR Review）

检查范围

优先覆盖：

• crates/openlark-core

• crates/openlark-client

• crates/openlark-docs

• crates/openlark-communication

可按参数缩小为某个 crate 或目录。

核心检查项

1. API 实现套路一致性

• 是否使用 Request/Response + Builder 模式

• 是否提供 execute() 与 execute_with_options(RequestOption)

• 是否通过 Transport::request(...) 发送请求

2. 端点定义规范

• 是否使用 ApiEndpoint 枚举/端点常量

• 是否避免手写业务 URL

• 是否通过 to_url() 或统一端点入口生成路径

3. 参数校验规范

• 必填校验是否统一用 openlark_core::validate_required!

• 字符串是否优先 trim() 后再校验

• 列表字段是否校验非空与长度上限（如 validate_required_list! ）

4. 命名与公开 API 表达

• Client/Service/Resource/Request/Builder 命名是否语义清晰

• 对外入口是否统一（避免同义入口并存）

• meta 调用链命名是否与仓库约定一致

5. 导出与 feature gating

• mod.rs 与 prelude 是否完整导出新增 API

• Cargo.toml feature 与 #[cfg(feature = "...")] 是否对齐

• 是否存在导出但不可编译或不可访问路径

输出模板（必须）

• 结论概览（3-6 条）

• 规则-证据对（至少 8 条）

• 规则

• 证据（path:line ）

• 风险等级（P0/P1/P2）

• 修复建议

• 新 API 最小检查清单（5-8 条）

• 建议行动项（按优先级排序）

推荐执行顺序

• 先读 AGENTS.md 与目标 crate 的 AGENTS.md/CLAUDE.md

• 再扫规则高频证据：api_endpoints 、execute_with_options 、validate_required 、prelude 、mod.rs

• 最后输出规则-证据对与整改建议

重点提醒

• 结论必须基于代码证据，不做“纯经验判断”

• 证据至少精确到文件路径，推荐精确到 path:line

• 不在规范检查中进行大规模重构，先给出可执行清单

与其他技能的关系

• 需要审查整体架构与公共 API：openlark-design-review

• 只聚焦校验写法统一：openlark-validation-style

• 需要新增/重构具体 API：openlark-api

• 需要做覆盖率统计：openlark-api-validation

技能分流决策表

场景 优先技能 何时转交

只想做一次项目规范体检（给出规则-证据对和风险清单） openlark-code-standards

若发现架构级冲突/公共 API 设计分歧，转 openlark-design-review

重点是架构收敛、范式选型、兼容策略（含 breaking 评估） openlark-design-review

若需要补充全仓规范一致性证据，可回补 openlark-code-standards

只处理 validate() 、validate_required! 、空白字符串与校验聚合 openlark-validation-style

若校验问题已扩展到命名/导出/端点体系，转 openlark-code-standards

新增或重构某个具体 API 文件（Request/Response/Builder/导出） openlark-api

若实现前需先做规范体检，先跑 openlark-code-standards

关注 API 覆盖率、实现数量、缺失清单 openlark-api-validation

若覆盖率问题背后是设计不一致，转 openlark-design-review

快速判断

• 问题是“这个项目现在规范是否一致” → openlark-code-standards

• 问题是“这个设计该怎么收敛” → openlark-design-review

• 问题是“这个校验写法到底怎么统一” → openlark-validation-style

• 问题是“我现在就要实现某个 API” → openlark-api

关键词触发映射

用户关键词/表述 建议技能

代码规范、规范检查、风格一致性、体检、对齐约定 openlark-code-standards

架构设计、public API、收敛方案、feature gating、兼容策略、breaking change openlark-design-review

validate、必填校验、validate_required、空白字符串、校验聚合 openlark-validation-style

新增 API、重构 API、Builder、Request/Response、mod.rs 导出 openlark-api

覆盖率、实现数量、缺失 API、统计、对比 CSV openlark-api-validation

组合关键词优先级

• 同时出现“规范检查 + 覆盖率”时，先用 openlark-api-validation 产出缺失清单，再用 openlark-code-standards 做规范归因。

• 同时出现“规范检查 + 架构收敛”时，先用 openlark-code-standards 做现状证据，再转 openlark-design-review 定迁移方案。

• 同时出现“新增 API + 校验统一”时，实现阶段用 openlark-api ，校验规则判定用 openlark-validation-style 。