Kun 工作区统一重构:Code/Work 双工作区、每轮 Design 任务表面与 DesignTaskProfile 锁定机制

原创2026-10-11 14:39:171,979 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

Kun 工作区统一重构:Code/Work 双工作区、每轮 Design 任务表面与 DesignTaskProfile 锁定机制

导读

本文深入解读 Kun 项目"统一 Code、Write 与 Design 工作区"(unify-code-design-and-work)这一架构级变更:顶层导航由 Code | Write | Design 收敛为 Code | Work 两个工作区,Design 从独立工作区降级为 Code 工作台内按轮(per-turn)选择的任务表面,并以首个被接受的 Design 轮次为边界锁定一份不可变的 DesignTaskProfile 契约。读者将掌握:会话级工作区归属与轮次级任务表面如何分离、Design 档案在 admission、持久化、回放、fork 中的流转规则,以及 html / image 双输出通道与 Work 呈现别名的落地方式。文中所有结论均可在仓库的 OpenSpec 文档与源码中直接验证。

一、背景与动机:为什么三个工作区要收敛为两个

在旧架构中,Kun 将 Code、Write、Design 呈现为三个顶层工作区,但三个表面共享同一套 Kun 运行时与 HTTP/SSE 通道。问题随之而来:

  • Design 拥有独立的侧栏、舞台(stage)、线程注册表、紧凑型 composer 与"一文档一会话"模型,与 Code 工作区割裂;
  • Code 的右侧工作区虽然已有 Canvas 面板可以展示 Design 文档,但该分支是瞬态(transient)的,不会运行完整的 HTML/ShapeOps 渲染管线;
  • Write 的能力边界已经扩展到 Markdown、PDF、图片以及 DOC/DOCX/XLS/XLSX/PPT/PPTX 六种 Office 格式的只读预览与问答,"Write" 这一产品名已无法描述其真实工作区内涵。

正如 proposal.md 所述,这种碎片化迫使用户在描述任务之前就必须先选择应用表面。因此本变更的核心意图是:保留一个 Kun 运行时,把"应用表面选择"从会话创建阶段推迟到每一轮对话发送之前,让用户先描述任务、再选择执行表面。

二、目标与非目标:边界清晰的收敛

design.md 明确了本次重构的边界。

目标(Goals):

  • 将 Code 与 Work 呈现为仅有的两个顶层工作区;
  • 在 Code 工作台的同一个 composer 内,为每一轮选择 Code 或 Design,且只锁定 Design 文档、输出媒介、目标与样式快照;
  • 在 Code 右侧白板中运行完整 Design 的 HTML/SVG/动效/图片行为,而不创建第二套会话表面;
  • 让 Design 任务的文档、输出媒介、目标与样式快照在重载、队列恢复、回放与 fork 中保持持久化并可校验;
  • 在把用户可见产品语言切换为 Work 的同时,保持内部所有 write 契约兼容。

非目标(Non-Goals):

  • 不迁移或删除旧 Design 会话与 .kun-design 文件;
  • 不重命名 write 路由值、IPC 通道、设置键、扩展令牌、存储键、目录或 Kun agent 表面;
  • 不新增 DOC/DOCX/XLS/XLSX/PPT/PPTX 的原生编辑能力;
  • 不创建第二个 agent 运行时,也不在 composer 中新增独立的图像模型选择器。

三、核心决策一:工作区归属与每轮任务表面解耦

本变更最重要的一条设计原则是:会话级归属(ownership)与轮次级任务表面(per-turn task surface)是两回事。

  • 从 Code 工作台新建的会话始终持久化 thread.agentSurface: 'code';write 归属 Work;旧的独立 Design 记录可以保留 thread.agentSurface: 'design'。
  • Code 会话的每一轮都可以选择 Code 或 Design,选择结果按轮持久化:Code 轮发送 agentSurface: 'code';Design 轮发送 agentSurface: 'design' 并附带 Design 标志与文档目标。
  • 运行时 admission 在接收 Design 轮次时不得把显式属于 Code 的会话重新打上 Design 标签。

