pp-redfin

Redfin — Printing Press 命令行工具

前置条件：安装命令行工具

此技能使用 redfin-pp-cli 二进制文件。**在调用此技能中的任何命令之前，必须先确认命令行工具已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install redfin --cli-only
   

2. 验证：redfin-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/other/redfin/cmd/redfin-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功之前，请勿执行此技能的命令。

何时使用此命令行工具

当 Agent 或用户需要结构化的 Redfin 数据，以及网站本身不提供的工作流时，请使用此命令行工具：按时间跨区域对比差异、扣除 HOA 费用后的每平方英尺价格排名、针对某处房产的已售房源可比分析方案、跨城市市场趋势叠加，以及摘要式概览。适用于买家比较房源、投资者筛选多个邮编区域、搬迁者比较城市，以及买方经纪人提取可比房源的场景。一次性浏览则无需使用它，直接访问 redfin.com 网站即可。

何时不使用此命令行工具

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此命令行工具。此 CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能是此 API 的其他工具所不具备的。

时间序列分析

• watch — 重新运行已保存的 gis 搜索，并显示自上次同步以来新增、移除、价格变更或状态变更的内容。

  当 Agent 需要持续跟踪买家的候选房源清单，并获取可复现的“发生了哪些变化”摘要时，请选择此功能。

  redfin-pp-cli watch austin-3br --since 7d --json
  

• drops — 列出在指定时间窗口内降价 N% 的活跃房源，或上市天数超过阈值的房源。

  在把握市场时机或安排看房前筛选低价候选房源时，请选择此功能。

  redfin-pp-cli drops --region-id 30772 --region-type 6 --since 7d --min-pct 3 --dom-min 30 --json
  

本地存储计算

• rank — 按每平方英尺价格对已同步的房源排名，可选择扣除 5 年周期内的 HOA 费用。

  当目标是衡量性价比，且需要让 HOA 费用较高的公寓与独栋住宅公平竞争时，请选择此功能。

  redfin-pp-cli rank --by price-per-sqft --net-hoa --region-id 30772 --region-type 6 --json --limit 25
  

候选清单工作流

• compare — 通过 Stingray 综合详情端点提取 2-8 套房源，并输出列对齐的结果（价格、每平方英尺价格、卧室数、浴室数、地块、建成年份、学校、AVM 差值、上次出售时间、税费）。

  缩小候选清单范围时，请选择此功能；宽表能让学校评分和 AVM 差值的差异一目了然。

  redfin-pp-cli compare <your-listing-url> <another-listing-url> --json
  

• comps — 针对某套目标房源，根据 --radius 生成圆形多边形，执行已售状态搜索，按 --sqft-tol 和 --bed-match 筛选，并返回排名后的可比房源集。

  当 Agent 需要为买家报价提取可比成交房源时，请选择此功能；一条命令即可省去 20 分钟的多边形点击操作。

  redfin-pp-cli comps <your-listing-url> --radius 0.5 --sqft-tol 15 --months 6 --bed-match --json
  

跨市场联接

• rank — 合并多个区域 slug 中已同步的房源，按 listing URL 去重后对整个集合进行排名。

  当 Agent 需要跨多个都会区获取统一的排名源，而不想编写扇出循环时，请选择此功能。

  redfin-pp-cli rank --regions 30772,30773,30774 --by price-per-sqft --beds-min 3 --price-max 600000 --json --limit 25
  

• trends — 提取 N 个区域的 aggregate-trends，并在指定时间窗口内输出一张整洁的长表（区域 × 月份 × 指标）。

  当搬迁者比较不同城市，并需要在同一坐标轴上叠加中位数时，请选择此功能。

  redfin-pp-cli trends --regions 30743,18028,30739 --metric median-sale --period 24 --json
  

批量提取

• export — 将价格空间划分为多个区间，逐个区间翻页遍历 gis-csv，直到每个区间返回的结果少于 350 条；按房源 URL 去重，并输出一个 CSV/JSON。

  当你需要某一年的所有可比房源，而不只是按相关性排序的前 350 条时，选择此项。

  redfin-pp-cli export --region-slug "city/30772/TX/Austin" --status sold --year 2024 --csv > austin-sold-2024.csv
  

聚合数据

• summary — 一条命令即可获取在售数量、待售数量、近 90 天售出数量、挂牌价中位数、成交价中位数、DOM 中位数、每平方英尺价格中位数、降价房源占比，以及趋势快照。

  当 Agent 需要为买家简报一次性获取市场快照时，选择此项。

  redfin-pp-cli summary 30772:6 --json
  

• appreciation — 对父级都会区下的所有子社区调用 aggregate-trends，并按同比成交价中位数变化百分比排序。

  当搬迁者或投资者想知道“这个都会区内哪里最热门”时，选择此项。

  redfin-pp-cli appreciation --parent "city/30772/TX/Austin" --period 12 --json --limit 10
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。常规 API 调用无需常驻的浏览器进程。

