perf(desktop): 优化流式正文动画与渲染 by DavidShenXD · Pull Request #3402 · makecindy/cindy

DavidShenXD · 2026-08-25T10:33:11Z

这次改了什么

摘要

承接 #3204 的流式正文淡入能力，优化消息级动画节奏和长回答的 Markdown 渲染成本，并为高速突发增加有界等待，避免正文已经占位却长时间透明。

变更类型

范围

关联 Issue / 需求：fix(desktop): 修复流式行内代码显示顺序 #3204 后续优化
本 PR 包含：消息级连续淡入时间线、160ms 高速突发保护、稳定 Markdown 前缀分片、动画结束轻量化，以及对应回归测试
明确不包含：非流式消息、静态 Markdown、代码块、KaTeX 和 Mobile 渲染路径
用户可见变化：普通流式正文按连续节奏浮现；高速输出自动追赶，不再形成大块透明空洞或孤立列表标记
是否存在 breaking change：无

UI 变化

界面效果：不改变布局、颜色或文案，仅调整流式正文的淡入节奏和高速追赶表现
实机证据：Windows Global 命名隔离沙盒中使用高速模型连续生成 30 条长编号列表；以下为同一轮输出的连续采样帧，能看到首批到达、词与行内代码同步淡入，以及后续批次连续追赶

用户验收：用户反馈“效果好了很多”
引用的设计规范：docs/design-rules/DESIGN.md §14.4 Motion & Transitions / Stream-word fade。本 PR 已将权威规范更新为经实机验收的消息级连续时间线：正常间隔 16ms、透明积压达到 96ms 后步长压缩为 4ms、透明等待封顶 160ms；继续遵守“仅流式助手正文、150ms opacity-only、reduced-motion 降级、终态无包装节点”的边界

怎么验证的

自动验证

pnpm test:unit:related
结果：通过；Desktop related 9

pnpm --filter desktop run --if-present typecheck
结果：通过

pnpm --filter desktop exec eslint src/renderer/components/chat/MarkdownRenderer.tsx src/renderer/components/chat/StreamFadeSpan.tsx src/renderer/components/chat/StreamingMarkdownChunk.tsx src/renderer/components/chat/rehypeStreamWordFade.ts src/renderer/components/chat/streamingMarkdownChunks.ts src/renderer/components/chat/__tests__/StreamFadeSpan.test.tsx src/renderer/components/chat/__tests__/rehypeStreamWordFade.test.ts src/renderer/components/chat/__tests__/streamingMarkdownChunks.test.tsx
结果：通过

pnpm check:dco
结果：通过；4 个提交签名有效

git diff --check origin/main...HEAD
结果：通过

手工验证

平台：Windows，Global 命名隔离沙盒 earnest-lederberg-c2de6c
启动判定：DESKTOP_DEV_VERDICT=ready
场景：高速模型连续生成 30 条长编号列表，观察大批词段集中到达时的淡入、列表标记/行内代码同步和界面响应
结果：连续采样中透明词段按有界时间线追赶，未出现长时间透明占位；用户验收通过

未执行的验证

未在本地执行全仓 pnpm test:unit：仓库工作流要求本地运行相关单测，完整单测由 CI 执行
未分别实机目检 Light / Dark：本次只动画 opacity，并复用语义动效 token，不改变主题颜色；如实保留该未验证项

风险

风险分类

无已知风险
SQLite / migration
system prompt
协议兼容
权限 / 安全 / 用户数据
存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
原生层 / fingerprint / OTA
跨平台差异
其他：流式动画时序与 Markdown 分片边界

影响与回滚

影响范围：仅 Desktop 流式助手正文；引用定义、多标题、HTML 块、数学块等需要全局上下文的 Markdown 自动回退整篇解析
回滚 / 降级方式：回退本提交即可恢复 fix(desktop): 修复流式行内代码显示顺序 #3204 合入后的行为；用户也可关闭流式动效，prefers-reduced-motion 会自动禁用动画
移动端冷更判断：不触发。本 PR 仅修改 Desktop Renderer、样式、测试与对应设计规范，不涉及 apps/mobile 原生配置、原生依赖或 runtime fingerprint
存量插件影响：无

提交前检查

已 review 完整 diff
每个 commit 都带 DCO 签名（git commit -s，见 DCO）
UI 改动已在「UI 变化」注明引用的设计规范章节（不涉及 UI 则跳过）
未提交凭证、令牌或授权文件
已补充必要文档（已对齐 DESIGN.md §14.4 并附隔离实机连续帧证据）
已确认测试结果或说明未执行原因

Signed-off-by: DavidShen <david@xd.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 03c9661bef

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

greptile-apps · 2026-08-25T10:37:39Z

Greptile Summary

本 PR 优化 Desktop 流式助手正文的动画节奏与 Markdown 渲染成本。

将稳定 Markdown 前缀拆分并缓存，仅重新解析持续增长的尾部分片。
为词段和列表标记引入共享的连续淡入时间线，并将突发等待限制在 160ms。
对需要全局 Markdown 上下文的内容回退到整篇解析，并补充相关回归测试与设计说明。

