housing-sentinel

---

目录

• 这是什么
• 覆盖城市与数据
• 核心概念：进攻/防守市场信号
• 快速开始（3 步）
  • 方式 A：MCP 接入（推荐）
  • 方式 B：REST API
  • 方式 C：Claude Skill
• API 一览
• 变化驱动：since / ETag 与 Webhook
• MCP Prompts 与 Resources
• npm stdio 包
• 接入配方 recipes/
• 示例与模板
• 使用规则与限制
• FAQ
• English Summary

这是什么

房哨兵是一个房产市场数据监控 SaaS：每日自动抓取各市住建局/房管局官方发布的住宅成交与库存数据，计算库存去化周期，输出"防守 / 观察 / 进攻 / 快速进攻"四档市场信号，帮助购房者和投资者把握交易时机。

本仓库是它的 AI 接入中心——通过 MCP、REST API 或 Claude Skill，把这些数据和信号接进 Claude、Cursor、扣子、Dify、n8n 或任何自建 Agent 工作流。新用户免费试用：登录生成密钥后，首次调用起 3 天内可查询全部 12 城；试用结束后深圳当前信号永久免费；点数包 ¥39/1000 次或订阅解锁全量。无需密钥的公开端点 GET /api/v1/cities/{city}/card 可直接拿到任一城市当日成交与市场档位。

📌 本仓库只包含公开接入文档与示例，不包含房哨兵实现代码。

覆盖城市与数据

12 城：深圳 · 上海 · 北京 · 广州 · 杭州 · 南京 · 苏州 · 无锡 · 成都 · 重庆 · 东莞 · 厦门

数据项	说明
一手/二手住宅网签成交	每日（成都/重庆一手为周度官方口径，广州二手为月度官方口径）
一手/二手住宅库存	每日或按官方发布节奏
库存去化周期	库存 ÷ 月均成交（月），一手/二手分列
市场阶段信号	防守 / 观察 / 进攻 / 快速进攻（阈值随城市返回）

数据每日更新一次（北京时间 07:00–23:59 各城市不同）。

核心概念：进攻/防守市场信号

判断框架以二手住宅库存去化周期为核心：

去化周期	市场阶段	含义
≥ 18 月	🔴 防守期	供过于求，房价下行风险大，观望
12 – 18 月	🟠 观察期	止跌企稳中，备好资源不急买
8 – 12 月	🔵 进攻/买入期	供需趋衡，可挑核心区笋盘
< 8 月	🟢 快速进攻期	供不应求，优质盘大概率上涨

无去化周期数据的城市降级为月成交量判断（荣枯线/暴涨线，各城市阈值不同，见 GET /api/v1/cities）。一手与二手信号矛盾时，以二手为准。

快速开始（3 步）

1. 登录：在 housingsentinel.cn 或微信小程序"房哨兵"登录（不订阅也有 3 天全 12 城免费试用，之后深圳当前信号永久免费；点数包 ¥39/1000 次/30 天；订阅单城市或全国套餐解锁完整历史与更高限额）
2. 取密钥：登录后进入 我的 → 接入 AI Agent，生成 API Key（hs_live_...）
3. 接入（任选其一）：

方式 A：MCP 接入（Claude / Cursor 等，推荐）

零安装——房哨兵 MCP 是远程服务，填 URL + 密钥即用。

Claude Code 一条命令：

claude mcp add --transport http housing-sentinel https://api.housingsentinel.cn/mcp \
  --header "Authorization: Bearer hs_live_你的密钥"

Claude Desktop / Cursor 配置文件：

{
  "mcpServers": {
    "housing-sentinel": {
      "type": "http",
      "url": "https://api.housingsentinel.cn/mcp",
      "headers": { "Authorization": "Bearer hs_live_你的密钥" }
    }
  }
}

然后直接问你的 AI：

"厦门现在是什么市场阶段？该进攻还是防守？" "对比一下我订阅的所有城市，哪个最接近买入期？" "分析深圳近90天二手去化周期趋势"

MCP 工具：list_cities · get_market_signal · get_metrics · get_history

方式 B：REST API（任意语言 / n8n / 扣子 / Dify）

curl https://api.housingsentinel.cn/api/v1/signals \
  -H "Authorization: Bearer hs_live_你的密钥"

OpenAPI 3.0 描述文件：openapi.yaml —— 可直接导入扣子（Coze）插件、Dify 自定义工具、n8n、Custom GPT Actions。

方式 C：Claude Skill（方法论 + 工具，一键安装）

skills/housing-sentinel/SKILL.md 让你的 Claude 掌握完整的"库存去化周期进攻/防守判断框架"——不只是会调 API，还知道怎么解读：二手优先原则、趋势重于水平、各城市口径差异、回答规范。

# Claude Code 安装（复制到项目 skills 目录）
mkdir -p .claude/skills/housing-sentinel
curl -o .claude/skills/housing-sentinel/SKILL.md \
  https://raw.githubusercontent.com/SheldonZhuang/housing-sentinel-ai/main/skills/housing-sentinel/SKILL.md

