From 0fa6e3d62c13674b69dd5ef499dc02cd3e6fc834 Mon Sep 17 00:00:00 2001 From: Diao Shengjia <104132148+GoDiao@users.noreply.github.com> Date: Sun, 15 Nov 2026 14:15:37 +0800 Subject: [PATCH 1/8] docs(slides): add the slides technical design Design for a deck artifact kind: one HTML file per slide, a stage script shipped with the app, a separate Slides entry and /slides skill, templates from beautiful-html-templates, and text, reorder and delete editing. Revised after a source-backed review and after probing the key assumptions in Electron 45. PNG export moves to a hidden window for every artifact kind, because a capture larger than the webview's visible surface comes out as repeated tiles. --- docs/README.md | 1 + docs/features/artifacts/tech-design.md | 2 + docs/features/slides/tech-design.md | 672 +++++++++++++++++++++++++ 3 files changed, 675 insertions(+) create mode 100644 docs/features/slides/tech-design.md diff --git a/docs/README.md b/docs/README.md index f907457c..7925a999 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,5 +17,6 @@ - [session-links](features/session-links/tech-design.md): sessions that start other sessions and message each other. - [session-state](features/session-state/tech-design.md): session state owned by the server. - [side-chat](features/side-chat/tech-design.md): side chats, forked from a session and shown as tabs in its side panel. + - [slides](features/slides/tech-design.md): slide decks as an artifact kind (draft design). - [ui-refresh](features/ui-refresh/README.md): the UI refresh design log, mockups and checks. - [tutorial/](tutorial/README.en.md): a walkthrough of the codebase ([中文](tutorial/README.md)), also published on the website. diff --git a/docs/features/artifacts/tech-design.md b/docs/features/artifacts/tech-design.md index 79879060..837dc46c 100644 --- a/docs/features/artifacts/tech-design.md +++ b/docs/features/artifacts/tech-design.md @@ -326,6 +326,8 @@ Agent 做一个服务页面放在侧边栏展示,不算产物,不进 Artifac 幻灯片不在当前范围:清单种类、模板类别、Design 页和技能里都没有它。下面是已经做过的调研,以后再做时不必重来。 +后续设计见 [幻灯片技术设计](../slides/tech-design.md)(2026-11-15,草案)。 + - **`deck` 只是一个标签。** 从模板建出的幻灯片产物,清单里 `kind` 是 `deck`,卡片上显示种类标签,但在应用里和普通页面完全一样:没有翻页控件、大纲或演示模式。 - **按设计的导出方式只出一页。** 对 `simple-deck`(6 页)和 `html-ppt-zhangzara-raw-grid`(10 页)用导出的真实参数(`printBackground: true, preferCSSPageSize: true`)做 `printToPDF`:两个都只输出 1 页 Letter 竖版,只有第一张幻灯片的内容(PDF 里 `/Count 1`,`pdfinfo` 也是 1 页)。「幻灯片按页分页靠产物自己的打印样式」这个假设不成立。 - **open-design 的幻灯片模板翻页写法不统一。** 一种是 `section.slide` 横向滚动加脚本翻页,另一种是 `div.slide` 加 `active` 类,并靠 `@media print` 打印;各模板自带一套,没有共同结构。 diff --git a/docs/features/slides/tech-design.md b/docs/features/slides/tech-design.md new file mode 100644 index 00000000..b75a2772 --- /dev/null +++ b/docs/features/slides/tech-design.md @@ -0,0 +1,672 @@ +# 幻灯片(Slides)技术设计 + +状态:草案,2026-11-15。维护者已确认的决定列在文末「已定」;已按一轮对照源码的独立审查修订(见文末「审查后的修订」),并在真实 Electron 里验证过关键假设(见「已验证」),待最终审阅。分支 `docs/slides-tech-design`,基线 `main` 的 `ee90358d`,文中代码位置以这个提交为准。没有 PRD,目标和取舍来自维护者在对话里确认的方向。 + +## 背景 + +Artifacts 现在有两种产物:网页(`page`)和画布(`canvas`)。幻灯片在 2026-11-01 被拆出当前范围,原因写在 [Artifacts 技术设计](../artifacts/tech-design.md)的「幻灯片(以后再做)」: + +- 当时的 `deck` 只是一个标签,在应用里和普通页面一样,没有翻页、总览和演示。 +- 导出 PDF 只出第一页。 +- open-design 的幻灯片模板各自带一套翻页脚本,没有共同结构。 + +这三点的根因相同:翻页、缩放、打印由每个产物自己实现。本设计把这部分收归应用,产物只保留内容。 + +参考了两个做法(都只学结构和思路,不复制文字和代码): + +- Claude 的 Slides 类型(2026-11-15 读它的类型说明):一个索引、一份共用 CSS、每页一个只含 `
` 的 HTML 文件;画布固定 1920×1080;正文不跑脚本,另有受限的嵌入元素;用户的编辑写回 HTML。 +- [frontend-slides](https://github.com/zarazhangrui/frontend-slides)(MIT):固定舞台整体缩放;切页用 `visibility` 而不是 `display`;打印时每页一个固定尺寸的块;模板是设计说明而不是成品 HTML。 + +## 目标与非目标 + +**目标** + +- 新的产物种类 `deck`:源文件是 HTML,每页一个文件,Agent 和用户改同一份文件。 +- 应用提供舞台:缩放、翻页、分步出现、总览、演示。 +- 导出:PDF 每页一张、当前页 PNG、可独立演示的单文件 HTML。 +- 点选和评论能指明是哪一页,并给出那一页的文件路径。 +- 用户能直接改文字、调整页序、删除页,改动写回源文件。 +- 独立的 Slides 入口、`/slides` 技能和幻灯片模板。 +- Agent 侧:格式约定、静态检查、溢出检查。 +- 顺带修掉现有的问题:产物页面比面板高时,导出的 PNG 内容不对(见「导出」和「已验证」)。 + +**非目标** + +- 导出 pptx。单独评估,不在本设计里(见「备选方案」)。 +- 页面正文里运行脚本。需要脚本的内容(图表库、小演示)放进嵌入页,见「页面文件」。 +- 用户拖动元素、改样式、加元素。这些仍然交给 Agent。也不为了支持这些操作去限制页面能用的标签(见「备选方案」)。 +- 恢复被删除的页。 +- 演讲者备注和演讲者视图。 +- 4:3。只做 16:9。 +- 换页过渡效果的自定义。 +- 导入现有的 pptx。 +- 把字体打包进应用。模板的字体保持在线加载,离线时退回系统字体。 +- H5 页面里的预览,和 Artifacts 现有范围一致。 + +## 现状 + +- **产物种类**:`ARTIFACT_KINDS` 只有 `page`、`canvas`(`src/utils/artifacts.ts:13`);清单解析在 `parseArtifactManifest`(`src/utils/artifacts.ts:142`),画布用 `boards` 字段列出画板。 +- **画布的做法可以照搬**: + - 入口是内容固定的小文件,只加载随应用发布的脚本(`CANVAS_ENTRY_HTML`,`src/utils/canvas.ts:6`),`ArtifactCheck` 核对它一字不差(`isCanvasEntryHtml`,`src/utils/canvas.ts:18`)。 + - 脚本由项目协议的保留路径提供:`serveProjectRequest` 在解析项目文件之前判断 `/__dreamcoder__/` 前缀,只返回白名单里的文件(`desktop/electron/browser.ts:281-286`,白名单 `CANVAS_SHELL_FILES` 在 `src/utils/canvas.ts:4`)。目录来自主进程的 `canvasShellDir`(`desktop/electron/main.ts:137`、`:147`)。 + - 页面到渲染进程:webview 的 `console-message`,带固定前缀并校验来源脚本(`parseCanvasMessage`,`desktop/src/lib/canvasBridge.ts:26`;监听在 `desktop/src/lib/browserGuests.ts:151-156`)。处理函数按标签登记在 `canvasHandlers` 里(`:52`、`:193`),没登记的标签,消息直接丢弃。 + - 渲染进程到页面:`webview.executeJavaScript` 调脚本暴露的对象(`refreshCanvas`,`desktop/src/lib/browserGuests.ts:198`;主题用 `applyCanvasScheme`,`:178`)。 + - 写回:渲染进程收到 `move` 后调 sidecar,sidecar 读-改-写清单并返回新的修改时间,渲染进程用它更新标签记的时间(`desktop/src/hooks/useCanvasTab.ts:19-24`,`src/server/services/artifactService.ts:361`)。 +- **产物标签靠元数据识别**:产物标签是带 `root` 和 `artifact` 的 `browser` 标签,画布多一个 `canvas: true`(`desktop/src/stores/workspacePanelStore.ts:45`,设置处 `:524`)。自动刷新、导出、画布写回都只对这样的标签生效(`desktop/src/stores/artifactStore.ts:17-18`,`BrowserView.tsx:94`、`:99`)。 +- **Agent 打开的标签没有这份元数据**:`navigate` 带 `newTab` 时,渲染进程只用地址开标签(`desktop/src/lib/browserControlRequests.ts:42`)。所以 Agent 打开的产物标签现在没有自动刷新和导出,Agent 打开的画布里拖动画板也不会写回。 +- **全屏查看**对任何种类的产物都登记画布的处理函数(`desktop/src/components/artifacts/ArtifactViewer.tsx:37`),也对任何种类提供导出(`:39`)。 +- **webview 不在标签组件里**:每个 webview 放在一个全局层里的槽位元素中,盖在标签组件留出的空白区域上(槽位在 `createGuest` 里创建,`desktop/src/lib/browserGuests.ts:102-104`)。 +- **地址**:页内跳转会把标签的地址更新成当前地址(`syncPage`,`desktop/src/lib/browserGuests.ts:79-85`)。重启后重开只取地址的路径部分,`#` 后面的部分被丢掉(`resolveStoredBrowserUrl`,`desktop/src/lib/browserGuests.ts:261`)。重载用的是 `webview.reload()`(`:289-291`),重载的是 webview 当前的地址。 +- **导出**: + - 渲染进程的 `exportArtifactPage` 先暂停 Agent 设置的视口模拟,再发导出请求(`desktop/src/lib/artifactExport.ts:34-35`)。 + - PDF 用 `printToPDF({ printBackground: true, preferCSSPageSize: true })`(`desktop/electron/pageExport.ts:93`),纸张尺寸取页面自己的 `@page`。 + - PNG 在标签里的 webview 上按整页内容尺寸截取(`desktop/electron/pageExport.ts:41-52`)。探针里验证,这种截法在内容超出 webview 的可见画面时,输出的是重复的画面(见「已验证」)。 + - 独立 HTML 复制当前的 DOM,把样式表和 ` + + +``` + +`deck.css` 和设计系统的 `tokens.css` 由舞台脚本按清单加进文档,不写在入口里。这样入口永远不用改,升级只换应用里的脚本。 + +### 页面文件 + +- 每个文件只有一个根元素 `
`,前后没有别的内容:没有 ``、``、``、`
' }])).toEqual(['logo: a