visualize

在 Agent 对话中把模型输出的 HTML / Mermaid 渲染成可交互卡片的产品线。宿主无关：同一套 core 与浏览器 UI 套件，接不同 Agent。

卡片原位替换原来的源码块：客户端观察会话 DOM、按围栏认领 html / mermaid 代码块（v0.6 起免 marker，围栏闭合即出卡），其余内容（散文、推理、图片、其它代码块）仍交回宿主自己的渲染管线。

卡片 chrome（v0.4）：唯一一个悬浮工具栏钉在卡片右上角，hover / 键盘聚焦时浮现（源码态常显）。预览态 [↓][⧉][⛶ 放大] │ [‹› 查看源码]，源码态 [语言][⧉ 复制] │ [◉ 预览]，失败态 [错误码][⧉ 复制][↻ 重试]。源码态直接用宿主代码渲染器（shiki 高亮、<pre> 排版都是宿主的），宿主自带的 banner 折起来、语言名挪进胶囊——所以两种视图都只有一个工具栏。工具栏文案跟随会话语言。

放大查看（v0.7）落在宿主的右栏面板：点 ⛶ 打开右栏的一个标签页（标签名取自围栏语言，如 HTML），面板里是同一张卡片的预览 / 源码 / 复制 / 导出，分栏与浮动由宿主提供。宿主没有右栏面板时这个入口不出现——面板是宿主的面板，插件不自己造（早先塞进宿主表单对话框的做法实测被裁掉且无处可滚，见 CHANGELOG 0.7.0）。

按钮文案永远等于它真实会做的事，没有格式菜单：

导出目标由 action-target.ts 的两个纯函数裁定（primaryDownload / previewCopyStrategy），按钮从中取名，所以不会出现"写着下载图片、其实在下 HTML"，也不会出现点了必然失败的图片动作。

分辨率：产物先经 core 的 normalizeSvgSize 把尺寸钉在自己声明的 viewBox 上，再按 max(config.export.scale, devicePixelRatio) 栅格化——响应式 SVG（mermaid 默认 width="100%"、无 height）作为 <img> 只有 300px 固有宽，不这么做导出的图会明显发糊（实测：卡片屏上 1484 设备像素，旧实现导出 600px 宽）。

HTML 卡为什么只有 SVG：Chromium 禁止含 foreignObject 的 SVG 图片读回 canvas（实测见 core/spec/html-artifact.md），所以 HTML 快照既栅格化不成 PNG 也写不进剪贴板。这是浏览器规则，与沙箱无关。

实机截图：预览态（mermaid 卡） · 源码态（HTML 卡） · 放大后的右栏面板 · 面板里的源码态。

core/spec（语言中立契约：协议 / schema / 错误码 / golden fixtures）
   ↓
core/ts（纯逻辑：fence 扫描 / gate / 切分计划 / 视图状态机 / 沙箱文档 / 报文校验；零宿主、零 DOM）
   ↓
platforms/web（浏览器 UI 套件：React 组件 + DOM 胶水；宿主差异经 WebPlatformPorts 注入；零宿主 SDK）
   ↓
adapters/dsh（DSH 接线：config wire + 围栏认领通道 + 资产路由 + 端口实现；零业务逻辑）

依赖单向；core 与 platforms 都不认识任何宿主。

能力清单

index 与 plan-visual 是同一套 scan+gate 的两种产物；对同一 fence 产出的 IndexItem 逐字节一致。

支持矩阵

宿主

第一期只实现 dsh；octop / pi 仅为规划位，未实现。

渲染语言

新增一种渲染语言 = 动 core/spec + core/ts + platforms/web/src/registry.ts 一行，adapters/ 零改动。

安装（DSH）

三种方式，按场景选一种即可。推荐方式一：一条命令、零构建。

方式一：从 git 源安装（推荐）

dsh plugin --profile <profile> add \
  "@slothtron/visualize-dsh@git+https://github.com/Slothtron/visualize.git#master&path:adapters/dsh"

dsh --profile <profile> --dump-config | grep -A3 visualize   # 应出现 id: visualize 一行

要可复现就把 master 换成 commit（git rev-parse HEAD）或 tag；日常跟分支用 master 最省事。升级＝换 ref 重装 （dsh plugin --profile <profile> add "…@git+…#<新 ref>&path:adapters/dsh"），回滚＝装回旧 ref。

写法要点（都实测过）

前置条件与常见报错

为什么安装时不需要构建：lib/ 走提交入库策略（AGENTS §3 的二选一，见 ./.gitignore 的说明）， git 依赖里直接带着构建产物（core 与 platforms/web 已内联进 lib/client.js），所以不跑 prepare、 也不需要 pnpm 的构建授权。代价是产物新鲜度：pnpm run verify 里的 verify:lib 会断言"重新构建后产物 与提交内容一致"，改了源码必须把重新构建的 lib/ 一起提交。

方式二：从 tarball 安装

git clone https://github.com/Slothtron/visualize.git && cd visualize
pnpm install && pnpm run verify && pnpm run build
cd adapters/dsh && npm pack --pack-destination /tmp
dsh plugin --profile <profile> add "@slothtron/visualize-dsh@file:/tmp/slothtron-visualize-dsh-<版本>.tgz"

注意：同一路径的 tarball 重装时 pnpm 可能跳过解析（Lockfile is up to date, resolution step is skipped）， 导致装的还是旧内容——换一个新文件名再装即可。

方式三：从 registry 安装（发布后）

dsh plugin --profile <profile> add @slothtron/visualize-dsh

配置项与默认值

配置分片由 core 唯一定义（core/ts/src/config.ts）；适配器只做映射，不得新增第二份默认值。非法配置在加载期以 invalid_config（附字段路径）失败。

