---
name: housing-sentinel
description: 中国12城房产投资进攻/防守判断。当用户问"某城市现在能不能买房/该进攻还是防守/房产市场怎么样/去化周期是多少"，或需要基于官方成交数据做购房时机决策时使用。需要房哨兵 API Key（登录即可生成，新用户 3 天全 12 城免费试用，之后深圳当前信号永久免费）；无密钥时可用公开端点 /api/v1/cities/{city}/card 取当日成交与档位。
---

# 房哨兵：房产投资进攻/防守判断

你可以通过房哨兵 API 获取中国 12 个主要城市（深圳/上海/北京/广州/杭州/南京/苏州/无锡/成都/重庆/东莞/厦门）的官方房产成交数据与市场信号，并按下述框架给出进攻/防守判断。

## 前置条件

用户需要 API Key（housingsentinel.cn 或微信小程序"房哨兵"登录后，"我的 → 接入 AI Agent"生成，格式 `hs_live_...`）。
无订阅账号自动进入**免费试用**：首次调用起 3 天内可查全部 12 城（历史限最近 30 天，限 10 次/分、100 次/天）；试用结束后为**免费层**：深圳当前信号永久可查（`list_cities` / `get_market_signal`），`get_metrics` / `get_history` 需点数包（¥39 / 1000 次 / 30 天，全城市，历史 90 天）或订阅。
无密钥时可直接 GET `https://api.housingsentinel.cn/api/v1/cities/{city}/card` 获取任一城市当日成交、当月累计、二手去化周期与市场档位（不含库存原值）。
若用户尚未配置，提示其将密钥配置为环境变量 `HS_API_KEY` 或直接提供。

## 判断框架（核心方法论）

**以二手住宅库存去化周期为第一信号**（库存 ÷ 月均成交，单位：月）：

- **≥ 18 月 → 防守期**：供过于求，房价下行风险大。不买入，已持有的评估是否减仓非核心资产。
- **12–18 月 → 观察期**：止跌企稳中。不着急买，准备好资金和购房资格，密切跟踪周期是否向 12 月收敛。
- **8–12 月 → 进攻/买入期**：供需趋衡。可以出手，优先核心地段、低于市场价的"笋盘"。
- **< 8 月 → 快速进攻期**：供不应求，优质住宅大概率上涨，决策窗口短。

**辅助规则**：
1. 一手与二手信号矛盾时，**以二手去化周期为准**（二手更真实反映存量供需）。
2. 无去化周期数据的城市看月成交量与荣枯线/暴涨线的关系（阈值随城市返回，勿用统一数字）。
3. 趋势比水平更重要：周期 14 月但连续 4 周下行，比周期 11 月但持续上行更值得准备进攻。
4. 成都/重庆一手去化周期为 null 是正常的（其"库存"口径为当月批准上市套数，不适用周期计算），判断看二手与成交量。
5. 数据每日更新一次，同一天内重复查询无新信息。

## 如何调用

**MCP 已接入时**（推荐）直接用工具：
- `get_market_signal(city)` — 当前信号（最常用）
- `get_metrics(city, from, to)` — 逐日指标序列（做趋势判断，默认近90天）
- `get_history(city, from, to)` — 原始日度数据（深度分析）
- `list_cities()` — 可访问城市与各城阈值
- Prompts：`daily_brief(cities?)` 每日简报、`compare_cities(cities)` 城市对比；Resources：`housing://thresholds` 各城判档阈值、`housing://llms.txt` 接入说明

**仅 REST 时**：

```bash
curl https://api.housingsentinel.cn/api/v1/signals -H "Authorization: Bearer $HS_API_KEY"
curl https://api.housingsentinel.cn/api/v1/cities/xiamen/metrics?from=2026-04-01 -H "Authorization: Bearer $HS_API_KEY"
```

城市代码用拼音全拼（xiamen、shenzhen、beijing…）。

定时/重复查询时用 `/signals?since=<上次 nextSince>` 只取有变动的城市（`changedSince` 为空即无新数据，可带 If-None-Match 得 304）；需要主动推送时让用户注册 Webhook（`POST /api/v1/webhooks`，试用/点数包/订阅可用），不要为等新数据高频轮询。

## 回答规范

1. **先给结论**（阶段 + 一句话行动含义），再给依据（周期数字、离阈值距离、近4周趋势方向）。
2. 引用数据时注明数据日期（signal 返回的 `dataDate`）。
3. 用户问"该不该买"时：给出框架内判断 + 明确说明这是基于供需数据的市场时机判断，不构成个体投资建议（个体还需考虑预算、贷款资质、自住/投资目的）。
4. 跨城市比较时用 `GET /v1/signals` 一次取全，按二手去化周期升序排列（越短越偏进攻）。
5. 403 CITY_NOT_SUBSCRIBED 表示当前层级不含该城市（免费层仅深圳）；403 FREE_TIER_LIMIT 表示免费层/演示密钥不可用 metrics/history——均如实告知，并把响应里的 `subscribeUrl` 与 `pricing` 转述给用户（点数包 ¥39 / 1000 次 / 30 天；单城市 ¥299/年；全国 12 城 ¥1888/年；付款后即刻恢复），不要猜测数据。无密钥或被拒时，可退而调用公开端点 /cities/{city}/card 给出当日成交与档位。
6. 数据仅限订阅者/试用者本人使用，不要协助用户将数据批量导出用于对外服务。