Kun 工作台统一改造:Code/Work 双顶层导航、per-turn Design 任务模式与内嵌白板设计全解析

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

Kun 工作台统一改造:Code/Work 双顶层导航、per-turn Design 任务模式与内嵌白板设计全解析

本篇技术指南以 Kun 仓库中的 OpenSpec 变更提案 unify-code-design-and-work/proposal.md 为主线,系统讲解 Kun 如何将顶层 Code | Write | Design 三工作台收拢为 Code | Work,把 Design 从独立工作台降级为 Code 工作台内每回合可选的任务模式,并引入 DesignTaskProfile 首个回合锁定、内嵌设计白板与 HTML/AI 图像双主输出通道。读完本文,你将掌握这套改造的契约设计(design-task-profile.ts)、准入锁定逻辑(turn-service-design-admission.ts)、渲染器任务状态机(useWorkbenchTaskSurface.ts)以及 Work 呈现别名对 write 协议兼容的完整方案。

背景:为什么要把 Code | Write | Design 收拢为 Code | Work

提案开篇(## Why)指出现状的三重问题:

  • 会话碎片化:Code、Write、Design 是三个顶层工作台,尽管 Design 已与 Kun 共享同一 runtime,且能在 Code 右侧白板中渲染,但用户仍然被迫在描述任务之前先选择一个应用表面;
  • Write 名不副实:Write 已覆盖 Markdown、PDF、图片和六种 Office 格式(DOC/DOCX/XLS/XLSX/PPT/PPTX),"Write" 这个名字已无法描述其工作台范围;
  • 导航与对话归属割裂:Design 拥有独立的 sidebar、stage、线程注册表和按文档组织的会话,与 Code 的 tabbed 右工作区各自为政,而 Code 已有的 Canvas 面板虽然能展示 Design 文档,但只是瞬态分支,不跑完整的 HTML/ShapeOps 管线。

因此本变更的目标非常收敛:保留一个 Kun runtime、稳定的扩展与持久化 write 标识符、.kun-design 下的既有 Design 产物文件、图像提供方能力检查,以及 700 行的源文件门限(authored-file gate)(见 design.md 的 Context 部分)。Design 与 Code 共用 HTTP/SSE,只是被投影成三条渲染器路由,改造的本质是重排这层投影,而不是重写 runtime。

顶层导航:从 Code | Write | Design 到 Code | Work

proposal.md 的 What Changes 部分给出了明确的导航变更:

  • 顶层导航由 Code | Write | Design 替换为 Code | Work,同时保留稳定的内部 write 路由、设置项、扩展、IPC 与持久化标识符;
  • Design 成为 Code 工作台内的对话模式(conversation mode):用户在模式中立的会话里,每一回合都可以选择 Code 或 Design;会话列表不给会话行打 Code/Design 标识,只有 Design 文档、输出介质、目标和样式快照会随首个被接受的 Design 回合锁定。

也就是说,"顶层只有两个入口"是用户可见的变化,而"write"这组内部标识符一个都不动。tasks.md 的第 4 节还记录了一个细节:Code/Work 的分段控件(segmented control)最终被替换为紧凑的无障碍下拉(accessible dropdown),以保证在窄 sidebar 中依然可读且不破坏工作台路由。

对应的工作台路由实现证据位于 src/renderer/src/components/workbench/useWorkbenchNavigationController.test.ts(导航控制器回归测试),顶层模式枚举在 threads.ts 中定义为 ThreadAgentSurface = z.enum(['code', 'write', 'design'])。

核心设计:工作台归属与 per-turn 任务表面分离

这是整个改造最关键的决策(见 design.md 的 Decisions 第一节):

  • 从 Code 工作台新建的会话,始终持久化 thread.agentSurface: 'code';
  • write 仍归 Work 所有;遗留的独立 Design 记录可以保留 thread.agentSurface: 'design';
  • Code 会话的每一回合可选择 Code 或 Design,并按回合持久化:
    • Code 回合发送 agentSurface: 'code';
    • Design 回合发送 agentSurface: 'design' 加上 Design 标志位与文档目标;
  • 准入(admission)不得把一个显式 Code 拥有的线程,在接受 Design 回合时重新打标签。

这样做的收益:一个任务列表 + 一条时间线(timeline),同时 runtime 依然能依据每回合的表面选择正确的指令、子代理与工具。每回合的表面与可选的 Design 档案成为可持久化的 runtime 权威,用于重载、队列恢复、扩展路由和审计。会话行保持视觉上的模式中立:不渲染 Code/Design 身份图标,也不渲染产物徽标,因为组合器(composer)的选择描述的是"下一回合",而不是"整段会话"。Design 回合采用 Agent/Direct 执行。

渲染器侧的实现位于 useWorkbenchTaskSurface.ts,其中关键判断:

// 只有遗留的独立表面才锁定任务模式;Code-owned 会话永远按回合选择
return thread.agentSurface === 'write' || thread.agentSurface === 'design'

而"下一回合表面"的推导优先级为:遗留 Design 会话 → 已持久化的草稿 → pendingDesignThreadIntent → 已锁定 profile → 默认 code。当线程拥有锁定文档目标(或遗留注册表绑定)时,白板的挂载独立于下一回合的表面选择——即"白板跟随文档,而非跟随下一回合模式"(designProfile.documentTarget 驱动)。

统一任务分类器实现在 design-task-classification.ts,它被任务列表资格、导航、返回记忆和画布恢复路径共享,但绝不用它给会话行分配 Code/Design 图标:

export function isDesignWorkbenchThread(threadId, thread, registry): boolean {
  if (isLegacyDesignWorkbenchThread(threadId, thread, registry)) return true
  if (!thread) return false
  // Code-owned 会话只有通过锁定 Design 文档才具备 Design 能力
  return Boolean(thread.designProfile)
}

DesignTaskProfile:结构化设计档案与首个回合锁定

契约字段

DesignTaskProfile 是本次改造新增的严格持久化契约,完整定义在 kun/src/contracts/design-task-profile.ts(基于 zod)。关键字段如下:

字段 类型/取值 说明
version 1 契约版本,严格字面量
documentTarget { documentId, boardArtifactId } 每任务唯一、可独立写画的文档绑定;两者均为 1~128 字符且须匹配 ^[A-Za-z0-9][A-Za-z0-9._-]*$ 的稳定标识符
outputMedium 'html' | 'image' 输出介质,HTML 为默认
target 'web' | 'app' 目标平台,直接影响默认画布尺寸(见下文)
preset 14 种设计系统预设 none / shadcn / radix / material / ios / fluent / ant / chakra / carbon / polaris / bootstrap / geist / brutalism / editorial
presetSource explicit | root-design-md | workspace-default | none Auto 解析来源,锁定时固化
styleSnapshot 版本 1、sourceHash、sourceName、content(≤16 000 字符)、truncated? 根 DESIGN.md 的不可变解析投影,仅当 presetSource === 'root-design-md' 时合法(superRefine 校验)
canvasEngine 'kun' | 'excalidraw'(可选) 绑定画布的渲染引擎;缺省表示遗留 Kun canvas
context 有界 DesignContextSnapshot designType、brandColor、tone(最多 12 项且不可重复)、designGuidelines(≤4 000)、radius、density、fontStyle
lockedAtTurnId 字符串 仅存在于运行时已锁定档案中,标记锁定回合

DesignImagePlacementTarget 还细化了 AI 图像放置目标:shapeId + 恰好一个 expectedImageUrl 或 expectedHolderKind(explicit / implicit-image / implicit-frame / implicit-rect),用于幂等放置。

锁定语义与错误码

一个 Code 工作台线程在首个被接受的 Design 回合之前没有锁定档案。首个 Design 回合被接受时,lockedAtTurnId 与该档案被原子写入;之后:

  • 后续 Design 回合必须与锁定档案完全一致(通过 sameDesignTaskProfile 的 JSON 比较,见 domain/design-task-profile.ts),否则拒绝并返回 design_profile_locked;
  • 后续 Code 回合不带档案即可被接受,且不会被 task_surface_locked 拒绝;
  • 再次进入 Design 时,复用锁定档案,不重新锁定、不修改。

这两个错误码(task_surface_locked 与 design_profile_locked)被注册进共享 runtime 错误契约(kun/src/contracts/errors.ts、kun/src/server/routes/runtime-error.ts),并规定确定性的 4xx 拒绝必须恰好失败一次,而不是进入未知结果恢复循环(见 tasks.md 第 12 节)。

准入解析:原子决策链

准入逻辑集中在 kun/src/services/turn-service-design-admission.ts 的 resolveDesignTurnAdmission。它在持有线程级 mutation 锁的情况下运行,保证任何 attachment 绑定、文档提交、模型回合、item 或事件产生之前,任务/档案归属已经确定,因此锁定决策是原子的。核心校验链包括:

  1. 表面锁定检查:若 lockedTaskSurface 与请求表面冲突,抛 TaskSurfaceLockedError;
  2. designProfile 与 designDocumentTarget 必须成对出现,且 documentTarget 必须与 designProfile.documentTarget 一致,否则抛 TurnConflictError;
  3. 提交档案必须通过 DesignTaskProfileInputSchema 严格解析(不支持的中介、预设、目标、超长上下文或错配文档 id 都在模型回合开始前被拒);
  4. 已锁定档案存在时:Code 回合不得携带档案/文档目标;Design 回合若档案或文档目标不匹配则抛 DesignProfileLockedError;匹配则返回锁定档案作为 effectiveProfile;
  5. 首次 Design 回合通过 lockDesignTaskProfile(submittedProfile, turnId) 完成锁定并返回 locksProfile: true。

对应的测试位于 kun/src/services/turn-service-task-surface-lock.test.ts,覆盖了"首个回合前任选模式""首个 Code 回合之后允许进入 Design""混合历史逐回合 Code/Design 选择"等场景,以及 design_profile_locked 与 Code-with-profile 冲突用例。

每次 Design 回合的快照语义

thread-design-profile spec 要求:每个 Design 回合及其 user item 都记录生效档案与文档目标,用于审计、回放与画布路由。这意味着:

  • 队列重试:排队中的 Design 消息在用户修改全局 Design 设置后被重试时,使用原排队时快照的档案与文档目标,而不是可变的全局设置;
  • 画布重放:错过的 Design 操作回放时,只有 thread、turn、document、board 目标全部匹配当前活跃 Design 任务的才被应用;
  • 渲染器本地存储只是发送前草稿/缓存,不是权威;权威始终是 runtime 数据(design.md 明确说明)。

Fork:保留意图但不共享可变画布状态

Fork 一个 Design 任务时,锁定档案被复制,同时绑定文档被克隆为独立可写的新绑定(retargetDesignTaskProfile + 文档克隆)。渲染器侧 design-locked-profile.ts 提供 cloneDesignTaskProfile 与 restoreLockedDesignDocument;线程恢复元数据 ResumeSessionMetadata 携带 sourceDesignProfile、sourceDesignDocumentTarget 与 requiresIndependentDesignTarget(见 threads.ts)。

还有一个重要的失败边界:从历史回合发起 fork 时,如果该回合不存在文档快照,操作必须在克隆前显式失败(返回 unsupported-history 错误),绝不能把截断的聊天与未来的画布状态配对(tasks.md 第 7.7 节专门做了 fault-injection 覆盖)。

遗留数据处理原则

档案解析对新写入严格、对遗留字段宽容:无档案的旧线程保持可读,绝不虚构档案;只有新 Design 工作流显式创建时才生成。遗留的 agentSurface: 'design' 或 Design 线程注册表记录是任务列表中的一等公民,其注册表文档绑定是权威,选择该会话时通过同一完整画布表面恢复原始可写的 .kun-design 文档——只改呈现与导航,不迁移、不复制、不删除任何线程归属、档案、注册表或产物数据。

内嵌设计白板:在 Code 右侧跑完整 Design 管线

embedded-design-whiteboard 能力要求 Code 右工作区挂载绑定文档时,具备既有 HTML、SVG、动效、多屏、设计系统、原型、选择、撤销与导出能力,而不是原来的只读瞬态分支。渲染器用 CodeCanvasDesignSurface 描述白板目标(code-canvas-design-surface.ts):

export type CodeCanvasDesignSurface = {
  surfaceKind?: 'kun-canvas' | 'kun-design' | 'kun-whiteboards'
  threadId: string
  workspaceRoot: string
  documentId: string
  boardArtifactId?: string
  readOnly?: boolean
  canonicalDocumentId?: string
  continuationOperationId?: string
} | null

surfaceKind 用来区分三种白板宿主(轻量 Code canvas、完整 .kun-design 文档、中央 Work 白板);boardArtifactId 在多画板文档内钉住画板,避免模式切换挂载到无关的空白画布。目标持久化在浏览器存储键 kun.codeCanvas.designSurface.v2 下,面板折叠与渲染器重载后仍存活;锁定档案在线程加载时重新断言该缓存(comment 明确指出 "A locked runtime Design profile remains authoritative and reasserts this cache on thread load")。

关键行为(design.md 与 spec 交叉确认):

  • 面板呈现变化不改变任务状态:折叠、聚焦、缩放、重开只影响呈现,任务、锁定档案、选中文档与画板状态不变;关闭右面板不清除绑定;
  • 持久重放:面板重开时对错过的操作幂等地应用;durable replay receipts 防止已投递的结果被二次应用(工具结果身份去重);
  • 目标水合(hydration):Design 会话在文档目标水合完成前,右面板保持 Design loading 状态,绝不回退到轻量 Code canvas;
  • Code 白板接收完成的渲染器工具结果:若画布工具结果先于线程文档就绪完成,渲染器在文档激活后将结果重放到匹配会话白板(spec 场景);
  • 首回合竞态:空工作台发送首个 Design 回合且新 Code-owned 会话在 createThread 返回前已激活时,pending Design 选择与临时文档在绑定前保持活跃(pendingDesignThreadIntent + provisionalDesignThreadIdsRef,见 useWorkbenchTaskSurface.ts 的 ensureDesignThread);发送失败时通过 rollbackProvisionalThread 回滚临时文档,不留下空文档。

白板恢复的完整实现链在 design-locked-profile.ts:activateLockedDesignDocument 先 restoreLockedDesignDocument(必要时 rehydrateArtifacts),再以 canvasDocumentKey(workspaceRoot, boardArtifactId, '.kun-design/<documentId>') 为目标等待画布就绪(waitForCanvasDocumentKey,默认 5 秒超时),失败时给出可读错误并保持绑定不变。测试覆盖见 code-canvas-design-surface.test.ts 与 canvas 系列回归(tasks.md 第 8 节记录 88 个文件 709/709 测试通过,涵盖重放恢复、图完整性、标注、导出、剪贴板、快捷键、缩放与组合器路由)。

HTML 与 AI 图像:两条互不静默降级的主输出通道

proposal.md 明确规定:HTML 是默认交互输出;AI 图像任务在白板上产出光栅资产,绝不静默回退为 HTML;而 HTML 任务可以调用图像生成作为支撑资产。设计决策(design.md)进一步给出两条通道的语义:

  • html:走既有 screen factory 与链接式 HTML 续写(linked HTML continuation),续写渲染为来源回合内部的进度,而不是另一条用户消息;
  • image:要求 runtime 具备图像生成能力,公告光栅通道,禁止 HTML-screen 回退。

模型侧的执行指令由 kun/src/prompt/design-task-profile.ts 的 buildDesignTaskProfileInstruction 生成,它只从不可变线程快照派生:

const frame = profile.target === 'app' ? '390x844 mobile-first' : '1280x800 desktop-first'
const output = profile.outputMedium === 'image'
  ? 'The primary deliverable is a generated raster image. Do not silently substitute HTML.'
  : 'The primary deliverable is an interactive HTML interface. Raster images may only support it.'

注意这里 app 目标使用 390×844 移动优先、web 使用 1280×800 桌面优先的默认画布尺寸,并在每条指令中输出锁定回合、绑定文档、绑定画板、输出介质、目标、预设及来源、样式快照哈希和视觉上下文快照。

渲染器侧的确定性放置逻辑(spec 的 AI-image placement 要求)为:

  • generate_image 成功完成后,幂等地填充选中的空 holder(不改变其边界),否则插入推荐槽位;
  • 工具结果身份(completion identity)保证 SSE 重连重放时不重复插入(见 canvas-generated-image-replay.ts);
  • 进行中的生成显示持久占位符,成功原位替换,失败/中止显示可操作错误状态(原因、耗时、重试动作),且永不退回空白(canvas-image-generation-progress.ts);
  • 交付文案随完成度变化:"助手说会把图像放到白板"时状态保持 in-progress,工具成功后才变为 delivered。

能力失败不改变任务意图(spec 场景):

场景 行为
首回合前图像生成被禁用(diagnostics 报告未启用) AI image 从输出选项中消失;未锁定的陈旧 image 草稿规范化为 HTML
首回合前已启用但不可用(未配置 provider) AI image 置灰并显示 runtime 原因 + Image Generation 设置入口,HTML 保持可用
锁定后 provider 被移除 保留档案与草稿、阻止 Design 提交并给配置动作,会话保持 AI image 身份

这些场景在 useWorkbenchTaskSurface.ts 中有直接实现:draftNeedsImageFallback 仅在未锁定任务表面、无锁定档案且图像生成明确禁用时把草稿介质规范化为 html——一旦锁定,绝不做静默切换。

样式播种:一次解析,之后尊重文档设计系统

Design 组合器复用既有 DesignSystemPreset 目录与 Design 上下文字段。在首次发送前,Auto 按如下顺序解析(design.md 决策):

  1. 有效的根 DESIGN.md(源码中 root-design-md 来源要求捕获 sourceHash/sourceName 与 ≤16 000 字符的内容投影,且 UI 要标明该项目的样式来源,见 design-task-profile.ts 与 spec);
  2. 工作区 Design 默认(workspace-default);
  3. 无(none)。

解析结果被快照进锁定档案。文档生成后,文档自身持久化的设计系统成为权威,后续全局设置变化不能隐式重排其样式——这正是 styleSnapshot 与 presetSource 存在的意义,且 buildDesignTaskProfileInstruction 明确要求模型"不要重读当前工作区文件,后续编辑不得重排本任务"。

Work:呈现别名与 Office 语义(work-product-surface)

Work 是一次纯呈现改名(design.md 决策 "Keep Work as a presentation alias"):

  • 只有面向用户的模式、工作台、助手、引导(onboarding)、设置与文档措辞改为 Work/办公;稳定的代码标识符与持久化线程标题保持 write/Write Assistant,渲染器把它们映射为本地化产品标签;
  • 扩展贡献到 workbench:write 时继续匹配 Work 表面,无需新增 workbench:work token;
  • Work 发送回合时 runtime 仍使用 agentSurface: 'write';
  • 具体动词(writing、polishing、formatting 等)在描述真实功能时保持不变。

同时 Work 的措辞必须如实反映能力边界:描述 Markdown/文本编辑以及 Office/PDF 的预览、选择、引用、分析与生成流程,不得声称原生编辑 Office 文件;DOC/DOCX/XLS/XLSX/PPT/PPTX 打开后保持既有的只读预览、选择、语义上下文与实时刷新行为不变。所有受支持语言都要提供 Work 产品标签,且不改名既有的 write* i18n 键(locale parity 校验)。

风险应对与迁移路径

design.md 记录了 6 项已识别的风险及对策:

风险 对策
完整 Design 画布控件在右面板过宽 增加聚焦/展开呈现与单面板窄布局;缩放/折叠永不改变任务/档案状态
首发送竞态锁错档案或产生重复文档 客户端请求幂等 + 原子 runtime 准入 + 临时文档回滚路径(rollbackProvisionalThread)
ShapeOps 重放到错误文档 每个 Design 回合持久化文档/画板目标,实时与重放过滤都要求它
AI 图像档案锁定后生成能力消失 保持档案锁定、保留草稿、以 runtime 能力原因阻止提交并链接图像生成设置,绝不静默切换 HTML
既有扩展依赖 workbench:design/workbench:write 从活跃任务表面派生 Design 上下文,保持稳定的 Write token 不变
旧 Design 会话不可访问 统一任务列表纳入项目自有遗留 Design 会话,恢复既有注册表文档,不迁移不删除 runtime 记录与文件

迁移分 6 步(design.md Migration Plan):先加宽容的可选 runtime/档案契约(旧记录无档案可加载)→ 显式化新建 Code/Design 线程并更新共享 Code 任务过滤器 → 在 Code 右工作区挂载完整 Design 文档表面并路由锁定回合 → 上线统一组合器/列表/空态并移除独立 Design 入口 → 应用 Work 显示别名(不改写已存设置或线程)→ 遗留与 Code-owned Design 任务都绑定到可复用完整 Design 画布。回滚只需移除新 UI 入口,可选线程/回合元数据与 .kun-design 内容对旧版本依然可读。

验证与交付门禁

tasks.md 记录了完整验证证据(2026-08-12 至 2026-08-14):

  • 首轮:typecheck 与生产构建通过;249 个聚焦 renderer/main 测试、40 个聚焦 Kun 测试、2 个 runtime-manifest 测试、127 个聚焦 canvas 生命周期测试通过;
  • 复查轮:聚焦 Kun 46/46、聚焦 renderer/main 143/143;全量 Kun 4352 通过,顶层全量运行 6896 通过(残余失败均被对照 HEAD 验证为 ToolStormBreaker/loop recovery、原生 node-pty/better-sqlite3 ABI、TUI/goal 时序等既有基线问题);
  • 内嵌白板轮:88 个聚焦 Design canvas 文件 709/709 通过;
  • 逐回合表面修正轮:严格 OpenSpec validation 通过,Kun 准入 12/12(含新增 design_profile_locked 用例),渲染器 39/39,store 准入/引导/分类 60/60;
  • 模式中立呈现轮:sidebar + per-turn 19/19,Kun 准入/档案 21/21;
  • 首发送竞态轮:7 个聚焦文件 55/55。

验证命令门禁为:npm run typecheck、npm run test、npm run build、npm run lint、npm run check:file-lines(700 行/文件门限)与 git diff --check,外加 strict OpenSpec validation。这些命令与测试脚本可在仓库 package.json、scripts/run-tests.mjs 与 scripts/check-file-lines.mjs 中查看。

小结

这次改造的技术内核可以浓缩为三句话:顶层只保留 Code 与 Work 两个表面,Design 退化为 Code 工作台内按回合可选的任务模式;每个 Design 任务通过 DesignTaskProfile 在首个被接受的回合原子锁定文档、介质、目标与样式快照,形成不可变的 runtime 权威;完整 Design 管线以 CodeCanvasDesignSurface 内嵌进 Code 右白板,HTML 与 AI 图像作为两条互不静默降级的主输出通道。而对外呈现上的 Write→Work 改名,只是一层不触碰 write* 协议、IPC、存储键与扩展 token 的本地化别名。对开发者而言,理解 design-task-profile.ts 的契约、turn-service-design-admission.ts 的原子准入、useWorkbenchTaskSurface.ts 的任务状态机与 design-locked-profile.ts 的文档恢复链,即可完整把握该功能的持久化语义与回放安全边界。

登录后查看全文
Kun