Kun 工作台统一改造:Code/Work 双顶层导航、per-turn Design 任务模式与内嵌白板设计全解析
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 标志位与文档目标;
- Code 回合发送
- 准入(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 或事件产生之前,任务/档案归属已经确定,因此锁定决策是原子的。核心校验链包括:
- 表面锁定检查:若
lockedTaskSurface与请求表面冲突,抛TaskSurfaceLockedError; designProfile与designDocumentTarget必须成对出现,且documentTarget必须与designProfile.documentTarget一致,否则抛TurnConflictError;- 提交档案必须通过
DesignTaskProfileInputSchema严格解析(不支持的中介、预设、目标、超长上下文或错配文档 id 都在模型回合开始前被拒); - 已锁定档案存在时:Code 回合不得携带档案/文档目标;Design 回合若档案或文档目标不匹配则抛
DesignProfileLockedError;匹配则返回锁定档案作为effectiveProfile; - 首次 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 决策):
- 有效的根
DESIGN.md(源码中root-design-md来源要求捕获sourceHash/sourceName与 ≤16 000 字符的内容投影,且 UI 要标明该项目的样式来源,见 design-task-profile.ts 与 spec); - 工作区 Design 默认(
workspace-default); - 无(
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:worktoken; - 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-sqlite3ABI、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 的文档恢复链,即可完整把握该功能的持久化语义与回放安全边界。