用途
api-audit 是一个只读的 API 路由与类型审计技能，用于将 API 路由与共享类型定义进行交叉比对，找出 schema 漂移、缺失认证以及校验缺口。该技能明确要求不修改任何文件。
主要能力
- 扫描 API 路由，编目每个端点的 HTTP 方法、路径、认证/权限要求、请求校验 schema（名称或内联）以及响应 schema。
- 扫描类型/schema 目录，编目所有导出的 schema 名称、文件位置、TypeScript 形状摘要，以及是否被任何路由导入引用。
- 识别三类问题：schema 漂移、认证缺口、孤立类型。
- 按严重程度（Critical、Warning、Info）分组输出 markdown 表格报告，并包含汇总计数：总路由数、完整校验覆盖、部分覆盖、无覆盖、不匹配数量。
使用方式
该技能提供脚本用于清点 API 表面：
bash scripts/inventory-api-surface.sh
bash scripts/inventory-api-surface.sh admin # scope filter
bash scripts/find-shared-schemas.sh packages
支持通过 $ARGUMENTS 传入可选路径前缀进行范围过滤，例如 admin 表示只审计 /admin/* 路由；留空则审计全部。
执行策略上，技能要求并行启动两个 agent：Agent A 扫描路由与插件，Agent B 扫描类型/schema 目录，两者完成后进行综合，不应串行执行。
判定规则
- Schema 漂移：仅当共享类型与路由处理器同时存在但在形状上不一致（字段名、必填与可选、类型分歧）时才算。路由使用自己的内联 schema 不算漂移。
- 认证缺口：仅当（a）同级或父级路由有认证钩子，且（b）该路由处理变更操作或用户范围数据时才算。没有同级模式的公开 GET 端点属于模糊情况，应报告为 Info 而非 Critical。
- 孤立类型：仅当 schema 没有任何导入、在任何路由文件中都没有引用，且不在可能服务外部消费者的 types/ 包中时才算。
适用场景
适用于审计 API 路由的 schema 一致性、认证覆盖和请求校验完整性，尤其适合使用共享 TypeScript 类型定义的项目。
限制
- 只读，不修改任何文件。
- 不得在未确认框架不使用内联校验（如 Fastify schema 对象、中间件中的 Zod 等）的情况下标记缺失 schema。
- 不得在未验证路由是否确实需要保护的情况下报告认证缺口——并非所有路由都需要认证。
- 不得将孤立类型视为严重问题——它们可能是计划中的、过渡性的，或由路由树中不可见的 SDK 消费者使用。
- 不得仅凭路由路径对认证做假设——
/admin/*前缀在没有检查钩子链的情况下并不保证路由需要认证。 - 关于收费、价格、平台支持等具体信息暂未提供。