HumanLayer WUI 已知问题排查指南：会话表快捷键、命令面板创建与搜索视图导航

HumanLayer WUI 已知问题排查指南：会话表快捷键、命令面板创建与搜索视图导航

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer

本文基于humanlayer-wui/problems.md中记录的 4 项已知问题，逐一映射到humanlayer-wui（Tauri + React 桌面客户端）的实际源码实现，分析每个问题的触发路径、根本原因与修复方向。读完本文，你将掌握会话表（SessionTable）、命令面板（CommandPaletteMenu）、草稿会话路由（DraftSessionPage）与快捷启动器（useSessionLauncher）之间的调用关系，并能据此定位与修复同类导航类 Bug。

humanlayer-wui是 HumanLayer 项目中负责会话管理的前端桌面应用（Tauri + React + Zustand），用户通过它查看 AI 编码 Agent 的会话列表、创建新会话、搜索历史会话并进入会话详情。problems.md是一份精炼的已知问题清单，记录了两大交互入口——会话表与命令面板——上的 4 项缺陷。本文以该清单为骨架，结合 CommandPaletteMenu.tsx、useSessionLauncher.ts、SessionTable.tsx、DraftSessionPage.tsx 与 router.tsx 等源码，逐条还原问题现场并给出可落地的修复思路。

背景：两条会话创建路径与三种视图

在深入问题之前，先厘清 WUI 中会话创建的两种入口，因为前两条问题恰好各对应一条路径：

• 会话表入口：在会话列表页（#/）按下c快捷键，或点击右上角 "Create" 按钮，均导航到草稿会话路由；见 SessionTablePage.tsx 中按钮的navigate('/sessions/draft')与 useSessionLauncher.ts 中c热键的window.location.hash = '/sessions/draft'。
• 命令面板入口：按Cmd+K/Ctrl+K打开命令面板，选择 "Create Session" 选项，调用createNewSession()直接向后端请求创建一个 draft 会话；见 CommandPaletteMenu.tsx 与 useSessionLauncher.ts。

路由侧则由 router.tsx 定义了三个关键路径：/（会话表）、sessions/draft（草稿会话页）、sessions/:sessionId（会话详情页）。problems.md的 4 条问题，本质上是"这两个入口与这三条路由之间没有完全对齐"。

问题一：会话表上按c不会启动会话创建器

问题描述：在会话表页面按下c键，并不会启动会话创建器（session creator）。

源码还原：c热键注册在 useSessionLauncher.ts 中：

// C - Navigate to new draft session route (root scope) useHotkeys( 'c', () => { // Navigate to draft route without creating a session // The draft will be created lazily when user starts typing window.location.hash = '/sessions/draft' }, { scopes: [HOTKEY_SCOPES.ROOT], enabled: !isTypingInInput(), preventDefault: true, }, )

从源码看，c的语义是"导航到草稿路由，但不立即创建会话"，草稿会等用户开始输入时才懒创建（lazy create）。这与会话表页面上 Create 按钮的行为一致（同样navigate('/sessions/draft')）。

问题根源：问题清单要求的预期行为是"启动会话创建器"，即弹出创建表单/启动器；而当前实现只是切换路由。若DraftSessionPage在无draftId参数时渲染的DraftLauncherForm缺少可见的创建表单外壳，用户感知到的就是"按了c什么都没发生"。此外，该热键注册在HOTKEY_SCOPES.ROOT作用域，而会话表自身有独立的HOTKEY_SCOPES.SESSIONS作用域（见 SessionTable.tsx），作用域重叠时热键冲突也可能导致c未被路由到预期行为。

修复方向：将c的行为与 Create 按钮统一为显式创建：要么调用createNewSession()创建 draft 后直接导航到详情；要么确保/sessions/draft路由在无draftId时渲染一个完整的创建表单而非空白占位。

问题二：从命令面板选择 "create new session" 进入空白屏幕

问题描述：在Cmd+K命令面板中选择 "Create Session" 后，页面跳转到空白屏幕。

源码还原：命令面板中 "Create Session" 选项调用 CommandPaletteMenu.tsx 的handleCreateNewSession，其内部执行：

const handleCreateNewSession = useCallback(async () => { trackEvent(POSTHOG_EVENTS.DRAFT_CREATED, {}) await createNewSession() }, [createNewSession, trackEvent])

createNewSession在 useSessionLauncher.ts 中的实现为：

