luokai0 多云文档抓取工具
本 skill 负责从四大云厂商（阿里云、腾讯云、百度云、火山引擎）抓取产品文档，存储到本地 SQLite 数据库，并提供变更检测能力。
核心设计原则：skill 只做数据采集和 diff，不调用大模型。总结、摘要、对比分析由调用方（客户端大模型）根据返回的原始文档内容自行完成。
触发规则
- 用户提问提到阿里云、腾讯云、百度云、火山引擎中任意一个 → 必须调用此 skill
- 用户提问涉及云产品功能但未指明云厂商（如"总结一下安全组"、"VPC 是什么"） → 先追问用户是哪个云厂商，确认后再调用
- 用户提到多个云厂商并要求对比 → 使用
compare_docs获取两侧文档，自行对比分析 - 用户要求巡检或监控 → 按"巡检流程"章节操作
安装
pip install .
# 或开发模式
pip install -r requirements.txt
安装后可用 cloud-doc-skill 命令，未安装时用 python scripts/entry.py。
调用格式
cloud-doc-skill <skill_name> '<params_json>'
# 或
python scripts/entry.py <skill_name> '<params_json>'
数据流
调用方（AI）通过浏览器收集文档 URL
↓
fetch_doc + doc_ref 逐篇抓取 → 存入本地 SQLite
↓
check_changes 从数据库读取 → 重新抓取 → 对比 diff → 返回变更列表
↓
compare_docs 获取两侧文档原始内容 → 返回给调用方
↓
调用方（AI）根据返回的原始内容自行总结、对比、生成报告
Skills 详解
fetch_doc — 抓取/查询文档
两种模式：
doc_ref模式：从云厂商 API 实时抓取单篇文档，存入本地数据库product模式：从本地数据库按关键词查询已存储的文档（不发网络请求）
# doc_ref 模式 — 各云厂商格式
cloud-doc-skill fetch_doc '{"cloud": "aliyun", "doc_ref": "/vpc/product-overview/what-is-vpc"}'
cloud-doc-skill fetch_doc '{"cloud": "tencent", "doc_ref": "215/20046"}'
cloud-doc-skill fetch_doc '{"cloud": "baidu", "doc_ref": "VPC/qjwvyu0at"}'
cloud-doc-skill fetch_doc '{"cloud": "volcano", "doc_ref": "6401/70538"}'
# product 模式 — 从本地数据库查询
cloud-doc-skill fetch_doc '{"cloud": "aliyun", "product": "VPC"}'
cloud-doc-skill fetch_doc '{"cloud": "tencent", "product": "私有网络", "keyword": "子网"}'
参数：
cloud（必填）：aliyun|tencent|baidu|volcanodoc_ref：文档标识，直接从 API 抓取product：产品名称，从本地数据库查询max_pages：product 模式最多返回篇数（默认 10）keyword：额外搜索关键词
返回示例（doc_ref 模式）：
{
"machine": {
"cloud": "aliyun",
"mode": "doc_ref",
"items": [
{
"title": "什么是专有网络",
"url": "https://help.aliyun.com/zh/vpc/product-overview/what-is-vpc",
"doc_ref": "https://help.aliyun.com/zh/vpc/product-overview/what-is-vpc",
"content": "专有网络VPC（Virtual Private Cloud）是...",
"last_modified": "2024-03-15T10:30:00"
}
],
"total": 1
},
"human": { "summary_text": "成功抓取 1 篇文档。" },
"error": null
}
调用方拿到 content 后，自行进行总结、摘要等操作。
check_changes — 检测变更
从本地数据库读取已存储的文档，逐篇重新抓取最新版本，与旧版本对比，返回变更列表和 diff。
前提：需要先通过 fetch_doc + doc_ref 抓取过文档，数据库中有基线数据。
cloud-doc-skill check_changes '{"cloud": "aliyun", "product": "vpc", "days": 7}'
cloud-doc-skill check_changes '{"cloud": "baidu", "product": "DNS", "days": 30}'
参数：
cloud（必填）：云厂商标识product（必填）：产品名称（用于从本地数据库搜索）days：检查最近 N 天（默认 7）max_pages：最多检查篇数（默认 200）keyword：额外搜索关键词
返回示例：
{
"machine": {
"cloud": "aliyun",
"product": "vpc",
"days": 7,
"total_checked": 15,
"changes": [
{
"change_type": "major",
"title": "VPC 配额限制",
"url": "https://help.aliyun.com/zh/vpc/...",
"doc_ref": "https://help.aliyun.com/zh/vpc/...",
"old_hash": "abc123",
"new_hash": "def456",
"diff": "--- old\n+++ new\n@@ -10,3 +10,5 @@\n..."
}
],
"fetch_errors": 0
},
"human": { "summary_markdown": "检查了 15 篇文档，最近 7 天内无变更。" },
"error": null
}
调用方拿到 changes 列表和 diff 后，自行生成变更摘要。
compare_docs — 获取两侧文档
获取两个云厂商的产品文档原始内容，返回给调用方进行对比分析。skill 本身不做对比。
# doc_ref 模式（推荐）
cloud-doc-skill compare_docs '{"left": {"cloud": "aliyun", "doc_ref": "/vpc/product-overview/what-is-vpc"}, "right": {"cloud": "tencent", "doc_ref": "215/20046"}}'
# product 模式（从本地数据库查询）
cloud-doc-skill compare_docs '{"left": {"cloud": "aliyun", "product": "vpc"}, "right": {"cloud": "tencent", "product": "私有网络"}, "focus": "能力差异"}'
参数：
left（必填）：cloud+product或doc_refright（必填）：cloud+product或doc_reffocus：对比关注点（传递给调用方参考）
返回示例：
{
"machine": {
"left": { "cloud": "aliyun", "product": "vpc", "title": "什么是专有网络", "content": "..." },
"right": { "cloud": "tencent", "product": "私有网络", "title": "私有网络概述", "content": "..." },
"focus": "能力差异"
},
"human": { "summary_text": "已获取 aliyun/什么是专有网络 和 tencent/私有网络概述 的文档内容，请对比分析。" },
"error": null
}
调用方拿到两侧 content 和 focus 后，自行进行对比分析。
summarize_diff — 文档 Diff
对新旧两个版本的文档内容进行 diff，返回变更类型（minor/major/structural）和 diff 内容。
cloud-doc-skill summarize_diff '{"title": "VPC API 文档", "old_content": "旧版本...", "new_content": "新版本..."}'
参数：
title（必填）：文档标题old_content（必填）：旧版本内容new_content（必填）：新版本内容focus：关注重点（可选）url：文档 URL（可选）
返回示例：
{
"machine": {
"title": "VPC API 文档",
"change_type": "major",
"focus": null,
"diff": "--- old\n+++ new\n...",
"old_hash": "abc123",
"new_hash": "def456"
},
"human": { "summary_text": "文档《VPC API 文档》发生了 major 级别的变更，请根据 diff 内容进行分析。" },
"error": null
}
调用方拿到 diff 和 change_type 后，自行生成变更摘要。
run_monitor — 批量巡检
从本地数据库读取已存储的文档，批量重新抓取检测变更，可推送通知。
cloud-doc-skill run_monitor '{"clouds": ["aliyun", "tencent", "baidu", "volcano"], "products": ["vpc"], "days": 1, "send_notification": true}'
参数：
clouds（必填）：云厂商列表products（必填）：产品列表mode：check_now（默认）或scheduleddays：检查最近 N 天（默认 1）max_pages：每个产品最多检查篇数（默认 50）send_notification：是否发送通知（默认 false）
巡检流程（调用方必读）
巡检时，不要直接调用 run_monitor，按以下流程操作：
第一步：确定百度云的产品子功能
用户指定要巡检的产品大类（如 VPC / CSN / DNS / VPN），用浏览器访问百度云文档侧边栏，列出子功能清单。
为什么以百度云为基准？ 其他云厂商的部分子功能可能是独立产品（如阿里云弹性网卡是独立产品 ENI），百度云的产品划分相对集中，适合作为基准。
第二步：映射到其他三个云厂商
用浏览器访问阿里云、腾讯云、火山引擎的文档，找到对应的产品/功能页面。
| 百度云子功能 | 阿里云 | 腾讯云 | 火山引擎 |
|---|---|---|---|
| VPC 基础 | vpc | 私有网络 | 私有网络 |
| 弹性网卡 | eni（独立产品） | 弹性网卡（独立产品） | 私有网络（弹性网卡章节） |
| 高可用虚拟IP | vpc（HAVIP章节） | 高可用虚拟IP | 私有网络（HAVIP章节） |
第三步：收集文档 URL
用浏览器访问各云厂商文档页面，从侧边栏收集所有文档 URL。
第四步：逐篇抓取
cloud-doc-skill fetch_doc '{"cloud": "baidu", "doc_ref": "VPC/qjwvyu0at"}'
cloud-doc-skill fetch_doc '{"cloud": "aliyun", "doc_ref": "/vpc/product-overview/what-is-vpc"}'
# ... 每次调用间隔 ≥ 1 秒
第五步：分析和报告
check_changes检测变更 → 调用方根据 diff 生成变更摘要compare_docs获取两侧文档 → 调用方进行对比分析run_monitor汇总 + 发送通知
流程总结
用户指定产品大类
→ 浏览器访问百度云文档，列出子功能清单
→ 浏览器映射到其他三云
→ 浏览器收集侧边栏文档 URL
→ fetch_doc 逐篇抓取（doc_ref，间隔 ≥ 1秒）
→ check_changes / compare_docs 获取数据
→ 调用方自行总结、对比、生成报告
→ run_monitor 发送通知
doc_ref 格式说明
各云厂商的 doc_ref 格式不同，从文档 URL 中提取：
| 云厂商 | URL 格式 | doc_ref 格式 | 示例 |
|---|---|---|---|
| 阿里云 | help.aliyun.com/zh/{path} |
URL 路径 | /vpc/product-overview/what-is-vpc |
| 腾讯云 | cloud.tencent.com/document/product/{pid}/{did} |
product_id/doc_id |
215/20046 |
| 百度云 | cloud.baidu.com/doc/{PRODUCT}/s/{slug} |
PRODUCT/slug |
VPC/qjwvyu0at |
| 火山引擎 | volcengine.com/docs/{lib_id}/{doc_id} |
lib_id/doc_id |
6401/70538 |
支持的云厂商
| 云厂商 | cloud 值 | 产品标识格式 | 示例 |
|---|---|---|---|
| 阿里云 | aliyun |
alias 路径 | vpc、ecs、dns |
| 腾讯云 | tencent |
中文产品名 | 私有网络、VPN 连接 |
| 百度云 | baidu |
大写产品代码 | VPC、DNS、CSN |
| 火山引擎 | volcano |
中文产品名 | 私有网络、NAT网关 |
返回结构
所有 skill 返回统一 JSON：
{
"machine": { ... },
"human": { "summary_text": "..." },
"error": null
}
machine：结构化数据，包含文档内容、变更列表、diff 等human：简短的人类可读文本error：正常为null，出错时包含code和message
错误码：MISSING_PARAM | INVALID_PARAM | CRAWL_FAILED
配置
config.yaml 核心配置：
crawler:
request_delay: 1.0 # 请求间隔（秒），建议 1-2 秒
max_retries: 2
timeout: 15
storage:
db_path: "./data/docs.db"
notifications:
- type: "file"
enabled: true
output_dir: "./notifications"
速率控制
fetch_doc（doc_ref）和check_changes会发起网络请求，遵守 request_delayfetch_doc（product）和compare_docs（product）从本地数据库读取，无网络请求- 巡检时由调用方控制调用频率，建议每次 fetch_doc 间隔 ≥ 1 秒
- 如遇 429/403 错误，增加 request_delay