尧图网站建设 
Yuxi 智能体快捷切换的搜索与滚动AgentView 弹层可用性修复的完整实现【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi导读当知识智能体平台中的智能体数量增多后聊天输入区左侧的智能体快捷切换弹层会把全部选项直接平铺出来导致弹层超出视口、末尾选项与管理入口无法访问。本文围绕 Yuxi 前端web目录于 2026-09-12 落地的决策文档 2026-09-12-agent-switch-search.md完整讲解这次界面修复的设计决策、搜索筛选实现、420px 限高与向上布局机制、替代方案取舍、边界行为以及验证方法。读完你可以掌握如何为弹层式选项选择器加入搜索 独立滚动 固定管理入口的成熟交互以及如何用源码级单测与浏览器脚本约束面板边界避免视口溢出回归。一、背景智能体变多后弹层溢出的问题Yuxi 是一个可私有部署的多租户知识智能体平台支持 RAG、知识图谱与多智能体工作流。用户在聊天输入区左侧有一个智能体快捷切换入口AgentView输入区左侧操作插槽#input-actions-left可以快速在多个智能体之间切换对话对象。在修复前该弹层的实现把全部选项直接排列在弹层内存在两类问题智能体数量较多时弹层高度超过视口末尾的选项无法访问弹层底部管理操作编辑智能体、新建智能体被挤出可视区域入口难以点选。决策文档 2026-09-12-agent-switch-search.md 将其定位为bug-fix类型决策Owner 为 web/src/views/AgentView.vue。二、决策参考模型选择器的搜索 滚动结构修复方案直接参考了 Yuxi 模型选择器已经验证过的顶部搜索与列表滚动结构。核心决策点包括决策点方案搜索匹配按智能体名称匹配trim()去掉首尾空格后统一toLocaleLowerCase()小写比较忽略大小写差异无结果反馈弹层内显示空状态提示不静默空白关键词生命周期打开或关闭弹层时自动清空搜索关键词弹层高度上限 420px并保留视口边距12px滚动范围只有选项列表滚动搜索框、对话绑定提示与管理操作保持固定可见职责划分搜索筛选逻辑由AgentView拥有面板、按钮样式与定位由共享组件 ActionDropdown.vue 与 ActionTrigger.vue 拥有这一职责划分与同批次的另一个决策 2026-09-12-composer-action-dropdown.md输入区操作弹层统一紧密衔接共享弹层组件负责骨架AgentView负责业务选项与筛选。2.1 AgentView 中的搜索筛选实现在 AgentView.vue 中搜索状态与筛选逻辑如下const agentSearchKeyword ref() const filteredAgentOptions computed(() { const keyword agentSearchKeyword.value.trim().toLocaleLowerCase() return agentQuickSwitchOptions.value.filter((agent) agent.label.toLocaleLowerCase().includes(keyword) ) })agentQuickSwitchOptions是可切换智能体集合从agents中过滤掉is_subagent子智能体不参与顶层快捷切换映射出label / value / icon / defaultIcon / isBuiltin字段筛选仅作用于已加载的普通智能体列表不改动后端可见性也不改变当前对话绑定智能体的既有规则无结果时渲染rolestatus的空状态节点暂无匹配智能体样式见.agent-switch-empty居中灰字提示保证辅助技术也能感知列表为空。搜索关键词的清空由共享组件统一负责ActionDropdown在open状态变化时emit(update:search, )实现打开或关闭弹层时清空关键词的决策。2.2 弹层结构搜索框 滚动列表 固定底部AgentView.vue 中弹层的模板结构为搜索区由ActionDropdown的search-placeholder搜索智能体渲染a-input带搜索图标、allow-clear、autocompleteoff、aria-label列表区v-foragent in filteredAgentOptions渲染选项项每项包含头像FallbackAvatar、名称、内置徽标isBuiltin与当前选中项的Check对勾底部固定区#footer插槽依次包含对话绑定提示有活跃线程时显示当前对话已绑定智能体新对话可切换。、分隔线、以及编辑智能体Settings2与新建智能体Plus两个管理操作按钮。关键交互约束来自handleAgentSwitch创建对话中提示等待已有活跃线程时提示请新建对话后切换因此选项项会被标记为disabled仅当前已绑定的智能体可选。这正是文档所述选择器不改变后端可见性与当前对话绑定规则的落地表现。三、为什么不做整层滚动与虚拟列表决策文档记录了被否决的替代方案整个弹层滚动会让搜索框与管理入口随选项一起滚出可视区域——恰恰是本次要解决的问题因此否决虚拟列表会显著增加实现与维护成本。当前智能体规模为几十项使用原生滚动overflow-y: autooverscroll-behavior: contain即可获得足够性能无需引入虚拟滚动。最终采用列表区独立滚动 顶部/底部固定的折中方案既保证可访问性又控制复杂度。四、弹层限高与向上布局的底层实现虽然本文决策文档聚焦搜索与滚动但其使用的 420px 上限与向上布局来自共享弹层组件 ActionDropdown.vue这里补充其底层原理便于完整理解弹层不再溢出是如何被保证的。4.1 高度计算420px 上限 视口边距const panelHeight computed(() { const above top.value - viewportTop.value - 12 const below viewportTop.value viewportHeight.value - bottom.value - 12 return Math.max(0, Math.min(420, props.upward ? above : Math.max(above, below))) })上下各保留12px 视口边距高度上限420pxMath.min(420, ...)upward输入区弹层只允许使用触发按钮上方空间显式禁止向下翻转自适应弹层取上下空间的较大者Math.max(0, ...)保证不可见触发器不会产生负高度。4.2 固定底边的零高定位容器.action-dropdown-positioner.is-upward { position: relative; height: 0; .action-dropdown-panel { position: absolute; bottom: 0; left: 0; } }upward弹层以零高度容器对齐触发器上沿、内容绝对定位在容器底边。这样搜索加载、筛选改变高度时弹层直接向上增减不等待组件库二次测量对应共享组件注释固定底边让内容增减直接向上布局避免底边漂移。这是配套决策 2026-09-12-composer-action-dropdown.md 中向上增减、不等待二次测量的机制实现。4.3 低视口的整体滚动兜底当可用高度不足 240px 时面板切换为is-compact整个面板含搜索与底部一起纵向滚动避免搜索框和底部说明挤掉选项。水平方向上panelWidth被限制为min(width, viewportWidth - 24)并用horizontalOffset把水平位置钳制在可视宽度内同时监听visualViewport的resize/scroll与窗口resize重新测量边界兼容移动端软键盘顶起可视区域的情况。五、验证真实页面 单测 浏览器脚本决策文档的验证部分要求非常明确与仓库测试一一对应5.1 真实开发页面手测清单在开发环境真实页面逐项检查搜索命中、无结果提示、清空关键词、切换智能体、关闭后重开关键词重置、Escape 关闭在桌面、窄屏、横屏三种形态下检查面板边界与列表滚动。另有一条强约束将面板限高临时移除时视口溢出检查必须失败——即回归测试必须能捕获移除限高这一退化。5.2 前端单测与构建前端单测与构建验证其余集成行为全量 lint 的既有失败项与本次文件检查结果需在交付报告中分别说明避免把存量问题混入本次变更。5.3 源码级位置单测actionDropdownPositionweb/test/unit/actionDropdownPosition.test.js 用 Vite SSR 直接加载ActionDropdown.vue组件验证共享弹层的边界行为默认upwardfalse自适应面板宽度在窄屏下收缩到可视区宽度viewport 280px 时panelWidth为 256px顶部表单默认使用下方空间panelHeight取上下较大者 420px输入区upward时不得借用下方空间翻转上方仅 88px 时高度即为 88pxvisualViewport顶部位移后高度收窄不越过可见顶部空间充足时仍被 420px 上限约束不可见触发器不得产生负高度。5.4 浏览器级定位脚本actionDropdownGrowthweb/test/browser/actionDropdownGrowth.js 通过延迟目录响应并筛选缩小列表逐帧检查弹层底边相对触发按钮的偏移不超过 1px。文档数据表明恢复普通文档流布局时旧实现的底边漂移约 266px固定底边后最大漂移约 0.03px。该脚本仅在已登录的开发浏览器内拦截目录响应不调用真实模型。六、配套测试与相关实现索引职责归属测试 dropdownStyleOwnership.test.js确认AgentView等消费者接入共享弹层、不再各自持有按钮/弹层样式输入区弹层统一决策 2026-09-12-composer-action-dropdown.mdActionDropdown拥有搜索、滚动区域、底部操作、外部点击关闭、Escape 与定位触发按钮组件 ActionTrigger.vueplain输入区 30px 无边框与field表单 32px 选择框两种外观collapse-label在窄容器下折叠为纯图标按钮智能体数据来源 web/src/stores/agent.jsselectAgent(agentId)拒绝切换子智能体isBuiltinAgent用于内置徽标与默认排序决策文档索引 docs/develop-guides/decisions/README.md 与本仓库的工程信任实践 docs/develop-guides/engineering-trust.md。七、结论一次范围明确、可在同一变更验证的界面修复本决策属于直接记录实现决定的类型范围明确仅限AgentView智能体快捷切换弹层、收益直观几十项智能体时不再溢出管理入口始终可达、验证闭环真实页面手测 单测 浏览器逐帧定位脚本。对开发者而言这套搜索筛选由业务页面拥有、弹层骨架由共享组件统一的拆分以及限高 独立滚动 固定底边 低视口整体滚动的组合拳可以直接复用到任何需要长列表弹层选择的场景。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Yuxi 智能体快捷切换的搜索与滚动：AgentView 弹层可用性修复的完整实现
Yuxi 智能体快捷切换的搜索与滚动AgentView 弹层可用性修复的完整实现【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi导读当知识智能体平台中的智能体数量增多后聊天输入区左侧的智能体快捷切换弹层会把全部选项直接平铺出来导致弹层超出视口、末尾选项与管理入口无法访问。本文围绕 Yuxi 前端web目录于 2026-09-12 落地的决策文档 2026-09-12-agent-switch-search.md完整讲解这次界面修复的设计决策、搜索筛选实现、420px 限高与向上布局机制、替代方案取舍、边界行为以及验证方法。读完你可以掌握如何为弹层式选项选择器加入搜索 独立滚动 固定管理入口的成熟交互以及如何用源码级单测与浏览器脚本约束面板边界避免视口溢出回归。一、背景智能体变多后弹层溢出的问题Yuxi 是一个可私有部署的多租户知识智能体平台支持 RAG、知识图谱与多智能体工作流。用户在聊天输入区左侧有一个智能体快捷切换入口AgentView输入区左侧操作插槽#input-actions-left可以快速在多个智能体之间切换对话对象。在修复前该弹层的实现把全部选项直接排列在弹层内存在两类问题智能体数量较多时弹层高度超过视口末尾的选项无法访问弹层底部管理操作编辑智能体、新建智能体被挤出可视区域入口难以点选。决策文档 2026-09-12-agent-switch-search.md 将其定位为bug-fix类型决策Owner 为 web/src/views/AgentView.vue。二、决策参考模型选择器的搜索 滚动结构修复方案直接参考了 Yuxi 模型选择器已经验证过的顶部搜索与列表滚动结构。核心决策点包括决策点方案搜索匹配按智能体名称匹配trim()去掉首尾空格后统一toLocaleLowerCase()小写比较忽略大小写差异无结果反馈弹层内显示空状态提示不静默空白关键词生命周期打开或关闭弹层时自动清空搜索关键词弹层高度上限 420px并保留视口边距12px滚动范围只有选项列表滚动搜索框、对话绑定提示与管理操作保持固定可见职责划分搜索筛选逻辑由AgentView拥有面板、按钮样式与定位由共享组件 ActionDropdown.vue 与 ActionTrigger.vue 拥有这一职责划分与同批次的另一个决策 2026-09-12-composer-action-dropdown.md输入区操作弹层统一紧密衔接共享弹层组件负责骨架AgentView负责业务选项与筛选。2.1 AgentView 中的搜索筛选实现在 AgentView.vue 中搜索状态与筛选逻辑如下const agentSearchKeyword ref() const filteredAgentOptions computed(() { const keyword agentSearchKeyword.value.trim().toLocaleLowerCase() return agentQuickSwitchOptions.value.filter((agent) agent.label.toLocaleLowerCase().includes(keyword) ) })agentQuickSwitchOptions是可切换智能体集合从agents中过滤掉is_subagent子智能体不参与顶层快捷切换映射出label / value / icon / defaultIcon / isBuiltin字段筛选仅作用于已加载的普通智能体列表不改动后端可见性也不改变当前对话绑定智能体的既有规则无结果时渲染rolestatus的空状态节点暂无匹配智能体样式见.agent-switch-empty居中灰字提示保证辅助技术也能感知列表为空。搜索关键词的清空由共享组件统一负责ActionDropdown在open状态变化时emit(update:search, )实现打开或关闭弹层时清空关键词的决策。2.2 弹层结构搜索框 滚动列表 固定底部AgentView.vue 中弹层的模板结构为搜索区由ActionDropdown的search-placeholder搜索智能体渲染a-input带搜索图标、allow-clear、autocompleteoff、aria-label列表区v-foragent in filteredAgentOptions渲染选项项每项包含头像FallbackAvatar、名称、内置徽标isBuiltin与当前选中项的Check对勾底部固定区#footer插槽依次包含对话绑定提示有活跃线程时显示当前对话已绑定智能体新对话可切换。、分隔线、以及编辑智能体Settings2与新建智能体Plus两个管理操作按钮。关键交互约束来自handleAgentSwitch创建对话中提示等待已有活跃线程时提示请新建对话后切换因此选项项会被标记为disabled仅当前已绑定的智能体可选。这正是文档所述选择器不改变后端可见性与当前对话绑定规则的落地表现。三、为什么不做整层滚动与虚拟列表决策文档记录了被否决的替代方案整个弹层滚动会让搜索框与管理入口随选项一起滚出可视区域——恰恰是本次要解决的问题因此否决虚拟列表会显著增加实现与维护成本。当前智能体规模为几十项使用原生滚动overflow-y: autooverscroll-behavior: contain即可获得足够性能无需引入虚拟滚动。最终采用列表区独立滚动 顶部/底部固定的折中方案既保证可访问性又控制复杂度。四、弹层限高与向上布局的底层实现虽然本文决策文档聚焦搜索与滚动但其使用的 420px 上限与向上布局来自共享弹层组件 ActionDropdown.vue这里补充其底层原理便于完整理解弹层不再溢出是如何被保证的。4.1 高度计算420px 上限 视口边距const panelHeight computed(() { const above top.value - viewportTop.value - 12 const below viewportTop.value viewportHeight.value - bottom.value - 12 return Math.max(0, Math.min(420, props.upward ? above : Math.max(above, below))) })上下各保留12px 视口边距高度上限420pxMath.min(420, ...)upward输入区弹层只允许使用触发按钮上方空间显式禁止向下翻转自适应弹层取上下空间的较大者Math.max(0, ...)保证不可见触发器不会产生负高度。4.2 固定底边的零高定位容器.action-dropdown-positioner.is-upward { position: relative; height: 0; .action-dropdown-panel { position: absolute; bottom: 0; left: 0; } }upward弹层以零高度容器对齐触发器上沿、内容绝对定位在容器底边。这样搜索加载、筛选改变高度时弹层直接向上增减不等待组件库二次测量对应共享组件注释固定底边让内容增减直接向上布局避免底边漂移。这是配套决策 2026-09-12-composer-action-dropdown.md 中向上增减、不等待二次测量的机制实现。4.3 低视口的整体滚动兜底当可用高度不足 240px 时面板切换为is-compact整个面板含搜索与底部一起纵向滚动避免搜索框和底部说明挤掉选项。水平方向上panelWidth被限制为min(width, viewportWidth - 24)并用horizontalOffset把水平位置钳制在可视宽度内同时监听visualViewport的resize/scroll与窗口resize重新测量边界兼容移动端软键盘顶起可视区域的情况。五、验证真实页面 单测 浏览器脚本决策文档的验证部分要求非常明确与仓库测试一一对应5.1 真实开发页面手测清单在开发环境真实页面逐项检查搜索命中、无结果提示、清空关键词、切换智能体、关闭后重开关键词重置、Escape 关闭在桌面、窄屏、横屏三种形态下检查面板边界与列表滚动。另有一条强约束将面板限高临时移除时视口溢出检查必须失败——即回归测试必须能捕获移除限高这一退化。5.2 前端单测与构建前端单测与构建验证其余集成行为全量 lint 的既有失败项与本次文件检查结果需在交付报告中分别说明避免把存量问题混入本次变更。5.3 源码级位置单测actionDropdownPositionweb/test/unit/actionDropdownPosition.test.js 用 Vite SSR 直接加载ActionDropdown.vue组件验证共享弹层的边界行为默认upwardfalse自适应面板宽度在窄屏下收缩到可视区宽度viewport 280px 时panelWidth为 256px顶部表单默认使用下方空间panelHeight取上下较大者 420px输入区upward时不得借用下方空间翻转上方仅 88px 时高度即为 88pxvisualViewport顶部位移后高度收窄不越过可见顶部空间充足时仍被 420px 上限约束不可见触发器不得产生负高度。5.4 浏览器级定位脚本actionDropdownGrowthweb/test/browser/actionDropdownGrowth.js 通过延迟目录响应并筛选缩小列表逐帧检查弹层底边相对触发按钮的偏移不超过 1px。文档数据表明恢复普通文档流布局时旧实现的底边漂移约 266px固定底边后最大漂移约 0.03px。该脚本仅在已登录的开发浏览器内拦截目录响应不调用真实模型。六、配套测试与相关实现索引职责归属测试 dropdownStyleOwnership.test.js确认AgentView等消费者接入共享弹层、不再各自持有按钮/弹层样式输入区弹层统一决策 2026-09-12-composer-action-dropdown.mdActionDropdown拥有搜索、滚动区域、底部操作、外部点击关闭、Escape 与定位触发按钮组件 ActionTrigger.vueplain输入区 30px 无边框与field表单 32px 选择框两种外观collapse-label在窄容器下折叠为纯图标按钮智能体数据来源 web/src/stores/agent.jsselectAgent(agentId)拒绝切换子智能体isBuiltinAgent用于内置徽标与默认排序决策文档索引 docs/develop-guides/decisions/README.md 与本仓库的工程信任实践 docs/develop-guides/engineering-trust.md。七、结论一次范围明确、可在同一变更验证的界面修复本决策属于直接记录实现决定的类型范围明确仅限AgentView智能体快捷切换弹层、收益直观几十项智能体时不再溢出管理入口始终可达、验证闭环真实页面手测 单测 浏览器逐帧定位脚本。对开发者而言这套搜索筛选由业务页面拥有、弹层骨架由共享组件统一的拆分以及限高 独立滚动 固定底边 低视口整体滚动的组合拳可以直接复用到任何需要长列表弹层选择的场景。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考