用户 Widget

用户 Widget 是 VizChat 的长尾 widget 扩展机制——Agent 在对话中生成组件实例，存入数据库作为一条 username/slug@version 记录，其他用户可在素材市场中浏览，并通过对话放进自己的画布，无需等版本发布。

Widget 是什么

• 一份数据契约（快照结构、默认值与操作）加一个视图：渲染在画布里的 React 组件（inline mount，默认），或在独立 iframe 里直接操作 DOM 的代码（nested mount）。两者都由后端编译成 bundle
• 由 Agent 按对话需求生成，也可由开发者手写后发布
• 以 username/slug@version 三元组唯一标识
• 有标签（tags）、简介、缩略图、收藏数与热度分等社区元数据

用户 Widget vs 内置 widget

如何使用

1. 在素材市场浏览

点击顶栏的地球图标进入 /marketplace——它是公开页面，未登录也能浏览。可按热门 / 正在流行 / 最新排序，也可关键词搜索。详情页会跑一个实时 demo，还能在一块试用画布上直接上手（选中、改尺寸、改数据和配置——改动只在本页有效，重置或刷新即回到初始状态）、展示文档，登录后可收藏；已开源的 widget 还能下载源码包、或一键导入成你自己的草稿（见下）。

2. 通过对话把 widget 放进画布

在聊天输入框里输入 @widget:，会弹出可选列表（素材市场 / 收藏 / 最近使用）；也可以手写引用 @widget:<作者>/<slug>（可加版本 @widget:<作者>/<slug>@<版本>）。Agent 随后会把该 widget 放到画布上。直接用自然语言让 Agent 加也可以。

3. 让 Agent 直接生成

在聊天里说：

"帮我做一个掷骰子 widget" "做一个倒计时器 widget，10 分钟"

Agent 会直接把该 widget 建到画布上——不进入素材市场，也可以事后手动发布。

4. 我的 Widget

登录后点击顶栏的 VizChat 标志进入我的主页 /me，其中的创作与收藏两个区块分别列出你发布过的和收藏的 Widget；各自还有独立页面 /me/creations 与 /me/favorites。

收藏的内容若被原作者删除，卡片会标注已被作者删除并停止跳转；被下架的标注已下架（下架可被恢复，所以它还会留着）。两者都能用卡片右上角的 ✕ 单独移除；收藏页顶部还有一键清理，只清掉已被删除的那些。

基于官方 widget 二次创作

官方 widget 大多以 Apache-2.0 开源（Math Coordinate 除外）。源码是否公开按版本定：最新版本已开源的 widget，详情页（标题旁带绿色「已开源」徽章）有两个出口：

下载源码 —— 得到一个 <slug>-source.zip，解压后是一份完整的 widget 包（package.json、src/、测试、LICENSE、NOTICE）。pnpm install 之后就能用 CLI 在本地开发。

导入到我的组件 —— 服务端把源码复制成你名下的一份草稿并打开 widget 编辑器，改完直接发布。包名会自动改成 @<你的用户名>/<slug>。

两条路拿到的是同一份源码，区别只在你想在哪儿改：下载给本地工具链，导入给浏览器里的编辑器。

导入出来的是独立副本，与原 widget 再无关联——改它不会影响官方那份，官方更新也不会回流到你这份。若你名下已有同名组件，导入会被拒绝而不是覆盖；在我的创作里改名或删除后重试即可。

许可证

Apache-2.0 允许你自由使用、修改、再发布（含商用），条件是保留包内的 LICENSE 与 NOTICE 两份文件。它们随下载与导入一起带走，请不要删掉。

rich-text 的 NOTICE 里另有一份 MIT 声明——它内嵌了 Milkdown 的样式代码，那份声明同样需要保留。