发现信号

此 CLI 根据浏览器观察到的流量上下文生成。

• 捕获覆盖率：0 个 API 条目，占网络条目总数 0 个
• 协议：stingray-json-api（95% 置信度）
• 生成提示：解码前，从每个 Stingray JSON 响应中剥除 {}&& CSRF 前缀；运行时使用具有 Chrome TLS 指纹的 Surf（UsesBrowserHTTPTransport）；默认采用保守的速率限制：1 req/s，并在遇到 429 时自适应退避；Stingray 仅限美国地区访问，doctor 命令应提醒非美国用户；区域 ID 可在 redfin.com URL 路径中查看（例如，/city/30772/TX/Austin）；区域类型 6=城市、1=邮编、11=社区
• 候选命令建议：homes — Stingray gis search 是主要入口；listing — 房源详情由 initialInfo + aboveTheFold + belowTheFold 组合而成；market — aggregate-trends 端点可提供社区中位数
• 注意事项：csrf-prefix：Stingray JSON 响应以字面字节 '{}'&&' 作为前缀，用于防止 CSRF。生成的客户端必须在调用 json.Unmarshal 前将其剥除。；geo-restricted：Stingray 端点仅限美国地区访问。非美国调用方无论 TLS 指纹如何都会收到 403。

命令参考

homes — 通过内部 Stingray /api/gis JSON 端点搜索 Redfin 在售房屋。

• redfin-pp-cli homes — 运行 Stingray gis 搜索，并从 JSON 地图载荷中返回解析后的房源行。去除 {}&& CSRF 前缀……

listing — 通过组合 initialInfo、aboveTheFold 和 belowTheFold Stingray 调用，获取完整房源详情。

• redfin-pp-cli listing — 房源的首次 Stingray 调用——从 URL 路径返回规范的 listingId 和 propertyId。

market — 汇总某个区域在指定时间范围内的市场趋势（售价中位数、上市天数、供应量、挂牌价与成交价之比）。

• redfin-pp-cli market — 获取一个区域和指定时段（月）的 aggregate-trends JSON。

手写命令

• redfin-pp-cli homes — 按城市、卧室数、浴室数、价格等条件搜索 Redfin 在售房屋。
• redfin-pp-cli sold — 按城市和筛选条件搜索 Redfin 已售房屋（委托给带有 status=sold 的 homes）。
• redfin-pp-cli listing <url-or-path> — 获取完整房源详情（合并 initialInfo + aboveTheFold + belowTheFold）。
• redfin-pp-cli region — 区域工具：将城市/邮编解析为 Redfin region_id。
• redfin-pp-cli feed — 跟踪 Redfin 的 RSS 订阅源：新房源、更新的房源。
• redfin-pp-cli sync-search <saved-search> — 运行已保存的搜索，并将结果快照保存到本地存储。
• redfin-pp-cli watch <saved-search> — 将最新同步结果与上一版进行比较：新增 / 已移除 / 价格变更 / 状态变更的房源。
• redfin-pp-cli rank — 按比例指标对已同步房源进行排名——$/sqft（可选扣除 HOA）、$/bed。
• redfin-pp-cli compare <url-or-id...> — 将 2-8 个房源透视为宽表——每个房源一列——包含 $/sqft、AVM 差值和学校评分。
• redfin-pp-cli comps <subject-url> — 在指定半径、面积容差和时间范围内，为目标房源拉取已售可比房源。
• redfin-pp-cli drops — 列出价格在指定时间范围内下跌 N% 的在售房源，或挂牌天数超过阈值的房源。
• redfin-pp-cli market <region-slug> — 单一区域快照：数量、中位数、DOM、降价比例，以及趋势调用。
• redfin-pp-cli summary <region-slug> — 社区市场摘要：在售/待售/近 90 天已售数量、中位数、DOM、降价比例。
• redfin-pp-cli trends — 多区域 aggregate-trends 叠加分析；输出整洁表格（区域 × 月份 × 指标）。
• redfin-pp-cli appreciation — 按同比售价中位数变化百分比，对某个都会区下属社区排名。
• redfin-pp-cli export — 通过切分价格区间并按 URL 去重，批量导出超过 Redfin 350 行 gis-csv 上限的数据。

数据新鲜度约定

此 CLI 仅对已注册的、由存储支持的读取命令路径管理有限的数据新鲜度。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有限刷新。--data-source local 不会刷新。--data-source live 从 API 读取，且不会修改本地存储。设置 REDFIN_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，而不改变数据源选择。

覆盖的路径：无。homes 是每次调用都实时执行的搜索；本地存储仅由 sync-search / watch 填充。

当 JSON 输出使用生成的来源信息封套时，新鲜度元数据会出现在 meta.freshness。应将其视为适用于所覆盖命令路径的当前缓存新鲜度，而非完整历史回填或 API 特定数据增强的保证。

