内容
lucifer-research
> 多平台内容提取引擎，适用于人工智能
[](https://github.com/kamisimokagura/lucifer-research/releases)
[](LICENSE)
[](https://www.typescriptlang.org/)
.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
从 12+ 个平台中提取结构化的 `Research 对象，通过分级回退链：**API → Jina Readability → Playwright）**。MCP 服务器** 为 Claude Code 和任何与 MCP 兼容智能工具使用 - 无 密钥即可启动。
选择 lucifer-research？
大多数提取工具要么 API 密钥，要 JS-heavy 网站上会返回非结构化的 HTML。lucifer-research 在有所不同：
1配置启动。**平台都有免费、无密钥的路径。仅为需要的平台添加2. **浏览器作为最后的回退。** Playwright 处理 JS-heavy 页面、单页应用和登录墙 使用现有的 Chrome 会3. **诚实的** 结果带有 `trust.score` 和 `trust.verified当我们回退到爬取时，我们会说明。
开始
### MCPClaude Code / Cursor / Windsurf）
```bash
git clone https://github.com/kokagura/lucearch
cd lucifer && npm ci && npm run build
```
```json
"mcpServers": {
"lucifer-research "command": "node",
"args": [/to/lucifer-research/packages/mcp/dist/index.js"]
}
}
}
```
想要访问 Chrome 会话？添加一行：
```json
"env": {
"CHROME_USER_DATA_DIR": "C:\\Users\\YourName\\AppData\\Local\\Google\\Chrome\\User Data"
}
```
### TypeScript 库
```ts
import { ResearchPipeline } from "@lucifer/core";
import { createDefaultRegistry } from "@lucifer/extractors";
const pipeline = new ResearchPipeline();
for (const [key, ext] of createDefaultRegistry()) pipeline.register(key, ext);
const result = await pipeline.extract("https://github.com/anthropics/claude-code");
console.log(result.title, result.platform, result.trust.score## 架构
```
用户（Claude / ）
|
v
[MCP] lucifer_extract / lucifer_pipeline
|
v
[ResearchPipeline]
|
v
[路由器] URL → 提取器选择
|
+-- [API 提取器] YouTube · GitHub · HackerNews · Bluesky · Qiita
| X/Twitter（4 级）· TikTok · Instagram
|
+-- [Jina Reader] JS-heavy 页面，可选清理提取
|
+-- [Readability] 本地提取，无外部调用
|
+-- [Browser Playwright — 略上下文：
CDP 桥话文件 → Chrome 配置文件 → 隔离
|
ResearchResult
· 标题 · 内容 · 平台参与度
· trust.score · trust.verified ·
```
## MCP 工具
| 工具 | |
| ---------------- --------------------------------------- |
| `` | 提取单个 URL |
| `_pipeline` | 并行提取最多 20 个 URL## 平台
| 平台 | 免费路径 |/额外设置 |
| ---------------------------------------------------------- | --------------------------------| YouTube | oEmbed + 转录； | `YOUTUBE_API_KEY` 获取观看赞/评论计数 |
| GitHub | 公共 次/小时 `GITHUB_TOKEN` — 5,000 次/小时 + 更高信任 |
| HackerNews | Alg共 API | —| Bluesky | AT 协议公共端点 |
| Qiita 公共 v2 | `QIITA_TOKEN更高速率限制 |
（Twitter） | → vxTwitter → Synd → oEmbed（4 级） | CDP 桥获取完整内容（见下文） |
| TikTok | oEmbed + BrowserExtractor 混合 | — |
| Instagram | GraphQL + OGP + BrowserExtractor 混合 | `INSTAGRAM_META_TOKEN` 获取 Meta oEmbed 级别 |
| Zenn / note 源 | — |
| Medium | Jina Reader | `JINA_API_KEY` 获取更高吞吐量 |
| Web（通用） | Readability → BrowserExtractor | Jina Reader器） |
###性说明
X、 Instagram 没有稳定的免费。提取器可能会通知的情况下中断 - 这的性质，而不是错误退时，` = false`代理可以区分结构和爬取内容。
Extractor
基于 Playwright退。使用现有的话，通过 **4层次结构** 重
| # | | 需要 |
|----------|
| 0 | CDP — 原始 WebSocket 会话，运行在 Chrome 上 | `CHROME_CDP_URL`（见下文） |
| 1 | 会话文件（从之前的策略 2/0 运行中自动保存） | 之前的成功提取 |
| 2 | Chrome 配置文件 | `CHROME_USER_DATA| 3隔离上下文（无 Cookie） | 始终可用作最后的### 策0：CDP（ / 登录墙站点）
当设置 `CHROME_URL` 时，lucifer-research 通过 `Target.createTarget` 打开一个新标签页，导航到目标 URL，提取内容，然后关闭标签页 - 不会触及您正在任何标签页。使用原始 CDP，完全wright 的页面管理需要 Node.js 21globalThis.WebSocket`）。
**标准 Chrome最简单的设置）：**
```bash
# Windows
"C:\Program Files\Google\Chrome\chrome.exe"-debugging-port2 --user-data-dir="%TEMP%\chrome-debug"
# mac/Applications/Google\ Chrome.app/Contents/MacOS Chrome --bugging-port=9222 --user-data-dir=/tmp/chrome-debug
```
```json
"env": {
"CHROME_CDP_URL": "http://127.0.0.1:9222"
}
```
> **为什么使用单独的 `--user-data-dir`？** 指向默认的 Chrome 配置文件，而 Chrome 已经运行时会导致锁定冲突。使用新的目录启动单独的干净实例。要使用已登录的会话，请传递实际的用户数据目录 - 但请先关闭 Chrome，或使用策略 2（`CHROME_USER_DATA_DIR`），它会自动处理配置文件复制。
**使用自定义 CDP 桥接代理：** 将 `CHROME_CDP_URL` 设置为桥接的 WebSocket URL，而不是直接的 Chrome 端点。无论哪种方式，都使用相同的原始 WebSocket 代码路径。
**关键环境变量：**
| 变量 | 效果 |
|-----|--------|
| `CHROME_USER_DATA_DIR` | Chrome 用户数据目录路径（策略 2） |
| `CHROME_CDP_URL` | CDP 桥接 WebSocket URL（策略 0） |
| `BROWSER_HEADED=1` | 在屏幕上显示浏览器窗口 |
| `BROWSER_KEEP_OPEN=<ms>` | 保持窗口打开 N 毫秒后提取（最大 60 秒，仅限头部） |
| `BROWSER_LEAVE_TAB_OPEN=1` | 保持提取的标签页打开以进行视觉检查（默认：提取后关闭） |
| `BROWSER_SAVE_CDP_SESSION=1` | 将 CDP 会话 Cookie 持久保存到磁盘（可选） |
## 配置
所有环境变量都是可选的。复制 `.env.example` 到 `.env`。
| 环境变量 | 使用者 | 效果 |
| ---------------------- | ----------------- | -------------------------------------------- |
| `YOUTUBE_API_KEY` | YouTube | 添加观看/点赞/评论计数 |
| `GITHUB_TOKEN` | GitHub | 5,000 次/小时（对比 60 次） |
| `JINA_API_KEY` | Jina Reader | 更高吞吐量 |
| `QIITA_TOKEN` | Qiita | 更高速率限制 |
| `INSTAGRAM_META_TOKEN` | Instagram | Meta oEmbed 级别 |
| `CHROME_USER_DATA_DIR` | BrowserExtractor | Chrome 配置文件路径 |
| `CHROME_CDP_URL` | BrowserExtractor | CDP 桥接 WebSocket URL（策略 0） |
## 信任级别
| 级别 | 含义 |
| ----- | ------- |
| `verified: true` | API 来源的数据，包含参与度计数 |
| `verified: false` | 爬取或浏览器提取的内容 |
| `conflicts` 设置 | API 元数据与浏览器内容不同 |
## 安全
4 层防御：
1. **DNS SSRF 保护** — 阻止 `127.x`、`10.x`、`172.16–31.x`、`192.168.x`、`169.254.x`、`100.64.0.0/10`（CGNAT）、IPv6 ULA/链路本地、DNS 绑定模式
2. **提示注入检测** — 当提取的内容包含覆盖模式时，标记 `trust`
3. **会话文件** — `~/.lucifer/sessions/` 在 `0700/0600`；基于域， 原子写入（pid+uuid 临时 → 重命名）
4. **CDP 验证** — 方案允许列表，URL 中无凭证，仅限环回（`127.0.0.0/8` + `::1`）；在任何连接之前验证 CDP 桥接端点
## 开发
```bash
npm ci
npm run build # turbo：所有软件包
npm run test # vitest + 集成测试
npm run lint # eslint
```
**集成脚本** （需要网络）：
```bash
node test-security.mjs # 72 个 SSRF + 注入模式
node test-urls.mjs # X + HackerNews + GitHub + Qiita
node test-urls-r2.mjs # 扩展平台覆盖
node test-urls-r3.mjs # Bluesky、TikTok、RSS（Zenn/Medium/note）
node test-stress.mjs # 并行 ×1/×5/
```
###
```
lucifer-research/
+-- packages/
-- core/ # ResearchPipeline、Router、SecurityGate、类型
| +-- extractors/ # 每个平台的提取器 + BrowserExtractor
| +-- mcp/ # MCP 服务器（lucifer_extract、lucifer_pipeline）
+-- turbo.json
```
## 更新日志
### v0.2.1（2026-05-20）
- **BrowserExtractor 策略 0：x.com 支持** — `CHROME_CDP_URL` 现在使用原始 WebSocket + `Target.createTarget` + `Target.attachToTarget` 启用从 x.com 和 twitter.com 提取，完全绕过 Playwright 的页面管理层（无法通过代理发现页面）。
- **`BROWSER_LEAVE_TAB_OPEN=1`** — 可选标志，用于保持提取的标签页打开以进行视觉检查。默认行为是在提取后关闭标签页，以便管道不会累积浏览器标签页。
- **安全** — 在任何连接之前对 `CHROME_CDP_URL` 进行环回验证；标签创建不会干扰现有的用户标签页；资源清理（`done()` 哨兵在所有出口路径上关闭待处理 CDP 命令）。
### v0.2.0（2026-05-14）
- **BrowserExtractor** — 基于 Playwright 的最终回退，具有 4 策略上下文层次结构
- **策略 0：CDP** — 通过 DevTools 协议（`CHROME_CDP_URL`）附加到正在运行的 Chrome
- **`BROWSER_HEADED=1`** / **`BROWSER_KEEP_OPEN=<ms>`** 环境变量
- **混合 SNS 提取** — X/Twitter、TikTok、Instagram 运行 API + 浏览器并行并合并结果
- **X/Twitter 4 级回退** — FxTwitter → vxTwitter → Syndication API → oEmbed（无身份验证）
- **YouTube** — 当转录为空时，oEmbed 描述回退；修复定时器泄漏
- **安全** — Codex 4 轮审查；SSRF CGNAT 范围；原子会话写入；CDP URL 验证
### v0.1.0（2026-04-15）
- 初始发布 — 12+ 平台，分级回退链，MCP 服务器，SSRF + 提示注入保护
## 许可证
[MIT](LICENSE) 2026 kamisimokagura