API 一览

端点	说明
GET /api/v1/signals	主接口：全部已订阅城市当前信号快照
GET /api/v1/cities/{city}/signal	单城市当前信号
GET /api/v1/cities/{city}/metrics?from=&to=	逐日指标时间序列（趋势分析，默认近90天）
GET /api/v1/cities/{city}/history?from=&to=	原始日度成交/库存数据（单次最多400条）
GET /api/v1/cities	已订阅城市列表 + 阈值元数据
POST/GET /api/v1/webhooks、DELETE /api/v1/webhooks/{id}、POST /api/v1/webhooks/{id}/test	Webhook 管理（试用/点数包/订阅/机构版）

城市代码用拼音全拼（xiamen、shenzhen…）。完整字段定义见 openapi.yaml。

信号响应示例（节选）：

{
  "cityCode": "xiamen", "city": "厦门", "dataDate": "2026-07-12",
  "phase": "观察期", "phaseSource": "cycle",
  "secondHand": { "inventoryCycle": 13.4, "inventory": 25495, "avgMonthly": 1901 },
  "firstHand":  { "inventoryCycle": 29.1, "inventory": 21058, "avgMonthly": 723 },
  "thresholds": { "cycleDefense": 18, "cycleWatch": 12, "cycleBuy": 8 }
}

变化驱动：since / ETag 与 Webhook

数据每天更新一次，没必要每次都解析全量。

轮询（所有层级可用）：首次调 GET /api/v1/signals，之后带上次响应的 nextSince：

curl "https://api.housingsentinel.cn/api/v1/signals?since=2026-09-30T00:00:00.000Z" \
  -H "Authorization: Bearer hs_live_xxx" -H 'If-None-Match: W/"上次的ETag"'

• 带 since 时只返回该时间后有数据变动的城市，响应多出 since、changedSince（变动城市代码数组）、nextSince（下次用）；每个城市对象带 updatedAt。非法 since 返回 400 BAD_SINCE。
• /signals 与 /cities/{city}/signal 返回弱 ETag，带 If-None-Match 且没变化时返回 304。
• 完整脚本：recipes/polling-etag.sh、recipes/n8n-signals-since.json。

Webhook（试用/点数包/订阅/机构版；免费层与演示密钥返回 403）：

curl -X POST https://api.housingsentinel.cn/api/v1/webhooks \
  -H "Authorization: Bearer hs_live_xxx" -H "Content-Type: application/json" \
  -d '{"url":"https://your.domain/hs-webhook","cities":["shenzhen"],"events":["data.updated","phase.changed"]}'
# → 201，响应里的 secret（whsec_...）只返回这一次

• 事件：data.updated（城市有新数据）、phase.changed（市场阶段变化，额外带 previousPhase/phase）；服务端每 5 分钟检测一次。
• 请求体 { id, event, createdAt, cityCode, signal }，signal 与 /cities/{city}/signal 响应相同。
• 请求头 X-HS-Event、X-HS-Delivery、X-HS-Signature: t=<unix秒>,v1=<hex>，v1 = HMAC-SHA256(secret, "<t>.<原始请求体>")。
• 要求：url 必须 https（拒绝内网/回环地址）；5 秒内返回 2xx，不跟随重定向；连续失败 10 次自动停用（POST /webhooks/{id}/test 成功可重新激活）；每账号最多 5 个；订阅/试用过期后停推。
• 验签示例：Node.js / Python。

MCP Prompts 与 Resources

MCP server 1.3.0 在 4 个工具之外提供：

类型	名称	说明
Prompt	daily_brief	每日房市简报；参数 cities 可选，逗号分隔
Prompt	compare_cities	多城市对比；参数 cities
Resource	housing://llms.txt	接入说明（与 llms.txt 相同）
Resource	housing://thresholds	各城市判档阈值（JSON）

npm stdio 包

只支持 stdio 的 MCP 客户端可以用 housing-sentinel-mcp，它把 stdio 消息原样转发到远程 MCP：

{ "mcpServers": { "housing-sentinel": { "command": "npx", "args": ["-y", "housing-sentinel-mcp"], "env": { "HOUSING_SENTINEL_API_KEY": "hs_live_xxx" } } } }

中国大陆网络可在 env 中加 "HOUSING_SENTINEL_URL": "https://housingpi-proxy-anirmyfaea.cn-shanghai.fcapp.run/mcp"。

接入配方 recipes/

recipes/ 里每个文件都可以直接复制：Claude Code 每日 08:00 简报、Claude Desktop/Cursor 配置、n8n since+ETag 轮询、扣子工作流、Dify OpenAPI 导入、OpenAI Agents SDK、Webhook 验签（Node/Python）、curl 轮询脚本。

示例与模板

文件	场景
examples/python-example.py	Python 拉取全城市信号 + 阶段跨越检测（可挂 cron）
examples/n8n-daily-alert.json	n8n 工作流：每天 8 点巡检，阶段跨越推送企业微信（导入即用）
examples/claude-agent.md	Claude Code 房产投资监控 subagent 定义 + 每日自动巡检

