> 核心功能: 本技能提供中文交互、化工作流场景等能力。

问题诊断

问题1: Google搜索结果为空或配额耗尽

现象: google-search-4返回空结果或403配额错误
原因: GOOGLE_API_KEY未配置、GOOGLE_CSE_ID错误或每日免费100次配额用尽
解决:
1. 检查 GOOGLE_API_KEY 和 GOOGLE_CSE_ID 环境变量是否配置
2. 确认Google Cloud Console中CSE已启用且配置了搜索范围
3. 检查Google API Dashboard确认配额使用情况
4. 配额耗尽时自动降级到free-web-search-4（Bing/DuckDuckGo免费搜索）
5. 国内环境可直接使用free-web-search-4，无需Google API

问题2: 网页抓取被目标网站拦截

现象: web-crawler-engine抓取返回403 Forbidden或频繁超时
原因: 目标网站部署了反爬虫机制，检测到自动化请求
解决:
1. 降低并发数（max_workers从5降到2）
2. 增加请求间隔（rate_limit_per_sec从2降到1）
3. 设置真实的User-Agent头（模拟浏览器请求）
4. 启用请求间隔随机化（避免固定频率被检测）
5. 如目标网站有公开API，优先使用API而非网页抓取
6. 遵守目标网站的robots.txt协议

问题3: 增量同步数据重复

现象: 增量同步后数据库中出现重复数据
原因: 时间戳基准不一致或去重逻辑失效
解决:
1. 确认增量同步基于last_sync时间戳，而非固定时间窗口
2. 检查URL哈希去重逻辑（MD5哈希）是否正常工作
3. 确认数据源的时间戳字段格式一致（ISO 8601）
4. 手动清理重复数据：使用SQL DISTINCT或GROUP BY去重
5. 重新设置last_sync时间戳，从正确的时间点开始同步

问题4: SQL分析结果不准确

现象: SQL分析的数据统计与预期不符
原因: 数据归档不完整、SQL语法错误或时区问题
解决:
1. 确认数据归档完整（检查crawled_count vs new_count）
2. 检查SQL语法，特别是GROUP BY和WHERE条件
3. 确认时间戳时区一致（统一使用UTC或本地时区）
4. 使用COUNT(*)验证数据总量，与归档记录数对比
5. 关键词频次分析使用LIKE + CASE，确认关键词匹配规则正确

问题5: DuckDuckGo搜索结果质量不稳定

现象: free-web-search-4返回的搜索结果相关度较低
原因: DuckDuckGo免费API的结果排序和索引范围有限
解决:
1. DuckDuckGo为免费兜底方案，结果质量低于Google CSE
2. 优化查询关键词，使用更精确的搜索词
3. 配置BING_API_KEY启用Bing搜索，结果质量优于DuckDuckGo
4. 优先使用internet-search-pro-2的AI优化查询构造功能
5. 多引擎结果交叉验证，取交集提高准确率

使用范围限制

搜索类限制

• Google CSE配额: 每日免费100次查询，超出需付费或降级到免费搜索
• 搜索结果时效性: 搜索引擎索引有延迟，最新内容可能未被索引
• 国内可用性: Google搜索在国内需VPN，建议国内用户优先使用free-web-search-4（Bing/DuckDuckGo）
• 查询长度: 搜索查询建议不超过50个词，过长查询可能被截断
• 结果数量: 单次搜索返回结果有限（Google CSE最多10条/次，Bing最多50条/次）

抓取类限制

• 反爬虫限制: 目标网站可能部署反爬虫机制，高频抓取会被拦截
• ** robots.txt**: 应遵守目标网站的robots.txt协议，不抓取禁止访问的页面
• 数据格式: 网页内容解析依赖HTML结构，目标网站改版可能导致解析失败
• 并发上限: 建议单实例并发不超过10，过高并发可能触发封IP
• 存储空间: 大量抓取数据需足够的磁盘空间，建议定期归档清理

不适用场景