源码中,这一逻辑由 kun/src/services/turn-service-design-admission.ts 的 resolveDesignTurnAdmission 实现,它在线程级互斥锁下解析所有任务/档案归属,保证锁决策的原子性。而 kun/src/domain/task-surface-lock.ts 的 resolveThreadLockedTaskSurface 明确注释:

Code-owned workbench threads never have a session-level task surface lock: each turn selects Code or Design independently, and only the optional Design profile is durable.

即:Code 归属的会话不存在会话级任务表面锁,只有可选的 Design 档案是持久的;write 与旧式独立 Design 记录才保留其持久化表面。lockedTaskSurface 因此只是 agentSurface: 'write' / 'design' 旧记录的遗留信号。

该分离带来的收益是:任务列表与时间线只有一份,而运行时仍能根据每一轮选择正确的指令、子代理与工具;每一轮的表面与可选 Design 档案成为重载、队列恢复、扩展路由与审计的持久运行时权威。同时,会话行保持视觉上的模式中立——不渲染 Code/Design 身份图标或产物徽章,因为 composer 里的选择描述的是"下一轮"而非"整个会话"。Design 轮次使用 Agent/Direct 直接编排方式。

四、核心决策二:首次接受轮锁定 DesignTaskProfile

4.1 严格契约:字段级定义

Kun 引入严格的 DesignTaskProfile 契约,其完整字段定义位于 kun/src/contracts/design-task-profile.ts(渲染器侧镜像位于 src/renderer/src/agent/design-task-profile.ts)。核心字段如下:

字段 取值/约束 含义
version 1(字面量) 契约版本
documentTarget.documentId 稳定 Design 标识符(/^[A-Za-z0-9][A-Za-z0-9._-]*$/,最长 128) 绑定的 Design 文档
documentTarget.boardArtifactId 同上 文档内画板(board)产物
outputMedium 'html' | 'image' 主输出媒介
target 'web' | 'app' 目标端
preset 14 个预设之一(见 4.4) 设计系统预设
presetSource 'explicit' | 'root-design-md' | 'workspace-default' | 'none' Auto 解析来源
styleSnapshot 见 4.4 不可变样式快照
canvasEngine 'kun' | 'excalidraw'(可选) 画布引擎
context DesignContextSnapshot 有界的设计上下文快照
lockedAtTurnId 运行时写入(DesignTaskProfile 专属) 锁定发生的轮次 id

其中 DesignStyleSnapshot 是版本为 1、来源固定为 root-design-md 的严格对象,包含 sourceHash(源文件哈希)、sourceName(可读风格名)、content(最长 16000 字符的稳定有界 JSON 投影)与可选的 truncated 标记。DesignContextSnapshot 覆盖 designType(brand/product)、brandColor、去重的 tone 列表(最多 12 项)、designGuidelines(最长 4000)、radius(sharp/soft/rounded/pill)、density(compact/cozy/spacious)与 fontStyle(system/geometric/humanist/serif/mono)。

值得注意的是,契约通过 .strict() 与 superRefine 做了防御性校验:styleSnapshot 仅当 presetSource === 'root-design-md' 时合法;tone 条目必须唯一;DesignImagePlacementTarget 要求 expectedImageUrl 与 expectedHolderKind 恰好出现其一。

4.2 锁定时机与冲突拒绝

一个 Code 工作台会话在首个被接受的 Design 轮之前没有锁定档案。首个被接受的 Design 轮会原子地存储档案与 lockedAtTurnId;此后的 Design 轮若与锁定档案不一致,将失败并返回 design_profile_locked。而后续 Code 轮无档案即可接受;再次进入 Design 时复用已锁定的档案。

该流程对应 kun/src/domain/design-task-profile.ts 的 lockDesignTaskProfile / sameDesignTaskProfile / sameDesignDocumentTarget,以及 kun/src/services/turn-service-design-admission.ts 中完整的判定分支:

  • 已有锁定档案 + Design 轮 + 提交档案不一致 → DesignProfileLockedError(携带 lockedAtTurnId、锁定文档/画板 id 与 mismatch: 'profile' | 'document-target');
  • 已有锁定档案 + Code 轮却携带档案/文档目标 → TurnConflictError;
  • 首次 Design 轮缺少档案或文档目标 → TurnConflictError("the first accepted Design turn requires a Design profile and document target");
  • 首个 Design 轮携带合法档案 → 返回 locksProfile: true 并生成 effectiveProfile。

