Kun 统一 Code/Design 任务面:从"顶层工作区"到"逐轮任务模式"的架构重构解读

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

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):

  1. 对话被割裂:同一主题的编码与设计任务被迫拆到不同工作区;
  2. Write 的定位被掩盖:Write 已扩展为覆盖 Markdown、PDF、图片及六种 Office 格式的办公工作区,名称不再贴切;
  3. 强制用户先选"应用形态":用户在描述任务之前就被迫在 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 的所有权,完整规则链如下:

  1. 解析会话级锁定任务面(resolveThreadLockedTaskSurface);若请求表面与锁定表面冲突 → 抛 TaskSurfaceLockedError;
  2. 遗留记录可在首个显式表面轮次时认领所有权;统一工作台线程在进入 Design 前已被创建为 Code 拥有;
  3. 校验 designProfile / designDocumentTarget 成对性与一致性,任一缺失即 TurnConflictError;
  4. Profile 只能在 Design 轮次提交;
  5. 若线程已有锁定 Profile:
    • Code 轮次提交 Profile/文档目标 → TurnConflictError;
    • Design 轮次提交不同 Profile → DesignProfileLockedError(携带 lockedAtTurnId 与锁定文档/画板 ID);
    • 省略 Profile 字段的后续 Design 轮次 → 复用锁定 Profile(effectiveProfile: lockedProfile);
  6. 无锁定 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 逐轮任务面的模型。理解这套设计,核心在于三组概念的分离:

  1. 线程所有权(thread.agentSurface)与逐轮任务面(turn 的 agentSurface)分离——线程稳定归属 Code,每轮可自由选择 Code/Design;
  2. 会话级锁定(仅遗留 write/design)与 Profile 级锁定(designProfile.lockedAtTurnId)分离——Code 对话唯一持久的锁定物是 Design Profile;
  3. 呈现层模式中立与运行时权威分离——任务列表不渲染会话级 Code/Design 标识,而每轮表面与 Profile 快照成为重载、队列恢复、重放与审计的持久权威。

对于希望在该仓库中进一步探索的读者,推荐按此路径阅读源码:先看 DesignTaskProfile 契约 与 ThreadSchema 中的 Profile 字段,再读准入实现 resolveDesignTurnAdmission 与模式推导 resolveThreadLockedTaskSurface,最后以 turn-service-task-surface-lock.test.ts 与 design-task-profile.test.ts 验证行为边界。

登录后查看全文
Kun