# Nomi 穿透式体验走查记录（2026-06-07）

> 方法：R13 穿透式体验走查。Playwright `_electron` 常驻驱动（`tests/ux/ui-driver.mjs`）开一次 app、边看边点，
> 逐页 `snap` 列可点元素 → `shot` 截图 → 人眼以**真实用户视角**判断顺不顺/美不美/一致不一致，
> 而非功能 pass/fail。本文只做**感知 + 记录**；处置方案见配套文档
> `2026-06-07-ux-walkthrough-actions.md`（6 角色评审 + 调研）。

- **构建**：走查开跑时渲染层 `vite build` 成功、electron `tsc` 因 WIP 报 `runtime.ts:2510 generateText 未定义` 而失败，故走查用**上次成功编译的 `dist-electron` + 全新渲染层**。
  > **【2026-06-07 回填修正】** 6 角色评审中后端 agent 实跑 `pnpm run typecheck` **已全过**——`agentChatHarness.ts` 已落地、runtime.ts import 正常，WIP 编译已自愈。即上面那条"编译 broken"在评审时已不成立。
- **覆盖面**：项目库 → 创作 → 生成（画布）→ 模型接入 → 预览/导出，含弹层/抽屉/下拉/助手等交互态。
- **截图**：`tests/ux/shots/00-home.png … 16-assistant.png`。

---

## 0. 走查中实际撞到的"工程/稳定性"卡点（先记，本身是发现）

这些不是用户故意操作出来的，但**真实用户也会撞上**，且暴露了健壮性缺口：

| # | 现象 | 根因 | 用户感受 |
|---|---|---|---|
| E1 | 重新构建渲染层后开 app，点任何项目「继续创作」**毫无反应**，停在项目库 | 打开项目走 `hydrateProject` → 懒加载 `projectPersistenceService-*.js` chunk；app 加载的是**缓存的旧 index/模块图**，请求旧 hash chunk → `Failed to fetch dynamically imported module` → `hydrateProject` 返回 `false` → **静默**停在库 | 按钮像"坏的"，没有任何报错/转圈，用户无从知道发生了什么 |
| E2 | 同上失败路径**零反馈** | `NomiStudioApp.openProject` → `hydrateProject`：`if (!hydrated) return false;` 后什么都不做，无 toast、无 loading 态 | 这是 E1 的**根因层**：即便 chunk 加载、磁盘读盘、迁移等任何一步失败，用户都只会看到"点了没反应" |
| E3 | 连开多个走查实例时，新 app 一启动就秒退 | ~~Electron 单实例锁占用~~ **【回填修正：归因错误】** 全仓 grep `requestSingleInstanceLock` **零命中——代码根本没有单实例锁**。真因是启动链 `app.whenReady().then(…).catch(app.quit())`（`electron/main.ts:766-769`）任一步抛错即**静默 `app.quit()`、无 `dialog.showErrorBox`**；多实例并发抢同一 userData/JSON 触发它。**反而暴露了两个真根因：① 缺单实例锁（双开会并发写坏 catalog/project JSON）② 启动失败静默退无提示** | 双击图标"打不开"，无报错 |

> E1/E3 部分由"开发期重建/多实例"诱发，但 **E2 是纯产品 bug**：打开项目失败必须给用户可见反馈（错误 toast / 重试），不能静默吞掉。

---

## 1. 项目库（首页）— `00-home.png`

**布局**：顶部「Nomi 项目库」标题 + 副标题；「30 秒体验 NOMI」hero 卡（标语"把一段故事，自动拆成 6-12 个镜头" + 3 个示例：漫剧/产品 demo/短视频）；「新建空白项目」「打开已有文件夹」；搜索框；项目网格（缩略图 + 标题 + 相对时间 + hover「继续创作」+ 删除）。

**发现**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| H1 | P2 | 项目名**泄漏文件夹命名痕迹**："未命名项目 05_31 13_00""未命名项目 05_31 12_47"（下划线、截断时间戳），不像作品名 | `00-home.png` 网格 |
| H2 | P2 | 同名「示例：30 秒产品介绍」**重复出现 3+ 次**，库面板拥挤、难辨 | `00-home.png` |
| H3 | P3 | 缩略图风格不统一：部分真实首帧图、部分灰底占位 icon，整体凌乱 | `00-home.png` |
| H4 | P3 | 「继续创作」按钮 hover 才显形，新用户不悬停时卡片像"不可点"，主操作可见性弱 | snap 显示按钮在 DOM 但视觉藏起 |
| H5 | P3 | hero 的 3 个示例卡与下方真实项目网格视觉权重接近，"30 秒体验"作为冷启动主 CTA 不够突出 | `00-home.png` |

