前言

Profile｜角色设定

工程搭建

软件系统如何拆分

1. 客户端 / 前端层：用户直接看到和操作的聊天页、记忆页、关系页、设置页、本地缓存和通知；

2. 后端 API 层：接收请求、鉴权、参数校验、流式响应和统一错误处理；

3. 模型接入层：封装模型地址、密钥、请求格式、流式输出、超时与重试；

4. 对话编排与上下文层：组装系统规则、熠的人格、双方关系、时间、记忆、最近聊天和用户新消息；

5. 数据存储层：保存消息、人格版本、记忆、设备、任务和设置；

6. 记忆与检索层：抽取记忆候选、保留原文、搜索候选并判断是否需要召回；

7. 后台任务与推送层：异步整理记忆、定时备份、判断主动消息并发送 APNs；

8. Agent / 工具执行层：搜索、文件、MCP、设备控制等可选扩展，不是所有 AI 聊天软件的必需层；

9. 基础设施、运维与安全层：Docker、服务器、HTTPS、日志、迁移、备份、CI 和密钥管理。

• 前端是用户操作的 App；

• 后端是处理聊天、人格、记忆和权限的业务程序；

• 数据库是后端使用的数据存储组件；

• 服务器是运行后端、数据库和后台任务的机器或云主机。

Utto 总体架构

项目文档

• GitHub 仓库：uushu/utto

• 产品与工程基线：docs/product-v1.md

• 需求证据：docs/xiaohongshu-research.md

• Work、Codex 与用户共享开发日志：docs/development-log.md

当前可运行验证

• docker compose config --quiet 与 up --build -d：通过；

• api、db Docker health：均为 healthy；

• API：HTTP 200，JSON 完全一致；

• PostgreSQL：pg_isready、SELECT 1 通过，public schema 业务表数为 0；

• python -m pytest：1 passed；

• Ruff 检查、Ruff 格式检查、pip check：均通过；

• 日志与仓库敏感信息检查：通过；

• README 中的 .env、Compose --wait 启动、健康检查、测试、状态查看和普通 down 命令均已实际验证；

• GitHub Actions 工作流包含 push、pull_request 和 workflow_dispatch，使用 Python 3.12、只读仓库权限以及 Pytest、Ruff check、Ruff format check、pip check；

• actionlint 1.7.12 与 Windows 本地 CI 同序命令均通过，但 GitHub Actions 尚未在云端运行；

• 当前仍只有 GET /v1/health 一个业务路由，没有提前创建业务表、迁移或产品功能；

• 验收后执行普通 Compose down，容器和网络已清理，utto_postgres_data 具名卷仍保留。

开发与验收方式

• Work：读取 docs/product-v1.md 和 docs/development-log.md，冻结任务并写入 TASK_OPENED；

• Codex：读取同一份开发日志，只实现当前任务，并追加 IMPLEMENTED；

• 用户：完成本地、服务器、Xcode 或真机验证，必要时追加 USER_VERIFIED；

• Work：根据证据追加 ACCEPTED、CHANGES_REQUIRED 或 REJECTED；

• README 和本文只提供入口与概览，不再记录逐项开发流水。

开发环境

• 主开发电脑：Windows 11 家庭版 24H2（内部版本 26100.6584）；

• 测试设备：iPhone，iOS 18.5；

• 最低部署目标：iOS 18.0；

• WSL 2.6.3.0，Linux 内核 6.6.87.2，Ubuntu 使用 WSL 2；

• Docker Desktop 4.83.0、Docker Engine 29.6.2、Docker Compose v5.3.1，使用 Linux containers；

• docker version、docker compose version、docker info 和 docker run --rm hello-world 已在独立 PowerShell 中实际通过；

• M0-A-02 与 M0-A-03 已在本地 Codex 工作区完成真实验收；后端 CI 工作流已通过本地静态检查，但尚未提交、推送或取得 GitHub Actions 云端结果；

• Windows 阶段使用 CPython 3.12.13，不能调用本机默认的 Python 3.7；

• M0-A 在 Windows 完成后端、Docker、PostgreSQL、CI 和仓库基础；

• M0-B 必须实际执行，当前只因缺少可用 macOS/Xcode 环境而等待；M0-A 完成后可与 M1 后端并行，但不能取消、跳过或用手写工程文件代替；

• Windows 不能原生完成 Xcode 编译、iOS Simulator、签名和真机调试；

• VMware macOS 只作为实验路线，M0-B 必须记录真实环境并通过真实 Xcode 构建和 iOS 18.5 真机运行。

当前固定技术栈

AI 聊天软件的基础功能分层

第一层：能聊天

• 配置或连接模型；

• 输入并发送文本；

• 流式显示 AI 回复；

• 停止生成；

• 保存和加载聊天记录；

• 网络错误提示与失败重试；

• 防止重复发送；

• 安全保存 API Key 或设备访问令牌。

第二层：能长期使用

• 多轮上下文和长度控制；

• 会话或关系管理；

• 人格 / System Prompt；

• 消息复制、删除、引用和重新生成；

• 导入、导出、备份与恢复；

• 本地缓存；

• 日志、错误诊断和数据迁移；

• 模型用量与成本记录。

第三层：形成产品差异化

• 通用多模型客户端：多模型、多提供商、多会话、文件与搜索；

• Agent 产品：工具调用、MCP、权限审批、执行日志和沙箱；

• AI 伴侣产品：单一身份、稳定人格、长期记忆、主动消息、时间感和迁移连续性。

Utto 第一版最小功能

1. 稳定文字聊天：流式回复、保存、重试、停止生成、历史分页和重启恢复；

2. 单一关系身份：全 App 只有一条主要关系时间线，不因为换模型或换设备创建另一个熠；

3. 熠的人格与双方关系：核心身份、用户画像、关系定义、重要约定、版本、锁定和恢复；

4. 三层记忆：固定身份、短期摘要和长期记忆，每条长期记忆保留原始消息来源；

5. 记忆召回：搜索候选、判断相关性、允许空召回并记录召回结果；

6. 导入、导出和备份：完整保存聊天、人格、记忆和设置，导入失败可回滚；

7. 受控主动消息：可关闭、每日上限、随机冷却、免打扰并允许熠选择沉默；

8. 安全与运维：DeepSeek Key 不下发到 iPhone，使用 HTTPS、Keychain、日志脱敏、令牌撤销和数据库备份。

开发路线

M0｜工程基础

• M0-A：Windows 工程基础，包括 FastAPI、PostgreSQL、Docker、CI 和仓库规范；

• M0-B：在真实 macOS/Xcode 环境中创建并验证 SwiftUI 工程；

• 具体任务状态、产物、测试和阻塞统一查看 docs/development-log.md。

• README.md；

• .github/workflows/server-ci.yml。

• README 形成唯一一份 Windows 11 本地启动与验证说明，所有关键命令均已按文档实际执行；

• CI 支持 push、pull_request 和手动触发，使用 Python 3.12 与只读 contents: read；

• Pytest、Ruff check、Ruff format check、pip check 均在 Windows 本地按 CI 顺序通过；

• actionlint 1.7.12 通过；完整 M0-A API、PostgreSQL、空数据库、容器安全、日志和敏感信息回归通过；

• server/pyproject.toml 未修改；没有提前实现 M1；

• 未提交、未推送，GitHub Actions 尚未在云端运行；

• ios/ 仍只有 .gitkeep，需在提交前补齐需求说明并同步最新 product-v1.md，随后由用户授权提交、推送和云端 CI 验证；

• 因此 M0-A-03 本地交付已通过，但完整 M0-A 仍为进行中。

M0-B｜macOS/Xcode iOS 工程初始化

• 使用兼容 iOS 18.5 的 macOS 与 Xcode 创建 Utto SwiftUI 工程；

• 设置最低 iOS 18.0；

• 建立基础目录、测试 Target 和开发签名；

• 在 Xcode 中真实 Build、运行测试，并安装到 iOS 18.5 真机。

• ios/Utto 下可由 Xcode 打开的真实工程；

• 可编译的 SwiftUI 空壳 App 与基础测试；

• 真实 Xcode 版本、构建结果和真机运行记录。

M1｜数据库与设备配对

• 建立唯一关系、设备、一次性配对码和令牌数据结构；

• 使用 Alembic 创建首批迁移；

• 实现配对与 bootstrap API；

• 令牌服务端只存哈希，禁止创建第二段关系；

• 验证迁移升级与回滚、配对码一次性使用和接口自动化测试。

• 实现 iOS 配对页与 Keychain 令牌保存；