快速验证

pnpm install
pnpm run verify        # build + typecheck + test + verify-contract + dependency-lint + pack-check + verify:lib

pnpm run verify 是单一入口，等价的 POSIX 包装是 ci/verify.sh。分步：

实机验收（需先起一个装好插件的 dsh 服务；脚本不依赖任何 npm 安装）：

node scripts/acceptance-card.mjs "http://127.0.0.1:18765/?token=<token>" /tmp "<会话标题>" [截图前缀]
#   指向含卡片的会话：驱动工具栏、解码导出的图、逐条断言并在失败时以非零码退出

node scripts/probe-export.mjs "http://127.0.0.1:18765/?token=<token>"   # 导出分辨率数值诊断（不出图不断言）
node scripts/probe-html-artifact.mjs "…"                                 # foreignObject 快照为何只能出 SVG

端到端：装插件 → 让模型输出一个 ```html 或 ```mermaid 围栏（免 marker）→ 该围栏原位变成卡片（原文不再以代码块出现，但可在卡片的源码视图里带高亮查看/复制/导出）→ 工具栏切换视图 → 导出。

golden fixture 维护

core/spec/fixtures/sandbox-doc/*.expected.html 是安全契约的字节级真相。修改沙箱文档后：

node scripts/verify-contract.mjs --update   # 重新钉 golden

该命令会打印醒目警告；必须逐字节审阅 diff 后再提交，不得用它掩盖非预期的漂移。

CI 接入（托管方无关）

唯一入口是 ci/verify.sh；它不含任何托管方专有内容，换托管方时只需让流水线调用它。

sh ci/verify.sh

可选的最新宿主探针（无 matrix 支持时用）：

VERIFY_LATEST_HARNESS=1 pnpm run verify:latest-harness

安全模型

1. 模型输出只进入 opaque-origin 沙箱 iframe（sandbox="allow-scripts"，禁止 allow-same-origin），绝不进宿主 React 树、绝不用 dangerouslySetInnerHTML。
2. 默认断网：CSP default-src 'none'；allow="assets" 只放宽 img-src。CSP 串、sandbox 属性矩阵、bootstrap 文档是 core 的 golden fixture，适配器无权放宽。
3. 三重校验：transport 检查 event.source === iframe.contentWindow，core 校验报文形状与在途 id，源取回校验 ref 命中当前索引。
4. 限额全部走归一化配置，非法即启动失败。
5. 零凭据、零落盘（visualize_present 例外，且仅在显式开启时写文件）；fixtures 全假值。

已知限制与待确认项

M0 运行时疑点已全部实机闭环（dsh 0.1.5-rc.2 / Node 26）：

1. 带 wire 的第三方 projection key 是否真出现在 useProjection props 中 ✅ 成立（无 wire 则恒 undefined）。
2. assistant/message 事件上的 seq / 载荷字段 ✅ event.seq + event.data.message.content[]。
3. DSH 如何把插件 config 同时交给 host 与 client 两半 ✅ wire 送归一化 config（key visualize）。
4. client 半区的 tools 服务注册形态 ✅ 缺失时 visualize_present 显式降级并告警。

剩余边界：

• 宿主按视口渐进渲染历史消息：不在视口内的围栏尚未进 DOM，滚动到该处时才出卡（真实使用自然发生）。
• octop / openclaw / hermes 的等价扩展点未评估；若其 UI 读不到消息正文，需退回"索引 + SourcePort"路径（buildIndex 与 SourcePort 已为此保留）。
• 源码态折起宿主 banner 依赖宿主声明的稳定钩子（data-code-block-banner / data-code-block-content）；宿主改名只会让 banner 重新出现，不影响功能。
• 卡片样式表由适配器注入；若某宿主 CSP 禁掉注入的 <style>，退化为"胶囊常显 + banner 可见 + 源码顶部无内边距"，控件仍可用（结构在 inline style 里）。
• 预览态"复制图片"/"下载图片"仅对可栅格化的渲染器生效（当前是 mermaid）；html 卡显示"下载 SVG"/"复制源码"——按钮文案如实反映它真正会做的事，原因见 core/spec/html-artifact.md。
• 本机 WSL2 下 bsk 的 Agent Window 标签页常处于 occluded 状态，Chrome 不跑渲染步（IntersectionObserver 不触发 → 宿主代码块也不高亮）。实机验收需用能真实渲染的环境（见适配器 README 的验收方法说明）。

实测细节、降级清单与 9 条集成缺陷记录见 adapters/dsh/README.md。

目录结构

visualize/
├── core/spec/          # 语言中立契约 + golden fixtures
├── core/ts/            # @slothtron/visualize-core
├── platforms/web/      # @slothtron/visualize-web
├── adapters/dsh/       # @slothtron/visualize-dsh
├── scripts/            # verify-contract / verify-lib-fresh / dependency-lint / pack-check
│                       #   / acceptance-card / probe-export / probe-html-artifact
├── ci/verify.sh        # 单一 verify 入口（POSIX）
├── .github/workflows/  # verify 门禁（GitHub 托管时生效；其它托管方调 ci/verify.sh）
├── docs/acceptance/    # 实机验收截图（**不放设计文档**）
└── tests/contract/     # 契约测试说明（实现即 scripts/verify-contract.mjs）

各包 lib/ 属于提交入库的构建产物（策略与理由见 ./.gitignore）；sourcemap 不入库。

文档

设计方案文档刻意与代码仓库分离：仓库里禁止出现设计文档（.gitignore 也对这几个路径做了兜底）。要改设计请改仓外那几份，再在 CHANGELOG.md 与本 README 里引用结论。

License

MIT