---

## 2. 创作 tab（文本 + AI 面板）— `05-creation.png` / `06-mode-dropdown.png`

**布局**：左 = 富文本编辑器（B/I/H1/H2/列表/引用/撤销重做工具条 + 大块编辑区）；右 = 「Nomi 创作」AI 面板（空态"需要一点灵感？" + 3 chips + 输入框 + 模式选择）。

**发现**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| C1 | P2 | 模式下拉项「提…」**文字被裁断**（菜单过窄），看不清是"提示词"还是"提炼" | `06-mode-dropdown.png` |
| C2 | P2 | **两套并行的"拆镜头"概念**：模式下拉里有「分镜」，输入条上又有独立「拆镜头」按钮；二者关系不明（违反 P1 无并行版精神） | `05-creation.png` snap：模式▾ + 拆镜头 + 定妆 |
| C3 | P2 | AI 建议 chips 是**小说向**（"一段悬疑开场""改成更童话的语气"），但当前项目是"30 秒产品介绍"，调性错配（违反 P4/P2，应随项目类型 derive 而非钉死小说示例） | `05-creation.png` |
| C4 | P3 | 左侧大编辑区**无 placeholder/引导**，新用户面对一片白，不知道该写什么、写完点哪 | `05-creation.png` 空编辑区 |
| C5 | P3 | 输入条挤了「模式▾」「拆镜头」「定妆」「发送」四个东西，模式与子动作层级混乱 | `05-creation.png` 底栏 |

---

## 3. 生成 tab（画布）— `04-studio.png` / `07-node-selected.png` / `14-category-panel.png` / `15-canvas-help.png` / `16-assistant.png`

**布局**：顶栏面包屑 + 创作/生成/预览 + 素材库/模型接入/导出；左 = 可折叠侧栏（分类「类」/ 文件「文」）+ 节点工具栏（文本/图片/视频/全景图/3D/复制/剪切/全部生成/发送到时间轴）；中 = 画布（点状网格 + 节点）；右上 = 浮动「Nomi 生成」助手；底 = 时间轴（图片轨/媒体轨 + 播放头 + 缩放）。

**发现**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| G1 | P2 | 点击节点（「等待生成」占位）**无任何可见反馈**：无选中环、无检查器/参数面板弹出，用户不知道点中没、去哪配参数 | `07-node-selected.png` 与点前无差异 |
| G2 | P2 | 分类面板 +（折叠后仍在的）节点工具栏构成**双左栏**，再叠右侧助手 = **三栏同开**，画布被挤得很窄；空间没做"渐进展开/防遮挡" | `14-category-panel.png` / `16-assistant.png` |
| G3 | P3 | 画布帮助「?」触发点在**左下角**，帮助条却弹在**窗口右上角**，触发与反馈空间错位 | `15-canvas-help.png` |
| G4 | P3 | 「Nomi 生成」助手与「Nomi 创作」助手结构几乎一致（空态+3chips+输入+模式），但**子控件范式不一致**：创作用「拆镜头/定妆」按钮，生成用「模式 Agent▾ + 自动选模型▾」双下拉 → 跨面板不一致 | `05-creation.png` vs `16-assistant.png` |
| G5 | P3 | 两个助手（创作 / 生成）何时用哪个、边界是什么，缺少引导，易混 | 同上 |
| G6 | P4(优点) | 助手「自动选模型」符合 P4 通用优先（系统填模型，不让用户挑），值得保留并推广 | `16-assistant.png` |

---

## 4. 模型接入 — `09-model-catalog.png` / `10-add-model.png`

**布局**：右抽屉「模型设置」+「添加模型」，按 文本/图片/视频 分组列模型；点「添加模型」弹「添加一个 AI 模型」（文本/图片/视频 tab + 文档地址 + API Key + 开始）。

