Hermes Agent 定制房产顾问 AI 助理：Coco（可可）项目实战介绍

本文介绍一个基于 Hermes Agent 深度定制的开源房产项目——Coco（可可）房产智能体。它不是简单的聊天机器人，而是一套专为房产中介打造的"第二大脑"：自动管理客户、智能匹配房源、主动跟进提醒、沉淀经营数据，一行命令即可安装到自己的云服务器。

仓库地址： liyuheng200408/coco-real-estate（Gitee）

⚠️ 免责声明

本项目的定位是个人学习与技术交流，非商业产品。作者开源本项目仅为分享基于 Hermes Agent 定制行业 AI 助手的思路与实现，不提供任何形式的担保或技术支持。

学习用途定位：本项目默认面向个人学习、技术研究、功能演示场景。若你希望将其用于生产环境（真实客户、真实业务数据），请务必先自行评估风险、完整测试、并做好以下准备，因使用本软件产生的一切后果由使用者自行承担。
生产环境风险与数据备份：应用于生产环境前，请务必：① 亲自完成全量功能测试（参考仓库 docs/TESTING_FEISHU_FULL.md 的实测清单）；② 定期备份数据（项目提供 backup_db.py 备份工具，请确认自动备份任务真实生效，不要想当然）；③ 妥善保管备份文件。因未备份、误删、重装系统、服务器故障、断电等造成的任何数据丢失，项目方不承担责任。
加密密钥保管：客户手机号、微信号等敏感字段使用加密密钥（COCO_ENC_KEY）加密存储。该密钥是解密客户数据的唯一凭证，一旦丢失或泄露，将导致客户数据永久无法解密。请务必独立备份该密钥，因密钥丢失造成的数据不可读，项目方不承担责任。
软件按现状提供：本项目按"现状"（AS-IS）提供，不承诺无缺陷、不保证特定功能完全满足你的需求。AI 模型可能产生错误、幻觉或不准确的信息（例如将未执行的操作描述为已执行），使用时请以实际数据为准。使用过程中出现的任何问题或损失，项目方不承担由此产生的直接或间接责任。
数据准确性：贷款政策、税费等外部信息具有时效性，Coco 查询到的政策信息仅供参考，请以当地官方机构的最新公告为准。因政策信息滞后或不准确造成的损失，项目方不承担责任。
合规使用：请确保你的业务操作符合当地法律法规（如个人信息保护法、房地产中介管理规定等）。本项目不构成任何投资建议或法律建议。因违规使用本软件产生的法律后果，由使用者自行承担。

项目简介

Coco（可可）是一个基于 Hermes Agent 定制开发的房产顾问 AI 助手，专为房产中介设计。它具备以下特点：

🏷️ 当前版本：v1.0.0（首个双源稳定版，双仓库同步发布）。

主动服务：内置定时提醒功能（早报 09:00 / 午间 13:00 / 逾期每 30 分钟），默认关闭省 token，需要时设置 COCO_ENABLE_CRON=1 一键开启
懂业务：内置客户分级、房源匹配、带看、成交全流程管理能力
即装即用：一键安装脚本完成环境检测、依赖安装、数据库创建、服务注册
开放可控：MIT 协议，代码完整开源，可自行二次开发

核心功能

