人工智能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 开源仓库中openspec/changes/add-work-whiteboard-surface变更包的技术指南核心围绕 Work 工作台如何把“白板”升级为与 Markdown、Office、PPTX 同级的一等公民编辑器标签页并复用既有画布引擎与 PPT 工作流投影能力。读完本文你将掌握 Work 白板的创建入口、类型化标签与布局迁移、隐藏工作区持久化、单画布写租约约束、Write 线程绑定以及 PPT 方向评审/逐页评审/QA 门禁/导出的完整闭环设计与源码实现。一、背景为什么 Work 需要一块白板Work 是 Kun 面向写作、办公文档与演示稿的一站式工作台它拥有源文档和最终 PPTX 预览但受治理约束的 PPT 工作流方向选择、逐页评审、QA 与审批此前只能通过 Code 画布宿主投影用户必须离开 Work 才能完成方向选择、批注、QA 与审批循环。该变更proposal.md的动机非常明确把白板作为 Work 内的一等公民编辑器标签页让 PPT 评审闭环在 Work 内部即可完成同时保留“白板是规划与评审面、导出的 PPTX 仍是只读预览”的既有 Office 契约。变更引入两个新能力Capabilitieswork-whiteboard-surfaceWork 白板的创建、中央标签页托管、持久化、线程归属、导航与助手共存work-ppt-whiteboard-review规范化的 PPT 工作流绑定、方向选择、逐页评审、QA 反馈、防回归投影、审批与最终 PPTX 导航。涉及面包括渲染进程的 Work 工作区 store、编辑器组/标签模型、侧边栏/开始页动作、文档面板与 Write 助手线程选择以及共享画布宿主、画布表面类型、文档持久化、选区隔离与可重放的 ShapeOps 投影。二、需求总览从 spec 看白板必须满足什么spec.md 用需求加场景Scenario的方式定义了白板表面的验收标准共 7 条需求、13 个场景是本文后续所有设计与实现的验收基线2.1 Work 暴露白板创建入口且工作区资源统一管理Work 表面必须在New file下方提供常驻的New whiteboard动作、在焦点编辑器组的添加菜单中提供New whiteboard条目并在 Work 开始页提供白板快捷入口。场景从 Work 侧边栏创建——用户选中工作区后在 Work 侧边栏激活New whiteboard系统创建持久的未命名白板并在焦点中央编辑器组中打开场景在焦点分栏组中创建——用户从编辑器组的添加菜单激活New whiteboard白板在该组内打开且不改变另一组的活动文件。2.2 白板是 Work 中一等公民的类型化标签Work 编辑器必须用区别于工作区文件路径的持久板身份board identity来表示白板并将其作为中央标签与文件标签并列展示。场景在源文档旁打开白板——打开与 Markdown 文档关联的白板时两者以独立标签出现文件的加载与保存不会把白板身份当作文件路径处理场景恢复编辑器布局——Work 重载包含文件与白板标签的持久化布局时恢复有效标签、活动项、焦点组与分栏方向。2.3 白板作为隐藏工作区资源持久化系统必须将白板元数据与画布文档持久化到 Kun 自有的工作区目录并把该目录从普通 Work 文件树中排除。场景应用重启后重新打开——用户命名并编辑白板后重启应用其标题、形状、视口、源关系与助手线程绑定全部恢复场景浏览工作区文件——Work 渲染工作区文件树时Kun 自有的白板元数据与画布 JSON 文件不得作为用户文档显示。2.4 白板与 Work 助手共存系统必须在中央编辑器区域渲染焦点 Work 白板同时在右侧面板保留 Work 助手。场景评审板打开时打开助手——白板标签激活且用户打开 Work 助手时白板保持挂载在中央助手在旁打开。2.5 白板拥有持久的 Write 线程每个白板必须用其板身份绑定一个 Write 线程并在无活动文件时聚焦白板也保留该线程。场景从白板发送提示词——焦点项是白板且用户发送 Work 助手提示词时提示词使用白板绑定的 Write 线程并包含当前画布上下文。2.6 可写画布不能跨编辑器组竞争在画布 store 成为按文档键控document-keyed之前应用必须在每个窗口最多挂载一个可写的 Work 画布。场景两个组都含白板标签——分栏布局在两个编辑器组中各引用一块白板时只有焦点组拥有可写画布另一组呈现安全的激活入口且不持久化画布状态。三、总体设计七个关键决策design.md 给出了实现这组需求的七个决策它们共同决定了白板在 Work 中的身份、存储、托管、线程、事件路由与授权模型。决策一把 Work 标签建模为类型化编辑器项编辑器布局从纯文件path标签演进为带稳定键的类型化项type WorkEditorItem | { kind: file; path: string } | { kind: whiteboard; boardId: string }持久化的纯文件 v1 布局会被归一化为类型化项。白板不使用伪文件 URL因为那会污染文件加载、监听、保存、最近文件与 Office 预览行为。仓库实际类型见 write-workspace-store-types.ts 的WriteWhiteboardTabkind: whiteboardboardIdviewMode: rich以及WriteEditorItem WriteEditorTab | WriteWhiteboardTab | WritePaperViewTab联合类型。标签键tab key由 write-editor-layout.ts 统一生成白板标签键为whiteboard:boardId文件标签键为文档键另有writeWhiteboardIdFromTabKey反向解析isWriteVirtualTabKey用于识别不指向磁盘文件的无文档表面确保文件监听与保存逻辑不会触碰白板键。决策二白板元数据与画布文档分离存储Work 白板元数据存于工作区本地注册表画布文档单独存放。以源码为准实际目录常量定义在 work-whiteboard.tsexport const WORK_WHITEBOARD_DIR .kun-whiteboards export const WORK_WHITEBOARD_INDEX ${WORK_WHITEBOARD_DIR}/index.json即.kun-whiteboards/index.json版本化注册表WorkWhiteboardRegistryV1含version: 1与whiteboards数组.kun-whiteboards/boardId/canvas.json每块白板的画布文档。注册表加载loadRegistry区分四种结果valid/missing/invalid/unavailable其中missing表示目录尚未初始化invalid表示目录存在但索引无法读取或解析二者在 work-whiteboard.ts 中通过listWorkspaceDirectory检查目录是否存在来区分。持久化则通过writeDesignWorkspaceFile/createWorkspaceDirectory/createWorkspaceFile等既有设计工作区 API 完成画布文档解析与持久化保持共享。决策三在焦点中央组托管唯一 Work 画布WorkWhiteboardSurface组合CanvasViewport、PropertiesPanel与既有 live ShapeOps 投影器并以surfacework运行。只有焦点白板标签可以挂载可写视口打开另一块白板会激活它分栏组中的非焦点白板展示不可编辑的交接占位handoff placeholder而不是挂载第二个 store 拥有者。决策四把助手线程绑定到 Work 工件Write 线程注册表在文件键之外新增工件键。焦点白板用whiteboard:boardId解析或创建线程并保留agentSurface: write。活动 Work 上下文区分file与whiteboard同时为 PPT 提示词保留可选的源文件。决策五把画布打开事件改为携带目标原来无参数的画布打开事件升级为携带目标target-bearing的事件PPT 捆绑路由包含父 Write 线程与工作流身份在 Work 中原子地查找或创建规范绑定板、投影捆绑、激活或通知其标签在 Code 中保持原行为。工具块 ID 加 PPT 工作流、子、版本与阶段共同构成重放键重复收到同一捆绑时替换或确认当前投影而不是追加重复。决策六PPT 权威性保持在白板之外方向卡片、逐页预览、批注与 QA 标记都是受治理 PPT 工作流的投影移动形状仅影响视觉呈现。方向采用、版本修订、页面修复与审批通过结构化引用回传给同一 PPT 子代理。导出的 PPTX 仍是 Work 中的只读预览白板作为评审记录保留。决策七一个常驻入口加两个上下文入口主入口是 Work 侧边栏New file正下方的New whiteboard行焦点组菜单与 Work 开始页提供上下文次级入口。演示类动作创建或复用评审板而不是创建无上限的重复板。四、白板领域模型与持久化实现4.1 白板元数据字段WorkWhiteboard类型定义在 write-workspace-store-types.ts字段类型含义idstring持久板身份与文件路径无关titlestring白板自己的规范显示标题workspaceRootstring所属工作区根threadIdstring \| null当前绑定的 Write 线程threadIds?string[]有序的 Work 会话历史旧板可能缺失sourcePath?string关联源文件如 PPT 提示词的 MarkdownworkflowId?string绑定的 PPT 工作流身份childId?string绑定的 PPT 子代理身份outputPath?string导出的 PPTX 输出路径phaseblank \| directions \| review \| complete工作流阶段revisionnumber当前修订号createdAt/updatedAtstringISO 时间戳engine?CanvasEngine画布渲染引擎缺失表示遗留 Kun 画布4.2 板身份与标题规范work-whiteboard.ts 定义了严格的归一化规则板 ID/^[a-zA-Z0-9_-]{1,64}$/默认由board-timestamp36-random36生成uniqueBoardId标题normalizeWorkWhiteboardTitle统一规则——trim、非空、最多 160 字符线程workWhiteboardThreadIds去重并截断到MAX_WORK_WHITEBOARD_THREAD_IDS 20阶段只接受directions/review/complete否则归为blank修订非负整数否则为 0。4.3 注册表 CRUD 动作createWorkWhiteboardActionswork-whiteboard.ts为 Zustand store 提供了一组完整动作loadWhiteboards(workspaceRoot)加载注册表valid时写入 storeinvalid/unavailable时设置fileErrorcreateWhiteboard(workspaceRoot, options)校验标题与可选 ID构造板并先持久化注册表、后打开标签任何写回失败都会回滚内存状态openWhiteboard(boardId, groupId?)在目标组默认焦点组添加kind: whiteboard标签项、持久化布局、清理 Office 选区并投影焦点文档renameWhiteboard/setWhiteboardEngine/deleteWhiteboard更新注册表并同步标签布局删除时还会调用cancelPendingCanvasDocument与deleteDesignWorkspaceEntry清理画布文档目录findOrCreatePptWhiteboardPPT 工作流的规范板查找/创建——按threadId workflowId找规范板子身份不匹配时拒绝创建第二块规范板子身份不可变findOrCreateExcalidrawWhiteboardExcalidraw 引擎板的查找/创建支持按boardId或按线程绑定查找并处理引擎锁定与线程绑定bindWhiteboardThread/forgetWhiteboardThread线程绑定与解绑PPT 规范板绑定后不可重绑updateWhiteboardPptState阶段与修订更新——方向与评审修订是独立计数器延迟到达的方向结果不会抬高评审修订水位work-whiteboard.ts。4.4 布局恢复与文件操作隔离持久化布局WriteEditorLayoutV1包含orientationsingle/horizontal/vertical、ratio、focusedGroupId与groups。v1 纯文件布局在解析时被归一化为类型化项且只有在解析成功后才持久化新版本对应风险清单中的“布局持久化迁移可能丢标签”。隔离逻辑有专门测试验证write-workspace-whiteboard-file-isolation.test.ts 证明常规文件被重命名/删除时白板元数据与标签保持完好write-workspace-whiteboard-restore.test.ts 则验证“先加载白板元数据、再恢复类型化白板标签”的顺序重启后标题、阶段、修订与线程绑定全部还原。五、创建入口与开始页/侧边栏 UX5.1 侧边栏常驻入口Work 侧边栏WriteSidebar.tsx在New file下方渲染New whiteboard创建行文案键writeCreateWhiteboard默认值New whiteboard。创建流程采用“先标题、后持久化”的对话框式设计useWorkWhiteboardCreationuse-work-whiteboard-creation.ts中openNewWhiteboardDialog先校验工作区根未选择工作区时先引导打开工作区submitNewWhiteboardTitle调用 store 的createWhiteboard传入标题与可选引擎创建成功后才关闭对话框。侧边栏内白板区由WorkWhiteboardSidebarSection管理测试WorkWhiteboardSidebarSection.test.ts覆盖了三类行为空白板文件夹保持可见并支持创建、按最近更新排序且折叠时隐藏子项、打开板后保留重命名与删除菜单动作。5.2 焦点组添加菜单与开始页焦点编辑器组的菜单WriteEditorTabBar.tsx提供New whiteboard条目目标组即当前焦点组符合“不改变另一组活动文件”的场景Work 开始页WriteWorkspaceStart.tsx同样渲染New whiteboard快捷入口并有关联测试 WriteWorkspaceStart.test.ts 断言其存在。六、中央画布表面WorkWhiteboardSurfaceWorkWhiteboardSurfaceWorkWhiteboardSurface.tsx是白板表面的核心组件根据writable属性与引擎类型分派到三种渲染形态6.1 可写板的单画布租约function WritableWorkWhiteboard(props: WorkWhiteboardSurfaceProps): ReactElement { const ownerId useId() const [ownsLease, setOwnsLease] useState(false) useLayoutEffect(() { let cancelled false setOwnsLease(false) void flushPendingCanvasDocuments(props.workspaceRoot).then(() { if (!cancelled) setOwnsLease(claimWritableWorkCanvas(ownerId, props.boardId)) }) ... }, [ownerId, props.boardId, props.workspaceRoot]) ... }挂载前先 flush 未决画布文档再通过claimWritableWorkCanvas(ownerId, boardId)尝试获得窗口级单例写租约租约被其他板占用时返回InactiveWorkWhiteboard带“另一块白板正在编辑中切换到这里后继续”的提示与激活按钮而不是挂载第二个可写视口。卸载时释放租约。租约实现在 work-canvas.ts其注释明确说明画布 store 是单例 Zustand store该租约防止两个 Work 编辑器组挂载可写视口、把同一份内存文档写入不同的板路径。6.2 Kun 画布表面CanvasViewport PropertiesPanel live ShapeOpsMountedWorkWhiteboard组合了三件套CanvasViewport以surfacework、baseDirWORK_WHITEBOARD_DIR渲染画布PropertiesPanel以surfacework显示属性面板useApplyShapeOpsLive以work表面订阅并重放 PPT 捆绑的 ShapeOps。关键状态判断work-canvas.tsworkCanvasHasBlockingQaNotes当前文档是否存在阻断级 QA 批注用于审批禁用workCanvasHasCompletePptReviewProjection评审投影是否完整评审阶段审批的前置条件workCanvasPptSelectionState当前选区是否命中方向卡片 / 页面卡片驱动“采用选中方向”“修改选中页”按钮的可用性。画布身份由resolveWorkCanvasIdentity(workspaceRoot, boardId)解析为artifactId baseDir designSystemBaseDir documentKey errorKeydocumentKey保证画布 store 的文档与当前板严格对应workCanvasPptWorkflowGate为无工作流绑定的普通板生成__unbound-work-board__:boardId门控标识防止未绑定板误接 PPT 投影。6.3 阶段化动作与 PPT 闭环面板底部动作随phase变化REVIEW_ACTIONS定义于 WorkWhiteboardSurface.tsxdirections 阶段重新生成方向、采用选中方向并继续未选中时退化为“采用推荐方向并继续”review 阶段修改选中页需先选页面卡片、通过并导出需评审投影完整且无阻断 QAcomplete 阶段显示打开 PPTX按钮经onOpenOutput导航到只读 PPTX 预览。动作按钮把结构化中文提示词通过onRequestAssistant发回 Write 助手线程从而把“方向采用 / 页面修复 / 审批导出”结构化回传给同一 PPT 子代理体现“PPT 权威性在白板之外”的决策六。顶部状态条同时展示标题、阶段徽标与源文件并支持 Kun/Excalidraw 双引擎切换仅空白板可切换PPT 板固定 Kun 引擎见 work-whiteboard.ts 的workWhiteboardEngineLocked。6.4 Excalidraw 引擎板ExcalidrawWorkWhiteboard通过useApplyExcalidrawLive与ExcalidrawSurface提供 Excalidraw 草图能力同样以surface: write、baseDir: WORK_WHITEBOARD_DIR持久化并与 Work 助手线程联动。6.5 提示词画布快照work-canvas.ts 的snapshotWorkCanvasForPrompt负责把当前板纳入助手上下文若 store 文档键与板身份匹配则直接快照内存文档否则回退读取持久化画布文档绝不让另一块挂载画布的单例 store 状态泄漏进提示词。这保证了分栏场景下后台板的提示词仍可用。七、PPT 评审集成目标化事件路由与规范板复用7.1 从 Code 专属到目标化路由workbench-ppt-whiteboard-routing.ts 实现了决策五的目标化路由。pptCanvasOpenRequestForBlock从ppt_agent工具成功块中解析 direction/review bundle 与 deck artifact抽取workflowId / childId / phase / revision / outputPath作为捆绑身份在route write时输出{ target: write, ... }的WorkCanvasOpenRequestDetail否则保持{ target: code, ... }。routePptCanvasOpenRequest按目标分发Code 走openCodeWork 走openWork。7.2 规范板查找与幂等重放Work 侧的findOrCreatePptWhiteboard保证一个 PPT 工作流对应一块规范评审板按threadId workflowId定位childId不匹配时拒绝复用并拒绝创建第二块标题优先级为“主代理 UI 标题 结构化 deck 标题 源文件派生标题”。重放键由工具块 ID 工作流 子 修订 阶段构成重复收到同一捆绑时替换/确认投影而非追加配合updateWhiteboardPptState的修订高水位逻辑实现幂等。7.3 延迟回执补水设计风险中明确提到“捆绑处理依赖 Code 画布钩子挂载”因此实现将目标解析前置于投影并在 Work 板激活时补水rehydrate未决回执——handlePptProjectionOpenRequested在请求投影后flushPendingCanvasDocuments并同步updateWhiteboardPptState保证方向/评审结果到达时正确落板。八、迁移与回滚design.md 的迁移计划分五步增加向后兼容的布局与白板元数据解析v1 纯文件布局归一化为类型化项在存在有效工作区根的前提下发布新 Work 表面与创建入口重定向 PPT 画布打开事件同时保留 Code 行为验证重载、重连、工作区切换与重复 SSE bundle回滚安全移除 Work 入口与目标路由即可已有.kun-whiteboards数据保持隔离可随时重新启用。tasks.mdtasks.md显示五组共 17 项任务已全部完成覆盖类型化编辑器项与布局归一化、版本化元数据与注册表 CRUD、线程绑定恢复、中央画布宿主CanvasViewport PropertiesPanel 持久化守卫、单画布写租约与分栏交接状态、标签全生命周期渲染/激活/移动/关闭/恢复/重命名/删除不触发文件监听与文件保存、三处创建入口、文件树隐藏 Kun 自有目录、PPT 目标化路由、规范板复用、方向/评审投影与重放守卫、结构化方向采用/修订/修复/QA 门禁/审批/PPTX 导航、助手发送携带画布快照以及对应的单元/组件/集成测试与类型检查、构建验证。九、测试与验证体系白板功能拥有一套完整的验证体系可作为读者继续深入仓库的入口布局迁移与恢复write-workspace-whiteboard-restore.test.ts先加载元数据再恢复标签、write-workspace-whiteboard-file-isolation.test.ts文件操作不触碰白板线程与对话work-whiteboard-session-title.test.ts、work-whiteboard.test.ts、chat-store-thread-actions-whiteboard.test.ts创建入口与表面WorkWhiteboardSidebarSection.test.ts、WorkWhiteboardSurface.test.ts、WriteWorkspaceStart.test.ts、use-work-whiteboard-rename-live.test.tsPPT 路由workbench-ppt-whiteboard-routing.test.ts。运行方式遵循仓库既有流程在 kun/README.md 所述环境就绪后于渲染进程目录执行vitest相关命令运行上述聚焦套件即可具体脚本见 kun/package.json。十、小结Work 白板表面是 Kun 在“规划与评审面”上的一次完整落地它以类型化编辑器标签让白板与文件平级、以.kun-whiteboards隐藏工作区存储实现重启恢复、以单画布写租约规避单例 store 竞争、以工件线程绑定保持助手上下文、以目标化 PPT 路由与规范板复用把方向评审/逐页评审/QA/审批/导出闭环收拢到 Work 内部。对希望扩展 Work 工作台、理解画布宿主复用或复用 PPT 投影契约的开发者而言spec.md 是验收契约、design.md 是设计决策、WorkWhiteboardSurface.tsx 与 work-whiteboard.ts 则是可直接参考的实现范本。赞分享人工智能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点击查看免费下载相关推荐Codewhale 模式与权限姿态完全指南Plan / Work / Operate、审批循环与持久化机制Codewhale 模式与权限姿态完全指南Plan / Work / Operate、审批循环与持久化机制 CodewhaleRust 编写的终端开源编码人工智能AI Agent代码智能体CLI工具调用MCP ClientsDeepSeek Harness 持久化 pwsh在 Windows 上落地一等公民的持久终端 ShellDeepSeek Harness 持久化 pwsh在 Windows 上落地一等公民的持久终端 Shell 导读 deepseek harness Ever人工智能AI AgentAgent 框架DeepSeekMeson 0.59.0 新特性全解析从 pkgconfig 转义到 Cython 一等公民支持Meson 0.59.0 新特性全解析从 pkgconfig 转义到 Cython 一等公民支持 导读 本文以 Meson 0.59.0 的官方发布说明为主体构建工具上一篇danmu源码解析深入理解Python直播弹幕抓取的实现原理下一篇React Native Material Dropdown与Formik集成构建高效表单验证系统的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考