企业官网建设流程全解析

OpenCLI 贝壳找房（ke.com）浏览器适配器实战：二手房、租房、小区与成交记录一键 CLI 化

【免费下载链接】OpenCLIMake Any Website into CLI & Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI

本指南以 OpenCLI 仓库中的 ke 适配器文档 为骨架，深入讲解如何通过opencli ke系列命令，把贝壳找房（ke.com）的二手房、租房、小区与成交记录四个核心页面变成可脚本化、可管道的 CLI 数据源。你将掌握每个子命令的完整参数语义、URL 构造规则、输出字段含义，以及底层浏览器桥接、登录态复用与验证码风控的处理原理。

Ke 适配器概览：让贝壳找房成为 AI Agent 的确定性数据源

OpenCLI 的理念是"Make Any Website into CLI & Use your logged-in browser by AI agent"，而ke适配器正是这一理念在房产领域的落地。它属于Browser 模式（Mode: 🔐 Browser · Domain:ke.com），即命令本身不直接发 HTTP 请求，而是通过 Chrome 扩展与微守护进程，复用你浏览器中已登录的贝壳找房会话，在页面上下文中执行 DOM 解析脚本，把网页内容结构化为固定 schema 的输出。

从源码结构看，整个适配器由 clis/ke 目录下的 6 个文件组成：

所有子命令均通过cli()注册（见 ershoufang.js），声明了site: 'ke'、strategy: Strategy.COOKIE与browser: true，意味着它们依赖浏览器 Cookie 会话，属于浏览器型命令。

命令速览与典型使用场景

文档给出了四个子命令的能力概览：

这些命令的典型用途包括：房产调研（对比不同商圈挂牌价）、租房选房（按预算过滤）、小区估值（查看均价与在售量）、成交分析（跟踪成交价与成交周期）。由于输出是结构化表格/JSON，可以轻松接入jq、Excel 或 LLM 工作流进行二次分析。

环境准备：Browser Bridge 与登录态复用

在使用任何opencli ke命令之前，必须满足两个前置条件（见 ke 适配器文档 的 Prerequisites 一节）：

1. Chrome 正在运行且已登录ke.com——浏览器命令复用你 Chrome 中的登录会话，账号凭据不会离开浏览器；
2. 已安装 Browser Bridge 扩展——即 Browser Bridge 设置 中描述的轻量级 Chrome 扩展 + 微守护进程组合，零配置、自动启动。

安装扩展有两种方式：推荐从 Releases 页下载预构建的opencli-extension-v{version}.zip解压后在chrome://extensions开启开发者模式加载；开发者也可以直接加载仓库中的 extension 目录。安装后用opencli doctor一键验证扩展与守护进程连通性。

整个数据通路（见 Browser Bridge 文档 的 How It Works 一节）：

┌─────────────┐ WebSocket ┌──────────────┐ Chrome API ┌─────────┐ │ opencli │ ◄──────────────► │ micro-daemon │ ◄──────────────► │ Chrome │ │ (Node.js) │ localhost:19825 │ (auto-start) │ Extension │ Browser │ └─────────────┘ └──────────────┘ └─────────┘

守护进程在首次执行浏览器命令时自动拉起并常驻，可用opencli daemon stop优雅关闭。值得注意的是，ke适配器还额外提供了登录态强校验：auth.js会先检查https://www.ke.com域下是否存在lianjia_tokenCookie，再打开首页探测登录按钮与用户名锚点（.typeShowUser等），任一环节缺失都会抛出AuthRequiredError，提示你先在浏览器中完成登录。

核心参数解析：city 城市码与 district 区域 slug

文档的 Notes 部分明确了两条参数规则，这是正确使用ke命令的关键：

• city使用短城市码，如bj（北京）、sh（上海）、gz（广州）、sz（深圳）。从 utils.js 的cityUrl()可以看到，城市码直接拼进域名前缀：https://{city}.ke.com。注意租房命令比较特殊，它走的是独立的https://{city}.zu.ke.com子域（见 zufang.js）。源码中city的帮助文本还额外列出了zs（中山）等更多城市码可选值；
• district使用贝壳 URL 中的区域 slug（拼音），例如chaoyang、haidian、tianhe。它会被拼进路径段：二手房为/ershoufang/{district}/，租房为/zufang/{district}/，小区为/xiaoqu/{district}/，成交为/chengjiao/{district}/。

