# 玄圃 v1.4.3 规划（基础设施 + onboarding + 可用性补强）

**日期**：2026-04-25
**状态**：Draft
**目标版本**：v1.4.3
**背景**：v1.4.0 → 1.4.2 连续三次发布都踩到了同一类问题：本地 dev 正常、CI 打包缺关键产物（cloudflared / mobile UI），以及一些只在 packaged / cold-start / SessionShell 新布局下才会暴露的 wiring 和可见性 bug。用户已经明确 1.4.x 要沿两条主线推进：

1. **事件流 / 现场提供继续做厚**
2. **让 Codex / OpenCode / Amp 真正在玄圃里可用**

在此之前，v1.4.3 先补一层基础设施和 onboarding，避免后续版本继续因为 packaging / wiring / 空状态体验问题浪费发布节奏。

---

## 1.4.3 主题

**一句话**：把"能发版"和"第一次打开就看得懂"两件事补齐。

这版不追求大功能，而是做一组高 ROI 的基础体验：

1. **CI post-package 验证**（防止再发出缺产物的包）
2. **首次 5 分钟 onboarding**（让新用户第一次就能看见现场注入 / 记忆）
3. **Memory / Field Context 空状态补强**（不再是 4 个空 tab）
4. **Edit / Write 卡片支持 diff 展开**（默认摘要 + 全量展开）
5. **Composer 图片支持大图预览**（解决目前小缩略图不可读）
6. **README.en.md 同步**（文档 front door 不再中英割裂）

---

## 1. 功能范围

### 1.1 CI post-package 验证（P0）

#### 问题

v1.4.0 和 v1.4.1 两次热修复都暴露同一个事实：

- 本地 `pnpm build:mac` 之所以正常，是因为它会隐式准备 cloudflared + mobile/dist
- CI release workflow 直接调用 electron-builder，跳过了这些前置步骤
- 我们直到用户安装后才发现：
  - `Resources/cloudflared/.../cloudflared` 不存在 → Hub 公网隧道报"找不到二进制"
  - `Resources/mobile-ui/index.html` 不存在 → 浏览器访问 Hub URL 返回 `{"error":{"code":"NOT_FOUND","message":"/"}}`

即使 1.4.1 / 1.4.2 已分别把这两步补回 workflow，**仍然缺一层 post-package 断言**，保证以后不再发出空包。

#### 目标

在 `Release Xuanpu` workflow 的 package 步骤之后新增一个 **Verify packaging completeness** 步骤，对每个平台产物做最小必要验证。

#### 验证项

**macOS**

针对 `dist/mac-${arch}/玄圃.app/Contents/Resources/`：

- `cloudflared/<expected-platform>/cloudflared` 存在且可执行
- `mobile-ui/index.html` 存在
- `app.asar` 存在
- `app.asar.unpacked` 下 better-sqlite3 / node-pty 的 `.node` 存在
- `native/ghostty.node` 存在（占位或真实二进制都可）

**Windows**

针对 unpack 目录或 installer 之前的 app output：

- `cloudflared/<expected-platform>/cloudflared.exe` 存在
- `mobile-ui/index.html` 存在
- 核心产物 `Xuanpu-Setup-*.exe` / zip 存在

#### 文件

- `.github/workflows/release.yml`

#### 验收标准

- 任一关键文件缺失 → workflow 直接 fail，release 不创建 / draft 不发布
- 对 v1.4.0 / 1.4.1 的两个事故分别能在 CI 中被拦截

---

### 1.2 首次 5 分钟 onboarding（P0）

#### 问题

当前新用户装完 1.4.2 之后，面对的是：

- 空工作台
- Field Context Debug 4 个 tab 初始全空
- 用户不知道 worktree / session / hub / memory 之间是什么关系
- 不知道 `memory.md` 写在哪
- 不知道事件流什么时候会积累、什么时候会压缩

这会直接吞掉我们好不容易做出来的差异化——明明有"现场提供"，但用户第一次打开完全感知不到。

#### 目标

做一个**最小 onboarding**，让用户在 5 分钟内亲眼看到：

1. Agent prompt 前会注入 Field Context
2. FieldContextDebug 不是空的
3. `memory.md` 在哪写
4. Hub 扫码后能用手机打开

#### 设计建议

以一个轻量的 4-step checklist/card 方式存在，不做重型 wizard：

1. **添加项目 / 选择 worktree**
2. **启动一个 session 并发送第一条 prompt**（让 Last Injection tab 有内容）
3. **展开 Field Context / Memory 面板**（告诉用户去哪里看）
4. **可选：启用 Hub，扫码打开手机端**

文案应该是"带你看懂玄圃为什么不是一个聊天框"，而不是泛泛的"欢迎使用"。

#### 实现位置建议

- 入口：SessionShell 或首页首次打开时的 callout
- 状态：复用 `useSettingsStore.initialSetupComplete` 或新增 onboarding step state
- 可关闭，但在用户未完成前保留可找回入口

#### 文件（建议）

