澜房ERP

概述

本文件＝常驻主文档（每次会话都读）。下列细则按需读取，不要整目录读：

· references/01-首次配置.md —— 仅当生效凭证不完整（取数报「缺少 base_url/AppKey」或 --check 显示未配置）、或要换账号·换城市·排查连通失败时读

· references/02-能力菜单.md —— 仅 T1 首次配置秘钥成功后（安装成功）的引导菜单、或用户问「能做什么 / 怎么用」时读

· references/11-清单与候选组件.md —— A 查房找房 / B 客源匹配

· references/12-报告与用途分档.md —— C 价格诊断 / F 分析报告

· references/16-推荐报告地图卡.md —— A/B 清单勾选后的客户推荐报告（地图卡规格，随 11 一起读）

· references/13-片区研究.md —— D　· references/14-新人踩盘.md —— G

· references/15-通用规格.md —— 落款 / 禁例 / 定位 / 配套（落盘前必读，全能力通用）

· references/31-典型任务配方.md —— E 谈单复盘 / H 经营体检 / 各类速查配方

· references/*.html —— 落盘蓝本（候选组件 / 能力菜单组件 menu-widget.html / 各类报告模板）

· references/17-清单数据契约.md —— 跑 scripts/build_list.py 备 list_data.json 前读（JSON 字段契约）

· references/18-推荐报告数据契约.md —— 跑 scripts/build_pick.py 备 pick_data.json 前读（JSON 字段契约）

· 房源清单不用照抄模板：备好 list_data.json 后跑 scripts/build_list.py（数据契约＝references/17-清单数据契约.md），脚本自动剥离注释并做产物自检

· 客户推荐报告同样不用照抄模板：备好 pick_data.json 后跑 scripts/build_pick.py（数据契约＝references/18-推荐报告数据契约.md；地图卡口径＝references/16-推荐报告地图卡.md），脚本自动渲染多小区配套地图卡 + 10 项红线自检，自检不过不落盘

⛔ 第 0 步：配置门禁（凭证没打通 → 立刻停，不产出任何东西）

这条排在能力路由之前，是所有能力的前置条件。 下列任一情形出现，立即停止全部取数与产出——不查数、不分析、不落盘、不出清单 / 报告 / 文案；⛔ 不得拿上一次的结果、记忆里的数据或估算值凑一份交差。本轮只做一件事：告知客户去完成密钥配置。

怎么判「有没有配置密钥」——⛔ 别拿 config.json 这个文件当判据

凭证有三个来源，优先级 环境变量 > config.json > 默认空（FANGYUAN_BASE_URL / FANGYUAN_CITY / FANGYUAN_APP_KEY / FANGYUAN_APP_SECRET；FANGYUAN_CONFIG 还能把配置文件整个换成另一份）。三处取数入口（MCP server / fangyuan_cli.py / HTTP server）都遵循这个优先级。⇒ 「config.json 里是空的」≠「没配置密钥」——凭证可能放在环境变量或 MCP 客户端的 env 段里。判据只有一个：当前生效的凭证是否完整，按下面的运行时信号判，⛔ 不要读文件下结论：

唯一例外：400 请求已过期 是机器时间问题、不是密钥问题，按「常见报错」表处理后重试 —— 但同样要停下，链路没通就不产出。

停下时的三段话（⛔ 不要多写、不要追问别的） —— 第 1 句按命中的情形选，⛔ 三种情形别用同一句：

⛔ ②③ 不要说「请先完成密钥配置」 —— 客户已经配过了，那样说会让他以为要重填、甚至怀疑自己填错。②只提「核对密钥」，③完全不提密钥（那是服务端的事）。

第 2 段 · 配置回填模板 —— 只有 ①② 给（4 项等号后补全、整段一次性回发；完整流程见 references/01-首次配置.md）：

【数据源接入信息】（请补全等号后内容，一次性回发）
服务地址 =（由服务方提供，形如 https://你的租户域名，必填）
城市 =（当前主要作业城市；建议填写，不清楚可留空）
AppKey =（由服务方提供，必填）
AppSecret =（由服务方提供，必填）

③ 情形 ⛔ 不给这段模板 —— 配置本身没问题，发了会让客户白重配一遍。② 情形加一句「请核对后把正确的一组按同样格式回发」。

第 3 段 · 恢复路径（三种情形共用）：① 客户回填 / ② 客户核对更正 / ③ 服务恢复后，AI 用 scripts/setup_config.py 写入 → --check --test 自检通过 → 立即补做刚才被中断的那件事（客户不必重说一遍需求）。③ 情形若无需改配置，服务恢复后直接补做即可。

⛔ 此时不给能力菜单 —— 菜单是「配置成功」后的动作（T1），链路没通时给了也点不动、只会误导。⛔ 也不追问「要不要先做点别的」，只等配置。⛔ 不得把「接口失败」误判成「这小区没房源」：真·空结果是 ok: true 且列表为空；ok: false 一律按下表停下。

🧭 拿到指令，第一步永远是「能力路由」

先判命中八项能力中的哪一项，再读文件。 命中后只读该行的必读文件，⛔ 不要把 references/ 整目录读一遍；未命中八项时才走通用流程，并明确说明「未命中预设能力」——⛔ 不得硬套一个错的能力。

参数门禁：编号 / 小区名 / 门店名 / 录音这类必须用户自己给的参数，缺了就只问那一句（一次只问最关键的一个），此轮不执行；能枚举的参数（出售·出租、几室、预算档、用途档）用点选卡问，每题 ≤4 项。⛔ 问编号时不给任何格式示例（前缀与位数各租户不同），用户给的编号原样照抄。完整门禁表见 02-能力菜单.md。术语纪律：对用户一律说「房源编号」「客源编号」，⛔ 不得说 uuid 或其它技术字段名。

⛔ 三步门禁（命中 A / B 出清单才用；每次必做、无例外）

1. 取数完成 → 清单落盘之前：单独弹一题「清单底部要留联系方式吗？」（A 留姓名电话 / B 只留电话 / C 不留）。
2. 清单落盘后、同一条消息里：调出「候选房源多选组件」——套 references/candidate-picker.html 蓝本，只换 R 数组，样式一个字不改；20 套一次列全、可多选、含「联系人姓名」「联系电话」两个输入框。
3. 这条消息的排布顺序：① 一句话说明（查到几套、按什么排序）→ ② 清单文件卡片 → ③ 组件压轴，组件之后不再接任何文字。

⛔ 绝不允许：只给文件就说「已完成」；先问「要不要出推荐报告」——组件本身就是这一问（勾选发送＝要报告；不勾＝只要清单）。⛔ 这一问每次出清单都必须给、无例外——不因「上次问过 / 上次说不用 / 这次指令没提 / 刚问过 PDF」而跳过；只有用户本轮已把话说死（明确要或明确不要）才免问。默认排序口径：四项综合打分（价格 40% / 热度 40% / 跟进 20%）降序取前 20 套；只有用户点名单一维度时才改。

命中「查房子」一律直接走 A，不反问

用户话里出现「找房 / 查房 / 看看有没有合适的房 / 有没有 XX 户型 / 有没有便宜点的 / 推几套给我」这类指向房源的动作 → 直接按 A 走完整链路，⛔ 不反问「你想做什么」、⛔ 不二次确认参数（用途已由动作本身说明）。只有用户明确说了别的用途才改道（单套详情 → F、片区报告 → D、议价单 → F、客源画像 → B 客源侧）。判断依据是用户明确说了别的用途，而不是「顺便也给个清单」。

⛔ PDF 一问的时机（适用于全部能力、全部交付物）

「要不要再出一份 PDF 版？」只能在：交付物已生成完毕 → 已交付并展示给用户 → 用户已经能看到成品内容 之后 才问。

下列时机一律禁止问 PDF：用户刚说完需求、还没取数；交付物正在生成中；已落盘但还没交付展示；与任何前置问题合并在同一条消息里问（用途分档、参数复核、勾选房源、落款一问、推荐报告那一问……都不许捎带问 PDF）。

唯一免问情形：用户本轮指令里已点名要 PDF → 直接连 PDF 一并产出；用户已答过 → 不重复问。PDF 做法：读 references/pdf-notes.md，按那五个坑产出同名 PDF。

交互硬规则（PC 与手机同一套）

必须点选（AskUserQuestion）：用途分档（A 客户版 / B 业主版 / C 内部版）、「要不要 PDF」、「要不要出成文件带走」。全部单选（调用时显式设单项选择，⛔ 严禁设多选），每题 ≤ 4 个选项；⛔ 不得用纯文本「请回复序号」替代点选。

两个例外（⛔ 别扩散到别处）：

• 能力引导菜单（8 项）不点选 —— 改为窗口内排整齐的能力菜单 + 每条指令带真「复制」按钮（首选内联组件，手机端客户端不给代码块挂复制按钮）。蓝本＝references/menu-widget.html（整段套用、只照抄内容不改样式）；⛔ 首次配置秘钥成功 / 用户问能力时，菜单必须压轴放在回复最底部、其后不再接文字（窗口底部才好点）。详见 02-能力菜单.md。
• 勾选房源 / 要不要客户推荐报告不点选 —— 改由候选房源多选组件承载（一题 ≤4 项装不下 20 套，用户已明确否定）。见 11-清单与候选组件.md。

兜底：客户端弹不出点选卡（用户反馈「没有选项」）→ 二选一的确认改用一句话文本问（「要不要生成推荐报告？要 / 不要」），⛔ 不要让用户手输序号或数字；客户端渲染不出组件 → 退化为窗口文本清单（序号 + 小区 + 面积/总价 + 房源编号，一次列全、不得分批），并说明「回一句『第 3、7、12 套』＋你的姓名电话即可」——这是唯一允许让用户回序号的情形。

用途分档等收尾确认走点选；能力菜单与房源勾选不走点选 —— 两者别搞混。

姓名电话：⛔ 不单独问一次——由候选组件的两个输入框承载（选填；留空则报告结尾写「有意向可直接回复我」）；用户若在对话里主动给了称呼 / 号码，原样照抄（不改位数、不加区号、不校验格式），⛔ 不得写进技能目录的任何文件。

⛔ 依赖检查与降级路由（每次开工前先跑）

本技能是依赖型技能（ERP 接口 + MCP + Python 运行时 + 图表 CDN）。开工前先跑一次环境检查，按返回状态走，不要跳过：

python3 scripts/probe_dependencies.py --out probe-results.json    # 最小只读探测，输出脱敏结果
python3 scripts/check_environment.py --probe-results probe-results.json

降级的硬规则：

• 一个依赖不可用只关闭受影响的功能，⛔ 不笼统宣布整个技能不可用；
• 降级路径与停止条件以 skill-dependencies.json 为准（每项功能逐条写明 fallback / limitations / recovery / stop_condition）；
• 核心数据或正确性无法保障时停止该功能 —— ⛔ 不用模型记忆、估算或模板示例数据顶替真实结果；
• 探测结果不含任何凭据值，⛔ 不要在对话里回显 AppKey / AppSecret / 租户服务地址；
• 首次配置与故障处置见 references/setup-guide.md（⛔ 凭证齐全时不要读它）。

服务概述

fangyuan-api MCP 提供 3 个工具，对接澜房ERP官方对外接口（凭证与接口域名的来源与优先级见上文「第 0 步：配置门禁」）：

最新接口能力：房源支持按门店筛选（store_org_name）并返回所属门店（sale_store_org/lease_store_org）与封面图（cover_image）；客源返回维护人及部门（agent_id/agent_name/org_id/org_name），可按维护人/门店维度筛选与统计。

工具参数速查

search_sources

⛔ 分页口径（2026-11-02 实测，旧的「不分页/50 条上限」已作废）：

• 接口已支持分页：page_size 实测 10→10 条、200→200 条、1000→1000 条、5000→5000 条（无硬上限）；page=1 与 page=2 的 uuid 集合交集 0；连续翻 12 页零重复；加 order=uuid 后同样零重复。
• 响应不含总数、也不含任何分页元数据（只有 data 数组）→ ⛔ 拿不到「一共有多少套」。要全量仍须翻页直到返回空 + 按 uuid 去重。
• 旧做法「按 room / area 分段多次查询」现在不是必需，但分段仍是最省请求的做法（一次 page_size=5000 与分段取全效果相同、请求更少）。
• 翻页建议带显式 order（如 uuid）——实测默认排序也稳定，但显式排序可避免并发写入导致的页漂移。

⛔ 状态筛选的默认规则（2026-11-02 官方新增，踩过）：

• sale_status 与 lease_status 都没传时 → 只查系统默认有效状态的房源。
• 传了任一状态条件 → 不再附加默认总状态筛选，即能查到暂缓 / 无效盘。
• 两者同时传 → 出售与出租状态条件同时满足（AND）。
• 实测证据（uuid 集合比对）：不传状态基线 200 套；传「我售 / 他售 / 无效」与基线交集 0；传「暂缓」交集 65；传「流通」交集 117 —— 参数确实生效，不是被忽略。

查"某天/最新新录入"的房源：接口无日期筛选参数 → 用 order="created_at"（降序）取回最新一批，

再在本地按 statistics_info.created_at[:10] 过滤目标日期即可。

search_clients

按维护人查客源（均走 extra_filters，接口原生支持）：{"agent_name":"张三"} 维护人姓名、{"org_name":"xx门店"} 维护人部门（门店）名称、{"name":"李四"} 客户姓名。

get_trace_info

search_bargains（已审核合同 · 2026-11-02 新增）

• 两项均未传、或楼盘名未匹配到楼盘 → 返回空 data（不报错）。
• 只返回近五个月内已审核的合同（实测最早一条距今正好 150 天），按审核日期倒序，最多 100 条，不分页。

get_source_videos（房源视频 · 2026-11-02 新增）

• 只返回该房源状态为「有效」的视频记录，按视频记录 ID 倒序。

返回数据字段地图

每条房源记录的 JSON 结构：

uuid                          房源唯一编号
basic_info.community_title    小区名
basic_info.district_name      行政区（注意以ERP为准，勿凭常识推断）
basic_info.business_name      商圈名
house_info.room / hall        室 / 厅
house_info.arch_square        面积(㎡)
house_info.decoration_level   装修（毛坯/简装/精装/豪装）
house_info.community_type     物业类型（住宅/商铺/车位/公寓）
house_info.delivery_at        交付年份
house_info.arch_type          塔楼/板楼等
house_info.direction          朝向
house_info.cover_image        房源封面图URL（输出图文内容可直接引用）
sale_info.high_price          挂牌总价（单位：万元）
sale_info.sale_unit_price     挂牌单价（元/㎡）
sale_info.sale_store_org      出售委托门店 {"id":门店ID, "name":门店名称}
sale_info.open_at            出售挂牌（开盘）时间 ← 出售房源的「挂牌日期」取它
lease_info.lease_price        租金（元/月）
lease_info.lease_store_org    出租委托门店 {"id":门店ID, "name":门店名称}
lease_info.lease_open_at      出租挂牌（开盘）时间 ← 出租房源的「挂牌日期」取它
statistics_info.current_source_status  状态（在售/空置/在租/自住等）
statistics_info.created_at    录入时间（**⛔ 不等于挂牌时间**，见下文「挂牌时间口径」；查"新增房源"用它，格式 2026-09-22 09:51:23）
statistics_info.click_num     浏览次数（录入起累计）
statistics_info.seen_num      带看次数（录入起累计）
statistics_info.share_num     分享次数（录入起累计）
statistics_info.followed_at   最后跟进时间（热度排序用）
statistics_info.last_opened_at 最新开盘时间
statistics_info.come_from     房源来源（如 项目推荐）
statistics_info.tags          标签数组（实测见过 地铁房 / 学区房 / 采光好 / 视野好 / 急切）
statistics_info.supporting    屋内软件设施数组（床 / 衣柜 / 空调 / 热水器 / 冰箱 / 洗衣机 / 宽带 / 灶具 / 电视 / 书桌…）
house_info.heating_supply     暖气（集中热力 / 集中供暖 / 壁挂炉 / 自采暖）
house_info.gas_supply         燃气（管道天然气 / 无）
house_info.elevator           电梯（true / false / "-"）
house_info.ownership_year      产权年（**是产权登记年，不是建成年**）
house_info.ownership_type      产权性质（商品房 / 房改房 …）
house_info.ownership_date      产权登记日期
house_info.delivery_at         交付年份
house_info.toilet / kitchen / balcony  卫生间 / 厨房 / 阳台数
house_info.floor_name_num      楼层（形如 1/15）
sale_info.sale_circulation_at  出售最后一次转流通时间（**当前出售状态为「流通」时才有值，否则 `-`**）
lease_info.lease_circulation_at 出租最后一次转流通时间（同上）
statistics_info.has_key        是否持钥匙（钥匙记录存在且**未归还**才为 true）
statistics_info.key_date       钥匙记录创建日期（Y-m-d，无记录为 `-`）
statistics_info.has_survey     是否存在实勘记录（布尔）
statistics_info.survey_date    实勘记录创建日期（Y-m-d，无记录为 `-`）

⛔ 新字段在嵌套层，不在顶层（2026-11-02 实测）：has_key / key_date / has_survey / survey_date 在 statistics_info；sale_circulation_at 在 sale_info、lease_circulation_at 在 lease_info。取字段必须按完整路径找（如 row["statistics_info"]["has_key"]），⛔ 只看顶层 key 会误判「字段不存在」。

注意：浏览/带看/分享三项均为录入起累计值（2026-10-12 实测天津环境证实：新录房源 click_num 从个位数起累加、接口无"近30天"字段），不是近30天滚动；对外文案、清单列头、报告口径一律写「累计」，禁止写「近 30 天」。

配套字段（2026-10-15 实测，重庆环境）：① 屋内硬件＝heating_supply + gas_supply + elevator，覆盖率接近 100%（实测「集中热力 35 / 集中供暖 8 / 壁挂炉 6」「管道天然气 49」「有电梯 41」）；② 屋内软件＝statistics_info.supporting，覆盖率偏低（实测 50 套里约 13 套有值），取值如 床 / 空调 / 衣柜 / 冰箱 / 书桌 / 电视 / 洗衣机——取不到一律写「未登记」，⛔ 不得写成「无」或自行补全；③ tags 里的「地铁房 / 学区房」是周边配套的系统内线索，可作检索与排序提示，但对客户输出前必须用外部平台复核并注明来源，⛔ 不得仅凭标签下结论。

周边配套与小区配套系统内无字段（接口仅开放房源 / 客源 / 跟进三个），小区级信息（容积率 / 绿化率 / 车位配比 / 健身场所 / 物业费）与周边配套（地铁 / 公交 / 医院 / 学校 / 商场菜场公园）一律来自外部公开平台，注明平台与抓取月份；多源冲突（容积率、物业费最易冲突）并列两个口径并注明取值依据。

房源归属门店：出售看 sale_info.sale_store_org，出租看 lease_info.lease_store_org；租售房源两处都可能返回。

挂牌时间口径（2026-10-15 用户定稿，⛔ 别再取错字段）：

• 挂牌（开盘）时间＝sale_info.open_at（出售）/ lease_info.lease_open_at（出租）；statistics_info.last_opened_at 是最近一次开盘时间。两者不可混用——实测出租批次 lease_open_at 覆盖 100/100 而 open_at 只有 4/100；出售批次则相反。
• ⛔ 录入时间 ≠ 挂牌时间。 statistics_info.created_at 只是信息录入系统的时间。房源可能是仅核盘（资料盘）——业主自住或空置、并未挂牌，录入只是为了留给经纪人回访；发现租售意向后才重新开盘，此时起才产生挂牌时间。两者可能差很远，⛔ 不得拿 created_at 冒充挂牌时间。
• 对应字段为空 ⇒ 该房源尚未开盘（资料盘 / 核盘盘）：挂牌日期栏写「未开盘 · 资料盘」、时长栏写「—」，⛔ 不得填录入日期、也不得按录入日期编时长。可用 statistics_info.current_source_status（在售 / 空置 / 在租 / 自住）佐证状态。
• 兜底只往下一级：open_at / lease_open_at 为空 → 看 last_opened_at；它也为空就是未开盘。兜底命中时在口径里注明用了哪一级。
• last_opened_at 会随调价重推刷新——算「已挂 X 个月」时优先用 open_at / lease_open_at，⛔ 不要拿 last_opened_at 算时长，否则重推过的房源时长会被刷成 0。
• 只有「判断是否新录集中」才看 created_at，与挂牌时间口径无关。

search_clients 返回关键字段

uuid           客源唯一编码
type           求购 / 求租
name           客户姓名
stage / level  客源阶段（首看…）/ 客源等级（A–E）
community_type 客户要的物业类型（住宅 / 车位 / 商铺）→ 配盘时按它过滤
status         状态（流通 / …）
district / business  需求区域 / 需求商圈（未填时值为 `-`）
org_id / org_name    维护人部门id / 部门（门店）名称
agent_id / agent_name  维护人id / 维护人姓名
price          预算区间字符串：求购 `70-90万`、求租 `1000-1500元`（**求购求租同一字段，无 rent_price**）
room / hall / toilet / floor  期望室/厅/卫/楼层**区间字符串**（`3-3`、`2-3`、`1`；未填 `-`）
area           期望面积**区间字符串**（`80-100m²`、`88-88m²`；未填 `-`）
latest_trace_dec     最近一次跟进描述（内部用，不进交付物）
last_follow_time / last_follow_time_zh  最后跟进时间 / 含「1天」人读版
click_num / dk_count / see_house_times  客源点击次数 / 带看次数 / 看房次数
created_at           客源录入时间
> ⚠️ 需求类字段（room / hall / toilet / floor / area / price / district / business）都是**区间字符串**、**空值写作 `-`**（2026-10-14 重庆环境实测），解析时按下界 / 上界拆开、剥单位，别当数字直接读。

search_bargains 返回字段（已审核合同 · 2026-11-02 新增）

sign_time      合同**审核**日期（官方字段 fixtured_at），格式 Y-m-d  ⛔ 不是"签订日"
bargain_type   合同类型：**买卖 / 租赁 / 其他**  ← ✅ 判定租售就读这个字段
price          合同价格（单位随 bargain_type 变，见下方口径）
source_area    合同房源面积（㎡）
room / hall    室 / 厅
toilet / kitchen / balcony  卫生间 / 厨房 / 阳台

✅ 合同类型判定（2026-11-04 官方上线 bargain_type，已实测确认）

• bargain_type 就是「交易类型」字段，取值 买卖 / 租赁 / 其他。判定租售一律读它，⛔ 不要再靠 price 量级猜。
• 实测证据（新居里 12 条）：买卖 2 条 → price 1,717,000 / 1,468,000（总价，元）；租赁 10 条 → price 2,200–3,300（月租，元/月）。类型与量级完全对应。
• price 的单位随类型走：买卖 → 售价总价（元）；租赁 → 月租（元/月）；其他 → 无固定口径，⛔ 不要自行换算或标注为总价，直接写「价格口径待确认」。
• 引用成交价时必须同时写出类型（写「成交总价 171.7 万」或「成交月租 2,400 元/月」），⛔ 不能只写数字。
• 兜底（接口偶发不返该字段时）：price < 10000 视为月租、>= 100000 视为售价总价，中间地带不判。

✅ 已解决：租售判定改用 bargain_type（2026-11-04 官方上线）

• 11-02 的坑已闭环 —— 当时接口不标租售，只能靠 price 量级猜；现在官方补了 bargain_type（买卖 / 租赁 / 其他），直接读它。
• 量级法降级为兜底（仅当该字段缺失时用）：< 10000 ＝ 月租、>= 100000 ＝ 售价总价，中间地带不判。
• 仍要遵守的三条：① 引用成交价必须同时标注类型；② 其他 类型的 price 无固定口径，写「价格口径待确认」；③ 买卖类可自校验（总价 ÷ 面积 应与同小区在库售价单价同量级：实测 171.7 万 ÷ 88.39㎡ = 19,425 元/㎡ vs 在库 22,424 元/㎡）。

另外三条口径：

• sign_time 是审核日（fixtured_at），不是签订日 —— 说「成交时间」时要说清是审核通过日。
• 户型字段取自合同关联房源的当前房屋信息 —— 签约后改过户型的话，合同记录里显示的是改后的。
• 合同接口只给结果不给上下文：没有房源编号、楼栋/单元/房号、小区名、单价、朝向、装修、门店。归属哪个小区要用查询时传的 community_title 回填。

get_source_videos 返回字段（房源视频 · 2026-11-02 新增）

add_time     视频记录创建时间（Y-m-d H:i:s）
video_link   视频完整链接

⛔ video_link 的域名含租户标识（实测形如 https://oss.<租户域名>/<租户>/...）—— ⛔ 不得原样写进客户版 / 业主版交付物，对外只说「该房源有视频」或提供经授权的链接。

📋 取数字段白名单（按能力取，只取这些——控上下文成本）

取数只为下表字段服务：⛔ 不为模板之外的维度额外拉外网、额外查询；⛔ 不把原始 JSON 整段读进上下文——大结果一律落盘 → 用脚本 / jq 聚合 → 只把聚合结果读回来（见「查询策略」第 4 条）。

取多少条（避免无谓拉取）：房源列表默认 page_size=50；要更多就显式加大（可到 5000+），要全量仍需翻页到空 + 按 uuid 去重（响应无总数）。合同 ≤100 条。视频按 source_uuid 逐套查。

三条纪律：

1. ⛔ 楼栋 / 单元 / 房号（ridgepole_name / unity_name / door_name）一律不查（房源定位信息禁区，见 15-通用规格.md）。
2. 兜底字段仍要取——statistics_info.supporting 取不到时写「未登记」，前提是取过；⛔ 不得因为"怕麻烦"而不取，那是漏字段不是省成本。
3. 客源的等级 / 阶段 / 跟进原文只用于内部判断（意向强弱、议价空间），⛔ 不进清单文件、不进客户版报告。

查询策略（务必遵守）

1. 单次返回上限（2026-11-02 已改）：接口现已支持分页 —— page_size 实测可取到 5000+（无硬上限），page=1 与 page=2 的 uuid 集合交集 0、连续翻 12 页零重复。⛔ 但响应不含总数、也不含任何分页元数据（只有 data 数组），所以仍然拿不到「一共有多少套」。取全量的正确做法：① 直接 page_size=5000 一次拉（请求数最少）；或 ② 按 room / arch_square / business_name 分段，每段翻页到返回空 + 按 uuid 去重合并。注意接口限流（每分钟约 60 次），分段与翻页间隔勿过密。（旧口径「官方写最多 20 条不分页、实测单次上限 50 条」已作废，保留在下方历史说明里备查。）
2. 必做清洗：先按 house_info.community_type == "住宅" 过滤，剔除车位/商铺再算价格分位数，否则均价被污染。
3. 售租分查：category=租售 混合返回，建议出售、出租各查一次后按 uuid 去重，口径更干净。
4. 大结果处理：单次响应超大时，结果会自动落盘为txt文件，用 jq 按上面字段地图聚合，不要全量读入。
5. 找单套房源：用 extra_filters='{"uuid":"<房源编号>"}'（uuid 为接口官方筛选参数，后缀模糊匹配，故传完整 uuid 最稳）。
6. 查新增房源：order="created_at" 降序 → 本地按 statistics_info.created_at 过滤日期（日均录入量个位数时，需多分几天/几段查询拼齐）。
7. A 查房找房 / B 客源匹配的完整取数与排序口径已移至 references/11-清单与候选组件.md「取数与排序口径」一节——命中 A / B 时在那里读（同户型 + 面积 ±10% / 候选池取全 / 剔非住宅 / 四项综合打分取前 20 / 输出字段与产出形态）。

数据口径提醒

• ERP数据与外网数据（58同城/安居客等）必须分开标注、不可混用；ERP为真实在库挂牌，外网为多口径行情。
• 挂牌价≠成交价，输出成交建议时说明推导逻辑（如挂牌均价×常见让价3-5%、税费对冲等）。
• 接口已返回门店与维护人信息：房源侧为 sale_store_org/lease_store_org（仅门店，无经纪人个人字段）；客源侧为 agent_name/org_name（维护人姓名与部门）。按人/店做统计时以这些字段为准，不要凭小区或区域推断归属。
• 门店、维护人姓名属内部经营数据：对客户/外部输出时避免直接暴露到个人粒度，内部经营分析可正常使用。

常见报错