| phase |
plan |
type |
wave |
depends_on |
files_modified |
autonomous |
requirements |
must_haves |
| 04-iframe-markdown-new-system-stabilization |
01 |
execute |
1 |
| 03-legacy-visual-alignment-pass |
|
| frontend/src/core/iframe-messages.ts |
| frontend/src/hooks/use-iframe-skill.ts |
| frontend/src/hooks/use-selected-skill-listener.ts |
| frontend/src/lib/utils.ts |
| frontend/src/components/workspace/chats/use-thread-chat.ts |
| frontend/src/core/threads/export.ts |
| frontend/src/components/workspace/export-trigger.tsx |
| frontend/src/core/utils/markdown-download/use-markdown-download.ts |
| frontend/src/core/utils/markdown-download/converter.ts |
| frontend/tests/e2e/input-and-compose.spec.ts |
| frontend/tests/e2e/message-and-history.spec.ts |
|
true |
|
| truths |
artifacts |
key_links |
| iframe 通信链路（selectedSkill / xclaw / fullscreen / clipboard）在前端侧具备可校验输入与容错，不因异常 payload 中断聊天主流程。 |
| markdown 导出链路（markdown/json/docx/pdf）在成功/失败路径均可被用户感知，且失败不破坏会话使用。 |
| artifact 与导出集成保持当前能力边界，不引入后端改造或新业务能力。 |
|
| path |
provides |
| frontend/src/core/iframe-messages.ts |
iframe 消息协议真源与类型边界 |
|
| path |
provides |
| frontend/src/hooks/use-selected-skill-listener.ts |
selectedSkill 初始化幂等与容错强化 |
|
| path |
provides |
| frontend/src/core/threads/export.ts |
导出链路稳定与下载行为可预期 |
|
| path |
provides |
| frontend/src/core/utils/markdown-download/use-markdown-download.ts |
docx/pdf 下载状态与错误回调一致性 |
|
|
| from |
to |
via |
pattern |
| iframe-messages.ts |
use-iframe-skill.ts / use-selected-skill-listener.ts |
统一消息类型 + 接收端校验 |
selectedSkill|XClawUsed|fullscreen|copyToClipboard |
|
| from |
to |
via |
pattern |
| export-trigger.tsx |
core/threads/export.ts + markdown-download/* |
导出入口与转换实现分层 |
export|download|docx|pdf |
|
|
|
完成 Phase 4 的新系统能力稳定化：在不改后端协议、不扩 scope 的前提下，强化 iframe 通信与 markdown 导出的前端稳定性与可验证性。
Purpose: 落实 LOGIC-01 / LOGIC-02，消除前端可控链路中的不稳定点。
Output: iframe 通信与导出链路具备明确容错、幂等和测试护栏。
@.planning/PROJECT.md
@.planning/REQUIREMENTS.md
@.planning/ROADMAP.md
@.planning/phases/04-iframe-markdown-new-system-stabilization/04-CONTEXT.md
@.planning/phases/03-legacy-visual-alignment-pass/03-UAT.md
@.planning/phases/03-legacy-visual-alignment-pass/03-02-SUMMARY.md
@frontend/src/core/iframe-messages.ts
@frontend/src/hooks/use-iframe-skill.ts
@frontend/src/hooks/use-selected-skill-listener.ts
@frontend/src/core/threads/export.ts
@frontend/src/core/utils/markdown-download/use-markdown-download.ts
Task 1: Iframe 消息协议与技能联动容错加固
（LOGIC-01
）
frontend/src/core/iframe-messages.ts
frontend/src/hooks/use-iframe-skill.ts
frontend/src/hooks/use-selected-skill-listener.ts
frontend/src/lib/utils.ts
frontend/src/components/workspace/chats/use-thread-chat.ts
- Test 1: 接收非法/缺字段 postMessage 时不会抛出未捕获异常，也不会打断聊天输入与路由。
- Test 2: selectedSkill 重复消息不会重复触发 bootstrap
（幂等
）。
- Test 3: iframe 场景复制动作始终通过父页面消息代理，非 iframe 场景走原生 clipboard。
统一消息类型入口，补齐接收端最小校验与早返回分支；保留现有成功链路行为不变，仅增强异常输入与重复输入的稳定性。确保 skill bootstrap 失败是“可恢复失败”，不阻断主流程。
cd frontend && npm run lint
iframe 通信链路在异常输入下保持稳定，且核心聊天路径不中断。
Task 2: Markdown 导出链路稳定化
（LOGIC-02
）
frontend/src/components/workspace/export-trigger.tsx
frontend/src/core/threads/export.ts
frontend/src/core/utils/markdown-download/use-markdown-download.ts
frontend/src/core/utils/markdown-download/converter.ts
- Test 1: 无消息时导出入口禁止触发并给出明确反馈。
- Test 2: markdown/json 导出文件名可预测且可下载。
- Test 3: docx/pdf 转换失败时可见且不影响页面继续操作。
维持“入口
（ExportTrigger
）- 格式化导出
（threads/export
）- 文档转换
（markdown-download
）”分层
；补足失败分支可见性与保护逻辑
，避免静默失败与状态错乱。
cd frontend && npm run lint
导出链路成功/失败路径可解释，且对会话交互无副作用。
Task 3: 前端可控回归护栏
（Phase 4 Integration
）
frontend/tests/e2e/input-and-compose.spec.ts
frontend/tests/e2e/message-and-history.spec.ts
frontend/tests/e2e/support/chat-helpers.ts
- Test 1: 关键路由/输入/发送场景在后端异常下仍能给出稳定、可解释结果。
- Test 2: 与历史加载耦合的断言不再制造无意义级联失败。
- Test 3: 导出相关可见状态（有无消息）具备稳定断言。
对现有 E2E 用例做最小必要收敛，优先验证前端可控行为与页面状态；后端不稳定场景保留可定位证据但不污染无关断言。
cd frontend && npm run test:e2e -- input-and-compose.spec.ts message-and-history.spec.ts
Phase 4 风险点拥有前端可控的自动化回归护栏。
<threat_model>
Trust Boundaries
| Boundary |
Description |
parent window -> iframe child |
postMessage 来源与 payload 不可信，前端需先校验再执行业务逻辑 |
UI export action -> file generation |
导出链路涉及浏览器下载与第三方转换库，需显式处理异常 |
STRIDE Threat Register
| Threat ID |
Category |
Component |
Disposition |
Mitigation Plan |
| T-04-01 |
T (Tampering) |
iframe postMessage payload |
mitigate |
接收端 schema 最小校验 + 非法消息早返回 |
| T-04-02 |
D (Denial of Service) |
repeated selectedSkill bootstrap |
mitigate |
幂等 key 去重与并发保护，避免重复请求风暴 |
| T-04-03 |
R (Repudiation) |
export failure observability |
mitigate |
转换失败统一可见反馈与日志锚点 |
| T-04-04 |
I (Information Disclosure) |
artifact/export scope |
accept |
本阶段不扩展后端数据面，仅前端稳定化 |
| </threat_model> |
|
|
|
|
1. `lint` 无 error 级阻塞。
2. Phase 4 目标 E2E 用例可执行并产出稳定结果。
3. 手动抽查 iframe 消息异常输入场景与导出失败场景，确认主流程不被阻断。
<success_criteria>
- LOGIC-01：iframe 通信与 selectedSkill 链路具备前端容错与幂等，不因异常 payload 导致主流程失败。
- LOGIC-02：markdown 导出链路稳定，失败可见且不中断会话。
</success_criteria>
After completion, create `.planning/phases/04-iframe-markdown-new-system-stabilization/04-SUMMARY.md`