- `src/renderer/src/components/layout/MainPane.tsx`
- `src/renderer/src/components/session-hq/SessionShell.tsx`
- `src/renderer/src/stores/useSettingsStore.ts`
- 可能新增：`src/renderer/src/components/onboarding/FieldOnboardingCard.tsx`

#### 验收标准

- 新用户第一次发送 prompt 后，能通过引导找到 Field Context 面板
- 引导文案明确提示 `memory.md` 路径和 Hub QR 能力

---

### 1.3 Memory / Field Context 空状态补强（P0）

#### 问题

当前 `FieldContextDebug.tsx` 的空状态只会说：

- No injection yet
- No episodic summary yet
- Memory injection is disabled / file not found
- No checkpoint yet

这些信息**技术上没错，但不够产品化**。用户真正想知道的是：

- 为什么是空的？
- 我做什么它会有内容？
- 这不是坏了吧？

#### 目标

把空状态改成**解释 + 下一步动作**：

**Last Injection**
- 解释：Field Context 会在下一条 prompt 前自动注入
- 动作：发送一条消息试试

**Episodic**
- 解释：需要约 20 个事件（命令 / 文件编辑 / 对话）后自动压缩
- 动作：继续工作；必要时提供"立即刷新 / 立即压缩"按钮（可选）

**Semantic**
- 解释：这里显示 worktree 的 `.xuanpu/memory.md` 和用户级 `~/.xuanpu/memory.md`
- 动作：直接给出路径和"去创建"按钮（后续 1.4.5 Memory 面板会替代它）

**Checkpoint**
- 解释：abort 或 app shutdown 之后才会有
- 动作：提示用户 abort 一次 session 再回来看看

#### 文件

- `src/renderer/src/components/sessions/FieldContextDebug.tsx`

#### 额外建议

在 1.4.3 里先保留 `FieldContextDebug` 命名；到 1.4.5 再升级为真正的 Memory 面板，不在这一版改组件命名和定位，避免 scope 膨胀。

---

### 1.4 Edit / Write 卡片支持 diff 展开（P1）

#### 背景

用户新增需求：

> edit 和 write，可以考虑支持展开，diff 卡片，默认展示几行，支持全部展开

当前 `FileWriteCard.tsx` 只有：
- file path
- add/remove 行数统计
- 状态 icon（running/error/success）

这对小改动勉强够，但对真正的 edit / write 来说信息远远不够，用户还是得跳到文件 diff 面板里找具体内容。既然这是 agent timeline 里的 tool card，至少应该给一个可读的 preview。

#### 目标

为 Edit / Write 类 tool card 增加一个**内联 diff 预览**：

- 默认折叠
- 默认显示前 N 行（建议 8-12 行）
- 支持"展开全部 / 收起"
- 优先展示 inline diff，而不是单纯 raw old/new text

#### 现有资产

- `src/renderer/src/components/session-hq/cards/FileWriteCard.tsx`
- `src/renderer/src/components/diff/InlineDiffViewer.tsx`
- `src/renderer/src/components/diff/DiffViewer.tsx`

#### 设计建议

**Edit**
- 从 `toolUse.input.old_string` / `new_string` 生成一个最小 inline diff 片段
- 默认展示前 8 行
- 如果 diff 太长，底部按钮：`展开全部` / `收起`

**Write**
- 没有 old_string，可退化为"新增文件内容预览"
- 默认展示前 8 行
- 同样支持展开全部

不要在 1.4.3 做跨文件完整 Monaco diff 弹窗——太重，且已有右侧 diff 面板能承载。1.4.3 只补 timeline card 自身的可读性。

#### 交互建议

卡片内结构：

- 第一行：路径 + 状态 + add/remove 统计
- 第二行开始：preview area（细边框 / 淡背景）
- 底部：`展开全部` 按钮（仅当超出 N 行时出现）

#### 验收标准

- Edit tool card 默认能看见一小段 diff 片段
- 超过 N 行时出现展开按钮
- Write tool card 能看见内容前几行预览
- 不引入明显的 timeline 高度抖动

---

### 1.5 Composer 图片支持大图预览（P1）

#### 背景

用户新增需求（见截图）：

> 输入框里的图片支持大图预览，像图 3 这样

当前 `ComposerBar.tsx` 里的附件预览通过 `AttachmentPreview.tsx` 渲染：

- 横向滚动的小缩略图
- 可删
- 不能点开看大图

对于截图类 prompt（尤其是让 agent 看 UI bug / 移动端截图），用户必须在脑子里记住图里内容，很不方便。

#### 目标

为 Composer 的图片附件增加**点击放大预览**：

- 点击缩略图 → 打开 modal / lightbox
- 保持原图比例，限制最大尺寸，不要拉伸
- 支持 ESC / 点击蒙层关闭
- 支持多图左右切换（1.4.3 可选，最低先做单图查看）

#### 现有资产

- `src/renderer/src/components/session-hq/ComposerBar.tsx`
- `src/renderer/src/components/sessions/AttachmentPreview.tsx`
- 项目已有 `Dialog` / `Popover` / `AlertDialog` 等 UI 基础组件

#### 设计建议