使用规则与限制

项目	说明
数据授权	API 数据仅限订阅者/试用者本人使用，不得对外提供数据服务
认证	Authorization: Bearer hs_live_...；密钥可在"接入 AI Agent"页随时重置（旧密钥即刻失效）
免费试用	无订阅账号首次调用起 3 天内可查全部 12 城；历史数据限最近 30 天
免费层	试用结束后永久：深圳当前信号（/cities /signals /cities/shenzhen/signal、MCP list_cities / get_market_signal），10 次/分、50 次/天；metrics / history 返回 403（FREE_TIER_LIMIT）
点数包	¥39 / 1000 次 / 30 天，全部 12 城，历史限最近 90 天；用完或到期回到免费层；不参与推荐返利
公开端点	GET /api/v1/cities/{city}/card 无需密钥：当日成交、当月累计、二手去化周期与市场档位（不含库存原值），60 秒缓存
订阅价格	单城市 ¥299/年，全国 12 城 ¥1888/年（完整历史、60 次/分、2000 次/天）；订阅/点数包入口 housingsentinel.cn/agent（登录后"我的 → 接入 AI Agent"），付款后密钥即刻生效；403/429 响应附 subscribeUrl 与 pricing
机构/企业版	更高限额（300 次/分钟、20000 次/天）、全部城市、多席位，线下签约；联系微信 SheldonZhuang
限流	订阅 60 次/分钟、2000 次/天；点数包 60 次/分钟；试用 10 次/分钟、100 次/天；免费层 10 次/分钟、50 次/天（按账号计，重置密钥不重置限额）
轮询建议	数据每日更新一次，建议轮询间隔 ≥ 1 小时
权限	订阅用户返回订阅中城市；试用期全部 12 城；试用结束后免费层仅深圳当前信号；点数包全部 12 城；订阅到期回到免费层，订阅/购买即恢复
免责	信号为基于官方成交数据的市场时机参考，不构成投资建议

本仓库的文档与示例代码可自由用于接入房哨兵服务；房哨兵名称、判断框架内容与数据服务的权利由 housingsentinel.cn 保留。

FAQ

Q：不订阅能试用吗？ 可以。登录后生成 API Key，首次调用起 3 天内可免费查询全部 12 城（含信号、指标序列与最近 30 天原始数据，限 10 次/分、100 次/天）；试用结束后深圳当前信号永久免费。不想登录也可以直接调公开端点 GET /api/v1/cities/{city}/card。需要更多：点数包 ¥39 / 1000 次 / 30 天（全城市，历史 90 天），或订阅（单城市 ¥299/年，全国 12 城 ¥1888/年，完整历史与更高限额）。

Q：密钥泄露了怎么办？ 登录后到"我的 → 接入 AI Agent"点"重置密钥"，旧密钥立即失效，把新密钥更新到 Agent 配置即可。

Q：为什么成都/重庆的一手去化周期是 null？ 这两城的一手官方口径为周度成交 + 当月批准上市套数（并非累计可售库存），计算去化周期会产生误导，故诚实地返回 null；判断请看二手指标与成交量。

Q：数据来源可靠吗？ 全部来自各市住建局/房管局官方发布渠道，每日自动抓取，多重兜底校验（详见产品内说明）。

Q：想要的城市不在列表里？ 到官网提交城市需求，订阅需求量是我们开新城的首要依据。

English Summary

Housing Sentinel provides official daily housing-transaction data and offense/defense market signals for 12 major Chinese cities (Shenzhen, Shanghai, Beijing, Guangzhou, Hangzhou, Nanjing, Suzhou, Wuxi, Chengdu, Chongqing, Dongguan, Xiamen). Signals are derived from second-hand inventory absorption cycles: ≥18 months = defense, 12–18 = watch, 8–12 = buy, <8 = strong buy.

Getting started: log in at housingsentinel.cn → generate an API key under My → AI Agent → connect via the remote MCP server (https://api.housingsentinel.cn/mcp, Bearer auth; or npx -y housing-sentinel-mcp for stdio clients) or REST (/api/v1/signals, spec in openapi.yaml). New users get a free 3-day trial of all 12 cities starting from the first API call, and Shenzhen’s current signal stays free forever afterwards — no subscription required. A public no-key endpoint GET /api/v1/cities/{city}/card returns any city’s latest transactions and market phase. A ready-made Claude Skill teaches your agent both the API and the decision framework. Change-driven access: /signals?since= + ETag/304, and HMAC-signed webhooks (data.updated / phase.changed). Copy-paste integrations live in recipes/.

Data updates daily; rate limits 60 req/min & 2,000 req/day for subscribers (credit pack ¥39 / 1,000 calls / 30 days; 10 req/min & 100 req/day during trial; 10 req/min & 50 req/day on the free tier); data is licensed for the subscriber's/trial user's own use only — redistribution as a data service is prohibited.

---