因此 URL 构造可总结为一张对照表：

二手房（ershoufang）：结构化字段解析与筛选参数

文档给出的示例命令：

# Beijing second-hand housing opencli ke ershoufang --city bj --district chaoyang --limit 10

从 ershoufang.js 看，该子命令支持以下参数：

价格与居室筛选会编码进 URL 路径段：价格形如p{min}t{max}，居室形如l{rooms}。例如--max-price 8000会生成/ershoufang/p t8000/这样的过滤器路径（min为空则只带上限），--rooms 3生成/ershoufang/l3/，组合时为p{t}l3/形式。

输出列定义为['title', 'community', 'layout', 'area', 'direction', 'total_price', 'unit_price', 'url']，含义为：标题、小区、户型、面积、朝向、总价（万元）、单价、详情链接。页面解析脚本在page.evaluate中执行，通过.sellListContent li.clear定位房源卡片，并对.houseInfo文本按|分段做正则提取——例如"中楼层 (共24层) 4室2厅 | 133.99平米 | 东南"会被拆出户型4室2厅、面积133.99平米、朝向东南，其中户型还做了兜底二次匹配，以兼容多种页面文案变体。总价从.totalPrice span取文本并统一追加万后缀，单价取自.unitPrice span。

租房（zufang）：月租预算过滤与结果规范化

文档示例：

# Rentals in Shanghai opencli ke zufang --city sh --district pudong --max-price 8000 --limit 10

租房子命令的参数（见 zufang.js）与二手房类似，但价格语义不同：--min-price/--max-price是最低/最高月租（元），且 URL 前缀为rp{min}t{max}，例如上述命令会构造出https://sh.zu.ke.com/zufang/pudong/rpt8000/。注意租房命令没有--rooms参数。

该命令在https://{city}.zu.ke.com子域下解析，输出列为['title', 'community', 'area', 'layout', 'price', 'url']（标题、小区、面积、户型、月租金、链接）。解析器以.content__list列表中的a.twoline标题链接为锚点向上回溯到卡片容器，再从<p>段落中提取小区名（取最后一个带title属性的链接）、面积（匹配㎡/平米）与户型（匹配室*厅），从<em>元素中提取纯数字租金并规范化为xx元/月。相对链接会被拼上baseUrl转为完整 URL。

小区（xiaoqu）：多选择器兼容的列表解析

文档示例：

# Communities in Guangzhou opencli ke xiaoqu --city gz --district tianhe --limit 10

小区命令的参数最简：--city、--district、--limit（默认 20），输出列['name', 'district', 'avg_price', 'year', 'on_sale']，对应小区名、区域、均价（元/平）、建成年代、在售量。

从 xiaoqu.js 可以看到一个值得借鉴的健壮性设计：解析器维护了一组按优先级降序的选择器列表（.xiaoquListItem→li.xiaoquListItem→.listContent li→ul.listContent li），逐个尝试直到命中非空集合，以兼容贝壳不同城市/版本的页面 DOM 差异。小区名优先取.title a文本，否则取a.img[title]的title属性；均价统一追加元/平后缀，无数据时输出暂无；建成年代通过(\d{4})年正则从信息文本中提取；在售量取自.xiaoquListItemSellCount a或.houseInfo a。

成交记录（chengjiao）：成交价、单价与成交日期

文档示例：

# Recent transactions in Beijing Haidian opencli ke chengjiao --city bj --district haidian --limit 10

成交记录命令同样只支持--city、--district、--limit，输出列['title', 'community', 'layout', 'area', 'deal_price', 'unit_price', 'deal_date']，即房源标题、小区、户型、面积、成交总价（万元）、成交单价、成交日期。部分页面还带成交周期元素.dealCycleTxt span（成交天数）可供扩展。

