house-fetcher

name	house-fetcher
description	房产网站专用爬虫技能。使用 Firecrawl 或 Playwright 抓取房源信息并生成对比报告。Use when user mentions "抓取房源", "房产对比", "链家爬虫", "real estate scraping", or provides Cookie for automated scraping.
license	MIT
version	2.1.0
tags	["real-estate","web-scraping","property","housing","firecrawl","chinese-sites"]
metadata	{"author":"sean","created":"2026-04-09T00:00:00.000Z","updated":"2026-04-09T00:00:00.000Z","category":"tools","compatibility":"OpenClaw, Claude Code, any AI agent with exec capability"}
allowed-tools	["Bash(npm *)","Bash(node *)","Bash(curl *)","Bash(npx *)"]

House Fetcher - 房产网站爬虫

使用 Firecrawl 或无头浏览器（Playwright + Stealth Plugin）抓取房产网站房源信息，自动转换为 Markdown 格式并生成对比报告。

前置条件

• ✅ Node.js v18+ (推荐 v22)
• ✅ npm 包管理器
• ✅ Firecrawl API Key（免费额度可用）
• ✅ 链家/贝壳 Cookie（人机验证后）

主要特性

• ✅ Firecrawl 集成: 专业反爬虫，支持 JS 渲染页面
• ✅ Cookie 支持: 使用登录后的 Cookie 绕过验证
• ✅ 自动化工作流: 一键完成抓取→解析→对比
• ✅ 动态内容等待: 自动等待房源列表加载完成
• ✅ 结构化输出: 提取小区、户型、面积、价格、楼层等关键字段
• ✅ 对比工具: 自动生成房源对比报告和推荐

支持网站

网站	支持度	要求
链家 (lianjia.com)	⭐⭐⭐⭐⭐	Cookie（人机验证后）
贝壳 (ke.com)	⭐⭐⭐⭐	Cookie
安居客 (anjuke.com)	⭐⭐⭐	可选
房天下 (fang.com)	⭐⭐⭐	可选

快速开始

1. 安装依赖

cd scripts
npm install

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填入 Firecrawl API Key

3. 运行工作流

node workflow.js

流程:

1. 输入链家 Cookie（人机验证后）
2. 输入目标 URL
3. 自动抓取房源
4. 自动生成对比报告

环境变量配置

复制模板

cp .env.example .env

编辑 .env

# Firecrawl API Key（必填）
FIRECRAWL_API_KEY=fc-your-api-key-here

# 默认抓取 URL（可选）
DEFAULT_URL=https://sh.lianjia.com/ershoufang/pudong/

# 默认等待时间（毫秒）
DEFAULT_WAIT=5000

# 输出目录
OUTPUT_DIR=./output

获取 API Key

1. 访问 https://firecrawl.dev
2. 注册账户（有免费额度）
3. 获取 API Key
4. 填入 .env 文件

⚠️ 安全提醒:

• .env 文件包含敏感信息，不要提交到 git
• 已配置 .gitignore 自动忽略

使用方法

方法 1: 自动化工作流（推荐）

node workflow.js

交互式输入:

1. Cookie: 链家 Cookie（人机验证后）
2. URL: 目标 URL

输出:

• output/house1.md, output/house2.md... - 房源详情
• output/comparison.md - 对比报告

方法 2: Firecrawl 抓取（需要 Cookie）

node firecrawl-fetch.js "https://sh.lianjia.com/ershoufang/pudong/" \
  --cookie "你的 Cookie" \
  -o pudong-houses.md

方法 3: Playwright 抓取（简单网站）

node fetch.js "https://sh.lianjia.com/ershoufang/pudong/" \
  -o pudong-houses.md \
  --pages 3 \
  --wait 5000 \
  --type list

方法 4: 对比房源

# 对比 2 个房源
node compare.js house1.md house2.md

# 对比多个并排名
node compare.js house1.md house2.md house3.md \
  -o comparison.md \
  -r

# 自定义指标
node compare.js house1.md house2.md \
  --metrics price,area,unitPrice

测试安装

验证依赖

cd scripts
node --version  # 应该显示 v18+ 或 v22+
npm list --depth=0  # 查看已安装的依赖

测试 Firecrawl

# 测试 API Key 是否有效
node firecrawl-fetch.js "https://example.com" -o test.md
cat test.md  # 应该显示 example.com 内容

测试工作流

# 使用测试 Cookie（如果有）
node workflow.js

Cookie 获取方法

链家/贝壳需要 Cookie

步骤:

