Smart Crawler Free

轻量本地知识库爬取与只读检索工具，支持单工作空间同步更新、关键词搜索和基础SQL查询，适合个人知识管理。

智能爬虫(免费版)

一个面向个人开发者与知识工作者的轻量化知识库爬取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
}