Confidence Score: 5/5

当前 HEAD 已修复先前报告的转义引用标签检测问题，未发现仍阻塞合并的故障。

当前实现允许引用标签中的反斜线转义对，并通过整篇解析回退避免引用与定义被拆入不同 Markdown 实例，因此没有阻塞性故障残留。

Important Files Changed

Filename	Overview
apps/desktop/src/renderer/components/chat/MarkdownRenderer.tsx	接入流式 Markdown 分片渲染，并在非流式终态继续使用普通整篇解析。
apps/desktop/src/renderer/components/chat/StreamingMarkdownChunk.tsx	新增可记忆的分片渲染组件，并协调分片级淡入状态与整篇回退。
apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts	实现稳定前缀分片及引用定义、标题和 HTML 块的全局上下文保护。
apps/desktop/src/renderer/components/chat/rehypeStreamWordFade.ts	将逐词动画调整为消息级共享时间线，并增加突发等待上限。
apps/desktop/src/renderer/components/chat/StreamFadeSpan.tsx	在 DOM 提交阶段调度词段和列表标记动画，并轻量化已完成节点。
apps/desktop/src/renderer/components/chat/tests/streamingMarkdownChunks.test.tsx	覆盖分片边界、全局上下文回退、DOM 复用和共享动画时间线。

_{Reviews (4): Last reviewed commit: "docs(design): align stream fade timing" | Re-trigger Greptile}

Signed-off-by: DavidShen <david@xd.com>

DavidShenXD · 2026-08-25T10:51:44Z

反馈已处理

已处理：

已评估“同批词段立即开始”建议：不回退已由用户实机验收的消息级连续节奏；现有 16ms 节奏、96ms 积压压缩、160ms 最大透明等待，以及行内代码/列表标记共享时间线共同避免高速输出异常。
已支持 CommonMark 的 1) 括号式有序列表 marker，避免 loose list 被拆到不同 Markdown 实例。
已支持引用定义标签中的反斜线转义，避免 [foo\]bar] 引用与定义被错误分片。
已删除未批准的第四条 easing，流式正文和列表 marker 改为复用 --motion-ease-out。

变更：

提交 9d840f926 更新 Markdown 分片边界、流式动效 token 及对应回归测试；四个 review conversation 均已逐条回复并 resolved。

验证：

pnpm test:unit:related：通过，Desktop related 9。
pnpm --filter desktop run --if-present typecheck：通过。
定向 Vitest：通过，2 个文件、37 项测试。
定向 ESLint、git diff --check、pnpm check:dco：通过。

备注：

仅修改 Desktop Renderer、CSS 与测试，不触发 Mobile 冷更；push 后不等待 GitHub Actions、CodeQL 或自动 review 完成。

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9d840f926e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

MagicLizi · 2026-08-25T11:06:18Z

@DavidShenXD 👋 这个 PR 还有 1 条 review conversation 没 resolve(apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts),auto-review 因此暂时跳过、没法继续审查 / 合并。

如果你已经按评论改完或回应了,请到对应 thread 上点 Resolve conversation;全部 resolve 后,下一轮 auto-review 会自动重新审查这个 PR。

Signed-off-by: DavidShen <david@xd.com>

DavidShenXD · 2026-08-25T11:08:16Z

反馈已处理

已处理：

已修复全局 Markdown 上下文晚到时，多分片骤然回退为整篇解析并重播已完成正文的问题。

变更：

提交 a93cf75c2 在整篇 candidate 中按原文起点合并既有分片的淡入匹配历史，复用旧 key 与共享时间线；layout commit 后清理旧分片状态。
新增真实渲染回归测试：追加第二个标题触发整篇回退后，旧 key 保持 settled，仅新标题淡入。

验证：

定向 Vitest：通过，3 个文件、44 项测试。
pnpm test:unit:related：通过，Desktop related 9。
pnpm --filter desktop run --if-present typecheck：通过。
定向 ESLint、git diff --check、pnpm check:dco：通过。

备注：

仅修改 Desktop Renderer 与测试，不触发 Mobile 冷更；push 后不等待 GitHub Actions、CodeQL 或自动 review 完成。

MagicLizi · 2026-08-25T12:45:56Z

