api-docs-quality-report

API 文档审计技能

爬取文档站点上的所有 API 参考端点页面，依据 5 项质量检查逐项评分，检测站点范围内的模式，并输出交互式 HTML 报告，样式与本会话中之前生成的审计报告一致。

---

步骤 0 — 收集输入

你只需要一个输入：文档 URL。

如果用户尚未提供，请询问：

要审计哪个 API 文档 URL？

如果已提供 URL，请去掉末尾的斜杠，并在继续之前向用户确认。

特殊情况 — “对 X 做同样的事”： 如果用户说“做同样的事”或“对 X 做同样的审计”，说明他们希望对新 URL 执行相同的工作流，并使用相同格式的 HTML 报告。直接继续步骤 1。

---

步骤 1 — 发现所有端点页面

1a. 优先尝试 llms.txt

获取 <docs_url>/llms.txt。

如果找到：

• 提取所有符合 - [Page Title](URL): description 模式的行
• 仅筛选 API 参考页面 — 查找路径中包含以下任一项的页面： api-reference、api-reference/、/api/、/endpoints/、/rest/、/docs/、/reference/ 或带版本号的路径（例如 /v1/）
• 排除：概览／索引页面（未暗示 HTTP 方法）、SDK 文档、CLI 文档、 Terraform 文档、指南、快速入门页面
• 保存为 ENDPOINT_PAGES[] — {title, url, description} 列表

如果未找到或返回 404：

• 获取文档主页
• 查找引用 API／端点的导航侧边栏或站点地图链接
• 从导航结构中提取所有 API 参考页面 URL
• 在报告中注明 llms.txt 不可用

1b. 确定分类

按发现的页面 URL 路径前缀或导航分区分组：

• 例如，/api-reference/agents/ → Agents 分类
• 例如，/api-reference/executions/ → Executions 分类
• 位于 api-reference 根级别的页面 → 未分类，或根据标题推断分类

保存为 CATEGORIES[] — {name, page_count, pages[]} 列表。

报告发现结果摘要：

共找到 N 个端点页面，分属 K 个分类。正在获取...

---

步骤 2 — 检查 OpenAPI 规范是否可用

获取各个页面之前，先检查是否存在独立的 OpenAPI 规范。

按以下顺序尝试这些发现方式（首次成功后停止）：

1. 检查主页或文档根目录的 Link HTTP 标头（RFC 8288），查找 rel="openapi" 或 rel="describedby" — 这是发现 API 规范的标准机制
2. <docs_url>/openapi.json
3. <docs_url>/openapi.yaml
4. <docs_url>/api/openapi.json
5. llms.txt 中 “## OpenAPI Specs” 下引用的任何 URL

结果：

• 如果可访问：SPEC_AVAILABLE = true，保存 URL
• 如果所有尝试均返回 404，且未找到 Link 标头：SPEC_AVAILABLE = false

缺少规范本身就是一个最高优先级问题 — 将其记录为问题 #1。

---

步骤 3 — 获取并解析所有端点页面

获取 ENDPOINT_PAGES[] 中的每个 URL。对每个页面提取：

3a. 页面级文字说明

出现在 OpenAPI 代码块上方的文本（或 # 标题与第一个 ## OpenAPI 标题之间的文本）。这是人工编写的说明。

3b. OpenAPI 代码块

查找语言标记为 yaml 或 json 且包含 OpenAPI 规范的围栏代码块。提取：

• HTTP_METHOD — 例如 GET、POST、PUT、DELETE、PATCH
• HTTP_PATH — 例如 /api/v1/agents/{agent_id}/execute
• REQUEST_BODY_SCHEMA — requestBody schema 部分（如果有）
• PARAMETERS — 路径参数 + 查询参数（如果有）
• RESPONSES — 完整的 responses 对象
• RESPONSE_200_SCHEMA — responses.200 或 201 下的 schema

如果未找到 OpenAPI 代码块，将 SPEC_INLINE = false 标记为真。

---

步骤 4 — 为每个端点评分（5 项检查）

针对每个端点，评估全部 5 项检查。将结果保存为 {check_name: "pass"|"warn"|"fail", current_state: string, fix_guidance: string}。

阅读 references/scoring-rules.md，了解每项检查的具体评分标准。

检查 1 — 端点说明 检查 2 — OpenAPI 规范 检查 3 — 请求体参数说明 检查 4 — 响应代码 检查 5 — 响应架构

---

步骤 5 — 检测全站模式

为所有端点评分后，查找在多个页面中重复出现的模式。

如果某种模式影响 ≥ 60% 的端点，则符合条件：

要检测的模式	识别方法
普遍缺少错误代码	所有端点均缺少 401、429、500 等错误代码
普遍存在空响应架构	大多数端点的 schema: {}
自由格式的请求体架构	大多数请求体中存在 additionalProperties: true
仅内嵌规范／规范地址失效	所有页面都内嵌规范，但规范地址返回 404
到处都是一句话描述	大多数页面的描述少于 10 个词
仅记录 422 验证错误	只记录了 FastAPI 的 422，未记录业务错误