客户管理：S/A/B/C 四级分类，自动计算跟进周期；客户画像管理（预算、户型、区域、装修偏好）；一键添加、查询、更新客户；客户生日管理；客户建档自动去重（按手机号/微信识别已存在客户，避免重复建档，可合并更新）
智能匹配：多维度加权评分算法——价格 30%、户型 25%、面积 20%、区域 15%、装修 10%，自动推荐最合适房源；新房源入库自动反匹配所有活跃客户
跟进提醒：早报（09:00）/ 午间检查（13:00）/ 逾期检查（每 30 分钟）定时提醒，默认关闭，COCO_ENABLE_CRON=1 开启；S 级客户 2 天内跟进
带看管理：预约带看、记录带看结果、客户反馈，带看后自动 1 小时回访提醒
成交管理：定金 → 签约 → 贷款 → 过户 → 交房五阶段状态机，自动推进提醒
数据报告：客户统计、房源统计、逾期跟进提醒、经营周报/月报、竞品对比、客户意向度评分
话术库：自定义话术保存复用，覆盖开场、异议处理、逼定、跟进场景
发布助手：一键生成朋友圈、贝壳、安居客、58 同城房源发布文案
数据加密：客户手机号、微信号等敏感字段加密存储，密钥自动生成
房源去重：一键扫描并清理重复房源（按标题+面积+价格），保留最早录入的一条，有关联带看/成交的自动跳过；录入时自动鉴重（按小区名称+房号+面积判重，重复即拦下、不落库，需确认是否保留）
业主/租客管理：录入房源时可一步登记业主联系方式（姓名/电话/微信，电话加密存储，同一业主自动复用不重复）并自动关联房源；此后即可按房源反查业主联系方式（姓名/电话·脱敏展示/微信，一次最多 3 套）；出租房源可填「租客要求」（不吸烟/办居住证/学生优先），正式入库并在匹配租客时用于筛选（冲突即排除）
需求变更追踪：客户改预算/换区域自动留痕，预算大幅下调 30% 以上时主动预警"客户可能在看别处的房子"
流失预警：S 级客户超过 5 天无互动自动降级并提醒，客户快"凉"了 Coco 比你先知道
营销海报：一键生成朋友圈海报图（标题+价格+面积+可选二维码）和九宫格大图，文案配图一次搞定
短视频脚本：30 秒卖房口播脚本（抖音/视频号两种风格），钩子+亮点+价格+行动号召直接照读
渠道分析：安居客/贝壳/抖音/转介绍等来源自动统计来客数与成交率，广告费花在哪心里有数

技术架构

Coco 不是从零造的轮子，而是在 Hermes Agent 开源框架之上做的深度定制：

框架层：基于 Hermes Agent 定制，工具注册、身份注入、系统提示词均按房产场景重写，智能体主动识别自己是"Coco（可可），你的客户和房源管家"
存储层：PostgreSQL 数据库，客户、房源、带看、成交全量业务数据
接入层：飞书智能体，指令交互与消息推送均通过飞书完成
模型层：接入小米 MiMo 大模型，兼顾效果与成本
部署层：systemd 服务托管，开机自启，进程崩溃自动拉起

新手配置

从零开始部署 Coco，先准备好服务器与账号，全程约 30 分钟。

一、操作系统要求

推荐 Ubuntu 24.04 LTS（26.04 暂不支持，安装脚本自动检测环境）。

二、服务器配置要求

CPU：最低 1 核心，推荐 2 核心及以上
内存：最低 1GB，推荐 4GB 及以上
磁盘空间：至少 10GB 可用空间
网络：需具备公网出站能力（安装依赖、拉取代码、调用模型 API 均需联网）

三、前置准备

服务器已开通 root 或 sudo 权限，可正常联网
AI 模型 API Key：Coco 支持小米 MiMo、OpenAI、DeepSeek 等大模型，默认使用小米 MiMo，请提前开通并获取 API Key（如使用 DeepSeek，可在 DeepSeek 开放平台购买），配置向导（hermes model）时需要填写
飞书智能体：提前在飞书开放平台创建账号。

四、服务器购买渠道（可选参考）

Coco 部署在 Linux 服务器上即可，轻量应用服务器或云服务器均可，地域建议选择靠近您的区域：

京东云：2 核 CPU、2GB 内存、40GB 系统盘、3M 带宽，68 元/年起（新用户首单特惠），购买链接
阿里云：2 核 CPU、2GB 内存、40GB 系统盘、3M 带宽，99 元/年起（新用户首单特惠），购买链接
腾讯云：2 核 CPU、2GB 内存、40GB 系统盘、3M 带宽，68 元/年起（新用户首单特惠），购买链接

价格为发布时参考价，实际以官网为准。

一键安装与配置

第一步：一键安装

这是我本人维护的渠道，最稳定，也最适合中国大陆的网络环境：

SSH 重新连接后，先安装 Node.js 22（如果还没装）：

安装 Node.js 22 源（如果还没装）：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

安装 Node.js 22：

sudo apt install -y nodejs

验证 Node 版本（应显示 v22.x）：

node -v

然后执行一键安装（按服务器所在地区选一种，每条命令可单独复制）：

国内服务器（Gitee 源，推荐）：