最小实现：
- `AttachmentPreview` 对 image mime 的缩略图增加 `onClick`
- 在该组件内部或父组件维护 `selectedImage`
- 渲染一个简单 `Dialog`：大图 + 文件名 + 关闭按钮

保持 scope：
- 只支持 `attachment.kind === 'data' && mime.startsWith('image/')`
- 不做多图导航也可，先解决"看不清"问题

#### 验收标准

- 粘贴一张 PNG/JPG 到 Composer 后，点击缩略图可以看大图
- 大图预览不影响发送 / 删除附件
- 深色/浅色主题都可读

---

### 1.6 README.en.md 同步（P1）

#### 背景

`README.md` 已更新为 1.4.0 的真实能力（Hub、现场事件流、分层记忆、Checkpoint、Session UI v2、1.4.x 路线图），`README.en.md` 仍是旧口径。

#### 目标

把中文版 README 的结构同步过去，不要求逐字翻译，但要保证：

- 顶部有 v1.4.0 essay callout（英文）
- Current Capabilities 反映 v1.4 的现场感知能力
- "not IDE, but field provider for agents" 口径同步
- priorities 改为 1.4.x roadmap

#### 文件

- `README.en.md`

---

## 2. 不在 1.4.3 范围内的内容

以下内容暂不进入 1.4.3，避免 scope 失控：

- Codex 体验大修（单独 1.4.4）
- Pinned Facts / 完整 Memory 面板（单独 1.4.5）
- 成本可见（单独 1.4.6）
- OpenCode / Amp 集成
- XFP 草案
- 大型 diff modal / Monaco diff 嵌入 tool card
- 多图图片预览左右切换

---

## 3. 建议拆分 PR

虽然版本叫 1.4.3，但实现上建议拆成 3 个 PR：

### PR A — Release / onboarding guardrails
- release.yml post-package verify
- onboarding card
- README.en.md

### PR B — Field / Memory UX polish
- FieldContextDebug 空状态补强
- （可选）Semantic "go create file" CTA

### PR C — 可视化可读性增强
- FileWriteCard diff preview + expand
- Composer image large preview

原因：
- PR A 可以优先落，马上给后续发版兜底
- PR B / C 风险独立，review 不会互相干扰
- 就算 PR C 拖期，也不影响 1.4.3 的主目标

如果你坚持按一个 PR 做，也可以，但不建议。

---

## 4. 验收清单

### 4.1 CI / packaging
- [ ] Release workflow package 后执行 verify step
- [ ] 刻意删掉 cloudflared / mobile dist 时，verify step fail
- [ ] 正常构建时 4 个平台全 success

### 4.2 Onboarding / 空状态
- [ ] 新用户 5 分钟内能看到 Last Injection 有内容
- [ ] Semantic 空状态明确告诉用户 memory.md 路径
- [ ] Checkpoint 空状态明确告诉用户 abort 一次后会生成

### 4.3 Edit / Write 卡片
- [ ] Edit tool card 能看到 diff preview
- [ ] 超长 diff 可展开全部 / 收起
- [ ] Write tool card 能看到内容前几行

### 4.4 图片大图预览
- [ ] 粘贴 PNG/JPG 到 Composer 后点击缩略图可看大图
- [ ] 关闭后附件仍在
- [ ] 发送后行为不变

---

## 5. 对后续版本的影响

完成 1.4.3 后：

- 1.4.4（Codex 大修）有 CI 兜底，不会再因为打包漏产物反复 hotfix
- 1.4.5（Memory 面板）可以建立在改善后的空状态和 onboarding 上，不需要从空白开始教育用户
- 用户第一次打开 1.4.x 就能看懂"现场提供"，不会再看到一堆空 tab

---

## 6. 推荐执行顺序

如果下一会话直接开工，建议顺序：

1. **先做 PR A（Release / onboarding guardrails）**
2. 再做 **PR C（FileWriteCard + image preview）** —— 用户最有感
3. 最后补 **PR B（Field 空状态）**

原因：
- PR A 最防御，先落地最安心
- PR C 是你今天用户直接点名的功能，体感收益最高
- PR B 文案类的收尾可以最后做

---

## 7. 参考文件

- `src/renderer/src/components/session-hq/cards/FileWriteCard.tsx`
- `src/renderer/src/components/diff/InlineDiffViewer.tsx`
- `src/renderer/src/components/session-hq/ComposerBar.tsx`
- `src/renderer/src/components/sessions/AttachmentPreview.tsx`
- `.github/workflows/release.yml`
- `README.md`
- `README.en.md`
- `docs/essays/2026-04-25-from-1-3-to-1-4-ai-native-workbench.md`
- `docs/plans/2026-04-25-memory-product-direction.md`

---

## 8. 给下一会话的启动语

> 做 v1.4.3，按 `docs/plans/2026-04-25-v1.4.3-plan.md` 执行。先做 PR A（release.yml post-package verify + onboarding + README.en.md），如果还有时间再做 PR C（FileWriteCard diff preview + Composer image large preview）。不要碰 Codex 大修、Pinned Facts、Memory 面板，这些不在本版范围。