6.0 KiB

Raw Blame History

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

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

## Phase Boundary

本阶段仅聚焦“新系统能力稳定化”，范围限定为：

iframe 场景下的宿主/子页面消息通信（selected skill、XClawUsed、fullscreen、clipboard）稳定；
markdown 导出链路（markdown/json/pdf/docx）稳定；
artifact 相关集成点在上述链路中的兼容性确认。

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

## 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 内部状态组织方式。
不中断主流程前提下的最小重构范围。

## Specific Ideas

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

<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 Ideas

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

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

6.0 KiB Raw Blame History Unescape Escape