createNewSession: async () => { try { const response = await daemonClient.launchSession({ query: '', // Empty initial query for draft working_dir: getLastWorkingDir() || '~/', draft: true, // Create as draft }) await useStore.getState().refreshSessions() get().close() // Navigate directly to SessionDetail window.location.hash = `#/sessions/${response.sessionId}` } catch (error) { logger.error('Failed to create draft session:', error) set({ error: 'Failed to create draft session' }) } },

问题根源：这里存在一个路由错配。createNewSession创建的是draft: true的草稿会话，却导航到#/sessions/${response.sessionId}——该路径在 router.tsx 中匹配的是sessions/:sessionId路由，渲染SessionDetailPage（会话详情页），而不是sessions/draft路由对应的DraftSessionPage（草稿创建页）。

对照同文件下会话表的激活逻辑即可印证正确做法：SessionTablePage的handleActivateSession对 draft 会话显式区分了路由：

const handleActivateSession = (session: any) => { // Route draft sessions to the dedicated draft route if (session.status === 'draft') { navigate(`/sessions/draft?id=${session.id}`) } else { navigate(`/sessions/${session.id}`) } }

见 SessionTablePage.tsx。而DraftSessionPage恰恰是通过useSearchParams().get('id')读取draftId来加载既有草稿的（DraftSessionPage.tsx），没有id时仅渲染空的DraftLauncherForm。于是：createNewSession把用户带去了"无草稿加载逻辑"的详情路由，SessionDetailPage对该 draft 会话渲染不出有效内容，表现为空白屏幕。

修复方向：将createNewSession的跳转目标由#/sessions/${response.sessionId}改为#/sessions/draft?id=${response.sessionId}，与SessionTablePage的 draft 路由策略保持一致；同时在DraftSessionPage中补充对"有 sessionId 但无draftId参数"场景的兜底处理（该文件第 94-97 行的 TODO 注释也指出了类似隐患）。

问题三：搜索视图高度与条目数量不符合预期

问题描述：搜索视图仍不工作——列表最大高度应为屏幕高度的 80%，并且只显示当前容器能容纳的条目数。

源码还原：命令面板的搜索列表由CommandList承载，当前高度是固定值 400px：

<CommandList className="max-h-[400px]">

见 CommandPaletteMenu.tsx。搜索数据通过防抖查询（150ms）调用 daemon 的会话搜索接口，且硬编码返回上限为 10 条：

useEffect(() => { if (!debouncedQuery || debouncedQuery.length < 2) { setSessionResults([]) return } ... const response = await daemonClient.searchSessions({ query: debouncedQuery, limit: 10, }) ... }, [debouncedQuery, daemonClient])

见 CommandPaletteMenu.tsx。

问题根源：

1. 高度不符合"屏幕高度 80%"的规格：max-h-[400px]是 Tailwind 固定值，与小屏/大屏设备的视口高度无关联。正确做法应使用视口相对单位（如max-h-[80vh]或max-height: 80dvh）并叠加max-h-[400px]之类的下限兜底。
2. 条目数不符合"只显示容器能容纳的数量"：当前是"后端限制 10 条 + 前端全量渲染"，并未根据容器高度计算可见条目。搜索输入少于 2 个字符时直接返回空结果（debouncedQuery.length < 2），也会让用户觉得搜索"不工作"。

修复方向：把CommandList的max-h-[400px]改为视口高度百分比（max-h-[80vh]），并考虑在渲染层根据行高与容器高度截断/虚拟化条目；同时将limit: 10提为可配置项，或在界面上提示"输入至少 2 个字符开始搜索"。

问题四：从搜索视图选择会话应导航到会话详情

问题描述：在命令面板的搜索视图中选中某条会话后，应跳转到对应的会话详情页。

源码还原：该交互在 CommandPaletteMenu.tsx 中已有实现框架：

const sessionOptions = sessionResults.map(session => ({ type: 'session' as const, id: session.id, label: session.title || session.summary || session.query, workingDir: session.workingDir, action: () => { window.location.hash = `#/sessions/${session.id}` close() }, }))

选中后通过window.location.hash = #/sessions/${session.id}完成导航并关闭面板，CommandItem的onSelect还会上报 PostHog 事件COMMAND_LAUNCHER_SELECTION（command_type: 'open_session'，见同文件第 359-365 行）。该问题与问题三存在联动：搜索视图本身（高度、命中条数、2 字符阈值）若不正常，导航入口自然"看起来"失效。

潜在缺陷：与问题二同源——此处对所有搜索结果一律导航到#/sessions/${session.id}（详情路由），没有区分 draft 会话。而SessionTablePage的正确做法是对 draft 走/sessions/draft?id=...路由。因此当搜索结果中包含 draft 会话时，点击同样可能落入SessionDetailPage而渲染异常。此外，会话选项的keywords只包含label与workingDir（第 358 行），对中文摘要/查询内容的可检索性偏弱。

修复方向：在 session 的action中复用SessionTablePage的 draft 判断逻辑（session.status === 'draft' ? /sessions/draft?id=... : /sessions/${id}）；若daemonClient.searchSessions返回的Session类型已含status字段（见 daemon/types.ts 的SessionStatus），可直接判定。

四项问题的共性根因与修复建议

从源码层面看，这 4 项问题可归纳为两个共性根因：

对应的统一修复建议：

1. 抽取统一的路由工具函数，如navigateToSession(session)：内部根据session.status === 'draft'决定跳#/sessions/draft?id=还是#/sessions/${id}，让会话表、命令面板、快捷启动器三处复用，从根上消除路由错配。
2. 命令面板搜索视图规格化：CommandList改用max-h-[80vh]（并保留max-h-[400px]下限），把limit改为按容器高度动态计算或放开为可配置值；输入不足 2 字符时展示"继续输入以搜索会话"的空态提示而非静默空白。
3. 补充回归测试：仓库已有命令面板的组件测试 CommandPaletteMenu.test.tsx（覆盖"渲染所有基础菜单项""根据输入过滤选项"等场景），可在其基础上新增"搜索会话后点击导航到详情/草稿路由"与"draft 会话路由区分"两条用例，防止问题回归。

小结

problems.md虽仅 4 行，但每条都对应 WUI 中真实可复现的交互缺陷：c热键语义与"创建器"预期不符、createNewSession路由错配导致空白屏、搜索视图高度/条数规格未落地、搜索导航未区分 draft 会话。它们的修复都不需要改动后端 daemon 协议，仅需在前端humanlayer-wui/src内统一路由策略与视图规格即可完成，这也再次印证了"路由约定不一致"是桌面端多入口应用中最常见的 Bug 温床。

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer