Unsloth Studio 内联图片渲染兼容性验证指南：从 Playwright 夹具到 Markdown 沙箱图片管线

• 人工智能
• 大模型
• 微调
• LoRA
• 模型优化
• 模型量化
• 强化学习

导读

本文面向 Unsloth Studio 前端/测试工程师，围绕仓库内tests/studio/fixtures/inline-images.md这套"内联图片模拟（Inline image simulations）"测试夹具，系统讲解它是如何以最小代价复刻生产环境 Markdown 渲染器、桌面端内容安全策略（CSP）与鉴权沙箱图片服务，并对路径规范化、编码分隔符、作用域切换、流式渲染、失败恢复、浏览器解码差异等边界场景进行自动化验证的。读完本文，你将掌握该夹具的完整运行命令、参数语义、覆盖矩阵（2,100 种路径/标记组合与 59 个浏览器用例），并理解其背后的前端实现——MarkdownImage渲染器、useSandboxImage鉴权拉取、rehypeSandboxImages路径改写与后端沙箱文件路由的完整调用链。

一、为什么需要一套"内联图片模拟"夹具

Unsloth Studio 的聊天界面允许模型在回答中直接书写 Markdown 图片语法（例如plot），指向工具调用（python/terminal）在沙箱工作目录里生成的图片文件。这条链路涉及三层风险：

1. 鉴权：沙箱文件路由要求Authorization: Bearer <token>，而浏览器原生<img>无法携带自定义请求头，直接渲染会收到 401，出现"Image not available"占位符；
2. 安全：文件名由模型自由选择，..、编码后的%2e%2e、反斜杠、控制字符、javascript:等都可能被用作路径逃逸或脚本注入载体；
3. 兼容：不同浏览器的图片解码能力不同（例如 Windows 实验版 WebKit 可能不支持 AVIF），且流式输出过程中 Markdown 链接可能不完整、作用域（线程/项目）可能中途切换。

inline-images.md 描述的这套夹具正是为了系统性地回归这些场景：它不启动任何推理后端，而是由一个回环（loopback）服务器直接供给生成的栅格图片文件、校验 Bearer 鉴权，并记录每次请求所声称的沙箱作用域。测试用生产 Markdown 渲染器 + 桌面端 CSP 挂载页面，从而把"浏览器里发生了什么"与"后端推理发生了什么"完全解耦。

二、夹具架构：两条执行路径的配合

从仓库源码看，这套夹具由两个文件协作完成：

• inline-image-server.mjs：基于 Vite 的 Node 服务器。它读取images.json（由 Python 侧预生成的多格式栅格图）、加载studio/frontend的vite.config.ts、从 tauri.conf.json 中解析出桌面端 CSP 并作为响应头下发，最后把 inline-image-client.js 作为虚拟模块注入页面。
• playwright_inline_images.py：Python 侧的编排器。它用 Pillow 生成 5 种宽度（32/48/64/80/96）× 7 种格式（png/jpg/jpeg/gif/webp/bmp/avif）的测试图，启动上述 Node 服务器，再驱动 Playwright 在指定浏览器中运行Run simulations，收集报告、验证下载行为并截取失败截图。

2.1 服务器侧的核心中间件

inline-image-server.mjs在configureServer里注册了一组以/inline-fixture/*为前缀的端点：

沙箱文件端点/api/inference/sandbox/<session>/<filename>模拟了真实后端行为：无 Bearer 返回 401；missing.png返回 404；forbidden.png返回 403；broken.png返回 200 但内容是非法图片字节；slow.png延迟 500ms 响应——这正是验证"慢响应不能覆盖新作用域"竞态的关键。此外，不同会话名（thread-a、thread-b、project-p1、recorded、session/id）映射到不同图片宽度，从而可以在浏览器侧断言"渲染出来的是当前作用域对应的那张图"。

值得注意，服务器还把variant === "before"模式下 markdown-text.tsx 与 markdown-data-images.ts 替换为git show <baseline>:studio/frontend/src/...取出的历史版本，用于复现"相对图片路径修复之前"的原始缺陷。这是整个夹具"能复现、能对照"的基础。

2.2 客户端侧：真实渲染器 + 断言脚本

inline-image-client.js 以 React 应用的形式挂载了生产组件MarkdownTextSource（messageHasRenderableRenderHtmlTool: false），外面包着ChatProjectScopeContext与AssistantRuntimeProvider。每个用例通过show({ text, thread, project, streaming, offscreen })切换渲染输入，然后：

• loaded(width)轮询img[data-streamdown="image"]，断言naturalWidth等于期望宽度且currentSrc以blob:开头；
• requests()拉取/inline-fixture/requests，断言每个用例只产生了预期的、带鉴权的沙箱请求；
• 每个用例结果进入checks数组，最终 POST 到/inline-fixture/report。

页面还会监听securitypolicyviolation，把 CSP 违规写入#errors，测试最后断言没有违规——这正是"夹具在桌面端 CSP 下运行"的验证点。

三、环境准备与完整运行步骤

inline-images.md 给出的 macOS/Linux 运行流程如下（从仓库根目录执行）：

uv venv temp/inline-image-validation/venv uv pip install --python temp/inline-image-validation/venv/bin/python playwright==1.62.0 pillow==12.3.0 export PLAYWRIGHT_BROWSERS_PATH="$PWD/temp/inline-image-validation/browsers" temp/inline-image-validation/venv/bin/python -m playwright install chromium firefox webkit temp/inline-image-validation/venv/bin/python tests/studio/playwright_inline_images.py

关键点：

• 依赖版本是固定的：playwright==1.62.0、pillow==12.3.0，避免浏览器自动化与图像编码行为漂移；
• 浏览器二进制与仓库解耦：PLAYWRIGHT_BROWSERS_PATH指向仓库内的temp/inline-image-validation/browsers，不会污染系统全局缓存；
• 前端依赖前置条件：必须在 studio/frontend 下先执行npm ci，因为服务器要在运行时importVite 与前端源码；
• Windows 差异：venv 解释器路径为venv/Scripts/python.exe，PLAYWRIGHT_BROWSERS_PATH需在 PowerShell 中设置（例如$env:PLAYWRIGHT_BROWSERS_PATH="$PWD\temp\inline-image-validation\browsers"）；
• 输出目录约束：--output必须位于仓库内部（playwright_inline_images.py中output.is_relative_to(REPO)校验），报告、下载与失败截图统一落在该目录下。

Python 侧的夹具生成逻辑（playwright_inline_images.py 的fixtures()）会用Image.new("RGB", (width, 24), ...)生成 24px 高的横向测试图，并写出images.json；随后subprocess.Popen拉起 Node 服务器并等待ready.json（内含http://127.0.0.1:<port>/inline-images）。服务器进程收到 SIGINT/SIGTERM 时优雅退出。

四、浏览器矩阵与参数速查

inline-images.md 明确说明：默认浏览器矩阵是 chromium、firefox、webkit。可以这样覆盖：

• --browsers chrome msedge：使用本机已安装的 Chrome / Edge（通过 Playwright 的channel启动）；
• --manual：只启动服务器并打印 URL，由人用任意浏览器（含 Safari）手动测试；服务器会阻塞等待；
• --probe：不启动夹具，只逐浏览器拉起/关闭一次，用于快速确认浏览器二进制可用（inline-image-client.js 之外的独立探测路径）；
• --baseline FULL_COMMIT_SHA：传入完整 40 位 SHA，进入"修复前"对照模式。

文档特别强调了两点浏览器语义：

1. WebKit 自动化 ≠ Safari 应用测试：WebKit 自动化引擎覆盖的只是引擎覆盖，不能替代真实 Safari 应用的验证；
2. 每种格式有独立的浏览器解码控制：测试先用new Image()+control.decode()探测浏览器能否解码该格式。若不能（当前特指 AVIF，例如 Windows 实验版 WebKit），则该格式用例改为断言出现image-fallback占位符、图片naturalWidth === 0，并把格式记入报告的unsupportedFormats；而png等"必需栅格编解码器"仍必须正常解码。

4.1 运行参数汇总

五、覆盖矩阵：2,100 种组合与 59 个浏览器用例

文档给出两组关键数字：

• 前端管线测试覆盖 2,100 种路径与标记组合：对应 markdown-text.tsx 中MarkdownTextRenderer对路径/标记的解析管线；
• 浏览器夹具覆盖 59 个用例：即inline-image-client.js里注册的check(...)用例数量级（路径 5 例、文件名 9 例、格式 7 例、作用域 3 例、标记 3 例、内嵌 1 例、根资源 1 例、拒绝 17 例、非图片 4 例、事件处理器 1 例、失败恢复 3 例、未鉴权 1 例、作用域切换 1 例、慢响应竞态 1 例、离屏 1 例、流式 1 例等）。

这些用例按主题可分为五大类：

5.1 路径与文件名的规范化

相对路径类（全部应映射到当前线程作用域thread-a）：

编码文件名类（模型完全可能输出这种名字）：loss curve.png、café.png、日本語.png、100%.png、plot #1.png、plot?1.png、literal%2F.png、a+b.png、paren(1).png——它们以encodeURIComponent(name)形式进入 Markdown，期望请求保持同样的编码形式，验证"编码后再解码"不丢真。100%.png是真实文件名，孤立的%不能导致渲染崩溃（前端decodeSegment对解码失败做了兜底，见 sandbox-files.ts）。

5.2 作用域解析

• 当前作用域回退：裸相对路径（未记录会话）回退到project-<projectId>（有项目）否则threadId（sandboxSessionIdFor的逻辑）；
• 记录的作用域优先：src 中记录了会话（/api/inference/sandbox/<sid>/...）时，以记录值为准——这正是"聊天被移动到其他项目后，旧消息里的图片仍指向当初写入时的目录"的保证（markdownSandboxImageSrc的语义，见 sandbox-files.ts）；
• 非路径安全会话走查询参数：会话 id 不满足PATH_SAFE_SESSION（[A-Za-z0-9_-]{1,64}）时，路由退化为/api/inference/sandbox/_/<file>?session=<id>（sandboxRoutePrefix与sandboxSessionInSrc对称处理）。

客户端用例依次断言：线程作用域thread-a（32px）、项目作用域project-p1（64px）、记录作用域recorded（80px）、查询参数会话?session=session%2Fid（96px）——每条都通过"渲染出对应宽度的图"来证明作用域生效。

5.3 标记形态兼容

三种 Markdown/HTML 写法都验证"请求全部带鉴权 + 不产生块级容器污染段落"：

• <img src="outputs/plot.png" alt="Plot">（HTML 直写）
• ![Plot][chart]+ 引用式定义[chart]: outputs/plot.png
• Plot（图片包在链接里）

另有内嵌 PNG用例：data:image/png;base64,...直通渲染，且断言requests()为空（内嵌图绝不触发沙箱请求）；根资源用例：/assets/fixture.png属于应用自有静态资源而非沙箱文件，仍可正常渲染（sandboxFileForSrc对非沙箱前缀的绝对路径返回 null，直接原样渲染）。

5.4 拒绝清单（17 个恶意/越界 src）

inline-image-client.js逐一断言"不产生图片节点 + 不产生任何沙箱请求"：

这些断言之所以成立，是因为前端在渲染前做了两层把关：

• rehype-sandbox-images.ts 的unsafeImagePath()在解码后逐段检查..、/、\与控制字符（含 ASCII 0x00–0x1F、0x7F），命中即把src置为undefined；
• safe-markdown-url.ts 的safeMarkdownUrl对非img节点走 Streamdown 默认转换；对img节点只放行data:/blob:与无 scheme 的相对路径，javascript:、http(s)、协议相对地址一律返回 null。

5.5 非图片内容、事件处理器与失败恢复

• 非图片内容：纯文本plot.png、行内代码`Plot`、代码块```python ... ```、外部文档链接[Documentation](https://example.invalid/page)均不得变成图片、不得触发请求；
• HTML 事件处理器剥离：<img src="plot.png" onload=... onerror=...>渲染成功后，document.title不得变为UNSAFE，且 DOM 上onload/onerror属性必须不存在（Streamdown 的 sanitize 已移除）；
• 失败恢复：missing.png（404）、forbidden.png（403）、broken.png（非法字节）都必须先显示data-streamdown="image-fallback"占位符，随后切换到合法plot.png时占位符必须消失、图片正常加载。

六、竞态、离屏与流式场景（前端的硬骨头）

夹具对前端渲染的时序问题有专门用例：

1. 作用域切换使缓存失效：依次thread-a(32)→thread-b(48)→project-p1(64)→thread-a(32)渲染同一句Plot，每一步都必须渲染出该作用域对应的宽度。底层原因是markdown-text.tsx中sandboxScopeKey = JSON.stringify([threadId, projectId])参与 Streamdown 的key，作用域变化即换 key、重建处理器（withDataImageSupport的 rehypePlugins 也随[threadId, projectId]重建）。
2. 慢响应不能覆盖新作用域：先请求slow.png（500ms 延迟），70ms 后切到thread-b的plot.png；650ms 后断言仍是 48px——useSandboxImage以 url 为键的 state 守卫（"stale response 不能写入它未被请求的 url"）保证旧响应被丢弃。
3. 离屏图片等待可见性：offscreen: true时图片被推到视口下 2500px，断言 100ms 内无任何请求；scrollIntoView后才加载——useSandboxImage用IntersectionObserver（rootMargin: "200px"）控制拉取时机（见 use-sandbox-image.ts）。
4. 流式链接补全：Markdown 每 3 个字符增量推送（streaming: true），期间保持链接语法不完整，最后一次性给全；断言最终图片正常加载——流式渲染管线stabilizeStreamingMarkdown+ 增量缓存必须容忍"链接尚未闭合"。

下载路径的验证也值得一提：Playwright 侧对plot.png、内嵌 PNG（下载名Embedded.png）、编码文件名（下载名loss curve #1.png，即解码后落盘）分别点击下载按钮，断言suggested_filename、图片尺寸(32, 24)，并且下载前后沙箱请求历史完全一致——证明下载复用了已拉取的 blob，绝不二次请求沙箱文件。

七、对照模式：用--baseline复现原始缺陷

文档给出了复现原始缺陷的标准姿势：

# 修复前的 commit，必须缺失"相对图片路径"修复 temp/inline-image-validation/venv/bin/python tests/studio/playwright_inline_images.py \ --baseline FULL_COMMIT_SHA --output temp/inline-image-validation/before

机制是：服务器侧把 markdown-text.tsx 与 markdown-data-images.ts 替换为基线 commit 的版本（git show <sha>:studio/frontend/src/<file>），并使用独立的cache-before缓存目录；客户端收到variant: "before"后只跑两个控制用例：

• path: plot.png（裸文件名）——必须失败；
• recorded scope（显式沙箱 URL）——必须通过。

Python 侧最终断言：所有浏览器上"裸文件名失败"且"显式 URL 通过"，否则报Baseline controls did not reproduce the bug。这组正反控制证明：修复前，模型书写plot（无显式沙箱 URL）时图片无法加载，而显式/api/inference/sandbox/<sid>/plot.png可以；修复后，after变体的 59 个用例全部通过。

八、从夹具反推生产管线的实现原理

夹具之所以能模拟得如此逼真，是因为它挂载的就是生产组件。从源码可以把整条链路串起来：

1. 路径改写：rehype-sandbox-images.ts 在 URL 加固（harden）之前遍历 hast 树，对每个img先过safeMarkdownUrl与unsafeImagePath，再调用markdownSandboxImageSrc(safe, scope)——有结果就用沙箱 URL 替换，否则保留原值或置空；
2. 作用域决议：sandbox-files.ts 的sandboxFileForSrc拒绝带 scheme、协议相对、含../编码分隔符/控制字符的 src；markdownSandboxImageSrc取"src 自记录的会话"优先、否则回退project-<id>/threadId；最终sandboxFilePath逐段encodeURIComponent拼 URL（子目录outputs/report.csv里的/不被转义）；
3. 鉴权拉取：use-sandbox-image.ts 用authFetch（带 Bearer）+IntersectionObserver近视口触发 +AbortController+URL.createObjectURL，把受保护文件变成blob:URL；以 url 为键的 state 守卫杜绝竞态；
4. 渲染与兜底：markdown-text.tsx 的MarkdownImage注册为 Streamdown 的img组件（整块替换默认渲染器），渲染blob:或直通data:/blob:，失败时显示data-streamdown="image-fallback"（"Image not available"），并提供悬停下载按钮（复用已拉取的 blob，命名规则见downloadName：真实扩展名优先，否则从 blob 类型推断并以 alt 兜底）；
5. CSP 与 data: 图片：markdown-data-images.ts 的withDataImageSupport向 Streamdown 默认 sanitize schema 追加data协议——因为默认 schema 只允许http(s)图片源，data:image/...会在 sanitize 阶段被剥掉，必须在 harden 前放行。而生产 CSP（tauri.conf.json）中img-src 'self' data: blob: https:允许data:/blob:渲染，不允许任何远程http(s)图片（远程 src 在 sanitize 层已被拦截）。

后端侧的对应实现位于 inference.py 的serve_sandbox_file：路由/sandbox/{session_id}/{filename:path}先经_authenticate_header_or_query校验 Bearer/查询 token（401 拒绝），再经_contained_sandbox_path做逐段字符白名单（[^/\\\x00-\x1f]{1,255}）、..拒绝、realpath包含性校验（403），并以O_NOFOLLOW+ 打开后fstat比对设备号/inode 的方式防符号链接逃逸。媒体类型白名单_SANDBOX_MEDIA_TYPES（inference.py）只允许 png/jpg/jpeg/gif/webp/bmp/avif 内联渲染，.svg刻意排除（模型自选文件名，内联 SVG 等同源脚本执行，故一律以 octet-stream 附件下发）；其余类型全部application/octet-stream+Content-Disposition: attachment，并带Cache-Control: private, no-store与nosniff。这与前端 sandbox-files.ts 的SANDBOX_INLINE_IMAGE_EXTS保持一致，构成前后端对称的"可内联格式"清单。

九、手动验证与常见问题排查

手动测试：运行--manual会打印类似http://127.0.0.1:<port>/inline-images的 URL，页面提供"Run simulations"按钮与两个演示下载按钮（"Show embedded download" 内嵌 PNG、"Show encoded download" 编码文件名），可在任意浏览器（含 Safari）中直接观察渲染、CSP 违规与下载命名。

常见失败信号与排查方向：

运行前提再核对：

1. macOS/Linux 或 Windows（命令差异见上文）；需已安装 Node.js（Vite 服务器）与 Python ≥ 3.x（编排器）；
2. 仓库根目录执行；--output不得指向仓库外；
3. 首次运行需playwright install下载浏览器二进制（约数百 MB，走PLAYWRIGHT_BROWSERS_PATH隔离）；
4. 对照模式需要可访问的 git 历史与完整 40 位 SHA。

十、总结

Unsloth Studio 的"内联图片模拟"夹具是一套高保真、可对照、跨浏览器的回归测试方案：它以 inline-image-server.mjs + inline-image-client.js 复刻生产 Markdown 渲染器与桌面 CSP，以 playwright_inline_images.py 完成浏览器矩阵编排，把"路径规范化、编码分隔符、作用域切换、流式链接、失败恢复、竞态、离屏懒加载、浏览器解码差异、下载命名与去重请求"这些边界场景固化成可断言的用例。它与生产管线（rehypeSandboxImages→markdownSandboxImageSrc→useSandboxImage→MarkdownImage）和后端沙箱文件路由（_SANDBOX_MEDIA_TYPES内联白名单 + 路径包含性校验 + Bearer 鉴权）形成完整的证据闭环。对任何改动 Markdown 渲染、沙箱文件服务或 CSP 的工程师而言，--baseline对照模式与 59 个浏览器用例就是最直接的回归防线。

• 人工智能
• 大模型
• 微调
• LoRA
• 模型优化
• 模型量化
• 强化学习