Files
CyberGril/docs/frontend/IMPLEMENTATION.md
T
2026-10-22 00:56:18 +08:00

49 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
HEL-748 · S1 实现与接线说明
本轮范围是可构建的完整前端及离线演示,不部署,不实现 B1–B3。基于正式仓库 main 的 `1e9b08aed81b4ebf163721232a8d65707b1c3183` 新建任务分支;检出时工作区干净,无仓库内额外 AGENTS,无平台关联 PR。未改 Python 核心、既有测试、服务配置、SSH 信任、端口、GPU 或模型。
依据为本卡《整套设计验收与施工裁定-v1》、HEL-746 R2、HEL-738 结构与接口边界和需求 v1.6。名字、关系不预选、未分享即隐藏三项裁定覆盖旧原型。首建底色明确为示例,真实排盘待接已有 Python 编译器,不在浏览器重写八字规则。
主要目录与职责:
- `web/src/app/`:入口、首建守卫、导航、全局 UI 偏好、返回/主动/断线演示。
- `web/src/manage/`:四步首建;只读身份;关系/城市/服务/显示草稿;保存取消失败;外观标识;演示导出与同身份恢复。
- `web/src/chat/`:文字草稿、IME 与快捷键、字幕/记录、取消重试、模拟语音/观察授权及结束。
- `web/src/life/`:生活与四类回忆、双向关联、原位保留、手机详情推入、分页和深链守卫。
- `web/src/domain/`:模型、首建校验、公开视图。所有可见事件、回忆、消息、摘要统一经过 `publicView`,未知关联默认拒绝;详情也从公开视图查找。
- `web/src/adapters/`:独立可替换聊天适配器、turn_id/epoch 门槛、AbortController、本地持久化、严格 JSON 重建校验。
- `web/src/demo/`:固定场景数据,与页面和传输分离。
- `web/src/stage/`:背景空间与 `FallbackPresenter`。Presenter 只消费 SceneDesc,不写生活;参考图片失效也有文字降级,不黑屏。
- `web/src/shared/`:复用按钮、图标、字段、状态和带焦点边界的确认弹层。
- `web/src/styles/`:R2 单一 Token 和组件样式来源;没有第三方 UI 皮肤或叠加覆盖样式表。
两主题使用相同 DOM 和布局;人物拱窗、交谈展开、阅读面板与手机断点沿用获批样式。静帧仅呈现参考人物/房间,不渲染整页图片。语音/观察不访问 `getUserMedia`、不调用 ASR/TTS、不发外部请求。演示天气固定并标注模拟;当前视觉标签来自演示记录公开视图。
F1–F9 走法:
| 流程 | 入口与边界 |
|---|---|
| F1 | 无本机档案 → 四步创建 → 名字/成年生日/关系/勾选校验 → 本机持久化 → 首晚空生活 |
| F2 | 普通入口说明未接服务 → 明确演示入口;重开直接回到同一位她 |
| F3 | 演示场景 → 模拟两天后返回;只从已分享数据生成摘要,不生成后台生活 |
| F4 | 演示场景 → 主动消息;来源是已分享事件,回她定位聊天并保留来源区域 |
| F5 | 交流麦克风 → 模拟授权 → 倾听界面;文字发送推进思考/说话,可打断/结束;无真实收音 |
| F6 | 演示断线 → 暂停发送,保留草稿,结束模拟语音、取消旧轮;恢复失败可重试,不自动重发 |
| F7 | 设置城市 → 搜索/选择 → 保存成功/失败/重试;不调用天气 API |
| F8 | 本地演示素材 JSON → 结构检查/模拟对比/确认;只更新外观标识,真实媒体导入待后续 |
| F9 | 本地演示 JSON 下载/同身份校验/输入确认/先导出再恢复;服务器备份明确未接通 |
取消与错误:新轮、手动取消、切离交流会 abort 当前模拟回复;事件还需同时匹配 turn_id 与 epoch,非协作适配器的迟到消息同样被门槛拒绝。断线 resync 提升 epoch;恢复不自动续接旧轮。管理保存切区/关区会 abort;草稿保留,取消恢复上次提交值;存储损坏不进入新的首建覆盖。导入只执行 JSON.parse 后按固定 schema 重建;不执行脚本、不作为 HTML、不加载媒体/服务 URL。
后续接线清单(当前均未提供):
1. B1 同源 API 与 WS:hello/sync、游标和持久 epoch、能力声明、HTTP AbortSignal。真实模式不得直接替换成未经审定的 LLM URL。
2. 服务端授权与隐私:必须在响应前裁剪未分享记录、未知引用、回忆和消息及摘要;本轮前端过滤不构成服务器权限控制。
3. 接已有 Python 生辰预览/只读档案、真实关系更新;身份 ID、底色指纹由服务端负责。
4. B2/B3 后台生活、主动性、记忆与增长层;前端只订阅 LifeScene/事件,不从素材反编生活。
5. S2 流式文字;S3 ASR/TTS 二进制协议、session_id/seq 隔离、权限与实际中断;当前没有真实音频流,因此不声称达到延迟指标。
6. S4 生活/回忆服务分页;S5 城市/天气、素材包校验和完整服务器备份/自动备份;演示 JSON 的 MIME 和结构不是媒体真伪校验。
7. S6 视觉摘要时效与 HTTPS、真实权限;Presenter 的视频/音频/口型驱动器可注入,当前只交静帧降级。
测试部署由总工审核后执行。建议在独立目录安装构建,将 `web/dist/` 作为静态站点挂到总工选定的未占用测试端口;正常路径 `/`,演示 `/?demo=1`。本轮未占用固定服务端口,也未更改 8010/18080/18081 或现网。部署若换 origin,浏览器本地演示资料不会自动迁移,可通过同身份演示 JSON 手动恢复。