用命令行发布 widget

如果你在本地开发 widget——用自己的编辑器、自己的工具链——vizchat-widget CLI 能把它从你机器上的一个文件夹变成 Marketplace 上的发布条目。本指南覆盖你需要的四个命令：auth login、dev、tts、publish。

前提：装好 Node.js 和一个包管理器。就这些——项目由下一步创建。

创建项目

npm create vizchat-widget my-widget

它会问你挂载形态（inline = host React 树里的一个组件，nested = iframe 里自持的一个页面），产出一个完整的包——schema、视图、演示 storyboard、双语文案、测试——并按你用的包管理器打印出对应的安装命令。加 --yes 直接取默认值，或用 --mount inline --scope <你的用户名> 跳过提问。

pnpm create vizchat-widget 与 npx create-vizchat-widget@latest 是同一件事。

已经有 widget 包了？那只需确认 devDependencies 里含 @vizchat/widget-scripts，且 name 形如 @<你的用户名>/<widget-slug>。

cd my-widget && pnpm install

CLI 在项目内以 pnpm exec vizchat-widget 调用。

登录

pnpm exec vizchat-widget auth login

CLI 会打印一个短码和一条浏览器链接。打开链接、核对短码一致后批准——终端会自动拿到凭证。token 存放在 ~/.config/vizchat/credentials.json，按签发它的服务器隔离；只要 90 天内使用过一次就持续有效。

auth whoami 查看当前登录身份；auth logout 在服务端撤销 token 并删除本地凭证。你也可以随时在 Web 应用的设置页撤销 CLI token。

本地预览

pnpm exec vizchat-widget dev

它会启动本地预览服务并监听源码。演示标签播放你的 demo.stb storyboard；交互标签把 widget 挂进一个可点击、可编辑的实时 dashboard。源码改动会自动重编译并刷新。

在 VS Code 里

如果你用 VS Code，装上 VizChat Widget Preview 扩展（vizchat.vizchat-vscode-extension）就不必再切到浏览器：打开 widget 包内的任意文件，从命令面板执行 VizChat: 打开 Widget 预览，预览会在编辑器旁边的面板里打开。扩展替你启动同一个 dev 服务，并在你关闭面板时把它停掉。

它是一条捷径，不是另一套东西——面板里嵌的就是 dev 提供的那个页面，用浏览器打开同一地址看到的完全一样。这里没有任何只有 VS Code 才有的能力。

合成讲稿语音

demo storyboard 里 markedText 的讲稿可以合成为语音，在本地预览中播放，并随发布一起交付：

pnpm exec vizchat-widget tts

合成消耗你账户的积分，且只合成文本有变化的页——内容没变时重跑不产生费用。音频落在 public/demo-tts/（已被 git 忽略；它随包上传交付，不进版本库）。当有页面缺音频时，预览页也会显示一键合成提示条。

发布

pnpm exec vizchat-widget publish

CLI 先在本地构建（明显的错误不出你的机器），然后上传包，由服务端编译、校验并发布。服务端是权威：它从源码重新构建，并把你的 demo 语音烘焙进发布版本——本地已合成的音频直接复用，不重复计费。如果你加了 --open-source，它还会在公开源码前扫描一遍疑似密钥（见下文「密钥扫描」）。

发布即公开

发布出去的组件立刻就在 Marketplace 上可见，没有「先发布、再上架」两步。你唯一要另外决定的是要不要连源码一起公开：

pnpm exec vizchat-widget publish                # 发布，源码不公开
pnpm exec vizchat-widget publish --open-source  # 发布，并公开源码

--open-source 与「发布」是两件正交的事：它管的是别人能不能读你的源码，不影响组件本身可不可见。

公开源码不可撤销——已经被看到的东西收不回来。所以先干跑一次看看会发生什么：

pnpm exec vizchat-widget publish --dry-run

干跑会在本地构建、列出将要上传的文件，然后停下——服务端不会收到任何写入。

想让组件不再出现在 Marketplace，用网页端的「下架」；那是可逆的，与源码是否公开无关。

密钥扫描

加了 --open-source 时，服务端会在公开源码前扫一遍疑似密钥。如果命中的是有意为之的内容 （例如演示用的 API key 占位符），确认无误后带 --acknowledge-secrets 重跑：

pnpm exec vizchat-widget publish --open-source --acknowledge-secrets

命中且未确认时，版本仍然已经发布出去了，只有「公开源码」这一步停下等你确认——不必也不要再发一个版本。

在脚本与 CI 里使用

每个命令的 stdout 末行恒为一行 JSON，进度与提示走 stderr，因此可以直接 | tail -1 | jq。 退出码是细分的，可据此决定下一步：

会扣费或有不可逆副作用的命令在非交互环境下不会默认放行：tts 需要显式 --yes（或用 --dry-run 只看报价）。

疑难排查

• 刚登录完就提示「未登录」 —— 凭证按服务器隔离。如果你是通过 VIZCHAT_API_URL 登录到非默认服务器的，之后每个命令（包括 dev）都要带同一个环境变量。
• 预览提示缺音频但你已经合成过 —— public/ 不在 watch 面里，音频索引只在重编译时刷新。改一下源码文件或重启 dev 触发一轮即可。
• publish 拒绝作者名 —— package.json name 里的 scope 必须与你的 VizChat 用户名完全一致。