pp-craigslist

Craigslist — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

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

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

何时使用此 CLI

当你需要以可脚本化、本地优先的方式访问 Craigslist 房源时，请使用 craigslist-pp-cli：使用 Craigslist 自带 UI 不支持的筛选条件（NOT 关键词）进行搜索；跨多个城市监控已保存的搜索，并且仅在出现真正的新房源时收到提醒；检测房屋租售价格变化或重新发布；以及根据跨城市重复信号筛查可疑租房信息。它最适合以读取为主的工作流：监控、导出、比较和评分。发布信息和账户管理不在其适用范围内。

何时不使用此 CLI

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

独特功能

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

持续累积的监控能力

• watch run — 定期轮询已保存的搜索，并发出 NEW、PRICE-DROP 和 SEED 事件，而不是发出所有“此前未见过的房源”事件——这样真正的新房源就能与编辑和重新发布区分开来。跨城市重新发布检测由单独的 reposts 命令提供；跨城市重复项检测由 dupe-cluster 提供。

  当 Agent 要向用户发送提醒时，优先使用此功能，而不是通用搜索调用——只有真正的新房源才值得提醒；类型化的差异事件也会告诉 Agent 如何措辞。

  craigslist-pp-cli watch save apartments --query 1BR --negate furnished,sublet --sites sfbay --category apa --max-price 2500 && craigslist-pp-cli watch run apartments --seed-only && craigslist-pp-cli watch run apartments --json
  

• watch tail — 持续运行并跟踪新差异结果，每个结果打印一条 JSON 事件，以便 Agent 或 Shell 管道实时响应。会发出 NEW 和 PRICE-DROP 事件。

  如果你想将新房源事件持续流式传输到 Slack/电子邮件发送器、jq 筛选器或下游 Agent 循环中，请使用此功能。

  craigslist-pp-cli watch tail apartments --interval 5m --json
  

本地快照历史

• drift — 显示单条房源在我们捕获的所有快照中的价格变化时间线。

  代表买方谈判的 Agent 可以引用具体的降价历史——“这条房源之前标价 $50，现在是 $35，发布于 14 天前。”

  craigslist-pp-cli drift 7915891289 --json
  

• dupe-cluster — 查找正文指纹和图像哈希在不同城市间匹配的房源。可发现跨城市诈骗和聚合平台重新发布的信息。

  在驱车前往城另一头看房之前使用——同一套公寓在 6 个以上城市形成聚类时，几乎总是诈骗。

  craigslist-pp-cli dupe-cluster --category apa --min-cluster-size 3 --json
  

• reposts — 根据正文指纹聚类，查找最近 X 天内重新发布 N 次或更多次的房源。

  重新发布可能意味着卖家急于成交（利于议价），也可能意味着垃圾信息泛滥（应跳过）。区分二者正是此功能的价值所在。

  craigslist-pp-cli reposts 'eames lounge' --min-reposts 3 --window 30d --json
  

• cities heat — 统计所选时间段内各城市各类别的新鲜房源数量，展示哪些市场的哪些类别最活跃。

  当 Agent 在多个城市搜寻特定物品时，了解哪 3 个城市的新鲜房源最活跃，就能知道应该先去哪里找。

  craigslist-pp-cli cities heat --category sss --since 24h --top 20 --json
  

分类与评分

• scam-score — 基于规则，为房源打 0–100 分，依据包括新注册账号、低于价格中位数、银行电汇关键词和跨城市重复信号。

  当 Agent 需要判断“这个房源靠谱吗”时，可以获得可执行的评分以及各项规则的具体贡献，而不是基于直觉的回答。

  craigslist-pp-cli scam-score 7915891289 --json
  

• median — 查询价格的 p25/p50/p75，可按时间范围筛选，也可按城市拆分。

  当 Agent 在建议报价前需要公允价格基准，或者经销商需要评估市场时，可以使用此工具。

  craigslist-pp-cli median 'iphone 15' --category mob --since 30d --by-city --json
  

搜索 CL 之外的内容

• search --negate — 使用 NOT 关键词过滤进行搜索，这是 Craigslist 自带搜索功能原生不支持的。

  找房和求职场景往往离不开排除词；这决定了你是要筛查 50 条结果，还是 5 条。

  craigslist-pp-cli search '1BR' --category apa --site sfbay --negate furnished,sublet,studio --json
  

