HEL-895: mechanically integrate the approved proactive-inbox frontend (bf23457, HEL-881 passed) onto the unified mainline 152479b

The mainline 31970c4..152479b never touched web/ (verified: git diff 31970c4 152479b -- web/ is empty), so this merge brings in exactly the two HEL-875/880 commits and nothing else: the visual director's six frontend files verbatim (web/src/adapters/inbox.ts, real.ts, app/RealApp.tsx, chat/ChatPanel.tsx + tests) with CSS untouched, plus handoff-HEL-875.json and handoff-HEL-880.json for governance provenance. No backend file changes, no redesign, no visual decisions made here; all HEL-874..894 backend fixes stay byte-identical.

Containment verified before merging: bf23457 is NOT an ancestor of 152479b (1ae243f + bf23457 were the only mainline-missing work); the old b48d28b test merge was never pushed and is superseded by this fresh integration at the current head.

Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
zonggong
2026-10-27 01:55:45 +08:00
co-authored by multica-agent
9 changed files with 698 additions and 15 deletions
+62
View File
@@ -0,0 +1,62 @@
{
"baseline_version": "1.11",
"read_commit": "31970c4dd3851aae67a922b03264743d504b8e97",
"task": "HEL-875 接线:沿已认可界面把真实主动留言(R4 reach-out,chat_message proactive=1)接进普通入口——打开页面期间接收、去重、未读提示与清除、不抢断阅读与回复;只改视觉总监负责的前端,不重定视觉方向,不改后端",
"requirement_ids": [
"CG-008",
"CG-011",
"CG-018",
"CG-031",
"VIS-001",
"VIS-002",
"VIS-003",
"VIS-004",
"VIS-005",
"VIS-006",
"VIS-007",
"VIS-008",
"VIS-009",
"VIS-010",
"VIS-011",
"VIS-012",
"VIS-013",
"UX-001",
"UX-002",
"UX-005",
"UX-006",
"AM-001",
"GOV-001",
"GOV-002",
"GOV-003",
"GOV-004",
"GOV-005",
"GOV-006",
"DEL-001"
],
"deliverable": "自统一母线 origin/hel-870-assembly @ 31970c4 起的前端补丁(仅 web/):1) 接口核实:后端没有 /api/sync;现有只读 GET /api/messages(按行 id 倒序分页、limit+1 探测、next_before,主动行带 proactive:true,见 src/cybergril/api/app.py:399-414 与 life/public.py:26-34)已足够,未改后端、未造假服务。2) web/src/adapters/inbox.ts:打开页面期间每 20 秒(标签页隐藏时停读,回到页面或网络恢复时立即读一次;失败安静退避至最长 2 分钟)读取比已持有行更新的记录,长时间离开会有界回翻;只接收她的主动行(proactive、companion、sent),你自己的轮次及她的回复按 turn_id 已在页面上,绝不重复插入;重复读取、重连、epoch 变化返回同一 id 不再插入。未读规则:进入交谈且页面可见时,已进入页面记录的主动留言都算已读(单句在舞台呈现;多句从此刻留言卡或「回她」进入时打开完整记录并定位第一句;直接点导航「交谈」时舞台只呈现最新一句,较早一句在记录里);交谈中排队、尚未呈现的不算已读;标记为本浏览器 localStorage cg.real.seen(最新已读 id),不写服务器;本浏览器首次加载时既有历史一律视为已读,不把旧历史标成刚来的新消息。3) web/src/app/RealApp.tsx:此刻页沿用已认可的留言卡(letter)——有未读时显示「她留给你的 · 还没看」与她的原话(多句时显示「N 句还没看」),无未读时「最近说过的话」用既有 .letter.read 状态;导航「交谈」沿用既有未读微光点(.nav-item.unread .badge);日子/设置页沿用演示已认可的主动留言卡(.reach),换成真实原话、去掉「模拟」,只有「回她 / 稍后再看」,绝不自行打开交流;一句未读回她时在舞台呈现,多句时打开完整记录并定位第一句未读。4) web/src/chat/ChatPanel.tsx:交谈中到达的新留言先排队,在她正在回答、你暂停或回看、完整记录/全文打开、鼠标停在台词上、当前最后一句尚未停留满时都不插入;条件满足后作为新一轮按既有新轮呈现动效进入;被你的阅读卡住时状态行只用既有文字样式说明「她刚又说了一句 · 继续后呈现 / 读完这段呈现」;草稿不受影响;离开交谈时排队留言并入记录并保持未读。5) 测试与证据:web/tests/inbox.test.ts(隔离 HTTP 合同 fixture,7 项);web/tests/hel875_mock.mjs + hel875_shots.mjs(隔离持久消息 mock + 无头 Edge,25 项浏览器检查、两主题电脑/手机截图与三段帧序列)。普通入口与 ?demo=1 完全分开:演示的「模拟主动消息」未改、未搬入真实入口,演示入口不请求 /api/messages。未新增 CSS、颜色、动效或组件(构建 CSS 产物哈希与改动前一致 index-DdDYzR5S.css)。",
"acceptance": [
"页面打开时收到服务器新主动留言:此刻页留言卡换成原话并显示未读,导航「交谈」亮未读点;日子/设置页出现主动留言卡;从不自行打开交流(浏览器检查 2–3、9)",
"关闭重开:完整记录、行 id 唯一不重复;未读跨重开保留;本浏览器首次加载既有历史不算新消息(浏览器检查 1、7;inbox.test unread 3 项)",
"重复读取、epoch 递增、503 失败后重连:只保留一份、画面无报错提示(浏览器检查 2;inbox.test 第 1 项)",
"不抢断:她回答中到达的留言等回答结束且最后一句停留满后才作为新一轮进入;暂停时停在你的那一句并以文字说明,继续后进入;草稿保持不变(浏览器检查 4–5,帧序列 m2-admit)",
"读过按明确规则清未读:进入交谈且页面可见时清除(排队未呈现的除外);稍后再看只收起卡片、未读点保留;多句未读时打开记录并定位第一句(浏览器检查 3、8、9)",
"只做网页内文字:未申请麦克风、摄像头或通知权限(浏览器检查计数为 0),无外部推送",
"工程:web tsc 0 错;eslint src 0 错(1 条既有警告在 ChatPanel 全文按钮焦点归还处,非本卡引入);vitest 6 文件 49 项全过(原 42 + 新 7);vite build 通过"
],
"deferred": [
"真机手机与 Safari 未测;手机为 390×844 等效视口,不冒充真机(UX-001)",
"未读标记只存本浏览器;同一账号换浏览器或清除站点数据后,既有留言按首次加载规则视为已读;多标签页之间不实时同步已读(下一次读取时各自按自己的标记)。若需要跨设备已读,须后端增加已读字段,此为最小后端需求,交总管决定,本卡未改后端",
"轮询为 20 秒;若要即时到达须后端推送通道(SSE/WebSocket),属后端合同变更,本卡未做",
"她在你等待回复期间生成的主动留言,服务器行 id 可能落在你那一轮的用户行与回复行之间;本页面先呈现回复再呈现留言,重开后按服务器 id 顺序显示,记录内容一致、顺序可能与本次所见不同",
"日子页电脑 1440×900 下,既有 .reach 卡与既有「她此刻」人物窗说明相距很近(未重叠);位置沿用既有样式,如需调整属新视觉,先出样图",
"R5 语音连续对话、语音开启时主动开口;R6 天气/素材包/备份;R7 有条件视觉观察——均未接,界面诚实文案不变",
"用户整体沉浸体验判断与验收由白栖知决定;本卡为功能接线,工程通过不代表项目完成"
],
"requirement_changes": [],
"verification": [
"实际读取提交 31970c4dd3851aae67a922b03264743d504b8e97(gitea 归档下载,origin/hel-870-assembly 分支头 API 核对一致);已读 AGENTS.md、docs/requirements/README.md、current.md v1.11、runbook-hel870.md §5/§7、handoff-HEL-870.json 及后端 /api/messages 与 reach_out 实现",
"web:tsc --noEmit 0;eslint src 0 错;vitest run 49/49;vite build 成功(依赖按 package-lock 由本机既有 npm 缓存离线铺设,176 个包,与此前 npm ci 一致,无新增依赖、无下载)",
"浏览器:node tests/hel875_mock.mjs 8875 + node tests/hel875_shots.mjs <msedge.exe> <out> 8875,25/25 通过;截图覆盖月光/雾光 × 电脑 1440×900 / 手机 390×844",
"需求结构检查:本运行环境无 Python 与 git,check_requirements.py 由逐行移植的 Node 版本执行,比较目标为 gitea 只读取得的 origin/main 与 origin/agent/agent/de8874a3803b,各含/不含本交接;结果见交付评论。Python 原脚本须由总管/总工在有 Python 的环境复跑"
]
}
+62
View File
@@ -0,0 +1,62 @@
{
"baseline_version": "1.11",
"read_commit": "1ae243f286b14789289e0bdca77eec818074c879",
"task": "HEL-880 返工(父卡 HEL-875):补齐长时间离开页面后的主动留言续读——有界分页读取未覆盖旧游标时不再把游标推进到最新行,保留缺口并在后续读取中续读,所有主动留言按 id 顺序且仅一次进入;只改前端逻辑与测试/交接,不改界面、CSS、后端、已读政策,不增加推送",
"requirement_ids": [
"CG-008",
"CG-011",
"CG-018",
"CG-031",
"VIS-001",
"VIS-002",
"VIS-003",
"VIS-004",
"VIS-005",
"VIS-006",
"VIS-007",
"VIS-008",
"VIS-009",
"VIS-010",
"VIS-011",
"VIS-012",
"VIS-013",
"UX-001",
"UX-002",
"UX-005",
"UX-006",
"AM-001",
"GOV-001",
"GOV-002",
"GOV-003",
"GOV-004",
"GOV-005",
"GOV-006",
"DEL-001"
],
"deliverable": "自候选 hel-875-proactive-wiring @ 1ae243f 起的前端补丁(仅 web/ 与本交接):1) 缺陷:web/src/adapters/inbox.ts 的 fetchAfter 每次最多读 5 页×50 条,未读到旧游标就把本次见到的最新 id 作为 newest 返回,RealApp 随即推进游标,缺口内较早的主动留言永远不再读取(总管 fixture:页面持有 id=1,id=2 为主动留言,普通记录至 id=301,arrivals 为空)。另:after=0 时只读首页即停,超过 50 条同样漏读。2) 修复:游标改为 InboxCursor { through, gap }——through 以下全部已读并已交出;有界读取停在中途时 gap 记住下一次从哪一行(before)往下续读、已读到哪一行(top),以及途中读到的她的主动留言(held,只留主动行,内存有界)。下一次调用先沿 gap 往下续读,碰到 through 或记录开头即一次性按 id 顺序交出 held,through 推进到 top;若这个缺口是之前留下的,同一次调用再读一次最新页取新到的记录。读取失败或中止时整体抛出,不改调用方游标,下次从同一位置重来;不以扩大上限掩盖。较新的留言只等待尚欠的读取(每次 250 条,缺口未补齐时 RealApp 1 秒后续读,而非 20 秒),不会因最旧记录永久卡住。3) RealApp.tsx:游标存 InboxCursor,成功才提交;缺口存在时 1 秒后续读,失败退避与隐藏时停读不变。去重、排序(arrivals 不变,交出顺序随 through 单调递增)、交谈中排队不抢断、草稿、未读规则 cg.real.seen、演示入口隔离均未改。ChatPanel、CSS、后端、服务、档案均未改;构建 CSS 产物仍为 index-DdDYzR5S.css。4) 测试:web/tests/inbox.test.ts 改用新游标并新增 6 项(总管原 fixture 精确复现、1200 条散布 13 句主动留言、after=0 超过 50 条、分页第 3 页失败后恢复、追读期间又有新消息、重复读取/epoch 变化/页面已持有不重复);web/tests/hel875_mock.mjs 增 /__bulk/<n>,hel875_shots.mjs 增 8b 长时间离开步骤(2 项)。",
"acceptance": [
"总管 fixture(持有 id=1;id=2 主动留言;普通记录至 301):首次读取不交出、游标保留缺口 before=52/top=301;第二次读取交出 id=2,游标推进至 301(inbox.test「HEL-875 review fixture」)",
"超过 250 条:1200 条中散布的 13 句主动留言全部按 id 顺序各进入一次,追平后再读不新增(inbox.test)",
"after=0 且超过 50 条:读过首页继续续读,两句主动留言全部进入(inbox.test)",
"分页中途失败:调用抛出、页面游标与失败前完全一致;恢复后补齐全部留言(inbox.test)",
"分页途中又有新消息:先交出缺口内较早的,再交出新到的,各一次(inbox.test)",
"重复读取同一游标结果一致、epoch 变化不影响、页面已持有的不再加入(inbox.test)",
"无头 Edge:长时间离开(中间 320 条普通记录)回到页面后此刻留言卡显示「2 句还没看」,记录里各一句、较早者在前并定位到较早一句(浏览器检查 8b);原 25 项检查全部仍通过",
"工程:tsc 0 错;eslint src 0 错(1 条既有警告,非本卡);vitest 6 文件 55/55(原 49 + 新 6);vite build 通过"
],
"deferred": [
"原版 Python 需求检查未在本运行时执行(无 Python、无 git);须总管/总工在有 Python 的环境对 origin/hel-870-assembly、origin/main 与原产品目标 agent/agent/de8874a3803b 含/不含本交接复跑",
"真机手机与 Safari 未测;手机为 390×844 等效视口(UX-001)",
"缺口追读期间较新的主动留言要等缺口补齐才出现(每秒续读 250 条;例如离开期间 1 万条约需 40 秒);若需即时到达须后端推送或按 id 正向分页(after 参数),属后端合同变更,本卡未做",
"页面若在缺口补齐前关闭或刷新,重开时按完整记录加载,不丢失;但 held 不跨页面保存",
"HEL-875 既有承接项不变:未读标记只存本浏览器、20 秒轮询、等待回复期间的留言顺序说明、日子页 .reach 位置等,见 handoff-HEL-875.json",
"R5 语音、R6 天气/素材/备份、R7 有条件视觉观察仍由主卡 HEL-797 承接;用户整体沉浸体验验收由白栖知决定"
],
"requirement_changes": [],
"verification": [
"实际读取提交 1ae243f286b14789289e0bdca77eec818074c879(gitea 归档下载 zip SHA256 E55C5E95B7DF575D56E305961E29A85B46CCBE963818271754208641C1FCE87C);已读 AGENTS.md、docs/requirements/README.md、current.md v1.11、coverage.md、changes.md、sources/integration-plan-v1.md、handoff-HEL-875.json 及后端 GET /api/messages(api/app.py:id < before 倒序、limit+1 探测、next_before 为页内最旧 id)",
"web:tsc --noEmit 0;eslint src 0 错;vitest run 55/55;vite build 成功(node_modules 自 HEL-875 同一 package-lock 树离线复制,无新增依赖、无下载)",
"浏览器:node tests/hel875_mock.mjs 8880 + node tests/hel875_shots.mjs <msedge.exe> <out> 8880,27/27 通过(含新增 8b 两项)",
"需求结构检查:仅用 HEL-875 留下的 Node 移植版作辅助参考(基准文件经 gitea 只读取得)——origin/main、agent/agent/de8874a3803b、hel-870-assembly@31970c4(本候选实际基点)各含/不含本交接均通过;对 hel-870-assembly 现头 e978e878 失败,原因是该分支在候选之后合入 HEL-874、追加了来源 comment-evidence-full-experience-20261026.json,候选尚未包含,与本补丁无关,合并前需先同步该分支。不代表原 Python 脚本通过"
]
}