后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载导读specs/ui-proof.md定义了 ClawHub 的远程proof:ui验证运行时——一种从源码和全新本地数据出发、不触碰任何共享或生产后端的全栈 UI 证明机制。本文结合 scripts/ui-proof.mjs、scripts/ui-proof-backend.mjs、scripts/ui-proof-runtime.mjs 及对应测试完整还原其两种模式、两种 runner、隔离与信任模型、后端固定版本 pin、进程生命周期契约与验证边界让你理解这套体系为何能同时保证结果可信与环境干净。specs/目录按 specs/README.md 的约定存放维护者内部记录不默认发布到公开文档页specs/ui-proof.md正是其中一份维护者验证与 CI 策略记录。与之对应的可执行入口在仓库根的 package.json 中注册为两个 npm scriptproof:publish: node scripts/ui-proof-publish.mjs, proof:ui: node scripts/ui-proof.mjs,一、UI Proof 是什么从源码证明全栈proof:ui的核心定位是远程 lane 从各自源码出发、配合全新本地数据证明完整技术栈Convex 后端 前端构建 Playwright 浏览器场景真实可用。它刻意设计为没有共享后端模式、也没有生产后端模式——每次验证都从零搭建避免任何外部状态污染验证结论。一次验证按lane车道组织每个 lane 是一套独立的端口、输出目录和运行环境laneconvexCloud 端口convexSite 端口frontend 端口默认引用baseline441745174317origin/maincandidate441845184318worktree端口常量定义在 scripts/ui-proof.mjs 的DEFAULT_PORTS中。所有 URL 均为127.0.0.1回环地址且必须保证三个端口互不相同见 scripts/ui-proof-backend.mjs 中runProofBackend的端口校验。1.1 两种模式--mode before-after与--mode featurebefore-after默认同时运行 baseline 与 candidate 两个 lane逐步骤对比截图用于验证 PR 改动没有破坏既有功能feature只运行 candidate 一个 lane用于验证新功能本身报告中会明确标注 Baseline: not run for feature proof。模式由parseProofUiArgs校验scripts/ui-proof.mjs非法值直接抛错。测试 scripts/ui-proof.test.mjs 还专门验证了--mode smoke会被拒绝——smoke 是独立脚本不是proof:ui的模式。1.2 两种 runner--runner crabbox与--runner localcrabbox默认通过 Crabbox 运行器引导远端 lane——先warmup申请带桌面与浏览器的租约再run注入远程脚本结束后inspectrsync拉回产物最后stop释放租约。执行细节见 scripts/ui-proof.mjslocal只附着attach到维护者自行启动的回环实例不申请远端资源也绝不自己启动后端或预览服务。它要求传入--baseline-url/--candidate-url且二者必须解析到localhost、127.0.0.1或[::1]assertLocalProofUrl见 scripts/ui-proof.mjs。local模式仍然保证 baseline/candidate 的 URL 与产物目录彼此分离只是把启动服务的责任留在维护者手中。1.3 输出目录约定默认输出目录为.artifacts/clawhub-ui-proof/UTC 时间戳时间戳由timestamp()把冒号和点替换为连字符生成见 scripts/ui-proof.mjs内部再按baseline/、candidate/分 lane 存放远程模式下还会在远端写出remote-timestamp/lane目录并整体 rsync 回本地。测试 scripts/ui-proof.test.mjs 验证了该目录规划在两种模式下都稳定可预测。二、proof:ui命令行参数全参考以下参数全部来自parseProofUiArgsscripts/ui-proof.mjs的解析逻辑均为当前仓库实际支持参数默认值说明--scenario path必填临时 Playwright 场景文件路径缺省会直接抛错--mode before-after\|featurebefore-after验证模式--runner crabbox\|localcrabbox运行器选择--baseline reforigin/mainbaseline 引用--candidate refworktreecandidate 引用--baseline-url url无仅local模式且before-after时必填必须回环地址--candidate-url url无仅local模式必填必须回环地址--provider namehetznerCrabbox 云提供商--class/--machine-classstandard机器类别传给 Crabboxwarmup--crabbox-bin path仓库内 wrapper直接指定 Crabbox 可执行文件缺省走scripts/crabbox-wrapper.mjs--lease-id id无复用已有租约而不新申请warmupLease中created: false--idle-timeout60m租约空闲超时--ttl120m租约 TTL--dev-auth关显式开启后端与前端 dev auth--env KEYVALUE无透传特性开关等自定义环境变量有保留字黑名单见下文--seed-command cmd无用一次性自托管凭据执行种子脚本--skip-install关跳过依赖重装浏览器二进制仍会装进全新私有缓存--video-duration sec60ffmpeg 录屏时长--output-dir path见上覆盖产物根目录--dry-run关只写规划报告不申请租约、不运行任何运行时--keep-lease关验证结束后保留租约否则finally中stopLease一个典型的远程前后对比验证bun run proof:ui \ --mode before-after \ --scenario .artifacts/proof-scenarios/demo.pw.ts \ --provider hetzner \ --class standard \ --ttl 120m一个附着本机回环实例的 feature 验证bun run proof:ui \ --runner local \ --mode feature \ --candidate-url http://127.0.0.1:4318 \ --scenario .artifacts/proof-scenarios/demo.pw.ts2.1--env的保留字校验--env不是随便透传的assertProofEnvironmentscripts/ui-proof-backend.mjs会拒绝任何涉及连接、凭据、进程与私有状态的环境变量例如CONVEX_DEPLOYMENT、CONVEX_SELF_HOSTED_ADMIN_KEY、VITE_CONVEX_URL、HOME、XDG_CACHE_HOME、PATH、NODE_OPTIONS、BASH_ENV、LD_PRELOAD、HTTPS_PROXY、DEV_AUTH_ENABLED、VITE_ENABLE_DEV_AUTH等同时也拒绝TOKEN/SECRET/API_KEY等敏感模式与*_PATH/*_HOME类后缀。合法的典型用法是透传特性开关如--env FEATURE_FLAG1。测试 scripts/ui-proof.test.mjs 与 scripts/ui-proof-backend.test.mjs 均覆盖了这些拒绝路径其中--runner local附着模式不经过该校验URL 由维护者自担风险。三、隔离与信任模型证明必须干净proof:ui对干净的要求贯穿整个生命周期核心原则是任何云认证或操作者状态operator state都不得被读取、复制或 source 进验证环境。3.1 拒绝.convex与.env系列文件远程 wrapper 与 app 根目录必须按名称拒绝.convex、.env以及除example/sample/template之外的.env.*正则/^\.env\.(?!example$|sample$|template$)/u实现见assertCleanProofSourcescripts/ui-proof-backend.mjs。关键语义是只检查名字、不读取、不删除——本地调用者可能持有被.gitignore忽略的.env.local/.convex同步源码时绝不能把这些文件水合hydrate进验证环境。检查时点有三个初始、源码 push 之后、preparation/seed 之后checkSources被反复调用见 scripts/ui-proof-backend.mjs。测试 scripts/ui-proof-backend.test.mjs 用指向不可读路径的 symlink 验证检测到preparation/push/seed任一阶段产生的.env.local都会中止验证且 symlink 原样保留、绝不被触碰。3.2 lane 独占的私有状态每个 lane 拥有位于源码与产物目录之外的全新私有状态目录/tmp/clawhub-ui-proof-*权限 0700且通过 realpath 校验确保它不在 appRoot/wrapperRoot/outputDir 之内scripts/ui-proof-backend.mjs。目录内包含HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_DATA_HOME、TMPDIR、BUN_INSTALL数据库文件db.sqlite3与storage/自托管 CLI 选择文件cli.env仅含CONVEX_SELF_HOSTED_URL与CONVEX_SELF_HOSTED_ADMIN_KEY权限 0600子进程环境只继承PATH/DISPLAY加上 lane 显式设置项isolatedProofEnvironment见 scripts/ui-proof-backend.mjs。私有 HOME 还顺带防止了 CLI 回退到全局认证查找。实例名与实例密钥每次全新生成randomBytesidentity 绝不跨 lane 复用。3.3 安装钩子与 Bun 语义安装钩子在凭据存在之前运行。依赖安装必须使用bun install --frozen-lockfile而不是bun --no-env-file install——后者是非法组合--no-env-file是运行时参数不能作为install子命令前缀。但运行时调用build、seed、UI proof一律保留--no-env-file防止从任何.env文件读取变量。Bun/unzip 的供应provisioning是有界且非交互的PROVISION_PROOF_TOOLS脚本用timeout --signalTERM --kill-after5s 120s apt-get或 curl 安装 unzip/bunscripts/ui-proof-backend.mjs。--skip-install只跳过依赖重装浏览器二进制仍然会装进全新私有缓存XDG_CACHE_HOME绝不会从操作者的浏览器配置或缓存加载。对应测试见 scripts/ui-proof-backend.test.mjs 的 installs browsers in the fresh private cache 用例。3.4 信任边界声明文档明确写道源码与场景是可执行输入helper 本身不是沙箱它保留 Crabbox 既有的信任边界。也就是说隔离模型保证的是不泄露操作者状态而不是把任意第三方源码关进沙箱——这两件事被刻意区分。四、后端与源码就绪固定版本 pin 与身份校验4.1 CLI 与后端的固定 pin验证对工具版本采用**钉死pin**策略绝不解析 latest绝不执行未验证的归档Convex CLI 版本精确等于 1.44.0CONVEX_CLI_VERSION见 scripts/ui-proof-backend.mjs且必须直调其bin/main.js禁止使用复制的.binlauncher启动前读取package.json校验版本后端 release pin 为precompiled-2026-08-25-7cce8fbhelper 内维护四平台的 SHA-256 摘要表BACKENDS见 scripts/ui-proof-backend.mjs平台目标 tripleSHA-256节选darwin-arm64aarch64-apple-darwin98831b0f…7317bdarwin-x64x86_64-apple-darwind142472d…bea29linux-arm64aarch64-unknown-linux-gnua0601ec5…7e2flinux-x64x86_64-unknown-linux-gnu47025026…4eff9f下载或本地--backend-archive提供的 ZIP 必须通过 SHA-256 校验downloadProofBackend见 scripts/ui-proof-backend.mjs不支持的平台直接抛错。测试 scripts/ui-proof-backend.test.mjs 覆盖了版本不符与归档摘要不符两条拒绝路径。4.2 回环绑定与端口独占后端以--interface 127.0.0.1启动API 与 site 两个监听地址都绑定回环文档明确建议更换 pin 时复查上游config.rsinterface 用于 API 与 site 绑定地址与main.rs用两个地址启动监听。实际 argv 构造见backendArgumentsscripts/ui-proof-backend.mjs固定端口、--convex-origin/--convex-site回环 URL、--instance-name、--instance-secret该 pin 的后端只接受 argv 传入密钥、--disable-beacon关闭 beacon 遥测与--local-storage。CLI 侧用CI1关闭 Sentry且不启动 dashboard。三个固定端口必须检查两次preparation 之前、后端启动之前assertPortsFree见 scripts/ui-proof-backend.mjs。任何已占用端口都直接失败——绝不收养其他服务。4.3 身份校验与两段式就绪查询后端就绪后先要求GET /instance_name精确返回本次全新的实例名waitForProofEndpoint见 scripts/ui-proof-backend.mjs防止附着到别的实例。随后执行源码 pushnode verified-cli run --push --typecheck disable --codegen disable appMeta:getDeploymentInfo {} --env-file private-file注意--env-file指向权限 0600 的私有选择文件且使用--typecheck disable --codegen disable绕过不必要的本地检查。push 之后重新校验身份与源码洁净度再运行独立的run --no-push就绪查询之后才进入 seed/build/browser 阶段。测试 scripts/ui-proof-backend.test.mjs 精确断言了这一调用序列与参数。4.4 为什么禁用dev --local/dev --once文档特别警告CLI 1.44.0 的dev配置路径即使在显式选择自托管后仍会写.env.local——这正是验证环境最忌讳的水合污染。run --push绕开该路径因此是唯一被允许的源码推入方式。选择文件只含自托管 URL 与 admin keyapp 侧使用的local:fresh-instance标记与 CLI 选择文件严格分离。4.5--dev-auth与凭据分级--dev-auth通过convex env set显式设置后端DEV_AUTH_ENABLED与DEV_AUTH_CONVEX_DEPLOYMENT并给前端注入VITE_ENABLE_DEV_AUTH1见 scripts/ui-proof-backend.mjs 的appEnv构造。凭据按阶段分级seed只拿到一次性自托管凭据与直连 CLI/私有文件路径build/browser不拿任何 admin key。后端实例密钥必须出现在 argv 中因此进程参数永不打日志keygen输出标记为私有privateOutput: true其他子进程输出在记录前做有界截断保留最近 128 KiB与脱敏——包括被切分/截断的密钥片段redactProofText见 scripts/ui-proof-backend.mjs。对应测试验证了日志不包含密钥任何片段即使日志写入本身失败也要继续尝试移除私有状态。五、生命周期与完成契约清理必须被证明5.1 单控制器与进程组语义一个控制器统一处理后端/preview 退出、截止时间默认 20 分钟、SIGINT 与 SIGTERMscripts/ui-proof-backend.mjs。清理针对进程组而非仅 leader子进程以detached: true启动。清理序列为先发SIGTERMffmpeg 例外用SIGINT有界等待仍存活则升级SIGKILL。文档记录了三个精细的边界条件macOS 的 EPERMleader 已退出但尚未 close 时对进程组发信号可能报 EPERM因此必须先做有界 close/reap 等待再探测进程组关闭的管道 ≠ 后代已消失stdio 关闭不代表进程树清空一旦收到 ESRCH绝不再对那个数字组 ID 发信号组 ID 可能被复用权限拒绝只失败该记录某进程组拒绝信号EPERM时该记录标记失败但其他组仍继续尝试清理KILL 之后组可能短暂存在被 KILL 的后代以 zombie 形态留在组内直到 init 回收因此组已拆除的证明必须有界轮询不能只探测一次。LaneProcesses.signal/releasescripts/ui-proof-backend.mjs实现了上述策略测试 scripts/ui-proof-backend.test.mjs 用真实进程树验证了[0, SIGTERM, 0, SIGKILL]的完整信号序列与 zombie 轮询。5.2 主失败与清理错误共存主失败信息必须与清理错误一起保留errors数组聚合即便关闭/写日志失败也要继续写脱敏诊断、尝试移除私有状态。bootstrap-summary.json只在整个清理完成之后才写——它本身就是清理已认证的证书。5.3 双清单判定远程成功远程 lane 的成功需要两份清单同时通过proof-steps.jsonUI 侧由ui-proof-runtime.mjs的runUiProofScenario在finally中写入见 scripts/ui-proof-runtime.mjsbootstrap-summary.json后端侧清理后写入见 scripts/ui-proof-backend.mjs。已完成的通过清单可以恢复传输错误如 rsync/SSH 中途失败——但截图不能掩盖缺失或失败的 bootstrap 完成。这一判定逻辑在runLanescripts/ui-proof.mjs中实现测试 scripts/ui-proof.test.mjs 用pass/fail/missing三态 bootstrap 验证了该恢复规则。local附着模式只依赖 UI 清单。SIGKILL 或宿主机丢失仍需要外层容器兜底。六、验证与限制聚焦测试与可选冒烟6.1 聚焦测试真实 owner 窄 I/O 缝proof:ui的单元测试刻意避开 dotenv 加载与复制 launcher直接用真实 owner 配合窄 I/O 注入spawnImpl/kill/connect/fetchImpl等和真实的进程树清理。文档给出的聚焦运行方式node --input-typemodule -e import {startVitest} from vitest/node; const ctxawait startVitest(test,[scripts/ui-proof.test.mjs,scripts/ui-proof-backend.test.mjs,scripts/ui-proof-runtime.test.mjs,scripts/ui-proof-publish.test.mjs],{run:true},{envDir:false});await ctx.close();envDir:false确保测试进程绝不读取.env目录。四份测试文件分别覆盖参数解析与计划构建、后端启动与清理的密集边界、场景运行时截图/清单、产物发布与评论渲染。6.2 可选冒烟会启动真实回环服务器scripts/ui-proof-backend-smoke.mjs是 opt-in 冒烟测试会启动真实服务器因此必须通过批准的preview_start/server launcher 运行绝不能用后台 shell。输入必须独立验证node scripts/ui-proof-backend-smoke.mjs --run --cli /verified/convex-1.44.0/package/bin/main.js --backend-archive /verified/convex-local-backend-aarch64-apple-darwin.zip它依次证明scripts/ui-proof-backend-smoke.mjsbaseline/candidate 两种源码的部署信息查询正确全新数据库的写入/读取markers 表count0→1dev auth 关→开→关三态DEV_AUTH_ENABLED/DEV_AUTH_CONVEX_DEPLOYMENT断言/instance_name身份精确匹配且每次运行唯一macOS 上 API/site 两个回环监听套接字确实只绑定127.0.0.1用 lsof 断言完成清单bootstrap-summary.json为 pass、私有状态目录已被删除、端口已释放。文档同时明确边界smoke 的支撑依赖来自已安装的依赖快照它不认证完整应用的 build/browser 行为——那需要随后跑真实的 ClawHub UI proof即完整proof:ui。6.3 父级失败测试父级失败parent failure测试使用可丢弃的一次性 fixture畸形源码malformed-source、缺失查询missing-query、端口占用occupied-port以及各种信号绝不触碰操作者服务并验证不继续执行 完整拆除两个不变量。这与runProofBackend中拒绝已占用端口、拒绝身份不符、拒绝版本不符、拒绝摘要不符的早失败路径一一对应测试见 scripts/ui-proof-backend.test.mjs 的 rejects %s before source continuation 用例。七、产物与发布proof:publish工作流一次成功或失败但完整的验证会在输出目录留下产物内容summary.json顶层汇总mode、runner、provider、lanes 状态report.md人读报告每 lane 的步骤状态、截图路径、视频路径lane/lane/proof-steps.jsonUI 侧清单每步 name/slug/status/error 与截图lane/lane/bootstrap-summary.json后端侧清单status、后端版本、CLI 版本、instanceNamelane/lane/screenshots/*.png每步全页截图fullPage: truelane/lane/full-run.mp4ffmpeg x11grab 全程录屏默认 60 秒SIGINT 收尾lane/lane/lane-summary.jsonlane 名称/引用/baseURLconvex.log、seed.log、build.log、preview.log、ffmpeg.log分阶段脱敏日志proof:publishscripts/ui-proof-publish.mjs把上述证据发布为 PR 评论关键参数bun run proof:publish \ --proof-dir .artifacts/clawhub-ui-proof/timestamp \ --target-pr PR号 \ --artifact-branch qa-artifacts \ --repo openclaw/clawhub \ --dry-run # 只渲染评论正文不推送它把summary.json、report.md、每步截图、full-run.gif预览与full-run.mp4推送到qa-artifacts分支默认并用带!-- clawhub-ui-proof --标记的评论做幂等 upsertbefore-after模式渲染 baseline/candidate 左右对照表格feature模式渲染单列截图路径穿越防护normalizeTargetPath/assertInside防止产物逃逸。dry-run 的 proof 目录会被拒绝与 scripts/ui-proof-publish.test.mjs 的断言一致。八、源码地图从文档到实现要深入这套体系建议按以下路径阅读当前仓库总控编排scripts/ui-proof.mjs参数解析、计划构建、租约、rsync、双清单判定后端引导与清理scripts/ui-proof-backend.mjspin 表、环境隔离、进程组、脱敏、bootstrap-summary.json浏览器场景运行时scripts/ui-proof-runtime.mjsPlaywright launch、step 截图、proof-steps.json可选冒烟scripts/ui-proof-backend-smoke.mjs产物发布scripts/ui-proof-publish.mjs测试scripts/ui-proof.test.mjs、scripts/ui-proof-backend.test.mjs、scripts/ui-proof-runtime.test.mjs、scripts/ui-proof-publish.test.mjs规范原文specs/ui-proof.md配套目录说明见 specs/README.md整体而言proof:ui的设计回答了一个被大多数项目回避的问题如何让我本地跑通了变成团队可复现、可审计、且不会污染任何操作者环境的工程事实。固定版本 pin、按名拒绝状态文件、进程组信号契约与双清单完成判定共同构成了这条从源码到截图证据的可信链路。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐Solana ZK Token Proof 原生程序基于 Curve25519 的零知识证明验证指令全解析Solana ZK Token Proof 原生程序基于 Curve25519 的零知识证明验证指令全解析 Solana ZK Token Proof 原生程区块链后端分布式系统FreeRTOS 内核内存安全证明实战基于 CBMC 验证 vTaskStartScheduler 的 TaskStartScheduler Proof 全解析FreeRTOS 内核内存安全证明实战基于 CBMC 验证 vTaskStartScheduler 的 TaskStartScheduler Proof 全解操作系统嵌入式OS嵌入式物联网immudb 密码学证明体系全解析线性哈希、Merkle 树与 Dual Proof 验证流程immudb 密码学证明体系全解析线性哈希、Merkle 树与 Dual Proof 验证流程 immudb 是一款基于零信任zero trust理念构建数据库安全后端上一篇屏幕快照神器基于PHP与PhantomJS的Web截图工具下一篇LightnCandy极速PHP实现的Handlebars Mustache引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/25 5:44:31 · 阅读 1.2k ClawHub UI Proof Runtime：基于 Crabbox 的远程全栈 UI 验证体系解析
后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载导读specs/ui-proof.md定义了 ClawHub 的远程proof:ui验证运行时——一种从源码和全新本地数据出发、不触碰任何共享或生产后端的全栈 UI 证明机制。本文结合 scripts/ui-proof.mjs、scripts/ui-proof-backend.mjs、scripts/ui-proof-runtime.mjs 及对应测试完整还原其两种模式、两种 runner、隔离与信任模型、后端固定版本 pin、进程生命周期契约与验证边界让你理解这套体系为何能同时保证结果可信与环境干净。specs/目录按 specs/README.md 的约定存放维护者内部记录不默认发布到公开文档页specs/ui-proof.md正是其中一份维护者验证与 CI 策略记录。与之对应的可执行入口在仓库根的 package.json 中注册为两个 npm scriptproof:publish: node scripts/ui-proof-publish.mjs, proof:ui: node scripts/ui-proof.mjs,一、UI Proof 是什么从源码证明全栈proof:ui的核心定位是远程 lane 从各自源码出发、配合全新本地数据证明完整技术栈Convex 后端 前端构建 Playwright 浏览器场景真实可用。它刻意设计为没有共享后端模式、也没有生产后端模式——每次验证都从零搭建避免任何外部状态污染验证结论。一次验证按lane车道组织每个 lane 是一套独立的端口、输出目录和运行环境laneconvexCloud 端口convexSite 端口frontend 端口默认引用baseline441745174317origin/maincandidate441845184318worktree端口常量定义在 scripts/ui-proof.mjs 的DEFAULT_PORTS中。所有 URL 均为127.0.0.1回环地址且必须保证三个端口互不相同见 scripts/ui-proof-backend.mjs 中runProofBackend的端口校验。1.1 两种模式--mode before-after与--mode featurebefore-after默认同时运行 baseline 与 candidate 两个 lane逐步骤对比截图用于验证 PR 改动没有破坏既有功能feature只运行 candidate 一个 lane用于验证新功能本身报告中会明确标注 Baseline: not run for feature proof。模式由parseProofUiArgs校验scripts/ui-proof.mjs非法值直接抛错。测试 scripts/ui-proof.test.mjs 还专门验证了--mode smoke会被拒绝——smoke 是独立脚本不是proof:ui的模式。1.2 两种 runner--runner crabbox与--runner localcrabbox默认通过 Crabbox 运行器引导远端 lane——先warmup申请带桌面与浏览器的租约再run注入远程脚本结束后inspectrsync拉回产物最后stop释放租约。执行细节见 scripts/ui-proof.mjslocal只附着attach到维护者自行启动的回环实例不申请远端资源也绝不自己启动后端或预览服务。它要求传入--baseline-url/--candidate-url且二者必须解析到localhost、127.0.0.1或[::1]assertLocalProofUrl见 scripts/ui-proof.mjs。local模式仍然保证 baseline/candidate 的 URL 与产物目录彼此分离只是把启动服务的责任留在维护者手中。1.3 输出目录约定默认输出目录为.artifacts/clawhub-ui-proof/UTC 时间戳时间戳由timestamp()把冒号和点替换为连字符生成见 scripts/ui-proof.mjs内部再按baseline/、candidate/分 lane 存放远程模式下还会在远端写出remote-timestamp/lane目录并整体 rsync 回本地。测试 scripts/ui-proof.test.mjs 验证了该目录规划在两种模式下都稳定可预测。二、proof:ui命令行参数全参考以下参数全部来自parseProofUiArgsscripts/ui-proof.mjs的解析逻辑均为当前仓库实际支持参数默认值说明--scenario path必填临时 Playwright 场景文件路径缺省会直接抛错--mode before-after\|featurebefore-after验证模式--runner crabbox\|localcrabbox运行器选择--baseline reforigin/mainbaseline 引用--candidate refworktreecandidate 引用--baseline-url url无仅local模式且before-after时必填必须回环地址--candidate-url url无仅local模式必填必须回环地址--provider namehetznerCrabbox 云提供商--class/--machine-classstandard机器类别传给 Crabboxwarmup--crabbox-bin path仓库内 wrapper直接指定 Crabbox 可执行文件缺省走scripts/crabbox-wrapper.mjs--lease-id id无复用已有租约而不新申请warmupLease中created: false--idle-timeout60m租约空闲超时--ttl120m租约 TTL--dev-auth关显式开启后端与前端 dev auth--env KEYVALUE无透传特性开关等自定义环境变量有保留字黑名单见下文--seed-command cmd无用一次性自托管凭据执行种子脚本--skip-install关跳过依赖重装浏览器二进制仍会装进全新私有缓存--video-duration sec60ffmpeg 录屏时长--output-dir path见上覆盖产物根目录--dry-run关只写规划报告不申请租约、不运行任何运行时--keep-lease关验证结束后保留租约否则finally中stopLease一个典型的远程前后对比验证bun run proof:ui \ --mode before-after \ --scenario .artifacts/proof-scenarios/demo.pw.ts \ --provider hetzner \ --class standard \ --ttl 120m一个附着本机回环实例的 feature 验证bun run proof:ui \ --runner local \ --mode feature \ --candidate-url http://127.0.0.1:4318 \ --scenario .artifacts/proof-scenarios/demo.pw.ts2.1--env的保留字校验--env不是随便透传的assertProofEnvironmentscripts/ui-proof-backend.mjs会拒绝任何涉及连接、凭据、进程与私有状态的环境变量例如CONVEX_DEPLOYMENT、CONVEX_SELF_HOSTED_ADMIN_KEY、VITE_CONVEX_URL、HOME、XDG_CACHE_HOME、PATH、NODE_OPTIONS、BASH_ENV、LD_PRELOAD、HTTPS_PROXY、DEV_AUTH_ENABLED、VITE_ENABLE_DEV_AUTH等同时也拒绝TOKEN/SECRET/API_KEY等敏感模式与*_PATH/*_HOME类后缀。合法的典型用法是透传特性开关如--env FEATURE_FLAG1。测试 scripts/ui-proof.test.mjs 与 scripts/ui-proof-backend.test.mjs 均覆盖了这些拒绝路径其中--runner local附着模式不经过该校验URL 由维护者自担风险。三、隔离与信任模型证明必须干净proof:ui对干净的要求贯穿整个生命周期核心原则是任何云认证或操作者状态operator state都不得被读取、复制或 source 进验证环境。3.1 拒绝.convex与.env系列文件远程 wrapper 与 app 根目录必须按名称拒绝.convex、.env以及除example/sample/template之外的.env.*正则/^\.env\.(?!example$|sample$|template$)/u实现见assertCleanProofSourcescripts/ui-proof-backend.mjs。关键语义是只检查名字、不读取、不删除——本地调用者可能持有被.gitignore忽略的.env.local/.convex同步源码时绝不能把这些文件水合hydrate进验证环境。检查时点有三个初始、源码 push 之后、preparation/seed 之后checkSources被反复调用见 scripts/ui-proof-backend.mjs。测试 scripts/ui-proof-backend.test.mjs 用指向不可读路径的 symlink 验证检测到preparation/push/seed任一阶段产生的.env.local都会中止验证且 symlink 原样保留、绝不被触碰。3.2 lane 独占的私有状态每个 lane 拥有位于源码与产物目录之外的全新私有状态目录/tmp/clawhub-ui-proof-*权限 0700且通过 realpath 校验确保它不在 appRoot/wrapperRoot/outputDir 之内scripts/ui-proof-backend.mjs。目录内包含HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_DATA_HOME、TMPDIR、BUN_INSTALL数据库文件db.sqlite3与storage/自托管 CLI 选择文件cli.env仅含CONVEX_SELF_HOSTED_URL与CONVEX_SELF_HOSTED_ADMIN_KEY权限 0600子进程环境只继承PATH/DISPLAY加上 lane 显式设置项isolatedProofEnvironment见 scripts/ui-proof-backend.mjs。私有 HOME 还顺带防止了 CLI 回退到全局认证查找。实例名与实例密钥每次全新生成randomBytesidentity 绝不跨 lane 复用。3.3 安装钩子与 Bun 语义安装钩子在凭据存在之前运行。依赖安装必须使用bun install --frozen-lockfile而不是bun --no-env-file install——后者是非法组合--no-env-file是运行时参数不能作为install子命令前缀。但运行时调用build、seed、UI proof一律保留--no-env-file防止从任何.env文件读取变量。Bun/unzip 的供应provisioning是有界且非交互的PROVISION_PROOF_TOOLS脚本用timeout --signalTERM --kill-after5s 120s apt-get或 curl 安装 unzip/bunscripts/ui-proof-backend.mjs。--skip-install只跳过依赖重装浏览器二进制仍然会装进全新私有缓存XDG_CACHE_HOME绝不会从操作者的浏览器配置或缓存加载。对应测试见 scripts/ui-proof-backend.test.mjs 的 installs browsers in the fresh private cache 用例。3.4 信任边界声明文档明确写道源码与场景是可执行输入helper 本身不是沙箱它保留 Crabbox 既有的信任边界。也就是说隔离模型保证的是不泄露操作者状态而不是把任意第三方源码关进沙箱——这两件事被刻意区分。四、后端与源码就绪固定版本 pin 与身份校验4.1 CLI 与后端的固定 pin验证对工具版本采用**钉死pin**策略绝不解析 latest绝不执行未验证的归档Convex CLI 版本精确等于 1.44.0CONVEX_CLI_VERSION见 scripts/ui-proof-backend.mjs且必须直调其bin/main.js禁止使用复制的.binlauncher启动前读取package.json校验版本后端 release pin 为precompiled-2026-08-25-7cce8fbhelper 内维护四平台的 SHA-256 摘要表BACKENDS见 scripts/ui-proof-backend.mjs平台目标 tripleSHA-256节选darwin-arm64aarch64-apple-darwin98831b0f…7317bdarwin-x64x86_64-apple-darwind142472d…bea29linux-arm64aarch64-unknown-linux-gnua0601ec5…7e2flinux-x64x86_64-unknown-linux-gnu47025026…4eff9f下载或本地--backend-archive提供的 ZIP 必须通过 SHA-256 校验downloadProofBackend见 scripts/ui-proof-backend.mjs不支持的平台直接抛错。测试 scripts/ui-proof-backend.test.mjs 覆盖了版本不符与归档摘要不符两条拒绝路径。4.2 回环绑定与端口独占后端以--interface 127.0.0.1启动API 与 site 两个监听地址都绑定回环文档明确建议更换 pin 时复查上游config.rsinterface 用于 API 与 site 绑定地址与main.rs用两个地址启动监听。实际 argv 构造见backendArgumentsscripts/ui-proof-backend.mjs固定端口、--convex-origin/--convex-site回环 URL、--instance-name、--instance-secret该 pin 的后端只接受 argv 传入密钥、--disable-beacon关闭 beacon 遥测与--local-storage。CLI 侧用CI1关闭 Sentry且不启动 dashboard。三个固定端口必须检查两次preparation 之前、后端启动之前assertPortsFree见 scripts/ui-proof-backend.mjs。任何已占用端口都直接失败——绝不收养其他服务。4.3 身份校验与两段式就绪查询后端就绪后先要求GET /instance_name精确返回本次全新的实例名waitForProofEndpoint见 scripts/ui-proof-backend.mjs防止附着到别的实例。随后执行源码 pushnode verified-cli run --push --typecheck disable --codegen disable appMeta:getDeploymentInfo {} --env-file private-file注意--env-file指向权限 0600 的私有选择文件且使用--typecheck disable --codegen disable绕过不必要的本地检查。push 之后重新校验身份与源码洁净度再运行独立的run --no-push就绪查询之后才进入 seed/build/browser 阶段。测试 scripts/ui-proof-backend.test.mjs 精确断言了这一调用序列与参数。4.4 为什么禁用dev --local/dev --once文档特别警告CLI 1.44.0 的dev配置路径即使在显式选择自托管后仍会写.env.local——这正是验证环境最忌讳的水合污染。run --push绕开该路径因此是唯一被允许的源码推入方式。选择文件只含自托管 URL 与 admin keyapp 侧使用的local:fresh-instance标记与 CLI 选择文件严格分离。4.5--dev-auth与凭据分级--dev-auth通过convex env set显式设置后端DEV_AUTH_ENABLED与DEV_AUTH_CONVEX_DEPLOYMENT并给前端注入VITE_ENABLE_DEV_AUTH1见 scripts/ui-proof-backend.mjs 的appEnv构造。凭据按阶段分级seed只拿到一次性自托管凭据与直连 CLI/私有文件路径build/browser不拿任何 admin key。后端实例密钥必须出现在 argv 中因此进程参数永不打日志keygen输出标记为私有privateOutput: true其他子进程输出在记录前做有界截断保留最近 128 KiB与脱敏——包括被切分/截断的密钥片段redactProofText见 scripts/ui-proof-backend.mjs。对应测试验证了日志不包含密钥任何片段即使日志写入本身失败也要继续尝试移除私有状态。五、生命周期与完成契约清理必须被证明5.1 单控制器与进程组语义一个控制器统一处理后端/preview 退出、截止时间默认 20 分钟、SIGINT 与 SIGTERMscripts/ui-proof-backend.mjs。清理针对进程组而非仅 leader子进程以detached: true启动。清理序列为先发SIGTERMffmpeg 例外用SIGINT有界等待仍存活则升级SIGKILL。文档记录了三个精细的边界条件macOS 的 EPERMleader 已退出但尚未 close 时对进程组发信号可能报 EPERM因此必须先做有界 close/reap 等待再探测进程组关闭的管道 ≠ 后代已消失stdio 关闭不代表进程树清空一旦收到 ESRCH绝不再对那个数字组 ID 发信号组 ID 可能被复用权限拒绝只失败该记录某进程组拒绝信号EPERM时该记录标记失败但其他组仍继续尝试清理KILL 之后组可能短暂存在被 KILL 的后代以 zombie 形态留在组内直到 init 回收因此组已拆除的证明必须有界轮询不能只探测一次。LaneProcesses.signal/releasescripts/ui-proof-backend.mjs实现了上述策略测试 scripts/ui-proof-backend.test.mjs 用真实进程树验证了[0, SIGTERM, 0, SIGKILL]的完整信号序列与 zombie 轮询。5.2 主失败与清理错误共存主失败信息必须与清理错误一起保留errors数组聚合即便关闭/写日志失败也要继续写脱敏诊断、尝试移除私有状态。bootstrap-summary.json只在整个清理完成之后才写——它本身就是清理已认证的证书。5.3 双清单判定远程成功远程 lane 的成功需要两份清单同时通过proof-steps.jsonUI 侧由ui-proof-runtime.mjs的runUiProofScenario在finally中写入见 scripts/ui-proof-runtime.mjsbootstrap-summary.json后端侧清理后写入见 scripts/ui-proof-backend.mjs。已完成的通过清单可以恢复传输错误如 rsync/SSH 中途失败——但截图不能掩盖缺失或失败的 bootstrap 完成。这一判定逻辑在runLanescripts/ui-proof.mjs中实现测试 scripts/ui-proof.test.mjs 用pass/fail/missing三态 bootstrap 验证了该恢复规则。local附着模式只依赖 UI 清单。SIGKILL 或宿主机丢失仍需要外层容器兜底。六、验证与限制聚焦测试与可选冒烟6.1 聚焦测试真实 owner 窄 I/O 缝proof:ui的单元测试刻意避开 dotenv 加载与复制 launcher直接用真实 owner 配合窄 I/O 注入spawnImpl/kill/connect/fetchImpl等和真实的进程树清理。文档给出的聚焦运行方式node --input-typemodule -e import {startVitest} from vitest/node; const ctxawait startVitest(test,[scripts/ui-proof.test.mjs,scripts/ui-proof-backend.test.mjs,scripts/ui-proof-runtime.test.mjs,scripts/ui-proof-publish.test.mjs],{run:true},{envDir:false});await ctx.close();envDir:false确保测试进程绝不读取.env目录。四份测试文件分别覆盖参数解析与计划构建、后端启动与清理的密集边界、场景运行时截图/清单、产物发布与评论渲染。6.2 可选冒烟会启动真实回环服务器scripts/ui-proof-backend-smoke.mjs是 opt-in 冒烟测试会启动真实服务器因此必须通过批准的preview_start/server launcher 运行绝不能用后台 shell。输入必须独立验证node scripts/ui-proof-backend-smoke.mjs --run --cli /verified/convex-1.44.0/package/bin/main.js --backend-archive /verified/convex-local-backend-aarch64-apple-darwin.zip它依次证明scripts/ui-proof-backend-smoke.mjsbaseline/candidate 两种源码的部署信息查询正确全新数据库的写入/读取markers 表count0→1dev auth 关→开→关三态DEV_AUTH_ENABLED/DEV_AUTH_CONVEX_DEPLOYMENT断言/instance_name身份精确匹配且每次运行唯一macOS 上 API/site 两个回环监听套接字确实只绑定127.0.0.1用 lsof 断言完成清单bootstrap-summary.json为 pass、私有状态目录已被删除、端口已释放。文档同时明确边界smoke 的支撑依赖来自已安装的依赖快照它不认证完整应用的 build/browser 行为——那需要随后跑真实的 ClawHub UI proof即完整proof:ui。6.3 父级失败测试父级失败parent failure测试使用可丢弃的一次性 fixture畸形源码malformed-source、缺失查询missing-query、端口占用occupied-port以及各种信号绝不触碰操作者服务并验证不继续执行 完整拆除两个不变量。这与runProofBackend中拒绝已占用端口、拒绝身份不符、拒绝版本不符、拒绝摘要不符的早失败路径一一对应测试见 scripts/ui-proof-backend.test.mjs 的 rejects %s before source continuation 用例。七、产物与发布proof:publish工作流一次成功或失败但完整的验证会在输出目录留下产物内容summary.json顶层汇总mode、runner、provider、lanes 状态report.md人读报告每 lane 的步骤状态、截图路径、视频路径lane/lane/proof-steps.jsonUI 侧清单每步 name/slug/status/error 与截图lane/lane/bootstrap-summary.json后端侧清单status、后端版本、CLI 版本、instanceNamelane/lane/screenshots/*.png每步全页截图fullPage: truelane/lane/full-run.mp4ffmpeg x11grab 全程录屏默认 60 秒SIGINT 收尾lane/lane/lane-summary.jsonlane 名称/引用/baseURLconvex.log、seed.log、build.log、preview.log、ffmpeg.log分阶段脱敏日志proof:publishscripts/ui-proof-publish.mjs把上述证据发布为 PR 评论关键参数bun run proof:publish \ --proof-dir .artifacts/clawhub-ui-proof/timestamp \ --target-pr PR号 \ --artifact-branch qa-artifacts \ --repo openclaw/clawhub \ --dry-run # 只渲染评论正文不推送它把summary.json、report.md、每步截图、full-run.gif预览与full-run.mp4推送到qa-artifacts分支默认并用带!-- clawhub-ui-proof --标记的评论做幂等 upsertbefore-after模式渲染 baseline/candidate 左右对照表格feature模式渲染单列截图路径穿越防护normalizeTargetPath/assertInside防止产物逃逸。dry-run 的 proof 目录会被拒绝与 scripts/ui-proof-publish.test.mjs 的断言一致。八、源码地图从文档到实现要深入这套体系建议按以下路径阅读当前仓库总控编排scripts/ui-proof.mjs参数解析、计划构建、租约、rsync、双清单判定后端引导与清理scripts/ui-proof-backend.mjspin 表、环境隔离、进程组、脱敏、bootstrap-summary.json浏览器场景运行时scripts/ui-proof-runtime.mjsPlaywright launch、step 截图、proof-steps.json可选冒烟scripts/ui-proof-backend-smoke.mjs产物发布scripts/ui-proof-publish.mjs测试scripts/ui-proof.test.mjs、scripts/ui-proof-backend.test.mjs、scripts/ui-proof-runtime.test.mjs、scripts/ui-proof-publish.test.mjs规范原文specs/ui-proof.md配套目录说明见 specs/README.md整体而言proof:ui的设计回答了一个被大多数项目回避的问题如何让我本地跑通了变成团队可复现、可审计、且不会污染任何操作者环境的工程事实。固定版本 pin、按名拒绝状态文件、进程组信号契约与双清单完成判定共同构成了这条从源码到截图证据的可信链路。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐Solana ZK Token Proof 原生程序基于 Curve25519 的零知识证明验证指令全解析Solana ZK Token Proof 原生程序基于 Curve25519 的零知识证明验证指令全解析 Solana ZK Token Proof 原生程区块链后端分布式系统FreeRTOS 内核内存安全证明实战基于 CBMC 验证 vTaskStartScheduler 的 TaskStartScheduler Proof 全解析FreeRTOS 内核内存安全证明实战基于 CBMC 验证 vTaskStartScheduler 的 TaskStartScheduler Proof 全解操作系统嵌入式OS嵌入式物联网immudb 密码学证明体系全解析线性哈希、Merkle 树与 Dual Proof 验证流程immudb 密码学证明体系全解析线性哈希、Merkle 树与 Dual Proof 验证流程 immudb 是一款基于零信任zero trust理念构建数据库安全后端上一篇屏幕快照神器基于PHP与PhantomJS的Web截图工具下一篇LightnCandy极速PHP实现的Handlebars Mustache引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考