• 需要登录认证才能访问的内容（搜索和抓取仅支持公开页面）
• 实时数据流处理（本Plug为批量抓取+定时同步，非实时流处理）
• 视频和图片内容分析（本Plug聚焦文本数据抓取和分析）
• 深度网页交互（如JavaScript动态渲染的SPA页面，需配合浏览器自动化工具）
• 需要完全离线运行的场景（搜索和抓取均需要网络连接）
• 大规模分布式爬虫场景（本Plug为单机方案，不支持分布式部署）
• 实时性要求<100ms的场景

常见疑问

Q1: Plug中的技能可以单独使用吗？

A: 可以，Plug中的每个技能都是独立的，可以单独调用。free-web-search-4可零配置直接使用（DuckDuckGo免费无需API Key），组合使用时效果更佳。

Q2: Google搜索API配额用完了怎么办？

A: Google CSE每日免费100次查询，用完后自动降级到free-web-search-4（Bing+DuckDuckGo双引擎免费搜索）。也可升级Google API付费计划增加配额。

Q3: 国内环境如何使用搜索功能？

A: Google搜索在国内需VPN，建议国内用户优先使用free-web-search-4（Bing+DuckDuckGo，国内可直接访问）。也可配置Bing API（国内可访问）替代Google搜索。

Q4: 网页抓取会被目标网站封IP吗？

A: 高频抓取可能触发反爬虫机制。建议：1）降低并发数（2-3个）；2）增加请求间隔（1-2秒/次）；3）设置真实User-Agent；4）遵守robots.txt协议；5）如目标网站有公开API，优先使用API。

Q5: 增量同步如何工作？

A: 增量同步基于时间戳，仅采集上次同步后的新数据。支持四种触发方式：定时同步（Cron调度）、事件触发（Webhook回调）、手动同步（命令行触发）、混合模式（定时+事件）。同步异常自动告警并下次重试。

安全

API Key零暴露原则

• 所有API Key（LLM_API_KEY/GOOGLE_API_KEY/GOOGLE_CSE_ID/BING_API_KEY）必须通过Agent环境变量注入
• 严禁在SKILL.md、配置文件或代码中硬编码API Key
• 本SKILL.md中不包含任何真实或示例API Key，所有引用均使用 $env:GOOGLE_API_KEY 占位
• exec工具记录日志时，自动过滤包含"key"/"token"/"secret"字段的值

数据安全

• 抓取合规: 遵守目标网站robots.txt协议，不抓取禁止访问的页面
• 数据隐私: 抓取的公开数据不含个人隐私信息，如意外包含会自动脱敏处理
• 版权提示: 抓取的数据仅供研究分析使用，商业使用需确认数据版权
• 存储安全: 归档数据存储在本地文件系统，不上传到第三方服务

国内适配性

• 搜索引擎: Bing API/百度搜索API/搜狗搜索API（替代Google搜索，国内可直接访问）
• 免费搜索: DuckDuckGo免费API（全球可用，无需API Key）
• LLM API: 通义千问/文心一言/智谱GLM/DeepSeek/Kimi（国内大模型替代海外LLM）
• 数据库: 达梦/人大金仓/TDSQL（替代MySQL/数据库）
• 告警通知: 飞书/钉钉/企业微信（替代Slack/Discord）

• Python发行版: Anaconda/miniconda（国内镜像源加速下载）

技术创新

效率提升量化分析

# 安装和初始化
skill install plug-intelligent-data-research
# 基本调用示例
skill execute plug-intelligent-data-research --input "示例输入"

高级用法

# Python API调用示例
import requests
# 配置API端点
api_url = "http://localhost:8080/api/skills/plug-intelligent-data-research"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
# 执行技能
response = requests.post(api_url, json={
    "input": "示例输入数据",
    "options": {"mode": "advanced"}
})
result = response.json()
print(result)

命令行批处理

# 批量处理多个输入
for file in *.csv; do
  skill execute plug-intelligent-data-research --input "$file" --output "result_$file"
done

===

