AGENTS.md@src/studio git:20260910.256ad8eA

Immutable. This exact content never changes and is served at /api/v1/blob/16ef01cb4f324259.

# Studio 领域规则

本文件补充仓库根 `AGENTS.md`，适用于 `src/studio/`。Studio 只消费稳定的领域投影，不应重新解释评测或观测语义。

## 渲染与查询边界

- Studio 应用页面统一向 Next.js 收敛；新页面不再增加手写 HTML 实现。API、SSE 与独立报告入口按各自职责维护，不为迁移页面而复制领域查询。
- 泳道布局、证据引用与活动快照放在共享 view-model 投影中，HTTP、React 和 HTML renderer 消费同一实现；共享投影不得依赖 presentation 或 web。
- Knowledge 页面与 API 共用 application 查询入口。缓存由服务实例持有，目录按请求解析，返回值不得暴露缓存内部的可变引用。
- 清理旧渲染器前检查实际调用者；仍服务于独立报告或调试入口的实现不算死代码。具体迁移路由与剩余工作记录在 PR，不在本规则中维护易过期的路由清单。

## 领域约束

- 品牌名称统一为“OMK Studio”，品牌入口在 hover、focus、active 状态保持文字颜色稳定，键盘焦点使用轮廓提示。
- Studio 定位为全屏应用：所有页面默认占满视口，页面根节点及页面外壳禁止横向、纵向滚动。导航、页面操作与关键摘要固定，不能靠整页滚动容纳内容。
- 先通过紧凑布局、分页、标签页与按需详情分配空间；只有确有长内容的表格、时间轴、证据面板和抽屉允许显式的内部滚动，并约束高度、最小尺寸与滚动传播。不能仅用 overflow:hidden 裁掉内容或操作；所有内容仍须可达。
- 所有表格的表头和单元格文字禁止自动换行，不靠拆字或换行适配列宽。为状态、数量和操作列保留足够宽度；长文本使用单行省略并提供完整内容提示／详情，或通过表格内部横向滚动查看，不得裁掉无法访问的内容。
- 改造或新增页面时，验收 Observe、Measure、Knowledge 及报告／异常页面的布局边界；至少检查正常桌面和较矮窗口，页面无双向溢出，四条泳道完整可见，表格操作列不换行，普通双行列表优先采用约 56px 行高。独立于 Studio 挂载的报告不强制使用应用外壳。

- 人工预览的端口选择遵循根规则；用户可见 URL 使用 `server.start()` 返回的实际地址，不以默认端口拼接 URL。
- 展示层消费 view-model，不直接读取或重算底层存储与评分语义。
- 修改报告 UI 后，先审查 `test/__snapshots__/html-renderer.test.ts.snap` 的实际变化，再决定是否更新 snapshot。

## Code Review Rules

- 必须拦截 presentation／http 层反向定义领域语义或绕过 view-model 读取底层数据。安全路径：在对应领域构造稳定投影，Studio 只负责呈现和传输。
- 必须拦截未转义的外部文本进入 HTML，以及敏感路径、凭证或原始异常泄漏给浏览器。安全路径：统一 escaping 与错误投影，并覆盖恶意输入测试。
- 必须拦截没有人工审阅可见差异的 snapshot 批量更新。安全路径：先核对预期 UI 变化与用户影响，再更新最小 snapshot 并做必要的真实页面验收。