补充AIWeb智能体落地方案

明确 /editor/agent 智能体作为工程改动编排器，通过结构化 patch、校验、snapshot、构建和预览反馈闭环落地。

补充左侧聊天、中间预览、右侧 IDE 的页面布局约束，右侧展开文件内容后隐藏聊天栏。

同步验收清单，明确 MVP 不做 diff 视图并覆盖 agent turn 和布局验收。

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，只返回可展示的校验错误和智能体修正建议。
+
 ## 虚拟文件系统
 
 平台内的“文件系统”是虚拟工作区，不是真实目录长期挂载。

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 与路径校验