Back to Details

api-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Route & Type Audit Skill

API路由与类型审计Skill

Scan API routes and plugins, catalog every endpoint, and cross-reference against type definitions to find mismatches. Read-only — do not modify any files.
扫描API路由和插件，记录每个端点，并与类型定义交叉引用以查找不匹配项。仅读取——请勿修改任何文件。

Steps

步骤

1. Scan Route Files

1. 扫描路由文件

Scan your routes directory recursively. For each route registration, extract:
  • HTTP method (GET, POST, PUT, PATCH, DELETE)
  • Path (e.g., 
    /api/users
    , 
    /api/admin/settings
    )
  • Auth requirements (public, session-required, RBAC permissions)
  • Request schema (Zod/validation schema name, if defined)
  • Response schema (Zod/validation schema name, if defined)
Look for framework-specific patterns (e.g., Fastify schema objects, Express middleware chains, Next.js route handlers).
递归扫描你的路由目录。对于每个路由注册，提取以下信息：
  • HTTP method（GET、POST、PUT、PATCH、DELETE）
  • 路径（例如：
    /api/users
    、
    /api/admin/settings
    ）
  • 认证要求（公开、需要会话、RBAC权限）
  • 请求Schema（若已定义，Zod/验证Schema名称）
  • 响应Schema（若已定义，Zod/验证Schema名称）
查找特定框架的模式（例如：Fastify Schema对象、Express中间件链、Next.js路由处理器）。

2. Scan Plugin/Middleware Files

2. 扫描插件/中间件文件

Scan middleware or plugin directories for:
  • Auth middleware registration (which routes get auth protection)
  • Permission mappings
  • Rate limiting configurations per route
  • Any route-level decorators or hooks
扫描中间件或插件目录，查找以下内容：
  • 认证中间件注册（哪些路由受认证保护）
  • 权限映射
  • 每个路由的速率限制配置
  • 任何路由级别的装饰器或钩子

3. Catalog Shared Types

3. 记录共享类型

Scan type definition directories for:
  • Validation schemas used as request/response validators
  • TypeScript interfaces/types that correspond to API payloads
  • Exported schema names and their shapes
扫描类型定义目录，查找以下内容：
  • 用作请求/响应验证器的验证Schema
  • 与API负载对应的TypeScript接口/类型
  • 导出的Schema名称及其结构

4. Cross-Reference and Detect Mismatches

4. 交叉引用并检测不匹配项

CategoryWhat to check
Missing schemasRoutes without request/response validation
Type driftRoute handler using a type that differs from the shared schema
Orphan typesSchemas in types package not referenced by any route
Auth gapsRoutes missing auth hooks that should have them (e.g., 
/admin/*
)
分类检查内容
缺失Schema未配置请求/响应验证的路由
类型偏移路由处理器使用与共享Schema不一致的类型
孤立类型类型包中未被任何路由引用的Schema
认证缺口应配置但未配置认证钩子的路由（例如：
/admin/*
）

5. Report Findings

5. 输出检测结果

Output a markdown table grouped by severity:
  1. Critical: Auth gaps, missing validation on mutation endpoints
  2. Warning: Type drift, missing response schemas
  3. Info: Orphan types, routes with inline schemas that could use shared ones
Include summary counts: total routes, full coverage, partial coverage, no validation, mismatches.
输出按严重程度分组的Markdown表格：
  1. 严重：认证缺口、变更端点缺失验证
  2. 警告：类型偏移、缺失响应Schema
  3. 信息：孤立类型、使用内联Schema可替换为共享Schema的路由
包含汇总统计：总路由数、完全覆盖数、部分覆盖数、无验证数、不匹配数。

Arguments

参数

  • $ARGUMENTS
    : Optional scope filter
    • Example: 
      /api-audit admin
      — only audit admin routes
    • If empty, audit all routes
  • $ARGUMENTS
    ：可选的范围过滤器
    • 示例：
      /api-audit admin
      — 仅审计管理员路由
    • 若为空，则审计所有路由

Execution Strategy

执行策略

Use two parallel Explore agents for speed:
  1. Agent A: Scan routes + plugins — catalog all endpoints
  2. Agent B: Scan types directories — catalog all shared schemas
Then synthesize their findings into the cross-reference table.
为提升速度，使用两个并行的Explore Agent：
  1. Agent A：扫描路由+插件——记录所有端点
  2. Agent B：扫描类型目录——记录所有共享Schema
然后将它们的检测结果整合到交叉引用表格中。

Key Rules

核心规则

  1. Read-only — do not create, modify, or delete any files
  2. Be specific — report exact file paths and line numbers
  3. No false positives — only report genuine mismatches
  4. Include context — show the relevant type/schema snippet for each mismatch
  1. 仅读取——请勿创建、修改或删除任何文件
  2. 精准定位——报告确切的文件路径和行号
  3. 无误报——仅报告真实的不匹配项
  4. 包含上下文——为每个不匹配项显示相关的类型/Schema片段