人工智能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/harden-write-design-health变更提案展开讲解 Write 模式写作工作区与 Design 模式设计工作区在数据一致性与持久化健壮性上的加固方案。此前Write 模式的异步操作可能把迟到的文件读取、保存完成、Agent 评审、AI 改写或剪贴板图片结果应用到“更新”的文档上下文上Design 模式则存在持久化失败被当作成功、全局状态跨工作区泄漏、解码图片无内存上限、持久化 Canvas 图被递归遍历前未校验等问题。读完本文你将掌握 Kun 引入的显式文档身份epoch/revision、按工作区与文件串行化的保存协调器、字节感知 LRU 图片缓存、按工作区隔离的 hydration 追踪以及迭代式 Canvas 图校验等核心机制并能在源码与测试中定位对应实现。变更背景两类缺陷的根源Write 模式虽然只有一个活动文档 Zustand store但其持久化基线是模块级全局的异步操作之间没有共享的文档身份。于是出现一系列“迟到结果覆盖新上下文”的缺陷迟到的文件读取覆盖新打开文件、旧的保存完成把新内容标记为已保存、Agent 评审落在错误文件、AI 富文本改写作用到切换后的文档、剪贴板图片插入到新文档等。最大的一块编排组件同时负责持久化、文件监听、编辑、导出与生成生命周期导致这些不变式难以测试。Design 模式在项目DESIGN.md上下文围栏、预览监听、SVG 准备上已有较强约束但持久化路径仍不一致直接 IPC 写入分散在各 store 与面板、多个调用方忽略了已解析的失败结果、防抖写入器无法全部 flush、hydration 会话标记是全局的、解码后的图片字符串无限留存、持久化 Canvas 图在递归遍历前被直接信任。因此本次变更的目标是把活动 Write 文档变成显式身份把保存按文件串行化让所有 Write 评审/AI/图片粘贴完成都上下文安全为 Design 持久化建立统一的“可检查、有序”写入原语并 flush 所有防抖持久化源让 Design 持久化失败可见为解码图片内存设上限并隔离 hydration 追踪在递归消费者看到 Canvas 图之前拒绝畸形或循环图并把高风险的 Write 编排逻辑从WriteWorkspaceView中抽出配上确定性回归测试。新增能力总览本次变更新增两项能力write-workspace-integrity保证文件导航、保存、评审、AI 改写与剪贴板图片补全不能修改不同或更新的 Write 文档上下文design-workspace-durability保证 Design 持久化可检查、可 flushhydration 状态按工作区隔离图片内存有界持久化 Canvas 图结构有效。对既有能力没有修改。影响范围限定在渲染进程Write 工作区 store、文件动作、编辑器编排、CodeMirror 与 TipTap 图片粘贴路径及相关测试Design 工作区 store、文档/artifact/canvas/design-system 持久化、导出面板、图片解析、hydration、Canvas 解析及相关测试。Electron IPC schema 保持兼容调用方将更严格地处理既有结果联合类型不涉及外部 HTTP 或 Kun 运行时协议变更。Write 文档身份epoch 与 content revision显式文档上下文三元组Write store 现在拥有documentEpoch、contentRevision与persistedContent。打开、清空、重命名离开或切换活动文档会使 epoch 前进本地内容变更使 content revision 前进。所有异步操作捕获{ workspaceRoot, filePath, documentEpoch }在变更活动状态前必须与之匹配。实现上write-document-context.ts 定义了WriteDocumentContext类型与三个纯函数captureWriteDocumentContext(state)从当前状态抓取归一化后的工作区根、活动文件路径与 epochwriteDocumentContextMatches(state, context)逐一比较三个字段是否一致nextWriteDocumentEpoch(current)单调递增 epoch并对非安全整数回退到 1。路径归一化统一为trim().replaceAll(\\,/).replace(/\/$/,)避免 Windows 与 POSIX 路径写法差异造成误判。选择 epoch 而非仅路径判断是因为用户可能离开一个文件后又重新打开同一路径旧操作仍在挂起选择 epoch 而非单纯 AbortController是因为 Electron IPC 与已开始的磁盘写入不一定能取消。迟到文件打开不再覆盖要求“活动 Write 文档身份”覆盖两类典型场景迟到 file-open 响应文件 A 先开始打开、文件 B 后开始打开但 A 最后返回——B 必须保持活动A 的响应不得覆盖其内容或状态重开同一路径针对某文件的操作开始时用户离开该文件、之后重开同一路径——由于 document epoch 不同旧操作必须视为过期。从源码看store 在打开流程末尾通过nextWriteDocumentEpoch(state.documentEpoch)推进 epochwrite-workspace-store.ts任何异步完成回调都要先过writeDocumentContextMatches这关。保存协调按工作区/文件串行化与 revision 安全保存队列的实现write-save-coordinator.ts 用两个模块级 Map 实现串行化saveQueues以workspaceRoot \0 path为键的 Promise 链同一文件的写入操作依次排队互不交错pendingSaveContents记录每个键当前排队/在途的content - 出现次数供 watcher 判断本地保存回声。对外暴露的 API 包括enqueueWriteWorkspaceFileTask(workspaceRoot, path, operation)把任意读-改-写任务与普通保存串行化供信息图占位符解析等后台任务使用避免与 autosave 竞争enqueueWriteWorkspaceSave(payload)排队一次真实写盘默认走window.kunGui.writeWorkspaceFileisWriteWorkspaceSaveContentPending(workspaceRoot, path, content)watcher 用它抑制本地文件系统回声同时不把真正的外部编辑误判为助手差异flushWriteWorkspaceSaveQueue(workspaceRoot?, path?)等待某个文件或全部队列落定。选择“按文件串行化”而非单一全局队列是为了让互不相关的工作区/文件不互相阻塞。flushSave 的 revision 感知循环store 的flushSavewrite-workspace-store.ts实现了“revision 安全”语义先await flushWriteWorkspaceSaveQueue(context.workspaceRoot, context.filePath)等待同文件旧写入落定重新读取状态若上下文已不匹配则直接返回不污染新文档若等待期间状态变化则基于最新persistedContent重新评估写入时捕获content与contentRevision只有writeDocumentContextMatches(current, context) current.contentRevision revision时才把状态置为saving写入成功且上下文仍匹配时仅当current.fileContent content才置saved否则保持dirty并进入下一轮循环——也就是说保存期间产生的新内容不会被旧完成标记为已保存且导航 flush 会继续写最新 revision写入抛出异常或返回ok: false时仅在上下文匹配的前提下置error状态与fileError返回false导航不得将其视为已持久化。这直接覆盖了提案中的三类场景编辑时保存挂起revision 1 保存中创建 revision 2revision 1 完成不得标记 revision 2 已保存、保存挂起时切换文件文件 A 的保存完成后不得改动文件 B 的持久化基线/错误/保存状态、排队的写失败ok: false或抛错时原文档保持 dirty 或 error另一文档保持不变。Agent 评审与编辑器异步动作的上下文绑定挂起的 Agent 评审现在携带 workspace、path 与 document epoch只允许在匹配的编辑器文档上打开。use-write-workspace-lifecycle.ts 暴露了两个纯谓词pendingWriteAgentReviewMatches(state, review)评审是否仍属于当前活动文档canApplyPendingWriteAgentReviewDirectly(state, review)评审匹配且saveStatus saved时才可直接套用。评审消费逻辑分三档上下文不匹配则清除评审并退出匹配但无法直接套用例如富文本模式没有行级 diff 界面时保留 dirty/error 草稿、设置外部变更冲突错误并暂停后台 autosave只有显式 Save 才能在冲突中选择本地草稿匹配且安全时才把nextContent写入文件并结束评审。若评审消费瞬间再次校验发现上下文已过期则立即放弃。富文本/源码内联编辑、信息图补全以及 CodeMirror/TipTap 剪贴板图片插入同理每个任务在启动时抓取{ workspaceRoot, filePath, documentEpoch }结果应用前必须同时满足上下文匹配与既有内容/范围前置条件。paste-image.ts 中可见图片持久化任务在启动时通过options.getDocumentEpoch()抓取 epoch应用前以writeDocumentContextMatches校验。过期任务可以为原文件完成外部工作但绝不能编辑当前编辑器——即使用户在文件 B 中也能选中同样的文本来自文件 A 的富文本改写也不会套用到文件 B剪贴板图片持久化完成后若活动文档已变化图片不会被插入新文档。生命周期收敛useWriteWorkspaceLifecycle抽出最大的编排组件WriteWorkspaceView不再直接拥有 autosave、卸载 flush、文件监听与挂起评审消费这些已收敛到useWriteWorkspaceLifecyclehook 与保存协调器autosave仅当autoSaveEnabled saveStatus dirty workspaceReady activeFileIsText !readOnly !reviewActive时启动防抖定时器到期调用flushSave(workspaceRoot)卸载 flush组件卸载清理定时器并在 autosave 仍开启时调用一次flushSave(workspaceRoot)挂起评审消费见上文上下文绑定的评审处理文件监听结合isWriteWorkspaceSaveContentPending抑制本地回声。配套的use-write-workspace-lifecycle.test.ts覆盖生命周期谓词与竞态路径。目标是显著减少混合生命周期职责而不是追求任意的行数重写——导出与编辑 UI 仍留在视图内除非搬动它确实能改善被强制的不变式。Design 持久化可检查、有序、可 flush统一协调器design-persistence-coordinator.ts 是 Design 侧写入/删除的统一入口normalizeDesignPersistenceWorkspaceRoot/operationKey以workspaceRoot \0 path为键做按路径串行化writeDesignWorkspaceFile(payload)/deleteDesignWorkspaceEntry(payload)内部把抛出的异常与解析后的{ ok: false }统一归一化为可检查结果并通过publishFailure通知注册的失败处理器默认走window.kunGuisetDesignPersistenceFailureHandler(handler)注册失败处理器flushDesignPersistenceQueue(workspaceRoot?)循环等待指定工作区或全部队列落定供生命周期收尾使用。失败必须可见要求“可检查的 Design 持久化”包含三类典型场景导出解析为失败Design 契约、互操作包或报告写入返回ok: false时UI 必须显示错误不得展示导出成功状态初始 board 写入失败初始 Canvas 文件写不成功时store 不得为缺失文件注册持久化的 board artifact后台持久化失败文档索引、artifact 元数据、Canvas 或 design-system 持久化失败时活动工作区要收到可观察的持久化错误同时保留可恢复的内存状态。渲染进程通过 design-workspace-lifecycle.ts 的registerDesignPersistenceFailureHandler把失败事件路由到活动工作区先归一化比对工作区根命中后把Failed to operation path: message写入fileError。防抖写入与 flush文档索引、Canvas、design-system 三类防抖写入都保留了挂起 payload并提供工作区作用域的 flush 函数。聚合入口flushDesignWorkspacePersistence(workspaceRoot?)design-persistence-flush.ts依次执行flushPendingDocumentsIndexes(workspaceRoot)flushPendingCanvasDocuments(workspaceRoot)flushPendingDesignSystems(workspaceRoot)flushDesignPersistenceQueue(workspaceRoot)。flushAndReleaseDesignWorkspace与afterFlushingDesignWorkspace在 Design 生命周期收尾/工作区切换时调用该 flush保证卸载时所有防抖持久化 payload 都提交到有序队列且队列可 flush。Canvas 持久化canvas-persistence.ts的persistCanvasDocument采用 600ms 防抖按 key 保留最新 payload旧完成不得覆盖最新 payloadcancelPendingCanvasDocument用于白板删除场景把 key 永久退役并等待已交到协调器的写入防止已删除目录被重建。Design 资源与工作区隔离字节感知 LRU 图片缓存解码后的工作区图片 Data URL 缓存在CanvasImageDataUrlCachecanvas-image-source.ts双上限DEFAULT_IMAGE_CACHE_MAX_BYTES 64 * 1024 * 102464 MiB 字节预算、DEFAULT_IMAGE_CACHE_MAX_ENTRIES 128条目上限构造时可注入字节估算dataUrlByteSize对 base64 载荷按len * 3/4 - padding估算解码字节对非 base64 按len * 2估算LRU 语义get命中刷新 recencyset插入时若超过条目数或字节预算则从最旧条目逐出工作区作用域清理clear(workspaceRoot?)可按工作区释放条目stats(workspaceRoot?)返回条目数与字节数便于测试与诊断单条图片超过预算时直接不入缓存失败的读取不缓存。选 LRU 而非无缓存是因为 canvas 重绘会重复昂贵的 IPC/base64 转换只做条目数限制不够因为允许的图片体积差异极大。按工作区隔离的 hydration 追踪design-workspace-registry.ts 用有界的、按归一化工作区根键控的注册表替换了全局 hydration 追踪集合MAX_TRACKED_WORKSPACES 8、MAX_IDS_PER_BUCKET 2048超限时淘汰最旧条目markDesignArtifactRemoved/markDesignDocumentRemoved/markDesignDocumentUserCreated及其was*查询按工作区隔离clearDesignWorkspaceRegistry(workspaceRoot?)支持整体或按工作区清理。hydration 同时引入 generation 围栏hydrate 开始时捕获 generation 与工作区根每次状态提交前同时校验 generation 与工作区根见 design-workspace-store.ts 中generation workspaceGeneration 归一化根匹配的判断。工作区 A 开始 hydration 后切到 B、A 稍后完成时A 的文档与 artifact 不得提交进 B 的状态同一 identifier 在 A 中被删除时B 中同 identifier 的条目仍保持可 hydration。切换 Design 工作区会重置投影/瞬态状态、使上一 generation 失效、清空瞬态 canvas/图片状态并从新根开始。Canvas 文档结构安全迭代校验与 v1 迁移校验规则与常量持久化 Canvas 文档只在对象图有限、有界、有根、无环、内部引用有效且与父指针一致时才被接受。canvas-persistence.ts 定义了四个上限常量MAX_CANVAS_DOCUMENT_OBJECTS 10_000文档对象总数上限MAX_CANVAS_CHILDREN_PER_SHAPE 4_096单个形状子节点数上限MAX_CANVAS_GRAPH_DEPTH 512图深度上限防递归栈溢出MAX_CANVAS_POINTS_PER_SHAPE 20_000单个形状点数上限。validateCanvasDocumentGraph(objects, rootId)迭代式显式栈非递归校验对象数非空且不超限根存在且parentId null逐节点校验子节点数、子节点存在、子节点parentId指向父节点、子节点未被重复引用、无环、深度受限最后要求从根可达的对象数等于对象总数即根可达、无孤儿。parseCanvasDocument(raw)的完整流程JSON 解析失败返回null版本仅接受 1 或 2objects必须是非空对象且数量不超限逐形状用parseShape做有限几何校验x/y/width/height/rotation/opacity/fontSize/fontWeight/lineHeight/cornerRadius/points等数值必须是有限数子节点/点数组长度受限随后validateCanvasDocumentGraph通过后才允许递归消费者看到该文档。畸形图全部拒绝提案要求以下情形解析必须拒绝且不得递归栈溢出环直接或间接子环——显式栈 visited集合天然防死循环缺失/重复/多父/父指针不一致的子节点子节点 id 缺失、同一父下重复、被多个父引用、或与parentId不一致均返回null不可达或深度/数量超限根不可达全部对象、图深度超过 512、对象数超过 10_000、子节点数超过 4_096 均拒绝有限几何非有限数值直接拒绝。v1 → v2 坐标迁移保持兼容v1 文档把 frame/group 子节点的x/y存为相对父节点的坐标旧渲染器把子节点嵌套在父变换内v2 存绝对坐标。flattenCoordinatesToAbsolute用显式栈迭代地把每个非根形状的坐标改写为自身坐标累加祖先偏移后的绝对坐标视觉位置保持不变。因此结构合法的 v1 文档加载后坐标被迭代迁移返回的文档对 v2 消费者保持兼容迁移发生在图校验通过之后。回归覆盖与验证本变更的所有不变式都有确定性回归测试。Write 侧write-workspace-store.test.ts、write-document-context.test.ts、write-editor-group-actions.test.ts、use-write-workspace-lifecycle.test.ts覆盖乱序打开、保存中编辑、跨文件保存完成、过期评审、过期富文本改写、过期图片粘贴Design 侧design-persistence-coordinator.test.ts、design-workspace-store.test.ts、design-workspace-isolation.test.ts、canvas-image-source.test.ts、canvas-persistence.test.ts、design-document-persistence.test.ts覆盖解析失败/抛错失败、按路径排序、防抖 flush、导出失败 UI、board 回滚、LRU 逐出、工作区缓存清理、同 ID 工作区隔离、迟到 hydration 拒绝、缺失/重复/多父/父指针不一致/环/不可达/深度与数量/有限几何等畸形图以及合法 v1 迁移。验证记录verification.md确认全部要求通过质量门槛包括npm run typecheck、npm run test460 个测试文件、3676 个测试通过、npm run lint、npm run build:kun与npm run buildKun、main、preload、renderer 生产包全部通过Write/Design 聚焦测试套件 230 个文件、1650 个测试通过。全程未改动任何 Electron IPC、Kun HTTP/SSE 或持久化文件 schema。迁移与回滚迁移分六步推进先为 Write 状态补充上下文/revision 字段与默认值无需持久化迁移即可初始化再把 Write 文件动作与编辑器任务接入上下文校验并先补回归测试最后才抽出视图生命周期 hook随后接入 Design 持久化协调器并迁移内部写入器与面板、补 flush 清理用有界注册表与 generation 围栏替换全局 hydration 集合与图片 Map但不改磁盘格式在保留 v1→v2 坐标迁移的前提下加入 Canvas 校验每块完成后跑聚焦测试最后全量 typecheck、测试、lint、Kun 构建与应用构建。回滚纯代码级不改任何磁盘 schema还原实现即恢复原行为而新协调器写入的文件依然兼容。所有上限以具名常量编码并由测试覆盖可在不改变契约的前提下调参。相关文档与源码索引提案openspec/changes/harden-write-design-health/proposal.md需求规格write-workspace-integrity/spec.md 与 design-workspace-durability/spec.md设计决策design.md任务清单tasks.md验证记录verification.mdWrite 侧实现write-document-context.ts、write-save-coordinator.ts、write-workspace-store.ts、use-write-workspace-lifecycle.ts、paste-image.tsDesign 侧实现design-persistence-coordinator.ts、design-persistence-flush.ts、canvas-persistence.ts、canvas-image-source.ts、design-workspace-registry.ts、design-workspace-lifecycle.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点击查看免费下载相关推荐Kun Design 模式实施蓝图在现有工作区架构上落地第三个顶层设计工作区Kun Design 模式实施蓝图在现有工作区架构上落地第三个顶层设计工作区 Kun 是一个 Local first 的 AI agent 工作区同一套运行人工智能AI Agent自主智能体桌面应用MCP ClientsProxySQL 3.0.4 版本发布说明PostgreSQL 支持、MySQL 协议健壮性与安全加固全面解读ProxySQL 3.0.4 版本发布说明PostgreSQL 支持、MySQL 协议健壮性与安全加固全面解读 本指南基于仓库中的 ProxySQL 3.0.后端数据库负载均衡ClickHouse v25.8.25.37-lts 发布解读安全加固、格式解析器健壮性与备份恢复修复全览ClickHouse v25.8.25.37 lts 发布解读安全加固、格式解析器健壮性与备份恢复修复全览 v25.8.25.37 lts 是 ClickHo数据库OLAP列式数据库大数据实时分析数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
