人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本文以仓库权威设计文档 docs/design/zh-CN/foundations-and-runtime.md 为核心骨架深入解读 Kun前身 DeepSeek GUI的设计基础视觉令牌体系、设计原则、布局语法与核心运行时Kun runtime的架构原理、HTTP/SSE 边界、缓存优先的 Agent 循环与持久化模型并结合 kun/src 源码给出可验证的实现细节。读完本文你将掌握Kun 为什么把一个运行时、一个边界作为最高原则kun serve的命令行参数与路由表如何工作缓存优先的 Agent 循环如何通过不可变前缀与 InflightTracker 保证稳定与可观测以及线程、审批、沙箱与磁盘持久化之间的完整关系。1. 如何阅读这份设计文档双层结构Kun 的设计文档刻意采用双层结构这是理解整个项目设计哲学的钥匙YAML frontmatter文档顶部的---代码块机器可读的设计令牌——精确的十六进制色值、字体栈、间距刻度、圆角刻度、阴影、动效时长与组件配方。Stitch、Figma 插件以及未来的代码生成工具会逐字读取并应用这些值。修改任何值都必须同时更新 frontmatter 与src/renderer/src/styles/*.css/src/renderer/src/index.css保证运行中的应用与设计文档保持同步。Markdown 正文人类可读的why——设计意图、原则、反模式以及每个屏幕的规则。贡献者在判断一个新屏幕是否符合品牌形象时阅读这部分。两条原则frontmatter 是值的唯一事实来源source of truthMarkdown 是判断的唯一事实来源。二者冲突时frontmatter 优先Markdown 必须更新。2. 项目全貌三个工作区 一个运行时Kun 是一个围绕同名Kun 运行时构建的本地桌面工作台桌面外壳是 Electron运行时是 TypeScript 包并通过 HTTP/SSE 通信渲染层是 React 19 Zustand 5视觉系统是 TailwindCSS 3 之上手工构建的令牌层。产品不是又一个聊天外壳——它的存在是为了让真正的 Agent 在真实机器的真实项目里做真实工作而人类对每一次变更型调用保持介入in the loop。四个产品面共享同一个运行时与边界产品面要完成的工作Job to be doneCode绑定本地仓库通过工具调用、文件变更、命令与审查驱动 Agent。Design生成并迭代 UI 草稿、交互式 HTML 原型、设计图design graph以及可交接给 Code 的共享设计系统。Work面向 Markdown 及其他文档的办公工作区支持 FIM 补全和选区级联内联 Agent。Connect phone连接手机后台自动化飞书/Lark 频道、webhook/中继、定时任务。内部路由与存储名仍用claw以保持兼容。所有产品面共享同一条 Kun HTTP/SSE 边界、同一套设置API key、base URL、模型与同一套视觉系统。3. 六条设计原则产品已被如此构建这六条规则不是愿景而是产品已经如此构建的方式新屏幕必须遵循而非重新诠释一个运行时、一条边界。Code含 Design 任务、Work、Connect phone 全部通过kun serve运行在127.0.0.1:port上。渲染进程从不内嵌 Agent 循环也从不讲第二种协议——这让升级与调试保持无聊。本地优先、可观测、可控。设置、会话与运行时状态都存于操作系统 app-data 目录下的磁盘。每一次工具调用、文件变更、推理步骤都显示在 UI 中用户可随时打断、批准、拒绝或回滚。没有 Agent 切换器没有运行时控制台。产品刻意不暴露运行时诊断、供应商选择或模型控制面板。重要的运行时细节进 Settings不进主画布。渲染进程映射 HTTP不实现 Agent 逻辑。批准、转向steering、压缩compaction、fork、resume、usage 全部来自 Kun 端点绝不在 React 中重实现。稳定的视觉身份而非视觉新奇。新屏幕应该像现有屏幕的兄弟而不是全新实验。新组件靠取代多个现有组件来赢得位置而非增加一种新样式。默认平静Calm by default。默认表面是近白或近黑画布 克制的表面chrome 中无彩色唯一的强调色只出现在可操作元素上。状态色、危险色与 skill 色是仅有的其他可选颜色。4. 视觉系统令牌、颜色、字体与布局语法4.1 画布与表面两层的 4% 对比渲染进程在 chrome 之后绘制两层基础画布Base canvas--ds-bg-canvas亮色#ffffff/ 暗色#181818中央工作区聊天时间线、写作编辑器、文件树都在此。环绕表面Surrounding surface--ds-bg-main亮色#f5f7fa/ 暗色#101010应用外壳侧边栏、顶栏、检查器落于此。画布与表面的对比刻意很小——约 4%——让眼睛把二者读作同一个工作区而非两个区域。其上再叠加三层半透明玻璃表面ds-card卡片、列表行、popover 触发器、ds-elevated对话框、下拉、composer 外壳等必须抬离页面的元素、ds-subtle安静的次级表面如未激活的设置页签。玻璃效果通过backdrop-blur-xl24px加微弱inset 0 1px 0 rgba(255,255,255,0.45)高光实现顶栏携带 3 档垂直渐变topbar_gradient_light/topbar_gradient_dark读作一条柔和玻璃带body::after上的body_glaze_light/body_glaze_dark提供柔和的定向光而不引入新颜色。4.2 颜色强调色只做这些事强调色是电光蓝#0088ff亮色 /#339cff暗色只用于主操作按钮SendAllowSave、聚焦表单控件的边框 ring、表示活跃且正在做事的状态点、超链接式 chip 标签、选区背景--ds-selection。禁止用于大于 chip 的装饰性背景填充、正文或标题、禁用态禁用元素是opacity 0.45不改色。其他具名颜色各守语义--ds-success/--ds-success-soft完成的工具、缓存读取、OK 健康 ping--ds-danger/--ds-danger-soft失败的工具、被拒的批准、错误、重试徽标--ds-skill/--ds-skill-soft用户加载的 Skill 相关内容紫色 来自插件--ds-diff-added/--ds-diff-removed文件变更 diff 块是唯一允许并排出现在代码块上的颜色--ds-warning-soft非致命警告token 缓存缺失、待重试等。其余一切——文本、边框、画布、侧边栏——保持中性色板。如果一个屏幕需要的颜色超过强调色 这些具名语义色那大概率意味着信息架构应该先改。4.3 字体、间距、圆角、阴影与动效三个字体家族Sans正文为 SF Pro Text → PingFang SC → Noto Sans SC → Helvetica Neue → Arial覆盖中英双语与 macOS/Windows/LinuxDisplayhero、欢迎页为 SF Pro Display同 CJK 回退Mono 为 SF Mono → JetBrains Mono → IBM Plex Mono用于代码块、行内代码、kbd 提示、命令行、模型 id 与工具结果详情。字号只能用typography.size_rhythm刻度梯。间距使用 Tailwind 默认 4px 刻度。卡片 padding 是px-3 py-2紧凑或px-4 py-3常规px-5 py-4留给 hero 卡与全屏模态行内元素间距为gap-1到gap-3区块间距为mt-3到mt-6。三栏布局尺寸本身也是设计系统的一部分--ds-layout-left-sidebar-width。圆角柔和但不圆。顶栏 pill 控件rounded-full、主体rounded-xl/rounded-2xl卡片、composer 的单个超大rounded-[28px]外壳。两条硬规则可点击表面无直角最小 6px、卡片表面不全圆rounded-xl到rounded-3xl绝不 pill。阴影三级Card soft列表行、侧面板、页内 popover单一微弱阴影→ Card strong / panel模态、下拉、composer更深阴影 backdrop-blur-xl读作抬升的玻璃→ Shell主外壳、欢迎屏、设置根最深但极少使用。chip 与 pill 按钮带 inset 高光亮色inset 0 1px 0 rgba(255,255,255,0.78)。禁止彩色阴影所有阴影为黑色或近黑低 alpha。动效是功能性的确认点击 140ms、悬停态 150ms、路由/面板切换 200–300ms、活性指示状态点、流式 shimmer循环 1.8–2.4s。系统内仅有两个循环动画状态点与 work logo 的pulse以及流式助手文本的ds-shiny-text2.4s 线性 shimmer不是打字机。其余均为一次性动画对话框进出不超过 200ms 的 opacityscale不动画含多单元格的行不动画 composer。4.4 布局语法每个屏幕的宏文法Kun 的每个屏幕遵循同一套宏文法Topbar半透明条带含返回按钮、会话标题、模式切换器与右侧操作簇。顶栏始终可拖拽移动窗口内部交互元素必须用.ds-no-drag退出拖拽。左侧边栏Code 的工作区根 / Connect phone内部claw的频道 / Work 的空间。可折叠、可拖拽调宽默认 268px。中栏工作表面——Code/Connect phone 的消息时间线或 Work 的编辑器绝不允许渗入侧边栏。右侧检查器可选的上下文驱动面板——Changes、Todo、Browser、Plan、File、Work Assistant、SDD Assistant可拖拽调宽默认 360px。新屏幕必须适配这套文法如果适配不了说明文法需要成长且变更应先写进这份设计文档。4.5 文案、主题切换与 on-brand 快速测试双语字符串位于src/renderer/src/locales/{zh,en}/经react-i18next加载新字符串必须中英双语同时发布。语气直接、有帮助、略带主见产品自称用第一人称复数we ship Code, Work, and Connect phone对用户用第二人称。无 emoji、无营销语言错误消息是带标点结尾的完整句子绝不裸抛堆栈。产品名是 Kun前身 DeepSeek GUIbundled 运行时同名需要区分时说 Kun runtime手机/IM 面英文 Connect phone、中文 连接手机内部代码可仍叫claw但对外文案不暴露。主题切换system/light/dark三态在 Settings → General 选择。system监听prefers-color-scheme并实时更新主题以data-theme应用到htmlTailwinddark:变体与 CSS 自定义属性同时生效。UI 字号缩放独立small / medium / large作为 CSS--ds-ui-scale缩放因子应用。on-brand 快速测试合并前逐项勾选符合三栏 topbar 文法只用四族颜色中性、强调、状态、skill/diff只用三族字体与字号梯用圆角梯无可点击直角、无圆形卡片用阴影分级而非自定义阴影所有交互元素有焦点环ring-1 ring-accent/30字符串在中英两份 locale 中都存在无 emoji、无营销文案、无额外运行时表面无 Agent 切换器、无运行时诊断、无 legacy CodeWhale/Reasonix 导入。5. 顶层架构三层分离谁不做什么文档给出了四层架构图三层各自不做什么是刻进结构里的三条教训┌─────────────────────────────────────────────────────────────┐ │ Renderer (React 19 Zustand 5) │ │ AppShell → Workbench → (Code with Design tasks | Work | Connect phone) UI│ │ │ │ │ │ window.kunGui.runtimeRequest / startSse │ │ ▼ │ │ Preload (contextBridge, contextIsolated) │ │ kunGui.* IPC surface │ │ │ │ │ ▼ │ │ Main process (Node) │ │ RuntimeHost → kunRuntimeAdapter │ │ Settings / Connect phone runtime / Terminal / Updater / Logger│ │ │ │ │ │ spawn child process HTTP/SSE │ │ ▼ │ │ Kun (TypeScript package) │ │ serve --host 127.0.0.1 --port 18899 │ │ /health · /v1/* · SSE /v1/threads/{id}/events │ │ cache-first AgentLoop · ports adapters · append-only log │ │ │ │ │ │ HTTPS to model API │ │ ▼ │ │ DeepSeek (or OpenAI-compatible) chat/completions │ └─────────────────────────────────────────────────────────────┘渲染进程只知道 kun不知道自己在和哪个运行时说话。切换供应商不是产品表面而是主进程的关注点。主进程不实现 Agent 逻辑。它只负责 spawn 子进程、转发 HTTP、转发 SSE并拥有 GUI 专属服务设置、更新器、Connect phone 运行时、工作区文件、外部编辑器、Work 导出/补全供渲染进程按需请求。Kun 就是 Agent。循环、工具宿主、存储、模型客户端、服务器——全在一个进程里躲在一条 HTTP/SSE 边界后面。6. 核心运行时 Kun模块布局与六边形架构Kun 包kun/是唯一活跃的 Agent 运行时一个 TypeScript ESM 包自带 HTTP 服务器在 Electron 应用构建之前先构建。模块布局如下与文档一致可由 kun/src 目录结构验证kun/src/ cli/ # Command-line entrypoints (serve) contracts/ # Zod schemas and inferred types for HTTP/SSE domain/ # Thread, Turn, Item, Event, Approval, Usage entities ports/ # ModelClient, ToolHost, ThreadStore, SessionStore, # ApprovalGate, EventBus, WorkspaceInspector, Clock adapters/ # DeepSeek-compatible model client, local tool host, # in-memory and file-backed stores, workspace inspector services/ # Thread and turn orchestration services loop/ # Cache-first AgentLoop, InflightTracker, # SteeringQueue, ContextCompactor cache/ # ImmutablePrefix, LRU cache, TTL-LRU cache telemetry/ # Usage counter, cache telemetry server/ # HTTP server, router, auth, SSE, response helpers, # runtime-factory, route handlers prompt/ # System prompt for the Kun identity shared/ # Shared types with the GUIKun 按ports adapters端口与适配器组织contracts/是边界——Zod schema 描述每一个 HTTP/SSE DTOGUI 通过自己的 mappersrc/renderer/src/agent/kun-contract.ts间接导入domain/是实体Thread、Turn、Item、Event、Approval、Usage无 I/Oports/是接口——Agent 循环只认识ModelClient、ToolHost、ThreadStore、SessionStore、ApprovalGate、EventBus、WorkspaceInspector、Clock、IdGenerator这些接口刻意保持很小adapters/是具体实现——默认CompatModelClient讲POST {baseUrl}/v1/chat/completions形状默认LocalToolHost在进程内运行工具并做审批门控services/是编排——ThreadService与TurnService掌握线程与轮次的生命周期把存储、模型与工具接在一起loop/是 Agent 循环纯编排只依赖端口server/是暴露一切的薄 HTTP 传输层。设计规则新能力应该落为新端口 新适配器绝不做成直接伸手进循环的新 server handler——边界就是测试。7. 缓存优先的 Agent 循环不可变前缀、Inflight 与压缩文档中的缓存优先循环是围绕 DeepSeek 原生 cache hit/miss 遥测设计的其原理在 kun/src/loop 与 kun/src/cache 中有完整实现不可变前缀 sha256 指纹。system prompt、工具 schema、固定约束pinned constraints与 few-shots 组成前缀变更只能走setSystemPrompt、setTools、setPinnedConstraints、setFewShots见 kun/src/cache/immutable-prefix.ts这些 setter 会使指纹失效。每个模型步开始时调用verifyImmutablePrefix见 kun/src/loop/model-step-preparation-service.ts漂移会立即抛错——保证前缀绝对稳定是缓存命中率的地基。追加式会话日志。每一轮是一条 JSONL 流重放时跳过畸形行但保留其余索引是原子 JSON 写入。有界 TTL/LRU 缓存。工具、模型响应、计算出的指纹都显式驱逐。Inflight 跟踪与保证清理。kun/src/loop/inflight-tracker.ts 是 SSE 事件对的权威来源——每个begin对应一个tool_call_started/tool_call_finished对。其run(record, work)先注册 id执行 work并在finally中删除 id——即使 abort 也会清理循环绝不泄漏 id。end()与has()支撑起一事件必有一配对事件的可观测性契约。中途转向。SteeringQueuekun/src/loop/steering-queue.ts收集轮次运行期间用户发布的消息在下一个安全的循环边界注入为用户输入。上下文压缩。ContextCompactorkun/src/loop/context-compactor.ts把长历史折叠成单个compaction项始终保留不可变前缀中的固定约束。软阈值 16k tokens、硬阈值 24k tokens阈值来自DEFAULT_CONTEXT_THRESHOLDS与contextCompaction.defaultSoftThreshold/defaultHardThreshold可按模型上下文画像contextThresholdsForModel调整。工具配对修复。发历史给模型前Kun 丢弃孤儿tool_result与缺结果的工具调用避免 400/重试风暴。缓存命中率用 DeepSeek 原生的prompt_cache_hit_tokens/prompt_cache_miss_tokens字段报告为hit / (hit miss)兼容字段cached_tokens、cache_read_input_tokens仅作回退。文档给出一个健康的温线程应保持 ≥ 90% 命中率并记录了一次实测2026-06-0212 个短轮次温跑命中 94.7%同一温前缀上 24 个短轮次总体 95.2%最新一轮 98.1%。8. HTTP/SSE 表面认证、路由表与 SSE 协议Kun 的 HTTP 服务器基于手写Router支持:id参数。认证用Authorization: Bearer runtime-token--insecure仅限本地开发。完整的 CLI 选项可见 kun/src/cli/serve.ts 的SERVE_USAGE其中默认端口定义于 kun/src/cli/cli-options.tsDEFAULT_SERVE_PORT 18899schema 校验端口为 0–65535。parseServeOptions支持--keyvalue与--key value两种写法并按命令行 环境变量KUN_PORT、KUN_HOST、KUN_DATA_DIR、DEEPSEEK_API_KEY等 配置文件 默认值的优先级合并。路由表与文档一致由 server 层实现MethodPathPurposeGET/health免认证健康探针GET/v1/workspace/status?path…工作区的 git/branch 状态GET/v1/threads?includeside列出线程最新在前side默认隐藏POST/v1/threads创建线程GET/v1/threads/{id}读取线程 轮次PATCH/v1/threads/{id}更新标题/状态/审批/沙箱/关系DELETE/v1/threads/{id}删除线程POST/v1/threads/{id}/forkforkrelation 默认fork或sidePOST/v1/threads/{id}/turns开始一轮GET/v1/threads/{id}/turns/{turnId}读取一轮POST/v1/threads/{id}/turns/{turnId}/steer排队转向文本POST/v1/threads/{id}/turns/{turnId}/interrupt中止一轮POST/v1/threads/{id}/compact折叠旧历史GET/v1/threads/{id}/events?since_seqNSSE 积压 实时事件POST/v1/approvals/{id}allow / denyPOST/v1/user-inputs/{id}与/v1/user-input/{id}提交 / 取消用户输入回答POST/v1/sessions/{id}/resume-thread将会话恢复进线程GET/v1/usage累计 token / cache / 轮次计数器SSE 帧格式id: seq、event: kind、JSONdata:。晚加入的客户端传since_seq或Last-Event-ID先收积压再收实时事件每 15 秒一条心跳保持空闲代理存活。事件对的权威来源正是第 7 节的InflightTracker。9. 线程记录与关系primary / fork / side每个线程持久化在{data-dir}/threads/{id}/thread.json携带relation元数据primary——顶层线程默认fork——手动 fork把用户切换到新线程side——继承自父快照的顺带侧对话。默认不出现在线程列表需?includeside才显示带parentThreadId提升回primary时清除。fork与side谱系还记录forkedFromThreadId、forkedFromTitle、forkedAt以及 fork 时的消息/轮次计数GUI 在侧边栏中呈现这些信息。10. 审批与沙箱两层门控与模式限定ToolHostContext携带approvalPolicy工具宿主在两层门控policy: never直接前置拦截on-request/suggest/untrusted总是提示除非调用在allowList中。需要限定模式mode的工具如create_plan只在plan线程内可用声明shouldAdvertise(ctx)谓词同时过滤工具列表与执行。SandboxModeread-only/workspace-write/danger-full-access/external-sandbox由工作区检查器与文件/工具适配器强制执行。对应的 CLI 参数在SERVE_USAGE中--approval-policy pon-request | untrusted | never | auto | suggest、--sandbox-mode mode、--approval-reviewer ruser | agent。11. 持久化--data-dir与原子写入--data-dir是运行时拥有的一切的磁盘根目录必填缺省时serve直接报错退出码 78见 kun/src/cli/serve.ts 的parseServeOptionsSafe{data-dir}/ threads/ index.json {threadId}/ thread.json # ThreadRecord messages.jsonl # TurnItem append-only events.jsonl # RuntimeEvent append-only session.json # latest AgentSession projectionindex.json、thread.json、session.json使用原子 JSON 写入JSONL 流容忍畸形行下次重放跳过。此外serve还支持--storage-backend hybrid|file与--sqlite-path切换混合存储后端以及--observability系列参数JSONL 或 OTLP HTTP/JSON 导出器输出脱敏的 OpenTelemetry 风格 Agent span。12. 结语一份既规范又描述实现的权威文档Kun 的 docs/design/zh-CN/foundations-and-runtime.md 的特殊之处在于它既是设计规范YAML 令牌 视觉规则 on-brand 检查表又是运行时架构文档模块布局、六边形边界、缓存优先循环、路由表、持久化布局且与 kun/src 源码一一对应。开发者若想深入可以从 kun/src/cli/serve.tsCLI 与参数解析、kun/src/loop/inflight-tracker.tsSSE 事件配对契约、kun/src/cache/immutable-prefix.ts缓存命中率地基与 kun/src/loop/context-compactor.ts上下文压缩四条路径切入结合kun serve的SERVE_USAGE与DEFAULT_SERVE_PORT 18899即可在本地复现文档描述的完整运行时。赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐Kun 单运行时架构实战指南统一 HTTP/SSE 边界的 Agent 运行时、缓存优化与扩展规范Kun 单运行时架构实战指南统一 HTTP/SSE 边界的 Agent 运行时、缓存优化与扩展规范 Kun 桌面应用Electron React T人工智能AI Agent自主智能体桌面应用MCP ClientsKun 扩展平台设计为本地优先 AI Agent 工作台构建完整的扩展契约Kun 扩展平台设计为本地优先 AI Agent 工作台构建完整的扩展契约 本文基于 Kun 仓库中已确认的设计变更文档 build kun extensio人工智能AI Agent自主智能体桌面应用MCP ClientsKun 本地优先 AI Agent 工作台实战指南GUI 与 TUI 共享运行时从目标到验收的完整工作流Kun 本地优先 AI Agent 工作台实战指南GUI 与 TUI 共享运行时从目标到验收的完整工作流 Kun 是一个本地优先的 AI Agent 工作台人工智能AI Agent自主智能体桌面应用MCP Clients上一篇ao doctor 健康检查命令全解析用 agent-orchestrator 排查 AO 环境配置问题下一篇Bunyan无阻塞日志写入Node.js事件循环优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本文以仓库权威设计文档 docs/design/zh-CN/foundations-and-runtime.md 为核心骨架深入解读 Kun前身 DeepSeek GUI的设计基础视觉令牌体系、设计原则、布局语法与核心运行时Kun runtime的架构原理、HTTP/SSE 边界、缓存优先的 Agent 循环与持久化模型并结合 kun/src 源码给出可验证的实现细节。读完本文你将掌握Kun 为什么把一个运行时、一个边界作为最高原则kun serve的命令行参数与路由表如何工作缓存优先的 Agent 循环如何通过不可变前缀与 InflightTracker 保证稳定与可观测以及线程、审批、沙箱与磁盘持久化之间的完整关系。1. 如何阅读这份设计文档双层结构Kun 的设计文档刻意采用双层结构这是理解整个项目设计哲学的钥匙YAML frontmatter文档顶部的---代码块机器可读的设计令牌——精确的十六进制色值、字体栈、间距刻度、圆角刻度、阴影、动效时长与组件配方。Stitch、Figma 插件以及未来的代码生成工具会逐字读取并应用这些值。修改任何值都必须同时更新 frontmatter 与src/renderer/src/styles/*.css/src/renderer/src/index.css保证运行中的应用与设计文档保持同步。Markdown 正文人类可读的why——设计意图、原则、反模式以及每个屏幕的规则。贡献者在判断一个新屏幕是否符合品牌形象时阅读这部分。两条原则frontmatter 是值的唯一事实来源source of truthMarkdown 是判断的唯一事实来源。二者冲突时frontmatter 优先Markdown 必须更新。2. 项目全貌三个工作区 一个运行时Kun 是一个围绕同名Kun 运行时构建的本地桌面工作台桌面外壳是 Electron运行时是 TypeScript 包并通过 HTTP/SSE 通信渲染层是 React 19 Zustand 5视觉系统是 TailwindCSS 3 之上手工构建的令牌层。产品不是又一个聊天外壳——它的存在是为了让真正的 Agent 在真实机器的真实项目里做真实工作而人类对每一次变更型调用保持介入in the loop。四个产品面共享同一个运行时与边界产品面要完成的工作Job to be doneCode绑定本地仓库通过工具调用、文件变更、命令与审查驱动 Agent。Design生成并迭代 UI 草稿、交互式 HTML 原型、设计图design graph以及可交接给 Code 的共享设计系统。Work面向 Markdown 及其他文档的办公工作区支持 FIM 补全和选区级联内联 Agent。Connect phone连接手机后台自动化飞书/Lark 频道、webhook/中继、定时任务。内部路由与存储名仍用claw以保持兼容。所有产品面共享同一条 Kun HTTP/SSE 边界、同一套设置API key、base URL、模型与同一套视觉系统。3. 六条设计原则产品已被如此构建这六条规则不是愿景而是产品已经如此构建的方式新屏幕必须遵循而非重新诠释一个运行时、一条边界。Code含 Design 任务、Work、Connect phone 全部通过kun serve运行在127.0.0.1:port上。渲染进程从不内嵌 Agent 循环也从不讲第二种协议——这让升级与调试保持无聊。本地优先、可观测、可控。设置、会话与运行时状态都存于操作系统 app-data 目录下的磁盘。每一次工具调用、文件变更、推理步骤都显示在 UI 中用户可随时打断、批准、拒绝或回滚。没有 Agent 切换器没有运行时控制台。产品刻意不暴露运行时诊断、供应商选择或模型控制面板。重要的运行时细节进 Settings不进主画布。渲染进程映射 HTTP不实现 Agent 逻辑。批准、转向steering、压缩compaction、fork、resume、usage 全部来自 Kun 端点绝不在 React 中重实现。稳定的视觉身份而非视觉新奇。新屏幕应该像现有屏幕的兄弟而不是全新实验。新组件靠取代多个现有组件来赢得位置而非增加一种新样式。默认平静Calm by default。默认表面是近白或近黑画布 克制的表面chrome 中无彩色唯一的强调色只出现在可操作元素上。状态色、危险色与 skill 色是仅有的其他可选颜色。4. 视觉系统令牌、颜色、字体与布局语法4.1 画布与表面两层的 4% 对比渲染进程在 chrome 之后绘制两层基础画布Base canvas--ds-bg-canvas亮色#ffffff/ 暗色#181818中央工作区聊天时间线、写作编辑器、文件树都在此。环绕表面Surrounding surface--ds-bg-main亮色#f5f7fa/ 暗色#101010应用外壳侧边栏、顶栏、检查器落于此。画布与表面的对比刻意很小——约 4%——让眼睛把二者读作同一个工作区而非两个区域。其上再叠加三层半透明玻璃表面ds-card卡片、列表行、popover 触发器、ds-elevated对话框、下拉、composer 外壳等必须抬离页面的元素、ds-subtle安静的次级表面如未激活的设置页签。玻璃效果通过backdrop-blur-xl24px加微弱inset 0 1px 0 rgba(255,255,255,0.45)高光实现顶栏携带 3 档垂直渐变topbar_gradient_light/topbar_gradient_dark读作一条柔和玻璃带body::after上的body_glaze_light/body_glaze_dark提供柔和的定向光而不引入新颜色。4.2 颜色强调色只做这些事强调色是电光蓝#0088ff亮色 /#339cff暗色只用于主操作按钮SendAllowSave、聚焦表单控件的边框 ring、表示活跃且正在做事的状态点、超链接式 chip 标签、选区背景--ds-selection。禁止用于大于 chip 的装饰性背景填充、正文或标题、禁用态禁用元素是opacity 0.45不改色。其他具名颜色各守语义--ds-success/--ds-success-soft完成的工具、缓存读取、OK 健康 ping--ds-danger/--ds-danger-soft失败的工具、被拒的批准、错误、重试徽标--ds-skill/--ds-skill-soft用户加载的 Skill 相关内容紫色 来自插件--ds-diff-added/--ds-diff-removed文件变更 diff 块是唯一允许并排出现在代码块上的颜色--ds-warning-soft非致命警告token 缓存缺失、待重试等。其余一切——文本、边框、画布、侧边栏——保持中性色板。如果一个屏幕需要的颜色超过强调色 这些具名语义色那大概率意味着信息架构应该先改。4.3 字体、间距、圆角、阴影与动效三个字体家族Sans正文为 SF Pro Text → PingFang SC → Noto Sans SC → Helvetica Neue → Arial覆盖中英双语与 macOS/Windows/LinuxDisplayhero、欢迎页为 SF Pro Display同 CJK 回退Mono 为 SF Mono → JetBrains Mono → IBM Plex Mono用于代码块、行内代码、kbd 提示、命令行、模型 id 与工具结果详情。字号只能用typography.size_rhythm刻度梯。间距使用 Tailwind 默认 4px 刻度。卡片 padding 是px-3 py-2紧凑或px-4 py-3常规px-5 py-4留给 hero 卡与全屏模态行内元素间距为gap-1到gap-3区块间距为mt-3到mt-6。三栏布局尺寸本身也是设计系统的一部分--ds-layout-left-sidebar-width。圆角柔和但不圆。顶栏 pill 控件rounded-full、主体rounded-xl/rounded-2xl卡片、composer 的单个超大rounded-[28px]外壳。两条硬规则可点击表面无直角最小 6px、卡片表面不全圆rounded-xl到rounded-3xl绝不 pill。阴影三级Card soft列表行、侧面板、页内 popover单一微弱阴影→ Card strong / panel模态、下拉、composer更深阴影 backdrop-blur-xl读作抬升的玻璃→ Shell主外壳、欢迎屏、设置根最深但极少使用。chip 与 pill 按钮带 inset 高光亮色inset 0 1px 0 rgba(255,255,255,0.78)。禁止彩色阴影所有阴影为黑色或近黑低 alpha。动效是功能性的确认点击 140ms、悬停态 150ms、路由/面板切换 200–300ms、活性指示状态点、流式 shimmer循环 1.8–2.4s。系统内仅有两个循环动画状态点与 work logo 的pulse以及流式助手文本的ds-shiny-text2.4s 线性 shimmer不是打字机。其余均为一次性动画对话框进出不超过 200ms 的 opacityscale不动画含多单元格的行不动画 composer。4.4 布局语法每个屏幕的宏文法Kun 的每个屏幕遵循同一套宏文法Topbar半透明条带含返回按钮、会话标题、模式切换器与右侧操作簇。顶栏始终可拖拽移动窗口内部交互元素必须用.ds-no-drag退出拖拽。左侧边栏Code 的工作区根 / Connect phone内部claw的频道 / Work 的空间。可折叠、可拖拽调宽默认 268px。中栏工作表面——Code/Connect phone 的消息时间线或 Work 的编辑器绝不允许渗入侧边栏。右侧检查器可选的上下文驱动面板——Changes、Todo、Browser、Plan、File、Work Assistant、SDD Assistant可拖拽调宽默认 360px。新屏幕必须适配这套文法如果适配不了说明文法需要成长且变更应先写进这份设计文档。4.5 文案、主题切换与 on-brand 快速测试双语字符串位于src/renderer/src/locales/{zh,en}/经react-i18next加载新字符串必须中英双语同时发布。语气直接、有帮助、略带主见产品自称用第一人称复数we ship Code, Work, and Connect phone对用户用第二人称。无 emoji、无营销语言错误消息是带标点结尾的完整句子绝不裸抛堆栈。产品名是 Kun前身 DeepSeek GUIbundled 运行时同名需要区分时说 Kun runtime手机/IM 面英文 Connect phone、中文 连接手机内部代码可仍叫claw但对外文案不暴露。主题切换system/light/dark三态在 Settings → General 选择。system监听prefers-color-scheme并实时更新主题以data-theme应用到htmlTailwinddark:变体与 CSS 自定义属性同时生效。UI 字号缩放独立small / medium / large作为 CSS--ds-ui-scale缩放因子应用。on-brand 快速测试合并前逐项勾选符合三栏 topbar 文法只用四族颜色中性、强调、状态、skill/diff只用三族字体与字号梯用圆角梯无可点击直角、无圆形卡片用阴影分级而非自定义阴影所有交互元素有焦点环ring-1 ring-accent/30字符串在中英两份 locale 中都存在无 emoji、无营销文案、无额外运行时表面无 Agent 切换器、无运行时诊断、无 legacy CodeWhale/Reasonix 导入。5. 顶层架构三层分离谁不做什么文档给出了四层架构图三层各自不做什么是刻进结构里的三条教训┌─────────────────────────────────────────────────────────────┐ │ Renderer (React 19 Zustand 5) │ │ AppShell → Workbench → (Code with Design tasks | Work | Connect phone) UI│ │ │ │ │ │ window.kunGui.runtimeRequest / startSse │ │ ▼ │ │ Preload (contextBridge, contextIsolated) │ │ kunGui.* IPC surface │ │ │ │ │ ▼ │ │ Main process (Node) │ │ RuntimeHost → kunRuntimeAdapter │ │ Settings / Connect phone runtime / Terminal / Updater / Logger│ │ │ │ │ │ spawn child process HTTP/SSE │ │ ▼ │ │ Kun (TypeScript package) │ │ serve --host 127.0.0.1 --port 18899 │ │ /health · /v1/* · SSE /v1/threads/{id}/events │ │ cache-first AgentLoop · ports adapters · append-only log │ │ │ │ │ │ HTTPS to model API │ │ ▼ │ │ DeepSeek (or OpenAI-compatible) chat/completions │ └─────────────────────────────────────────────────────────────┘渲染进程只知道 kun不知道自己在和哪个运行时说话。切换供应商不是产品表面而是主进程的关注点。主进程不实现 Agent 逻辑。它只负责 spawn 子进程、转发 HTTP、转发 SSE并拥有 GUI 专属服务设置、更新器、Connect phone 运行时、工作区文件、外部编辑器、Work 导出/补全供渲染进程按需请求。Kun 就是 Agent。循环、工具宿主、存储、模型客户端、服务器——全在一个进程里躲在一条 HTTP/SSE 边界后面。6. 核心运行时 Kun模块布局与六边形架构Kun 包kun/是唯一活跃的 Agent 运行时一个 TypeScript ESM 包自带 HTTP 服务器在 Electron 应用构建之前先构建。模块布局如下与文档一致可由 kun/src 目录结构验证kun/src/ cli/ # Command-line entrypoints (serve) contracts/ # Zod schemas and inferred types for HTTP/SSE domain/ # Thread, Turn, Item, Event, Approval, Usage entities ports/ # ModelClient, ToolHost, ThreadStore, SessionStore, # ApprovalGate, EventBus, WorkspaceInspector, Clock adapters/ # DeepSeek-compatible model client, local tool host, # in-memory and file-backed stores, workspace inspector services/ # Thread and turn orchestration services loop/ # Cache-first AgentLoop, InflightTracker, # SteeringQueue, ContextCompactor cache/ # ImmutablePrefix, LRU cache, TTL-LRU cache telemetry/ # Usage counter, cache telemetry server/ # HTTP server, router, auth, SSE, response helpers, # runtime-factory, route handlers prompt/ # System prompt for the Kun identity shared/ # Shared types with the GUIKun 按ports adapters端口与适配器组织contracts/是边界——Zod schema 描述每一个 HTTP/SSE DTOGUI 通过自己的 mappersrc/renderer/src/agent/kun-contract.ts间接导入domain/是实体Thread、Turn、Item、Event、Approval、Usage无 I/Oports/是接口——Agent 循环只认识ModelClient、ToolHost、ThreadStore、SessionStore、ApprovalGate、EventBus、WorkspaceInspector、Clock、IdGenerator这些接口刻意保持很小adapters/是具体实现——默认CompatModelClient讲POST {baseUrl}/v1/chat/completions形状默认LocalToolHost在进程内运行工具并做审批门控services/是编排——ThreadService与TurnService掌握线程与轮次的生命周期把存储、模型与工具接在一起loop/是 Agent 循环纯编排只依赖端口server/是暴露一切的薄 HTTP 传输层。设计规则新能力应该落为新端口 新适配器绝不做成直接伸手进循环的新 server handler——边界就是测试。7. 缓存优先的 Agent 循环不可变前缀、Inflight 与压缩文档中的缓存优先循环是围绕 DeepSeek 原生 cache hit/miss 遥测设计的其原理在 kun/src/loop 与 kun/src/cache 中有完整实现不可变前缀 sha256 指纹。system prompt、工具 schema、固定约束pinned constraints与 few-shots 组成前缀变更只能走setSystemPrompt、setTools、setPinnedConstraints、setFewShots见 kun/src/cache/immutable-prefix.ts这些 setter 会使指纹失效。每个模型步开始时调用verifyImmutablePrefix见 kun/src/loop/model-step-preparation-service.ts漂移会立即抛错——保证前缀绝对稳定是缓存命中率的地基。追加式会话日志。每一轮是一条 JSONL 流重放时跳过畸形行但保留其余索引是原子 JSON 写入。有界 TTL/LRU 缓存。工具、模型响应、计算出的指纹都显式驱逐。Inflight 跟踪与保证清理。kun/src/loop/inflight-tracker.ts 是 SSE 事件对的权威来源——每个begin对应一个tool_call_started/tool_call_finished对。其run(record, work)先注册 id执行 work并在finally中删除 id——即使 abort 也会清理循环绝不泄漏 id。end()与has()支撑起一事件必有一配对事件的可观测性契约。中途转向。SteeringQueuekun/src/loop/steering-queue.ts收集轮次运行期间用户发布的消息在下一个安全的循环边界注入为用户输入。上下文压缩。ContextCompactorkun/src/loop/context-compactor.ts把长历史折叠成单个compaction项始终保留不可变前缀中的固定约束。软阈值 16k tokens、硬阈值 24k tokens阈值来自DEFAULT_CONTEXT_THRESHOLDS与contextCompaction.defaultSoftThreshold/defaultHardThreshold可按模型上下文画像contextThresholdsForModel调整。工具配对修复。发历史给模型前Kun 丢弃孤儿tool_result与缺结果的工具调用避免 400/重试风暴。缓存命中率用 DeepSeek 原生的prompt_cache_hit_tokens/prompt_cache_miss_tokens字段报告为hit / (hit miss)兼容字段cached_tokens、cache_read_input_tokens仅作回退。文档给出一个健康的温线程应保持 ≥ 90% 命中率并记录了一次实测2026-06-0212 个短轮次温跑命中 94.7%同一温前缀上 24 个短轮次总体 95.2%最新一轮 98.1%。8. HTTP/SSE 表面认证、路由表与 SSE 协议Kun 的 HTTP 服务器基于手写Router支持:id参数。认证用Authorization: Bearer runtime-token--insecure仅限本地开发。完整的 CLI 选项可见 kun/src/cli/serve.ts 的SERVE_USAGE其中默认端口定义于 kun/src/cli/cli-options.tsDEFAULT_SERVE_PORT 18899schema 校验端口为 0–65535。parseServeOptions支持--keyvalue与--key value两种写法并按命令行 环境变量KUN_PORT、KUN_HOST、KUN_DATA_DIR、DEEPSEEK_API_KEY等 配置文件 默认值的优先级合并。路由表与文档一致由 server 层实现MethodPathPurposeGET/health免认证健康探针GET/v1/workspace/status?path…工作区的 git/branch 状态GET/v1/threads?includeside列出线程最新在前side默认隐藏POST/v1/threads创建线程GET/v1/threads/{id}读取线程 轮次PATCH/v1/threads/{id}更新标题/状态/审批/沙箱/关系DELETE/v1/threads/{id}删除线程POST/v1/threads/{id}/forkforkrelation 默认fork或sidePOST/v1/threads/{id}/turns开始一轮GET/v1/threads/{id}/turns/{turnId}读取一轮POST/v1/threads/{id}/turns/{turnId}/steer排队转向文本POST/v1/threads/{id}/turns/{turnId}/interrupt中止一轮POST/v1/threads/{id}/compact折叠旧历史GET/v1/threads/{id}/events?since_seqNSSE 积压 实时事件POST/v1/approvals/{id}allow / denyPOST/v1/user-inputs/{id}与/v1/user-input/{id}提交 / 取消用户输入回答POST/v1/sessions/{id}/resume-thread将会话恢复进线程GET/v1/usage累计 token / cache / 轮次计数器SSE 帧格式id: seq、event: kind、JSONdata:。晚加入的客户端传since_seq或Last-Event-ID先收积压再收实时事件每 15 秒一条心跳保持空闲代理存活。事件对的权威来源正是第 7 节的InflightTracker。9. 线程记录与关系primary / fork / side每个线程持久化在{data-dir}/threads/{id}/thread.json携带relation元数据primary——顶层线程默认fork——手动 fork把用户切换到新线程side——继承自父快照的顺带侧对话。默认不出现在线程列表需?includeside才显示带parentThreadId提升回primary时清除。fork与side谱系还记录forkedFromThreadId、forkedFromTitle、forkedAt以及 fork 时的消息/轮次计数GUI 在侧边栏中呈现这些信息。10. 审批与沙箱两层门控与模式限定ToolHostContext携带approvalPolicy工具宿主在两层门控policy: never直接前置拦截on-request/suggest/untrusted总是提示除非调用在allowList中。需要限定模式mode的工具如create_plan只在plan线程内可用声明shouldAdvertise(ctx)谓词同时过滤工具列表与执行。SandboxModeread-only/workspace-write/danger-full-access/external-sandbox由工作区检查器与文件/工具适配器强制执行。对应的 CLI 参数在SERVE_USAGE中--approval-policy pon-request | untrusted | never | auto | suggest、--sandbox-mode mode、--approval-reviewer ruser | agent。11. 持久化--data-dir与原子写入--data-dir是运行时拥有的一切的磁盘根目录必填缺省时serve直接报错退出码 78见 kun/src/cli/serve.ts 的parseServeOptionsSafe{data-dir}/ threads/ index.json {threadId}/ thread.json # ThreadRecord messages.jsonl # TurnItem append-only events.jsonl # RuntimeEvent append-only session.json # latest AgentSession projectionindex.json、thread.json、session.json使用原子 JSON 写入JSONL 流容忍畸形行下次重放跳过。此外serve还支持--storage-backend hybrid|file与--sqlite-path切换混合存储后端以及--observability系列参数JSONL 或 OTLP HTTP/JSON 导出器输出脱敏的 OpenTelemetry 风格 Agent span。12. 结语一份既规范又描述实现的权威文档Kun 的 docs/design/zh-CN/foundations-and-runtime.md 的特殊之处在于它既是设计规范YAML 令牌 视觉规则 on-brand 检查表又是运行时架构文档模块布局、六边形边界、缓存优先循环、路由表、持久化布局且与 kun/src 源码一一对应。开发者若想深入可以从 kun/src/cli/serve.tsCLI 与参数解析、kun/src/loop/inflight-tracker.tsSSE 事件配对契约、kun/src/cache/immutable-prefix.ts缓存命中率地基与 kun/src/loop/context-compactor.ts上下文压缩四条路径切入结合kun serve的SERVE_USAGE与DEFAULT_SERVE_PORT 18899即可在本地复现文档描述的完整运行时。赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐Kun 单运行时架构实战指南统一 HTTP/SSE 边界的 Agent 运行时、缓存优化与扩展规范Kun 单运行时架构实战指南统一 HTTP/SSE 边界的 Agent 运行时、缓存优化与扩展规范 Kun 桌面应用Electron React T人工智能AI Agent自主智能体桌面应用MCP ClientsKun 扩展平台设计为本地优先 AI Agent 工作台构建完整的扩展契约Kun 扩展平台设计为本地优先 AI Agent 工作台构建完整的扩展契约 本文基于 Kun 仓库中已确认的设计变更文档 build kun extensio人工智能AI Agent自主智能体桌面应用MCP ClientsKun 本地优先 AI Agent 工作台实战指南GUI 与 TUI 共享运行时从目标到验收的完整工作流Kun 本地优先 AI Agent 工作台实战指南GUI 与 TUI 共享运行时从目标到验收的完整工作流 Kun 是一个本地优先的 AI Agent 工作台人工智能AI Agent自主智能体桌面应用MCP Clients上一篇ao doctor 健康检查命令全解析用 agent-orchestrator 排查 AO 环境配置问题下一篇Bunyan无阻塞日志写入Node.js事件循环优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
