Genarrative/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md

AI Web 工程静态预览 MVP 验收清单

更新时间：2026-06-13

范围

本清单用于验收 /editor/agent 浏览器内 AI Web 工程编辑器 MVP。

MVP 必须只支持：

• 固定 React / Vite / TypeScript 静态模板。
• 虚拟文件系统。
• 结构化 AI patch。
• 独立 runner 静态构建。
• 独立 preview origin iframe 预览。
• 失败保留上一版可用预览。
• 左侧聊天、中间预览、右侧 IDE 的 /editor/agent 三分布局；右侧 IDE 展开文件内容后隐藏左侧聊天。

MVP 不支持：

• 终端 shell。
• 后端服务。
• HMR。
• 任意端口代理。
• 任意 npm 安装。
• AI 自定义 package scripts。
• diff 视图。
• Service Worker。
• 主站同源预览。

Happy Path

• 用户打开 /editor/agent 能看到左侧聊天、中间预览和右侧 IDE 文件树。
• 右侧 IDE 默认只显示文件树，不默认显示文件内容。
• 用户展开右侧 IDE 后能看到当前文件内容，左侧聊天栏隐藏。
• 用户收起右侧文件内容后恢复左侧聊天、中间预览和右侧文件树三栏。
• 页面不展示 diff 视图。
• 创建新 Web project 后得到固定模板文件树。
• 用户在左侧聊天提交需求后创建 agent turn。
• 智能体结合当前 snapshot、选中文件和最近构建状态生成结构化 patch plan。
• AI patch plan 新增或修改一个 React 组件后，api-server 校验通过并生成新 snapshot。
• patch 校验失败时不生成 snapshot，不创建 build job，并在聊天中展示可读校验错误。
• 前端 debounce 后创建 preview build job。
• runner 构建成功并产出 immutable artifact。
• SSE 返回 queued -> running -> succeeded。
• iframe 切换到新 preview URL。
• 刷新 /editor/agent 后能恢复当前 project、active snapshot、active preview、agent turn 历史和未完成 job 状态。

智能体编排

• 智能体只通过 agent-turns 或等价受控接口提交用户需求，不直接写真实目录。
• 智能体输出只包含 create_file/update_file/delete_file/rename_file/package_manifest_request 这类结构化 patch 操作。
• 智能体不输出或执行 shell 命令。
• 智能体不直接触发任意 npm script。
• 智能体不直接访问 runner 临时工作区。
• 智能体不接收平台 access token、用户 cookie、SpacetimeDB 连接、OSS 写权限或 LLM provider 密钥。
• 每轮 agent turn 记录用户输入、上下文摘要、patch 摘要、校验结果、snapshotId、jobId 和最终状态。
• 构建失败后，智能体基于受脱敏的错误摘要生成下一轮修复 patch。
• 构建成功后，智能体不会覆盖非当前 active snapshot 的 preview。

Patch 与路径校验

• 相对路径普通源码修改通过。
• 绝对路径被拒绝。
• .. 路径被拒绝。
• 符号链接被拒绝。
• .env 被拒绝。
• .npmrc 被拒绝。
• .git/ 被拒绝。
• .ssh/ 被拒绝。
• 超深目录被拒绝。
• 超大单文件被拒绝。
• 超大 snapshot 被拒绝。
• 大 Data URL 被拒绝或转资产流程。
• 二进制膨胀被拒绝。
• rename 后目标路径仍需重新校验。

构建与状态机

• job 状态覆盖 queued/running/succeeded/failed/cancelled/expired/stale。
• 新 snapshot 创建后，旧 running job 被取消或标记 stale。
• 只有当前 active snapshot 的 succeeded job 能推进 active preview。
• failed job 不覆盖上一版 active preview。
• cancelled job 不覆盖上一版 active preview。
• expired job 不覆盖上一版 active preview。
• stale job 不覆盖上一版 active preview。
• 构建失败时展示可读错误摘要和日志片段。
• 构建超时后 runner 被 kill，job 进入 failed 或 expired。
• runner 崩溃后 job 能恢复为可重领或 expired。
• 页面刷新后能通过 projectId / jobId 恢复日志和状态。
• snapshot 回滚会复用对应 immutable artifact 或重新构建，不复用临时目录。

Runner 隔离

