Re: [PR] docs(usage): design revision-consistent screen reads [maka]

["likun666661 (via GitHub)" <gi...@apache.org>]

likun666661 commented on PR #5023:
URL: https://github.com/apache/maka/pull/5023#issuecomment-5682698338

   重新审阅当前设计稿 `af032418e18deaba23f5172d206a32784a16db63`，并核对了文档引用的 `1ae4d5b89` 源码基线。
   
   我支持核心方向：首屏在一个 Storage 读事务内取得统计、breakdown、pricing 和第一页活动记录；后续页在同一个读事务内检查 revision 并读取页面；Host 不保留整批历史副本。问题定义可以收敛为：**Usage 同屏数据必须来自一个版本，后续页面只能接在同版本结果后面。**
   
   这版已经明确接受持续写入导致 continuation 返回 `revision_changed`，保留旧屏并等待用户 Refresh。因此不再把“持续写入时能否一直翻页”作为未决项，也不要求本 PR 重新引入性能预算、任意历史规模保证或增量聚合。下面两点是当前契约仍需补齐的地方。
   
   **1. [P2，实施前必须明确] 完整首屏超过 wire 容量时的行为。**
   
   [文档第 68–78 行](https://github.com/apache/maka/blob/af032418e18deaba23f5172d206a32784a16db63/docs/architecture/usage-screen-revision-consistency-draft.md#L68) 排除额外 breakdown/pricing 分页，同时保留现有协议数量和编码字节限制；[第 113–117 行](https://github.com/apache/maka/blob/af032418e18deaba23f5172d206a32784a16db63/docs/architecture/usage-screen-revision-consistency-draft.md#L113) 又要求一次返回完整 breakdown 和 pricing。这些集合尚未证明始终能够装进单次响应。现有 [pricing 协议](https://github.com/apache/maka/blob/1ae4d5b899db66511322876d9df44295eb49eb70/packages/runtime-host/src/protocol/usage-pricing.ts#L41) 使用每页 128 项、48 KiB 的限制；这些是现有 pricing page 的上限，并不能自动定义新 screen 响应的容量或完整性。
   
   请明确新 screen 的响应边界及超限分支：是整个首屏确定性失败，并说明错误与 UI 行为；还是允许同 revision 的分段读取后原子安装？如果保持当前不增加分页的范围，可以选择前者，但应写清楚且不能静默截断。这里要求的是既有 wire 约束下的正确性与完整性，不是新增 scan/latency/admission 性能目标。
   
   **2. [契约澄清] 活动筛选变化时，是整屏重读还是旧 revision 下重新读第一页？**
   
   [第 211–216 行](https://github.com/apache/maka/blob/af032418e18deaba23f5172d206a32784a16db63/docs/architecture/usage-screen-revision-consistency-draft.md#L211) 说筛选变化会重启 activity navigation 并使用新的 query identity，但当前接口只列出整屏读取和绑定已有 query identity 的 continuation。
   
   例如当前显示 revision A，Storage 已变为 B，用户此时修改模型搜索条件。不能保留 A 的统计，只安装 B 的筛选结果。建议直接规定最简路径：筛选变化调用 `readUsageScreen(resolvedRange, newActivityFilters)`，原子替换整屏；headline/breakdown 仍按整个选定时间范围计算，筛选只影响 activity。若希望保留旧统计，则需要明确在 A 下获取新筛选第一页的接口及 A 失效时的 stale 行为。这是消除实现歧义，不是已经复现的运行时代码缺陷。
   
   Storage 机制方面，我倾向现有 Usage facade 内的同步事务模块、通过既有 writer 完成独立 repair 后再读、先采用较粗的 root revision，以及有唯一稳定 tie-breaker 的 keyset cursor。最终 revision 选择仍需真实 writer 覆盖清单和回滚/恢复测试证明；不需要为本轮预先增加细粒度 revision 或新的聚合权威。
   
   结论：认可设计方向；补齐首屏超限行为与筛选切换路径后，再确认实施方案。这是设计意见，不是实现批准。
   
   ---
   AI-assisted：本评论由 Codex 根据设计稿及相关源码静态审查整理，经用户授权发布；没有运行实现测试或性能验证，不替代独立人工审查。
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org