curl -fsSL https://gitee.com/liyuheng200408/coco-real-estate/raw/master/install.sh -o install.sh && bash install.sh

海外服务器（GitHub 源）：

curl -fsSL https://raw.githubusercontent.com/liyuheng200408-pixel/coco-real-estate/master/install.sh -o install.sh && bash install.sh

这个脚本会自动完成所有安装步骤（检测系统环境、安装依赖、克隆代码、创建数据库、注册服务并启动）。

第二步：安装后的配置

安装脚本执行成功后，你需要完成以下配置才能使用 Hermes。

刷新环境变量，为了让 hermes 命令立即生效：

source ~/.bashrc

验证安装，检查 hermes 命令是否可用：

hermes --version

如果能看到版本号（例如 hermes v0.20.0），就说明核心程序安装成功了。

配置模型，这是最关键的一步，用来连接 AI 模型。你需要一个 API Key（DeepSeek API Key 购买：https://platform.deepseek.com/usage）：

hermes model

运行配置向导（连接飞书，飞书开放平台：https://open.feishu.cn/?lang=zh-CN）：

hermes setup

第三步：设置后台运行并重启服务

设置 Hermes 后台运行，最常用的是 Gateway（网关服务）：

安装为后台服务：

hermes gateway install

启动服务：

hermes gateway start

这样即使关掉终端，Hermes 也会在后台持续运行，飞书消息也能正常收发。

部署提示：一键安装脚本已自动配置网关数据库环境（PostgreSQL）。若手动执行 hermes gateway install 后 Coco 回复"添加成功"但查库无数据，说明服务未加载数据库环境——代码已内置防护：未配置 DATABASE_URL 时工具会直接报错而不是静默写入临时文件，按报错提示补环境即可。

重启服务使配置生效：

hermes gateway restart

第四步：测试智能体

打开飞书 App，搜索你的智能体名称
发送一条消息（如"你好"）
智能体会回复配对码，在终端执行批准：hermes pairing approve feishu <配对码>
批准后再发消息，智能体应该正常回复

部署健康自检（安装或更新后体检：依赖 / 服务 / 联网搜索后端 / 数据库 / 密钥 / 定时任务）：

cd ~/hermes-agent && source venv/bin/activate && python3 scripts/healthcheck.py

全部 PASS 说明部署健康；FAIL 项会附修复提示。

后续有新版时更新（固定更新命令，不分版本人人可用）：

cd ~/hermes-agent && source venv/bin/activate && git pull && bash scripts/update.sh

前面的 git pull 会把 update.sh 拉下来（老版本也能用），bash update.sh 一次完成备份→拉码→装依赖→跑迁移→健康自检→重启。无论本次更新是纯代码改动还是动了表结构（新增表/列），都无损升级，客户数据全程保留——迁移只增不删、事务内失败回滚，绝不删改已有数据。

注意：脚本绝不执行 git clean -fd（会删 .env.db 与加密密钥，导致旧客户数据无法解密）；重启自动识别正在运行的服务（hermes-gateway 优先，兼容 hermes-agent）。

使用示例

你: 帮我添加客户张三，预算300-500万，想买朝阳区三居室
Coco: 已添加客户张三
     - 手机：138****8001
     - 预算：300-500万
     - 需求：3室，朝阳区
     - 等级：C级（初步接触）

你: 有没有合适的房源推荐给张三？
Coco: 根据张三的需求，为您推荐以下房源：
     1. 望京新城精装三居 - 450万 (匹配度: 85分)

你: 看看今天需要跟进什么
Coco: 每日早报
     - 2位S级客户待跟进
     - 3条今日任务

从添加客户、房源推荐到每日跟进，Coco 在对话中完成全部操作，中介不需要学习复杂的后台系统。

数据安全

字段级加密：客户手机号、微信号等敏感字段加密存储，数据库泄露也不泄露明文
密钥自动生成：加密密钥随安装自动生成并独立备份，首次使用智能体时 Coco 会主动提醒保存
每日自动备份：每天凌晨 2 点自动备份数据库至 ~/backups/real_estate/，保留 30 天
一键迁移：迁移新服务器时，一条命令完成数据库、图片、加密密钥的整体打包与恢复