**发现**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| M1 | P1/P2 | **内部 vendor key 直接暴露给用户**：每个模型副标题是 `kie` / `dm-fox` / `api-moonshot-cn` 这种路由内部名（违反"词汇=模型真名，别给用户看管线"） | `09-model-catalog.png` |
| M2 | P2 | **分类错位**：「Gemini Omni Video」（名字就是 Video 视频模型）被列在「图片」分组下 | `09-model-catalog.png` 图片组 |
| M3 | P2 | 模型行**唯一操作是删除（垃圾桶）**：无启用/停用开关、无"已连通/未配 key"状态、无"测试一下"。最危险的删除成了唯一可见动作 | `10-add-model.png` snap：每行只有"删除 X" |
| M4 | P2 | 接入仍要求**每个模型粘贴官方文档 URL**（`https://docs.example.com/api/...`），即便是已知 vendor（kie 下一堆模型）也要用户去找文档（与 memory 记录的"文档+key 不该手配每个模型"同一 gap） | `10-add-model.png` |
| M5 | P3 | 11 个模型无搜索/筛选；「添加模型」弹窗压在抽屉之上，两层右侧浮层叠加，层级略乱 | `09/10` |

---

## 5. 预览 / 导出 — `12-preview.png` / `13-export.png`

**布局**：大预览区（空态"画面预览 / 从「生成区」拖入素材即可显示"）+ 底部控制条（播放 / 时码 / 画幅16:9▾ / 显示适应▾ / 缩放 / **导出 MP4** / 安全框）+ 底部时间轴。

**发现**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| P1 | P3 | 主操作「导出 MP4」是控制条里一个**小深色 chip**，夹在一排小图标中间，作为成片出口存在感不足、易被淹没 | `12-preview.png` |
| P2 | P4(优点) | 「导出 MP4」空时**正确禁用**且带 title「时间轴为空，先添加素材」——禁用+原因做得对 | `13-export.png`（按钮 `disabled` + title） |
| P3 | P3 | 禁用原因只在 hover title，inline 不可见；新用户看到灰按钮可能不知为何 | 同上 |
| P4 | P3 | **两个导出入口**：顶栏「导出」(前往预览导出) + 预览内「导出 MP4」。前者只是跳转，轻度冗余 | snap：顶栏 aria"前往预览导出" |

---

## 6. 跨页面横切问题（合并同类项）

1. **管线名泄漏**（M1）+ **文件夹名泄漏**（H1）：到处能看到 `kie`/`dm-fox`/下划线时间戳等"给机器看的名字"，整体不像面向创作者的成品。
2. **空态引导缺失**（C4 编辑器、G1 节点、首页冷启动）：多个关键起点是"一片空白 + 无下一步指引"，新用户卡在"我现在该干嘛"。
3. **失败静默**（E2 打开项目、潜在的生成/导出失败）：失败路径普遍不给可见反馈，违反 P2"修根因"——错误应在统一层冒泡成 toast。
4. **空间三栏挤压**（G2）：画布同时被左分类栏 + 节点栏 + 右助手夹击，缺渐进展开/可折叠协同。
5. **AI 入口"双生子"不一致**（C2/G4/G5）：创作助手 vs 生成助手、模式下拉 vs 拆镜头/定妆按钮，范式与措辞两套，需要统一。
6. **示例没"演示力"**：打开的「示例：30 秒产品介绍」编辑器空、画布仅一个"等待生成"占位节点——示例本应是"打开即看到一个做好的样例"，现在更像空项目（注：此条受本机已存项目数据影响，需在干净环境复核是否所有示例都如此）。

---

## 6.5 空项目冷启动专项走查（2026-06-07 补做）

> 起因：首轮走查时本机有一堆历史项目，把"真实首次用户"体验盖住了。补做一次**纯空状态冷启动**：用隔离的空 userData（`--user-data-dir`）+ 空 `NOMI_PROJECTS_DIR` 启动，**完全不碰真实数据**，模拟全新安装第一次打开。截图 `empty-00…empty-02`。

**先说好的**：去掉项目杂物后，**首页 hero 终于成了清晰主 CTA**——「30 秒体验」标题醒目、3 个示例带头像图标（🦄/🚀/🎒）、「新建空白项目」是明确的深色主按钮。这反向印证了首轮 H2/H3/H5：**是历史项目网格在埋没 hero，不是 hero 本身弱**。

**但冷启动暴露了首轮看不到的致命链路**：

