pp-apartments

Apartments.com — Printing Press CLI

前提条件：安装 CLI

此技能由 apartments-pp-cli 二进制文件驱动。**调用此技能中的任何命令前，必须先确认 CLI 已安装。**如果尚未安装，请先安装：

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

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

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

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

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

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

何时使用此 CLI

当 Agent 或用户需要结构化的 Apartments.com 数据，以及网站本身未提供的工作流时，请使用此 CLI：跨时间搜索差异、$/平方英尺和总入住成本排名、多 slug 联合查询、并排比较以及摘要式汇总。它适用于搬迁跟踪、候选清单的性价比筛选、租赁代理每周摘要，以及任何需要 JSON 和离线处理的租房搜索场景。单次浏览时无需使用它——直接访问 apartments.com 网站即可。

何时不使用此 CLI

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

独特功能

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

时间序列分析

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

  如果 Agent 要长期跟踪搬迁情况，并需要一份可复现的“与上周相比有哪些变化”摘要，而不是重新搜索，请选择此功能。

  apartments-pp-cli watch austin-2br --json --since 7d
  

• drops — 列出在某个时间范围内最高租金下降 ≥N% 的房源。

  如果要把握市场时机或留意急售房源，请选择此功能。

  apartments-pp-cli drops --since 14d --min-pct 5 --json
  

• stale — 标记价格和可租状态在 N 天内未发生变化的房源——这类房源往往是虚假房源或信息停滞的房源。

  如果房源看起来好得不真实，请选择此功能；停滞的房源往往确实有问题。

  apartments-pp-cli stale --days 30 --json --select url,maxrent,unchanged_days
  

• phantoms — 根据三个信号的关联结果，找出被标记的房源：重新获取时返回 404、已从已保存搜索结果中消失，或停滞 ≥45 天。

  如果要为安排看房准备候选清单，请选择此功能——虚假房源会浪费看房名额。

  apartments-pp-cli phantoms --json
  

• history — 查看单个房源每次观测的时间序列，包括租金、可租状态和状态。

  如果要分析单个房源的价格走势，请选择此功能。

  apartments-pp-cli history https://www.apartments.com/example-property-1234 --json
  

跨市场联合查询

• nearby — 在多个城市、邮编或社区中展开搜索，并返回一个经过排序和去重的列表。

  如果 Agent 需要整合多个搜索 slug 并生成单一排序结果，而不想编写扇出循环，请选择此功能。

  apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --rank sqft --agent
  

本地存储计算

• value — 按 12 个月总成本（租金 + 宠物租金 + 宠物押金 + 宠物费用）对已同步房源排序，并按你的预算上限筛选。

  当预算是硬性限制，且宠物费用可能让房源超出预算时，选择此项。

  apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,total_cost
  

• rank — 按比例指标对已同步房源排序——每平方英尺价格或每间卧室价格。

  当目标是追求每美元的价值，而不是“最匹配”或“最低价格”时，选择此项。

  apartments-pp-cli rank --by sqft --beds 2 --price-max 2500 --json --limit 10
  

• floorplans — 对已同步房源中每种户型的每平方英尺租金进行排序——同一栋楼可能有 4 种户型，比例各不相同。

  当一栋楼有多种户型，而你特别想找其中最便宜的户型时，选择此项。

  apartments-pp-cli floorplans --rank price-per-sqft --beds 2 --json --limit 10
  

• must-have — 使用 FTS5 筛选已同步房源，找出便利设施数组中包含所有指定词条的房源。

  当必备条件是自由文本，且不在 apartments.com 的便利设施下拉菜单中时，选择此项。

  apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json
  

候选清单工作流

• compare — 将 2–8 个房源转换为宽表——每个房源占一列——并计算每平方英尺价格和便利设施重合情况。

  当你要缩小候选范围时，选择此项；宽表能清楚显示便利设施重合情况的差异。

  apartments-pp-cli compare austin-arboretum-1 austin-arboretum-2 austin-arboretum-3 --json
  

