From b4746c24b59c2bc44e684d0abdadd7afa7059ffc Mon Sep 17 00:00:00 2001 From: kdletters Date: Sun, 14 Jun 2026 19:34:44 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85AIWeb=E6=99=BA=E8=83=BD?= =?UTF-8?q?=E4=BD=93=E8=90=BD=E5=9C=B0=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确 /editor/agent 智能体作为工程改动编排器，通过结构化 patch、校验、snapshot、构建和预览反馈闭环落地。 补充左侧聊天、中间预览、右侧 IDE 的页面布局约束，右侧展开文件内容后隐藏聊天栏。 同步验收清单，明确 MVP 不做 diff 视图并覆盖 agent turn 和布局验收。 --- ...】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md | 96 ++++++++++++++++++- ...例】AIWeb工程静态预览MVP验收清单-2026-06-13.md | 27 +++++- 2 files changed, 118 insertions(+), 5 deletions(-) diff --git a/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md b/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md index 236780ed..694bdb77 100644 --- a/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md +++ b/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md @@ -29,6 +29,7 @@ MVP 明确不做： - HMR / 长驻 dev server。 - 任意 npm 依赖安装。 - AI 自定义 build shell script。 +- diff 视图。 - 与主站同源的预览 iframe。 - 将 AI 生成工程写入当前 Genarrative 仓库源码目录。 @@ -38,8 +39,9 @@ MVP 明确不做： 入口路由固定为 `/editor/agent`。这一层只负责前端体验： -- 文件树、代码编辑器、AI 指令输入。 -- 当前项目版本、diff、构建日志和预览 iframe。 +- 左侧聊天、中间预览、右侧 IDE 的水平三分布局。 +- AI 指令输入、构建日志、当前项目版本和预览 iframe。 +- 右侧 IDE 默认只显示文件树；展开后显示当前文件内容，并隐藏左侧聊天栏。 - 保存用户编辑和 AI patch。 - 订阅构建 job SSE 状态。 - 在构建成功后切换 iframe 的 `previewUrl`。 @@ -49,6 +51,74 @@ MVP 明确不做： 如果后续接入现有创作链路，入口仍应走 `play_flow` 主干和 `shared-contracts` DTO，不在前端壳或 `app.rs` 中新建平行业务流程。 +### 智能体编排器 + +`/editor/agent` 的智能体不是普通聊天页，也不是直接生成整包代码的黑盒。它是“工程改动编排器”，负责把用户意图转成可审计、可校验、可回滚的 Web 工程 patch。 + +智能体职责： + +- 理解用户自然语言目标，并结合当前 snapshot、文件树、选中文件和最近构建结果形成任务上下文。 +- 输出结构化 patch plan，而不是直接写真实目录或执行 shell。 +- 将 patch plan 提交给 api-server 校验，校验通过后生成新 snapshot。 +- 创建 preview build job，并订阅 job SSE。 +- 读取构建日志、错误摘要和 preview 状态，失败时继续生成修复 patch，成功时推动预览切换。 +- 保留每轮 agent turn 的用户输入、上下文摘要、patch 摘要、校验结果、jobId 和最终状态，便于刷新恢复和审计。 + +智能体最小闭环： + +```text +用户在左侧聊天输入需求 + -> 前端提交 agent turn + -> api-server 读取当前 snapshot 和允许暴露的上下文 + -> LLM 返回结构化 patch plan + -> api-server 校验 patch plan + -> 校验通过后生成新 snapshot + -> 创建 preview build job + -> runner 构建 + -> SSE 回传 queued / running / log / succeeded / failed + -> 成功时中间预览 iframe reload + -> 失败时智能体基于错误摘要进入下一轮修复 +``` + +智能体输出只允许以下 patch 操作： + +- `create_file` +- `update_file` +- `delete_file` +- `rename_file` +- `package_manifest_request` + +`package_manifest_request` 只是依赖请求，不是事实源。MVP 中 api-server 必须拒绝或忽略任意新增依赖、生命周期脚本、私有 registry、`git:` / `file:` / `http:` 依赖和 AI 自定义构建命令。 + +智能体不得： + +- 直接写入当前 Genarrative 仓库源码目录。 +- 直接访问 runner 临时工作区。 +- 直接执行 shell、npm script 或任意构建命令。 +- 直接拿平台 access token、用户 cookie、SpacetimeDB 连接、OSS 写权限或 LLM provider 密钥。 +- 绕过 api-server 的路径、依赖、大小、敏感文件和 snapshot 校验。 + +### 页面布局 + +`/editor/agent` MVP 使用水平三分布局，不做 diff 视图： + +```text +┌───────────────┬──────────────────────────────┬────────────────┐ +│ 左侧聊天 │ 中间预览 │ 右侧 IDE │ +│ Agent 对话 │ sandbox iframe + 状态日志 │ 默认文件树 │ +└───────────────┴──────────────────────────────┴────────────────┘ +``` + +布局规则： + +- 左侧聊天承载用户输入、智能体回复、构建状态摘要和失败修复建议。 +- 中间预览始终是主工作区，展示当前 active preview iframe；构建失败时保留上一版 succeeded preview，并在聊天或日志区域展示失败摘要。 +- 右侧 IDE 默认只显示文件树，突出当前工程结构，不默认展示代码内容。 +- 用户展开右侧 IDE 后，右侧显示文件树和当前文件内容，左侧聊天栏隐藏，中间预览与右侧 IDE 形成双栏工作模式。 +- 用户收起右侧文件内容后，恢复左侧聊天 + 中间预览 + 右侧文件树三栏。 +- 文件内容查看用于理解和轻量编辑当前文件，不提供 diff 视图；版本变化通过 agent turn 摘要、snapshot 时间线和构建状态表达。 +- 移动端优先保持预览和聊天可用，右侧 IDE 通过抽屉或分段入口进入；展开文件内容时同样隐藏聊天。 + ### api-server 控制面 控制面只管理权限、快照、任务和状态，不执行 AI 工程代码： @@ -128,6 +198,7 @@ MVP 只服务静态构建产物。HMR、WebSocket 代理和长驻 dev server 后 POST /api/creation/web-project/projects GET /api/creation/web-project/projects/{projectId}/snapshot PATCH /api/creation/web-project/projects/{projectId}/files +POST /api/creation/web-project/projects/{projectId}/agent-turns POST /api/runtime/web-project/projects/{projectId}/preview-builds GET /api/runtime/web-project/preview-builds/{jobId} GET /api/runtime/web-project/preview-builds/{jobId}/events @@ -146,6 +217,27 @@ GET /api/runtime/web-project/preview-builds/{jobId}/events 前端刷新恢复时，先读取项目 active snapshot 和 active preview，再按未终态 job 继续订阅 SSE。 +`agent-turns` 的请求建议包含： + +- `projectId` +- `baseSnapshotId` +- `message` +- `selectedFilePath` +- `visibleFilePaths` +- `recentBuildJobId` + +`agent-turns` 的响应建议包含： + +- `turnId` +- `status` +- `assistantMessage` +- `patchSummary` +- `validationErrors[]` +- `snapshotId` +- `buildJobId` + +当 patch 校验失败时，不生成 snapshot，不创建 build job，只返回可展示的校验错误和智能体修正建议。 + ## 虚拟文件系统 平台内的“文件系统”是虚拟工作区，不是真实目录长期挂载。 diff --git a/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md index 1d97a0ff..45445ff2 100644 --- a/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md +++ b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md @@ -14,6 +14,7 @@ MVP 必须只支持： - 独立 runner 静态构建。 - 独立 preview origin iframe 预览。 - 失败保留上一版可用预览。 +- 左侧聊天、中间预览、右侧 IDE 的 `/editor/agent` 三分布局；右侧 IDE 展开文件内容后隐藏左侧聊天。 MVP 不支持： @@ -23,19 +24,39 @@ MVP 不支持： - 任意端口代理。 - 任意 npm 安装。 - AI 自定义 package scripts。 +- diff 视图。 - Service Worker。 - 主站同源预览。 ## Happy Path -- [ ] 用户打开 `/editor/agent` 能看到文件树、编辑器、AI 输入区、构建日志区和预览 iframe。 +- [ ] 用户打开 `/editor/agent` 能看到左侧聊天、中间预览和右侧 IDE 文件树。 +- [ ] 右侧 IDE 默认只显示文件树，不默认显示文件内容。 +- [ ] 用户展开右侧 IDE 后能看到当前文件内容，左侧聊天栏隐藏。 +- [ ] 用户收起右侧文件内容后恢复左侧聊天、中间预览和右侧文件树三栏。 +- [ ] 页面不展示 diff 视图。 - [ ] 创建新 Web project 后得到固定模板文件树。 -- [ ] AI patch 新增或修改一个 React 组件后，api-server 生成新 snapshot。 +- [ ] 用户在左侧聊天提交需求后创建 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 和未完成 job 状态。 +- [ ] 刷新 `/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 与路径校验