错误码 task_surface_locked 与 design_profile_locked 均注册在 kun/src/contracts/errors.ts,并映射为 HTTP 409 响应(见 kun/src/server/routes/runtime-error.ts)。tasks 文档还强调:这类确定性 4xx 拒绝必须恰好失败一次,不能进入未知结果恢复循环。

测试方面,kun/src/services/turn-service-task-surface-lock.test.ts 覆盖了首轮双模式可选、Code 首轮后进入 Design、混合历史逐轮选择、失败 provisional 档案忽略、design_profile_locked 冲突拒绝、锁定档案复用、Code 轮携带档案拒绝以及 legacy 标题撞车不能认领 Work 等 8 类场景。

4.3 快照、回放与 fork

  • 快照:每个 Design 轮与其用户消息都记录生效的档案与文档目标,供审计、回放与画布路由使用。队列中的 Design 消息重试时使用入队时的档案快照,即使此后用户修改了全局 Design 设置也不会被影响;渲染器本地存储只是发送前的草稿/缓存,不是权威。
  • 回放:画布回放只应用线程、轮次、文档与画板目标与当前 Design 任务匹配的操作。
  • fork:fork 复制锁定档案,并先克隆绑定的 Design 文档再激活 fork,使 fork 获得独立的可写文档绑定。从历史轮次 fork 且该轮无画布快照时,操作在克隆前以显式"不支持的历史"错误失败,避免截断的聊天与未来画布状态错误配对。designCloneOperation(含 operationId、kind: 'fork' | 'resume'、sourceId)作为幂等审计记录存在于 kun/src/contracts/threads.ts 的线程契约中。

4.4 样式:只播种一次,之后遵循文档设计系统

composer 复用 Kun 既有的 DesignSystemPreset 目录与 Design 上下文字段。在首次发送前,Auto 按以下顺序解析:

  1. 合法的根级 DESIGN.md;
  2. 工作区 Design 默认值;
  3. none。

解析结果被快照进锁定档案;一旦文档生成,其持久化的设计系统即成为权威,后续全局设置的变更不会隐式地重新样式化该任务。契约中的 14 个预设为 none, shadcn, radix, material, ios, fluent, ant, chakra, carbon, polaris, bootstrap, geist, brutalism, editorial。渲染器侧,src/renderer/src/components/chat/FloatingComposerTaskProfile.tsx 为每个预设提供图标与色彩标记(DESIGN_STYLE_MARKS),并在摘要区展示 输出媒介 · 目标 · 预设 的紧凑概要。

运行时侧,kun/src/prompt/design-task-profile.ts 的 buildDesignTaskProfileInstruction 把不可变档案编译为模型可见的指令块,其中明确:app 目标使用 390x844 移动优先、web 目标使用 1280x800 桌面优先的默认画幅;image 媒介强调"主交付物是生成的栅格图像,不得静默替换为 HTML";root-design-md 来源会提示"不要重新读取当前工作区文件,后续编辑不得重新样式化此任务"。

五、核心决策三:每个 Design 任务一个规范 DesignDocument

每个进入 Design 的 Code 会话只绑定一个 DesignDocument,该文档可包含多个 HTML、SVG、图片、画板与动效产物。Code 右侧工作区通过可复用的完整 Design 画布表面挂载此文档,而非旧的只读瞬态 Design 文档分支;从未进入 Design 的会话继续使用轻量的逐线程 .kun-canvas 白板。

渲染器侧的挂载目标由 src/renderer/src/design/code-canvas-design-surface.ts 的 CodeCanvasDesignSurface 承载,关键设计:

  • surfaceKind 三态区分:'kun-canvas'(轻量 Code 画布)、'kun-design'(完整 .kun-design 文档)、'kun-whiteboards'(中央 Work 白板),保证模式切换永远不会重挂一个无关的空白画布;
  • 目标被限定到线程(threadId + workspaceRoot + documentId + boardArtifactId),线程切换即回退到线程画布;
  • 目标缓存在浏览器存储键 kun.codeCanvas.designSurface.v2 中,面板折叠与渲染器重载后仍可恢复;而锁定的运行时 Design 档案在线程加载时重新断言此缓存,是权威来源;
  • 浏览非规范文档(readOnly: true)不会改变任务的可写目标;失败的 Design 发送删除临时文档后,restoreDesignSurface 会原子恢复之前捕获的目标,避免永久挂载已删除文档。

