用途:在本地构建并预览 prefab 的 renderer(主题、组件、样式)与 playground 改动。
主要能力:修改 renderer 源码、Python 源码或 playground 代码后,用统一命令 uv run prefab dev build-docs 编排完整流水线,并带智能缓存,只重建变化部分。流水线包含:TS 源码变化时经 npm run build:renderer 构建面向 CDN 的代码分割 ESM bundle;将 src/prefab_ui/**/*.py 序列化为 renderer/src/playground/bundle.json 供 Pyodide 使用;playground 源码变化时以 VITE_LOCAL_PLAYGROUND=1 运行 Vite 内联 Python bundle;最后把产物拷贝到 docs/ 供 playground 与 mintlify dev 使用。注意 build-docs 构建的是 CDN renderer;打包的单文件 renderer(离线回退)由 prefab dev build-renderers 单独构建。
使用方式:构建后可用 uv run prefab playground 启动 playground(默认端口 5174,从 docs/ 提供服务),或用 mintlify dev --dir docs 启动完整文档站点。不要直接运行裸 npm 构建命令(如 npm run build:playground、npm run build:renderer),否则会跳过关键步骤。
常见问题:出现 “attempted to install wheel before downloading it” 说明 playground 未以 VITE_LOCAL_PLAYGROUND=1 构建,应改用完整流水线;playground 显示过期 Python 代码说明 bundle.json 过期,完整流水线会重新生成;部署预览中看不到 renderer 改动,是因为部署预览从 CDN(@latest)加载分块而非当前分支,渲染器改动需本地测试。完整构建与发布细节见 dev-docs/build-pipeline.md。