对于每个检测到的模式，撰写一段总结，说明：

• 模式是什么
• 影响多少个端点
• 根本原因（例如 FastAPI 自动生成、缺少中间件文档）
• 对开发者体验的影响

存储为 SITE_WIDE_PATTERNS[]。

---

步骤 6 — 汇总主要问题

根据影响程度对所有发现的问题进行排序，选出 10 个最重要的问题。优先考虑：

1. 影响端点最多的问题
2. 发生在流量最高／最重要端点上的问题
3. 与安全相关的缺漏（身份验证端点、架构为空的凭据端点）
4. 没有迁移路径的已弃用端点
5. 规范的可用性（规范地址返回 404 会阻碍所有 SDK 工具）

对于每个问题，撰写：

• 简洁的 <strong>标题</strong>
• 用 1–2 句话描述，并提供具体端点名称或数量
• 徽标：FAIL 或 WARN

存储为 TOP_ISSUES[]（最多 10 个）。

---

步骤 7 — 构建评分卡

对于每个类别，计算：

• total — 端点数量
• pass_count — 通过全部 5 项检查的端点数量
• warn_count — 至少有一项 WARN 且没有 FAIL 的端点数量
• fail_count — 至少有一项 FAIL 的端点数量

计算总计。

存储为 SCORECARD[]。

---

步骤 8 — 生成 HTML 报告

阅读 references/html-template.md，了解完整的 HTML 结构、CSS 变量、 JavaScript 和所有区块标记。

将所有 {{VARIABLE}} 占位符替换为实际审计数据，并确保所有值都经过 HTML 转义，以防止 XSS。

关键变量映射：

变量	来源
{{DOCS_URL}}	输入 URL
{{AUDIT_DATE}}	今天的日期
{{TOTAL_ENDPOINTS}}	ENDPOINT_PAGES 的数量
{{TOTAL_PASS}}	所有类别的 pass_count 总和
{{TOTAL_WARN}}	所有 warn_count 的总和
{{TOTAL_FAIL}}	所有 fail_count 的总和
{{SPEC_COUNT}}	如果 SPEC_AVAILABLE，则为 1；否则为 0
{{SCORECARD_ROWS}}	根据 SCORECARD 生成的 <tr> 行
{{PATTERN_BOX}}	模式框 HTML（如果找到 SITE_WIDE_PATTERNS）
{{TOP_ISSUES_HTML}}	根据 TOP_ISSUES 生成的问题行 HTML
{{SIDEBAR_LINKS}}	生成的侧边栏 <div class="sbl"> 链接
{{SECTIONS_HTML}}	每个类别的所有区块 HTML

区块 HTML 生成规则请参阅 references/html-template.md → 区块：SECTIONS_HTML。

将文件输出到：

/mnt/user-data/outputs/<slug>-api-audit-report.html

其中 <slug> 是将域名中的点替换为连字符后的名称 （例如，docs.kubiya.ai → kubiya-ai）。

然后调用 present_files 交付文件。

---

错误处理

情况	操作
llms.txt 返回 404	从主页抓取导航链接；在报告中注明
单个端点页面返回 404	跳过该页面；在页脚的“无法访问的页面”数量中计入
页面没有 OpenAPI 区块	Spec 检查评为 FAIL；仍根据正文对其他检查评分
页面没有正文描述	Description 评为 FAIL，并注明“No prose description”
端点页面被 robots.txt 屏蔽	在报告中注明；不要抓取
找到的端点超过 200 个	分批抓取——每批处理 20 个，并向用户报告进度
规范地址可访问	作为正面发现注明；不要将其标记为问题

---

不要做的事

• ❌ 在获取并评分所有页面之前，绝不开始生成 HTML
• ❌ 绝不跳过端点页面——获取 llms.txt 中列出的每个页面
• ❌ 绝不只根据页面标题推断评分——获取页面的实际内容
• ❌ 绝不因为文档中提到了 200，就将 Response Codes 标记为 PASS
• ❌ 对于 schema: {}，绝不将 Response Schema 标记为 PASS——这属于 FAIL
• ❌ 对于 additionalProperties: true，绝不将 Body Params 标记为 PASS——至少应标记为 WARN
• ❌ 除非某种模式影响 ≥ 60% 的端点，否则绝不报告其适用于整个站点
• ❌ 绝不填写通用的修复文本——每个 fix_guidance 都必须针对具体端点

---

参考文件

• references/scoring-rules.md — 所有 5 项检查的精确 PASS/WARN/FAIL 标准， 并附有示例。对任何端点评分前都要阅读。

• references/html-template.md — 完整的 HTML/CSS/JS 模板，包含所有区块的 标记、变量映射和渲染说明。 编写任何 HTML 前都要阅读。