像素风 多猫情绪陪伴 iOS App：七只猫在「巷口」陪聊，在「猫窝」攒羁绊与成就，在「里巷」管收藏与设置。
仓库既开源代码，也欢迎直接装上真机玩一玩——最推荐先走 TestFlight，无需自行编译即可体验完整对话、多猫房间与养成。
https://testflight.apple.com/join/zEfxCTZR
- iPhone / iPad 安装 TestFlight
- 用上方链接加入 emocats
- 安装后打开即可体验（演示账号等说明见 docs/TESTFLIGHT_NOTES.md）
本仓库同时提供源码，便于了解端侧多 Agent 编排；若你主要想「用起来」，请优先 TestFlight，不必先搭本地工程。
- 体验：TestFlight 真机包（见上）
- 代码：事件驱动多 Agent 对话编排；主回复走远程 LLM。旁路可尝试本地 Core ML（仍在调试，效果不稳定，失败会 fallback 远程快模型）
| Tab | 名称 | 内容 |
|---|---|---|
| 0 | 巷口 | 多猫闲聊（自动轮换主讲，可用 @ 点名） |
| 1 | 猫窝 | 七猫网格 → 单猫主页 → 单猫房间（深度陪伴 + 养成） |
| 2 | 里巷 | 成就 / 场景 / 简介 / 手账 / 开发沙盒 |
- 会话隔离：巷口
multi与各猫solo:<id>历史分库，避免串台 - 亲密度 / 剧情卡：升档触发专属卡，旁路记账（不进 EventBus）
- 技能系统：规则 Eligibility 候选闸门 + LLM 选型；配置在
roles.json - 安全：
SafetyGate在总线外；危机固定话术不经 LLM；碎纸机内容不进记忆/日志
更多使用说明：docs/USER_MANUAL.md
userInput → SafetyGate
→ EventBus: ContextExtraction ∥ MemoryRetrieval ∥ SkillEligibility
→ PrimaryCharacter (join) → primaryCharacterLocked
├ 主流式回复 (onPrimaryToken，不上总线)
├ SkillAgent ∥ InterjectionAgent（并行，不等主回复全文）
→ ResponseAssembler → responseReady → SafetyGate
→ MemoryUpdate（异步，不挡上屏）
| 设计点 | 说明 |
|---|---|
| EventBus + actor join | Agent 互不直连；禁止 sleep 轮询；可能不触发的分支须显式 nil |
| 读写记忆拆分 | MemoryRetrieval / MemoryUpdate；Update 禁止再调 LLM |
| LLM 路由 | LLMProvider 统一接入；旁路可尝试本地 Core ML（调试中）→ 失败则远程快模型 |
| 粘滞状态 | 放在 RoomSession（跨轮），不在每轮重建的 ConversationContext |
| 依赖克制 | 默认纯 Apple 框架；唯一 SPM 例外：本地 Vendor GRDB |
约定全文：AGENTS.md · 链路说明：docs/CURSOR_IMPLEMENTATION_GUIDE_V7_FULL_AGENT_CHAIN.md
- 平台：iOS 18.5+（兼 iPadOS / macOS / visionOS）
- UI：SwiftUI · 自研像素风组件
- 存储：GRDB（SQLite）— 对话 / AppLog / 向量记忆 / 亲密度等
- 记忆：
NLContextualEmbedding+ 倒排预过滤 + 余弦召回 - LLM：远程主模型（正式体验以此为准）；本地 Core ML 旁路 实验中，效果尚不稳定
- macOS + Xcode（iOS 18.5+ SDK）
- 本地 Core ML 旁路需 真机；模拟器旁路自动走远程快模型
以下内容已在 .gitignore 中排除，克隆仓库后 UI 图会缺失，需自备本地文件（作者本机保留即可）：
| 位置 | 内容 |
|---|---|
emocats/Assets.xcassets/ |
猫头像 / 全身 / 合影背景 / 养成道具 / 技能图标 / Tab 图标 / AppIcon PNG 等 |
emocats/Resources/Brand/ |
品牌图 |
docs/avatar_previews/ |
头像预览导出 |
docs/fullbody_* / docs/sitting_fullbodies/ |
全身 / 坐姿切图与预览 |
docs/gathering_*.png 等 |
合影墙烘焙 / 模拟截图等设计稿 |
对话场景墙本身多为程序化像素绘制（不依赖上述 PNG）；缺素材时头像与合影条等可能空白或占位异常，不影响 Agent / 远程 LLM 主链路调试。
公开仓库保留的是代码与说明文档（见下方「文档索引」），不含商用像素立绘。
cp emocats/Resources/LLMConfig.example.plist emocats/Resources/LLMConfig.plist
# 编辑 remoteAPIKey / remoteBaseURL / remoteModelName / remoteFastModelNameLLMConfig.plist 含密钥，勿提交（见 .gitignore）。
open emocats.xcodeproj重要：本地 Core ML 目前属于调试阶段，效果并不好，不建议作为正式体验路径。
产品主回复仍以 远程 LLM 为准；旁路在本地失败时会 fallback 到远程快模型。
当前问题主要出在 自行实现的 encode（分词 / chat template）→ 定长预测 → 采样 → decode 管线上：无 KV cache 的定长循环、采样与解码对齐等实现细节导致输出不稳定、延迟高或频繁失败。模型转换本身可用，但 端侧推理胶水层仍在修。
模型约 1.7GB，默认不打进 TestFlight / 商店包。源文件放本机 tools/local_llm/out/，不要 git add .mlpackage。
| 方式 | 做法 |
|---|---|
| A · 沙盒（推荐） | 拷到设备 Application Support/emocats/LocalLLM/ |
| B · 开发期内置 | bash tools/local_llm/toggle_resources_model.sh on 后真机 Run；Archive / TF 前务必 off |
双轨说明：tools/local_llm/WORKFLOW.md
emocats/
Core/Agents/ # EventBus 多 Agent 编排
Core/LLM/ # Provider / Router / 本地 Core ML
Core/Memory/ # 向量记忆
Core/Safety/ # SafetyGate（总线外）
Features/ # Chat / Nest / Settings / Alley …
Resources/ # roles.json、配置（密钥与像素 PNG 勿提交）
Assets.xcassets/ # 像素猫/背景/图标等 imageset 已 gitignore，需本地自备
docs/ # 产品 / 技能 / V7 实现指导（预览图目录已 gitignore）
tools/local_llm/ # 本地模型转换与 Resources 开关
AGENTS.md # 给协作者 / Cursor 的硬性约定
| 文档 | 内容 |
|---|---|
| AGENTS.md | Agent 清单与硬性约束 |
| docs/USER_MANUAL.md | 用户操作说明 |
| docs/SKILL_CATALOG.md | 技能目录 |
| docs/EMOTION_DOMAIN_ROUTING_SPEC_V7.md | 情绪 / 领域路由规范 |
| docs/TESTFLIGHT_NOTES.md | TestFlight / 演示账号备注 |
| docs/PRODUCT_IA_P0.md | 产品信息架构 |
- 远程 API Key 仅放本地
LLMConfig.plist，不要提交仓库。 - 危机干预由
SafetyGate固定文案处理，不经 LLM。 mood_shredder（碎纸机）内容不进入对话日志与长期向量记忆。
看完架构说明后，也欢迎装上 App 真实聊几句：
TestFlight 公开测试 → https://testflight.apple.com/join/zEfxCTZR
emocats © 2026 yaundoudou · Ver 1.0
源码与文档由作者保留权利；未经书面许可，请勿将本仓库用于商业再分发或闭源衍生发布。欢迎通过 TestFlight 体验产品、阅读代码学习端侧 Agent 实现。
第三方依赖：GRDB 仍遵循其上游许可证（见该目录内 LICENSE，与 emocats 自身声明相互独立）。