# Phase 4: Iframe + Markdown New-System Stabilization - Context

**Gathered:** 2026-04-07
**Status:** Ready for planning

<domain>
## Phase Boundary

本阶段仅聚焦“新系统能力稳定化”，范围限定为：
1. iframe 场景下的宿主/子页面消息通信（selected skill、XClawUsed、fullscreen、clipboard）稳定；
2. markdown 导出链路（markdown/json/pdf/docx）稳定；
3. artifact 相关集成点在上述链路中的兼容性确认。

不新增业务能力，不改后端协议，仅做前端稳定化、容错与可验证性增强。

</domain>

<decisions>
## Implementation Decisions

### Iframe 消息协议稳定策略
- **D-01:** 统一以 `frontend/src/core/iframe-messages.ts` 作为消息类型单一真源，禁止在页面/Hook 内散落硬编码 type 字符串。
- **D-02:** 所有 `postMessage` 接收端先做 `type` 与最小字段校验，再进入业务逻辑；非法 payload 只记录调试日志，不触发 UI 错误。
- **D-03:** `selectedSkill` 重复消息保持幂等，沿用现有 key（thread + skill + language）防抖初始化逻辑。

### Iframe 路由与技能初始化行为
- **D-04:** `/workspace/chats/new` 与 `/workspace/chats/[thread_id]` 的路由判定仍以前端路由为真源，不再依赖历史接口成功与否。
- **D-05:** skill bootstrap 失败采用“可恢复错误”策略（toast/dialog），不阻断基础聊天输入与路由切换。
- **D-06:** `xclaw_used` 仅作为兼容参数，不作为新会话/历史渲染核心开关。

### Markdown 导出稳定策略
- **D-07:** 维持导出入口统一在 `core/threads/export.ts`，格式转换能力（docx/pdf）保持在 `core/utils/markdown-download/`，避免职责混叠。
- **D-08:** 转换失败必须可见（toast 或 error callback），且不影响会话继续使用。
- **D-09:** 文件名策略保持可预测（title 派生 + sanitize），并保证无消息时禁止导出。

### Artifact 集成点策略
- **D-10:** artifact 仍以线程 state 为来源，不在 Phase 4 引入新的 artifact 数据源。
- **D-11:** markdown 导出以消息内容为核心，artifact 链接保留现有 markdown 行为，不在本阶段扩展“artifact 打包导出”新能力。

### 测试与验证策略
- **D-12:** Phase 4 优先补“前端可控”的稳定性验证：消息协议、防重入、错误兜底、导出成功/失败路径。
- **D-13:** 与后端耦合点（如 `/history`）在 E2E 中采用“前端状态可验证优先”断言，减少无意义级联失败。

### the agent's Discretion
- 具体日志粒度、错误文案细节、hook 内部状态组织方式。
- 不中断主流程前提下的最小重构范围。

</decisions>

<specifics>
## Specific Ideas

- 保持 Titan 对齐方向：在前端契约层尽量“单一入口 + 显式容错 + 幂等执行”。
- 以“可恢复失败”替代“整页失败”：即使 skill bootstrap 或 history 出错，聊天主路径可继续。
- 导出体验保持轻量：用户只看到明确成功/失败反馈，不暴露底层转换细节。

</specifics>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Iframe 通信与技能联动
- `frontend/src/core/iframe-messages.ts` — iframe 消息类型与发送辅助函数。
- `frontend/src/hooks/use-iframe-skill.ts` — query + postMessage 双通道 skill 选择处理。
- `frontend/src/hooks/use-selected-skill-listener.ts` — selectedSkill 接收与 bootstrapRemoteSkill 调用链。
- `frontend/src/app/workspace/chats/[thread_id]/page.tsx` — 线程页内路由、欢迎态、skill 错误兜底和主交互承接。
- `frontend/src/lib/utils.ts` — iframe 场景 `copyToClipboard` 的父页面代理逻辑。

### Markdown 导出链路
- `frontend/src/components/workspace/export-trigger.tsx` — 导出入口与用户可见反馈。
- `frontend/src/core/threads/export.ts` — markdown/json 导出格式与下载实现。
- `frontend/src/core/utils/markdown-download/use-markdown-download.ts` — docx/pdf 下载状态管理与错误回调。
- `frontend/src/core/utils/markdown-download/converter.ts` — markdown 到 docx/pdf 的核心转换实现。

### Roadmap / Phase 约束
- `.planning/ROADMAP.md` — Phase 4 范围与目标定义。
- `.planning/phases/03-legacy-visual-alignment-pass/03-UAT.md` — 上一阶段遗留问题与验证边界。
- `.planning/phases/03-legacy-visual-alignment-pass/03-02-SUMMARY.md` — 已完成的前端侧 E2E 稳定化策略。

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `useSelectedSkillListener`：已经具备 bootstrap 幂等键、防重复初始化、错误弹窗能力，可直接扩展协议校验与容错分支。
- `useIframeSkill`：已覆盖 query 与 postMessage 两条输入通道，可作为统一入口继续收敛。
- `exportThreadAsMarkdown/exportThreadAsJSON`：导出职责清晰，适合作为导出稳定化主承载点。
- `useMarkdownDownload`：已提供下载中状态和错误回调，是 PDF/DOCX 稳定化的天然抓手。

### Established Patterns
- 前端通过 toast + 非阻断 UI 处理异步失败。
- 聊天路由在 Hook (`useThreadChat`) 中归一化，页面层消费“是否欢迎态/是否渲染历史”。
- 线程页将 artifact、消息、输入框拆为独立上下文与组件，便于局部加固。

### Integration Points
- `ChatPage` ↔ `useSelectedSkillListener`：selected skill 到 bootstrap 请求链。
- `ExportTrigger` ↔ `core/threads/export.ts`：导出按钮到文件下载链。
- `useIframeSkill` / `copyToClipboard` ↔ 宿主页 postMessage：iframe 能力对接链。

</code_context>

<deferred>
## Deferred Ideas

- artifact 打包导出（zip/多文件合并）属于新增能力，延后到独立 phase。
- 跨窗口消息安全增强（origin allowlist、签名校验）可在后续安全专项 phase 深化。
- 导出模板皮肤化（品牌样式、主题模板）不在本阶段。

</deferred>

---

*Phase: 04-iframe-markdown-new-system-stabilization*
*Context gathered: 2026-04-07*