用途:指导安全地校验并发布 PostHog canvas 源码项目。画布源码存于 PostHog,按发布版本化;每次编辑基于特定版本,服务器拒绝覆盖更新的工作;每次发布会排队一次服务端构建,画布渲染最后一次成功构建。
源码项目:canvas-source-retrieve 返回 project(schemaVersion 1、files、entryHtml 为 index.html、dependencies 精确平台锁定版本、canvasSdkVersion、capabilities)与 current_version_id(编辑所基于的版本,首次发布为 null)。保持 index.html 与 dependencies 原样,可添加相对源文件与允许的资源;二进制资源以 base64 放入 assets;新增 npm 依赖或版本漂移会导致校验失败。
能力声明:宿主在运行时强制 project.capabilities,未声明的 ph 调用能构建但渲染时失败。需声明 insights、captureEvents、inlineQueries、agentRequests、connectors(每个 provider 的 {provider, tools},工具须 is_read_only: true,含 connectors 的画布不能声明共享状态)与 network.origins(精确 HTTPS 源,不含路径、凭据、查询、片段或通配符;主机须公开,localhost 等会被拒)。校验前需清点所有字面外部 URL,导航链接与 ph.openExternal 无需网络源。
校验:canvas-validate-create 无副作用,可反复调用。error 诊断阻止发布,常见有 import_not_allowed、forbidden_dynamic_import/require/inline_script、invalid_path、capability_missing_*、dependency_not_admitted/version_mismatch、platform_token_redeclared 等;warning 不阻止但需注意。
发布:默认立即上线。编辑用 canvas-edit-create(str_replace、write、delete、rename,一次调用包含全部操作,失败按索引返回);整项目用 canvas-publish-create,须传 expected_current_version_id。发布后轮询 canvas-builds-retrieve 直到 ready 或 failed;failed 需修复后重发。
草稿:仅当用户要求预览或审核时用 canvas-draft-create,等待构建后可用 canvas-source-retrieve 预览,经 canvas-promote-create 提升为线上版本。
冲突恢复:409 version_conflict 表示画布已前进,应重新读取源码、在新头上重做编辑并再次发布,不可无保护重试。版本历史每次发布追加完整源码并移动头指针,用户可回退。