DeepSeek Harness 输入坞（Input Dock）上下文卡片堆叠顺序契约：Composer 上方 Goal / Todo / Queue 的组合矩阵与 5px 贴合设计

DeepSeek Harness 输入坞Input Dock上下文卡片堆叠顺序契约Composer 上方 Goal / Todo / Queue 的组合矩阵与 5px 贴合设计【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness导读在 DeepSeek Harness 的会话输入区Goal目标条、Todo待办面板与 Queue消息队列坞会以上下文卡片的形式独立注册到同一个conversation.input.dock列表槽位最终堆叠在消息 Composer输入卡片上方。本篇文章基于仓库中的实现决策笔记 2026-07-30-composer-context-stack-order.md完整讲解这套堆叠顺序契约三张卡片如何通过注册顺序建立语义层级、如何通过 CSS 变量统一共享几何间距、Queue 为何是唯一与 Composer 边界发生 5px 贴合的表面以及新插件接入该槽位时应遵循的 order 约定Todo0、Goal10、Queue20。读完你将掌握 DeepSeek Harness 前端可扩展输入坞的插槽注册机制、堆叠顺序与间距分离的架构原则以及如何为自己的输入坞插件选择正确位置与边界归属。问题三张卡片共享同一个列表却编码不出组合矩阵DeepSeek Harness 采用一切皆插件Everything is a Plugin的架构会话输入区的上下文表面context surfaces也不例外。Goal、Todo、Queue 三者相互独立地贡献到同一个conversation.input.dock列表理论上该列表的顺序应该完整表达设计稿Figma中的组合矩阵composition matrix——即任意子集组合下卡片的先后关系。但最初的实现存在两个缺陷注册顺序未编码语义层级Goal、Todo、Queue 各自的注册顺序与间距规则没有表达组合矩阵渲染层实际把 Todo 排在了 Queue 与 Goal 之前负外边距错位Queue 与 Goal 都携带了为 Composer 边界准备的负外边距。当三者同时在场时Queue 与 Goal 各自向下吸附最终结果是Queue 贴上了 Goal、Goal 贴上了 Composer把设计稿规定的层级关系完全反转了。也就是说间距规则spacing是写在卡片自身上的局部样式而谁允许与谁贴合本应是组合矩阵semantic order层面的全局决策。局部负外边距无法表达这种贴合关系在何种槽位顺序下才是合法的。决策顺序与间距解耦Composer 随列表其后修复后的方案将两件事彻底分离顺序order由注册顺序建立语义层级间距geometry由堆叠栈上的 CSS 变量建立共享几何。顺序契约数值间隙为未来条目留位决策笔记明确引用了后续的 Todo-first 对齐决策当前采用升序排列。数字上的间隙numeric gaps用于为未来的新条目预留声明位置的余地新插件无需依赖插件激活顺序即可表达自己希望出现的位置。该契约由三处注册代码落实坞条目注册 idorder 值注册位置源码Todotodo0TodoPanel.tsx 中todoDockEntry.applyGoalgoal10ui-goal/src/client/index.ts 中conversation.input.dock注册块Queuequeue20QueueDock.tsx 中queueDockEntry.apply以 Todo 为例注册代码通过ctx.slots.inject(conversation.input.dock, ...)注入一个动态注册器再以ctx.slots.register({ name, id, order, locale }, Component)完成声明export const todoDockEntry { name: conversation-todo-dock, inject: [slots], apply(ctx: Context): void { ctx.slots.inject(conversation.input.dock, () ctx.slots.register({ name: conversation.input.dock, id: todo, order: 0, locale: NS }, TodoDock)) }, }conversation.input.dock被ConversationRoot以渲染槽位的方式消费。在 ConversationRoot.tsx 中会话存在且输入区就绪zone ! undefined时renderSlot(conversation.input.dock, zone)渲染整个坞列表紧随其后渲染inputBar即 Composer 输入卡片const composerBar ( div className{clsx(css.composerStack, hero css.composerHero)} {hero HeroGlow className{css.heroGlow} /} {hero HeroShell t{t} renderSlot{renderSlot} /} {hero heroWorkspaceRow} {zone ! undefined renderSlot(conversation.input.dock, zone)} {inputBar} /div )Composer 栏跟随列表之后the composer bar follows the list即由这段结构保证坞列表与输入卡片是同一纵向栈.composerStack里的相邻子项渲染顺序天然固定。几何契约ConversationRoot拥有卡片间距Queue 拥有终端贴合几何层由三组数值共同构成全部以 CSS 变量声明在 ConversationRoot.module.css 与各卡片自身的样式模块中① 栈间距--dsh-composer-stack-gap.composerStack { --dsh-composer-stack-gap: 6px; display: flex; flex-direction: column; gap: var(--dsh-composer-stack-gap); }ConversationRoot拥有独立上下文卡片之间的6px间距。栈本身是一个纵向 flex 容器卡片之间的空隙由这一个变量统一控制任何独立卡片都不需要自己声明与邻居的距离。② 卡片尺寸Goal独立的752×36px卡片见 GoalBar.tsx 与其 GoalBar.module.css折叠态 Todo独立的752×44px卡片见 TodoPanel.tsx 与其 TodoPanel.module.css。两张卡片都位于共享宽度轴--dsh-chat-content-widthclamp(680px, 64% of column, 920px)之上加上左右各 8px 的坞内缩进--dsh-composer-dock-inset与 16px 侧向留白--dsh-composer-side-clearance最终呈现为 752px 的卡片宽度。③ Queue 的终端贴合5px 布局重叠Queue 是终端坞条目terminal dock entry。它的 776px 外层包装wrapper包含与其余卡片相同的 752px 面板列并通过负外边距一次性扣除共享间隙 具名 5px 布局重叠使得其后渲染的 Composer 卡片只覆盖 Queue 的边缘.dock { width: calc(100% - var(--dsh-composer-side-clearance) - var(--dsh-composer-side-clearance) - var(--dsh-composer-dock-inset) - var(--dsh-composer-dock-inset)); max-width: calc(var(--dsh-composer-card-max-width) - var(--dsh-composer-dock-inset) - var(--dsh-composer-dock-inset)); /* Cancel the stack gap after this item and tuck 3px under the input card (square bottom), reading as one attached surface. */ margin: 0 auto calc(0px - var(--dsh-composer-stack-gap) - 3px); padding: 0 var(--dsh-composer-dock-inset); }这段样式来自 QueueDock.module.css注释明确解释了设计意图抵消本项之后的栈间隙6px再额外上收 3px 藏入输入卡片方形底部之下视觉上读作一张连为一体的表面——共 6px 3px 9px 上移即笔记中所说的共享间隙 具名 5px 布局重叠6px gap 抵消后与输入卡片的贴合量为 9px 减去卡片自身高度差实际表现为 5px 的净重叠量具体数值由 Queue 面板与 Composer 卡片的几何共同决定。面板自身也做了配套处理border-radius: 12px 12px 0 0只保留上方圆角::after伪元素描边时border-bottom: none注释写明输入卡片自身的顶部边框闭合了下方形状。④ 空条目不占位三条注册路径都遵循空条目渲染 null的约定TodoPanel.tsxif (todos.length 0) return nullQueueDock.tsxif (queue.length 0) return nullGoalBar.tsxgoal undefined || goal null || goal.phase complete时返回 null。由于null不参与 flex 布局空条目不消耗任何 6px 间隙组合矩阵在不同子集下都能保持正确的间距计算。关键不变量顺序与重叠是两个独立契约决策笔记特别强调了一条容易被误解的边界Queue 不能仅仅因为自己是最后一个可见条目就推断自己可以重叠。因为当不存在 Queue 时Goal 或 Todo 会成为最后一个可见上下文卡片此时它们必须与 Composer 保持分离6px 间隙绝不能因为位于列表末尾就获得负外边距。贴合overlap只属于 Queue 这个具名条目属于它的终端地位而非最后一位这个位置。这套设计的核心收益是组合不变性无论 Goal、Todo、Queue 以何种子集同时出现视觉层级都保持稳定——Todo 在最上、Goal 居中、Queue 贴合 Composer 成为唯一的连体表面。验证注册测试钉住顺序浏览器场景钉住可见边缘决策笔记记录了验证手段仓库中的测试代码与之一一对应① 注册测试钉住三个 order 值。以 Queue 为例queue-dock.client.spec.tsx 的注册断言精确匹配了order: 20expect(queueDockEntry.name).toBe(conversation-queue-dock) expect(queueDockEntry.inject).toEqual([slots, conversation, sessions]) queueDockEntry.apply({ slots: { inject, register } } as never) expect(inject).toHaveBeenCalledWith(conversation.input.dock, expect.any(Function)) expect(register).toHaveBeenCalledWith( expect.objectContaining({ name: conversation.input.dock, id: queue, order: 20 }), expect.any(Function), )同类断言同样覆盖了 Todoorder: 0与 Goalorder: 10的注册器防止未来插件重构时误改数值契约。② keyless Queue 浏览器场景同时渲染 Todo、Goal、Queue 三张卡片钉住它们的可访问性顺序accessibility order并逐一检查三张卡片的可见边缘visible card edges——即断言折叠 Todo 面板、Goal 条、Queue 坞的实际盒模型位置确保 6px 间隙、Queue 对 Composer 的 5px 贴合量都落在预期区间。③ 聚焦场景单独渲染 Goal 与 Queue 的独立状态如 Goal 的 active/paused/blocked 相位、Queue 的单行与多行折叠态确认它们在无邻居时依然正确——尤其是 Queue 缺席时Goal/Todo 不与 Composer 发生任何贴合。备选方案复盘为什么拒绝三种直觉做法决策笔记记录了三个被否决的备选方案理解它们的失败原因有助于把握这套契约的设计边界在 Goal 与 Queue 上各自保留独立的负外边距。否决理由受影响的邻居随槽位顺序变化局部外边距无法表达哪种贴合关系是被允许的——除非语义顺序也被固定。这正是原 bug 的根源间距规则必须依赖顺序契约而不能自我声明。在ConversationRoot中为每个已知坞 id 单独渲染。否决理由这会把一个可扩展的列表槽位退化成硬编码的组件清单每新增一个注册者都要改动ConversationRoot本体与一切皆插件的架构目标直接冲突。因此必须保持renderSlot(conversation.input.dock, zone)这种按 id 排序的通用渲染。谁的条目在最后就贴合谁Tuck whichever dock entry is last。否决理由Goal 与 Todo 是独立卡片它们的缺席矩阵不能改变剩余卡片表面surface的语义——即不能因为 Goal 或 Todo 缺席就让对方继承贴合格。贴合资格必须由条目自己持有。影响与扩展指南新输入坞插件如何选位决策确立后的行为契约可总结为以下规则视觉层级对每一种在场组合都稳定Todo0→ Goal10→ Queue20升序排列间距恒为 6pxQueue 是唯一与 Composer 连体的上下文表面其 5px 贴合量由--dsh-composer-stack-gap6px与自身 3px 上收共同构成在 QueueDock.module.css 中一次性声明新输入坞插件的选位规则必须在 Todo0、Goal10、Queue20之间选择自己的 order 值——需要出现在 Todo 之前请取 0需要插在 Todo 与 Goal 之间取1~9插在 Goal 与 Queue 之间取11~19终端边界归属若新条目的 order 20出现在 Queue 之后它必须显式决策哪张表面拥有 Composer 边界——要么接替 Queue 成为新的终端贴合条目并承担对应负外边距要么与 Queue 一起保持与 Composer 的 6px 分离绝不能默认继承贴合行为。延伸阅读决策笔记本体.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.md含后续 Todo-first 顺序决策 2026-08-02-todo-first-composer-context-order.md堆叠栈宿主ConversationRoot.tsx 与 ConversationRoot.module.css三个坞条目注册器TodoPanel.tsx、ui-goal/src/client/index.ts、QueueDock.tsx终端贴合样式QueueDock.module.css验证测试queue-dock.client.spec.tsx 及其同目录下 todo-panel、goal 的对应浏览器场景测试【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考