| # | 级别 | 发现 | 依据 |
|---|---|---|---|
| **CS1** | **P0 致命** | **冷启动死路**：全新用户点 hero 的「30 秒体验」示例 → 弹「先接入一个文本模型…」toast → **模型面板不打开**（监听器只在画布工作区挂载，首页没有）→ 而**首页根本没有任何「模型接入」入口**（`hasModelEntryOnHome:false`，首页可点元素只有 3 示例 + 新建空白 + 打开文件夹）→ 新用户在第一个动作就**无路可走**。要接模型必须先"新建空白项目"进工作区，但 toast 没告诉他这条绕路 | `empty-01-after-example.png` + eval |
| **CS2** | **P0 致命** | **全新安装零文本模型**：fresh userData 只预置了**图片组**（GPT Image 2 文生图/图生图、Seedream 4.5、Nano Banana）+**视频组**（Seedance 2.0/Fast、HappyHorse、可灵 3.0），全是 `kie`，**没有任何文本模型**。而「30 秒体验」必须要文本模型才能拆镜头 → 新用户必然撞 M4 那堵"手配文档+key"的墙，且文本模型连个预置都没有 | `empty-02-blank-project.png` 抽屉只有 图片/视频 两组 |
| **CS3** | P2 | 引导 toast「先接入一个文本模型，就能一键体验示例」**文字被窗口右缘裁断**（toast 溢出视口） | `empty-01-after-example.png` 右上角 |
| **CS4** | P2 | 首页空态是**一大片空白虚空**：去掉项目后下方 60% 全是空白，无"还没有项目/从这里开始"的空态引导，页面头重脚轻、像没做完 | `empty-00-home.png` |
| **CS5** | P3 | **新建空白项目竟弹"迁移"提示**："项目已升级到目录树：1 个节点已归类"——一个刚建的全新项目没有任何 legacy 可迁移，这条消息对新用户莫名其妙 | `empty-02` 顶部 toast |
| **CS6** | P3 | 之前点示例排队的"打开模型接入"事件，**延迟到后来新建的不相关空白项目上才触发**（抽屉在新项目里自动弹开）——事件队列跨上下文泄漏，时机怪异 | `empty-02` 抽屉自动开 |

**冷启动一句话结论**：空状态下首页更好看（印证 hero 被杂物埋没），但**真实新用户走「30 秒体验」会在第一步就死**——没文本模型预置（CS2）+ 首页无接入入口（CS1）+ 引导 toast 还裁断（CS3）。这把首轮 PM 评审判定的"关口 5（M4 模型门槛）是漏斗最窄处"升级成了**关口 0 直接断路**：新用户连"进到能接模型的地方"都做不到。配套处置见 actions 文档 §3 P0（M4 免文档接入 + 首页加接入入口 + 文本模型预置）。

---

## 7. 待复核 / 未覆盖

- **素材库**：点「素材库」无可见弹层（可能触发原生文件选择器或为开/关 toggle），未确认其内部界面 → 待补走查。
- **真实生成 / 导出成片**：需真实模型额度，未实跑（J1/J4 的"可以生成了→真出片"环节未验证）。
- **J2 定妆链路 / J4 参考图驱动**：本轮以 J1/J3/J5 主链路为主，定妆建角色卡、上传参考图挂节点未深入。
- **节点检查器**：G1 点节点无反馈，未能进入参数配置界面（需确认是无检查器，还是触发方式不同/双击/侧栏）。
- E1 的 stale-chunk 是否会在**正式打包版**复现（生产 file:// 模块缓存策略）需单独验证。

---

## 附：本轮截图索引

| 文件 | 内容 |
|---|---|
| `00-home.png` | 项目库首页 |
| `05-creation.png` | 创作 tab（编辑器 + Nomi 创作助手） |
| `06-mode-dropdown.png` | 创作模式下拉（含「提…」截断） |
| `04-studio.png` / `07-node-selected.png` | 生成画布 / 选中节点（无反馈） |
| `14-category-panel.png` | 画布左侧分类面板（双左栏） |
| `15-canvas-help.png` | 画布帮助快捷键条（右上） |
| `16-assistant.png` | 生成画布助手（三栏挤压） |
| `09-model-catalog.png` | 模型接入抽屉（kie 泄漏、视频归图片） |
| `10-add-model.png` | 添加模型弹窗（文档+key） |
| `12-preview.png` | 预览（导出 MP4 小 chip） |
| `13-export.png` | 导出按钮禁用态（带原因 title） |