Apache-2.0 覆盖的是这份 widget 的源码。它依赖的 @vizchat/* 包（SDK / UI / 构建工具）另有自己的许可证：用于开发、构建、分发甚至售卖 widget 都是免费的，但不允许再分发这些包本身。详见包内的 LICENSE。

回到组件草稿之前的版本

组件编辑器顶栏的「历史」列出这个组件草稿的快照，新的在前。快照是自动记下的：

• AI 修改前：Agent 每一轮动手改组件之前记一份，旁边附着 Agent 那一轮最后说的话；
• 手动编辑前：你在编辑器里保存（或从本地文件夹同步上来）之前记一份，半分钟内的连续保存算一次；
• 已发布：每发布一个版本记一份，带版本号；
• 回退前：每次回退之前记一份。

选中一个快照，能看到回退会改动哪些文件（恢复、删除或改回），改动过的文本文件可以展开看逐行差异。点「回退到这个版本」确认后，草稿就回到那一刻的样子，预览随之重新编译；回退之前的草稿已经存成「回退前」那一份，成功提示上的「撤销」或历史里的那一格都能把它找回来。编辑器里还没保存的修改会作废。

你也可以直接对 Agent 说「改坏了，回到上一版」——它看的是同一份历史。每个组件保留最近 50 份快照，发布出的版本全部保留。有待合并的本地修改时回退不了，先按下一节处理。

在本地文件夹里改自己的组件

在桌面客户端里，我的创作的组件行上有「同步到本地文件夹」：组件的草稿会出现在你选的文件夹里，用任何编辑器改动都会同步回来；已经连接的组件显示「在文件夹中显示」。网页版没有这个入口。

你在本地改的同时，如果 Agent 或网页里的组件编辑器也改了这个组件，哪一边都不会覆盖另一边：云端的版本留在草稿里，你在本地的修改暂存成一组待合并的修改，本地文件夹随之换成云端的版本。本地新加的文件、只在本地改过的二进制文件（图片、字体等）不需要合并，会直接收进草稿。

有待合并的修改时，「我的创作」里该组件的那一行和组件编辑器上方都会提示，并给出两个出口：

• 让 Agent 合并：打开组件编辑器，并替你在对话里发出合并请求。Agent 把两边的改动合到一起、编译通过之后才算合并完成。之后你让 Agent 改这个组件时，它也会先合并、再做你要的事。
• 放弃这些修改：先列出涉及的文件，确认后这些本地修改不再合并，组件保持云端现在的内容。

有待合并的修改时组件发布不了：发布对话框会说明原因并给出同样两个出口，处理完再发布。

发布自己的 Widget

Widget 的发布流程与自定义 widget 开发共享一套工作流，详见 自定义 widget 开发指南。

发布会检查即将发出的这一版：默认画面与 demo 的每一页都按两种语言渲染一遍。渲染出错、页面一直加载不完、操作执行失败、界面上露出未翻译的键、越界访问（伸进宿主页面，或请求没有声明的来源）会拦住上架到市场的发布，并逐条列出问题。已从市场收回分发的组件同样检查，但不会被拦。较软的问题（对比度、性能、无障碍）从不拦住发布，只随结果列出。

在自己的 board 里试用还没发布的组件

还没发布的组件也可以放进自己的 storyboard 和 dashboard——让 Agent 加进去即可。只有你自己看得到，显示的是这个组件最近一次预览成功的样子；如果还没预览过，board 上会显示占位和「打开预览」。要发布或导出这个 board，先发布那个组件：board 会自动改用发布出来的版本。

发布之后：运行时依赖与维护

组件构建时用的是平台运行时（SDK、共享 UI 与 d3 / echarts / three 这类依赖）当时的最新版本，构建出来就钉住这组版本，所以别人的 board 不会因为平台升级而突然变样。旧的运行时版本过一段时间会进入弃用期（90 天），期满冻结：冻结的版本照常加载，只是新的构建不再用它。

在组件详情页上（只有你自己看得到），或在我的创作里点「运行时与维护」，可以看到每个已发布版本的情况：

• 弃用提示：如「依赖的 @vizchat/widget-sdk 0.3.2 将于某日冻结」。点「重新构建」用最新的运行时重新构建这一版——源码和版本号都不变，用到它的 board 不受影响。构建要几分钟，结果会发到通知里。
• 切回旧构建：重新构建之后 7 天内，可以切回之前的构建。
• 撤回：平台发现某个运行时版本有问题时会撤回它；用它构建的组件照常加载，建议重新构建换到修复后的版本。
• 平台维护：进入弃用期时平台会先试着用最新运行时构建你的组件，通过就直接换上并通知你（可以切回）；没通过会在「平台维护记录」里列出原因。你可以自己修，也可以点「让 agent 修」——这一次的费用由你承担。依赖冻结时你仍没处理的，由平台接着维护。
• 已内联旧依赖：平台维护的一种方式——把旧的运行时直接打进组件包，组件照常运行，但体积更大。随时可以重新构建换回最新的运行时。

不想再维护某个组件时，可以在同一处把它转交给平台。转交不可撤销：之后由 VizChat 维护，你不能再发布新版本，页面上不再显示你的名字、改为「由 VizChat 维护」；但页面地址和 board 里对它的引用仍含你的用户名。

Tier 限制

Widget 开发能力各档位完全一致，详见 计费规则与档位限制。BYOK 可大幅降低 Widget 调试成本——详见 定价页面。

Next step

• 自定义 widget 开发 — 开发者视角的 widget 开发
• 自定义 widget 指南