sdk-docs-auditor

SDK 文档审计工具

对任意 SDK 文档站点进行全面、交叉引用的审计，并生成带完整样式、可下载的 HTML 报告。

此技能的功能

1. 首先通过 llms.txt 发现所有 SDK 页面；若无结果，则使用 sitemap.xml（通过 curl），再尝试爬取首页导航
2. 获取并阅读所有相关 SDK 页面
3. 审计六个固定部分：安装、快速入门、错误处理、故障排查、示例、最佳实践
4. 在所有其他 SDK 页面中交叉核对每项缺漏——如果内容存在于其他位置，绝不将其标记为缺失
5. 为每个部分评分（0–100），并分配评级
6. 生成精美、独立完整且可下载的 HTML 报告

---

步骤 1 — 发现所有 SDK 页面

按顺序尝试以下三种发现方式，直到其中一种成功。

1a. 首先尝试 llms.txt（首选）

运行 bash curl 命令获取 llms.txt：

curl -s <docs_url>/llms.txt

如果找到：

• 从符合 - [Page Title](URL): description 模式的行中提取所有 URL
• 仅筛选与 SDK 相关的页面——保留路径中包含以下任一内容的 URL： sdk、installation、quickstart、quick-start、error、troubleshoot、example、best-practice、getting-started、reference、api-reference、overview、client、service、memory、search、worker、job、policy、agent、team
• 排除：营销页面、变更日志、博客、法律页面、社区／论坛页面
• 保存为 SDK_PAGES[]——由 {title, url, description} 组成的列表
• 在报告中注明：“发现方式：llms.txt”

1b. 回退方案 — 尝试 sitemap.xml

如果 llms.txt 不可用或没有返回有用的 URL，则运行 bash curl 命令获取站点地图：

curl -s <docs_url>/sitemap.xml | python3 -c "import sys, re; print('\n'.join(re.findall(r'<loc>(.*?)</loc>', sys.stdin.read())))"

如果站点地图返回了 URL：

• 解析每个 <loc> 条目，获取完整 URL 列表
• 使用上方相同的关键词列表进行筛选
• 保存为 SDK_PAGES[]——由 {title, url} 组成的列表
• 在报告中注明：“发现方式：sitemap.xml — 共找到 N 个 URL，保留 M 个 SDK 相关 URL”

另外，检查是否存在站点地图索引（包含多个站点地图）：查看响应中是否有 <sitemapindex>。如果有，则使用 curl 获取每个子站点地图，并在筛选前汇总所有 URL。

1c. 最终回退方案 — 爬取首页导航

如果 llms.txt 和 sitemap.xml 都失败，则获取文档首页（<docs_url>），并从导航侧边栏或站点地图结构中提取所有链接，使用相同的关键词列表进行筛选。

• 在报告中注明：“发现方式：首页导航爬取（llms.txt 和 sitemap.xml 不可用）”

1d. 确定部分映射关系

根据发现的页面，确定哪些页面对应六个审计目标：

审计部分	查找路径／标题中包含以下内容的页面
安装	install、setup、getting-started
快速入门	quick-start、quickstart、tutorial
错误处理	error、exception、errors
故障排查	troubleshoot、faq、debug
示例	example、sample、cookbook、tutorial
最佳实践	best-practice、guide、pattern

如果某个部分没有找到专门页面，请注明这一点——缺少页面本身也是一项发现。

构建语料库

所有发现的页面都构成页面语料库，用于审计各部分并进行交叉引用。

报告发现摘要：

通过 [sitemap.xml / llms.txt / 导航爬取] 找到 N 个页面。保留 M 个与 SDK 相关的页面。正在获取……

---

步骤 2 — 获取语料库中的每个页面

使用 bash_tool 和 curl 获取每个页面，并通过 Python 去除 HTML 标签以提取纯文本。不要使用 web_fetch 获取语料库页面——curl 更可靠，也可避免权限错误。

对每个页面 URL 使用以下模式：