画布上的每次变更都按线程、轮次、文档与画板产物限定作用域。关闭右侧面板只改变呈现,不清除绑定;面板重新打开时,错过的操作以幂等方式重放(durable replay)。若 Design 任务目标仍在水合中,右侧面板保持 Design 加载状态,而不是挂载轻量 Code 画布。从源码结构看,src/renderer/src/design/code-canvas-design-surface.ts 之外,src/renderer/src/design/canvas/ 目录下的 code-canvas.ts、design-system-persistence.ts 与 canvas-persistence.ts 共同构成该表面在轻量画布与设计系统持久化间的分界。

六、核心决策四:旧 Design 会话保留在统一任务列表

通过 agentSurface: 'design' 或持久化 Design 线程注册表识别的项目自有旧会话,在 Code 任务列表中保持一等公民地位。其既有注册表文档绑定是权威的:选中所属会话后,通过 Code 归属 Design 任务使用的同一完整画布表面,恢复其原始可写 .kun-design 文档。

这里只改变呈现与导航:不迁移、不复制任何线程归属、档案、注册表或产物数据。一个共享的任务分类器被列表资格、导航、返回记忆与画布恢复路径复用,但不用于给会话分配 Code/Design 徽标;对 Code 归属会话,可选 Design 档案只驱动白板文档绑定,lockedTaskSurface 仅为 write/design 遗留记录服务。

七、核心决策五:HTML 与 AI 图像双主输出通道

html 是默认媒介,复用既有 screen factory 与链接式 HTML 续作;续作在发起轮内以进度形式渲染,而不是追加为另一条用户消息。image 通道要求运行时具备图像生成能力,会宣告栅格通道并禁止 HTML 屏幕兜底。

成功 generate_image 后,渲染器确定性地填充被选中的空占位(holder)或在推荐白板插槽插入图像;工具结果身份(tool-result identity)防止 SSE 回放期间重复放置。HTML 任务可以调用图像生成为辅助资源,但主产物仍是 HTML。

图像生成的呈现语义(来自 specs/embedded-design-whiteboard/spec.md):

  • 生成开始 → 白板创建"生成中"占位符并跨重载/回放持久化;
  • 成功 → 原位替换占位符(不改变占位符边界、不重复插入);
  • 失败/中止 → 占位符变为可操作的错误态(显示原因、耗时与重试动作),绝不回到空白;
  • 布局 → 生成开始时白板自动打开,首个成功放置后执行一次 fit-to-content,focus/全宽模式提供可用的最小宽度且不改变绑定文档与画布状态。

能力故障不改变任务意图:composer 以运行时图像生成诊断为权威。首次发送前若诊断报告图像生成未启用,AI 图像从输出选项中消失,未锁定的过时 AI 图像草稿回退为 HTML;若已启用但不可用,AI 图像以运行时原因与"图像生成设置"动作禁用,HTML 仍可用;锁定 AI 图像会话丢失图像提供商后,提交被阻止、草稿保留、给出配置动作,会话保持 AI 图像,绝不静默切到 HTML。实现侧,图像生成工具定义于 kun/src/adapters/tool/image-gen-tool-provider.ts(generate_image 工具)。

八、核心决策六:Work 作为呈现别名,协议零重命名

Work 是一次用户面向的呈现别名:只有模式、工作区、助手、引导、设置与文档语言切换为 Work/办公,稳定代码标识符与持久化会话标题保持 write / Write Assistant,渲染器将其映射为本地化产品标签。

