笔记自动化抓取工具

一款高性能的Obsidian笔记自动化抓取工具,通过智能网页抓取技术将结构化数据自动整合到知识库中。

  • by Antonymwangi20
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Antonymwangi20/obsidian-mcp-actor

使用说明

黑曜石MCP演员

一个安全、高性能的Apify Actor,通过模型上下文协议(MCP)将黑曜石笔记工作流程与智能网络抓取自动化连接起来。使用来自任何网站的结构化数据自动丰富您的知识库。

🎯 v2.0中的新增功能

🛡️ 安全加固

  • 路径遍历保护:根据vault目录验证所有文件操作
  • 内容大小限制:防止最大内容大小为10MB的OOM
  • 输入验证:具有明确错误类别的山宁泰URL和文件名
  • Robots.txt合规性:自动尊重 robots.txt 规则

⚡ 性能和可扩展性

  • 并行处理:并发图像下载(速度快3-10倍)
  • 智能缓存:三种缓存策略(内存、磁盘、Apify KV)
  • 指数退避:针对速率受限站点的具有抖动的智能重试逻辑
  • 隐身模式:增强了剧作家规避,以保护反机器人

🏗️ 现代建筑

  • 服务导向设计:模块化、可测试、可维护
  • 策略模式:可插拔的刮擦引擎(Cheerio→ 剧作家后备)
  • 实时监控:实时WebSocket进度查看器
  • TypeScript支持:核心接口的完整类型定义

🔥 主要特点

特性 描述
🤖 双刮发动机 Cheerio代表速度,Playwright代表JavaScript密集型网站
💾 持久缓存 避免在运行之间使用磁盘支持的缓存进行重新抓取
🏷️ 智能标记 从内容、元数据、JSON-LD和域中提取标签
🔗 自动内部链接 通过共享标签自动链接相关笔记
📸 图像处理 通过并行处理下载和参考图像
📝 模板支撑 通过Obsidian模板文件配置抓取
📊 实时进度 WebSocket查看器显示实时抓取状态
🔐 安全第一 路径遍历保护、输入验证、大小限制
🎯 MCP集成 向Claude/LLM展示5个工具,用于AI驱动的工作流程
📈 性能指标 跟踪缓存命中率、处理时间和吞吐量

🚀 快速开始

单个URL报废

{
  "url": "https://example.com/article",
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "folderPath": "research/articles",
  "tags": ["ai", "research"],
  "autoTag": true,
  "autoLink": true
}

带缓存的批量导入

{
  "urls": [
    "https://site1.com/post",
    "https://site2.com/guide",
    "https://site3.com/tutorial"
  ],
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "bulkMode": true,
  "usePlaywright": false,
  "cache": "disk",
  "rateLimitDelay": 2000
}

JavaScript重度网站

{
  "url": "https://react-app.example.com",
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "usePlaywright": true,
  "enableStealth": true,
  "playwrightTimeout": 45
}

📋 配置参考

核心设置

参数 类型 必填 默认 说明
url string 否* - 要抓取的单个URL(使用 urls 散装)
urls array 否* [] 批量导入的URL数组
vaultPath 字符串 是 - 通往黑曜石金库的绝对路径
folderPath string 否 scraped vault中的子文件夹路径
noteName string 否 自动 自定义笔记文件名(自动清理)

处理选项

参数 类型 默认值 说明
addMetadata 布尔值 true 包含YAML前端内容
tags 阵列 [] 要应用的手动标签
autoTag 布尔值 true 启用智能自动标记
autoLink 布尔值 true 在笔记之间创建内部链接
updateExisting 布尔值 false 允许覆盖现有笔记
templatePath string - 黑曜石配置模板

性能和可靠性

参数 类型 默认值 说明
usePlaywright 布尔值 false 使用Chrome浏览器自动化
playwrightTimeout 编号 30 页面加载超时(秒)
enableStealth 布尔值 true 应用反机器人规避
maxRetries 编号 3 每个URL重试次数
rateLimitDelay 编号 2000 请求之间的延迟(ms)
cache 字符串 memory 缓存类型: memory, disk, apify
downloadImages 布尔值 false 将图像下载到vault
concurrency 编号 3 并行下载工作器

*要么 url 或 urls 必须提供


📁 生成的笔记格式

---
title: "Understanding Machine Learning"
url: https://example.com/ml-guide
scraped: 2024-01-15T10:30:00.000Z
tags: ["machine-learning", "ai", "research", "technology", "example"]
description: "A comprehensive guide to ML fundamentals"
author: "Jane Smith"
---

# Understanding Machine Learning

> 🔗 Source: [https://example.com/ml-guide](https://example.com/ml-guide)

> 📅 Scraped: January 15, 2024

---

## Article Content

Full content converted to Markdown...

---

## Metadata

- **Author:** Jane Smith
- **Description:** A comprehensive guide to ML fundamentals
- **Canonical:** https://example.com/ml-guide
- **Robots:** index,follow

🎓 高级用法

基于模板的配置

创建 templates/scraper-config.md 在您的保险库中:

---
folderPath: "research/ai-papers"
autoTag: true
autoLink: true
tags: ["ai", "paper"]
usePlaywright: false
cache: "disk"
---

# AI Paper Scraper Template

This template automatically applies settings when referenced.

用途:

{
  "url": "https://arxiv.org/abs/2401.12345",
  "vaultPath": "/path/to/vault",
  "templatePath": "templates/scraper-config"
}

缓存策略

// Memory cache (fast, ephemeral)
const cache = new MemoryCache({ maxSize: 100 });

// Disk cache (persistent across runs)
const cache = new PersistentCache({ cacheDir: './storage' });

// Apify KV store (cloud, for scheduled actors)
const cache = new PersistentScrapeCache('my-scrape-cache');

实时进度查看器

地方发展:

npm install  # Install dependencies
npm run dev  # Start MCP server with live viewer

Apify平台:

{
  "startResultsServer": true,
  "resultsServerPort": 8080
}

然后访问 http://localhost:8080 在您的浏览器中。


🤖 MCP服务器集成

Actor向Claude/LLM公开了5个工具:

# Install globally
npm install -g obsidian-mcp-actor

# Add to Claude config
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-actor",
      "args": ["mcp-server"]
    }
  }
}