curl -s "https://docs.example.com/sdk/some-page" -L | python3 -c "
import sys, re, html
content = sys.stdin.read()
content = re.sub(r'<script[^>]*>.*?</script>', '', content, flags=re.DOTALL)
content = re.sub(r'<style[^>]*>.*?</style>', '', content, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', content)
text = html.unescape(text)
text = re.sub(r'\s+', ' ', text).strip()
print(text[:6000])
"

Batch multiple pages in a single bash call using a loop to minimise round-trips:

```bash
for page in installation quick-start error-handling troubleshooting examples best-practices overview api-reference; do
  echo "=== PAGE: $page ==="
  curl -s "https://docs.example.com/sdk/$page" -L | python3 -c "
import sys, re, html
content = sys.stdin.read()
content = re.sub(r'<script[^>]*>.*?</script>', '', content, flags=re.DOTALL)
content = re.sub(r'<style[^>]*>.*?</style>', '', content, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', content)
text = html.unescape(text)
text = re.sub(r'\s+', ' ', text).strip()
print(text[:6000])
"
  echo ""
done

对于大型站点（超过 30 个页面），按以下顺序确定优先级：

1. 六个目标部分页面（安装、快速入门、错误处理、故障排查、示例、最佳实践）
2. 概览／客户端概览页面
3. API 参考
4. 特定服务页面（Agent、任务、工作进程、策略、内存、搜索等）

---

步骤 3 — 审查六个目标章节

仔细阅读以下六个章节的页面，并根据评估标准逐项检查。然后检查已获取的其他所有页面，确认其中是否已解决任何遗漏。

3a. 安装

必须包含（缺失时大幅扣分）：

• 注明确切版本的先决条件（Python/Node/语言版本、包管理器）
• 至少一条完整的安装命令（pip/npm 等）
• 认证设置，包括获取和配置凭据的确切步骤
• 能证明安装成功的可运行验证代码片段
• 至少一项预期输出或成功确认信息

应包含（缺失时适度扣分）：

• 多种安装方式（包管理器、源码、Docker）
• IDE/编辑器设置
• 使用 .env 示例配置环境变量
• 版本兼容性表格
• 可选依赖说明（每个额外依赖包含什么）
• 构造函数参数参考（所有参数、类型、默认值）

检查其他页面中是否存在的常见遗漏：

• 环境变量自动检测（不传参数调用时，客户端是否会读取环境变量？）——检查 api-reference、overview
• 高级构造函数参数（timeout、retries、org）——检查 api-reference
• 版本锁定指导——检查任何入门页面

3b. 快速入门

必须包含：

• 简洁的编号步骤，新用户可在 5 分钟内完成
• 从零开始到首次成功调用的完整可运行代码
• 每个代码片段的预期输出
• 对任何先决服务/资源（队列、工作进程等）的说明

应包含：

• 环境变量和内联凭据两种配置方式
• 多种安装选项（pip + poetry 等）
• 为所介绍的每个概念提供深入文档链接

检查以下常见遗漏：

• 工作进程/队列的先决条件——检查 workers/environments 页面
• 有效的模型/运行时 ID——检查 models/runtimes 服务页面
• Execute 调用签名是否准确——检查 api-reference 和 agents 服务页面

3c. 错误处理

必须包含：

• 完整的异常层次结构（所有异常类及其继承关系）
• 每个异常类的文档，包括：说明、导入路径、代码示例
• 至少涵盖：认证、连接、超时、速率限制、API/HTTP 错误
• HTTP 状态码分支处理（至少包括 400/401/403/404/500）
• 至少一种弹性处理模式（带退避的重试）

应包含：

• 特定于资源的异常（每项主要服务对应一种）
• 流式传输错误处理
• 上下文管理器清理模式
• 错误场景的测试/pytest 示例
• 错误做法与正确做法的反模式示例

交叉引用检查——至关重要：

• 列出 api-reference 或服务页面中出现的每个异常类
• 标记本页缺少的异常类
• 检查 execute/方法调用签名在所有页面中是否一致——标记任何差异

3d. 故障排查

必须包含：

• 认证失败的诊断步骤
• 连接/超时问题及解决方案
• 至少一个特定于服务的故障排查章节

应包含：

• 针对每项主要服务（workers、jobs、policies、agents 等）的故障排查
• 可自托管/自定义 base_url 相关问题
• 导入错误及正确的导入路径
• 汇总错误消息的查询表
• 速率限制及退避相关参考
• 包含实际链接/命令、可执行的“获取帮助”检查清单

交叉引用检查：

• 对于每个包含独立错误处理章节的服务页面，检查其中的场景是否也出现在本页
• 描述“未找到”错误时，检查是否链接到数据集/资源创建方法
• 检查“验证状态”步骤是否引用了健康检查 API

3e. 示例

必须具备：

• 每个主要服务至少有一个完整、可运行的端到端示例
• 每个示例都展示预期输出
• 工作流示例中包含错误处理

应该具备：

• 覆盖以下内容：Agent 生命周期、作业／调度、记忆／回忆、语义搜索、策略管理、Worker 管理、流式处理
• 不要提供仅调查资源、却不执行任何操作的“工作流”示例
• SDK 支持会话时，提供多轮／会话管理示例

交叉引用检查——大多数缺口都积累在这里：

• 对于每个有独立示例页面的服务，检查其示例是否已在此处体现
• 标出每个缺失的服务类别，并注明包含相关示例的源页面

3f. 最佳实践

必须具备：

• 身份验证／凭证安全章节
• 错误处理／重试逻辑
• 性能（批处理、分页、缓存）

应该具备：

• 每个主要服务各有一个最佳实践章节（Worker、作业、策略、Agent）
• 资源清理／上下文管理器
• 代码组织（类型提示、可复用函数）
• 测试模式
• 并发／线程安全指南
• 密钥轮换／凭证生命周期

交叉引用检查：

• 对于每个定义了自身最佳实践的服务页面，检查这些模式是否已在此处体现
• 注明并发／线程安全是否在整个内容库的任何位置有所涉及

---

第 4 步——为每个章节评分

使用以下标准按 0–100 分评分：

分数	含义
85–100	强——具备所有必须项、大多数应该项，且缺口很少
70–84	良好——具备所有必须项，但缺少一些应该项
50–69	尚可——具备大多数必须项，但存在明显缺口
30–49	薄弱——缺少多个必须项
0–29	很差——章节内容流于表面或基本缺失

指定一个评级标签：强 / 良好 / 尚可 / 薄弱 / 很差

---

第 5 步——整理各章节的缺口清单

对于每个缺口：

• 用一句清晰的话描述缺失内容
• 如果内容在内容库中存在，为其标注位置：[covered in: page-name]
• 或标注：[not covered anywhere in corpus]

这一区分至关重要——内容在其他位置存在的缺口，只需交叉引用或整合；而内容在任何位置都不存在的缺口，则需要新增页面。

---

第 6 步——得出优先级最高的建议

按影响 × 工作量对前 6–8 项行动排序。优先处理：

1. 事实错误／签名不匹配（优先级最高——会导致用户操作失败）
2. 内容库中任何位置都未覆盖的必须项缺口
3. 其他位置已覆盖但未链接的必须项缺口
4. 高价值的应该项缺口
5. 交叉引用和内容整合机会

---

第 7 步——生成 HTML 报告

读取 assets/report-template.html 中的模板，并将所有审计数据填入其中。

填写以下占位符：

• __AUDIT_URL__ → 已审计的 URL
• __PAGES_FETCHED__ → 获取的页面总数
• __AUDIT_DATE__ → 今天的日期
• __SECTION_DATA_JSON__ → JSON 数据块（参见下方架构）
• __PRIORITIES_JSON__ → JSON 数据块（参见下方架构）
• __OVERALL_SCORE__ → 整数 0–100（六项评分的加权平均值）

数据架构

{
  "sections": [
    {
      "num": "01",
      "name": "Installation Guide",
      "rating": "Good",
      "score": 74,
      "strengths": ["string", ...],
      "gaps": [
        {
          "text": "Description of the gap",
          "covered_in": ["page-name-1", "page-name-2"],
          "nowhere": false
        }
      ]
    }
  ]
}

当缺口在内容库中任何位置都不存在时，设置 "nowhere": true 和 "covered_in": []。

{
  "priorities": [
    {
      "rank": 1,
      "text": "Fix X in Y page. The correct form per api-reference is Z.",
      "type": "error"
    }
  ]
}

优先级类型："error"（事实错误）、"missing"（任何位置都未覆盖）、"xref"（其他位置已覆盖，需要添加链接）、"improvement"（应该项缺口）。

---

输出

将最终报告保存到 /mnt/user-data/outputs/sdk-audit-report.html，并使用 present_files 呈现该文件。

告知用户：

• 获取了多少页面
• 总体评分及其含义
• 最关键的一项发现

不要在聊天中复现完整报告内容——只需呈现文件并提供简要摘要。