房地产风险分析专家

房地产风险分析全链路工作流（采集→去化→货值→授信）。覆盖：跨城房源与备案价采集（36城实战、WAF瑞数攻坚、CDP兜底）、去化率四档口径（毛B/净A/签约C/现金回笼D）、开发商穿透检索防JV漏归、预售信息失真核查、货值与授信量化（业态折扣、可变现货值、结清触发点）、实战案例协议、交付规范。适用于：查楼盘房源备案价、算去化率、排查房企在售项目与现金流、做房地产授信尽调。曾用名 real-estate-filing-query。

最后更新：2026-09-04（周五） ｜ 本次变更：⑳ 【更名】 real-estate-filing-query → real-estate-risk-analyst（能力已覆盖房企分析/去化口径/货值授信量化，「备案查询」名不副实；同步改 2 个自动化 prompt + 3 个 skill 交叉引用）＋新增「授信量化四档口径（D 现金回笼）与结清触发点」专章＋headless 反检测启动参数铁律；｜⑲ C 级清零实战固化：山樾湾安居房核实初查时 6 批（2025-09/10、2026-01/02/03/04）为自媒体 C 级，逐一回查官方公示页 + 下载 xlsx 逐套校验后全部升 A（2025-09 实为住保售〔2025〕027号、2025-10 实为 030号、2026-01=054/03月=008/04月=021），C 级彻底清零；来源分级规范改为"不再保留 C 级残留"（发现自媒体线索必须回查升 A，最终交付物不留未升 C 级）；去化率主数字改为全 A 级口径（39.0%），另给含 D 级认购中上限（70.9%）。同步修正此前误记文号 + 批次序列补 027/030。用户强制铁律：该一次性弄完的别虎头蛇尾、留尾巴反问用户——核实类任务发现残留项必须自己闭环，不得在交付后反问"要不要继续"。｜⑱（前）安居房核实路径补充「跨年度多批次连续配售」铁律 + 来源分级标注规范（A官方xlsx/C自媒体/D认购中）；去化率须同时给宽口径（含C级）与严口径（仅A级）；⑰（前）「交付物必须全量重建·时间戳最新」工程铁律｜⑰（前）新增「交付物必须全量重建·时间戳最新」工程铁律（山樾湾 2026-08-24 低级事故根因：报告生成器用事后 append 追加章节→重跑被覆盖→前后口径打架/格式乱/时间戳旧；强制整篇一次性生成 + 实时时间戳 + 交付前回读实测审计，并写入「动态总结机制」章自检清单第 5 条）；⑮（前）新增「安居型商品房去化核实标准路径」专章（2026-08-24 山樾湾花园实战：平台"安居房"标签不区分已售/待售→须走住建局配售批次线交叉印证；059批次选房结果 xlsx"已选房源"状态列筛"已选定"=实际签约套数；91套司法查封实为商铺、与安居房本体风险隔离）+ 案例库新增『深圳·山樾湾花园 安居房去化核实』条目；⑯（前）新增「动态总结进 skill」机制章节（用户强制：每次任务产出必须即时沉淀为 skill 资产）。｜⑭（前）新增「WAF 挑战下的 token 直连枚举法（轻量兜底·无需 CDP）」专章（2026-08-24 晟悦家园实战：SPA initSession 被 tamperUrl 重定向阻断、但 headless token 直连三个枚举接口成功）＋案例库新增『深圳·晟悦家园 WAF 挑战 token 直连枚举』条目＋参考案例 references/cases/深圳-晟悦家园-WAF挑战token直连枚举.md；⑫（前）新增「复用采集器给新项目须防跨项目数据污染」工程铁律（EXTERNAL_JSON 须按项目覆盖 + 标题/外部对比行改 project-agnostic + 交付前全表扫旧项目关键字）；⑬ 正式沉淀第二个案例资产 references/cases/深圳皇熙悦府-跨项目污染教训.md（猴子补丁 wrapper 零改动复用 + 跨项目数据污染坑 + 3 条可迁移铁律），案例库章节同步新增该条目。｜（2026-08-12 基线）① 新增「按开发商/品牌/合作方检索」五阶段 SOP + 四红线（已确认标准起手式）；② 财汇MCP 失效降级到 neodata 等官方工商渠道；③ 新增 scripts/by_developer.py 脚本工厂（P3+P4 一键）；④ 拆分 references/（类型库/瑞数专项/待办清单），主文档去重瘦身；⑤ 新增 scripts/validate.py 质量校验模块并接入工厂；⑥ 工厂增强（深圳注入 PERMITS 修复静默空跑、采集后自动 validate、新增 --mode project-summary 出品牌项目总表）；⑦ 新增 references/城市接入checklist.md 填表式城市接入模板（六步：入口→反爬→API→字段→脚本→收口），探测 SOP 加索引；⑧ 新增 scripts/price_integration.py 外部价格整合与货值测算（D/E 类缺价城市闭环，--demo 自测通过）；⑨ 修正 scripts/by_developer.py 广州适配器空跑 bug（--search 备案名优先 + --search-dev 兜底，新增 --search-name），新增 references/33城总表v6.md 能力矩阵；⑩ 广州鹏瑞壹湾广场实跑闭环（4 项目/1116 套），并修复工厂 AND 组合、采集器空条件硬拼与 __main__ 守卫缺失、price_integration 子串匹配与中位数等 4 处隐性 bug（均端到端验证）。完整变更见 CHANGELOG.md。｜⑪ 2026-08-12 收官复盘：成都案例入 cases、桌面查询实验（城市自由输入+区域联动+点击bug修复+入口脚本）开发后被用户判定实验性搁置、回归 WorkBuddy 运行；提炼 6 条工程铁律（前端必真浏览器验证 / 轻量工具优先零依赖 Web 版 / 联动用自定义 combobox 不用 datalist / 设计从用户场景出发 / 复盘错误诚实更正 / 实验性及时止损），详见 references/复盘_2026-08-12_全天迭代与smart铁律.md。

房地产风险分析（采集 → 去化 → 货值 → 授信）

把"搜索预售证 → 拦截 API → 提取 → 标准化 → 去化口径 → 货值测算 → 授信量化 → 可视化交付" 的完整方法封装为可复用工作流。采集是手段，风险/授信研判是目的——本 skill 不止于查备案价，更覆盖去化水分识别、可变现货值测算与结清触发点判断。

曾用名：real-estate-filing-query（房地产备案信息查询）。2026-09-04 更名为 real-estate-risk-analyst， 原因：能力早已覆盖房企分析、去化口径、货值与授信量化，"备案查询"已名不副实。 历史文档/旧对话中出现的旧名均指本 skill。核心方法论跨城市通用；具体 API 端点与字段随平台变化， 需按同法重新探查（参考文档已给出深圳平台的已验证基准）。

何时使用

• 采集某个房地产项目（楼盘）的全部房源数据并产出 Excel 报告。
• 按开发企业/开发商名查其名下全部存量项目（各项目预售证 + 房源 + 剩余货值 + 失真核查），产出"开发商存量项目清单"（2026-08-11 深润川案例已落地，见下方深圳平台补充）。
• 需要做日/周/月/季的去化对比、价格/状态突变告警。
• 把同样的搜索+统计方式套用到新城市、新平台、新项目。

工作流（SOP）

1. 定位列表/搜索入口：在平台内找到"项目列表/在售楼盘搜索"页（哈希路由或独立路径），用 page.on("response") 拦截其列表 API。

2. 搜索项目名 → 拿全预售证：列表 API 返回每条的 项目ID(ysProjectId) + 预售证ID(preSellId) + 预售证号。一个项目常有多张预售证、各证 ysProjectId 可能不同，务必拿全，否则丢楼栋。 深圳还支持按开发企业名搜全部项目：列表 API getYsfYsPublicity 是 POST（body 加 organName 字段，如 {"organName":"深润川",...}），页面搜索表单 3 个 el-form-item 顺序为 0=项目名称/1=开发企业/2=宗地地址，用 document.querySelectorAll('.el-form-item')[1] 定位开发企业输入框填词后点「查询」按钮；响应每条含 sypId=ysProjectId、sypeId/id=preSellId、strpreprojectid=证号、project=项目名、name=开发企业。深润川实测：搜"深润川"返回 2 项目 4 证（信城缙悦花园×2 + 鸿威鸿景华庭×2）。

3. 逐证访问详情页：用 详情页URL?项目ID&预售证ID 构造地址。详情页会自动发起两个枚举接口：

   • getBuildingNameListToPublicity → 楼栋列表（每条 label=楼栋名，key=fybId 楼栋ID 5位，value=buildNo 19位）
   • getBuildingDictToPublicity → 该楼栋的 gnqmcList(单元名列表，如 ["1单元".."5单元"] 或 ["商业","未知"]) 与 chList(楼层)，响应 data.buildNo=19位（对应楼栋的 value） ⚠️ 5位/19位关联规则（2026-08-11 深润川实测踩坑）：fetch 房源接口的 fybId 必须用 5 位 key；19 位 value 会导致 500「程序异常」。getBuildingDictToPublicity 的 data.buildNo 是 19 位，须匹配 getBuildingNameListToPublicity 的 value 建立 {buildNo: key} 映射，才能把 gnqmcList 关联到正确的 5 位 fybId。单元名用 gnqmcList 原始值（中文数字"一单元"或"商业/未知"都照传），不要兜底成"1单元"（会返回 200 空 data）。 用 page.on("response") 拦截这两个响应来发现全部楼栋与全部单元。

4. 逐楼栋、逐单元取数（关键，不可漏）：房源接口 getHouseInfoListToPublicity 是 POST，请求体带 fybId(楼栋) + buildingbranch(单元) 过滤，默认只返回当前选中单元（通常是 1单元）。务必对每个 (楼栋, 单元) 组合各发一次请求，否则会大面积漏栋漏单元。遍历方式：

   • 用会话 token（从任意 Publicity 请求 URL 的 cuyGLa6e= 提取）在 page.evaluate 内 fetch POST 该接口，body={buildingbranch:单元, floor:"", fybId, housenb:"", status:-1, type:"", ysProjectId, preSellId}；
   • 楼栋切换：点 .el-radio(楼栋名) 触发新的 getBuildingDictToPublicity，再取该栋单元。

5. 拦截并提取房源：房源响应按楼层分组 data:[{floor, list:[house,...]}]，提取须遍历 data[].list；最后按 (楼栋,单元,楼层,房号) 去重。

6. 标准化字段：映射到 楼栋/楼层/房号/建筑面积/套内/分摊/备案总价/备案单价/状态/合同编号。

7. 写历史快照：把当前聚合（总套数、各状态计数、均价、按 日期/周/月/季 分桶）写入 history/snapshots.json，存聚合不存全量。

8. 生成 Excel：≥6 Sheet（预售许可证清单 / 房源明细 / 统计分析 / 剩余货值测算 / 分析总结 / 异常与告警）。可选增补 Sheet：①「预售信息失真核查」（现楼/商办/抵押查封项目必做，见第10步）；②**「外部渠道价格交叉验证」**（当政府平台不公开已备案/已售备案价、为补全数据完整性时必建，见第11步）。晟悦家园已落地 8 Sheet 版（上述 6 + 失真核查可选 + 外部交叉验证）。

