贝壳找房小区研究工具 v2.2

I/O 契约（输入 / 输出 / 错误）

Agent 调用此 Skill 前必读，确保参数与返回结构符合预期。

模式 A：单小区深度研究

输入参数（环境变量 / 脚本参数）

参数	类型	默认值	说明
$1 (NAME)	string	必填	小区名（中文），用于 rs{小区名} 搜索
$2 (CITY)

string | sh | 城市前缀 |
| $3 (OUTDIR) | string | /tmp/beike | 输出目录 |
| BEIKE_HEADLESS | env | 0 | 设为 1 则 headless 模式，验证码时 exit 4 不挂起 |

成功输出（OUTDIR 下生成以下文件）

json
{
status: ok,
mode: single_xiaoqu,
xiaoqu_name: 东方花园三期,
xiaoqu_id: 5011102207315,
files: {
xiaoqujson: {OUTDIR}/东方花园三期xiaoqu.json,
ershoujson: {OUTDIR}/东方花园三期ershou.json,
chengjiaojson: {OUTDIR}/东方花园三期chengjiao.json
}
}

*_xiaoqu.json 字段 Schema：

json
{
avg_price: 78000,
building_type: 板楼,
total_units: 320户,
total_buildings: 8栋,
green_rate: 35%,
far: 1.8,
ownership: 商品房,
built_year: 2008-2012,
mgmt_fee: 2.5元/月/㎡,
mgmt_company: 绿城物业,
developer: 绿城集团,
followers: 125,
on_sale: 5,
sold_90d: 2,
views_30d: 38,
metros: [🚇9号线 七宝站 688m],
parsesource: css+innerText
}

模式 B：区域批量发现

输入参数

参数	类型	默认值	说明
$1 (BOARDS)	string	必填	逗号分隔板块，如 qibao,gumei
$2 (CITY)

string | sh | 城市前缀 |
| $3 (OUTDIR) | string | /tmp/beike_discover | 输出目录 |
| --district | flag | minhang | 区域路径段，如 pudong |
| --no-detail | flag | off | 仅发现，不抓详情 |
| --consensus | flag | off | 发现后接 PAL MCP 评估 |
| BEIKE_HEADLESS | env | 0 | headless 模式 |

成功输出

json
{
status: ok,
mode: region_discover,
city: sh,
district: minhang,
boards: [qibao, gumei],
total_candidates: 8,
candidates: [
{
name: 好世鹿鸣苑,
board: qibao,
price: 68000,
year: 2010-2012,
on_sale: 5,
sold_90d: 2,
metro: 1号线 莘庄站 688m,
xiaoqu_id: 5011000015858
}
],
csvfile: {OUTDIR}/candidates2026-03-23.csv
}

错误状态码

exit code	status 字符串	说明
0	ok	成功
1

dependency_missing | mcp-chrome 未启动 / 依赖缺失 | | 2 | captcha_detected | 验证码（交互模式，等待用户处理） | | 3 | parse_failed | 关键字段解析失败（贝壳结构变更） | | 4 | captcha_headless | headless 模式遇验证码，无法处理 |

---

两种工作模式

模式	触发场景	脚本
A. 单小区深度研究	查XX小区的信息、看东方花园三期	fetchxiaoqu.sh
B. 区域批量发现

找七宝/古美附近符合条件的小区、帮我发现候选小区 | regiondiscover.sh |

两种模式最终都可接 PAL MCP Consensus 评估（consensus_analyze.py）。

---

前置检查

1. mcp-chrome 连接

bash
curl -s http://127.0.0.1:12306/mcp -X POST \
-H Content-Type: application/json \
-H Accept: application/json, text/event-stream \
-d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:agent,version:1.0}}} \
| grep -o name:ChromeMcpServer && echo ✅ 已连接 || echo ❌ 请检查插件

获取 SESSION_ID（动态获取，不要写死）：

bash
SESSION_ID=$(curl -s -i -X POST http://127.0.0.1:12306/mcp \
-H Content-Type: application/json \
-H Accept: application/json, text/event-stream \
-d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:agent,version:1.0}}} \
| grep -i mcp-session-id: | awk {print $2} | tr -d \r\n )

2. PAL MCP 可用性（Consensus 模式需要）

bash
mcporter list pal 2>&1 | grep -q chat && echo ✅ PAL MCP 正常 || echo ❌ 请检查 ~/.mcporter/mcporter.json

---

贝壳 URL 规则

城市前缀：sh=上海 bj=北京 sz=深圳 gz=广州

区域列表（发现小区）

按板块： https://{city}.ke.com/xiaoqu/minhang/{板块拼音}/ 全区： https://{city}.ke.com/xiaoqu/{区拼音}/

常用上海板块

七宝=qibao 古美=gumei 金汇=jinhui 龙柏=longbai 莘庄=xinzhuang 漕河泾=caoheqing 虹桥=hongqiao

单小区操作

详情页： https://{city}.ke.com/xiaoqu/{小区ID}/ 在售： https://{city}.ke.com/ershoufang/rs{小区名}/ 成交： https://{city}.ke.com/chengjiao/rs{小区名}/

---

模式 A：单小区深度研究（四步）

Step 1 – 查小区 ID

bash
navigate → ershoufang/rs{小区名}/
wait 7s
JS: return Array.from(document.querySelectorAll(a))
.find(a => a.href.includes(/xiaoqu/) && /\/\d+\//.test(a.href))?.href ||

取 URL 中的数字部分即为小区 ID

Step 2 – 小区详情页

bash
navigate → xiaoqu/{小区ID}/
wait 7s
JS: return document.body.innerText
→ parse_beike.py xiaoqu

关键解析注意：

• - 贝壳使用 \xa0（非断行空格），正则需用 [\s\xa0]* 代替普通空格
• 字段格式：字段名\n值（换行分隔，非同行）
• 在售套数：格式为 N套\n在售二手房

Step 3 – 在售二手房

bash
navigate → ershoufang/rs{小区名}/
wait 7s
JS: return document.body.innerText
→ parse_beike.py ershou

Step