Kun PPT 扩展实现深度解析：构建人与 Agent 共编的独立 HTML 演示文稿工作区

人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本文围绕 Kun 仓库中add-agent-ppt-extension变更的实现任务清单展开系统讲解presentation-studio用户可见名称Kun PPT这一 Extension API v1 示例扩展的完整落地过程从.kun-ppt.html独立文件格式与类型化操作归约器到 revision 感知的持久化服务与五个 Agent 工具再到右侧边栏可视化编辑器和回合末演示文稿产物交接。读完本文你将掌握该扩展的架构决策、数据模型、安全边界、打包验证方式以及如何在仓库中复现其构建、测试与校验流程。一、背景与目标为什么需要 Kun PPTKun 原本已能通过受管理的PPT Master工作流生成原生 PPTX 文件但缺少一个让用户与主 Kun Agent反复编辑同一份演示文稿的幻灯片工作区。proposal.md明确指出参考项目NQ PPT HTML Editor的临时 DOM 标识符、非沙箱任意 HTML 与整文档快照导出并不适合作为 Kun 的稳定扩展契约因此 Kun PPT 采用受约束的演示文稿模型而非导入该运行时。该变更的核心目标与边界见 proposal.md一份演示文稿可由人与主 Agent 共同编辑且不发生 last-writer-wins 数据丢失规范产物是可直接在普通浏览器打开的独立 HTML 演示文稿幻灯片与元素 ID 在会话与导出之间保持稳定仅使用公开的 Extension API v1.0 表面与最小权限不导入任意 HTML、不在带 bridge 的 Webview 中执行用户/Agent 编写的 JavaScript不包含 PPTX/PDF 导入导出、动画时间线、图表、多人 CRDT 或像素级 PowerPoint 兼容PPT Master 继续独立承担 Markdown → PPTX 的路径。二、Presentation Model And Projection独立 HTML 文件与类型化归约器2.1 单一.kun-ppt.html文件作为规范源每份演示文稿保存为工作区根级文件name.kun-ppt.html。文件内部是一个非可执行的application/json标记携带 schema 版本化的结构模型文件其余部分是确定性的 HTML/CSS 投影带有持久的data-kun-slide-id与data-kun-element-id属性。模型标记与投影由 presentation-html.ts 生成script idkun-presentation-model typeapplication/json…/script设计上采用单一根级文件是因为 Extension API v1.0 的 Workspace Broker无法创建目录同时避免了 JSON/HTML 双文件不一致的问题解析器只读取精确的模型标记绝不把周围任意 HTML 当作编辑器权威。投影输出在 serializePresentationHtml 中以确定性方式渲染所有文本与属性经escapeHtml转义内嵌 JSON 经escapeEmbeddedJson转义、、分别编码为\u003C、\u003E、\u0026并处理\u2028/\u2029且包含严格的内联 CSPdefault-src none; script-src none; style-src unsafe-inline; img-src self data: file:; object-src none; base-uri none; form-action none; frame-src none; connect-src none测试用例 presentation.test.ts 验证了文本中包含/scriptimg srcx onerroralert(1)时投影输出被安全转义、嵌入模型仍可解析并且相同输入两次序列化结果完全一致确定性。2.2 约束化模型有界的数据结构模型定义位于 presentation-model.ts核心结构如下PresentationProjectschemaVersion当前恒为 1、id、revision正整数、title、theme、slides数组、operationReceipts数组PresentationSlideid、title、backgroundColor可为 null回退到主题背景、elements数组PresentationElementtext / shape / image 三种判别联合公共字段为id、x、y、width、height百分比几何、rotation-180~180、opacity0~1。模型强约束硬上限汇总如下均定义在 presentation-model.ts 并写入工具输出 schema约束上限说明渲染 HTML 字节900,000单文件总大小与MAX_KUN_PRESENTATION_HTML_BYTES一致规范 JSON 字节700,000模型标记内字节幻灯片数64slides数组每页元素数128单张幻灯片的elements总元素数1,024全库元素合计单批操作数128apply/save的operations幂等回执数64operationReceipts滚动保留最近 64 条解析器 presentation-parser.ts 逐字段做严格校验ID 必须匹配^[A-Za-z0-9][A-Za-z0-9_-]*$、颜色必须是#RRGGBB统一转大写、数字必须是有限值且经Math.round(v * 10000) / 10000规整、元素几何必须保持在 16:9 画布内x width 100.0001、图片路径必须是工作区相对的 PNG/JPEG/WebP/GIF 且禁止绝对路径、反斜杠、%、..段、冒号 scheme 与控制字符。重复 ID、未知字段、缺失字段、过多回执等都会抛出带code/path/message的PresentationParseError。此外还提供stableStringify按键排序的规范 JSON与 SHA-256 摘要函数用于幂等与完整性校验。2.3 类型化操作归约器单一语义、可逆、与修订无关presentation-operations.ts 中的applyPresentationOperations是视觉编辑与 Agent 编辑共享的归约器支持 8 种操作kind语义说明document.update改标题/主题支持部分 patchslide.insert插入幻灯片可选index缺省追加slide.update改标题/背景slide.delete删除幻灯片拒绝删除最后一张slide.reorder移动幻灯片element.upsert插入或整体替换元素完整类型化元素element.style对单个元素应用受约束 CSS映射回类型字段element.delete删除元素归约器逐操作返回三件套changedIds变更涉及的 ID 去重列表、inverseOperations逆操作Webview 用它实现 undo/redo、warnings结构性/可访问性警告如空幻灯片empty_slide、图片缺alt的missing_alt_text、line 形状填充色被忽略的unused_line_fill。测试 presentation.test.ts 证明同一批操作在 revision 1 与 revision 5 上应用得到完全相同的模型revision 无关的确定性且按逆操作回放后stableStringify结果与原始模型逐字节一致可逆。无效批次如删除最后一张幻灯片会抛出PresentationOperationError且不污染源模型。三、Extension Host And Agent Toolsrevision 感知的项目服务3.1 持久化服务预期修订、串行化、幂等回执、写后验证presentation-project-service.ts 的PresentationProjectService是扩展宿主的持久化核心全部文件 IO 都通过context.workspaceWorkspace Broker完成不使用 Node 文件系统 API也没有私有 Kun 导入。其关键机制预期修订expectedRevision每次变更必须携带expectedRevision宿主先重读文件、比较修订、应用批次、修订号加一然后在写入前立即再次重读比对内容最后写入后再读回验证#writeAndVerify。修订不一致时抛出CONFLICTretryable: true绝不覆盖更新的演示文稿——失败即关闭fail closed。每路径串行化#enqueue以path.toLowerCase()为队列键同一 Extension Host 内对大小写折叠后相同的路径串行调用#enqueueMany用于导出时同时对源路径与目标路径加锁。清单中明确指出Extension API v1.0 不提供原子重命名/条件写跨进程原子性被显式延后为平台限制。幂等回执idempotency receiptsAgent 调用可省略operationId此时宿主从invocation.invocationId派生有界键成功提交后保存{ operationId, digest, resultingRevision }到滚动回执列表。若同一operationId与相同载荷重试直接返回记录的 revisionidempotentReplay: true同一operationId配不同载荷则报冲突。大小与路径前置校验路径必须匹配^[A-Za-z0-9][A-Za-z0-9._ -]*\.kun-ppt\.html$根级 ASCII 文件名最长 240操作批 JSON 不超过 256,000 字节HTML 不超过 900,000 字节见 presentation-project-validation.ts。大小写别名防护#readRawOptional通过workspace.stat 根级workspace.list(.)双重确认精确条目存在发现仅大小写不同的别名或歧义条目即报冲突列表达到 10,000 条上限时也拒绝断定目标不存在。3.2 四个 View 命令与presentation.changed消息Webview 通过ExtensionHostClient调用四个本地命令见 README.md 与 tool-contracts.ts 的presentationCommandContributionspresentation-create{ path, title? }presentation-load{ path }presentation-save{ path, expectedRevision, operations, operationId? }presentation-export-copy{ path, destinationPath, expectedRevision }create/save/export-copy 成功后宿主在presentation.changed通道发布 fail-soft 消息关闭的 View 不会把持久化写入变成失败的工具调用{ path: roadmap.kun-ppt.html, revision: 2, source: command, changedIds: [slide-agenda, element-title] }source为command或tool。Webview 端 studio-host.ts 通过decidePresentationChangepresentation-sync.ts决策动作工具来源且路径不同于当前激活路径 →follow-tool同路径且 revision 更新 →refresh-current否则忽略。若 View 打开时没有恢复的 deck会扫描根级.kun-ppt.html文件并加载最近修改的一份latestPresentationPath保证 Agent 在 View 关闭期间创建的 deck 打开后立即可见。3.3 五个窄工具与 Manifest 声明一致性安装 Kun PPT 后以下五个工具注册到 Kun 常规的 extension ToolHost 路径对主对话 Agent开放Webview 不创建、不引导、不重放 extension 自有的 Agent run且不声明 Agent profile 或agent.run权限工具sideEffectsidempotentmaxOutputBytes用途presentation-createwritefalse65,536创建不覆盖已有文件presentation-readreadtrue950,000读取结构模型与修订presentation-applywritetrue131,072应用类型化操作批presentation-validatereadtrue131,072结构/可访问性诊断presentation-export-copywritetrue65,536复制已验证修订工具声明在 tool-contracts.ts 中只定义一次presentationToolDeclarations并由 generate-manifest.mjs 经 TypeScript transpile 后生成 Manifest 的contributes.tools、contributes.commands与views.rightSidebar通过npm run check:manifest回归比对防止工具 schema、副作用分类、输出上限或 View 标题静默漂移。Manifestkun-extension.json声明的权限仅为commands.register、ui.views、webview、tools.register、workspace.read、workspace.write。3.4 让主 Agent 的实际调用更顺手设计文档 design.md 明确了几项宽容默认使模型作者Agent生成的调用保持简洁operationId可省略宿主用工具调用的有界身份派生slide.insert省略backgroundColor时规范化为null沿用 deck 主题背景text 元素可用可选的fontFamily覆盖sans/serif/monoelement.style接受与 Properties 面板相同的受约束 CSS 声明。归一化后持久化的模型始终是规范的canonical。四、Visual Presentation Studio右侧边栏的受信渲染器4.1 贡献形态与布局Kun PPT 仅以右侧边栏 Viewviews.rightSidebaridstudio图标 assets/presentation-studio.svgorder 40贡献不提供全页 Webview。编辑器提供三个聚焦标签页Slides幻灯片缩略图轨道、Canvas16:9 画布、Properties属性检查器。布局由 sidebar-layout.css 实现使用单一显式工作区行避免宿主宽度媒体查询把编辑器自动放置进短内容行后面出现空网格轨道紧凑的双行 deck 顶栏将 Load/Export 收进溢出菜单缩略图轨道在 420px 及以上宽度始终与 Canvas/Properties 并排可见360px 以下才折叠进 Slides 标签页。宿主将完整嵌入 View 标记为不可拖拽保证其控件能接收指针输入。4.2 编辑能力与交互细节studio-editing.ts 与 studio-events.ts 实现了完整的可视化工作流幻灯片新建、复制深拷贝并重生成元素 ID、删除拒绝删除最后一张、拖拽/方向键重排元素插入 text/shape/image指针拖拽移动、四角手柄缩放beginPointer/updatePointer/endPointer键盘方向键以 0.25Shift 为 1步进微调Delete/Backspace 删除选中元素内联文本编辑重复点击或 Enter 进入编辑复用已渲染的同一 HTML 文本层contentEditable plaintext-only保持字体、字号、颜色、对齐、透明背景与原文光标置于末尾且不清空、不全选Escape 取消Ctrl/CmdEnter 通过类型化操作提交两者都进入 undo/autosave 链路undo/redo基于归约器返回的 inverseOperations最多保留 100 步历史Ctrl/CmdZ / Ctrl/CmdShiftZ 快捷键预览模态对话框内逐页渲染结构化 SVG 预览左右键翻页防抖保存450ms 防抖SAVE_DEBOUNCE_MS批次满 128 条立即提交保存携带expectedRevision与派生operationId冲突时显示冲突横幅并要求 Reload绝不覆盖图像插入#image-file-picker使用系统文件选择器用户手势触发的原生 file input接受 PNG/JPEG/GIF/WebP拒绝空文件与超过 6 MiB 的文件字节以 base64 经 broker 写入碰撞安全的唯一工作区相对资产kun-ppt-deck-stem-time-nonce.ext优先复用assets/目录Webview 与保存文件都不接触绝对路径取消选择则 deck 不变。加载时经 broker 有界读取并以data:URI 缓存缺失或过大则渲染非致命占位符!/…DOM/Layers 树与安全 CSS 编辑器Properties 中列出当前页元素text/shape 对应divimage 对应img可调整层顺序CSS 编辑器presentation-css.ts只允许有界声明列表text 含color/font-size/font-weight/font-family/text-align/justify-contentshape 含background-color/border-color/border-width/border-radiusimage 含object-fit公共含position/left/top/width/height/opacity/transform长度上限 2,000 字符拒绝选择器、{}、规则、注释、URL、未知属性与超出画布的几何并将合法声明映射回类型化字段后经element.style操作提交——与直接操作、Agent 编辑共享修订检查、undo、autosave 与确定性投影。Webview 渲染全部使用createElement/textContent/经校验的样式值与 broker 加载的工作区图片构建 DOM绝不使用innerHTML注入演示文稿 HTML、不创建嵌套 iframe、不启用远程网络访问见 studio-visual.ts 与 studio-runtime.ts。视图状态路径、选中幻灯片、激活面板通过client.ui.setViewState持久化并在下次打开时恢复。五、Packaging And Documentation打包与文档落地5.1 扩展包脚本与文档package.json 提供完整开发脚本generate:manifest/check:manifest从tool-contracts.ts生成/校验kun-extension.jsontypecheck分别用tsconfig.host.json与tsconfig.webview.json检查宿主与 Webviewbuildvite build --config vite.host.config.ts构建宿主输出dist/host/extension.jsNode 20 目标、ESM、内联动态导入vite build构建 Webview根目录src/webview输出dist/webviewtest构建后运行宿主与共享模块的node --test用例并执行smoke:packvalidate/pack通过仓库的 Kun CLI../run-repository-kun-cli.mjs extension validate|pack .验证与打包.kunx归档。仓库级门禁npm run check:extension-examplescheck-extension-examples.mjs会把 presentation-studio 纳入扩展示例索引与校验枚举。示例还附有 MIT LICENSE 与 clean-room 参考说明交互词汇受 NQ-PPT-HTML-Editor 启发但未复制任何源码、运行时 DOM 快照格式、临时 ID 方案、iframe bridge、样式或资源全部基于公开 Extension API v1 与仓库 OpenSpec 工件实现详见 README.md。5.2 打包冒烟与确定性归档smoke-packed.mjs 用仓库 Kun CLI 实际执行extension pack解包归档后断言views.rightSidebar贡献为 Kun PPT、无views.fullPage、无agentProfiles、权限不含agent.run、Webview HTML 含idimage-file-picker与typefile且无旧式inline-text-editor/image-dialog、脚本含canvas-text-content/plaintext-only、图标为合法 SVG、activate可导入并注册 4 个命令与 5 个工具最后验证所有 disposables 可释放。5.3 产品打包目录与升级策略当前仓库的pack-bundled-extensions.mjsscripts/pack-bundled-extensions.mjs中presentation-studiokun-examples.presentation-studio与kun-video-editor已被列入退休retired列表当前活跃的 bundled 定义仅为kun-examples.social-media-sidebar打包脚本对归档执行确定性校验同源码两次打包的字节与 SHA-256 必须一致并在 catalog 中记录权限排序、enginesKun 与 apiVersion。任务清单中的能力描述进入产品级 bundled catalog、默认 seeding 且不覆盖显式卸载、允许仅移除过时权限的子集升级而拒绝新增权限的 bundled 更新为设计目标实际打包行为以当前pack-bundled-extensions.mjs为准开发者可显式npm run pack侧载验证源示例本身仍可完整构建与校验。六、Verification验证与回归要点任务清单第 5 区块覆盖了完整验证闭环详见 tasks.md 各条目当前仓库中可复现的部分包括类型检查与构建npm --prefix examples/extensions/presentation-studio run typecheck与build单元测试npm --prefix examples/extensions/presentation-studio run test覆盖规范化、严格校验、归约器确定性与可逆性、无效批次不突变源、可选 index 省略、HTML 转义与模型往返、安全 CSS 往返与注入拒绝、标记缺失/重复/畸形拒绝、stable stringify 与 SHA-256、回执与警告上限presentation.test.tsManifest 校验node examples/extensions/validate-manifest.mjs examples/extensions/presentation-studio/kun-extension.json及npm run check:manifest的声明一致性回归打包冒烟smoke:pack解包并激活扩展断言命令/工具注册与 Manifest 精确一致。清单中还记录了一批已完成的交互/布局回归修复继承的 Electron 拖拽区域、保留作者设定的幻灯片背景、缩略图在可用边栏宽度下与活动编辑面板并排、420–640px 窄宽度下画布不横向裁切、显式 Edit/Delete 动作、指针选择后恢复键盘焦点、重复点击内联编辑修复、键入删除与 autosave/undo 联动、系统文件选择器与取消/类型/大小处理、单 HTML 文本层在视图与编辑模式保持一致、CSS 编辑器与 DOM 层树注入防护等。仓库中的 smoke-packed.mjs 即是对其中多项的自动化落地。七、Presentation Artifact Handoff回合末演示文稿卡片7.1 产物收集与来源信任Agent 回合结束后GUI 会把成功的、限定在工作区内的.ppt、.pptx或受信任的 Kun PPT.kun-ppt.html输出渲染为去重的演示文稿文件卡片。收集逻辑位于 generated-document-artifacts.ts按平台感知的路径身份去重大小写敏感的工作区同时存在Deck.pptx与deck.pptx时保留两张卡片拒绝父目录穿越与词法外部路径.kun-ppt.html只有 provenance 来自真实 Presentation Studio 工具身份PRESENTATION_STUDIO_EXTENSION_ID kun-examples.presentation-studio见 presentation-artifact.ts且工具结果携带已验证的 SHA-256 时才作为可执行卡片发布——普通工具报告的evil.kun-ppt.html不会被当作可执行独立演示文稿浮出。7.2 打开策略与主进程校验卡片主操作复用现有editor:open-pathbridgeeditorId: system并附带presentation-artifact打开策略实现于 workspace-editor-operations.ts。主进程workspace-editor-resolution.ts将路径解析并限定在活动工作区内校验规范目标是常规文件拒绝目录/符号链接目标换后缀且后缀属于PRESENTATION_FILE_SUFFIXES [.ppt, .pptx, .kun-ppt.html]对.kun-ppt.html额外重新计算当前字节的 SHA-256 并与写入时摘要比对且大小不超过MAX_KUN_PRESENTATION_HTML_BYTES 900,000不匹配则拒绝启动浏览器并显示受限失败态Presentation changed after it was generated. Save it again in Kun PPT before opening.通过 Electronshell.openPath交给操作系统默认应用关联原生 PPTX 由 WPS/PowerPoint/LibreOffice 打开.kun-ppt.html由默认浏览器打开卡片第二动作复用文件管理器 reveal 路径。卡片仅在回合结束后渲染打开失败时保持可见并显示有界失败态与诊断日志绝不回退到任意 shell 命令extension_tool_call渐进网关包裹的写操作保留其规范工具来源与工作区写入语义result.content信封被解包。回合内多条工具结果指向同一路径时只显示一次。八、总结与上手路径Kun PPT 通过受约束 AST 类型化操作归约器 revision 感知持久化 受信侧边栏渲染器 主进程产物校验的组合实现了人与主 Agent 在同一份.kun-ppt.html上安全、无冲突地反复协作视觉编辑与 Agent 编辑共享同一语义与 undo/autosave 链路冲突失败即关闭独立 HTML 产物在 Kun 之外仍可直接播放与打印。想亲自验证的读者可按 README.md 的 Development 章节从仓库根目录执行npm --prefix examples/extensions/presentation-studio run typecheck npm --prefix examples/extensions/presentation-studio run test npm --prefix examples/extensions/presentation-studio run build node examples/extensions/validate-manifest.mjs \ examples/extensions/presentation-studio/kun-extension.json侧载并启用后右侧活动栏出现 Kun PPT 图标选择即可在边栏布局中打开 revision 感知的编辑器也可以直接在常规对话中让主 Agent 调用presentation-create/presentation-read/presentation-apply等工具创建或修改 deck。需要留意的前提Extension API v1.0 不提供原子条件写跨进程并发原子性属于平台限制operationId缺省派生、backgroundColor缺省为 null、fontFamily可选覆盖等默认让 Agent 调用保持简洁归一化后的模型始终是规范的。赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐Kun PPT基于 Kun 扩展 API v1 的人机协作演示文稿工作区实现解析Kun PPT基于 Kun 扩展 API v1 的人机协作演示文稿工作区实现解析 Kun 已经能够通过受管的 PPT Master 工作流生成原生 PPTX人工智能AI Agent自主智能体桌面应用MCP ClientsKun PPT基于 Extension API v1 的人机协同 HTML 演示文稿工作区设计解析Kun PPT基于 Extension API v1 的人机协同 HTML 演示文稿工作区设计解析 导读 Kun PPT内部扩展标识 kun example人工智能AI Agent自主智能体桌面应用MCP ClientsKun PPT 幻灯片工作区人与主 Agent 同构编辑 .kun-ppt.html 的技术实现Kun PPT 幻灯片工作区人与主 Agent 同构编辑 .kun ppt.html 的技术实现 本文以 openspec/changes/add agent人工智能AI Agent自主智能体桌面应用MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考