9. 剩余货值测算（修正口径）：排除已备案(已售/真正卖掉)房源，剩余 = 可售 + 签约中。基准 = 已备案(已售)房源均价，按两级回退：①优先逐套已备案单价均值；②若逐套不公开(深圳0/***、成都***)→用预售证级备案均价(深圳 getProjectDetailInfoToPublicity 的 均价 字段，如翠湖大厦 83019 元/㎡)作基准；③两级都没有才主口径=0 并备注"无备案价格参考"，同时补「参考口径」= 可售挂牌价之和 + 签约中按同用途可售均价×面积（标注"非备案成交价、仅供参考"）。抵押/查封在售房源单独列示；按全部用途(住宅/公寓/商业/车位等)分列；并输出独立的「合并汇总（全项目）」区块（合计可售面积、合计可售挂牌货值、合计总剩余货值等）作为对外汇报核心指标。

10. 异常与对比：用上一快照做 delta 检测突变（总套数/期房待售/备案均价），区分 异常/提示 两级；首跑无基准不报。

11. 预售信息失真核查（现楼/商办/开发商风险项目必做）：见下方「失真核查专章」。触发条件：项目为现楼、或用途以商务公寓/办公/商业为主、或开发商有失信被执行记录、或用户主动提出疑虑。绝不能把"首次登记/初始登记"直接当已售算剩余货值=0；平台不体现项目级查封；须用财汇MCP 查开发商风险 + 查册/法院公告逐套交叉验证，并在产物单列「预售信息失真核查」Sheet（8 Sheet 版）。

12. 外部渠道价格交叉验证（政府不公开备案价时必建）：很多平台仅公开"期房待售"备案价，已备案/已售房源备案价不公开（深圳/成都常态）。为补全数据完整性，须用外网（贝壳·链家 / 安居客·房天下 / 乐有家 / 吉屋 等）交叉验证一二手房源价格，在 Excel 单列 「外部渠道价格交叉验证」 Sheet，列示：①补全背景（哪类房源价格缺口、占总量比）；②外网采集明细（渠道/类型一手·二手/房源描述/面积/单价/总价/时间/来源URL/备注，一手二手着色区分）；③价格口径对比（政府备案均价 vs 外网一手/二手市场均价 + 折让幅度）；④交叉验证结论（市场价显著低于备案价时，已备案/已售房源真实价值以市场价代理，参考口径偏保守）。实现方式：外网数据由 Agent 用 WebSearch 获取后落盘为 output/external_prices.json（结构化 records + search_date + tag），脚本 load_external_data() 读取并在 generate_excel 末尾 add_external_sheet() 追加 Sheet（文件缺失则跳过，不影响主流程）。数据来源标注：外网数据一律标注 [外网·WebSearch YYYY-MM-DD]（与用户长期数据标注偏好一致）；所有外网价为市场挂牌/成交价、非政府备案价，仅作价值量级参考、不构成逐套精确值。

关键工程约定

• 平台多为 Vue SPA + 动态 token，纯 HTTP 直连不可用 → 必须 Playwright 拦截响应。

• request/response handler 用 x.url，不是 x（对象不可直接 in 字符串）。

• ⚠️ 房源接口按「楼栋+单元」范围返回（最易漏的坑）：getHouseInfoListToPublicity 是 POST，带 buildingbranch(单元) 过滤，默认仅返回 1单元。绿景白石洲璟庭 1栋有 5 单元共 2746 套，若只取默认 1单元会漏掉 2293 套（占 84%）。必须枚举全部楼栋+全部单元、逐组合取数并去重。

• ⚠️ 深圳 B1 全量快照（units_summary.dedup.jsonl / 深圳销控总表 / TOP20 分表）系"首屏一次采集"，未做单元枚举 → 系统性失真（2026-08-27 修正口径）：730 项目中 233 个（31.9%）仅采到 1 个单元，高可疑 45 + 中可疑 28 = 73 个须枚举重采（多证单单元/套数异常小/空采）。⚠️ 旧记"621/730=85.1%"系 scan_shenzhen_distortion.py 解析器错配（把扁平房源列表误判为 0 房源）产生的假象，2026-08-27 已修正解析器。该快照只能当"下界/部分口径"，不可作权威全量；引用时须标注"B1 首屏口径·未枚举·可能低估"。重采须走枚举法（collect_shenzhen_enum.py CDP 连本机 9222 真实 Chrome 绕过 WAF，见 developer-group-cross-analysis skill 可复用资源）并在用户本机/住宅 IP 运行（沙箱 WAF 拦不到 token）。

• 枚举接口可直连，但须带 token（已验证，纠正旧误述）：getBuildingNameListToPublicity / getBuildingDictToPublicity / getHouseInfoListToPublicity 三个接口都用 ctx.request.post(f"{BASE}?cuyGLa6e={tk}", ...) 带 SPA 下发的 cuyGLa6e token 直连即可（见 collect_longhan.py 逐栋逐单元枚举法，已抓到珑瀚 366 套全量；旧 SOP 称"必须靠页面自动触发拦截、裸 fetch 直连返回 500"——500 实为裸 fetch 无 token/无会话所致，ctx.request 携带会话+token 则直连成功）。流程：getBuildingNameListToPublicity(拿 5 位 fybId) → getBuildingDictToPublicity(拿 gnqmcList 单元名) → 逐单元 getHouseInfoListToPublicity(body 带 buildingbranch=单元名)。wait_for_response 在用户本机环境可用（fetch_house_data.py 即依赖它跑通），沙箱探测环境偶尔缺失该方法时改用 page.on("response") 监听即可。

• 价格行为：很多平台只给"期房待售"公开备案价，已备案/已售等不公开 → 缺失价是正常，勿当异常；缺失单价可用 总价/面积 回算。

• ⚠️ 预售信息失真风险（翠湖大厦教训，2026-08-10；深润川存量项目 2026-08-11 复现）：① 深圳「首次登记」= 开发商大确权状态，现楼项目≠已售，切勿计入"已卖掉"并直接算剩余货值=0；② 平台状态不反映项目级/开发商级查封，仅具体房源被司法查封才显示"司法查封"状态——开发商失信被执行时单套状态仍可能全"首次登记/已备案"，属信息失真；③ 企业司法/金融风险数据优先用财汇MCP(企业预警通)，但其不覆盖不动产/房产抵押，须深圳市不动产登记中心查册或法院公告逐套交叉验证具体房源权利限制；④ 涉及现楼/商办项目时，务必做失真核查并在产物单列「预售信息失真核查」Sheet。深润川案例（存量项目失真核查范式）：名下 2 项目 4 证 2126 套全部「首次登记1161/已备案962/区局锁定3」，0 套备案价公开、零期房待售；开发商为深圳中院 1.82 亿元执行标的被执行人+限高（财汇MCP核实），但平台零司法查封标识；外网证实信城缙悦花园 2026-07 仍现房在售（2.0-2.6万/㎡≈备案价 3.97 万的 5-6 折）。剩余货值须双口径：上限口径（全部首次登记=可售存量，主口径按证级备案均价 34.5 亿/参考口径按市场价 25.3 亿）+ 审慎口径（现房在售确认可售的项目才计：信城 22.9 亿/12.4 亿；交付 13 年二手活跃的鸿威视为业主已办证、货值趋近 0）。采集完整性校验技巧：每证房源面积合计应等于预售证详情 presellarea，全对上即证明无漏栋漏单元（深润川 4 证全部精确相等）。

• ⚠️ 口径写在文档 ≠ 脚本已实现（晟悦家园 2026-08-11 教训）：剩余货值「两级回退」必须在代码里真正落地。晟悦家园脚本原先只实现 ①逐套已备案均价 → ③归零，漏掉第②级"预售证级备案均价"，导致主口径错误显示为 0（实际应为 5.897 亿元）。深圳落地方法：getProjectDetailInfoToPublicity 响应中 averagePriceTotal=证级备案均价、buildingnb=该证楼栋名，构建 {buildingnb: averagePriceTotal} 映射，逐套匹配 houses[].楼栋 计算主口径（晟悦家园：2栋 25,722.89、晟悦家园1栋 35,999.97 元/㎡）。**每次改口径后必须回读生成的 Excel 校验主口径非零且基准来源标注正确，别只看脚本跑通。**建议在 Sheet 内输出「主口径基准来源/明细」两行，一眼可判用了第几级。

• ⚠️ 复用采集器给新项目须防跨项目数据污染（皇熙悦府 2026-08-14 教训）：fetch_house_data.py 本质是按晟悦家园打磨的通用采集器，经 wrapper 猴子补丁（覆盖 PROJECT_NAME/PERMITS/HISTORY_FILE）即可零改动复用给任意新项目。但有两处会静默泄漏旧项目数据、必须处理：① 外部交叉验证 Sheet 的 EXTERNAL_JSON 固定读 OUTPUT_DIR/external_prices.json（晟悦家园外网价），新项目必须在 wrapper 里 fh.EXTERNAL_JSON = HERE/\"external_prices_<项目>.json\" 指向本项目外网价文件，否则会把旧项目（如坪山≈2.2万/㎡）价格套到新项目（如福田≈11.5万/㎡）上，得出 80% 折让等荒谬结论；② 脚本的 Sheet 标题 A1 与「外部渠道价格交叉验证」对比行/结论曾硬编码"晟悦家园/坪山"，必须改为 f\"{PROJECT_NAME} ...\" 并由 permit_details 逐楼栋动态生成对比行（不得写死旧项目证号）。交付前必做：对产出 Excel 全表扫描旧项目关键字（如"晟悦家园/坪山"），0 命中才算干净。

• 单元枚举核查要留证：即使项目最终是单单元，也应跑一次 getBuildingDictToPublicity 核查并把 gnqmcList 记录在案，避免后续反复怀疑漏抓。晟悦家园已验证：两张证各 1 栋，gnqmcList 分别为 ['未知']、['住宅']，均为单单元，默认请求即全量（616=294+322）。

• ⚠️ 采集后必做多键去重核查（2026-08-18 淦盈置业·祥云居沉淀）：楼栋标签可能重复（同标签分属不同批次/不同楼栋ID，如三座×2、五座×3），脚本内置去重（标签+房号）可能误删或漏删 → 交付前跑多键独立核查：(楼栋ID+房号) / (预售证号+房号) / (预售证号+房号+坐落) 全部 0 重复才算干净。"同房号跨多证号"≠重复（不同楼栋各有同号房，如每栋高层都有 3101），以楼栋ID+房号为准即唯一。另：用途归类先精确匹配再 startswith——"住宅车位".startswith("住宅") 为 True 会把车位误算进住宅（祥云居去化率被污染 74.1%→修正 96.3%）。

• ⚠️ 状态词表随项目不同，勿硬编码 4 种：深圳实际状态含 期房待售/已签认购书/已签合同/已备案/首次登记/已录入合同/司法查封/安居房/在建抵押/锁定 等。剩余货值里"已卖出/已登记"类须用 {已备案, 已售, 首次登记}（代码常量 SOLD_STATUSES）；分析总结须遍历输出全部状态而非只打 4 种，否则会漏算（翠湖大厦 468 套"首次登记"被漏打即教训——它实际是已办证/已转移登记=已卖掉）。单元枚举用 getBuildingDictToPublicity 的 gnqmcList 核对单元数，>1 单元须逐单元全量抓（翠湖 gnqmcList=["未知"]=单单元，528 即全量）。

• 列表页先于详情页：详情页 API 只返回当前预售证数据，从详情页挖不到其他证/楼栋；但详情页内要主动遍历楼栋/单元。

• ⚠️ "lite" 不能作为自动化(automation)的 modelId："lite" 是 Agent 工具的模型变体名，自动化运行时不认，设成 "lite" 会导致定时任务启动失败、完全不执行（实测：8/7 设置后 8/8 全天 + 8/9 上午的任务全部缺席）。自动化 modelId 需用具体模型标识符或 "default"；在确认某 modelId 对自动化有效前，勿盲目设置。交互式 Agent 调用仍可用 model: "lite" 变体省钱。

• 历史快照去重：save_history() 应按"日期+小时"去重（同小时只留最新一条），避免短时多次运行（如手动+自动化撞车）导致快照堆积膨胀。

• ⚠️ 先找公开入口，再考虑 CAS/SPA：很多城市有两条路径——公开信息页（无需登录/验证码）和查询SPA（需CAS/验证码）。务必优先走公开页。成都的 infoDetail 公开页（blmp.cdzjryb.com/fplc_daas_portal/#/infoDetail?...&type=1&title=预/现售项目）可直接按项目名搜索、返回含「一房一价」「预/现售方案」详情链接的表格，点击「一房一价 详情」即跳转逐套房源页 zw.cdzjryb.com/roompricezjw/index.html?param=<token>，全程无需登录/验证码。只有需要更深层数据（如预售证PDF原文）时才走 CAS SPA。

• CAS SPA 驱动（fallback）：带 CAS 的 SPA 直接用 page.request.get/post 或 page.evaluate(fetch) 打 CAS 网关接口会超时/Failed to fetch。正确做法：用 Playwright 填充查询表单 + 点提交，让 SPA 自己走内部 axios XHR 完成 CAS 票据流程；再用 page.on("response") 或 page.add_init_script 钩 fetch/XMLHttpRequest 拦截响应。成都 SPA 真接口是 /fplc/Ticket/getDataWithLogin（POST，返回 hex 编码的 PDF），而非直观的 /fplc/zhcx/HouseListQuery（超时不可用）。

• 验证码先查前端 canvas + Vue $data：很多 SPA 验证码是 <canvas id="s-canvas"> 由 Vue 组件 fillText 前端绘制、值存在 __vue__.$data 里（键名含 code/captcha，值为 3–8 位字母数字），用 el.__vue__.$data[k] 直接读，比"明文验证码接口"更通用——先查 DOM <canvas> 与 Vue $data，再退而求其次找验证码接口。

• 逐套房源页结构（roompricezjw 模式，成都已验证）：跳转到 roompricezjw/index.html?param=<token> 后，页面渲染 <table> 含全部字段（楼栋号/楼层/房号/建筑面积/户型/挂牌清水价/装修价格/用途/销售状态/抵押/查封）。楼栋/单元切换靠 .rp-nav-item[data-val="HNO"]（楼栋tab）和 .rp-subnav-item[data-val="UNO"][data-parentval="HNO"]（单元tab），.on 类标记当前选中。API：POST /house-one2one/one2one/getHnoAndUnos 返回楼栋/单元列表（明文JSON），POST /house-one2one/one2one/getFloorEstateOfViews 返回逐套数据（加密/Base64编码，但页面JS解密后渲染到table）。直接 scrape 渲染后的 table DOM 比解密API更可靠。关键坑：①点击已激活(.on)的nav会清空表格，须检查 classList.contains('on') 跳过；②subnav选择器须带 [data-parentval="HNO"] 避免跨楼栋误匹配；③每次点击后 wait_for_response("getFloorEstateOfViews") + 1.5s 渲染等待。

• 预售许可证信息纳入采集：在房源明细Excel中增加「预售许可证清单」Sheet，记录每张证的 证号/项目名/行政区域/项目地址/房屋用途/开发商/预售面积/预售日期/监管银行/监管账号/备注 等字段。这些信息通常在公开列表页（如成都infoDetail）或详情页API中可直接获取。

• 剩余货值测算（口径详见 SOP 第 8 步）：Excel 增「剩余货值测算」Sheet。关键补充（2026-08-10/08-11 实战）——①口径分级：现楼/首次登记场景须输出「上限口径」（全部首次登记=可售存量）与「审慎口径」（现房在售确认可售的项目才计，交付多年的视为业主已办证），见深润川案例（上限 34.49 亿 vs 审慎 22.91 亿，均分主/参考双口径）；②基准两级回退在代码里必须真正实现并回读校验（晟悦家园漏实现第②级导致主口径错误为 0，教训）；③「合并汇总（全项目）」区块是对外汇报核心，勿省略；④切勿把可售均价直接当主基准——它是替代参考，不是备案成交价。

• ⚠️ 交付物必须全量重建、时间戳必须最新（山樾湾 2026-08-24 教训·用户强制）：任何重新生成 Excel/Word 的脚本，必须"整篇一次性生成"，严禁事后用 add_paragraph/append 追加章节再覆盖——否则每次重跑旧版函数体会把追加内容覆盖掉，制造"前后口径打架、格式乱、章节时有时无"的低级事故（本次 Word 就曾出现第四、六章结论冲突）。强制规则：① 报告正文（含全部章节、全部口径修正）必须写进生成函数体内一次性产出，不依赖运行后再补；② 生成时时间戳一律用 datetime.now() 实时刷新，禁止硬编码旧时间或从旧文件残留；③ 重跑即覆盖旧产物，产物文件名带时间戳区分版本，交付时只给最新版；④ 交付前实测审计：用 openpyxl/python-docx 回读生成的文件，确认（a）章节齐全且口径一致无冲突、（b）时间戳为本次、（c）无旧项目关键字残留。这条是"动态总结进 skill 机制"的交付物自检项，违者等同未完成任务。

预售信息失真核查工作流（现楼/商办/抵押查封项目专章）

翠湖大厦（2026-08-10）核心教训：现楼/商办项目的平台预售信息会系统性失真，若不核查会把"仍在开发商名下可售"的房源误判为"已售罄"，得出剩余货值=0 的致命错误结论。本专章是 SOP 第 10 步的展开。

触发条件（满足任一即必做）

• 项目为现楼（已竣工交付，存在"首次登记/初始登记/大确权"状态）
• 用途以商务公寓/办公/商业/车位为主（非单纯住宅）
• 开发商存在失信/被执行/限高/股权出质等风险信号
• 用户主动提出"现楼/抵押/查封/是否失真"等疑虑

四步核查法

1. 状态语义校验：核对平台状态词表中「首次登记/初始登记/大确权」的真实含义——在深圳即开发商初始登记（取得大产证），是现售前置条件，≠ 交易完成(已售)。现楼项目大量此类状态的房源实际仍在开发商名下可售。剩余货值口径里绝不能直接把"首次登记"计入已卖掉；去化率亦不可简单用"总套数−期房待售"算（会虚高）。
   • ⚠️ 去化率三档对比铁律（2026-08-20 实战修正）：交付物须并列三档，缺口即"号称卖掉但未实锤"的水分，反推资金回笼须以审慎口径为硬底数：
     • 审慎去化率(主) = (已备案 + 已售 + 首次登记) / 总套数 —— 仅已向房管部门备案/办证的销售视为真去化，用于反推销售资金回笼。
     • 含签约管道去化率(次) = (审慎分子 + 已签认购书 + 已签合同 + 已录入合同) / 总套数 —— 仅反映签约势能，未备案前可撤单/被按揭拒批，不作去化结论。
     • 宽口径去化率(对比) = (总套数 − 期房待售) / 总套数 —— 除在售外全算卖掉（含签约管道+受限房源+政策房），仅供与审慎口径对比，严禁直接采信。
     • 宽-审慎差(pp) = 宽口径 − 审慎口径，差额即水分（认购/合同管道 + 受限/政策房源）；差额≥15pp 须高亮提示。
     • 在建抵押 / 司法查封 / 区局锁定 / 共有产权房 / 安居房 一律不计入审慎去化（受限/政策房，分母保留全部故偏保守）。
     • 代码实现：fetch_house_data.SOLD_STATUSES、collect_shenzhen_all_units.py、build_shenzhen_units_summary.py 三处已对齐；汇总脚本务必从原始 statuses 重算，勿直接信任 jsonl 的 sold/destock_rate 旧值（旧版曾误含签约管道）。
   • ⚠️ 物业类型范围（2026-08-20 用户强制）：分析重心为可自由交易的物业（商品住宅 / 公寓 / 商办写字楼）；政策性住房（安居房、共有产权房等）保留在统计范围但不过度纠结——有数据就带、无详细数据也无所谓，绝不因政策房数据缺失而阻塞或返工。政策房不计入审慎去化、单独成列标注即可。如需项目级"可交易 vs 政策房"筛选，房源级 useage 字段已存在于逐套 raw（fetch_house_data 提取的 house 含 "用途"/useage，注意源字段名拼写是 useage）。已落地：build_shenzhen_units_summary.py 从 raw_{safe(项目名)}.json 聚合 useage（去空格归一化，如"单 身 公 寓"→"单身公寓"），生成项目级「物业类型」列（商品住宅/公寓/商办写字楼/产业工业/宿舍配套/酒店/其他）及「可交易套数」「可交易占比%」（可自由交易=商品住宅+公寓+商办写字楼）。空 raw 标"无逐套数据"。每次重跑自动刷新，无需手动。
2. 查封体现校验：平台"司法查封/在建抵押"等状态仅当具体房源被司法查封时才显示；项目级/开发商级的查封与债务限制不在单套状态中体现。若某项目全部房源 lastStatusName 均为"首次登记/已备案"、零"司法查封"标识，但开发商确有债务风险，则属典型失真——不得据此认为"无查封"。
3. 开发商风险核查（财汇MCP·企业预警通）：用 caihui_mcp 查开发商 失信被执行人 / 限高 / 被执行人(执行标的) / 股权出质 / 司法冻结；⚠️ 财汇MCP 不覆盖不动产/房产抵押，仅反映企业级债务信号（股权未冻 ≠ 房产未封）。数据须标注 [MCP·预警通 YYYY-MM-DD]。⚠️ 同 P2 降级规则：若财汇MCP 不可用，按优先级降级——① neodata（WorkBuddy 企业数据连接器，取失信/限高/股权出质/司法冻结等）；② 国家企业信用信息公示系统 / 天眼查 / 企查查 等权威工商源；③ WebSearch 定向兜底（须明示「风险核查降级、置信度有限」）。来源标注同步切换为 [neodata] / [工商·公示系统] / [工商·天眼查] 等，并在交付物注明本次实际所用渠道。
4. 权利限制交叉验证：逐套权利限制须 深圳市不动产登记中心「查册」或法院查封公告 确认；辅以第三方在售渠道（吉屋/焦点/企查查/启信宝）佐证项目是否"在售/工抵房"。外网数据标注 [外网·WebSearch]。

产物要求

• 在 Excel 追加独立 「预售信息失真核查」Sheet（8 Sheet 版），列明：失真点、状态语义误判、平台不体现查封、开发商风险证据、交叉验证结论、真实剩余货值的可测算性结论。
• 修正原"剩余货值=0 / 100%去化"的错误表述，改为"平台显示去化殆尽，但现楼语境下失真，真实剩余货值受价格不公开+查封限制无法精确测算，建议单套查册"。
• 来源标注严格遵循用户长期偏好：财汇MCP = [MCP·预警通]；外网 = [外网·WebSearch]。
• 【用户强制规则·2026-08-20】所有交付的 Excel/Word 必须标注数据时间：每个 Sheet 首行加"数据时间：YYYY-MM-DD（数据反映时点/官方发布日）｜本表生成：YYYY-MM-DD｜来源"标注行（深色底合并单元格，表头下移一行）；「数据来源说明」Sheet 单列「数据时间/本表生成」两行。数据时间≠生成时间：数据时间=官方发布日/数据反映时点，生成时间=本表制作日。参考实现：build_sz_refprice.py 的 add_note_row()。

经验教训总结（踩坑复盘 · 元级教训）

以下来自 2026-08 成都青江名邸项目的真实踩坑，优先级高于具体技术细节。

1. ⚠️ 绝不下"数据不可得"的过早结论。当某条路径（如 CAS SPA 详情页 getWebPreSellInfo）只返回项目级汇总时，绝不意味着"平台不公开逐套"。很可能存在另一套独立系统（公开信息公示页）含完整逐套"一房一价"。本案先误判"成都不公开逐套"，后因用户截图显示 7 条记录（非已抓的 3 条）才推动重新探查，最终在公开 infoDetail 页找到完整逐套数据 —— 方法没问题，是路径选错了。
2. 用户在线所见 = 最高优先级信号。用户说"我在网上看不止这些项目信息，也不需要登录/验证码"时，必须重新探查，而非以"平台规则"驳回。用户截图/反馈是交叉验证的金标准：凡用户报告"看到更多/不需要登录"，立即回到平台重新找入口，不要依赖自己之前的探测结论。
3. 公开页优先于登录/SPA（双系统并存）：详见「关键工程约定」第 56 行——政府平台普遍有公开公示页 + 认证 SPA 两套系统，务必先试公开页。
4. roompricezjw 模式可跨城市复用。楼栋 tab(.rp-nav-item[data-val]) + 单元 tab(.rp-subnav-item[data-val][data-parentval]) + 渲染后 <table> DOM scrape + 每次切换 wait_for_response 的模式，适用于任何"一房一价"式逐套页面；API 响应即使加密，scrape 渲染后的 table 更稳。
5. 价格可见性规则（跨平台一致）：仅"可售/期房待售"公开备案价；"已售/签约中/已备案"显示 *** 或留空 —— 属平台规则，非数据损坏、非异常，缺失单价可用 总价/面积 回算。
6. 剩余货值测算基准：详见 SOP 第 8 步 + 「关键工程约定」第 61 行——基准用已备案均价、两级回退须在代码落地并回读校验、必须补「合并汇总（全项目）」区块。
7. 交付物随数据粒度自适应：有逐套 → 6 Sheet 完整版；只有项目级 → "房源明细"改为"项目汇总"，其余 Sheet 照常。两种都合法，别在逐套接口上死磕。
8. ⚠️ 现楼/商办项目必做「失真核查」：详见「预售信息失真核查工作流」专章（第 63 行起）——「首次登记」≠已售、平台不体现项目级查封，否则会误判剩余货值=0（翠湖大厦教训）。 9–10. 反爬类型识别与定性：详见 references/类型库.md 二、反爬类型速查 + references/瑞数专项.md——务必实测 WAF meta id 再定性（杭州原误判瑞数实为阿里云 WAF）；难度排序：瑞数 > 顶象(headless) > 阿里云 acw_sc__v2。
9. ⭐ 产出约定（2026-08-11 用户明确）：日常单项目检索固定「Excel + 交互看板」双件套（Excel 存档/授信、看板演示/探索），跨城大屏等综合看板仅少数综合场景才做。
10. ✅ 交互看板 = 交付物升级方向（探数数三层）：把 Excel 升级为自包含 HTML 看板（6 图表 + KPI + 质量校验 10 项 + 楼层梯度回归 + 6 决策模块 + 四筛选 + 排序分页），可离线/发给客户。通用生成器 build_house_dashboard.py 一条命令复用（自动探测表头/动态列映射/动态状态配色/兼容两种剩余货值结构）。
11. ⚠️ 政府开放数据平台也可能在同一 WAF 下（上海 data.sh.gov.cn）：开放数据平台看似「无条件开放、CSV/JSON 可下载」，但 API 与下载链接可能在瑞数 412 下全挂——别默认它可用，先 requests 试一下。替代：同城其他局委域名（上海 fgwapp.fgj.sh.gov.cn 无瑞数保护，11342 条证级直连）。
12. ⭐ 成都青江名邸完整复盘已沉淀为独立案例：见 references/cases/成都青江名邸-教训案例.md——本案贡献三大新教训：① 分母对齐（覆盖率/缺口的分母必须严格匹配"抓取目标范围"，错用"项目总建面"当分母会系统性高估缺口，正确用"预售建筑面积"得 69.4%）；② 双口径货值（逐套价不公开时，用官方"预/现售方案"modal 的预售均价×预售面积解锁"官方备案货值"口径，与实测逐套货值互证、诚实标注覆盖率）；③ 复盘诚实更正（发现分母错立即在文档更正、不掩盖）。该案例是「公开信息页 infoDetail + roompricezjw 逐套 + 预/现售方案 modal」完整组合的首个落地范例，亦印证本清单 #1–#4。

工程铁律（2026-08-12 今日复盘提炼 · 元级）

今日（成都案例入 skill + 桌面查询实验开发/bug修复/入口/搁置回归）收口复盘，提炼为跨任务强制规则。详细复盘见 references/复盘_2026-08-12_全天迭代与smart铁律.md。

1. ⚠️ 前端交互必须真浏览器验证，绝不只验 API：今天城市下拉用 <input list>（datalist）只验了后端 API 正常，交付后用户实测"点击无反应"——根因 datalist 只在打字时弹、点击不展开。凡涉及 UI 交互，交付前必须用 Playwright + 本地 Chromium 真跑点击/输入/联动（gui_desktop/verify_ui.js 即回归脚本），零报错才交付。
2. 轻量分发工具优先零依赖 Web 版，而非 tkinter：tkinter 在精简/便携 Python 常缺 Tcl/Tk（本环境即缺），无法渲染验证、跨机部署也怕缺包；改用 标准库 http.server + webbrowser.open 的本地 Web 版，任何装 Python 的机器都能跑、且可沙箱实跑验证。
3. 依赖联动下拉用自定义 combobox，不用 datalist：自定义 <input>+<div列表>（focus/click 展开、input 实时筛选、mousedown 回填、blur 延时关）比 datalist 可控；未知项用「手动输入 fallback」兜底，不阻断流程。
4. 设计从用户真实使用场景出发，不从"实现便利/适配范围"偷懒：城市本不该被"skill 只适配33城"锁成固定下拉——用户要"别人也能查"的通用工具，城市本就该自由输入 + 适配标记。功能边界由需求定，不由当前能力定。
5. 复盘发现错误立即诚实更正，不掩盖：今天的套数差异复盘曾错用"项目总建面"作分母高估缺口38%，发现后立刻在文档更正为预售建筑面积得69.4%（见本清单 #14）——错误更正本身也是资产。
6. 实验性分支及时止损，回归主线：桌面查询程序被用户判定为实验性、要求搁置——立即归档经验、回归 WorkBuddy 内运行（skill 采集 + Excel/看板双件套），不沉没成本、不强行推进。

案例库（实战复盘 · 可复用教训资产）

每个案例是某一城市/项目从「踩坑 → 修复 → 复盘 → 提炼」的完整闭环，沉淀为可迁移方法论。新城市/新项目遇到同类问题优先查本库。

• 成都·金地青江名邸（2026-08）：首例「公开页 infoDetail + roompricezjw 逐套 + 预/现售方案 modal」完整组合。核心教训——分母对齐（覆盖率分母须匹配抓取范围，错用总建面高估缺口 38%→正解 69.4%）、双口径货值（官方预售均价×预售面积解锁权威货值，与实测货值互证）、复盘诚实更正。完整文档见 references/cases/成都青江名邸-教训案例.md。
• 深圳·皇熙悦府（卓越缦悦）（2026-08-14）：首例「猴子补丁 wrapper 零改动复用采集器给新项目」实战，暴露 跨项目数据污染 新坑——复用 fetch_house_data.py 给皇熙悦府时，首次成品 Excel 的「外部渠道价格交叉验证」Sheet 静默继承了晟悦家园（坪山）外网价与硬编码标题/对比行，福田项目算出 80.6% 折让等错误结论。核心教训——① 复用须按项目隔离 EXTERNAL_JSON/HISTORY_FILE/PROJECT_NAME；② 采集器须 project-agnostic（标题/对比行/结论不写死旧项目值）；③ 交付前用 openpyxl 全表扫旧项目关键字（命中即回退）。修复后全表扫描旧项目关键字 0 命中、折让修正为 11.5%。完整文档见 references/cases/深圳皇熙悦府-跨项目污染教训.md。
• 佛山·中粮珑湾祥云/祥云居（淦盈置业）（2026-08-18）：首例「开发商专项 + 自持转可售核实」——官方搜索框定位项目（#floorsearchkeyword 输入+点 button.btn-search，Enter 不触发）→ --ids 69262 逐栋实采 1,040 套。核心教训——① 多键去重核查（楼栋ID+房号/证号+房号/证号+房号+坐落 全 0 重复；同房号跨证号=不同栋同号房属正常）；② 用途归类先精确匹配再 startswith（"住宅车位"污染住宅统计）；③ 自持转可售判定＝最新现售证批次×可售状态（官方无自持专列）；④ 官方页面顶部"680/80/600"为全站占位符不可用；⑤ --ids 会覆盖共享 houses.json，专项数据立即备份隔离。完整文档见 ~/.workbuddy/skills/developer-group-cross-analysis/references/淦盈置业案例.md（跨 skill 案例）。
• 深圳·晟悦家园（2026-08-24）：首例「WAF 挑战下 token 直连枚举法」实战——深圳房信对 headless 发起 SPA 会话挑战（initSession→tamperUrl.html 重定向），SPA 不再自发触发业务 API，但 headless 下发的 cuyGLa6e token 对三个枚举接口直连 POST 仍有效。改用「headless 取 token → page.request 直连逐(楼栋,单元)枚举」绕过，无需 CDP 真实浏览器，一次跑通 616 套全量。核心教训——① WAF 只拦 SPA 会话流程、不拦带 token 的直连 API；② 此轻量兜底优先于 CDP；③ 仍须复用 8-Sheet 管道并按项目覆盖配置防污染。完整文档见 references/cases/深圳-晟悦家园-WAF挑战token直连枚举.md。
• 深圳·山樾湾花园（汉京山樾湾）（2026-08-24）：首例「安居型商品房去化核实标准路径」实战——平台 4900 套标"安居房"不区分已售/待售，单套去化算不出。核心成果——① 普通商品房 8-Sheet 管道直接套会失真（安居房误判已售 + 商业异常值拉爆均价）→ 必须切安居房适配口径；② 住建局配售批次线闭环：059 批次房源池 1654 套→实际选定 112 套（6.8%，双 xlsx 文件交叉校验一致）、064 批次 1563 套认购中（2026-09-01 截止）；③ 91 套司法查封逐套核用途全为商铺，与安居房本体风险隔离；④ 证级备案均价平台公开（4.4 万/㎡）但单套配售明细价不公开。⚠️ 外网复核关键修正（同日）：山樾湾自 2025-06（住保售〔2025〕014号）起已跨年度月度连续配售（014→034→040→031→059→064），累计已选定超 2000 套，绝不能只查最近批次；2025-09/10、2026-0104 各批"已选定"来自自媒体汇总（C级，谨慎采信），须按 A/C/D 来源分级标注、去化率给宽/严双口径。完整文档见 references/cases/深圳-山樾湾花园-安居房去化核实.md。

采集路径决策树

text

开始
 ├─ 有公开信息公示页（含"一房一价/详情"链接，无需登录）？
 │    └─ 是 → 点「详情」→ roompricezjw 式逐套页 → 遍历楼栋/单元 scrape table ✅
 ├─ 否，但有查询 SPA（需登录/CAS/验证码）？
 │    └─ 是 → 表单驱动 + 拦截响应 → 取项目级/PDF（或 CAS 穿透后逐套）
 └─ 都无逐套入口 → 交付项目档案（6 Sheet 中"房源明细"改"项目汇总"）

跨城市扩展采集（33 城实测 · 2026-08-11 收官）

异地多城"一房一价/备案价"逐套采集的实测分类与方法库。城市平台速查表（33 城）见 references/real-estate-guide.md 五-B；本节约方法论与"下次怎么继续"。

城市分类（按用户规则：A 纯匿名可自动化持续 / B 待解IP封 / C 待一次性环境 / D 需用户协助不纳入持续 / E 反爬或不可达）

类	数量	城市	说明
✅ A	10	深圳/成都/佛山/珠海/南京/重庆/苏州/西安/武汉/郑州	纯匿名可自动化，已固化采集器，采样 ≈1.07 万套
🟡 B	3	无锡 / 杭州 / 广州	无锡：方法通，沙箱出口 IP 被拉黑 → 用户本机跑 extract_wuxi.py；杭州（2026-08-11 升级）：项目级/证级可采（阿里云 WAF 已绕过），仅逐套一房一价被顶象无感验证拦截 → B+ 类，用户本机住宅 IP 大概率进白名单可拿逐套；广州（2026-08-12 实测修正，原误列 E/瑞数）：阳光家缘(zfcj.gz.gov.cn)为 jQuery/Vue 站，反爬实为 nginx Referer 校验+IP信誉（非瑞数，无 hmYiCp5tA9K0），Playwright 同域 fetch 可过；逐套销控表(房号/面积/户型/用途/状态/抵押)可全自动采，但备案价需'广州市房地产行业协会'小程序PDF或依申请公开 → 销控表版 B 类（extract_guangzhou.py 已落地，详见 output_cross/广州/status.txt）
🔧 C	1	宁波	采集器就绪，仅差一次性装 Tesseract 跑 OCR（PNG 反爬）
🔶 D	12	合肥/东莞/肇庆/中山/清远/潮州/茂名/惠州/廊坊/天津/贵阳/济南	小程序/扫码/注册登录/无制度（济南），不纳入持续
🚫 E	7	北京/石家庄/常州/保定/江门/上海/南通	瑞数反爬、域名劫持、无入口

广州专区（B 类 · 阳光家缘 zfcj.gz.gov.cn）

• 反爬：nginx Referer 校验 + IP 信誉 WAF；非瑞数（无 hmYiCp5tA9K0 meta）。裸 curl 易 403；须 Playwright 同域 fetch（带 cookie/Referer，JS 内 o.u/o.p 单参）绕过。
• 关键端点：
  • 列表 zxyslplb.ashx（showNum 参数）——仅返最新 10 条、不接受关键词，用于"最新项目"采样。
  • 检索 fdcxmxxlb.ashx（sProjectName / sDeveloper / sPresellNo / page / pageSize，全库 11902 条）——按备案名/开发商/预售证定位"非最新"项目，是唯一能命中老项目/具体楼盘的入口。
  • 楼栋 xmldxx.ashx（sProjectId）→ 逐套 xmxkbxx.ashx（buildingId + 固定过滤参数）。
• 状态码图例（阳光家缘官方销控表页，2026-08-12 核验）：1=可售 · 2=已售(已签合同) · 3=已备案(合同登记备案) · 4=已过户(所有权转移) · 5=不可售/限制销售。授信口径：status∈{2,3,4} 均计"已售/权属已转移"；抵押以 pledgeStatus≠0 计（码 1=已抵押/2=已解押/3=已抵押其他）。
• 缺口：广州备案价不经 API 返回，须"广州市房地产行业协会"小程序 PDF 或依申请公开 → 货值测算需外网补价或官方底单。
• 采集器：extract_guangzhou.py 已支持 --search <备案名>（按 fdcxmxxlb 检索，输出 5 Sheet：项目清单/房源明细/统计分析/状态码图例/口径说明）。例：python extract_guangzhou.py --search "壹湾广场" --max-projects 0 --out <xlsx>。
• 实测坑：① 搜开发商"鹏瑞"返回 0（注册名是"广州市铮玥投资有限公司"），须按备案名搜；② fdcxmxxlb 项目字段用 section/projectAddress（旧 zxyslplb 用 sectionName），采集器已做归一。③ 接口对 sProjectName 与 sDeveloper 做 AND 组合：工厂曾把两者同传导致必返 0，已修复为"有备案名只传 --search"；④ 采集器 asyncio.run(main()) 现已加 __main__ 守卫，避免被 import 时误跑默认全量抓取。
• 实跑闭环（2026-08-12）：by_developer.py --brand 鹏瑞 --city guangzhou --search-name 壹湾广场 命中 4 项目/1116 套官方逐套；官方备案主体=广州市铮玥投资有限公司（与外网宣称"鹏湾"不符，红线②实证）；外网称"批准152套/去化30%" vs 官方全业态 1116 套/已售97%（红线④实证）。

合肥专区（⭐ A 级 · www.hfzfzlw.com/spf · 2026-08-31 用户线索打通 · 纯 requests 可采）

• 域名订正（元级教训）：hfzfzlw.com 根路径 / = 住房租赁交易服务监管平台；/spf 子路径才是「合肥市房产市场信息平台」（商品房）。真实入口从局官网 zfbzfcglj.hefei.gov.cn 首页「重要业务系统」区取到 = https://www.hfzfzlw.com/spf。教训：一个域名下常挂多套业务系统，绝不能只看根路径标题就定性该域名"没有某类数据"——必须先从主管局官网取业务系统入口清单，再逐个子路径探。
• 可达性：/spf 系列 纯 requests 可达（200 / 无 WAF / 无瑞数 / 无验证码）。而政府主站 drc.hefei.gov.cn、zfbzfcglj.hefei.gov.cn 对沙箱 IP 全部 HTTP 521（加全套浏览器指纹 Sec-Fetch-*/Accept 仍 521 = IP 信誉封禁，非 UA 问题）。→ 破 521 的通用手法：用 WebFetch 通道读被封站（能通），requests 读业务系统（同域名不同子路径可能不封）。
• 模块清单（全服务端直渲，HTML 表格直接解析）：/spf/Permit 入网楼幢（预/现售证号·项目名·楼幢号·销售面积·发放日期·物业类型）／/spf/Project 入网项目（公司·项目·区域·地址）／/spf/HouseMarket 房源超市（项目·区域·企业·地址·电话）／另有 Bank Scheme Contract Homefund。
• ⭐ 逐套下钻（升 A 关键）：/spf/Permit 每行证号挂 /spf/details/<加密token>（token 就写在列表 HTML 的 href 里，随取随用，无需破解加密）→ 详情页即官方楼盘表：楼层 × 房号网格（层：7 → 701/702/703/704…）。
• ⭐⭐ 逐套单价 API 三步链（2026-08-31 完全破解，纯 requests，无需 CDP）——详情页静态 HTML 只有房号没有价，单价走异步：
  1. 楼盘表单元格 <td style="…background-color:XXX" onclick="s('房屋ID',1)">701</td> → 取 房屋ID（注意 onclick 在 td 开标签内，正则须匹配 <td[^>]*>.*?</td> 整段再搜，只搜标签内容会漏）。
  2. 数字替换 nscaler(id)：逐位映射 0→0 1→2 2→5 3→8 4→6 5→1 6→3 7→4 8→9 9→7（定义在 /spf/Content/js/Jquery.Query.js，不在 jquery.min.js 里，别找错文件）。
  3. GET /spf/details/getrsa/{nscaler(id)} → {"state":true,"id":"<RSA密文>"} → GET /spf/details/house/{密文} → 逐套 JSON。
  • 致命坑：house 端点的密文必须原样拼进 URL（保留 + / =）。做 base64url 转换（+→-、/→_、去 =）或 URL-encode 都会返回 {"state":false,"data":{}}。列表页 token 用 base64url 只是展示层风格，API 不吃这套。
  • 返回字段（A 级全套）：iPrice(备案单价元/㎡)、lbBuildArea/lbInsideArea/lbJoinArea(建筑/套内/分摊㎡)、lbHouseType(户型，如"三室户")、lbHouseUsefulness(房屋用途)、lbSellFlag(销售状态中文)、sellflag(状态码)、lbLocation(完整坐落，含行政区)、lbStructure、strTitle/lbPartNO(房号)。
  • 价格口径：前端仅对 sellflag ∈ {0,3,11,13} 显示 iPrice（与深圳同口径：可售类才公示价）；但 API 对其余状态也返回该字段（可能为空），须用「有价 vs 无价交叉表」实测占比后据实解读。
  • 色块图例（HTML 层，兜底用）：#0001fe可售 / #8a048x已签约 / #fd0002备案 / 已办产权 / 抵押可售 / #ffa500摇号冻结 / 已限制 / #cc660x限制销售 / #33cc99自建房 / 拆迁安置 / 抵押不可售。
• 规模：/spf/Permit 分页函数 listPager($(this), N) 末页 = 1583 页（每页 15 行 ≈ 2.37 万条证/楼幢），数据 T+1 更新（实测 2026-08-31 当日发放记录已在）。
• 坑：该站 UA 敏感——精简头（仅 UA + Accept-Language）返 200；加全套浏览器指纹（Sec-Fetch-*/Accept-Encoding 等）反 400。
• 已失效源（不必再试）：市发改委明码标价 drc.hefei.gov.cn/jggl/index.html 与 jggl/jggs/spzzmmbjcx/index.html 均 404 下线（2022-12 即有市民投诉无法访问，现首页便民服务区已无该入口，只剩粮油价格/CPI/民生价格）。
• 定级：C → A（官方逐套：单元级备案价 + 面积 + 销控状态 + 含区坐落），字段完整度优于郑州（仅单价）与深圳（仅待售有价）。
• 采集器：output_cross/collect_hefei.py（self-contained，两阶段 + 断点续跑）
  • --stage permits --max-page 1583 → hefei_permits.jsonl（全量证/楼幢底表，约 25 分钟，每页 15 行，?p=N 分页，默认发证日期倒序，p=1 最新、p=1583 到 2000 年）
  • --stage units --max-buildings 600 --max-units 30000 --workers 14 → hefei_units.jsonl（逐套；默认跳过车位/车库/地下室/储藏/人防类，加 --keep-parking 可保留）
  • 速度实测：14 并发约 14 套/秒（每套 2 次请求）；单个大型地下室可达 2273 房，务必设 --max-units 上限防跑飞。
  • 建表：output_cross/build_hefei_master.py → 7 sheet（房源明细/楼幢汇总/项目汇总/按区统计/统计分析/楼幢底表全量/数据说明）。⚠️ 性能铁律（2026-08-31 实测）：26k 行主档用 openpyxl 逐格 font/border 样式会触发 SIGTERM 超时（~360µs/格 × 49 万格 > 5min）；须改用 xlsxwriter（已装 3.2.9）流式写出（逐格写 format 极快，秒级）。坑：xlsxwriter write(row,col) 为 0 索引，而 for r,row in enumerate(data,start=1) 的 r 是 1 索引 → 合计行加粗须用 ws.write(len(data), c, …) 而非 len(data)-1，否则会覆盖倒数第二个分区行。
  • 现状（2026-08-31）：合肥主档已建 合肥_一房一价_主档_20260831.xlsx（房源 26,084 / 楼幢 601 / 项目 107，抽样=最新 600 楼幢逐套；楼幢底表全量 23,739）。
  • ⭐ 点名制实战案例（2026-08-31 用户点名 ①②③ 全跑）：build_hefei_cases.py 针对 hefei_target_permits.jsonl（筛项目名→全楼幢→逐套）出 合肥实战案例_三盘尽调_20260831.xlsx（逐套+楼幢去化+汇总对比+说明）+ …报告_20260831.docx。三盘真值（全量下钻，非主档抽样）：
    • ① 文渊府（政务区·青年公寓）：8 证 / 8 楼幢 / 2195 套，可售 1929、已售类 192、限制 74；去化率(总)12.1%、(审慎)9.1%；有价可售建面 39,562㎡、在售货值 ≈7.99 亿；备案单价 9,778~36,900、中位 12,278 元/㎡。→ 2026-08-14 新取证，去化刚起步。
    • ② 嘉宸雅园：24 证 / 24 楼幢 / 1943 套，可售 366、已售类 1436、限制 141；去化率(总)81.2%、(审慎)79.7%；有价可售建面 2,919㎡、在售货值 ≈0.77 亿；中位 26,323 元/㎡。→ 已近清盘，剩余可售多为未公示价车位+零星 19 套住宅。
    • ③ 汀云居（滨湖区·中高端）：16 证 / 16 楼幢 / 620 套，可售 376、已售类 192、限制 52；去化率(总)39.4%、(审慎)33.8%；有价可售建面 65,311㎡、在售货值 ≈19.09 亿；单价 24,004~37,006、中位 29,115 元/㎡。→ 去化中段。
  • ⚠️ 抽样 vs 全量（元级教训）：主档 项目汇总 的套数是最新 600 楼幢抽样的部分值——文渊府被抽中仅 1~2 栋→主档显示 604 套（实为 2195）；嘉宸雅园主档 816 套（实为 1943）；汀云居 620 套（巧合正好全中）。城市级主档只能看趋势，单盘真值必须点名制全量下钻。
  • ⚠️ 车位口径（与深圳同源）：合肥房信对「可售」车位不返备案单价——文渊府/嘉宸雅园可售中含大量未公示价车位（文渊府 1929 可售仅 440 有价）。故「有价可售建面 / 可售货值」只统计住宅·商业有价子集，车位库存仅以套数列于逐套明细（绿字无单价），勿把可售总套数当有货值库存。

贵阳专区（D 类 · 筑房网 www.gyfc.net.cn · 2026-08-12 深化）

• 两个匿名开放 API（无需登录、无反爬、JSON 明文）：
  • 列表：POST /api/gyzfw/open-api/certificate/list，body {"businessType":"ysz","current":N,"size":200}。
    • 全库 total=6245 条，按发证日倒序，翻页可回溯到 2017 年 → 不要只采当年（旧版误判"仅 2026 年 142 条"）。
    • ⚠️ 不支持任何关键词参数（实测 placeName/keyword/projectName/name/searchValue 均被忽略，仍返全库前 N 条）→ 必须翻页后本地过滤项目名。经验：size=200 时约 12 页可覆盖 2017 年以后全部。
  • 详情：POST /api/gyzfw/open-api/certificate/info，body {"acceptanceId":"<列表返回的受理号>","businessType":"ysz"}。
    • 返回 building(楼栋号)、preSellStart/preSellEnd(预售起止)、banks+accounts(监管银行与账号)、sellSummaryList[{useRange,count,area}]（分用途批准套数与面积）。
    • 端点名很挑：certificate/info 可用；certificate/detail、certificate/building/list、certificate/house/list 及 GET 形式全部 HTTP 500。
• 能拿到 / 拿不到：可拿 证级全量 + 栋号 + 分用途批准套数/面积（供应口径）；拿不到 逐套一房一价备案价（仅"贵阳住房"小程序登录态）。
• 口径红线：sellSummaryList 是预售批准量（供应），不是成交；外网网签是成交口径，两者不可相减推库存。
• 万科系主体识别坑：贵阳万科项目多由合营/平台主体登记预售证，企业名不含"万科"——万科麓山=贵阳广晟鑫德房地产开发有限公司、万科云翠隐秀=贵阳万新建设有限公司、万科锦上兰台=贵州融通小微企业金融超市管理有限公司。按企业名检索必漏，须按项目名/坐落匹配。
• 可复用脚本（output_cross/贵阳/）：probe_lushan.py（关键词参数探测+全库翻页过滤）、build_lushan.py（拉详情+7 Sheet 建表，含来源着色）。实测：万科麓山 17 本证（2019-07~2024-11）、批准 5628 套 / 581,876.52 ㎡。
• 交叉校验技巧：官方住宅批准套数（5316）vs 外网宣称总户数（约 5900）吻合度可用于背书外网体量数据的可信度；若二者差异 >30% 则外网口径可疑。
• web 9 盘清单 ≠ 官方真实在售盘（2026-08-12 万科贵阳实测）：web（安居客等）所称「万科贵阳 9 盘」中，仅 5 盘能在官方预售证系统检索到真实证级（麓山17/云翠隐秀10/锦上兰台4/都会印象13/观山甲第11 = 55 本）；另 4 盘官方库查无此盘——未来星光（阅山湖板块官方全为"中铁阅山湖"系）、未来溪地（花溪仅"万科花溪大都会"）、翡翠公园/鸣翠（官方"翡翠"全为"万科翡翠天骄"、老湾塘仅安置房）、新都荟（三马无"都荟"备案）。→ web 营销口径会高估万科官方在售盘数量，授信尽调须以官方证级库（全库 6245 条、含万科 167 本/53 个项目）为准。可复用脚本已升级：collect_vanke_all.py（全库翻页+8 盘过滤+info 拉取）、build_vanke_consolidated.py（5 盘整合+4 盘红旗+全览 6 Sheet）。

五类成功范式（跨城复用，按性价比排序）

1. 纯 requests 匿名 GET 链路（最干净）：西安三层 GET / 武汉五层 GET（⚠️ GB2312 编码坑：URL 中文须 gb2312 编码、响应 gb18030 解码、POST body gb2312）/ 郑州 Playwright 渲染列表 + requests 逐套。特征：政府站老式 aspx/jsp 页面，逐套数据明文返回。
2. 纯 requests 匿名 POST 接口：南京 webBuildingInfo / 重庆 GetRoomJson（ASP.NET PageMethod，POST JSON body）。
3. HTML 公示表/PDF 解析（政府"价格备案公示"栏目）：珠海住建局文章页 <table>（表头跨行，须定位含"房号+建筑面积"的表头行）/ 苏州发改委公示表（栏目列表 API 枚举 + 文本型 PDF，pdfplumber 直解，扫描版 PDF 宁可跳过不产脏数据）。⚠️ 苏州注意：此类公示往往是历史存量（2019–2022），非实时，交付前必须声明口径。
4. Playwright 拦截动态 token（深圳/成都基准）：Vue SPA + 动态 token，纯 HTTP 不可行 → page.on("response") 拦截 + 逐(楼栋,单元) POST。
5. 纯 requests 整栋表格：佛山 ajaxToGetHouseModel.do（body floorId=&buildingNo=）。

反爬/失真类型库（识别→对策）

完整类型表（16 类 + 瑞数攻坚专项）已迁出至 references/类型库.md 与 references/瑞数专项.md，主文档仅保留索引，避免重复维护。下表为速查入口：

想查	去处
反爬类型全表（瑞数/顶象/阿里云/PNG/小程序/关键词忽略等 16 类）	references/类型库.md 二、反爬类型速查
瑞数/政窗动态 token 识别与 Playwright 应对（含上海攻坚）	references/瑞数专项.md
WAF 终极兜底 · CDP 复用真实浏览器（2026-08-22 深圳验证）	本文件「CDP 复用真实浏览器」专章
城市分类 A–E、状态码图例、数据质量校验	references/类型库.md 一、三、四

瑞数攻坚专项（2026-08-11 上海二次攻坚完整经验）

用户指示：用更强模型逐个攻破 E 类城市，一步步积累经验。上海为首个试点，结论：E 类维持，瑞数在当前 headless 沙箱不可绕过。本文档记录完整方法，供未来（非沙箱/独立IP/真 JS 逆向）再战。

已实测失败的路线（上海，2026-08-11，全部折戟）：

1. 纯 requests / curl：412（瑞数拒绝未执行 JS 挑战的请求）
2. Playwright Chromium headless（--disable-blink-features=AutomationControlled）：412→加载瑞数 JS(200)→二次请求 400 空页
3. playwright-stealth（Stealth.apply_stealth_async）+ enhanced fingerprint（navigator.webdriver→undefined、plugins、chrome.runtime、permissions hook、移动端 UA、headless=False 回退）：同样 412→400
4. 页面内 fetch API（拿到 412 挑战 cookie 后仍 502/400）；20+ 常见 API 端点枚举：全 412
5. 关键证据：瑞数 JS 执行后设置的 cookie（如 UA1L1zGonajvO httpOnly + UA1L1zGonajvP）被服务端判定为无效——说明挑战不只校验 cookie 存在，还校验浏览器真实指纹（canvas/WebGL/音频/时序等非标准特征），stealth 补丁深度不够

判定瑞数封锁等级的"411 速查"：看 412 响应体大小——

• ~60KB：首次挑战，实际页面内容仍在响应里（可解析静态链接）
• ~3KB：纯挑战页（只含 meta + $_ts.nsd/$_ts.cd 编码数据 + 混淆 JS），说明 WAF 已对该 IP 升级封锁
• ⚠️ 一旦出现 ~3KB 形态，立即停止试探（越打越严），换 IP 或数小时后再试，或直接定性 E

有用的替代数据源（上海案例，证级兜底）：

• fgwapp.fgj.sh.gov.cn/hudong/xuke/home/ysxk?pageNo=1&pagesize=20&testpara=0：无瑞数保护，requests 直连可拿全市 11342 条预售许可证（项目名/企业名/地址/证号/发证日期），支持 ?name= 搜索。可做「证级清单」Excel（济南模式），但没有一房一价
• data.sh.gov.cn 开放数据平台：有「商品房预售许可证信息」数据集（9036 条，无条件开放，CSV/JSON/XLSX），但也在同一瑞数 WAF 下，API 与下载全 412
• 外网聚合：fangqingbao.com（房情宝）聚合 fangdi 公示摘要（证级+备案均价）；房天下 m.fang.com/xf/business/houseprice/sh/{project_id}/ 有一房一价页但需登录

下次再战的可行路线（未尝试/需环境）：

1. 真 JS 逆向：抓取混淆 JS（~200KB），用 Node 补环境（mock $_ts、document、canvas/WebGL 等）生成有效 cookie——需要 reasoning 级模型 + 大量调试时间，成功率中等，且瑞数版本更新后 cookie 算法会变（维护成本高）
2. 非沙箱 headed 浏览器 + 独立住宅 IP：在用户本机跑 Playwright headed（不 headless），配合干净 IP，瑞数误判率大幅下降——性价比最高的路线，可列入用户本机一次性协助
3. 政务侧深挖：同城其他局委域名（fgwapp/zfzl 等）逐个试，找无瑞数保护的证级/租金数据兜底

攻坚 SOP（再战时按此执行，bounded 尝试后即定性）：

1. 抓 412 响应体 → 记录 meta id + 响应体大小（判断是否已升级封锁）
2. 拦截挑战 JS → 尝试 Node 补环境执行生成 cookie（1~2 次 bounded 尝试）
3. Playwright stealth + enhanced fingerprint 全量测试（含 headless=False、独立 UA 轮换）
4. 若 3 步全败 → 按「替代数据源」拿证级兜底 → 定性 E，写 status.txt，不无限对抗

🆕 2026-08-22 重大更新：路线 2「非沙箱 headed 浏览器 + 干净 IP」已在深圳通过 CDP 复用真实浏览器 方案验证成功（730 项目 / 49.5 万套 / 0 失败）。今后任何城市 Playwright 直接 launch 被 WAF 拦（瑞数/腾讯云等 JS 挑战），一律先上 CDP 方案，见下节。

🔒 用户强约束 · 数据时间范围（2026-08-24 确立）：用户只看近 ~10 年数据（顶多往前 10 年），远久年份的盘基本不关心。触发规则：任何"跑数/采集/分析"任务，若目标涉及取证/建成/上市年份较早（如 ≤2015）或整体数据有明显时间排布，必须先暂停并提示年份分布（如"730 项目里 ≤2009 老盘占 1295 个、2020+ 仅 0 遗漏"），由用户决定跑全量还是只跑近十年，不得闷头全跑。延伸到：① 全量采集前先出"按年份分桶"概览；② 老盘（>10 年）默认提示可跳过；③ 衍生表/报告默认只呈现近十年，老盘单列或省略。

韧性采集器必须设「连续退避封顶」——防无限空转（2026-09-03 东莞实战）

症状：采集进程跑了几十小时、CPU 近乎为零、日志反复刷 [退避] 限流, 静默冷却 3600s， 数据文件 mtime 一动不动 → 不是"在慢慢采"，是死循环假活。 东莞实况：进程自 2026-09-01 17:36 空转至 09-03 10:48（40+ 小时）， 期间 dongguan_permits.jsonl 零新增，日志 44 行里 40 行是第 4 阶退避。

根因：退避序列 BACKOFFS=[600,1200,1800,3600,3600] 走到最后一阶后没有退出条件， backoff_sleep() 永远 sleep 最后一档再重试 → 只要站点不恢复就无限循环。

定性判据（速率型限流 vs IP 级持久封禁）：退避期间已做到零请求仍连续多次失败 （如连续 6 次、累计冷却 4 小时无一次成功）→ 就是 IP 级持久封禁，再等也没用， 必须换出口 IP / 隔日再试 / 改人工渠道，绝不能靠加长退避解决。

强制写法：全局 _consec_boff 连续退避计数，成功即复位；达上限写 *_blocked.flag （记录 blocked_at / reason / resume 页码）后 sys.exit(3)，把决策权交回人工：

python

MAX_CONSEC_BACKOFF = 6   # 连续退避上限(≈4 小时无任何成功请求)
def backoff_sleep():
    global _boff, _consec_boff
    _consec_boff += 1
    if _consec_boff >= MAX_CONSEC_BACKOFF:
        # 写 blocked 标记 + sys.exit(3)，不再无限占位
        ...
def ok():
    global _boff, _consec_boff
    _boff = 0; _consec_boff = 0   # 成功一次即全部复位

巡检习惯：排查"自动化卡住"时，先 ps 看有没有起跑时间异常早的 python 进程， 再对比日志 mtime 与产出文件 mtime —— 两者背离（日志在动、数据不动）= 假活，直接终止。

CDP 复用真实浏览器（WAF 终极兜底 · 2026-08-22 深圳验证成功）

结论：WAF（瑞数系/腾讯云 JS 挑战）会拦截 Playwright 直接 launch 的浏览器——headless/headed/指纹伪装（webdriver 覆盖、stealth 补丁）全被识别，页面停在挑战阶段不发业务请求（特征：请求里只有随机路径混淆 JS + 动态时间戳参数，页面标题/内容为空）。终极兜底通路 = CDP 复用用户手动打开的真实浏览器会话。

🔴 2026-09-03 重要修正（优先级高于上段，先试这个再上 CDP）：「唯一通路 = CDP」已被证伪。 深圳实测：裸 chromium.launch(headless=True) 拿不到 cuyGLa6e token（脚本只能报错退出， 底数自动化因此静默停更 15 天，表现为"自动化卡住"）；但仅加一个启动参数 --disable-blink-features=AutomationControlled（配 --no-sandbox）后 headless 一次即拿到 token， 底数重采 4,417 证 + B1 逐套拦截房源 API 全部成功，全程无需 CDP、无需真实浏览器。 新默认顺序：① 裸 launch 失败 → ② 加 --disable-blink-features=AutomationControlled 重试（必做，成本近乎为零） → ③ 仍失败才上 CDP。此前把②跳过直接判"必须 CDP"，是本次 15 天停更的直接原因。 完整参数（与已验证的 collect_shengyue_token.py 对齐）：

python

browser = await p.chromium.launch(
    headless=True,
    args=["--disable-blink-features=AutomationControlled", "--no-sandbox"])
ctx = await browser.new_context(viewport={"width": 1920, "height": 1080}, user_agent=<桌面 Chrome UA>)

⚠️ 排障提醒：token 拿不到时先比对启动参数，不要误判为"引导页项目选错"——本次曾依次怀疑 "底数第一条 / 最新发证 / 在售活跃证"三种选证策略，全部无效，真正变量自始至终是启动参数。

识别特征（触发 CDP 方案）：① Playwright 全模式拿不到业务 token；② 页面标题空、body 空；③ 请求列表出现 /<随机串>/<随机串>.js 混淆脚本 + ?xxx=时间戳 动态参数 → 直接上 CDP，不要继续试其他 launch 模式。

三步操作（用户本机）：

1. 开真实浏览器：1_启动浏览器.bat（自动探测 Chrome/Edge，--remote-debugging-port=9222 --user-data-dir=chrome_profile 打开目标页面）。关键检查：页面必须能显示内容（眼睛能看 = WAF 放行真实浏览器）。
2. 脚本借用会话：connect_over_cdp("http://127.0.0.1:9222") → ctx.pages[0] → req = page.request（页面级请求上下文，带会话 Cookie——这是能过的关键）。
3. 主动 POST 枚举采集（不要等 SPA 响应）：监听 page.on("request") 抓 cuyGLa6e token 后，主动构造 POST 到 projectPublish 三个枚举接口——getProjectDetailInfoToPublicity（证级均价）→ getBuildingNameListToPublicity（楼栋）→ 逐栋 getBuildingDictToPublicity（单元 gnqmcList）→ 逐单元 getHouseInfoListToPublicity（房源），逐证/逐栋/逐单元枚举。⚠️ 绝不等 SPA 前端自发请求——WAF 升级后 SPA 被重定向到 tamperUrl.html、不再发业务 API，必须脚本主动打后端（与下节「token 直连枚举法」同款内核）。每项目完成即落盘。

关键坑（全部实测踩过）：

• 🔴 浏览器路径：企业版/用户级 Chrome 装在 %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe，不在 4 个标准 Program Files 路径——探测必须含 LOCALAPPDATA + 注册表 HKLM:\SOFTWARE\Clients\StartMenuInternet。
• 🔴 MSYS 参数转换：Git Bash 里 shutdown //s 被 MSYS 破坏不生效，须 cmd //c "shutdown /s /t 60" 或 PowerShell 调用。
• 🔴 沙箱限制：schtasks / Start-Process 在 WorkBuddy 沙箱被安全策略禁 → 自动关机用 Bash watcher + PowerShell shutdown /s /t 兜底。
• 🟢 断点续跑：每项目完成立即追加 summary.jsonl，重启自动跳过 OK 项（脚本重启即可续，不怕中途断网/关浏览器）。
• 🟢 速度：CDP 复用真实浏览器比 Playwright launch 更快（深圳实测 5.7 项目/分钟，token 复用会话）。

模板脚本（深圳已固化，可改清单复用）：1_启动浏览器.bat + cdp_rerun.py（小批量/单项目）+ collect_all_b1.py（全量清单、断点续跑、节流、失败容忍）。落盘格式与普通枚举版一致。

失真项目枚举重采三件套（2026-08-27 深圳闭环 · 修正 B1 首屏失真）

B1 全量快照（collect_all_b1.py + fetch_house_data.py）只拦首屏一次房源 API、未枚举单元 → 系统性失真（如白石洲仅 453 套/1 单元，漏 2293 套/84%；珑瀚曾误报 3/366）。以下三件套改用 CDP 逐单元枚举全量，可信度=A 权威全量。

脚本清单（工作区根目录，可改清单复用）：

• gen_recrawl_config.py：从 B1 失真扫描结果生成 recrawl_permits.json（73 项目 / 120 证，含 ysProjectId/preSellId）。
• collect_shenzhen_enum.py：73 失真项目通用 CDP 枚举重采器（连本机 9222 真实 Chrome）。⚠️ 致命 bug 已修（2026-08-27）：原 if not tk: break 遇 WAF 抖动会终止整轮 → 改 continue（单项目失败跳过续跑，不中断其余）。补采用 --only <项目名子串> 逐个跑可绕过。
• collect_baishizhou_full.py：绿景白石洲璟庭专属全量枚举（2746 套/5 单元）。⚠️ 须 CDP 连 9222：原 launch(headless=True) 必被 WAF 拦（实测 token=None）→ 已改为 connect_over_cdp(CDP_URL)。
• build_shenzhen_enum_master.py：合并所有 raw_*_full.json → 深圳失真重采主档_YYYYMMDD.xlsx（房源明细 + 项目汇总 + 数据说明），openpyxl 审计。

🔑 深圳 CDP 采集三铁律（2026-08-27 实测提炼）：

1. 采集前必查杀遗留 collect_all_b1.py 僵尸进程：其挂起会占满本机 Chrome CDP(9222) 资源，致 connect_over_cdp 超时 180s、新采集全卡。先 tasklist|grep collect_all_b1 → taskkill /PID /F /T 清理再跑。
2. enum 脚本 if not tk: break 必须改 continue：WAF 偶发抖动使单项目拿不到 token，break 会让整轮 73 项目只跑部分（昨夜 64/73 退出即此因）。
3. 专属脚本勿 launch headless，一律 CDP 连 9222：深圳房信 WAF（瑞数系）2026-08 已封死 headless 指纹，连 token 都拿不到；CDP 复用本机真实 Chrome 会话是唯一稳定通路。

WAF 挑战下的 token 直连枚举法（轻量兜底 · 无需 CDP · 2026-08-24 深圳验证）

结论：深圳房信平台对 headless 浏览器发起 WAF/反爬挑战时，SPA 的 user/initSession 会返回 needtoken=true 并被重定向到 tamperUrl.html，导致 SPA 不再自发触发业务 API（getProjectDetailInfoToPublicity / getHouseInfoListToPublicity 等根本不发出）——表现为"首屏未捕获房源 API"、"页面标题/body 空"。但实测证明：WAF 只拦了 SPA 的会话流程，没拦带 token 的直连枚举接口——headless 页面下发的 cuyGLa6e token 对三个枚举接口直连 POST 完全有效。因此可用 「headless 取 token → page.request 直连枚举」 绕过 SPA 会话挑战，无需开真实浏览器、无需 CDP。

触发识别（优先于 CDP 尝试）：⚠️ 2026-08-27 更新：深圳房信 WAF 已封死 headless 指纹，launch 连 token 都拿不到，本法已失效——直接走下方 CDP 方案。

• Playwright 直接 launch 后，SPA 资源能加载（412/200），但 page.on("response") 只看到 user/initSession→needtoken=true→tamperUrl.html 重定向，业务 API 从不被触发；
• 同时 headless 上下文仍能拿到 cuyGLa6e token（出现在任意 Publicity 请求 URL 的 query 里）→ 先试本法，省去 CDP 开真实浏览器的步骤（用户本机动作）。

三步操作（2026-08-24 晟悦家园实跑闭环，一次跑通 616 套全量）：

1. headless 启动 + 抓 token：chromium.launch(headless=True, args=["--disable-blink-features=AutomationControlled","--no-sandbox"])，开 page.on("request", h) 拦截任意 cuyGLa6e= URL，正则 cuyGLa6e=([^&]+) 取出 token（SPA 即使被重定向，token 仍在首次请求的 URL 里下发）。
2. page.request 直连枚举（与 CDP 同款 token 机制，但用 page.request 而非 CDP 会话）：
   • POST {BASE}/getBuildingNameListToPublicity?cuyGLa6e={tk}（body ysProjectId=&preSellId=）→ 拿 5 位 key(fybId)
   • POST {BASE}/getBuildingDictToPublicity?cuyGLa6e={tk}（body 含 19 位 buildNo）→ 拿 gnqmcList(单元名)
   • 逐单元 POST {BASE}/getHouseInfoListToPublicity?cuyGLa6e={tk}（body {"buildingbranch":单元名, "fybId":5位, "status":-1, ...}）→ 房源
   • BASE=https://fdc.zjj.sz.gov.cn/szfdcscjy/projectPublish；枚举逻辑与 collect_longhan.py 同款（5位/19位关联、单元名原样传）。
3. 落盘 + 复用 8-Sheet 管道：枚举得到的 houses 直接喂给既有 generate_excel（项目名/预售证/外部价均按项目覆盖，避免跨项目污染），产出与 SOP 完全对齐的 Excel。

与 CDP 方案的关系（决策次序）：

• 本法（headless token 直连）最轻量，优先尝试；胜在无需用户手动开真实浏览器。
• ⚠️ 2026-08-27 实测更新：深圳房信 WAF（瑞数系）已封死 headless 指纹——launch(headless=True) 连 cuyGLa6e token 都拿不到（白石洲实测 token=None，7.9s 退出）。因此 headless 直连法已失效，CDP 复用真实浏览器（上节）成为唯一稳定通路，不再作为"优先轻量"选项。
• 两者共用同一套「逐(楼栋,单元)枚举 + token」内核，区别仅在 token 来源（headless 页面 vs 真实浏览器会话）。

🔑 通用铁律（两种方案共用 · 2026-08-24 提炼）：无论 token 来自 headless 页面还是 CDP 真实浏览器会话，拿到 token 后一律主动 POST projectPublish 三个枚举接口做逐(楼栋,单元)枚举，不要依赖 SPA 自发请求。WAF 升级后 SPA 会话流程被卡（initSession→needtoken→tamperUrl.html），但带 token 的直连枚举接口仍放行——这是深圳（及同类 WAF 城市）采集的唯一稳定内核。

可复用脚本：工作区 collect_shengyue_token.py（晟悦家园实跑版，616 套全量抓全、8 Sheet 校验通过）已沉淀此模式；后续新项目只需替换 PERMITS(ysProjectId/preSellId) 与 PROJECT_NAME 即可复用同一套直连枚举逻辑。完整踩坑与代码见 references/cases/深圳-晟悦家园-WAF挑战token直连枚举.md。

安居型商品房（保障房）去化核实标准路径（2026-08-24 山樾湾花园实战）

核心盲区：政府平台（深圳 fdc.zjj.sz.gov.cn 等）对安居型商品房的房源状态只标 「安居房」 一个聚合标签，不区分"已签约配售"与"待配售"——因此单套去化率平台层面算不出来，也不能默认"已售"或"未售"。普通商品房的 8-Sheet 去化/货值管道若直接套用会失真（把安居房误判已售 + 被商业异常值拉爆均价）。本项目必须切换安居房适配口径 + 走住建局官方配售批次线交叉印证。

⚠️ 触发条件（满足任一即走本路径）：

• 项目用途/状态大量为"安居房 / 共有产权房 / 公租房"等政策性住房；
• 用户问"平台显示安居房，到底卖没卖完 / 能不能确认是否售出"；
• 授信尽调涉及保障房项目去化与货值。

四步核实法（标准路径）：

1. 平台采集走安居房适配口径（勿套普通商品房管道）：

   • 把"安居房"从 SOLD_STATUSES（已售类）剥离开，单独成列，不计入审慎去化；
   • 单套配售明细价平台不公开（askpricetotalB/askpriceeachB 全 null）→ 价格字段不做回算，标注"政府定价不公开·不测算"；
   • 货值仅测算有真实价的"期房待售"等市场化房源，安居房标注"不测算"；
   • 注意：证级备案均价（getProjectDetailInfoToPublicity.averagePriceTotal）平台是公开的（约 4.4 万/㎡量级），与"单套明细价不公开"不矛盾，须在「预售许可证清单」Sheet 如实填证级均价，避免口径矛盾；
   • 交付物结构仍保持 6~8 Sheet（房源明细/统计分析/预售许可证清单/剩余货值测算/分析总结/异常与告警），但口径修正。

2. 住建局配售批次线交叉印证（硬证据来源）：

   • 检索 区住建局"安居型商品房配售通告"（命名如 住保售〔2026〕0xx号），定位点名本项目的批次；
   • 每批次通告含：本批次房源总套数、户型分布（两房/三房各多少）、认购申请起止、选房安排；
   • 认购期内的批次 = "待配售/未售出"的硬证据（证伪"安居房=已全部售出"）。

   ⚠️ 关键铁律（2026-08-24 山樾湾外网复核教训）：安居房项目常是跨年度、多批次（甚至月度）连续配售，绝不能只查最近一两个批次就下"去化率"结论。 ① 批次序列必须从项目首开年份拉全，不得从中间年份起算。山樾湾实战：用户凭记忆说"去年就开始卖了"，外网复核证实其配售自 2024 年即已开售（四批次）——第一批次 2024-03（房源 2310 套·已定位 post_11217682·逐套校验两房613/三房185=798套·A）、第二批次 2024-05（住保售无文号·310 套·A）、第三批次 2024-06（无文号·95 套·A）、补充批次 2024-09（无文号·25 套·A）；2025 下半年至 2026 上半年继续有一连串月度批次（015→027→030→040→054→008→021→031→059→064）。2023 年核查无配售批次证据（安居房 2023-08 闭库、2023-04 停土地出让，检索结果均指向 2024-03 为最早批次）。 ② 跨年度回查、把全年批次序列拉全，再按"已选定/认购中/待配售"做分批次进度表。山樾湾实战：2024 补全后 A 级累计 1910→2340（13 批）；2026-08-25 第一批次(post_11217682)补齐后 → 3138 套（14 批），去化率(A级) 64.0%，含 D 级（064 认购中）上限 95.9%。若只查 059/064 两批会严重低估去化。首开年份必须按"项目最早批次年份"而非"用户提到的年份"确认——用户记忆常滞后于实际开售时间。

   来源分级标注规范（强制）：安居房批次数据可信度差异极大，交付物必须按级着色+标注：

   • A 级＝官方选房结果公示 xlsx（已下载逐套校验）或官方公示页面披露汇总数（最可靠）；
   • D 级＝认购期内尚未选房（如 064 批次，认购中）。
   • ⚠️ 不再保留 C 级残留：自媒体（深房驿站等）月度汇总只是"初筛线索"，发现后必须逐一回查官方公示页 + 下载 xlsx 逐套校验，能升则升 A、对不上则以官方校正，最终交付物不应留有未升的 C 级（除非官网确无独立公示且时间边界内无法获取——此时须显式标注"待查"而非笼统 C 级）。
   • 去化率以全 A 级口径为主数字（山樾湾当前 64.0%·A 级已选定累计 3138 套 / 14 批）；另给含 D 级认购中的上限（95.9%·含 064 批次 1563 套）提示时间边界。
   • ⚠️ 配套交付物必须同步收尾（2026-08-24 第二次虎头蛇尾教训）：进度表（Excel）与交互看板（HTML）是一对同源交付物，凡改动批次数据/来源级/去化率口径，两者必须同轮重出、数字与色块完全一致，不得只改 Excel 漏改看板（或反之）。看板卡片数字、表格来源色块、累计行、口径声明须逐项对齐 Excel 实测值。

   C 级清零实战（2026-08-24 山樾湾）：

   • 初查时 2025-09/10、2026-01/02/03/04 共 six 批为自媒体 C 级；逐一回查发现：① 2025-09 文号实为 住保售〔2025〕027号、2025-10 文号实为 住保售〔2025〕030号（并非"无文号/034号预审"，此前误记）；② 2026-01=054号、03月=008号（自媒体把 008 一批拆成"2月391+3月196"）、04月=021号。全部下载官方 xlsx 逐套校验后，六批全部升 A，C 级清零。
   • 升 A 的前提：必须抓到该批次官方「选房结果公示」页 + 下载"已选房源"xlsx 逐套筛 状态="已选定" 核对数字，不是改标签。自媒体汇总常有：① 把预审/补选混入正式批次；② 跨月合并或拆分；③ 数字四舍五入误差（054 官139 vs 自142、021 官196 vs 自164）。
   • 实测教训：① "已选房源"xlsx 表头常在第 2 行（第 1 行是大标题），状态列多为第 7 列；② 同房型多场次（如上午场+下午场）"已选房源"表，取最后一场次（最终状态）而非累加——008 号两房上午场151+下午场345，下午场表已是最终状态，合计取 345（与官方 391 吻合）；③ 自媒体与官方差 3~32 套属常态，以官方为准。

3. 选房结果公示 xlsx 提取实际签约套数（去化硬证据）：

   • 每批次配售结束会发 「选房结果公示」，含 4 个 xlsx 附件：两房/三房 × 选房结果 / 已选房源；
   • 在 「已选房源」文件里筛选 状态 列 = "已选定" 的套数 = 本批次实际签约去化（如山樾湾 059 批次：房源池 1654 套 → 已选定 112 套，选定率 6.8%）；
   • 双重交叉校验：同批次「选房结果」文件里的"选定项目=本项目 且 有选定房号"计数，须与「已选房源」"已选定"计数一致（山樾湾两文件均确认 112 套 ✅）；
   • 下载附件用 curl 直链（通告页附件 URL 规律：.../attachment/1/<分段>/<id>/<通告id>.xlsx，文件名在 download= 属性）。
   • ⚠️ 定位官方公示页技巧（2026-08-25 实战·可复用）：深圳南山住建局 gkmlpt 文章页对不存在的 post 也返回 200 + <title>出错了</title>（软404），故不能靠 HTTP 状态码筛真页，必须 grep <title> 是否含项目关键词；post ID 路径段号 = ID 截前 5 位（如 11217682→11217、11298183→11298）；真实 post ID 零散非整百，须步长 1 扫描 + 并发(xargs -P 40)，按日增量（约 1640/天）估算窗口后收敛。山樾湾第一批次即以此法从 1121xxxx 区间定位到 post_11217682。

4. 查封用途隔离判断（授信关键）：

   • 平台"司法查封"状态逐套标用途——务必核查封房源的 useage 字段：山樾湾 91 套司法查封全部为"商铺"（商业配套），0 套住宅/安居房；
   • 结论：查封风险与保障房本体隔离，不侵蚀安居房房源池；若授信涉及商业抵押须对商铺逐套查册核债权顺位。

进度上限与时间边界：

• 认购期未截止的批次（如 064 号认购至 2026-09-01）选房结果尚未发布，检索 065+ 批次无公开记录 → 官方渠道当前时点配售进度已到天花板（时间未到，非遗漏）；
• 须提示用户：剩余房源待后续批次选房结果公示后复查（建议在认购截止后复查）。

产物要求：

• Excel 保持安居房适配版（6~8 Sheet），口径按上述修正；
• Word 简报须含「官方渠道交叉印证」章节，列明批次线 + 实际选定套数 + 查封用途隔离结论；
• 来源标注：[A类·官方] 区住建局住保售〔2026〕0xx号通告及选房结果公示 xlsx + [A类·官方] 市房地产信息平台房源状态（采集日）；
• 生成独立的司法查封房源逐套查册清单 Excel（房号/面积/用途 + 待填查册字段），供用户持权到不动产登记中心办理（政务系统本环境不可直调）。

可复用脚本：工作区 build_shanyuewan_report.py（安居房适配版 8-Sheet 生成器，含 CDP 补采证级均价 + 安居房口径修正）；交叉印证 xlsx 解析逻辑见 output_cross/shenzhen_all_units/shanyuewan_cross/。完整案例见 references/cases/深圳-山樾湾花园-安居房去化核实.md。

🔑 安居房核实铁律（2026-08-24 提炼）：① 平台"安居房"标签不可信为去化率，必须走住建局配售批次线闭环；② 实际签约去化 = 选房结果公示「已选房源」文件"已选定"计数（双文件交叉校验）；③ 查封须逐套核用途，商铺查封 ≠ 安居房查封；④ 普通商品房 8-Sheet 管道禁止直接套保障房，必须切安居房适配口径。

探测 SOP（新城市快速定性，每次 bounded 尝试后即定性，别死磕）

📋 填表式落地模板：本 SOP 的逐城执行请配套使用 references/城市接入checklist.md（六步填表：基本信息→入口→反爬识别→API探针→字段映射→脚本固化→收口），避免口述走样、漏步。

1. WebSearch 确认官方入口（住建局/房管局/发改委 gov.cn，域名常变、以实测为准）。
2. 按"五类成功范式"顺序试：纯 GET 链路 → 纯 POST 接口 → HTML/PDF 公示表 → Playwright 拦截 → 整栋表格。
3. ⚠️ 先探"政务服务网/行政审批局证照查询 API"，再下"无官方数据"结论（济南教训）：住建局门户可能只有"公告"（项目级），但同级政务服务网常有「商品房预售许可证查询」类匿名 POST API（如济南 zwfw.jinan.gov.cn/jpaas-jiq-web-jnywtb/front/info/searchspfys，body holderName/queryType/certificateDate），返回预售证级 JSON（证号/楼栋/日期/地址）——虽无逐套，但可证级全采、按楼栋核对推广信息。下"无制度基础/无数据可采"结论前，务必探政务服务网查询接口。
4. 命中即固化 extract_<city>.py + 落 output_cross/<city>_data/houses.json（统一结构：city/source/anonymous/captured_at/house_count/projects[]，逐套字段用中文键名）。
5. 未命中按反爬库识别类型 → 定性 D（需用户）或 E（反爬/不可达），写 status.txt（结论+证据+数据量）。
6. 一次性人工协助可商量，持续性一律放弃（用户明确规则）：装 Tesseract/本机跑 IP 受限脚本这类"一次性本机动作"可列给用户；小程序/扫码/每日登录属"持续性"不纳入。

交互式 HTML 看板（2026-08-11 新增，探数数三层整合）

把「房源明细 Excel」升级为自包含 HTML 交互看板（Chart.js CDN，可离线打开/演示/发给客户）。 一次开发长期复用：换数据源即重生成。晟悦家园已落地 build_chengyue_dash.py → output/晟悦家园_交互看板_*.html。

⭐ 产出约定（2026-08-11 用户明确）：日常单项目检索，产物固定为「Excel + 交互看板」双件套（Excel 作正式存档/授信依据，看板作演示/自助探索），两者都要生成；跨城对比大屏等综合性看板仅少数综合场景才做（如全国覆盖汇报），不要默认给每个项目做大屏。看板已覆盖 Excel 全部 Sheet 内容（含剩余货值/预售证/对比/告警/外部验证/总结），单文件即可独立交付。

产出形态：单文件 HTML，含 6 图表 + KPI 卡片 + 质量校验表 + 梯度分析表 + 可排序分页明细表，楼栋/状态/用途三筛选联动（多项目 Excel 自动加「项目」筛选）。

三大增强层（探数数·data 专家框架）：

1. 可视化层：状态环形图 / 楼栋×状态堆积柱 / 单价直方图 / 面积直方图 / 楼栋均价柱 / 楼层-单价散点图（楼栋分色）
2. 数据质量校验层：重复房源检测 / 空值率 / 面积异常（>2x 或 <0.5x 中位数）/ 单价异常（z>3）/ 总价≠单价×面积 偏差>1% —— 自动输出「质量表」
3. 统计层：每楼栋「楼层-单价」线性回归（斜率=每层价格变化元/㎡、R²=拟合优度，样本≥4 层）——可快速识别定价策略（R² 高=严格按楼层定价；R² 低≈均一价）

复用要点（通用版 build_house_dashboard.py）：

• 用法：python build_house_dashboard.py <Excel路径> [项目名] —— 任何项目一条命令出完整看板（晟悦家园/深润川已验证）
• 自动探测表头行（含「房号」那行）+ 动态列映射（项目/预售证/楼栋/楼层/用途 15 列）+ 动态状态配色（非硬编码 4 种）+ 多项目四筛选
• 剩余货值兼容两种结构：合并汇总块（晟悦，值在 col6 index=5）/ 行级表（深润川，识别「主口径货值(万元)」列 ×10000 转元）
• 楼层字段是 str（如 "46"），须转 int 否则梯度分析为空（已踩坑）；深润川全无备案价公开时价格图/梯度为空属正常
• Chart.js histogram 类型不存在，须用 bar
• 脚本固化于 skill/scripts/build_house_dashboard.py

"无逐套"城市的信息整合 Excel（济南模板，D 类城市复用）

用户 2026-08-11 明确："无逐套备案价"≠"没信息没 Excel"——把政府官网能拿到的尽可能提取（哪怕证级），再辅以外网（贝壳/安居客/房天下等）补房源与价格，合成带来源标注的 Excel。

跨城对比大屏（2026-08-11 新增，少数综合场景用）

全国 33 城覆盖能力的综合展示（向领导/客户汇报全国版图时用）。⭐ 用户 2026-08-11 明确：综合大屏属少数场景——日常单项目检索一律走「Excel + 交互看板」双件套，不要默认做大屏。

实现：skill/scripts/build_cross_dashboard.py → output_cross/全国33城房源采集对比大屏.html（18KB 自包含）。

• 内容：33 城全量（分类 A10/B2/C1/D12/E8、区域、套数、入口、状态、备注、下一步）+ 分类 KPI + 分类分布环形图 + 采集套数柱状图 + 分类/区域/关键词三筛选 + 可排序分页表
• 数据源：27 城状态报告 + skill 分类（改 CITIES 数组即更新）
• 触发场景：全国覆盖汇报 / 跨城对比分析 / 展示采集方法论体系

模式（济南·观山隐秀已落地，脚本 build_jinan_excel.py，产出 6 Sheet）：

1. 官方侧尽力提取：政务服务网证照查询 API（证级 JSON）→ 「官方预售证清单」Sheet；住建局门户公告/开放数据 → 可采即采。
2. 外网侧 8 源交叉：房天下/安居客/贝壳（详情页，CAPTCHA 拦则用搜索摘要）/克而瑞/乐居/百度AI摘要等，补户型/单价/总价/去化/竞品 → 「户型与价格」「销售与去化」「竞品对比」Sheet。
3. 来源标注规范：每条数据旁加来源列——官方 [官方·政务服务网 2026-08-11]（浅绿底），外网 [外网·WebSearch 2026-08-11]（浅黄底）；颜色编码一眼区分。
4. 口径声明必写：外网价为挂牌/参考/成交口径、非政府备案价；多平台合并展示同一项目（安居客把 C3 与 C1/C2/C4 合并）时须以官方证级为准甄别；「数据来源说明」Sheet 列全渠道（渠道/URL/用途/可信度）。
5. 参考实现：output_cross/jinan_data/济南观山隐秀_房源信息整合_20260811.xlsx + build_jinan_excel.py。

外部价格整合与货值测算（脚本化 · price_integration.py）

D/E 类城市官方多只公开证级、逐套/备案价锁登录或无制度，平台不公开价。把"外网补价"程序化为可复用能力，让这类城市也能做去化/折扣率/货值量级分析（济南模式的可复用升级）。

流程：

1. 外网价采集（Agent 执行）：WebSearch 抓贝壳/安居客/房天下/乐有家/吉屋等 → 落盘 external_prices.json（结构见 scripts/price_integration.py 文件头：records[{channel,type,desc,area,unit_price,total_price,date,url,note}] + search_date/city/tag）。
2. 官方证级：用既有采集器/工厂拿证级 JSON（projects[]）。
3. 脚本整合：python price_integration.py --prices ext.json --permits permits.json --out out.xlsx → 多 Sheet（官方证级绿底 / 外网补价黄底 / 价格对比与货值 / 数据来源说明），自动按项目名模糊匹配并算折扣率(外网/官方)、货值估算(外网均价×批准面积)。
4. 口径声明强制：外网价=市场挂牌/成交价、非政府备案价，仅作量级参考；折扣率仅在官方有备案均价时计算（D/E 多为 None）；供应≠成交，不可相减推库存。

• 来源着色：官方绿底 C6EFCE / 外网黄底 FFEB9C，与全 skill 一致。
• 自测：python price_integration.py --demo 内置小样本跑通（无需真实数据验证逻辑）。

授信量化：四档去化口径与结清触发点（2026-09-04 深圳六家实战 · 强约束）

为什么必须补第四档：既有 A/B/C 三档都把「首次登记（竣工未确权）」计入已处置， 导致表面 100% 去化的项目实际现金回笼极低。偿债来源是销售回款，不是竣工登记—— 单看 A/B/C 判"已清盘"会出授信事故。

四档定义（必须并列，绝不只给一个数字）

档	公式	含义
D 现金回笼（新增·最保守）	已售·网签 / 总套数	只看真卖出去多少。结清能力以 D 为主
C 签约口径（最严）	(总−在售−风险−登记−安居)/(总−风险−登记−安居)	剔除竣工未确权与政策房
A 净口径（授信推荐）	(总−在售−风险)/(总−风险)	只剔风险
B 毛口径（最宽）	(总−在售)/总	含风险计入已处置侧

恒有 D ≤ C ≤ A ≤ B；B−A≈风险房源占比，A−D=名义去化水分（越大越危险）。 分母必须单独暴露，否则数值不可跨城比较。

实证（深圳，触目惊心）

项目	A 净口径	D 实际回笼	水分
翠湖大厦	100.0%	11.4%（60/528）	88.6pt（468 套是首次登记）
乾成数创文化园	100.0%	13.8%（202/1466）	86.2pt
圳发云谷大厦	100.0%	15.0%（21/140）	85.0pt
云谷里	70.7%	34.4%（278/808）	36.3pt（另 415/808=51.4% 在建抵押）
深铁熙府	100.0%	0%（2080 套全安居房）	100pt（不可变现）

两条铁律（实测踩坑，勿犯）

1. 状态互斥·禁双重扣减：在售/已售/风险(抵押·查封·锁定)/首次登记/安居房 五类互不重叠 （逐项目核对「在售+已售+风险+登记+安居=总套数」均成立）。 故 有效可变现 = 在售 ×(1−业态折扣)，不可再乘(1−风险占比)—— 风险房源本就不在在售里，再折减即重复扣减、低估货值（云谷里 39 套 → 正确 80 套）。 风险占比作独立风险信号单列展示。
2. 缺失严禁当 0：原始分项为「—」时一律置 None、显示「—」，不得用 or 0 参与计算 （万科麓山贵阳仅总套数 3540、or 0 后 D 被算成 0% 并误报"回笼严重不足"）。 缺失项目的提示改为「数据缺失·须补充后再评」。

可承载授信上限 = 有效可变现货值 × 回款率 90%；判断：实际授信额 ÷ 上限 ≤1 安全、 1~1.5 需追加担保、>1.5 不建议新增投放。（本表不含贷款余额，给的是可套用框架。）

落地脚本：build_credit_quant.py（工作区根），产出 4 Sheet：口径说明 / 项目级 / 六家汇总 / 结清触发点。每次改动后必须 openpyxl 回读实测审计再报完成。

下次继续的方向（已挂账待办）

完整 backlog（含已完成项与按价值排序的待办）已迁出至 references/待办清单.md，主文档按需查阅，避免陈旧清单与实战脱节。

• 城市扩采（B/C/A/E 类）与瑞数攻坚路线：见 references/待办清单.md
• 新城市：按「探测 SOP」复制即可（本轮 33 城均已定性）

工程注意（跨城项目专属）

• 混元 429 配额超限时切 Agent model: "lite" 变体继续（交互式 Agent 可用 lite 省钱；automation 的 modelId 仍须具体模型或 "default"，见上文"lite"警告）。
• 并行探测用后台 Agent（每个 Agent 负责 2~3 城，完成后写 status.txt 回传）；主线程只做整合，不要让 Agent 改主清单文件。
• 采集器脚本放项目根目录 extract_<city>.py，数据统一放 output_cross/<city>_data/，结论放 output_cross/<city>/status.txt。
• 苏州教训：公示表类数据交付前必须声明时间范围与行政区覆盖，避免"历史存量"被误当实时价。

按开发商 / 品牌 / 合作方检索专项方法论（2026-08-12 沉淀 · 强约束 · ✅已确认标准起手式）

✅ 2026-08-12 用户确认 + 本日补充：本五阶段 SOP + 四道红线作为此类检索的标准执行模式；其中 P2 工商穿透默认走财汇MCP（股权/对外投资）为强制步骤，不得跳过直接按企业名去官方库搜。⚠️ 财汇MCP 有概率失效——若不可用，必须降级到其他官方工商渠道完成穿透（首选 WorkBuddy 的 neodata 连接器，亦可用国家企业信用信息公示系统 / 天眼查 / 企查查 等），最终仍须产出「品牌 ↔ 备案法人映射表」，穿透动作本身不可省。

适用场景：检索锚点是「企业」而非「项目名」——用户给的是品牌方（如万科/鹏瑞）、开发商、合作方/股东，要反查其全部在售/在途房源。这是最易踩坑的一类，核心死局是 「品牌 / 开发商 / 合作方」名字 ≠ 官方备案主体 / 项目名。

一、为什么这类检索特殊（踩坑根源）

• 官方预售证系统（筑房网、阳光家缘等）几乎都按「项目名 / 备案名」检索，极少支持「按开发商企业名」可靠检索；即使支持（如广州 sDeveloper）也常漏。
• 头部房企普遍用合营 / 项目平台公司登记预售证，企业名不含母品牌字号（贵阳万科麓山=贵阳广晟鑫德、云翠隐秀=贵阳万新、锦上兰台=贵州融通；广州鹏瑞虽用本名但接口仅返最新 10 条）。
• 房产平台（安居客/房天下）给的是营销品牌名 + 板块叙事，与官方备案名存在系统性偏差，直接当候选名单会高估官方在售盘数量（万科贵阳 web 9 盘 → 官方仅 5 盘有证级）。

二、五阶段执行流程（SOP，务必顺序执行）

• Phase 0 · 明确检索主体与口径：先厘清用户给的是「品牌方 / 开发商 / 合作方」哪一类；定城市、时间窗、产品类型、交付物（证级 / 逐套 / 网签去化）。→ 避免拿到一堆无关主体。
• Phase 1 · 外网广撒网（拿候选名单）：WebSearch + 房产平台 + 房协/筑房网周榜，产出「候选项目 + 板块 + 疑似备案名/坐落 + 取证年份线索」+ 营销口径基础数据（均价/户型/体量）。→ 此步只作线索，不可当结论。
• Phase 2 · 工商穿透溯源（股东结构 · 关键桥梁）：用财汇MCP（query_enterprise_profile 企业档案 / query_enterprise_equity_and_investments 股权 / query_enterprise_business_and_bidding 对外投资）沿股东链找 项目公司 = 备案主体、合营/联营公司、区域平台。产出「品牌 ↔ 备案法人(项目公司) 映射表」。→ 这一步解决「按企业名搜不到」的死局，是整条 SOP 的胜负手。
  • ⚠️ 财汇MCP 失效降级通道（强制 fallback）：财汇MCP 并非 100% 可用（连通失败 / 超时 / 空响应均有概率）。一旦 caihui_mcp 不可用，立即按以下优先级降级，穿透动作一个都不能省：
    1. 首选 neodata（WorkBuddy 官方企业数据连接器）：取股权结构 / 对外投资 / 股东链，能力对齐财汇MCP；
    2. 次选权威工商源：国家企业信用信息公示系统、天眼查、企查查 等公开/授权工商渠道；
    3. 若以上全不可用，至少用 WebSearch 定向检索「公司名 + 股东 + 股权」 兜底，并在交付物明示「工商穿透降级、置信度有限」。
  • 降级时来源标注同步切换：[MCP·预警通] → 改用 [neodata] / [工商·公示系统] / [工商·天眼查] 等，并在交付物「数据来源说明」注明本次穿透实际所用渠道。
• Phase 3 · 官方证级核证（权威绿底）：用 Phase2 拿到的「备案法人名 + 项目名」双线索去官方系统拉证级。贵阳=certificate/list 全库翻页 + 本地过滤（关键词被忽略，必须兜底翻页）；广州=fdcxmxxlb.ashx 的 sProjectName/sDeveloper 检索。产出官方证级（批准套数/面积/楼栋/监管账户），落盘绿底。
• Phase 4 · 深挖目标盘（逐套/网签/去化）：对选定重点盘拉逐套销控（广州可行、贵阳锁登录）、网签去化（周/月榜、外网成交）；整合表绿底=官方、黄底=外网。

三、四道红线（任何一步违反都须标注，不可静默放过）

1. 品牌 ≠ 备案名：只要检索锚点是企业名，第一反应应是「它下面挂着哪些项目公司」，而非直接拿企业名去官方库搜。
2. 须穿透到项目公司：Phase 2 不可省略（穿透所用渠道可降级，但该动作本身不可省）；合营盘按母品牌企业名查必然漏（万科贵阳 4 盘、金地深圳 3 盘均因此「查无此盘」）。
3. 全量翻页兜底：官方列表接口常忽略关键词参数（贵阳筑房网实证），必须翻全库 + 本地过滤，否则漏采早年期证。
4. 供应 ≠ 成交口径：证级 sellSummaryList 是批准（供应）口径，与外网网签成交口径不可相减推库存；网签均价高于挂牌属结构/计价差异，不可直接读成「涨价」。

四、交叉校验与尽调红旗

• 背书校验：官方住宅批准套数 vs 外网宣称总户数，吻合（差异 ≤30%）可反向背书外网体量可信；差异 >30% 则外网口径可疑。
• 红旗标注：web 列出但官方库查无的盘 → 红底标注「官方查无，营销口径不可采信」，并附区位反查证据（如阅山湖=中铁系、老湾塘=安置房）。
• 口径声明：交付物必须含「数据来源说明」Sheet，逐条标注 [官方·筑房网/阳光家缘] / [外网·WebSearch]，并声明供应/成交口径不可混用。

五、今日两案例佐证（已实证）

• 广州·鹏瑞/壹湾广场：zxyslplb.ashx 仅返最新 10 条且拒关键词 → 改 fdcxmxxlb.ashx 检索端点实拉 1116 套官方逐套；用官方图例（1可售/2已售/3已备案/4已过户/5不可售）纠正「已售」统计口径。
• 贵阳·万科：web 9 盘 → 工商穿透发现合营主体（广晟鑫德等）→ 全库翻页过滤得 5 盘 55 本官方证级；另 4 盘官方查无（尽调红旗）。全库含「万科」167 本 / 53 个项目，远超 web 9 盘。
• 可复用脚本：collect_vanke_all.py（全库翻页+过滤+info）、build_vanke_consolidated.py（整合+红旗+全览）、probe_lushan.py / build_lushan.py。
• 一键工厂：本 SOP 的 P3（官方证级采集）+ P4（着色 Excel）已固化为 scripts/by_developer.py，支持 guiyang（完整内置，无需浏览器）/ guangzhou / shenzhen（薄封装调既有采集器）。P1（外网撒网）/ P2（工商穿透）仍由 AI 执行，其产出（品牌名 + 备案主体名列表）作为工厂输入。用法见文件头注释。
  • 深圳适配器已修复：旧版误传 --organ 参数（fetch_house_data.py 不认 → 静默空跑），现改为注入 PERMITS 列表后调 fetch_house_data.main()，需 --sz-script 指向采集器 + --sz-permits 提供 {ysProjectId,preSellId,presell_no} 清单。
  • 采集后自动质量校验：工厂调用 scripts/validate.py 的 validate_permits 输出重复证号/批准套数缺失等报告（--no-validate 可关）。
  • 品牌项目总表模式：--mode project-summary --from-json <全量dump> --brand-key 万科 从本地全量证级 dump 生成「品牌在筑官方项目总表」（53 项目汇总 + 全量证级清单），无需联网；scripts/gen_vanke_guiyang_total.bat 为万科一键启动器。
  • 📋 授信级报告模板：本 SOP 的产物标准化格式（主体界定→工商穿透→官方证级→深挖→交叉校验→授信结论→来源标注）见 references/尽调报告模板.md，任何品牌/城市一键产出可采信底稿。

🔗 跨 skill 整合（与集团交叉分析协同）：本专项方法论解决的是「采集层」——按开发商/品牌拿去化底数。当用户目标是 「以项目去化佐证开发商集团信用风险 + 配 Word 综合分析报告」 时，须加载 developer-group-cross-analysis skill 走完整整合流程：它在采集层之上，再叠加 财汇MCP·企业预警通（集团工商/司法/评级/债券/担保）与 外网 WebSearch 交叉印证，最终产出 Excel(7Sheet)+Word(8章)+跨城看板 三件套，正面实现「以项目去化佐证集团分析」。两 skill 共用同一底层去化 JSON，避免口径分裂。

实战案例协议（点名制 · 2026-08-31 用户确立 · 强约束）

用户原话（2026-08-31）：「后续的城市若缺失可参考楼盘样本，可以建议我启动实战案例，让我点名跑一个楼盘，不让你盲目抓取。盘点一下，我还没有给过实际楼盘的城市，我来帮你每个城市至少保有一个实战案例。」

一、核心铁律：不许盲目抓取楼盘

城市级底表（全市销控 / 一房一价总表）由 AI 自主跑；但「具体楼盘」必须用户点名。

场景	允许	禁止
跑某城全市底表 / 补样本行	✅ 自主	—
决定「跑哪个盘」	❌ 不许	禁止 AI 自选楼盘开跑
提供候选清单请用户点名	✅ 必须	—
用户点名后深挖该盘	✅ 执行	—

违反后果：楼盘名五花八门（推广名≠备案名，见既有铁律），AI 自选极易跑错主体、抓成安商房/自持/非目标盘，白烧 token 且结论不可采信。

二、触发条件（满足任一即启动「报缺 + 请点名」）

1. 某城为 C/D 级，缺 真·逐套备案价（Sheet3 为 0 或极少）→ 升 A 需人工补录，只能靠点名单盘。
2. 某城样本达标但无实战案例（见第六节覆盖表）→ 主动盘点报缺。
3. 授信/尽调场景需要单盘深度（证级逐套 + 去化 + 货值 + 报告），城市级底表不够用。
4. 用户问「某城能不能做深」「这个盘什么情况」。

三、报缺 → 点名 的标准话术（AI 必须照此输出）

禁止说：「我去跑一下 XX 盘」「建议抓这几个盘」。 必须说：报缺口 + 给 3 个候选 + 请点名。格式：

text

【XX 城 · 缺实战案例】现状：C 级 24 条外网样本，无真逐套备案价。
建议启动实战案例。请从以下候选中点名 1 个（或你直接给盘名）：

  候选A · <盘名> | <区> | 外网均价 X 元/㎡ | 推荐理由：<在售/大体量/开发商有授信关联/…>
  候选B · <盘名> | <区> | … | 推荐理由：…
  候选C · <盘名> | <区> | … | 推荐理由：…

口径提示：该城为 C 级，官方无逐套价 → 本案例只能产出「外网参考价 + 官方销控/证级」，
价格须标 [外网·WebSearch]，不可当成官方法定备案价。

候选挑选规则：① 来自该城已有样本表（自采，不新抓）；② 尽量跨区、跨价位段；③ 优先在售/近 1–3 年取证（避免清盘老盘，去化失真）；④ 避开安商房/自持/保障房；⑤ 注明「推广名 vs 备案名」若已知不同。

四、用户点名后的执行标准（沿用既有 SOP，不另起炉灶）

• 采集口径：逐（楼栋→单元）枚举 + 证载套数校验（首屏漏栋是失真头号来源）。
• 去化口径：审慎口径 = 已售类 / 总数（在建抵押 / 锁定 / 共有产权不计入已售）。
• 交付：Excel（官方浅绿底 / 外网浅黄底双色标源）+ Word 尽调报告（主体界定→工商穿透→官方证级→去化→交叉校验→授信结论）。
• 三源三角：官方（底数）+ 财汇MCP·预警通（集团风险）+ 外网（动态），逐条标来源。
• 若该盘跑不通（反爬/无数据）：bounded 尝试后主动上报人工介入，不硬磨、不编造。

五、案例沉淀与回写（闭环）

1. 案例产物落 output_cross/ 或独立 run_<城>_<盘>/ 目录（参照 run_gz_pengrui/：尽调报告 md + 证级逐套 xlsx + 货值 xlsx + 重跑对比）。
2. 回写覆盖表，保证每城 ≥1 个实战案例；已达标城市在盘点表中标 ✅ 与案例名。
3. 新踩的坑（新反爬类型 / 新口径失真）当场补进本 skill 对应章节（遵循「动态总结进 skill」机制）。

六、36 城实战案例覆盖现状（2026-08-31 实测盘点）

已有案例 15 城：深圳（卓越系 7 盘 + 山樾湾花园 + 晟悦家园 + 圳发云谷大厦 + 绿景/金地集团级）、广州（鹏瑞·壹湾广场）、佛山（保利中嘉花园 + 中粮珑湾祥云）、厦门（五缘公馆）、青岛（越秀天悦海湾）、成都（青江名邸）、合肥（文渊府 + 嘉宸雅园 + 汀云居，2026-08-31 点名制三盘·活销控）、廊坊（丁香园 + 狮子城 + 正雅馨苑，2026-08-31 点名制三盘·开盘公示快照型：无实时去化，出价格结构+全盘货值GDV）、南京（上城十号院 + 华曦璟园 + 鱼嘴润府平园，2026-08-31 点名制三盘·活销控·三盘合计在售50.4亿/全盘79.7亿）、武汉（黄金口三村 + 保利城四期 + 公园绿地2026-011，2026-08-31 点名制三盘·⚠️无销控状态仅价格结构+全盘货值）、重庆（力帆红星广场C10组团 + 盛豪·首港城 + 星悦·礼嘉天序，2026-08-31 点名制三盘·⚠️状态复合历史态去化近似）、西安（锦华颂 + 时光云境小区 + 云璞小区，2026-08-31 点名制三盘·⚠️无销控状态仅全盘货值·三盘合计20.8亿）、苏州（浅棠平江 + 海胥澜庭 + 江湾雅园，2026-08-31 点名制三盘·⚠️历史2019-2022·仅姑苏区高端·无销控状态·三盘合计47.2亿）、郑州（保利尚园 + 锦绣田苑 + 经开区瑞祥小区，2026-08-31 点名制三盘·⚠️仅备案单价无面积→货值N/A·状态全已售→去化无效）、北京（望坛新苑 + 御林湾苑 + 天汇银杏苑 + 都阙苑 + 商贸中心，2026-09-01 点名制代表盘·官方逐套可下钻子集·仅期房占全市1.2%·真实去化率+拟售均价）。

待补城市（按「数据可得性 × 业务价值」排优先级，用户点名即跑）：

• T0★ · 本轮排查新发现·官方平台已确认可达·待建主档（4）：福州、东莞、惠州、江门 —— 原 T5(C级) 误判，住建局明文可查逐套备案价；东莞已按合肥套路建采集器 collect_dongguan.py 并确证 A 级（数据链 licenseList→querySalePrice→viewXxgs 全验证、公开无登录墙），其余 3 城参照合肥 /spf 套路建主档即可升 A（详见「跨城排查惊喜清单」章节）
• T1 · A 级官方逐套可用，能出全套深挖（3）：杭州、宁波、济南 —— 均为死路（杭州逐套被顶象反爬拦截仅项目级·宁波 houses.json 空无价·济南无主档无采集），需本机住宅 IP 或重采方可建案例；西安/苏州/郑州/南京/武汉/重庆已建案例
• T2 · A 级其余（2）：珠海、贵阳
• T3 · D 级重点城市，仅外网口径（2）：北京、上海
• T4 · B 级（2）：大连、无锡（无锡须本机跑 extract_wuxi.py）
• T5 · C 级受限 / 待核验（7）：长沙（⚠️2025-12 新平台「房屋交易一体化服务平台」疑似开放价格·待核验）、天津（智慧住房平台·逐套单价需扫证载二维码·网站不列）、运城 / 石家庄 / 太原（销控状态可达·官方不公示逐套备案价）
• 不计：保定、南通（放弃·有网签/销控状态查询但无逐套价）；中山、肇庆（粤安居死路·2026-08-31 排查坐实·印证用户「永久放弃」决定）

六·附 · 跨城排查惊喜清单（2026-08-31 · 合肥误判教训的规模化复检）

触发：合肥 www.hfzfzlw.com 根路径=租赁平台、误判无房价，实际 /spf 才是商品房平台跑通后，对 11 个 T5(C级) + 2 个放弃城市做「主管局官网→商品房/一房一价业务系统」定向排查。

方法（元级铁律）：域名≠单系统，先开主管局官网取「重要业务系统」清单，别被根路径/外网兜底样本误导（合肥即典型）。

结论：

• ★ 升 A·已验证可达（原 C 误判，住建局明文可查逐套备案价）：福州（强制登录墙·福建省统一实名认证，需本机已登录态 CDP 才可达，未跑通）、东莞（zjj.dg.gov.cn 首页「建设工程信息公示」→商品房预售/现售许可信息→「房价申报」；数据链 licenseList.action(楼栋级13511)→querySalePrice.action→viewXxgs.action 逐套一房一价表，server 直渲公开无登录墙=确证A；但全量爬取触发服务端 IP 级限流，限流冷却后须用温和模式（单线程+请求间隔，禁用12线程并发——高并发会重触发限流、把刚冷却的 IP 再打封）trickle 爬完；定向下钻只钻代表盘楼栋（collect_dongguan_units_targeted.py）几分钟搞定、免全量13511逐套10h再触限流）、惠州（zjj.huizhou.gov.cn「房产信息交易版」/ 综合监管平台 113.96.111.148:9087）、江门（房屋交易和产权管理信息平台 218.14.150.123:8085）。
• ⚠️ 待核验：长沙（2025-12-12 新平台「长沙市房屋交易一体化服务平台」上线，含房源核验/网签/资金监管，疑似开放价格，需一次探活确认）。
• 维持受限（销控状态可达·官方不公示逐套备案价）：运城、石家庄、太原、天津（逐套单价需扫证载二维码）。
• 印证永久放弃：中山、肇庆（已并入粤安居 yueanju.zfcxjst.gd.gov.cn 死路）。

建主档注意：福州/东莞为政府标准域名、纯网站可达概率高（类比合肥 /spf）；惠州/江门为 IP:port 内网式直连，建主档前须先探活确认是否被外网拦截。

交付物：output_cross/跨城排查_惊喜清单_20260831.html（可视化矩阵 + 可抄作业官方入口）；覆盖表 城市实战案例覆盖盘点_20260831.xlsx 已同步（4 城保真度→★、长沙→C⚠️、中山/肇庆→放弃(粤安居死路)、修正太原行原名误标）。

盘点表交付物：output_cross/城市实战案例覆盖盘点_20260831.xlsx（36 城 × 有/缺 × 优先级 × 候选来源 × 口径红线）。每次补案后回写该文件，保持最新。

动态总结进 skill 机制（用户强制 · 2026-08-24 确立）

用户原话：「让你总结就是，写进 skill，以后不要再说了，你要时刻总结进 skill，随时的，动态的！！！记住！！！」

规则（强制）：每次任务产出任何可复用的经验、口径、踩坑、方法论、脚本路径、数据结论，必须即时沉淀进本 skill（或跨 skill 的对应资产），不要只在对话里口头总结就让任务结束。具体要求：

1. 时机：任务完成那一刻即写 skill，不等用户追问"总结一下"——对话里的总结是给用户看的，skill 里的沉淀才是给未来的自己看的。
2. 落点优先级：
   • 新方法/新口径/新专章 → 本文件对应章节（如安居房核实、CDP、token 直连）；
   • 完整踩坑闭环 → references/cases/ 新建案例文件 + 案例库章节加条目 + 顶部变更说明加编号；
   • 脚本固化 → 可复用资源章节登记路径 + 文件头注释；
   • 长期用户偏好/约束 → 同时写 ~/.workbuddy/MEMORY.md（跨项目）与本项目 memory/MEMORY.md。
3. 动态更新：skill 是活文档，不是写完就封存。下次同类任务跑出新坑/新数据，立即回写对应章节（顶部"最后更新"日期 + 变更编号同步推进）。
4. 勿重复口头总结：已沉淀进 skill 的内容，对话交付时只给结论索引（"详见 skill 安居房核实专章"），不必在对话里大段复述 skill 已有内容——用户要的是"脑子记下来"，不是"嘴上再说一遍"。
5. 交付物自检清单（强制·对应「关键工程约定」交付物铁律）：每次生成 Excel/Word 产物，交付前必须回读实测并确认：① 报告全章节写进生成函数一次性产出（无任何事后追加/覆盖）；② 时间戳为本次 datetime.now()（无旧时间残留）；③ 章节口径前后一致无打架；④ 无旧项目关键字残留；⑤ 仅给用户最新版产物路径。任一项不达标 = 任务未完成。
6. 验证：写完后用 Skill 工具重新加载确认无语法/结构错误（如章节断裂、编号重复）。

自动化调用约定（沿用最新版）

• 本 skill 会持续迭代（新增城市/修正口径/改 Sheet 结构）。凡是调用本 skill 的自动化任务，其 prompt 必须：
  1. 以 @skill real-estate-risk-analyst 开头显式加载本 skill（曾用名 real-estate-filing-query，已停用）；
  2. 注明"始终使用最新版"——这样 skill 文件更新后，下次定时运行自动采用新版方法，无需改 prompt。
• 原因：自动化任务的 prompt 是独立存储的快照，不会随 skill 文件更新而自动同步；只有显式 @skill 加载，运行时才会读取最新 skill 文件。
• 反例：若 prompt 直接硬编码"运行某脚本"且未 @skill，则 skill 后续更新（如新增「预售许可证清单」「剩余货值测算」Sheet）对该自动化不生效。
• 已落地示例：晟悦家园采集任务（automation-1786070770715，每日 09:00）prompt 已改为 @skill real-estate-risk-analyst 开头 + 沿用最新版 + 6 Sheet 对齐校验。

可复用资源

• references/城市实跑案例库.md：跨城采集城市样本速查（2026-08-18 收官）——每个城市的官方平台入口 + 采集方式 + 已有实跑样本（15城实跑/4城新定性/6城受限），下次接到任一城市任务先查本库直接照跑；配套 Excel output_cross/跨城一房一价_城市实跑案例库_20260818.xlsx。
• references/real-estate-guide.md：完整技术参考（深圳平台已验证的列表/房源 API、字段映射表、状态取值、价格行为、脚本骨架函数、避坑清单、成都 infoDetail→roompricezjw 逐套采集方法、剩余货值测算、复制粘贴提示词）。
• 项目脚本骨架（换项目只改配置与字段映射，逻辑零重写）：PERMITS 列表遍历、compute_snapshot() 聚合快照、find_baseline() 取对比基准、detect_anomalies() 突变检测、add_comparison_sheet() / add_alert_sheet() / add_permit_sheet() / add_value_sheet() 生成各 Sheet。
• scripts/build_house_dashboard.py：交互看板通用生成器（2026-08-11）——python build_house_dashboard.py <Excel路径> [项目名] 一条命令出完整 HTML 看板（6 图表+KPI+质量校验+梯度回归+6 决策模块+四筛选+排序分页）。自动探测表头/动态列映射/动态状态配色/兼容两种剩余货值结构。晟悦家园/深润川已验证。
• scripts/build_cross_dashboard.py：跨城对比大屏（2026-08-11，少数综合场景用）——33 城覆盖能力综合展示，改 CITIES 数组即更新。
• scripts/validate.py：数据质量校验模块（2026-08-12，从看板下沉）——validate_houses(list) / validate_permits(list) 返回机读报告（重复房源、字段空值率、面积异常、单价 z-score、总价单价一致性、证号重复、批准套数/面积缺失）。工厂采集后自动调用。
• scripts/by_developer.py：按企业/品牌检索脚本工厂（2026-08-12）——把 SOP 的 P3+P4 固化为 CLI：guiyang 完整内置 REST 证级采集、guangzhou/shenzhen 薄封装调既有采集器、--mode project-summary 出品牌项目总表。详见文件头注释。
• scripts/gen_vanke_guiyang_total.bat：万科在筑 53 项目总表一键启动器（2026-08-12）。
• scripts/collect_shenzhen_all.py：深圳全市预售证全量采集器（2026-08-19，基本盘检索底数）——getYsfYsPublicity 翻页全量（pageSize=200，无过滤）+ 每页覆盖写断点续跑。实测 4,408 证/2,932 项目 → output_cross/shenzhen_data/shenzhen_presell_all.json。
• 📌 检索底数模式（2026-08-19 沉淀，深圳/大连/青岛同型）：对"有列表 API 且可匿名/半匿名翻页"的城市，先建全市证级全量检索底数（项目ID+预售证ID+证号+项目名+开发商+区），后续按项目名/开发商直接命中（project/name 子串过滤），无需每次全量翻页。已落地：深圳 4,408 证（Playwright 页面内 fetch）、大连 1,623 项目（纯 POST）、青岛 13,695 证（纯 GET JSP）。⚠️ 推广名≠备案名：营销推广名常 0 命中（"前海未来城"），检索须用备案名/开发商双线索。
• build_manifest.py：交付物总览清单生成器（2026-08-26 固化，工作区根目录）——扫描工作区全部交付物（剔除调试 HTML 如 yuehaitang_*/shanghai/*_body/lf_*），按 9 大类（A卓越金地绿景标杆 / B深圳专项 / C大湾区 / D新一线10城 / E跨城总览案例库 / F单项目专项 / G交互看板 / H官方PDF / Z其他）生成带可点击 file:// 超链接 + 说明 + 大小 + 日期的折叠 HTML（output_cross/交付物总览清单_<日期>.html）。新增任一份 Excel 后重跑即自动收录；清单自身已排除。⚠️ 前台 Bash 一旦报序列化故障，改派 Agent 跑此脚本（子 Agent 独立 Bash 通道可用）。
• 📌 多快照防膨胀三件套（2026-08-26 沉淀，通用方法论）：针对"同一项目被反复采集、每次另存带时间戳 xlsx"导致的文件膨胀，套用「融合主档 + 定时合并 + 归档旧文件」：每个项目只留 1 个 *_主档.xlsx（5 Sheet：数据源说明/最新房源明细/逐日去化汇总/状态变更日志[单元级(楼栋,房号)状态diff]/预售许可证清单）+ 1 个固定名 *_去化趋势_最新.html，历史散落快照移入 *_归档_<日期>/（可恢复不删）。已落地项目：晟悦家园(616套/10日/13变更)、山樾湾花园(5003)、珑瀚公馆(366)、卓越缦悦(231)、珺奕府(891)、卓越前海未来城(595)、深润川实业(2126)——output/ 根目录从 ~44 散落快照收敛为 7 主档+7归档夹。
• merge_any_project_master.py：通用参数化融合器（2026-08-26，工作区根目录）——python merge_any_project_master.py <项目关键词> [展示名]，自动归一化文件名（去日期/去「房源数据」「安居房适配」「存量项目」/繁简「公館」→「公馆」）做分组，兼容首行是标题行的文件（深润川），自动探测状态列/备案单价列/单元主键，生成主档+趋势+归档。幂等自愈：既扫 output/ 根目录也扫 *_归档_*/，且只移动仍驻根目录的源文件（归档中已有的跳过），故归档后重跑也能从归档重建主档。
• merge_all_scatter.py：批量融合运行器（2026-08-26）——一次性对 山樾湾花园/珑瀚公馆/卓越缦悦/珺奕府/卓越前海未来城/深润川实业 调 merge_any_project_master，并把遗留晟悦旧快照并入 晟悦家园_归档_*；新项目只需在 PROJECTS 列表加一行即可。
• merge_shengyue_master.py：晟悦家园专用融合器（逻辑同通用版，晟悦首创），保留作标杆参考。
• ⚠️ parse_date 坑（2026-08-26 踩中并修复）：parse_date 必须只解析文件名(os.path.basename)，不能用完整路径——否则会命中归档文件夹名里的日期（如 *_归档_20260826），导致所有快照被判为同一天、snaps[-1] 错取排序最后的残档（珑瀚曾因此主档变成 3 行而非 366 行）。通用版已修正。
• 配套自动化 房产主档维护（防文件膨胀·全项目）（automation-1787726153078，每日 09:30，model=auto，幂等）：依次跑 merge_all_scatter.py + merge_shengyue_master.py，覆盖全部 7 项目。去化率口径沿用本 skill 铁律（审慎=已备案/总；宽口径=(总-期房待售)/总，已售=0）。