可用工具:

  1. scrape_website -删除任何URL
  2. extract_tags -分析标签内容
  3. validate_content -检查刮擦质量
  4. convert_html_to_markdown -转换内容
  5. save_note -保存到黑曜石保险库

AI工作流示例:

“克劳德,从黑客新闻中抓取最新的5篇文章,按主题标记它们,并保存到我的 trending 带有内部链接的文件夹。"


🔧 开发设置

# Clone repository
git clone https://github.com/yourusername/obsidian-mcp-actor.git
cd obsidian-mcp-actor

# Install dependencies
npm install

# Run TypeScript compilation
npm run build

# Run tests
npm test

# Start MCP server locally
npm run mcp-server

项目结构

obsidian-mcp-actor/
├── src/
│   ├── main.js                      # Apify Actor entry point
│   ├── mcp-server.js               # MCP server entry point
│   └── lib/
│       ├── processor/              # Core business logic
│       │   ├── UnifiedScraper.js
│       │   ├── MarkdownConverter.js
│       │   ├── TagExtractor.js
│       │   └── ActorService.js
│       ├── scraper/                # Scraping strategies
│       │   ├── CheerioStrategy.js
│       │   └── PlaywrightStrategy.js
│       ├── vault/                  # Obsidian operations
│       │   ├── NoteManager.js
│       │   └── LinkManager.js
│       ├── cache/                  # Caching implementations
│       │   ├── MemoryCache.js
│       │   ├── PersistentCache.js
│       │   └── PersistentScrapeCache.js
│       ├── utils/                  # Utilities
│       │   ├── url.js
│       │   ├── errors.js
│       │   ├── retry.js
│       │   └── stealth.js
│       └── server/                 # WebSocket server
│           └── ResultsServer.js
├── test/                           # Unit and integration tests
├── input_schema.json               # Apify input schema
├── output_schema.json              # Apify output schema
└── package.json

🧪 测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test test/UnifiedScraper.test.js

测试覆盖目标:

  • 核心抓取逻辑:>90%
  • 安全验证:100%
  • 保险库操作:>85%

📦 部署

Apify平台

  1. 推到Apify:
apify push
  1. 配置环境变量:
APIFY_MEMORY_MBYTES=4096
APIFY_BUILD_TIMEOUT_SECS=300
  1. 计划运行:
apify schedule create my-schedule \
  --actor-id your-actor-id \
  --cron "0 9 * * *" \
  --input-json '{"urls": [...], "vaultPath": "/data"}'

自托管

# Docker
docker build -t obsidian-mcp-actor .
docker run -v /path/to/vault:/data -p 8080:8080 obsidian-mcp-actor

🔄 从v1.x迁移

突破性变化

对于大多数用户:无需更改。 公共API保持相同。

如果你扩展了内部:

  • 遗留功能 helpers.js 已弃用,但功能正常
  • 从特定模块导入新功能:
    // Old (still works)
    import { scrapeWebsite } from './helpers.js';
    
    // New (recommended)
    import { UnifiedScraper } from './lib/processor/UnifiedScraper.js';
    const scraper = new UnifiedScraper({ usePlaywright: true });
    

新缓存API

// Old
const cache = new ScrapeCache();

// New
const cache = new MemoryCache({ maxSize: 100, ttl: 3600000 });

更新的文件结构

从以下位置移动自定义代码 main.js 到 lib/processor/ActorService.js 为了模块化。


📚 用例

用例 配置
研究论文集 usePlaywright: false, cache: "disk", folderPath: "papers/{year}"
新闻监测 bulkMode: true, rateLimitDelay: 5000, updateExisting: true
竞争情报 enableStealth: true, downloadImages: true, autoTag: true
课程材料 templatePath: "templates/course", addMetadata: true, autoLink: true
人工智能驱动的策展 启用MCP服务器,使用Claude编排复杂的抓取任务

📊 性能基准

场景 v1.x v2.0 改进
单页静态 2.1s 0.8s 速度提高2.6倍
批量10个网址 45秒 18秒 速度提高2.5倍
JS重型SPA 15秒 12秒 速度提高1.25倍
图片下载(20) 25s 3s 快8.3倍
缓存命中率 0% 78% 78%重复使用

M1 Mac上的基准测试,10个并发工作者


🤝 贡献

我们欢迎捐款!请看 贡献.md 作为指导方针。

开发指南

  • 为新功能编写测试
  • 遵循现有的代码风格(ESLint配置)
  • 更新TypeScript类型
  • 使用JSDoc记录公共API
  • 安全第一:验证所有输入

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢


由以下材料制成❤️ 面向研究人员、知识工作者和自动化爱好者

将您的黑曜石金库转化为自我更新的知识库。