house-hunter

# house-hunter: 对话式找房 / 房产中介 skill > 面向 **年轻租客**（25-35 岁）的对话式找房工具。 > 核心维度：**配套（吃喝玩乐购）+ 租金 + 居住口碑 + 安全事件** > 不关注：房价走势、学区、投资分析（年轻租客不需要） > 底层：自建编排引擎 + 百度/高德地图 MCP + 复用 xiaohongshu-skills + 链家/贝壳 WebFetch + WebSearch --- ## 🔒 数据源约束（硬性，全局生效） > 这一节优先级**高于**所有其他设计决策。所有代码改动违反此约束需要在本文件先讨论。 ### 房产数据源优先级（D10 终版） ``` 1. ke.com (贝壳) ← 首选，所有 lianjia/ke 双 host 选择必须 ke 第一 2. lianjia.com (链家) ← fallback，同公司同数据但作 ke 失败时的备用入口 3. anjuke.com (安居客) ← 独立数据源，列表区准 4. ziroom.com (自如) 5. 58.com (58同城) 6. fang.com (房天下) ``` 具体落地点（必须遵守）： - `rental.community_basic_info`：先试 `sz.ke.com/xiaoqu/{id}/`，失败再试 `sz.lianjia.com/...` - `rental.community_rental_summary`：先试 `sz.ke.com/zufang/c{id}/`，失败再试 lianjia - `_resolve_via_keyword_search`：先试 ke 关键词搜，失败再试 lianjia - 报告链接：默认 ke.com，链接显示给用户的链接里也优先 ke 域 理由：用户决策 — 贝壳是首选品牌，链家是历史遗留入口。即使两者同公司同数据库，**呈现给用户和优先抓取顺序必须以贝壳为先**。 --- ## 🧰 Opus 调研操作手册（核心方法论，**必读**） > 你（接 /house-hunter 调用的 Opus）是真正的智能层。 > Python 引擎只做**重型批量任务**（候选生成、bridge 抓数据）； > **本节是你的方法论 SOP**，让你能复现高质量调研。 --- ### 🎯 7 类意图识别 SOP（第一步必做） 收到 `/house-hunter <input>` 后，**先识别意图**再决定流程： | 意图 | 触发词 | 处理流程 | |------|--------|---------| | **search** | "找房"/"附近"/"X 区 Y 平 Z 房"/"预算" | Python 引擎候选生成 + 7 步 enrich + rank 模板 | | **research** | "了解"/"调研"/"top N 小区" | 同 search，top_n 加大 | | **compare** | "vs"/"对比"/"PK"/"A 和 B 哪个好"（**含 2+ 具体小区名**）| **跳过候选生成** → 直接对每个名字跑 7 步 chain → compare 模板 | | **deepdive** | "为什么"/"深挖"/"X 栋"/"X 期"/"X 怎么样"（**单候选**） | 单候选 7 步 + 加栋号/楼层/朝向细化 → deepdive 模板 | | **reweight** | "如果短租"/"不考虑价格"/"如果开车"（**承接上文**）| **不重跑数据**，按新场景权重重排已有候选 → reweight 模板 | | **add_candidate** | "再加 X"/"还有 Y 也对比下"（**承接上文 PK**）| 增量对新候选跑 7 步，merge 进已有 PK | | **why_question** | "为什么 X 噪音"/"X 是什么意思" | 针对具体事实深度 WebSearch + 地图实测 | **关键判断**： - 用户给**具体小区名**（≥1 个）→ 不是 search/research，是 compare/deepdive - 用户**承接上文换条件** → 不重跑，是 reweight 或 add_candidate - **判断错就重跑浪费 5+ 分钟**，慎重选意图 --- ### 🔗 7 步多源 Chain SOP（每个候选必做） 不论什么意图，**对每个 community 调研时按这 7 步 chain**（并行可加速）： #### Step ① 百度地图 geocode + POI 配套 ```python from sources import baidu_map geo = baidu_map.geocode(f"{city}{name}", city) # 对每类 POI（短租租客视角）： for kw, rad in [('地铁站', 1500), ('购物中心', 2000), ('医院', 3000), ('公园', 1500), ('大道', 800)]: baidu_map.search_nearby(kw, geo.lat, geo.lng, rad, page_size=5) ``` → 拿到坐标 + 精确距离 + 周边主干道（噪音源） #### Step ② WebFetch 房产门户详情页（基础数据） - **优先**：`{city}.leyoujia.com/xq/detail/{id}` (乐有家，**字段最全**) - **备用**：fang.com / anjuke.com / 房天下 / 安居客 - **抓**：建成年份、户数、容积率、绿化率、物业公司、物业费、当前挂牌均价、在售房源数 #### Step ③ WebSearch 政府/官方投诉 ``` WebSearch("{小区} 物业 投诉 维权 业主") WebSearch("{城市} {区} 住建局 物业管理通报") ``` → 看黑猫投诉、住建局季度通报、广东省违法违规企业名单 → **官方红旗** #### Step ④ WebSearch 专家分析 ``` WebSearch("{小区} 优缺点 知乎") WebSearch("{小区} 哪栋好 不建议买") WebSearch("{小区} 入住 真实 体验 缺点") ``` → 深度评测、栋号优劣、朝向噪音 #### Step ⑤ WebSearch 市场信号 ``` WebSearch("{小区} 二手房 成交价 走势 2025 2026") WebSearch("{小区} 急售 / 跌价") ``` → 价格趋势、业主信心信号、跌幅 #### Step ⑥ xhs 多关键词搜（真实居住口碑） ```python from sources import xhs # 基础 for q in [name, f"{city} {name}", f"{name} 评价"]: xhs.search_feeds(q, max_results=15) # 风险词 for q in [f"{name} 避雷", f"{name} 噪音", f"{name} 漏水", f"{name} 物业 投诉"]: xhs.search_feeds(q, max_results=10) # 租房视角（短租） for q in [f"{name} 出租", f"{name} 入住"]: xhs.search_feeds(q, max_results=10) ``` **严格过滤**：笔记标题或正文必须含「城市名」或「区名」才算精确命中（避免同名小区混淆） #### Step ⑦ WebSearch 同名区分 / 维基百科 ``` WebSearch("{小区} 百度百科") ``` → **必查**：同名小区（如"南沙金茂湾" vs "灵山岛金茂湾"），不区分会出灾难性错误 --- ### 🚨 红旗 Checklist（合成报告前必扫） **出现任一信号时，报告里必须打 🚨 警示标记**： | 红旗 | 触发条件 | 严重度 | |------|---------|:-----:| | 业主急售信号集中 | xhs "急售/捡漏/X 折出/砸盘" 笔记 ≥ 3 条 | 🟠 中 | | **二手房跌价 > 30%** | 实际成交 vs 开盘 比 < 0.7（or xhs"跌到 X 万"信号）| 🔴 **高** | | **政府住建局通报** | 该小区/该物业在通报名单中 | 🔴 **高** | | 黑猫投诉集中 | 黑猫投诉记录 ≥ 2 条 | 🟠 中 | | 知乎/xhs 高互动负面 | ❤️ > 50 且明确负面 | 🟠 中 | | 装修质量集中吐槽 | 多条 "装修差/瑕疵/漏水" 笔记 ❤️ > 20 | 🟠 中 | | 同物业兄弟盘有通报 | 该物业管的其他盘出现在政府名单 | 🟡 低-中 | | **产权年限缩水** | 土地出让 vs 交楼 间隔 > 10 年（剩余年限 < 80%） | 🟠 中 | | **紧邻城中村** | 距离 < 200m（百度地图可查"村""社区"标注） | 🟡 低-中 | | **紧邻主干道/高架/铁路** | 距离 < 200m | 🟠 中（24/7 噪音） | | **环境污染信号** | xhs/知乎多次提"臭水""废气""异味" | 🟠 中 | | 开发商央/国企但兄弟盘维权 | 品牌污染（用户可能联想） | 🟡 低 | **报告规则**： - 高严重度（🔴）必须列在报告显眼位置 - 中严重度（🟠）放在「风险点」一节 - 低严重度（🟡）作为信息补充 --- ### ⚖️ 场景化评分权重表 根据用户表述场景，**用对应权重重新计算综合分**。不是固定 5 项 5 等分。 | 用户场景关键词 | 价格 | 通勤地铁 | 物业 | 配套 | 噪音 | 安全 | 户型 | 学校 | |--------------|:---:|:------:|:---:|:---:|:---:|:---:|:---:|:---:| | **默认**（长租自住） | 0.15 | 0.15 | 0.15 | 0.15 | 0.10 | 0.10 | 0.10 | 0.10 | | 短租 1 年 | 0.20 | 0.20 | 0.20 | 0.20 | 0.15 | 0.05 | 0 | 0 | | 短租 + 开车（无地铁需求） | 0.20 | 0 | 0.25 | 0.20 | 0.20 | 0.10 | 0.05 | 0 | | 短租 + 不考虑价格 | 0 | 0.15 | 0.25 | 0.25 | 0.20 | 0.10 | 0.05 | 0 | | **短租 + 不考虑价格 + 开车** | 0 | 0 | 0.30 | 0.25 | 0.25 | 0.15 | 0.05 | 0 | | 长租自住 + 通勤 | 0.15 | 0.25 | 0.20 | 0.15 | 0.10 | 0.10 | 0.05 | 0 | | 长租 + 有孩子 | 0.10 | 0.10 | 0.20 | 0.15 | 0.10 | 0.10 | 0.10 | **0.15** | | 投资 / 买入 | 0.20（升值潜力）| 0.15 | 0.10 | 0.15 | 0.05 | 0.05 | 0.10 | 0.20 | **自动调整规则**（当组合没匹配时）： - 用户说"**不考虑 X**" → X 权重置 0，余下按比例归一 - 用户说"**X 必备**" → X 权重 +0.10，其他比例缩减 - 用户说"**X 优先**" → X 权重 +0.05 - 用户切换约束时，**显式告诉用户用了什么权重**（透明化） --- ### 📋 4 套报告模板库 根据意图选模板： | 意图 | 模板 | 核心结构 | |------|------|---------| | search/research | **rank.md** | 你的需求 / Top N 评分表 / 各小区详情 / 数据来源 | | compare | **compare.md** | 基础数据对比表 / POI 实测 / 红旗扫描 / 综合 PK 表（按场景权重）/ 看房 checklist | | deepdive | **deepdive.md** | 基础 / 配套 / 红旗 / 业主真实声音 / 风险+应对 / 看房 checklist | | reweight | **reweight.md** | 权重变化说明 / 旧排序 vs 新排序 / 新排序理由 | #### compare.md 模板（A vs B / 多方 PK） ````text # 🥊 {城市}{area} {N} 方 PK — {date} [基础数据] 含建成/户数/容积率/物业/物业费/价格 的对比表 [配套实测] 百度地图距离对比：地铁/商场/医院/公园 [红旗扫描] 🚨 每个候选列红旗 [综合 PK] 显式列出用的场景权重 → 加权综合分表 [综合排序] 🥇/🥈/🥉 [看房 checklist] 必看 + 必问 [Sources] 每个事实附来源链接 ```` #### deepdive.md 模板（单候选深挖） ````text # 🔍 {小区} 深度调研 [基础数据] 房产门户直抓 [配套] 百度地图 [🚨 红旗扫描] [业主真实声音] xhs / 知乎 [风险点 + 应对] [看房 checklist] [Sources] ```` #### reweight.md 模板（场景变化重新排序） ````text # 🔄 重新加权 — 场景：{新约束} [权重变化说明] 旧权重 / 新权重 / 变化原因 表 [排序变化] # | 旧 | 新 | 变化原因 [新 Top 1-3 详细] 每个含新权重下分数 + 主要加分项 ```` #### rank.md 模板（沿用现有 search.md.j2，由 Python 渲染或 LLM 直接生成） --- ### 🔑 关键沟通原则 1. **每个事实附来源链接**（参考 xiaohongshu-skills 引用规范） 2. **安全/口碑措辞谨慎**："未查到" ≠ "没发生" 3. **不夸大单条事件代表性**（1 条负面笔记 ≠ 整个小区差） 4. **同名小区必区分**（百度百科 + 地址 + 开发商三重验证） 5. **权重透明**：合成报告时显式告诉用户用了什么场景权重 6. **承认不知道**：xhs 数据稀疏时明确说，不编 --- ### 📦 Python 工具 API 速查（Opus 直接调） ```python # 候选生成（按区或中心点） from sources.community_search import find_candidates candidates, source = find_candidates(city, district, area, limit, search_radius_m) # 多源详情 enrichment from house_hunter import _ensure_latlng, _enrich_community_basics _ensure_latlng(c) # 补 lat/lng + 元数据 _enrich_community_basics(c) # 强制刷新元数据 # 百度地图 POI from sources import baidu_map baidu_map.geocode(addr, city) baidu_map.search_nearby(kw, lat, lng, radius, page_size) # 桥接抓取（链家/贝壳） from sources import housing_bridge housing_bridge.fetch_html(url) # 24h 缓存 housing_bridge.fetch_via_bridge(url) # 不缓存 # 小红书 from sources import xhs xhs.search_feeds(keyword, max_results) ``` --- ## Step 0: 环境检查（必须先做）⚠️ 找到 skill 安装路径： ```bash for dir in \ "${CLAUDE_PLUGIN_ROOT:-}" \ "${OPENCLAW_SKILL_ROOT:-}" \ "${GEMINI_EXTENSION_DIR:-}" \ "$HOME/.claude/skills/house-hunter" \ "$HOME/.agents/skills/house-hunter" \ "$HOME/.codex/skills/house-hunter" \ "$HOME/.gemini/extensions/house-hunter" \ "$HOME/workspace/tools/house-hunter"; do [ -n "$dir" ] && [ -f "$dir/SKILL.md" ] && [ -d "$dir/scripts" ] && SKILL_ROOT="$dir" && break done echo "SKILL_ROOT=$SKILL_ROOT" ``` 运行健康检查： ```bash python3 "${SKILL_ROOT}/scripts/status.py" --json ``` **根据返回的 `fixes` 数组逐项修复：** | fix ID | 问题 | 你（LLM）的修复动作 | |--------|------|---------------------| | `install_python_deps` | pyyaml/jinja2 未安装 | 直接运行 `python3 "${SKILL_ROOT}/scripts/setup.py"` | | `configure_baidu_key` | 百度地图 Key 未配置（**必需**，fallback#1，5000/天） | **走下面的「Step 0.A：地图 Key 引导」流程** |