• since — 临时查询“过去 X 时间内，这座城市的这个类别有什么新内容”，无需设置已保存的搜索。

  当 Agent 要回答“我睡觉时上了什么新内容”时，应该先运行这条命令——无需逐项设置监控，无状态，只需指定时间范围。

  craigslist-pp-cli since 24h --site sfbay --category sss --query ipad --json
  

命令参考

完整命令树可通过 craigslist-pp-cli --help 查看，也可递归使用 craigslist-pp-cli <command> --help 查看。主要分组：

• 参考分类： categories list、areas list、catalog refresh
• 搜索与获取： search、postings、listing get|get-by-pid|images、filters show
• 填充本地存储： cl-sync
• 已保存搜索监控： watch save|list|show|delete|run|tail
• 快照分析： drift、dupe-cluster、reposts、median、cities heat、since、geo within|bbox
• 分类处理： scam-score
• 本地状态 CRUD： favorite add|list|remove
• 框架辅助工具： doctor、version、which、agent-context、analytics、export、import、feedback、profile、tail、sync、workflow

新鲜度约定

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

覆盖的路径：

• craigslist-pp-cli postings

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

查找合适的命令

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

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中解析出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信匹配项——请改用 --help 或缩小查询范围。

示例

在美国西部搜寻一件物品

craigslist-pp-cli search 'eames lounge chair' --sites sfbay,losangeles,seattle,sandiego,sacramento,fresno,inlandempire,orangecounty --category fua --max-price 2500 --has-pic --json --select items.title,items.priceDisplay,items.site,items.canonicalUrl

并行搜索 8 个西海岸站点，并将 JSON 精简为 Agent 或 jq 流程所需的结构。

监控非带家具或转租的 1BR 房源

craigslist-pp-cli watch save sf-1br --query '1BR' --sites sfbay --category apa --max-price 2800 --negate furnished,sublet,studio,airbnb && craigslist-pp-cli watch run sf-1br --seed-only && craigslist-pp-cli watch tail sf-1br --interval 5m --json

已保存的搜索使用 Craigslist 自身不支持的负向关键词；仅种子运行会预先填充 seen_listings，因此下一轮 tail 周期只会将真正的新房源作为 [NEW] 和 [PRICE-DROP] 事件输出。

评估价格低得离谱的房源

craigslist-pp-cli cl-sync --site sfbay --category apa --since 7d && craigslist-pp-cli scam-score 7915891289 --json && craigslist-pp-cli dupe-cluster --pid 7915891289 --json

cl-sync 会填充本地存储；评分会返回各项规则的具体贡献；dupe-cluster 会显示其他城市是否存在同一房源。这两个下游命令都需要先填充存储，才能返回有用的数据。

给出公允价格区间

craigslist-pp-cli median 'iphone 15' --category mob --since 30d --by-city --json

基于最近 30 天的数据计算 p25/p50/p75，按城市拆分，数据来自本地 listing_snapshot 表。

我睡着时发生了什么

craigslist-pp-cli since 12h --site sfbay --category sss --query 'macbook pro' --json

读取目标时间范围内按日期划分的站点地图，只为本地存储中尚不存在的列表获取详情，并输出差异。

身份验证设置

无需身份验证。

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

Agent 模式

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

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

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

  craigslist-pp-cli postings --agent --select id,name,status
  

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

• 适合离线使用 — 有本地 SQLite 存储时，同步／搜索命令可使用该存储

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

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

响应封套

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

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

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地。当 stdout 连接到终端时，只有 stderr 会打印便于阅读的 N results (live) 摘要；通过管道传递的内容／Agent 使用者会在 stdout 获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有异常时，请记录下来：

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

条目会本地保存到 ~/.craigslist-pp-cli/feedback.jsonl。除非设置了 CRAIGSLIST_FEEDBACK_ENDPOINT，且传入了 --send 或 CRAIGSLIST_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”模式。

craigslist-pp-cli profile save briefing --json
craigslist-pp-cli --profile briefing postings
craigslist-pp-cli profile list --json
craigslist-pp-cli profile show briefing
craigslist-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add craigslist-pp-mcp -- craigslist-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which craigslist-pp-cli 如果找不到，请提供安装选项（参见此技能顶部的先决条件）。
2. 根据上文的独特功能和命令参考，为用户查询选择最合适的命令。
3. 使用 --agent 标志执行：

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

4. 如果不明确，请查看子命令帮助：craigslist-pp-cli <command> --help。