• runner 进程无平台密钥环境变量。
• runner 无宿主源码目录挂载。
• runner 无 Docker socket。
• runner 使用非 root 用户。
• runner 工作区为任务级临时目录。
• 任务结束后临时目录被销毁。
• CPU 限制生效。
• 内存限制生效。
• 磁盘限制生效。
• 进程数限制生效。
• 打开文件数限制生效。
• 日志大小限制生效。
• artifact 大小限制生效。
• 任务超时限制生效。

网络隔离

• 构建期默认不能访问公网。
• 若允许 registry mirror，只能访问白名单域名。
• 不能访问 RFC1918 内网地址。
• 不能访问云 metadata 地址。
• 不能访问 api-server 管理端口。
• 不能访问 SpacetimeDB。
• 不能访问生产数据库。
• HTTP redirect 到内网时被阻断。
• DNS rebinding 到内网时被阻断。

依赖供应链

• AI 修改 package.json 新增普通依赖时，MVP 拒绝或忽略。
• preinstall 被拒绝或忽略。
• install 被拒绝或忽略。
• postinstall 被拒绝或忽略。
• prepare 被拒绝或忽略。
• git: 依赖被拒绝。
• file: 依赖被拒绝。
• http: / https: tarball 依赖被拒绝。
• 私有 registry 被拒绝。
• lockfile 篡改被拒绝或重写。
• 构建命令由平台固定，不执行 AI 写入的 shell script。

Preview Token 与 Gateway

• preview token 绑定 owner。
• preview token 绑定 project。
• preview token 绑定 snapshot。
• preview token 绑定 artifact。
• preview token 短期有效。
• preview token 可撤销。
• preview token 不可枚举。
• 跨租户访问返回 403 或 404。
• path traversal 被拒绝。
• 错误 MIME 不会按可执行脚本服务。
• SPA fallback 只在 artifact 根内生效。
• artifact 删除后旧 URL 不能继续读取。
• token 过期后旧 URL 不能继续读取。
• preview cache 不串租户。

浏览器隔离

• 预览 origin 与主站 origin 不同。
• 预览 iframe 不带主站 cookie。
• 预览代码不能读取主站 localStorage。
• 预览代码不能读取主站 sessionStorage。
• 预览代码不能调用主站认证 API。
• iframe sandbox 不允许 top navigation。
• iframe sandbox 不允许 downloads。
• iframe sandbox 不允许 popups。
• iframe sandbox 不允许 clipboard。
• iframe sandbox 不允许 camera / mic。
• CSP 禁止未白名单 connect-src。
• Service Worker 被禁用。

日志与错误

• 构建日志按 jobId 分段展示。
• 日志限长。
• 错误摘要可读。
• 日志不包含平台 token。
• 日志不包含 OSS 写签名。
• 日志不包含完整宿主路径。
• 日志不包含环境变量 dump。
• SSE 断开后前端可重新拉取 job 状态。

取消、回滚与并发

• 用户连续编辑触发多个 snapshot 时，只保留最新 snapshot 的 active build 候选。
• 用户手动取消当前 build 后，runner 停止或 job 被标记 cancelled。
• 两个标签页同时编辑同一项目时，有明确版本冲突或 last-write 策略提示。
• 回滚到历史 snapshot 后，active preview 对应历史 snapshot。
• 历史 artifact 缺失时可重新构建。
• 构建队列积压时 /editor/agent 显示确定状态，不假装实时完成。

Artifact GC

• 未引用的 failed artifact 会清理。
• 过期 preview artifact 会清理。
• active preview artifact 不会被误删。
• 历史 snapshot 的可回滚 artifact 按保留策略保留或可重建。
• GC 后 preview gateway 对已删除 artifact 返回确定错误。

最小自动化验证建议

后端 / runner：

cargo test -p api-server web_project --manifest-path server-rs/Cargo.toml
cargo test -p spacetime-module web_project --manifest-path server-rs/Cargo.toml

前端：

npm run test -- src/services/sseStream.test.ts
npm run test -- src/components/editor/agent
npm run typecheck
npm run check:encoding
git diff --check

浏览器 smoke：

打开 /editor/agent
创建模板项目
提交一次 AI patch
等待静态构建成功
确认 iframe 展示新预览
提交一次故意破坏构建的 patch
确认错误出现且上一版预览仍保留
刷新页面确认项目、日志和 active preview 可恢复