back
loading skill details...
轻量本地知识库爬取与只读检索工具，支持单工作空间同步更新、关键词搜索和基础SQL查询，适合个人知识管理。
---
slug: smart-crawler-free
name: smart-crawler-free
version: 1.0.0
displayName: 智能爬虫(免费版)
summary: 轻量化本地知识库爬取与检索工具,支持归档同步、新鲜度检测、关键词搜索与基础SQL查询,适合个人知识管理。
license: Proprietary
edition: free
description: '智能爬虫(免费版)是面向个人开发者与知识工作者的轻量化知识库爬取Skill,通过本地归档与只读查询的组合,帮助用户在离线环境下快速检索Notion工作空间内容。核心能力:
- 多源归档同步(桌面导出、API拉取),支持增量更新
- 新鲜度检测,智能判断是否需要刷新归档
- 关键词搜索与基础只读SQL查询
- 工作空间报告(页面数、数据库数、时间跨度)
- 完全只读操作,绝不修改源数据
适用场景:
- 个人Notion知识库的离线检索与备份
- 写作、研究场景的快速资料查找
- 团队Wiki的本地镜像,断网可...'
tags:
- 集成工具
- 知识检索
- 生产力
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: "L2-标准级"
pricing_model: per_use
suggested_price: "19.9 CNY/per_use"
tools: ["read", "exec", "glob", "grep"]
tags: "工具,效率,自动化"
---
# 智能爬虫(免费版)
一个面向个人开发者与知识工作者的轻量化知识库爬取Skill,通过本地归档与只读查询的组合,帮助你在离线环境下快速检索工作空间内容。本免费版聚焦个人工作空间,适合日检索量不超过500次的场景。
## 概述
本Skill将Notion工作空间的内容归档到本地,提供只读查询能力。所有操作均为只读,绝不修改源数据。免费版支持单工作空间归档,适合个人知识管理场景。
## 核心能力
| 能力 | 描述 | 免费版是否支持 |
|---|---|-------|
| 桌面源同步 | 从Notion桌面导出归档 | 支持 |
| API源同步 | 通过API增量拉取 | 支持(单工作空间) |
| 新鲜度检测 | 判断归档是否过期 | 支持 |
| 关键词搜索 | 全文关键词检索 | 支持 |
| 只读SQL查询 | 基础SELECT查询 | 支持(单表) |
| 工作空间报告 | 页面/数据库统计 | 支持 |
| 多工作空间 | 同时管理多个空间 | 不支持 |
| 分布式调度 | 多节点并行爬取 | 不支持 |
| 增量索引 | 仅更新变更部分 | 不支持 |
| 自定义导出 | 导出为Markdown/PDF | 不支持 |
### 核心功能执行
用`input_params`参数进行配置。
**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回核心功能执行的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 参数配置与调用
用`config_options`参数进行配置。
**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回参数配置与调用的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作
### 结果处理与输出
用`output_format`参数进行配置。
**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：轻量化本地知识库、爬取与检索工具、支持归档同步、关键词搜索与基础、适合个人知识管理、智能爬虫、是面向个人开发者、与知识工作者的轻、量化知识库爬取、通过本地归档与只、读查询的组合、帮助用户在离线环、境下快速检索、工作空间内容、核心能力等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。
## 使用场景
### 场景一:个人知识库离线检索
写作者希望在断网环境下也能检索自己的Notion笔记。
```bash
# 1. 检查归档状态
smart-crawler doctor
smart-crawler status --json
# ...
# 2. 从桌面导出同步归档
smart-crawler sync --source desktop
# ...
# 3. 关键词搜索
smart-crawler search "时间管理"
# ...
# 4. 查看工作空间报告
smart-crawler report
```
### 场景二:写作前的资料快速查找
研究者在撰写报告前,需要快速回顾相关笔记。
```bash
# 查找包含特定关键词的页面
smart-crawler search "用户研究方法"
# ...
# 查询页面数量统计
smart-crawler sql "select count(*) from pages;"
# ...
# 列出所有数据库
smart-crawler databases
```
### 场景三:团队Wiki的本地镜像
小团队成员希望在工作中频繁查询Wiki,但不希望每次都打开浏览器。
```bash
# 定期同步(建议每天一次)
smart-crawler sync --source desktop
# ...
# 检查是否需要刷新
smart-crawler status
# 输出:last_sync=2026-07-17, freshness=stale(超过24小时)
# ...
# 刷新归档
smart-crawler sync --source api
```
## 不适用场景
以下场景智能爬虫(免费版)不适合处理：
- 数据库架构设计决策
- NoSQL选型
- 数据仓库ETL设计
## 触发条件
需要数据库操作、SQL查询、数据存储管理时使用。不适用于非本工具能力范围的需求。
## 快速开始
预计上手时间:<60秒。
### 依赖详情
```bash
npm install -g smart-crawler
```
### Step 2:首次同步
```bash
# 从Notion桌面应用导出的归档同步
smart-crawler sync --source desktop
# ...
# 或通过API同步(需要NOTION_TOKEN)
export NOTION_TOKEN="your_notion_integration_token"
smart-crawler sync --source api
```
### Step 3:验证归档
```bash
smart-crawler doctor
# 输出:归档完整,共1234个页面,56个数据库
```
### Step 4:开始检索
```bash
smart-crawler search "你的关键词"
```
## 示例
### 归档存储位置
```bash
# 默认存储位置
~/.smart-crawler/archive/
# ...
# 自定义存储位置
export SMART_CRAWLER_HOME="/path/to/custom/archive"
```
### 同步策略配置
```json
{
"sync": {
"source": "desktop",
"interval": "daily",
"maxPages": 5000,
"excludeDatabases": ["archive_old"]
},
"freshness": {
"threshold": "24h",
"autoRefresh": false
}
}
```
### SQL查询示例
```sql
-- 查询页面总数
select count(*) from pages;
# ...
-- 查询最近更新的页面
select title, last_updated from pages order by last_updated desc limit 10;
# ...
-- 按数据库分组统计
select database_id, count(*) as page_count from pages group by database_id;
```
> **重要**:仅支持只读SELECT查询,禁止任何修改语句(INSERT/UPDATE/DELETE),系统会自动拦截。
## 最佳实践
1. **优先使用桌面源同步**:桌面导出对API配额无消耗,适合日常刷新
2. **设置合理的同步频率**:个人知识库每天同步一次足够,避免频繁同步占用资源
3. **使用具体关键词搜索**:关键词越具体,检索结果越精准
4. **定期清理过期归档**:超过3个月未访问的归档可删除,释放存储空间
5. **先搜索后SQL**:简单查询用search,复杂统计再用SQL
6. **保持只读原则**:任何对源数据的修改都应通过原生客户端完成
## 常见问题
### Q1: 同步失败提示"Token无效"怎么办?
A: 检查NOTION_TOKEN是否正确设置、是否过期、Integration是否有访问目标页面的权限。在Notion中需要将页面"共享给Integration"。
### Q2: 归档文件占用空间过大?
A: 1)检查是否有大量媒体文件(图片、附件);2)在同步配置中排除不需要的数据库;3)定期清理历史归档。
### Q3: 搜索结果不全?
A: 1)检查归档是否过期(stale状态需重新同步);2)确认关键词拼写;3)尝试使用SQL查询验证页面是否在归档中。
### Q4: SQL查询报错"只读模式"?
A: 系统强制只读,任何修改语句都会被拦截。请使用SELECT语句,或通过Notion原生客户端修改数据。
### Q5: 免费版可以同步多个工作空间吗?
A: 不可以。免费版仅支持单工作空间归档。多工作空间管理请使用专业版。
## 错误处理
| 错误场景(症状) | 可能原因 | 解决方案 |
|:---------|:---------|:---------|
| sync命令卡住 | 网络不稳定或归档过大 | 执行ping命令测试网络连通性,检查防火墙和代理设置,使用`--source desktop`替代API |
| 搜索无结果 | 归档为空或关键词不匹配 | 运行`doctor`检查归档完整性,调整关键词 |
| SQL语法错误 | 使用了不支持的关键字 | 仅使用SELECT,参考"SQL查询示例" |
| doctor报错"归档损坏" | 同步中断导致数据不完整 | 删除归档目录,重新执行sync |
| 状态显示stale | 超过24小时未同步 | 执行`smart-crawler sync`刷新归档 |
## 已知限制
本免费体验版限制以下高级功能:
- 多工作空间管理(同时管理>1个工作空间)
- 分布式调度(多节点并行爬取)
- 增量索引(仅更新变更部分)
- 自定义导出(Markdown/PDF/HTML)
- 高级SQL查询(多表JOIN、子查询)
- 定时自动同步(cron调度)
- 全文检索引擎(中文分词、同义词)
- 团队协作与共享归档
解锁全部功能请使用专业版:smart-crawler-pro
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
## 依赖说明
### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux
- **Node.js**: 16+(用于运行smart-crawler CLI)
- **Python**: 3.8+(可选,用于辅助脚本)
### 第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---:|---:|---:|---:|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| smart-crawler CLI | 命令行工具 | 必需 | `npm install -g smart-crawler` |
| Notion Integration | 在线服务 | 可选 | 通过Notion开发者平台创建 |
| SQLite | 数据库 | 必需 | Node.js内置或系统自带 |
### API Key 配置
- **NOTION_TOKEN**: 通过环境变量传入,用于API源同步
- **存储位置**: 默认`~/.smart-crawler/archive/`,可通过`SMART_CRAWLER_HOME`自定义
- **安全建议**: Token仅用于只读访问,定期检查Integration权限范围
- **权限最小化**: Notion Integration仅授予"读取内容"权限,禁止授予写入权限
### 可用性分类
- **分类**: MD+EXEC(纯Markdown指令,部分功能需exec命令行执行)
- **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作
## 输出格式
```json
{
"success": true,
"data": {
"result": "智能爬虫(免费版)处理结果",
"execution_time": "0.5s",
"metadata": {
"version": "1.0",
"processor": "smart crawler"
}
},
"execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
"error": null
}
```
don't have the plugin yet? install it then click "run inline in claude" again.