1. 打开浏览器 (Chrome/Edge)
2. 访问链家网站 (https://sh.lianjia.com)
3. 登录账户
4. 完成人机验证（如果有）
5. 按 F12 打开开发者工具
6. 进入 Application → Cookies
7. 复制所有 Cookie 值
8. 粘贴到工作流脚本

Cookie 格式

select_city=310000; lianjia_uuid=xxx; lianjia_token=xxx; security_ticket=xxx; ...

输出格式

房源详情 (house1.md)

# 小区名称 - 户型

**价格**: 850 万
**单价**: 9.5 万/㎡
**户型**: 89㎡ | 中楼层 | 南向
**装修**: 精装
**年代**: 2015
**地址**: 浦东新区 XXX 路
**链接**: https://...

对比报告 (comparison.md)

# 房源对比报告

**对比房源数**: 3 个

## 对比表格
| 房源 | 价格 | 面积 | 单价 | 楼层 | 朝向 |
|------|------|------|------|------|------|
| 小区 A | 850 万 | 89㎡ | 9.5 | 中楼层 | 南 |
| 小区 B | 1200 万 | 120㎡ | 10 | 高楼层 | 东南 |

## 推荐建议
### 🏆 首选推荐：小区 A
**综合评分**: 8.52 分

错误处理

错误	原因	解决方案
FIRECRAWL_API_KEY 未配置	.env 未配置	复制 .env.example 并填入
需要重新验证	Cookie 过期	重新登录获取 Cookie
人机验证	需要完成验证	浏览器完成验证后复制新 Cookie
Timeout	页面加载超时	增加 --wait 参数
node: command not found	Node.js 未安装	安装 Node.js v18+

最佳实践

1. 控制频率

# ✅ 好的做法
node fetch.js "<url>" --wait 5000 --pages 3

# ❌ 避免
node fetch.js "<url>" --wait 1000 --pages 10

2. 及时保存

node fetch.js "<url>" -o ./data/$(date +%Y%m%d-%H%M).md

3. 使用调试工具

node debug.js "<url>"

4. 遵守规则

• ✅ 仅供个人学习使用
• ✅ 低频抓取
• ✅ 遵守网站服务条款
• ❌ 不要商业用途
• ❌ 不要高频抓取

法律与免责声明

⚠️ 重要提醒:

1. 仅供个人学习使用 - 不要用于商业目的
2. 遵守服务条款 - 使用前阅读网站服务条款
3. 低频抓取 - 避免对网站造成压力
4. 数据准确性 - 抓取数据仅供参考，以实际为准
5. 法律责任 - 使用者自行承担法律责任

文件结构

house-fetcher/
├── SKILL.md                       # 主技能文件
├── README.md                      # 详细文档
├── .env                           # 环境变量（不提交）
├── .env.example                   # 环境变量模板
├── .gitignore                     # Git 忽略配置
├── scripts/
│   ├── fetch.js                   # Playwright 抓取
│   ├── firecrawl-fetch.js         # Firecrawl 抓取
│   ├── compare.js                 # 对比工具
│   ├── workflow.js                # 自动化工作流
│   ├── debug.js                   # 调试工具
│   └── package.json               # 依赖配置
└── references/
    ├── usage-guide.md             # 使用指南
    ├── compare-guide.md           # 对比指南
    └── workflow-guide.md          # 工作流指南

安全说明

API Key 保护

• ✅ API Key 存储在 .env 文件
• ✅ .env 已添加到 .gitignore
• ✅ 不要将 .env 提交到版本控制
• ✅ 不要公开分享 API Key

Cookie 安全

• ✅ Cookie 仅用于本次抓取
• ✅ 不存储 Cookie 到文件
• ✅ 使用后立即丢弃
• ⚠️ Cookie 过期时间较短，需定期更新

更新日志

v2.1.0 (2026-04-09)

改进:

• ✅ 精简 description
• ✅ 添加 allowed-tools 声明
• ✅ 优化 tags
• ✅ 添加前置条件
• ✅ 添加测试步骤
• ✅ 添加法律声明

v2.0.0 (2026-04-09)

• ✅ Firecrawl 集成
• ✅ 自动化工作流
• ✅ Cookie 支持
• ✅ 环境变量管理
• ✅ 对比工具

v1.0.0 (2026-04-09)

• ✅ 初始版本
• ✅ Playwright 抓取

常见问题

Q: 为什么抓取返回验证码？

A: 链家/贝壳有反爬虫保护，需要：

1. 在浏览器完成人机验证
2. 复制验证后的 Cookie
3. 使用 Firecrawl + Cookie 抓取

Q: Cookie 在哪里获取？

A: F12 → Application → Cookies → 复制所有值

Q: Firecrawl API Key 免费吗？

A: Firecrawl 有免费额度，超出后需付费。查看 https://firecrawl.dev 定价。

Q: 如何对比多个房源？

A: 使用 node compare.js house1.md house2.md house3.md -r

Q: Node.js 版本要求？

A: 需要 Node.js v18+，推荐 v22。使用 node --version 检查。

许可证

MIT License - 仅供个人学习使用

---

版本: 2.1.0
创建: 2026-04-09
更新: 2026-04-09
作者: sean