查找合适的命令

如果你知道要做什么，但不知道该使用哪个命令，可以直接询问 CLI：

redfin-pp-cli which "<capability in your own words>"

which 会从此 CLI 精选的功能索引中，根据自然语言功能查询匹配最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有足够确定的匹配项——请改用 --help 或使用范围更窄的查询。

示例

三个都会区的搬迁叠加分析

redfin-pp-cli trends --regions 30743,18028,30739 --metric median-sale --period 24 --json --select rows.region,rows.month,rows.value

对三个都会区在相同的 24 个月时间范围内拉取 aggregate-trends，并将其合并为一张便于导出的整洁长表——Redfin 的 UI 无法生成这种叠加结果。

一条命令获取买家代理的可比房源

redfin-pp-cli comps <your-listing-url> --radius 0.5 --sqft-tol 15 --months 6 --bed-match --json

解析目标房源，划定半径为 0.5 英里的范围，抓取过去 6 个月内售出的房屋，这些房屋的卧室数量相同且面积相差不超过 15%，并返回排序后的可比房源集，可直接用于买家报价简报。

跨 5 个邮编筛选投资房源

redfin-pp-cli rank --regions 30772,30773,30774,30775,30776 --by price-per-sqft --net-hoa --beds-min 3 --price-max 600000 --status for-sale --json --limit 25

合并跨 5 个 Austin 邮编的已同步搜索结果，并按扣除 HOA 费用后的每平方英尺价格对完整结果集排序。筛选条件会缩小范围，符合投资者筛选标准；最终结果是一个 Redfin 无法提供的单一排序信息流。

已保存搜索的每周差异

redfin-pp-cli watch austin-3br --since 7d --json --select new_listings.url,new_listings.price,price_changed.url,price_changed.delta_pct

将监控结果与 --select 组合使用，仅输出 Agent 所需的列——Agent 无需额外解析，即可直接将结果放入每周买家邮件。

批量抓取 2024 年售出的房屋

redfin-pp-cli export --region-slug "city/30772/TX/Austin" --status sold --year 2024 --csv > austin-sold-2024.csv

将价格区间划分为多个档位，逐页遍历每个档位的 gis-csv，并根据房源 URL 跨档位去重，最终生成一份超出 Redfin 350 行上限的 CSV。

身份验证设置

无需身份验证。

运行 redfin-pp-cli doctor 以验证设置。

Agent 模式

在任何命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 支持管道传递 — JSON 写入 stdout，错误写入 stderr

• 支持筛选 — --select 可保留部分字段。点分隔路径可深入嵌套结构；数组会逐个元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  redfin-pp-cli homes --agent --select id,name,status
  

• 支持预览 — --dry-run 会显示请求，但不会发送

• 便于离线使用 — 如果本地 SQLite 存储可用，sync/search 命令可以使用该存储

• 非交互式 — 不会提示输入，每项输入都通过标志指定

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在溯源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 确认数据来自实时来源还是本地存储。只有当 stdout 连接到终端时，才会将便于人类阅读的 N results (live) 摘要写入 stderr——通过管道传递的输出和 Agent 使用者在 stdout 上获得的都是纯 JSON。

Agent 反馈

当你或 Agent 发现此 CLI 有任何不妥之处时，请记录下来：

redfin-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
redfin-pp-cli feedback --stdin < notes.txt
redfin-pp-cli feedback list --json --limit 10

条目会保存在本地 ~/.redfin-pp-cli/feedback.jsonl。只有在设置了 REDFIN_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 REDFIN_FEEDBACK_AUTO_SEND=true 时，才会通过 POST 发送。默认情况下，反馈仅保存在本地。

写下令你感到意外的地方，而不是提交错误报告。简短、具体，只写一行：这部分反馈会不断累积。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定目标，同时也会输出到 stdout，或取代 stdout 输出，这样 Agent 无需手动通过管道传递，就能路由命令结果。支持以下三种目标：

目标	效果
stdout	默认值；仅写入 stdout
file:<path>	以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（当使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回结构化错误，列出支持的方案。Webhook 请求失败时会返回非零退出码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置文件

配置文件是一组已保存的标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一条命令，就可以使用配置文件——类似于 HeyGen 的 “Beacon” 模式。

redfin-pp-cli profile save briefing --json
redfin-pp-cli --profile briefing homes
redfin-pp-cli profile list --json
redfin-pp-cli profile show briefing
redfin-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置文件，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 redfin-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的前置要求
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并添加 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/other/redfin/cmd/redfin-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add redfin-pp-mcp -- redfin-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which redfin-pp-cli 如果未找到，则提出安装建议（参见本技能开头的前置要求）。
2. 将用户查询与上文“独特功能”和“命令参考”中的最佳命令匹配。
3. 使用 --agent 标志执行：

   redfin-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，查看子命令帮助：redfin-pp-cli <command> --help。