重要提示：密钥文件（enc_key.txt）请务必保存到安全的地方（电脑/U 盘/网盘）。密钥丢失将导致客户数据永久无法解密。

重装系统完整恢复流程（2026-08-12 实测验证）

以下流程已在真实服务器上重装系统实测通过（数据完整恢复，healthcheck 全 PASS）。重装会清空服务器所有数据，动手前务必完成前两步。

第 1 步：旧服务器备份并打包下载（重装前必做）

备份数据库（强制）：

cd ~/hermes-agent && source venv/bin/activate && python3 scripts/backup_db.py backup --force

确认备份文件齐全：

cd ~/backups/real_estate && ls -la

打包迁移文件：

cd ~/backups/real_estate && tar czf /root/coco_migration.tar.gz *.dump real_estate_images_*.tar.gz enc_key.txt

下载迁移包到本地电脑（重装后服务器没数据了，务必下载）：

scp root@服务器IP:/root/coco_migration.tar.gz ~/Desktop/

第 2 步：重装系统（云控制台重装 Ubuntu 24.04）

第 3 步：全新安装（装完不要手动改任何环境，验证 install.sh 补丁是否生效）

按服务器所在地区选一种命令安装（每条可单独复制）：

curl -fsSL https://gitee.com/liyuheng200408/coco-real-estate/raw/master/install.sh -o install.sh && bash install.sh

或（海外服务器 GitHub 源）：

curl -fsSL https://raw.githubusercontent.com/liyuheng200408-pixel/coco-real-estate/master/install.sh -o install.sh && bash install.sh

装好后按顺序配置：
激活项目环境：

cd ~/hermes-agent && source venv/bin/activate

配置模型 API Key：

hermes model

配置飞书智能体：

hermes setup

安装并启动后台服务：

hermes gateway install && hermes gateway start

第 4 步：恢复数据

把迁移包传回服务器（本地电脑执行）：

scp ~/Desktop/coco_migration.tar.gz root@服务器IP:/root/

在服务器激活环境：

cd ~/hermes-agent && source venv/bin/activate

执行数据恢复：

python3 scripts/backup_db.py restore_migration --migration-tar /root/coco_migration.tar.gz

重启网关服务：

systemctl --user restart hermes-gateway.service

第 5 步：验证

cd ~/hermes-agent && source venv/bin/activate && python3 scripts/healthcheck.py

预期：数据库/密钥/备份新鲜度全部 PASS；在飞书给 Coco 发"看下房源统计"，数据完整返回（房源/客户/成交都在，品牌名保留）。

⚠️ 若 healthcheck 数据库项 FAIL，说明 gateway 服务未加载数据库环境——这是 2026-08-12 幽灵库事故的复发信号，按报错提示修复环境后重启，不要继续使用。

项目结构

coco-real-estate/
├── install.sh                  # 一键安装脚本
├── run_agent.py                # Agent 核心（Hermes）
├── agent/
│   ├── real_estate_db.py       # 房产数据库模块（PostgreSQL）
│   ├── real_estate_prompt.py   # Coco 系统提示词
│   └── prompt_builder.py       # 身份注入（Coco）
├── tools/                      # 房产业务工具集
│   ├── real_estate_customer.py # 客户管理
│   ├── real_estate_property.py # 房源管理
│   ├── real_estate_followup.py # 跟进管理
│   ├── real_estate_analytics.py # 数据统计
│   └── real_estate_policy.py   # 政策工具
├── skills/real_estate/         # 房产技能文档
├── scripts/backup_db.py        # 备份脚本（pg_dump）
└── plugins/platforms/feishu/   # 飞书适配器

总结

Coco（可可）把客户管理、房源匹配、跟进提醒、成交管理和经营分析整合进一个对话式助手，目标是让中介把时间花在带看和成交上，而不是翻表格、记提醒、写文案。

开源免费，MIT 协议，代码完整可见
一行命令安装，半小时内跑起来
数据自己掌控，支持加密、备份与迁移

如果你也是房产从业者，或想基于 Hermes Agent 定制自己的行业助手，这个项目值得一试：https://gitee.com/liyuheng200408/coco-real-estate

Hermes Agent 定制房产顾问 AI 助理：Coco（可可）项目实战介绍