解析逻辑（见 chengjiao.js）同样采用多选择器回退策略（.listContent li→li.listContent li→.sellListContent li.clear→li.clear），标题取.title a, a.VIEWDATA，户型与面积从.houseInfo文本按|分段取第 1、2 段，成交总价追加万后缀，成交日期从.dealDate读取。

通用输出与管线化：把 ke 数据接入你的工作流

所有ke子命令（以及 OpenCLI 的全部内置命令）都支持统一的输出格式控制（参见 入门指南）：

opencli ke ershoufang --city bj --district chaoyang -f json # JSON，便于管道与 LLM opencli ke zufang --city sh --district pudong -f table # 终端富表格（默认） opencli ke chengjiao --city bj --district haidian -f csv # CSV opencli ke zufang --city sh --district pudong -f md # Markdown opencli ke xiaoqu --city gz --district tianhe -f yaml # YAML opencli ke ershoufang --city bj --district chaoyang -v # 输出管线调试信息

因此一条典型的调研链路可以是：opencli ke ershoufang --city bj --district haidian --max-price 600 --limit 20 -f json | jq '.[] | {title, total_price, unit_price}'，把贝壳数据直接喂给脚本或 AI Agent。由于命令是确定性的（同一命令、同一输出 schema），天然适合脚本化与 CI 集成。

源码级原理：登录态复用、风控检测与错误语义

要真正用好ke适配器，理解 utils.js 中的两个公共函数很有价值：

gotoKe(page, url)（见 utils.js）是每个子命令导航的统一入口：先page.goto(url, { settleMs: 2500 })等待页面稳定，再page.wait(2)，随后读取页面状态并做assertNotBlocked校验。它返回{ href, title, body_text }三元组，供上层判断。

assertNotBlocked(state)（见 utils.js）实现三层风控/登录检测：

1. URL 层：命中hip.ke.com/captcha或任意/captcha路径，判定为触发验证码；
2. 文本层：标题或正文包含请拖动下方滑块完成验证、请按住滑块、验证码、安全验证、访问验证、滑动验证等关键词（CAPTCHA_TEXT_PATTERNS），同样抛AuthRequiredError，提示"请先在浏览器中完成滑块验证"；
3. 登录层：标题包含请登录、账号登录、手机登录、扫码登录等关键词，抛AuthRequiredError，提示先登录贝壳找房。

这套检测机制把"验证码/未登录"这类可恢复的用户操作错误（AuthRequiredError）与"网络/解析失败"这类命令执行错误（CommandExecutionError）明确区分开，AI Agent 可以根据错误类型决定下一步动作（例如提示用户去浏览器完成滑块验证后重试）。此外，fetchKeJson()（见 utils.js）展示了在浏览器上下文内带 Cookie 请求贝壳 JSON API 的通用模式，credentials: 'include'保证登录态随请求携带，401/403 会被识别为登录过期。

小结

opencli ke系列通过 Browser Bridge 复用 Chrome 登录态，将贝壳找房的二手房、租房、小区、成交记录四个高频页面封装为带筛选参数、结构化输出、风控感知的确定性 CLI 命令。其核心要点可归纳为：

• 城市用短码（bj/sh/gz/sz等）拼入域名前缀，区域用贝壳 URL slug 拼入路径段，租房走独立zu.ke.com子域；
• 二手房/租房支持价格与居室筛选，筛选条件编码为 URL 路径过滤器（p{min}t{max}、rp{min}t{max}、l{rooms}）；
• 各子命令输出固定列 schema，支持-f json/yaml/csv/md/table，可直接管道接入jq、Excel 或 LLM；
• 底层通过gotoKe+assertNotBlocked统一处理导航、验证码与登录态检测，将风控问题以AuthRequiredError暴露给上层编排。

如需进一步了解 Browser Bridge 的完整安装与 Tab 生命周期管理，可继续阅读 Browser Bridge 设置 与 入门指南；若要在远程服务器上运行opencli而浏览器留在本地，可参考 远程编排指南。

【免费下载链接】OpenCLIMake Any Website into CLI & Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI