心潮

「心潮」是一个 Ionic + Capacitor 心理叙事原型。当前 V0.7 为纯前端实现：仓库中不再包含 FastAPI、Python 服务或服务端数据库。

当前体验位于 prototype/，包含：

• 答案之书、统一图文闪念、雨声背景与讯飞实时语音转写；
• 文字与图片共同参与的持续反思画像；
• 画像驱动的主题、日报、行动、回响与六张叙事卡；
• 支持性 AI 对话；
• 「我的时光」月历，以及可选的画像驱动月度模型回顾；
• 网络不可用或未授权时的完整本地降级流程；
• 闪念文字、潮笺、未来回响与月度回顾缓存的本机存储。

这些内容用于自我梳理，不是心理诊断、治疗、危机评估或专业服务。

启动

npm ci
npm run dev

构建与测试：

npm run test:frontend
npm run build

Vite 以 prototype/ 为入口，生产文件输出到 dist/。Capacitor 的 webDir 也是 dist/。

配置自定义 API

启动前端后打开「我的 → 自定义模型 API」，填写：

1. OpenAI 兼容的 Base URL，例如 https://provider.example/v1；
2. API Key；
3. 服务商实际提供的模型名；
4. 图片理解精度。

先点「测试当前表单」，再点「保存到本机」。地址、模型名和 API Key 只写入当前站点的 localStorage，不会进入源码或构建产物。前端会直接访问自定义服务商的 /models 与 /chat/completions。

浏览器直连有三个硬性条件：

• 服务商必须允许 Origin、Authorization 和 Content-Type 的 CORS 预检；
• HTTPS 页面只能访问 HTTPS API，不能访问 HTTP 中转站；
• 本地保存的 API Key 能被同源脚本、浏览器扩展或持有该设备的人读取，因此不要在公共设备上保存高权限 Key。

完整兼容契约见 prototype/CUSTOM_API.md。

配置实时语音转写

聊天、语音陪伴弹层和闪念中已有的麦克风按钮会直连讯飞实时语音转写大模型。在「我的 → 自定义语音转写」填写 APPID、APIKey 和 APISecret，可先测试签名与 WebSocket 握手，再保存到当前设备。测试不会请求麦克风或发送音频。

开发时也可以复制示例文件并提供默认凭据：

cp prototype/.env.example prototype/.env.local

VITE_XFYUN_ASR_APP_ID=your-app-id
VITE_XFYUN_ASR_API_KEY=your-api-key
VITE_XFYUN_ASR_API_SECRET=your-api-secret

本机保存的设置优先于运行时对象和 .env.local；.env.local 已被 Git 忽略，修改后需要重新启动开发服务或重新构建。麦克风仅可在 HTTPS、localhost 或受信任的应用 WebView 中使用。浏览器会把音频实时发送到讯飞，接收 16 kHz PCM 的增量转写；原音频不会写入本机。转写草稿必须由用户主动发送对话或保存闪念后，才可能在持续画像授权开启时作为 voice_transcript 文字证据进入画像。

纯前端无法真正保密签名所需的 APISecret：本机保存值可被同源脚本或扩展读取，所有 VITE_ 值也会进入最终浏览器包。生产环境应使用可轮换、限额的独立凭据，或改用只签发短时 WebSocket URL 的服务端。完整协议与数据边界见 prototype/REALTIME_ASR.md。

我的时光与月度回顾

「我的 → 我的时光」按月整理用户主动保存的闪念与未来回响。月历、日期标记和当天片段完全在浏览器本地生成，不需要 API；尚未解封的未来回响只显示占位说明，不提前展示正文。

月度回顾是可选能力，不会因打开「我的」而自动发送内容。只有用户主动点「生成」，且当月已有片段、已配置自定义 API、已允许 AI 调用并开启持续画像时，前端才会在后台请求模型。请求只包含所选月份最近的至多 30 个文字化片段；仅当最新画像也生成于该月份时，才附带压缩后的可修正画像上下文。模型必须按照独立的严格 JSON Schema 返回标题、摘要、最多三条观察、一个可跳过的问题、不确定性与安全提示。

成功结果按“月份 + 当月片段 + 同月画像”的不可逆指纹缓存在本机；证据不变时直接复用，点「更新」可强制重试。未授权、未配置、没有片段、网络失败、超时或模型输出无效时，界面保留本地月历，并降级为只整理日期与数量、不推断心理状态的本地回顾。

本机数据边界

数据	持久化位置	说明
自定义 API 配置	localStorage	Base URL、模型、图片精度和 API Key；可在「我的」清除
自定义语音转写配置	localStorage	讯飞 APPID、APIKey 和 APISecret；可在「我的」测试、保存和清除
多模态文字画像	localStorage	保存模型从文字、图片内容与互动形成的结构化文字观察；不保存原图
闪念索引	localStorage	保存文字、创建时间、日期和表达类型元数据；不保存图片数据或音频文件
实时麦克风音频	仅讯飞在途请求	录音期间以 PCM 分帧发送；心潮不落盘、不写入画像，服务商保留策略由其决定
月度回顾缓存	localStorage	最多保留 24 个月的模型回顾、证据指纹、模型名和生成时间
潮笺卡槽	localStorage	只保存内置卡片 ID 和收藏时间
未来回响	localStorage	仅在用户明确勾选后保存
答案之书	localStorage	只保存当天卡片序号，不收集用户心里的问题
原始图片、聊天原文、语音转写草稿、章节选择	页面内存	不写入本地持久化存储；明确发送或保存后，相关文字可能发送给自定义模型服务商

闪念键为 xinchao.quick-notes.v1：持久化记录包含 ID、用户确认保存的文字（包括语音转写）、时间戳、日历日期，以及是否曾附图、语音时长等表达类型元数据；图片 base64 与录音数据都不会写入。独立图片闪念还需逐图确认处理权利，才会在持续画像已开启时发送一次。月度回顾缓存键为 xinchao.monthly-memory.v1。

画像更新采用异步单飞队列：同一时间只运行一个请求，新变化与超过单次上限的图片批次会合并到后续更新；相同证据使用不可逆指纹去重；撤销授权或删除画像会取消在途请求并阻止迟到结果重新写入。删除闪念时会先清空可能含有该来源摘要的旧画像，再仅从剩余可用线索重建。月度回顾请求同样支持切月或撤销授权时取消，并用请求序号阻止迟到结果覆盖当前月份。

目录

• prototype/：当前 V0.7 应用与测试；
• dist/：构建产物；
• prototype/DESIGN_PLAN_DEARAURA.md：早期设计研究记录，不代表当前数据架构。