{
"markdown": "\n\n# 🏠 房哨兵 Housing Sentinel — AI 接入中心\n\n**把中国 12 城官方房产成交数据与进攻/防守市场信号，接入你的 AI Agent 和自动化工作流**\n\nConnect official daily housing-transaction data & market signals for 12 major Chinese cities
to your AI agents and workflows.\n\n[](https://housingsentinel.cn)\n[](#方式-amcp-接入claude--cursor-等推荐)\n[](https://smithery.ai/servers/sdzhuang/housing-sentinel-ai)\n[](./openapi.yaml)\n[](./skills/housing-sentinel/SKILL.md)\n[](#覆盖城市与数据)\n\n**中文** | [English](./README.en.md)\n\n
\n\n---\n\n## 目录\n\n- [这是什么](#这是什么)\n- [覆盖城市与数据](#覆盖城市与数据)\n- [核心概念：进攻/防守市场信号](#核心概念进攻防守市场信号)\n- [快速开始（3 步）](#快速开始3-步)\n - [方式 A：MCP 接入（推荐）](#方式-amcp-接入claude--cursor-等推荐)\n - [方式 B：REST API](#方式-brest-api任意语言--n8n--扣子--dify)\n - [方式 C：Claude Skill](#方式-cclaude-skill方法论--工具一键安装)\n- [API 一览](#api-一览)\n- [示例与模板](#示例与模板)\n- [使用规则与限制](#使用规则与限制)\n- [FAQ](#faq)\n- [English Summary](#english-summary)\n\n## 这是什么\n\n[房哨兵](https://housingsentinel.cn)是一个房产市场数据监控 SaaS：每日自动抓取各市住建局/房管局**官方发布**的住宅成交与库存数据，计算库存去化周期，输出\"防守 / 观察 / 进攻 / 快速进攻\"四档市场信号，帮助购房者和投资者把握交易时机。\n\n本仓库是它的 **AI 接入中心**——通过 MCP、REST API 或 Claude Skill，把这些数据和信号接进 Claude、Cursor、扣子、Dify、n8n 或任何自建 Agent 工作流。**新用户免费试用**：登录生成密钥后，首次调用起 3 天内可查询深圳数据；订阅任一城市解锁对应城市全量数据。\n\n> 📌 本仓库只包含公开接入文档与示例，不包含房哨兵实现代码。\n\n## 覆盖城市与数据\n\n**12 城**：深圳 · 上海 · 北京 · 广州 · 杭州 · 南京 · 苏州 · 无锡 · 成都 · 重庆 · 东莞 · 厦门\n\n| 数据项 | 说明 |\n|---|---|\n| 一手/二手住宅网签成交 | 每日（成都/重庆一手为周度官方口径，广州二手为月度官方口径） |\n| 一手/二手住宅库存 | 每日或按官方发布节奏 |\n| 库存去化周期 | 库存 ÷ 月均成交（月），一手/二手分列 |\n| 市场阶段信号 | 防守 / 观察 / 进攻 / 快速进攻（阈值随城市返回） |\n\n数据每日更新一次（北京时间 07:00–23:59 各城市不同）。\n\n## 核心概念：进攻/防守市场信号\n\n判断框架以**二手住宅库存去化周期**为核心：\n\n| 去化周期 | 市场阶段 | 含义 |\n|---|---|---|\n| ≥ 18 月 | 🔴 防守期 | 供过于求，房价下行风险大，观望 |\n| 12 – 18 月 | 🟠 观察期 | 止跌企稳中，备好资源不急买 |\n| 8 – 12 月 | 🔵 进攻/买入期 | 供需趋衡，可挑核心区笋盘 |\n| < 8 月 | 🟢 快速进攻期 | 供不应求，优质盘大概率上涨 |\n\n无去化周期数据的城市降级为月成交量判断（荣枯线/暴涨线，各城市阈值不同，见 `GET /api/v1/cities`）。一手与二手信号矛盾时，以二手为准。\n\n## 快速开始（3 步）\n\n1. **登录**：在 [housingsentinel.cn](https://housingsentinel.cn) 或微信小程序\"房哨兵\"登录（想解锁全部 12 城可订阅任意城市或全国套餐；不订阅也有 3 天深圳免费试用）\n2. **取密钥**：登录后进入 **我的 → 接入 AI Agent**，生成 API Key（`hs_live_...`）\n3. **接入**（任选其一）：\n\n### 方式 A：MCP 接入（Claude / Cursor 等，推荐）\n\n零安装——房哨兵 MCP 是远程服务，填 URL + 密钥即用。\n\n**Claude Code 一条命令：**\n\n```bash\nclaude mcp add --transport http housing-sentinel https://api.housingsentinel.cn/mcp \\\n --header \"Authorization: Bearer hs_live_你的密钥\"\n```\n\n**Claude Desktop / Cursor 配置文件：**\n\n```json\n{\n \"mcpServers\": {\n \"housing-sentinel\": {\n \"type\": \"http\",\n \"url\": \"https://api.housingsentinel.cn/mcp\",\n \"headers\": { \"Authorization\": \"Bearer hs_live_你的密钥\" }\n }\n }\n}\n```\n\n然后直接问你的 AI：\n\n> **\"厦门现在是什么市场阶段？该进攻还是防守？\"**\n> **\"对比一下我订阅的所有城市，哪个最接近买入期？\"**\n> **\"分析深圳近90天二手去化周期趋势\"**\n\nMCP 工具：`list_cities` · `get_market_signal` · `get_metrics` · `get_history`\n\n### 方式 B：REST API（任意语言 / n8n / 扣子 / Dify）\n\n```bash\ncurl https://api.housingsentinel.cn/api/v1/signals \\\n -H \"Authorization: Bearer hs_live_你的密钥\"\n```\n\nOpenAPI 3.0 描述文件：[`openapi.yaml`](./openapi.yaml) —— 可直接导入**扣子（Coze）插件、Dify 自定义工具、n8n、Custom GPT Actions**。\n\n### 方式 C：Claude Skill（方法论 + 工具，一键安装）\n\n[`skills/housing-sentinel/SKILL.md`](./skills/housing-sentinel/SKILL.md) 让你的 Claude 掌握完整的\"库存去化周期进攻/防守判断框架\"——不只是会调 API，还知道**怎么解读**：二手优先原则、趋势重于水平、各城市口径差异、回答规范。\n\n```bash\n# Claude Code 安装（复制到项目 skills 目录）\nmkdir -p .claude/skills/housing-sentinel\ncurl -o .claude/skills/housing-sentinel/SKILL.md \\\n https://raw.githubusercontent.com/SheldonZhuang/housing-sentinel-ai/main/skills/housing-sentinel/SKILL.md\n```\n\n## API 一览\n\n| 端点 | 说明 |\n|---|---|\n| `GET /api/v1/signals` | **主接口**：全部已订阅城市当前信号快照 |\n| `GET /api/v1/cities/{city}/signal` | 单城市当前信号 |\n| `GET /api/v1/cities/{city}/metrics?from=&to=` | 逐日指标时间序列（趋势分析，默认近90天） |\n| `GET /api/v1/cities/{city}/history?from=&to=` | 原始日度成交/库存数据（单次最多400条） |\n| `GET /api/v1/cities` | 已订阅城市列表 + 阈值元数据 |\n\n城市代码用拼音全拼（`xiamen`、`shenzhen`…）。完整字段定义见 [`openapi.yaml`](./openapi.yaml)。\n\n**信号响应示例**（节选）：\n\n```json\n{\n \"cityCode\": \"xiamen\", \"city\": \"厦门\", \"dataDate\": \"2026-07-12\",\n \"phase\": \"观察期\", \"phaseSource\": \"cycle\",\n \"secondHand\": { \"inventoryCycle\": 13.4, \"inventory\": 25495, \"avgMonthly\": 1901 },\n \"firstHand\": { \"inventoryCycle\": 29.1, \"inventory\": 21058, \"avgMonthly\": 723 },\n \"thresholds\": { \"cycleDefense\": 18, \"cycleWatch\": 12, \"cycleBuy\": 8 }\n}\n```\n\n## 示例与模板\n\n| 文件 | 场景 |\n|---|---|\n| [`examples/python-example.py`](./examples/python-example.py) | Python 拉取全城市信号 + 阶段跨越检测（可挂 cron） |\n| [`examples/n8n-daily-alert.json`](./examples/n8n-daily-alert.json) | n8n 工作流：每天 8 点巡检，阶段跨越推送企业微信（导入即用） |\n| [`examples/claude-agent.md`](./examples/claude-agent.md) | Claude Code 房产投资监控 subagent 定义 + 每日自动巡检 |\n\n## 使用规则与限制\n\n| 项目 | 说明 |\n|---|---|\n| **数据授权** | **API 数据仅限订阅者/试用者本人使用，不得对外提供数据服务** |\n| 认证 | `Authorization: Bearer hs_live_...`；密钥可在\"接入 AI Agent\"页随时重置（旧密钥即刻失效） |\n| **免费试用** | 无订阅账号首次调用起 **3 天**内可查深圳；历史数据限最近 30 天；到期返回 403（`TRIAL_EXPIRED`） |\n| 限流 | 订阅 60 次/分钟、2000 次/天；试用 10 次/分钟、100 次/天（按账号计，重置密钥不重置限额） |\n| 轮询建议 | 数据每日更新一次，**建议轮询间隔 ≥ 1 小时** |\n| 权限 | 订阅用户返回订阅中城市；试用期仅深圳；订阅到期/试用结束返回 403，订阅或续费即恢复 |\n| 免责 | 信号为基于官方成交数据的市场时机参考，不构成投资建议 |\n\n本仓库的文档与示例代码可自由用于接入房哨兵服务；房哨兵名称、判断框架内容与数据服务的权利由 housingsentinel.cn 保留。\n\n## FAQ\n\n**Q：不订阅能试用吗？**\n可以。登录后生成 API Key，首次调用起 **3 天内可免费查询深圳数据**（含信号、指标序列与最近 30 天原始数据，限 10 次/分、100 次/天）。也可以在 [housingsentinel.cn](https://housingsentinel.cn) 免费查看各城市的当日/本月成交数据。订阅任一城市解锁对应城市全量数据与更高限额。\n\n**Q：密钥泄露了怎么办？**\n登录后到\"我的 → 接入 AI Agent\"点\"重置密钥\"，旧密钥立即失效，把新密钥更新到 Agent 配置即可。\n\n**Q：为什么成都/重庆的一手去化周期是 null？**\n这两城的一手官方口径为周度成交 + 当月批准上市套数（并非累计可售库存），计算去化周期会产生误导，故诚实地返回 null；判断请看二手指标与成交量。\n\n**Q：数据来源可靠吗？**\n全部来自各市住建局/房管局官方发布渠道，每日自动抓取，多重兜底校验（详见产品内说明）。\n\n**Q：想要的城市不在列表里？**\n到官网提交城市需求，订阅需求量是我们开新城的首要依据。\n\n## English Summary\n\n**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**.\n\n**Getting started:** log in at [housingsentinel.cn](https://housingsentinel.cn) → generate an API key under **My → AI Agent** → connect via the remote MCP server (`https://api.housingsentinel.cn/mcp`, Bearer auth) or REST (`/api/v1/signals`, spec in [`openapi.yaml`](./openapi.yaml)). New users get a **free 3-day trial of Shenzhen data** starting from the first API call — no subscription required. A ready-made [Claude Skill](./skills/housing-sentinel/SKILL.md) teaches your agent both the API and the decision framework.\n\nData updates daily; rate limits 60 req/min & 2,000 req/day for subscribers (10 req/min & 100 req/day during trial); data is licensed for the subscriber's/trial user's own use only — redistribution as a data service is prohibited.\n\n---\n\n\n\n**[开始接入 →](https://housingsentinel.cn)** ｜ 问题反馈请提 [Issue](https://github.com/SheldonZhuang/housing-sentinel-ai/issues)\n\n*让 AI 帮你盯住每一个买入时机。*\n\n
\n",
"bytes": 7262,
"sha": "af18a334ee7d9253ef1877a2e9a4084062f0a4d592e9e9fc1719feb452f1af71",
"repo_slug": "sheldonzhuang/housing-sentinel-ai",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_cn_housingsentinel_housing_sentinel_e94dc4da/readme"
}