兼容性要点(见 specs/work-product-surface/spec.md):

  • 升级用户已有 Write 设置、工作区注册表与助手线程时,Work 打开同一份数据,不创建重复工作区或会话;
  • Work 新轮次仍使用 agentSurface: 'write';
  • 已安装扩展贡献到 workbench:write 仍能匹配 Work 表面,无需新的 workbench:work 令牌;
  • Work 的引导文案准确描述 Markdown/文本编辑与 Office/PDF 的预览、选择、引用、分析与生成流程,不声称原生编辑 Office 文件;DOC/DOCX/XLS/XLSX/PPT/PPTX 的只读预览、选择、语义上下文与实时刷新行为保持不变;
  • 本地化方面,所有受支持语言提供 Work 产品标签,同时保留写作类具体功能(写作、润色、格式化、行内补全)的原有措辞与 write* i18n 键。

九、风险与取舍

design.md 记录了六项风险与对应缓解策略:

风险 缓解
完整 Design 画布控件对现有右面板宽度过于密集 增加 focus/expand 呈现与单面板窄布局;缩放或折叠时绝不改变任务/档案状态
首次发送竞争导致锁定不同档案或创建重复文档 客户端请求幂等 + 原子运行时 admission + 临时文档回滚路径
Shape 操作回放到错误文档 每个 Design 轮持久化文档/画板目标,并作为 live/replay 过滤的必需条件
AI 图像档案锁定后图像生成消失 保持档案锁定、保留草稿、以运行时能力原因阻止 Design 提交并链接到图像生成设置,绝不静默切 HTML
既有扩展依赖 workbench:design 或 workbench:write Design 上下文从活动任务表面派生,Write 稳定令牌不变
旧 Design 会话不可访问 项目自有旧会话纳入统一任务列表,恢复其注册表文档绑定,不迁移不删除运行时记录或文件

十、迁移计划与回滚

六步迁移(design.md):

  1. 增加容忍性的可选运行时/档案契约与渲染器映射;旧记录无档案也能加载;
  2. 让所有新建 Code/Design 线程显式归属,并在移除旧导航前更新共享 Code 任务过滤器;
  3. 在 Code 右侧工作区挂载完整 Design 文档表面,并路由锁定的 Design 任务轮次;
  4. 发布统一 composer/列表/空状态,从新流程移除独立 Design 入口;
  5. 应用 Work 显示别名,不重写已保存设置或线程;
  6. 将旧 Design 会话纳入共享列表,并让旧式与 Code 归属的 Design 任务都绑定到可复用的完整 Design 画布。

回滚只需移除新 UI 入口,可选线程/轮次元数据与 .kun-design 内容仍可被旧版本读取,保证前后版本数据互通。

十一、落地与验证:测试与工程质量

tasks.md 记录了 14 个阶段全部完成(含多轮评审修正),关键证据包括:

  • 运行时与持久化:design_profile_locked 与 Code-with-profile 冲突的 admission 套件 12/12 通过;档案/模式锁、admission 重试/重启、legacy 记录、fork/resume 失败边界、回放回执、AI 放置与不可变样式等跨层回归测试齐备;
  • 渲染器:工作台任务表面、侧栏混合徽章、图像生成进度、共享运行时错误码与队列治理 39/39 通过;任务模式锁定、共享任务列表、档案隔离、HTML/图像路由、能力失败、画布回放、响应式控件与 legacy 兼容等专项测试完备;
  • 嵌入式白板:88 个 Design 画布文件 709/709 测试通过,覆盖回放恢复、图完整性、标注、导出、剪贴板、快捷键、缩放与 composer 路由;
  • 工程质量门禁:npm run typecheck、npm run build、npm run lint、npm run check:file-lines(700 行文件上限)与 git diff --check、严格 OpenSpec 校验均通过,改动文件全部低于 700 行。

十二、总结

Kun 的 unify-code-design-and-work 是一次"表面收敛、契约收紧"的重构:把 Design 从独立工作区收敛为 Code 工作台内的每轮任务表面,用 DesignTaskProfile 把文档绑定、输出媒介、目标与样式快照在首个接受轮原子锁定,并让 Work 以零协议改名的别名方式承接 Write 的用户界面。其核心价值在于:一个运行时、一份任务列表、一套持久契约——会话归属稳定,轮次表面灵活,数据不迁移、扩展不破坏、旧会话不丢失。对于想理解 Kun 工作区架构或在其上开发扩展的工程师,这份设计与配套源码是理解"模式中立会话 + 持久任务档案 + 文档级画布路由"的最佳入口。

登录后查看全文
Kun