• digest — 一次性生成摘要：针对一个已保存的搜索，在 N 天内汇总新增、下架、降价、每平方英尺价格排名前 5、过期和虚假房源标记。

  当 Agent 需要通过一次调用获取周一早上的摘要时，选择此项。

  apartments-pp-cli digest --saved-search austin-2br --since 7d --format md
  

• shortlist — 基于标签的本地候选清单表；可添加、查看、移除房源，并附上备注和标签。

  当 Agent 或用户要整理候选清单时，选择此项；下游命令（如 compare）会读取清单内容。

  apartments-pp-cli shortlist add https://www.apartments.com/example-1234 --tag austin --note "liked the kitchen"
  

汇总统计

• market — 按城市/州和卧室数量统计租金及每平方英尺租金的中位数、p10、p90，以及允许养宠物房源的占比。

  当 Agent 需要根据本地分布判断“这个价格是否合理”时，选择此项。

  apartments-pp-cli market austin-tx --beds 2 --json
  

HTTP 传输

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

发现信号

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

• 捕获覆盖率：0 个 API 条目，占网络条目总数 0 个
• 协议：html-ssr（置信度 95%）
• 生成提示：运行时使用带 Chrome TLS 指纹的 Surf（UsesBrowserHTTPTransport）；所有响应均为 HTML/SSR——使用 html_extract 模式：page 进行提取，无需捕获 clearance cookie；无需常驻浏览器 sidecar；主要提取目标为 schema.org 微数据（meta itemprop=streetAddress|addressLocality|addressRegion|postalCode）以及 data-beds / data-baths / data-maxrent 属性
• 候选命令构想：rentals — 在 apartments.com 上，路径 slug 搜索是主要入口；listing — 房源详情页提取 schema.org 微数据
• 注意事项：防护已启用：Apartments.com（CoStar）采用 Akamai 风格的机器人检测。stdlib HTTP 会返回 403；带 Chrome TLS 指纹的 Surf 可以通过检测。请留意防护升级；未来版本可能需要导入 Chrome clearance cookie 或回退到完整浏览器。

命令参考

listing — 按 URL 或房源 ID 获取单个 Apartments.com 房源详情页，解析租金、卧室数／浴室数、地址、配套设施和宠物政策。

• apartments-pp-cli listing <property_id> — 获取单个 Apartments.com 房源详情页，并解析 schema.org 微数据。

rentals — 按城市、卧室数、浴室数、价格和宠物政策搜索 Apartments.com 租房信息。返回已解析的房源卡片。

• apartments-pp-cli rentals — 在 apartments.com 上执行路径 slug 搜索，并返回从 HTML 响应中解析出的房源卡片。

手写命令

• apartments-pp-cli sync-search <saved-search> — 在 apartments.com 上执行已保存的搜索，并将房源卡片快照保存到本地存储。
• apartments-pp-cli watch <saved-search> — 对比已保存搜索的最新同步结果与上一次结果；输出新增／已移除／价格变动的房源。
• apartments-pp-cli nearby <slug...> — 在多个城市／邮编／社区 slug 上分发搜索，并返回一个排序、去重后的列表。
• apartments-pp-cli value — 按 12 个月的总居住成本（租金 + 宠物租金 + 宠物押金 + 宠物费）对已同步的房源排序。
• apartments-pp-cli rank — 按比例指标（每平方英尺价格或每间卧室价格）对已同步的房源排序。
• apartments-pp-cli compare <url-or-id...> — 将 2–8 个房源整理成宽表，每个房源占一列，并计算每平方英尺价格和配套设施重合度。
• apartments-pp-cli drops — 列出在指定时间范围内最高租金下降 ≥N% 的房源。
• apartments-pp-cli stale — 标记价格和可租状态已连续 N 天未变化的房源，作为虚假房源或卡滞信号。
• apartments-pp-cli phantoms — 显示符合以下任一信号的房源：重新获取时返回 404、从已保存的搜索结果中消失，或连续 ≥45...
• apartments-pp-cli market <city-state> — 汇总已同步的房源：租金和每平方英尺租金的中位数、p10、p90，以及允许宠物的房源占比。
• apartments-pp-cli history <url-or-id> — 查看单个房源的所有观测时间序列，包括租金、可租状态和状态。
• apartments-pp-cli digest — 每周摘要生成器：以一种结构化输出汇总新增、已移除、降价、每平方英尺价格排名靠前、过期和虚假房源。
• apartments-pp-cli floorplans — 按已同步房源中各户型的每平方英尺租金排序。
• apartments-pp-cli must-have <term...> — 通过 FTS5 筛选已同步房源，仅保留配套设施数组包含所有列出词条的房源。
• apartments-pp-cli shortlist — 本地候选清单表，可添加／查看／移除房源，并附加备注和标签。