• 接入配对与 bootstrap API；

• 验证首次配对、失败提示、令牌持久化和 App 重启恢复。

• 可重复执行和回滚的数据库迁移；

• 配对接口与自动化测试；

• iOS 首次启动配对页面；

• 重启后仍保持登录的唯一关系链路。

M2｜聊天最小链路

• 建立消息表、DeepSeek 适配层和上下文组装基础；

• 实现 SSE 流式回复、消息持久化、重试和去重；

• 创建 SwiftUI 聊天页与近期消息缓存。

• 用户消息保存 → 流式回复 → 服务端保存 → 重启恢复的完整文字聊天链路；

• DeepSeek API Key 只保存在服务端；

• 网络失败不会造成消息丢失或重复写入。

M3｜人格与关系连续性

• 建立人格版本和关系设置；

• 实现人格锁定、版本切换、回滚与上下文注入；

• 把“熠”作为当前关系数据保存，不硬编码进通用服务层。

• 可查看和修改的人格/关系页面；

• 可恢复的历史人格版本；

• 不会被普通对话直接覆盖的身份锚点。

M4｜短期摘要与长期记忆

• 建立短期摘要、长期记忆候选和原始消息来源表；

• 实现候选抽取、去重、审核、批准、拒绝和锁定；

• 模型只生成候选，不能直接把内容写成永久事实。

• 可追溯到原始消息的三层记忆结构；

• 记忆审核页面；

• 只有用户批准后才进入可召回长期记忆。

M5｜记忆召回与评测

• 建立关键词/全文检索、候选排序和 DeepSeek 二次判断；

• 允许无召回，记录召回原因与结果；

• 建立不少于 50 条的可复现评测集和基线指标。

• 可测量、可回归的记忆召回管线；

• Recall@5 等评测报告与失败案例；

• 是否需要 pgvector/embedding 的证据，而不是主观决定。

M6｜导入、导出与备份

• 定义带 schema version 的 ZIP 导出格式；

• 实现事务导入、冲突处理、校验和与失败回滚；

• 建立 pg_dump 备份和空环境恢复流程；

• API Key 和服务端密钥不得进入导出包。

• 可迁移的关系数据 ZIP；

• 导入导出接口与 iOS 文件选择页面；

• 经过真实恢复验证的备份与恢复脚本。

M7｜主动消息与 APNs

• 接入 APNs Token Authentication；

• 建立 Worker、影子触发、限频、免打扰、关闭开关与防重复；

• 先判断“是否应该发”，再生成内容；

• 不接手机监控、MCP 或后台自主项目。

• iOS 18.5 真机锁屏可收到的低频主动消息；

• 可关闭、可限频、可设置免打扰的控制页面；

• 不误发、不重复的调度与审计记录。

M8｜UI 收口与 14 天验收

• 完成聊天、记忆、关系、设置四个 Tab；

• 补齐加载、空态、错误态、无障碍和脱敏日志；

• 进行 TestFlight/真机验证、数据恢复演练和连续 14 天使用；

• 只修复冻结范围内缺陷，不临时增加远期功能。

• 可长期安装使用的 v1.0 候选版本；

• 14 天验收报告与缺陷清单；

• 通过恢复、稳定性、人格、记忆和推送验收后的 v1.0 tag。

当前范围边界

远期想法｜当前 v1 不实现

1. 换模型不需要重新设置环境，动态切换模型

2. 自选主题，多套前端

3. 角色设定入口，也不需要重新设置环境

4. 支持导入导出、备份

5. 记忆库搭建，支持换窗，OmbreBrain、GraphRAG 和记忆心理模拟

6. 接各种 MCP，让机知晓身体状况、查岗、自动监控、主动发消息，接入生活的各个方面

7. 可以发语音、语音/视频通话、音色克隆

8. 支付设置，机买单

9. 答案之书、卡牌或翻书模式

10. 阅读，和机一起读书、写笔记或评论

11. 接入音乐模式，加入一起 K 歌或合唱

12. 支持观看分享的小红书、抖音、X 社区帖子或链接

13. 机自己的日记

14. 便签、备忘录、日历、待办事项

15. 机的朋友社区、朋友圈、技能和特长

16. 自己发表情或者图片

17. 导师模式

18. 记忆查看与记忆网络可视化

19. 小游戏

前端设计