智能数据研究工作站

> 搜索、聚合、抓取、分析，4合1AI驱动数据研究平台：多引擎搜索精准获取信息，网页抓取引擎批量归档数据，SQL分析挖掘数据洞察

主要能力

本Plug将数据研究流程拆解为4个阶段：多引擎搜索获取信息源、精准搜索锁定目标数据、免费搜索兜底覆盖、网页抓取引擎批量归档并SQL分析。4个技能形成从信息发现到数据归档到分析洞察的完整研究闭环。

包含技能

internet-search-pro-2 (AI搜索) ──发现信息源──> google-search-4 (精准搜索)
         │                                         │
    多源聚合搜索                            Google CSE精准定位
         │                                         │
         v                                         v
free-web-search-4 (免费兜底) <──Bing/DuckDuckGo──> web-crawler-engine (批量抓取)
         │                                         │
    免费方案覆盖                             增量同步+SQL分析
                                                   │
                                              数据洞察输出

• internet-search-pro-2 为研究起点，AI优化查询构造，多源聚合搜索发现信息源
• google-search-4 使用Google CSE对特定领域进行精准搜索，结果排序更相关
• free-web-search-4 在Google搜索配额耗尽或不可用时，通过Bing+DuckDuckGo双引擎兜底
• web-crawler-engine 接收搜索发现的URL列表，批量抓取归档，增量同步，SQL分析输出数据洞察

使用时机

{
  "plug": "plug-intelligent-data-research",
  "action": "execute_workflow | execute_single",
  "input": {
    "workflow": "full | search_only | google_only | free_search_only | crawl_only",
    "search_input": {
      "query": "AI编程工具 竞品对比 2026",
      "category": "tech",
      "depth": "multi_step"
    },
    "google_input": {
      "query": "AI编程工具 竞品对比",
      "cse_id": "custom_search_engine_id",
      "num_results": 10
    },
    "free_search_input": {
      "query": "AI编程工具 竞品对比",
      "engine": "auto"
    },
    "crawl_input": {
      "urls": ["https://example.com/article1", "https://example.com/article2"],
      "max_workers": 5,
      "rate_limit_per_sec": 2,
      "sync_strategy": "incremental",
      "sync_interval_minutes": 60
    }
  },
  "options": {
    "format": "json",
    "verbose": true
  }
}

响应格式

{
  "status": "success",
  "plug": "plug-intelligent-data-research",
  "results": [
    {
      "step": 1,
      "skill": "internet-search-pro-2",
      "status": "completed",
      "output": {
        "results": [
          {
            "title": "2026年AI编程工具横评：5款主流工具对比",
            "url": "https://example.com/ai-tools-review",
            "snippet": "本文对比了Cursor、Copilot、Claude等5款AI编程工具...",
            "source": "multi_source",
            "relevance_score": 0.95
          }
        ],
        "total_results": 15,
        "search_depth": "multi_step"
      }
    },
    {
      "step": 2,
      "skill": "web-crawler-engine",
      "status": "completed",
      "output": {
        "crawled_count": 15,
        "new_count": 12,
        "duplicate_count": 3,
        "archive_path": "data/research/2026-07-29/",
        "sql_analysis": {
          "top_keywords": [{"keyword": "Cursor", "count": 28}, {"keyword": "Copilot", "count": 22}],
          "date_distribution": {"2026-07": 15, "2026-06": 8}
        }
      }
    }
  ],
  "metadata": {
    "total_steps": 2,
    "duration_ms": 30000,
    "timestamp": "2026-07-29T10:00:00Z"
  }
}

环境要求

运行环境

• Agent平台: Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持SKILL.md的任意Agent
• 操作系统: Windows / macOS / Linux
• 运行时: 需要Agent支持 exec（命令行执行）能力
• 网络: 搜索和抓取均需要网络连接（必需）

依赖项

A1: 多引擎搜索/网页抓取/SQL分析/增量同步,4合1数据研究平台。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

快速启航

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

用户咨询