数据新鲜度约定

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

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

查找合适的命令

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

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示无法确定匹配项，此时请改用 --help 或尝试更具体的查询。

使用示例

三个社区的搬迁搜寻

apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --pets dog --rank sqft --json --select url,addressLocality,maxrent,sqft,price_per_sqft

将三个目标社区的搜索结果合并为一个排序信息流，按房源 URL 去重，并通过 --select 仅保留 Agent 需要的列。

每周租赁 Agent 摘要

apartments-pp-cli digest --saved-search client-rachel --since 7d --format md

为单个客户端搜索汇总新增、已移除、降价、每平方英尺价格排名前 5、过期和虚假房源标记，并生成可直接粘贴到电子邮件中的 Markdown 报告。

带硬性预算限制的总成本筛选

apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,maxrent,pet_rent,total_cost,price_per_sqft

按 12 个月总成本（租金 + 宠物租金 + 宠物押金 + 宠物费用）对已同步的房源排序，并仅筛选出低于预算的房源。

安排看房前进行虚假房源排查

apartments-pp-cli phantoms --json --select url,reason,unchanged_days

三项信号取并集：404、已从已保存的搜索中移除、过期 ≥45 天。预订看房前先筛选候选房源，避免大老远开车去看已出租的房源。

离线 FTS 配套设施交集筛选

apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json --select url,addressLocality,maxrent,amenities

通过路径筛选配套设施，这是 apartments.com 的筛选下拉菜单未提供的功能。对已同步的配套设施数组执行 FTS5 AND 联合查询。

身份验证设置

无需身份验证。

运行 apartments-pp-cli doctor 验证设置。

Agent 模式

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

• 支持管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 支持筛选 — --select 保留一部分字段。带点号的路径可深入嵌套结构；数组则逐项遍历。对于输出冗长的 API，这对精简上下文至关重要：

  apartments-pp-cli listing example-property --agent --select id,name,status
  

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

• 支持离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示输入，每项输入都通过标志传入

• 只读 — 不要使用此 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 有异常之处时，请记录下来：

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

条目会保存在本地 ~/.apartments-pp-cli/feedback.jsonl。除非设置了 APARTMENTS_FEEDBACK_ENDPOINT，且传入了 --send 或 APARTMENTS_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 请求失败时会返回非零状态码，并将 URL + HTTP 状态码记录到 stderr。

命名配置

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

apartments-pp-cli profile save briefing --json
apartments-pp-cli --profile briefing listing example-property
apartments-pp-cli profile list --json
apartments-pp-cli profile show briefing
apartments-pp-cli profile delete briefing --yes

显式传入的标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，让负责内省的 Agent 能在运行时发现它们。

退出代码

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

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 apartments-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文的前置条件
3. 其他任何内容 → 直接使用（将其作为带 --agent 的 CLI 命令执行）

MCP 服务安装

1. 安装 MCP 服务：

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

2. 向 Claude Code 注册：

   claude mcp add apartments-pp-mcp -- apartments-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which apartments-pp-cli 如果未找到，询问用户是否要安装（参见本技能顶部的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

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

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