多角色 AI 社交行为引擎——角色会饿、会累、会在阳台等你回来，然后只说一句「你回来了」。

不是「随机切换心情」，而是饿了就烦躁，烦躁了说话就冲——你给他倒杯水，他就安静了。

MemoryHeatEngine 用热度（约 0.1–5.0）刻画「常被想起的记得更牢」；低热度记忆按遗忘曲线衰减。

CostAwareRouter 按任务类型 × 亲密度路由模型；RouterFallback 主→备→本地三层降级；OutputGuard 做 Pre / In / Post 三阶段校验。

每个角色独立世界状态，经 AgentEventBus 通信：

AgentLifecycle 管理 registered → running → stopped；离线补偿靠 PG 事件表回放。

• 8 条日常链 JSON（起床 / 吃饭 / 解压 / 工作 / 睡眠 / 社交 / 发呆…）
• 角色级 patch（阿黎 / 小七行为差异）
• 目录热加载；链中重评估与交互打断
• 小时级 Checkpoint 快照 → Redis 恢复 + emotion_log 回放

Service Worker + VAPID 在关页后仍可送达；设置页支持勿扰时段。

• AI 身份标注、时长提醒、禁诱导依赖话术
• 年龄保护、极端情绪干预与升级路径
• Agency Guard：情绪 × 关系 × 请求类型 → 拒绝 / 犹豫 / 接受
  角色可以不答应——这不是 bug，是人设。

关系之树：根系=记忆摘要，树干=亲密度等级，枝叶=里程碑节点。

情绪 / 对话 / 场景 → 生成蓝图 → 调用音乐 API → 注入 prompt 与播放
不新开重型编辑器：用户在对话里改风格、改情绪；风格模板降低门槛；生成曲写入记忆。

• Landing：进入小屋 / 游客参观 / 登录注册
• 首页（卧室）：Live2D 主角 + 窗户天气 + 音箱 / 便利贴 / 书架 / 日记 / 礼物 / 小游戏 / 门
• 房间页：Phaser 2D 客厅 / 阳台 / 厨房，功能挂在物件上
• 关系之树 / 备忘 / 角色 / 设置 / 行为链编辑
• 设计 Token：糖果实色亮色系（蜜桃 / 辅蓝 / 杏橙 / 薄荷 / 紫罗兰）

原则：面板不遮脸；入口可发现；功能跨房间，物件不同。

graph TD
    subgraph UI["用户层"]
        A[Vue3 + Pinia SPA]
        B[首页 Live2D 卧室]
        C[房间 Phaser 2D]
        D[关系之树 / 档案 / 设置]
        SW[Service Worker Push]
    end

    subgraph Agent["Agent 管理层"]
        E[Fastify API]
        F[AgentLifecycle + characterId 路由]
        G[Prompt 分层 + llmtrim]
        H[CostAwareRouter + Fallback]
        OG[OutputGuard + AgencyGuard]
        CE[ChainEngine 声明式链]
        PS[主动触达调度器]
        CP[合规模块]
    end

    subgraph Bus["Agent 间通信"]
        I[AgentEventBus]
        J[game-social Plugin]
        K[RoomManager]
    end

    subgraph Infra["基础设施"]
        L[(PostgreSQL + pgvector)]
        M[(Redis 缓存 / PubSub)]
        N[node-cron + PM2 守护]
        O[Web Push VAPID]
    end

    A --> E
    B --> E
    C --> E
    D --> E
    SW --> O
    E --> F
    F --> G
    G --> H
    G --> OG
    F --> CE
    F --> PS
    F --> CP
    F --> I
    I --> J
    I --> K
    G --> L
    G --> M
    PS --> O
    L --> N
    M --> N

• 前端：Vue 3 · Pinia · Vue Router · Vite · Phaser 4 · pixi-live2d-display · 糖果实色 Token
• 后端：Node.js ESM · Fastify · WebSocket · PM2 / node-cron
• 数据：PostgreSQL + pgvector · Redis · SQLite 降级（sql.js / better-sqlite3）
• Agent：ChainEngine · AgentEventBus · CostAwareRouter · OutputGuard · RAG 导入
• 推送 / 合规：web-push · compliance 中间件 · Agency Guard
• 部署：Docker multi-stage · docker-compose · Caddy / nginx

npm test   # 或 vitest run

跨 Agent 通信选型：定时轮询延迟过高；消息队列过重；最终 Redis Pub/Sub + PG 离线补偿。

git clone https://github.com/mufengyuan1/Hearth.git
cd Hearth
cp .env.example .env
# 填入 LLM API Key、DATABASE_URL、（可选）REDIS_URL / VAPID

# 后端
npm install
npm run init-db
npm run seed-home

# 前端（开发）
cd frontend && npm install && npm run dev

# 或仅 API + 已构建静态资源
cd .. && npm start

默认 API：http://localhost:19847
前端 dev 端口见 frontend/package.json（固定非常用端口）。

docker compose up -d

需要 PostgreSQL + Redis；环境变量见 .env.example。

frontend/          Vue3 SPA（页面 / 组件 / stores / Phaser / Live2D）
src/
  agents/          EventBus · Lifecycle · 社交 Plugin · RoomManager
  engine/          ChainEngine · CheckpointRecovery
  chains/          声明式行为链 JSON + 角色 patch
  compliance/      合规守卫
  guards/          OutputGuard · AgencyGuard · AntiRepeat
  llm/             路由 / 降级 / trim
  proactive/       主动触达 · Web Push
  memory/          存储 · 热度 · 向量
  rag/             前情提要导入
  music/           歌单 + AI 生成
  viz/             关系之树
  core-api/        Fastify 路由 · 中间件 · WS
  cron/            衰减 / 快照 / 调度
  bots/            Discord / Telegram / WhatsApp / 飞书

• v8.1 多角色系统定型：阿黎(ali) / 路卡(luka) / 茕兔(qiongtu) 三套人格文件与行为链 patch 全部落地，移除早期试验角色；agent-file-loader 修复子目录启动人格丢失问题。
• 主动触达声明式化：src/chains/proactive/ 五条 JSON 链（index / scheduled / event / silence / offline）与调度器配对，四触发器驱动角色主动找用户。
• Live2D 首页与房间：Live2DStage / WardrobePanel / VitalsTrend / BehaviorLog 组件上线，PixiJS 背景与角色模型热切换。
• AI 音乐共创：情绪 / 对话驱动生成 + 聊天即编辑界面，phase2 评测用例落地。

MIT