命中 UI 路径(apps/desktop/src/renderer/components/chat/MarkdownRenderer.tsx / apps/desktop/src/renderer/components/chat/StreamFadeSpan.tsx / apps/desktop/src/renderer/components/chat/StreamingMarkdownChunk.tsx 等)但 description 未附界面效果证据——建议补充改动后效果:截图/录屏,或改动后界面的 HTML 页面(```html 代码块、.html 附件或在线预览链接),便于确认界面符合 DESIGN.md 设计规范

MagicLizi

流式淡入的节奏已经改成了 16ms / 96ms / 160ms，但权威规范还写着「普通聊天禁止跨段 stagger、新段一律 0ms」。

[P1] docs/design-rules/DESIGN.md:689
§14.4 红线仍是 ordinary chat no cross-segment stagger，同一 render 新到的段从 0ms 起。实现（rehypeStreamWordFade.ts 53-57、202-215）和测试锁的是消息级 16ms 节奏、96ms 后压到 4ms、可见等待封顶 160ms。Windows 上的观感可以接受，但必须先改 §14.4 承认 16/96/160（inline code 与 list marker 走同一时间线），不能让红线和已上船的节奏互相打架。不要只改注释。

Signed-off-by: DavidShen <david@xd.com>

DavidShenXD · 2026-08-25T13:19:12Z

反馈已处理

已处理：

UI 效果证据：已在 PR description 补充当前 PR worktree 的 Windows Global 隔离实机连续帧；测试为高速模型生成 30 条长编号列表，证据覆盖首批到达、正文与行内代码同步淡入、后续批次连续追赶。证据文件：pr-3402-burst-contact-sheet.png。
设计规范冲突：确认反馈属实。没有回退用户已验收的连续节奏；已把权威规范 DESIGN.md §14.4 Stream-word fade 对齐为消息级连续时间线：正常间隔 16ms、透明积压达到 96ms 后步长压缩为 4ms、透明等待封顶 160ms，并保留已显示内容不重播、列表标记/行内代码共用时间线等红线。

变更：

新增提交 5b6cc5e4a docs(design): align stream fade timing 并已 push。
更新 docs/design-rules/DESIGN.md，补充隔离实机连续帧证据，并同步更新 PR description 的 UI 变化、设计依据和验证结果。

验证：

pnpm test:unit:related：通过（Desktop related 9）。
pnpm --filter desktop run --if-present typecheck：通过。
pnpm check:dco：通过（4 个提交签名有效）。
git diff --check origin/main...HEAD：通过。
pnpm restart:desktop:remote --region=global -- --isolated=@worktree：DESKTOP_DEV_VERDICT=ready；隔离沙盒高速生成 30 条编号列表并完成连续帧采样。

备注：

未分别实机目检 Light / Dark；本 PR 只调整 opacity 动画并复用语义动效 token，不改变主题颜色。完整 CI 当前由 GitHub 运行，本轮不等待其完成。

这些问题已在当前 head 的后续 commit 中修复(格式门/安全门已通过),自动 dismiss 旧的 CHANGES_REQUESTED 以解除合并阻塞。

perf(desktop): 优化流式正文动画与渲染

03c9661

Signed-off-by: DavidShen <david@xd.com>

DavidShenXD requested a review from a team as a code owner August 25, 2026 10:33

chatgpt-codex-connector Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread apps/desktop/src/renderer/components/chat/rehypeStreamWordFade.ts

Comment thread apps/desktop/src/renderer/styles/globals.css Outdated

Comment thread apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts Outdated

greptile-apps Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts

fix(desktop): 修正流式 Markdown 边界与动效曲线

9d840f9

Signed-off-by: DavidShen <david@xd.com>

chatgpt-codex-connector Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts

fix(desktop): 避免流式整篇回退重播正文

a93cf75

Signed-off-by: DavidShen <david@xd.com>

MagicLizi added status:ci-failed CI 失败(review-pr 自动维护,仅展示) touches:core 改动碰到架构核心路径(review-pr 自动维护,仅展示) touches:product-ui 改动碰到产品 / UI 面(review-pr 自动维护,仅展示) labels Aug 25, 2026

MagicLizi removed the status:ci-failed CI 失败(review-pr 自动维护,仅展示) label Aug 25, 2026

MagicLizi previously requested changes Aug 25, 2026

View reviewed changes

docs(design): align stream fade timing

5b6cc5e

Signed-off-by: DavidShen <david@xd.com>

MagicLizi added the touches:rules 改动碰到规则 / 规范文档(review-pr 自动维护,仅展示) label Aug 25, 2026

Navigation Menu

Uh oh!

perf(desktop): 优化流式正文动画与渲染 - #3402

perf(desktop): 优化流式正文动画与渲染#3402
DavidShenXD wants to merge 4 commits into
mainfrom
cindy/stream-fade-followup

DavidShenXD commented Aug 25, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 25, 2026 •

edited

Loading

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

DavidShenXD commented Aug 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

MagicLizi commented Aug 25, 2026

Uh oh!

DavidShenXD commented Aug 25, 2026

Uh oh!

MagicLizi commented Aug 25, 2026

Uh oh!

MagicLizi left a comment

Uh oh!

DavidShenXD commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

DavidShenXD commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

这次改了什么

摘要

变更类型

范围

UI 变化

怎么验证的

自动验证

手工验证

未执行的验证

风险

风险分类

影响与回滚

提交前检查

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

DavidShenXD commented Aug 25, 2026

反馈已处理

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

MagicLizi commented Aug 25, 2026

Uh oh!

DavidShenXD commented Aug 25, 2026

反馈已处理

Uh oh!

MagicLizi commented Aug 25, 2026

Uh oh!

MagicLizi left a comment

Choose a reason for hiding this comment

Uh oh!

DavidShenXD commented Aug 25, 2026

反馈已处理

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DavidShenXD commented Aug 25, 2026 •

edited

Loading

greptile-apps Bot commented Aug 25, 2026 •

edited

Loading