Kun 统一 Code/Design 任务面:从"顶层工作区"到"逐轮任务模式"的架构重构解读
Kun 统一 Code/Design 任务面:从"顶层工作区"到"逐轮任务模式"的架构重构解读
本篇文章基于 Kun 仓库中 unify-code-design-and-work 变更集 的正式规格文档(unified-code-design-tasks/spec.md)展开。Kun 是一个 Local-first 的 AI Agent 工作台,本文聚焦其将 Code 与 Design 由相互独立的顶层工作区,重构为同一个 Code 工作台内的"逐轮任务模式" 这一核心设计变更:读者将理解
thread.agentSurface与designProfile两个契约的分工、逐轮模式准入(admission)规则、Design 执行行为约束,以及空任务体验的设计要点,并能在源码中定位到每一处规则的实现与测试证据。
背景:为什么要统一 Code 与 Design
在重构之前,Kun 将 Code、Write、Design 呈现为三个顶层工作区,即使 Design 已经共享 Kun 的运行时、并且可以在 Code 右侧白板中渲染。这种结构带来了三个问题(见 proposal.md):
- 对话被割裂:同一主题的编码与设计任务被迫拆到不同工作区;
- Write 的定位被掩盖:Write 已扩展为覆盖 Markdown、PDF、图片及六种 Office 格式的办公工作区,名称不再贴切;
- 强制用户先选"应用形态":用户在描述任务之前就被迫在 Code 与 Design 之间做顶层选择。
因此该变更集的核心决策是:顶层导航只保留 Code | Work 两个工作区,Design 降级为 Code 工作台内的逐轮任务模式,同时保留稳定的内部 write 标识符与全部既有数据契约。
配套的四个规格文档共同定义了这次重构:
| 规格文档 | 主题 |
|---|---|
| unified-code-design-tasks/spec.md | 统一任务列表、逐轮 Code/Design 选择、固定 Design 执行行为 |
| thread-design-profile/spec.md | 线程级 Design Profile 的持久化、锁定、快照与 Fork |
| embedded-design-whiteboard/spec.md | Code 右侧白板内的完整 Design 画布与 HTML/AI 图像双输出通道 |
| work-product-surface/spec.md | Write 面向用户改名为 Work/办公的呈现层变更 |
核心契约一:Code 工作台持有"模式中立"的对话
规格的第一条要求是:Code 工作台拥有所有模式中立的对话。无论一个对话包含 Code 轮次、Design 轮次还是两者皆有,它都只出现一次在 Code 工作台的任务列表中,不会跳转到独立的 Design 路由(spec.md)。
这里的关键语义是 "会话行模式中立":任务列表不为对话行渲染 Code 图标、Design 图标或 Design 产物徽章;对话的"下一步模式"由 composer 逐轮决定,而不是由对话本身携带。同时满足以下场景:
- 共享任务列表:含 Code/Design 任一或混合轮次的对话,在 Code 工作台列表中只出现一次;
- 锁定的 Design Profile 不污染行级标识:即使对话已锁定 Design Profile,任务列表仍然中立渲染,Profile 只负责恢复其绑定的 Design 文档,与"下一轮模式"无关;
- 遗留 Design 对话保持可见:通过
agentSurface: 'design'或持久化 Design 线程注册表识别的项目级遗留对话,同样出现在统一任务列表中,但其运行时所有权与持久化文档绑定不会被改写; - 返回 Design 对话:用户选中 Design 对话、重载工作台或从其他工作区返回时,它仍是合法的 Code 工作台返回目标,并恢复其绑定文档,而不给整个对话打上 Design 标签;
- 顶层导航:工作区模式选择器中只含 Code 与 Work,不含独立 Design 标签页。
源码层面的"模式中立":resolveThreadLockedTaskSurface
"会话不持有模式"在运行时由领域函数 resolveThreadLockedTaskSurface 落地。它从持久的准入历史中推导会话级任务面,规则如下:
- 显式 Code 拥有的对话(
thread.agentSurface === 'code')→ 返回undefined,即没有会话级任务面锁,每轮各自选择; write/design遗留记录 → 保持其持久化的所有权;- 无显式所有权元数据的旧记录 → 从第一个已接受轮次的
agentSurface推导。
配套契约定义在 threads.ts:ThreadAgentSurface = z.enum(<a href="https://link.gitcode.com/i/b297ffa001c207aedbf209153bcb2f3c" target="_blank">'code', 'write', 'design']),而 ThreadSummary 中新增的 lockedTaskSurface 字段被明确定义为"从持久轮次历史推导的首个已接受 Code/Design 模式",仅用于遗留 write/design 记录([threads.ts)。
核心契约二:Code 与 Design 是逐轮任务面
规格的第二条要求是:composer 允许 Code 对话的每一轮选择 Code 或 Design(spec.md)。首次被接受的 Design 轮次会锁定 Design 文档、输出媒介、目标与风格快照,但 Code/Design 表面选择在后续轮次中始终保持可用。
逐轮语义的关键场景:
| 场景 | 行为 |
|---|---|
| 首条消息前选择 | 空对话(无已接受轮次)可在 Code/Design 间切换,不创建、替换、删除或重打标签线程 |
| 每轮都可选择 | 已有已接受轮次的 Code 对话,composer 仍为每个新轮次提供 Code/Design 选择 |
| Design 轮次后的 Code 轮次 | 带锁定 Design Profile 的对话提交 Code 轮次 → 被接受,不携带 Profile 或文档目标,不会以 task_surface_locked 失败 |
| 重新进入 Design | 复用已锁定的文档、输出媒介、目标与风格,不重复锁定 |
| 混合对话呈现 | 任务列表不从任何轮次推导会话级 Code/Design 身份;composer 继续控制下一轮模式 |
| 白板绑定跟随文档 | 绑定 Design 文档保持挂载与可引用,只由 designProfile.documentTarget 驱动,而非下一轮选择 |
| 准入失败保留选择 | 本地校验或运行时准入拒绝某轮时,草稿与选择器保持可编辑,不遗留已提交的空 Design 文档 |
| 首次 Design 发送激活新对话 | 空工作台发送首个 Design 轮次且新对话在 createThread 返回前已激活时,挂起的 Design 选择与临时文档保持有效,直到草稿绑定到新对话 |
| 线程所有权保持 Code | Design 轮次被接受时使用 Design 能力面,但 thread.agentSurface 保持 code |
实现细节:StartTurnRequest 的逐轮表面字段
逐轮选择在 HTTP/SSE 契约中体现为 StartTurnRequest 的三个字段:agentSurface(本轮产品面)、designProfile(首个 Design 轮次的候选 Profile)、designDocumentTarget(画布路由目标)。契约级校验强制:
designProfile与designDocumentTarget必须成对出现;designDocumentTarget必须与designProfile.documentTarget完全一致(documentId+boardArtifactId);- 携带
designProfile的轮次必须声明agentSurface: 'design'; designImagePlacementTarget只允许出现在outputMedium: 'image'的 Design Profile 上。
StartTurnResponse 同时回传 threadAgentSurface(持久的线程所有权)与 agentSurface(本轮的生效表面),两者被明确区分(turns.ts)。
运行时准入:resolveDesignTurnAdmission
逐轮选择在运行时由 resolveDesignTurnAdmission 强制执行,它在持每线程互斥锁时以原子方式决定任务面与 Profile 的所有权,完整规则链如下:
- 解析会话级锁定任务面(
resolveThreadLockedTaskSurface);若请求表面与锁定表面冲突 → 抛TaskSurfaceLockedError; - 遗留记录可在首个显式表面轮次时认领所有权;统一工作台线程在进入 Design 前已被创建为 Code 拥有;
- 校验
designProfile/designDocumentTarget成对性与一致性,任一缺失即TurnConflictError; - Profile 只能在 Design 轮次提交;
- 若线程已有锁定 Profile:
- Code 轮次提交 Profile/文档目标 →
TurnConflictError; - Design 轮次提交不同 Profile →
DesignProfileLockedError(携带lockedAtTurnId与锁定文档/画板 ID); - 省略 Profile 字段的后续 Design 轮次 → 复用锁定 Profile(
effectiveProfile: lockedProfile);
- Code 轮次提交 Profile/文档目标 →
- 无锁定 Profile 时,首个 Design 轮次必须提交完整 Profile 与文档目标,经 lockDesignTaskProfile 原子写入
lockedAtTurnId。
对应的测试覆盖在 turn-service-task-surface-lock.test.ts 中:包括首轮前两种模式均可、首轮 Code 之后进入 Design、混合历史逐轮切换、失败的临时 Design Profile 被忽略、design_profile_locked 冲突拒绝、后续 Design 轮次省略字段时复用锁定 Profile、Code 轮次携带 Profile 被拒绝等 8 个场景。
核心契约三:固定 Design 执行行为
规格第三条要求:Design 轮次必须使用 Design Agent/工具面,采用直接的 Agent 执行,同时保留共享的任务时间线、模型选择、权限与工作区控制;Design composer 不得暴露 Plan 模式、Graph 编排或 pursue-goal 控制(spec.md)。
三个确定性的执行场景:
- Design 任务提交:发送 Design 轮次 → 指向同一线程与 Design 文档、使用 Design 工具,不创建独立的 assistant 线程;
- 共享模型选择:在 Design 模式下修改对话模型 → 同一个 composer 模型控件(与 Code 共用)更新对话,不咨询独立的 Design 模型设置;
- Design 执行控件:选择 Design 轮次时,Plan 模式、Graph 编排与 pursue-goal 入口全部缺席,提交保持 Agent + 直接编排。
设计文档 design.md 进一步解释了原因:会话行保持视觉模式中立,因为 composer 选择描述的是下一轮而非整个对话;每轮的表面与可选 Design Profile 成为重载、队列恢复、扩展路由与审计的持久运行时权威。
核心契约四:空任务体验意图感知
规格第四条要求:Code 空状态使用一个 composer,内含 Code/Design 选择与类型特定的启动动作,并在执行开始后将同一个有状态 composer 移动到对话停靠区(spec.md)。
- Design 启动器:在空任务上选择 Design → 空状态提供 Design 导向的启动器与 Design Profile 控制,不渲染第二个独立 composer;
- 窄布局:工作台过窄无法显示完整标签时,任务/Profile 控件通过紧凑控件或单一响应式抽屉保持可访问。
实施任务清单 tasks.md 确认:空任务 Code/Design 选择器、任务特定启动器、以及用于输出媒介/Web-App/Design 预设的响应式 composer Profile 控件均已落地;首轮已接受后移除任务/Profile 选择器,保留共享的模型/工作区/权限控件,并从 Design 中省略 Code 专属的 Plan/Graph/goal 控件。
Design Profile:持久化契约与错误码
配套规格 thread-design-profile/spec.md 定义了 Design Profile 的持久化规则,核心要点:
- Profile 是 Code 线程上的可选持久契约:每个 Code 工作台对话最多持有一个锁定的 Design Profile,含文档绑定、画板目标、输出媒介、Web/App 目标、已解析风格快照、完整有界设计上下文快照与锁定轮次身份;
- Profile 跨重载存活:渲染器重载、重连、历史分页或恢复排队消息时,从运行时数据恢复锁定控件与画布目标,而非可变的全局 Design 设置;
- 冲突拒绝:后续 Design 轮次提交不同输出媒介/目标/风格/文档绑定 → 以
design_profile_locked拒绝,既有 Profile 保持不变; - 每轮快照:每个 Design 轮次及其用户条目记录生效 Profile 与文档目标,供审计、重放与画布路由使用——队列重试使用原始排队的 Profile 快照,画布重放只应用与活动 Design 任务匹配的操作;
- Fork 保持意图:Fork Design 任务保留锁定 Profile,但为其分配可独立写入的文档克隆;历史轮次 Fork 且该轮无文档快照时,在克隆前以明确的"不支持历史"错误失败,绝不把截断的聊天与未来的画布配对;
- 宽松读取遗留数据:Profile 解析对新写入严格、对缺失遗留字段宽容;缺少 Profile 元数据的遗留线程保持可读,不从无关遗留对话推断出新的 Design 任务。
契约结构:DesignTaskProfile
design-task-profile.ts 用 Zod 定义了完整的 Profile 结构:
// 输出媒介:HTML 是默认,AI 图像是独立主通道
export const DesignOutputMediumSchema = z.enum(['html', 'image'])
// Web/App 目标
export const DesignTargetSchema = z.enum(['web', 'app'])
// 复用 Kun 既有的设计系统预设目录
export const DesignSystemPresetSchema = z.enum([
'none', 'shadcn', 'radix', 'material', 'ios', 'fluent',
'ant', 'chakra', 'carbon', 'polaris', 'bootstrap',
'geist', 'brutalism', 'editorial'
])
// 持久化路由身份:一个 Design 任务对应一个可独立写入的画板
export const DesignDocumentTargetSchema = z.object({
documentId: DesignIdentifierSchema,
boardArtifactId: DesignIdentifierSchema
}).strict()
// 提交时的输入 Profile(无锁定轮次)
export const DesignTaskProfileInputSchema = z.object({
version: z.literal(1),
documentTarget: DesignDocumentTargetSchema,
outputMedium: DesignOutputMediumSchema,
target: DesignTargetSchema,
preset: DesignSystemPresetSchema,
presetSource: DesignPresetSourceSchema.optional(), // explicit | root-design-md | workspace-default | none
styleSnapshot: DesignStyleSnapshotSchema.optional(), // 仅 root-design-md 来源有效
canvasEngine: z.enum(['kun', 'excalidraw']).optional(),
context: DesignContextSnapshotSchema // 有界的 DesignContext 快照
}).strict()
// 运行时持有的不可变 Profile:在首个已接受轮次后存储
export const DesignTaskProfileSchema = DesignTaskProfileInputSchema.safeExtend({
lockedAtTurnId: z.string().trim().min(1).max(256)
}).strict()
值得注意的设计约束:styleSnapshot 仅在 presetSource: 'root-design-md' 时合法;DesignContextSnapshot 要求 tone 去重、字段长度有界——这是为了确保 Profile 是有界、可序列化、可审计的不可变契约。
错误码契约
错误契约 errors.ts 为这次重构注册了两个新的稳定错误码:task_surface_locked 与 design_profile_locked。tasks.md 第 12 节(tasks.md)确认:这两个 4xx 确定性拒绝只会失败一次,不会进入未知结果恢复循环。
Design 文档绑定与 Fork/恢复语义
线程契约 threads.ts 在 ThreadSchemaBase 中新增了三个字段:
agentSurface(可选):持久的产物面所有权,缺失时从同质轮次历史解析;designProfile(可选):不可变的 Design 任务契约,Code/Work/遗留线程缺失;designCloneOperation(可选):渲染器预制的独立 Design 克隆的幂等审计记录。
Fork 请求 ForkThreadRequest 支持 designDocumentTarget 与 designCloneOperationId(两者必须同时提供),且通过 .refine 强制 beforeTurn 必须携带 turnId。克隆实现位于 thread-service-core.ts:cloneTurnForThread 在克隆轮次时若提供 designDocumentTarget 且原轮次携带 designProfile,则用 retargetDesignTaskProfile 将 Profile 重定向到新的独立文档——意图保留,画布状态独立。
输出通道:HTML 默认与 AI 图像独立通道
配套规格 embedded-design-whiteboard/spec.md 定义了 Code 右侧白板内的完整 Design 表面,关键规则:
- HTML 是默认主输出:HTML 任务请求页面/应用屏幕时,右侧白板创建并预览链接的可交互 HTML 产物,而非普通 Code 画布帧;HTML 任务可使用生成图像作为支撑资源;
- AI 图像是独立主通道:
outputMedium: 'image'的任务完成后,生成的位图资源放置到活动白板,绝不静默回退为 HTML; - 确定性且可重放:AI 图像成功结果以幂等方式填充选中的空占位符或推荐槽位;SSE 重放时依据完成身份识别,不插入重复图像;
- 进度与失败可视化:进行中的生成显示持久占位符,成功时原位替换,失败/中止时显示可操作错误状态(原因、耗时、重试动作),永不回到空白;
- 生成感知布局:生成开始时白板自动打开,首次成功放置后执行一次 fit-to-content,支持聚焦/全宽呈现并保证最小可用宽度;
- 能力失败不改变任务意图:以运行时图像生成诊断为准;首次发送前诊断报告未启用 → AI 图像从输出选项中消失、未锁定的过期草稿回退 HTML;已锁定的 AI 图像对话丢失 Provider → 阻止提交、保留草稿并提供配置动作,对话保持 AI 图像;
- 风格解析与锁定:复用
DesignSystemPreset目录;Auto按"有效根DESIGN.md→ 工作区 Design 默认值 →none"确定性解析,解析结果快照进锁定 Profile;生成后文档持久化的设计系统成为权威,后续全局设置变更不能隐式重设样式。
迁移兼容:遗留对话与 Work 呈现别名
遗留 Design 对话零迁移
设计文档明确"非目标"包括:不迁移或删除遗留 Design 对话或 .kun-design 文件;不重命名 write 路由值、IPC 通道、设置键、扩展令牌、存储键或 Kun agent 表面(design.md)。项目级遗留对话由 agentSurface: 'design' 或持久化 Design 线程注册表识别,在统一任务列表中以一等条目出现,其既有注册表文档绑定保持权威;选中归属对话时,通过同一全量画布表面恢复原始可写 .kun-design 文档。这只改变呈现与导航:线程所有权、Profile、注册表与产物数据均不被迁移或复制。
Work 呈现别名
work-product-surface/spec.md 要求:所有用户可见的工作区导航、引导、设置、助手、空状态与知识库入口语言呈现为 Work/办公,而稳定内部标识符保持 write。要点包括:
- 升级用户打开 Work 看到同一份数据,不产生重复工作区或对话;
- Work 发送新轮次时渲染器与 Kun 继续使用
agentSurface: 'write'; - 已安装扩展对
workbench:write的贡献继续匹配 Work 表面,无需新workbench:work令牌; - 所有支持的语言环境提供 Work 产品标签,同时保留具体写作、润色、格式化与内联补全功能上的写作术语,且不重命名现有
write*i18n 键; - Work 的起始建议可提供总结、PDF 问答、表格分析、演示生成与文档讨论,但不得声称原生编辑 Word/Excel/PowerPoint。
验证证据与测试覆盖
tasks.md 记录了多轮评审修正(第 7~14 节),其中与本文规格直接相关的证据包括:
- 第 7 节(Review Remediation):区分 Code 工作台线程所有权与任务模式,首轮前允许 Code/Design 选择、之后由运行时准入强制;首个 Design Profile 准入重试安全且崩溃安全;遗留 standalone Design 记录与文档绑定在过渡期间不被迁移或删除;持久化根
DESIGN.md风格快照并识别来源。 - 第 12 节(Per-Turn Surface Correction):将"会话级互斥"替换为"逐轮表面选择":保持
thread.agentSurface: 'code',持久化每轮agentSurface,lockedTaskSurface仅作用于遗留write/design记录;准入接受 Code→Design→Code→Design,仅以design_profile_locked拒绝 Profile 不匹配,不再以task_surface_locked拒绝 Code 轮次。 - 第 13 节(Mode-Neutral Conversation Presentation):移除会话级 Code/Design 图标与 Design 产物徽章,保留单一共享任务列表、逐轮 composer 选择器与 Design 文档恢复。
- 测试数据:第 12 节显示 Kun 准入套件 12/12 通过(含新的
design_profile_locked与 Code 携带 Profile 冲突用例);第 13 节显示侧栏与渲染器逐轮任务面套件 19/19、Kun 准入/Profile 套件 21/21 通过;第 14 节 7 个聚焦渲染器文件 55/55 通过(含临时 Design 激活、宿主目标隔离、live/durable 重放与 Code 白板投递)。
总结
unify-code-design-and-work 变更集把 Kun 从"三个顶层工作区"收敛为 Code/Work 双顶层 + Design 逐轮任务面的模型。理解这套设计,核心在于三组概念的分离:
- 线程所有权(
thread.agentSurface)与逐轮任务面(turn 的agentSurface)分离——线程稳定归属 Code,每轮可自由选择 Code/Design; - 会话级锁定(仅遗留
write/design)与 Profile 级锁定(designProfile.lockedAtTurnId)分离——Code 对话唯一持久的锁定物是 Design Profile; - 呈现层模式中立与运行时权威分离——任务列表不渲染会话级 Code/Design 标识,而每轮表面与 Profile 快照成为重载、队列恢复、重放与审计的持久权威。
对于希望在该仓库中进一步探索的读者,推荐按此路径阅读源码:先看 DesignTaskProfile 契约 与 ThreadSchema 中的 Profile 字段,再读准入实现 resolveDesignTurnAdmission 与模式推导 resolveThreadLockedTaskSurface,最后以 turn-service-task-surface-lock.test.ts 与 design-task-profile.test.ts 验证行为边界。