|
|
@@ -0,0 +1,186 @@
|
|
|
+# AI 产物(Artifacts)输出架构
|
|
|
+
|
|
|
+## Context
|
|
|
+
|
|
|
+模型通过 `write_file` / `edit_file` / `execute` 生成的产物已经落在会话工作区磁盘上(实测 `artifact-test.txt` 位于 `cases/{caseId}/ai/workbench/{sessionId}/`),但聊天页只展示工具调用状态和文字路径,用户看不到、也下载不了产物。`ai_message_attachment` 是「用户上传给模型」的表,不适合存模型产物。
|
|
|
+
|
|
|
+产品需求 `docs/AI工作台演示稿.md` §2.10 已明确:右侧「产物」栏、按会话隔离、支持预览与下载。本次按「文件即事实」实现,不建新表。
|
|
|
+
|
|
|
+### 业界做法(调研结论)
|
|
|
+
|
|
|
+| 产品 | 做法 | 对本项目的启示 |
|
|
|
+|---|---|---|
|
|
|
+| Claude Artifacts | 产物在对话右侧独立面板;可预览/编辑/下载;产物库跨会话持久化 | 右侧面板 + 标题栏入口;先做会话内列表,暂不做跨会话库 |
|
|
|
+| Manus Sandbox | 每个 task 独立 VM;右上角「View all files in this task」;文件生命周期随沙箱 | 按会话目录隔离;入口放在标题栏右上角 |
|
|
|
+| WrenAI Artifacts | workspace 文件按 filename 寻址,提供 list/download 接口,`?mode=download` | 列表/下载 API 分离;下载强制 Content-Disposition |
|
|
|
+| Devin | 会话附件 list + 短时 presigned download;文件侧栏 | 下载 URL 鉴权;侧栏文件操作 |
|
|
|
+| 本仓库旧 Codex 设计 | `codexArtifactPanel`:目录树 + 大小/时间 + 新产物角标 + 刷新;主进程 root 白名单 + 路径穿越校验 | 复用交互与路径安全思路 |
|
|
|
+
|
|
|
+Sources: [Claude Artifacts](https://support.claude.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them)、[Manus Sandbox](https://www.manus.im/blog/manus-sandbox)、[WrenAI Artifacts API](https://wrenai.readme.io/reference/artifacts)、`docs/AI工作台演示稿.md`、`docs/design/codex-analysis-plan.md`。
|
|
|
+
|
|
|
+## 核心决策(已确认)
|
|
|
+
|
|
|
+1. **产物源 = 磁盘,不写 `ai_message_attachment`、不复制到 OSS、不新增索引表。**
|
|
|
+2. **仅智能工作台会话**(`ai_session.source = workbench`),根目录 `cases/{caseId}/ai/workbench/{sessionId}`,天然按会话隔离。
|
|
|
+3. **展示全部非系统文件**:会话根文件、`outputs/`、其他用户目录;排除 `agents/`、`default/`、`memory/`、`.skills-cache/`、`.agentscope-runtime/`、`large_tool_results/`、`sessions/`、`events/`、`logs/`、`tmp/`、`.project/`、`shared/`,以及隐藏文件、符号链接、非普通文件。
|
|
|
+4. **预览范围**:文本/Markdown/CSV/图片/PDF/HTML;Office 首版只提供下载。
|
|
|
+5. **HTML 预览直接同源渲染**:模型产物不作为不可信内容处理,iframe `srcdoc` 同源加载,不做 sandbox/CSP 隔离。
|
|
|
+6. **下载接入现有 Electron 下载管理器**:复用 `startDownload`(URL + `x-token` + fileName),下载进度/记录出现在工作台顶栏已有的 `AppDownloadManager`,不新增第二个下载器。
|
|
|
+
|
|
|
+## 后端设计
|
|
|
+
|
|
|
+### 新增接口(`AiArtifactController`)
|
|
|
+
|
|
|
+放在 `/ai/chat/session/{sessionId}/artifacts`,与附件接口同口径,每个方法先 `aiSessionService.assertSessionInCurrentCase(sessionId)`:
|
|
|
+
|
|
|
+- `GET /`:产物列表
|
|
|
+ - 返回 `{ sessionId, items[], total, truncated }`
|
|
|
+ - item 字段:`path`(相对会话根、POSIX)、`name`、`kind`、`mime`、`size`、`lastModified`、`previewable`、`downloadable`
|
|
|
+- `GET /content?path=...`:文本类预览(含 HTML 源码)
|
|
|
+ - 返回 `{ path, name, kind, mime, size, lastModified, text, truncated }`
|
|
|
+ - 仅文本类读取,上限 1 MB / 20 万字符
|
|
|
+- `GET /download?path=...&inline=false`:文件流
|
|
|
+ - `Content-Disposition: attachment/inline; filename*=UTF-8''...`
|
|
|
+ - `Content-Type` 按扩展名映射;HTML/SVG 下载时用 `application/octet-stream` + attachment,避免直接当页面打开
|
|
|
+ - `Cache-Control: no-store`、`X-Content-Type-Options: nosniff`
|
|
|
+
|
|
|
+### Service 与安全
|
|
|
+
|
|
|
+新增 `IAiArtifactService` / `AiArtifactServiceImpl`:
|
|
|
+
|
|
|
+1. 校验 `session.source == AiSession.SOURCE_WORKBENCH`,否则明确报错。
|
|
|
+2. 根目录:`StorageLayout.caseWorkbenchSessionDir(caseId, sessionId)`(新增方法,内部 `caseWorkbenchDir(caseId).resolve(sessionId)`)。
|
|
|
+3. 列表扫描:`Files.walkFileTree`,不跟随符号链接;最大深度 8、最多 500 个文件;`visitFileFailed` 跳过;按 `lastModified` 倒序。
|
|
|
+4. 路径校验(下载/预览共用):
|
|
|
+ - 只接受相对路径;`Path.of(raw).normalize()` 后拒绝绝对路径、`..`、盘符、空路径
|
|
|
+ - `target = root.resolve(relative).normalize()`,必须 `startsWith(root)`
|
|
|
+ - `toRealPath()` 后再校验一次;拒绝符号链接;必须 `Files.isRegularFile`
|
|
|
+ - 拒绝 reserved 目录(即使知道路径也不能下载 `agents/...`)
|
|
|
+5. 响应直接返回 `ResponseEntity<Resource>`(`FileSystemResource`),参考 `SystemService.downloadFile` 的 `ContentDisposition` 写法;不返回 `/files/**` URL,因为 `/files/**` 只校验登录、不校验会话归属。
|
|
|
+
|
|
|
+### VO
|
|
|
+
|
|
|
+新增 `AiArtifactVo`、`AiArtifactListVo`、`AiArtifactContentVo`;`kind` 枚举由扩展名推导:`text / markdown / csv / json / image / pdf / html / office / archive / other`。
|
|
|
+
|
|
|
+## HTML 预览方案
|
|
|
+
|
|
|
+- 后端 `GET /content` 对 `.html/.htm` 返回源码文本(JSON),不直接返回 `text/html`。
|
|
|
+- 前端预览弹窗用同源 iframe 渲染:
|
|
|
+ ```html
|
|
|
+ <iframe class="artifact-html-preview" :srcdoc="htmlContent" />
|
|
|
+ ```
|
|
|
+ 不加 `sandbox`,不注入 CSP;模型生成的 HTML 中的 CSS/JS 正常执行。
|
|
|
+- 典型产物是自包含 HTML(内联 CSS/JS),可直接预览;如果 HTML 引用同目录的兄弟资源,`srcdoc` 无法解析相对路径,预览可能不完整,弹窗提供「下载」按钮作为兜底。
|
|
|
+- HTML 下载仍走附件流(`application/octet-stream` + attachment),不通过浏览器直接打开。
|
|
|
+- SVG 作为图片预览时用 `<img>` 加载 blob;其余图片/PDF 用 blob URL。
|
|
|
+
|
|
|
+**其余预览类型**
|
|
|
+- 文本/Markdown:`getArtifactContent` → `<pre>` 或现有 `AiMarkdown`
|
|
|
+- CSV:解析为表格(复用仓库已有 `xlsx` 依赖或简单 CSV 解析)
|
|
|
+- 图片/PDF:`fetchArtifactBlob` → `URL.createObjectURL` → `<img>` / `<iframe>`;关闭时 `revokeObjectURL`
|
|
|
+- Office:只提供下载
|
|
|
+
|
|
|
+## 前端设计
|
|
|
+
|
|
|
+### 新增 API 模块
|
|
|
+
|
|
|
+`ai-electron/frontend/src/workbench/api/artifact.ts`:
|
|
|
+
|
|
|
+- `listArtifacts(sessionId)`、`getArtifactContent(sessionId, path)`
|
|
|
+- `buildArtifactDownloadUrl(sessionId, path)`:用 `useGlobSetting()` 拼 `apiUrl + urlPrefix + adminPath`
|
|
|
+- `downloadArtifact(sessionId, item)`:
|
|
|
+ - 桌面端:`startDownload({ url, fileName: item.name, mime: item.mime, headers: { 'x-token': token }, source: 'AI 产物' })`
|
|
|
+ - 浏览器:`aiDownload(..., 'GET')` 或 `downloadByUrl`
|
|
|
+ - 用 `onDownloadProgress` 按 `item.id` 过滤,成功后提示"已下载",失败提示原因
|
|
|
+- `fetchArtifactBlob(sessionId, path)`:给图片/PDF 预览用,axios 带 `x-token` 取 blob
|
|
|
+
|
|
|
+### 聊天页改动(`chat/index.vue`)
|
|
|
+
|
|
|
+**标题栏**
|
|
|
+- `.chat-context-bar` 增加右侧图标按钮(使用已 safelist 的 `i-mdi:folder-open-outline`),`aria-expanded`、tooltip「产物」
|
|
|
+- 把 `v-if="messages.length"` 改为 `v-if="currentSessionId"`,保证新会话也能打开产物面板
|
|
|
+- 面板开关状态存 `localStorage`,默认收起
|
|
|
+
|
|
|
+**右侧面板**
|
|
|
+- 作为 `.chat-workbench` 第三个 flex 子项:`<aside class="chat-artifact-panel">`,`flex: 0 0 320px`
|
|
|
+- 面板头:`产物` + 数量 + 刷新按钮 + 收起按钮
|
|
|
+- 列表行:文件图标(按 kind)、文件名、相对路径、大小、修改时间;hover 显示「预览」「下载」
|
|
|
+- 空态/加载/错误/`truncated` 提示
|
|
|
+- ≤900px 改为 fixed overlay + 遮罩,避免挤压聊天区
|
|
|
+
|
|
|
+**预览弹窗**
|
|
|
+- 文本/Markdown/CSV/图片/PDF/HTML 按上述分支渲染
|
|
|
+- Office 显示「该类型暂不支持在线预览,请下载后查看」
|
|
|
+- 复用 `formatSize`(`core/components/Upload/src/helper.ts`)、`Icon`、`EmptyState`
|
|
|
+
|
|
|
+**刷新时机**
|
|
|
+- SSE `tool_result` 成功 → 500ms 防抖刷新(覆盖 write_file / edit_file / execute)
|
|
|
+- SSE `done` → 再刷新一次兜底
|
|
|
+- 切换会话 → 清空并重新加载
|
|
|
+- 新建会话 / 切案件 → 清空
|
|
|
+- 停止生成 → 刷新(展示已落盘的部分产物)
|
|
|
+- 面板头部手动刷新
|
|
|
+
|
|
|
+## Electron 下载管理器适配
|
|
|
+
|
|
|
+现有链路已完备,**不新增 IPC/Controller**:
|
|
|
+
|
|
|
+- `frontend/src/core/utils/desktop/downloader.ts#startDownload` 支持 URL + headers,主进程流式落盘、进度推送、下载记录
|
|
|
+- `AppDownloadManager` 已挂在 `WorkbenchLayout.vue` 顶栏,产物下载会自动出现在现有管理器
|
|
|
+- 默认保存到系统下载目录,重名自动 `(1)`,不自动打开、不弹系统通知
|
|
|
+
|
|
|
+需要补一个健壮性改动(`electron/service/download/downloadService.js`):
|
|
|
+
|
|
|
+- `run()` 收到 `application/json` 响应且 `code != 200` 时,按失败处理并回传 message,避免把 401/业务错误 JSON 保存成文件
|
|
|
+- 可选:读取 `Content-Disposition` 作为 `fileName` 缺省值(当前调用方会传 fileName,非必需)
|
|
|
+
|
|
|
+## 需要新增/修改的文件
|
|
|
+
|
|
|
+**新增(后端)**
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/controller/AiArtifactController.java`
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/service/IAiArtifactService.java`
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/service/impl/AiArtifactServiceImpl.java`
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/domain/vo/AiArtifactVo.java`
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/domain/vo/AiArtifactListVo.java`
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/module/ai/domain/vo/AiArtifactContentVo.java`
|
|
|
+
|
|
|
+**修改(后端)**
|
|
|
+- `ai-server/src/main/java/com/zsjz/ai/common/storage/StorageLayout.java`(新增 `caseWorkbenchSessionDir`)
|
|
|
+
|
|
|
+**新增(前端)**
|
|
|
+- `ai-electron/frontend/src/workbench/api/artifact.ts`
|
|
|
+
|
|
|
+**修改(前端)**
|
|
|
+- `ai-electron/frontend/src/workbench/views/chat/index.vue`(标题栏图标、右侧面板、预览弹窗、刷新钩子)
|
|
|
+- `ai-electron/frontend/src/workbench/api/http.ts`(如需补 `aiFetchBlob`)
|
|
|
+- `ai-electron/frontend/src/uno.config.ts`(仅当新增图标不在 safelist 时)
|
|
|
+
|
|
|
+**修改(Electron)**
|
|
|
+- `ai-electron/electron/service/download/downloadService.js`(JSON 错误响应识别)
|
|
|
+
|
|
|
+## 验证
|
|
|
+
|
|
|
+1. **编译/静态检查**
|
|
|
+ - `mvn -q -pl ai-server -am -DskipTests compile`
|
|
|
+ - 对改动的前端文件跑 `eslint`
|
|
|
+2. **端到端(浏览器/Electron)**
|
|
|
+ - 在 `/workbench/chat` 发消息让模型 `write_file` 生成 `outputs/report.csv`,允许 HITL
|
|
|
+ - 标题栏图标出现;打开右侧面板,产物出现在列表;刷新后仍在
|
|
|
+ - 点击下载:Electron 下载管理器出现进度/记录,文件落到下载目录;浏览器模式走 blob 下载
|
|
|
+ - 预览:文本/Markdown/CSV/图片/PDF/HTML 正常;Office 提示下载
|
|
|
+ - HTML 预览:模型生成的 HTML(含内联 CSS/JS)在 iframe 中正常渲染与交互
|
|
|
+ - 让模型用 `execute` 写一个文件(如 `echo hi > outputs/exec.txt`),面板刷新后能看到(验证扫描覆盖 execute)
|
|
|
+ - 切换会话:只显示当前会话产物;切回原会话恢复;新会话为空
|
|
|
+ - 专家链路产物(专家在入口会话工作区写文件)同样出现在面板
|
|
|
+3. **安全**
|
|
|
+ - `GET .../download?path=../../...`、绝对路径、`agents/xxx` → 400/403
|
|
|
+ - 非本人会话 / 非当前案件 → 拒绝
|
|
|
+ - 未登录 → 401;HTML/SVG 下载响应为 attachment + `nosniff`
|
|
|
+ - 造一个超长/超多文件目录,确认 `truncated` 与上限生效
|
|
|
+
|
|
|
+## 不在本期范围
|
|
|
+
|
|
|
+- 不建 `ai_session_artifact` 索引表;不做产物版本、晋升为"项目产物"、跨会话产物库
|
|
|
+- 不做 Office 在线预览、产物删除/保留策略
|
|
|
+- 不修改模型提示词或工具;产物发现完全依赖磁盘扫描
|
|
|
+- `execute` 写到会话工作区之外的文件不会出现在面板(当前命令工具在宿主机执行,这是已知边界)
|