Merge pull request #878 from 2379278408/fix/875-task-skill-wheel-scroll

safe1ine · web-flow · commit a731d68dca5e · 2026-07-15T19:28:20.000+08:00
修复任务技能列表滚轮失效
diff --git a/docs/superpowers/plans/2026-07-15-task-skill-wheel-scroll.md b/docs/superpowers/plans/2026-07-15-task-skill-wheel-scroll.md
@@ -0,0 +1,260 @@
+# 启动任务技能列表滚轮修复实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让“创建任务”和“启动 AI 任务”弹窗中的技能列表支持鼠标滚轮和触控板纵向滚动。
+
+**Architecture:** 共享 `TaskSkillSelector` 接收可选 `enableWheelScrollFallback` 属性。“创建任务”和“启动 AI 任务”入口启用滚轮回退，通过回调 ref 跟踪 Portal 中稳定的 `PopoverContent` 节点。容器上的原生 `wheel` 监听器从事件目标定位活动技能列表，通过 `deltaMode` 换算后主动更新 `scrollTop`；该实现避开 PR #874 修改的 `TabsContent` 渲染结构。独立临时 worktree 组合 PR #871、PR #874 和 Issue #875，用于统一构建和预览。
+
+**Tech Stack:** React 19、TypeScript、Radix UI、Node.js test runner、Vite。
+
+## Global Constraints
+
+- 修复范围限定为“创建任务”和“启动 AI 任务”入口。
+- 保持搜索、标签筛选、技能勾选及其他任务入口行为。
+- PR #874 和 Issue #875 按任意顺序合并时不产生文本冲突。
+- 纵向滚轮回退不处理纯横向手势和 `Ctrl+滚轮`。
+- 执行 `pnpm lint` 和 `pnpm run build:online`。
+- 完成 SaaS 预览并由用户验收后再提交代码。
+
+---
+
+### Task 1: 更新入口范围回归测试
+
+**Files:**
+- Modify: `frontend/test/task-skill-selector-wheel.test.mjs`
+- Read: `frontend/src/components/console/task/task-skill-selector.tsx`
+- Read: `frontend/src/components/console/project/start-develop-task-dialog.tsx`
+- Read: `frontend/src/components/console/task/task-input.tsx`
+- Read: `frontend/src/components/console/task/create-default-task-dialog.tsx`
+
+**Interfaces:**
+- Consumes: `TaskSkillSelectorProps` 和三个现有调用入口。
+- Produces: 对 `enableWheelScrollFallback?: boolean`、滚轮增量换算和两个弹窗入口启用范围的源码约束。
+
+- [x] **Step 1: 编写失败测试**
+
+```typescript
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+function readSource(path) {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const selector = readSource("../src/components/console/task/task-skill-selector.tsx");
+const startTask = readSource("../src/components/console/project/start-develop-task-dialog.tsx");
+const taskInput = readSource("../src/components/console/task/task-input.tsx");
+const defaultTask = readSource("../src/components/console/task/create-default-task-dialog.tsx");
+
+function taskSkillSelectorTags(source) {
+  return source.match(/<TaskSkillSelector\b[^>]*\/>/gs) ?? [];
+}
+
+test("启动任务技能选择器启用滚轮回退", () => {
+  assert.match(selector, /enableWheelScrollFallback\?: boolean/);
+  assert.match(selector, /addEventListener\("wheel", handleSkillListWheel, \{ passive: false \}\)/);
+  assert.match(selector, /event\.preventDefault\(\)/);
+  assert.match(selector, /removeEventListener\("wheel", handleSkillListWheel\)/);
+  assert.match(selector, /setPopoverContentElement/);
+  assert.match(selector, /activeSkillList\.scrollTop \+= getWheelScrollDelta/);
+  assert.match(selector, /ref=\{setPopoverContentElement\}/);
+  assert.match(selector, /closest<HTMLDivElement>\(ACTIVE_SKILL_LIST_SELECTOR\)/);
+  assert.match(selector, /event\.ctrlKey/);
+  assert.match(selector, /Math\.abs\(event\.deltaY\) <= Math\.abs\(event\.deltaX\)/);
+  assert.doesNotMatch(selector, /ref=\{tag === activeSkillTag/);
+  assert.doesNotMatch(selector, /<Popover modal=/);
+  assert.equal(
+    taskSkillSelectorTags(startTask).some((tag) => /\benableWheelScrollFallback\b/.test(tag)),
+    true,
+  );
+});
+
+test("滚轮回退按 deltaMode 换算滚动距离", () => {
+  const getWheelScrollDelta = loadWheelScrollDelta();
+
+  assert.equal(getWheelScrollDelta(24, 0, 300), 24);
+  assert.equal(getWheelScrollDelta(3, 1, 300), 48);
+  assert.equal(getWheelScrollDelta(2, 2, 300), 600);
+  assert.equal(getWheelScrollDelta(-2, 1, 300), -32);
+});
+
+test("其他任务入口保持默认 Popover 行为", () => {
+  assert.equal(
+    taskSkillSelectorTags(defaultTask).some((tag) => /\benableWheelScrollFallback\b/.test(tag)),
+    true,
+  );
+  assert.equal(
+    taskSkillSelectorTags(taskInput).some((tag) => /\benableWheelScrollFallback\b/.test(tag)),
+    false,
+  );
+});
+```
+
+- [x] **Step 2: 运行测试并确认失败**
+
+Run: `node --test test/task-skill-selector-wheel.test.mjs`
+
+Expected: 第一个测试因仍使用活动 `TabsContent` ref 而失败。
+
+### Task 2: 为两个弹窗入口启用滚轮回退
+
+**Files:**
+- Modify: `frontend/src/components/console/task/task-skill-selector.tsx:29-40,108-140,182-223,267-286`
+- Modify: `frontend/src/components/console/project/start-develop-task-dialog.tsx:456-466`
+- Modify: `frontend/src/components/console/task/create-default-task-dialog.tsx:575-585`
+- Test: `frontend/test/task-skill-selector-wheel.test.mjs`
+
+**Interfaces:**
+- Consumes: 浏览器原生 `WheelEvent`、`WheelEvent.deltaMode` 和非 passive 事件监听器。
+- Produces: `TaskSkillSelectorProps.enableWheelScrollFallback?: boolean`，稳定的 Popover 容器监听器，两个弹窗入口启用该属性。
+
+- [x] **Step 1: 移除 modal 方案并增加滚轮回退属性**
+
+```tsx
+interface TaskSkillSelectorProps {
+  enableWheelScrollFallback?: boolean
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  selectedSkills: string[]
+  skills: SkillForPicker[]
+  skillTags: string[]
+  activeSkillTag: string
+  onActiveSkillTagChange: (tag: string) => void
+  onSkillChange: (skillId: string, checked: boolean) => void
+  triggerClassName?: string
+  labelClassName?: string
+}
+
+export function TaskSkillSelector({
+  enableWheelScrollFallback,
+  open,
+  onOpenChange,
+  selectedSkills,
+  skills,
+  skillTags,
+  activeSkillTag,
+  onActiveSkillTagChange,
+  onSkillChange,
+  triggerClassName,
+  labelClassName,
+}: TaskSkillSelectorProps) {
+  const { t } = useTranslation()
+}
+```
+
+- [x] **Step 2: 通过 Popover 容器上的非 passive 原生监听器主动滚动技能列表**
+
+```tsx
+const DOM_DELTA_LINE = 1
+const DOM_DELTA_PAGE = 2
+const WHEEL_LINE_HEIGHT = 16
+
+function getWheelScrollDelta(deltaY: number, deltaMode: number, pageHeight: number) {
+  if (deltaMode === DOM_DELTA_LINE) return deltaY * WHEEL_LINE_HEIGHT
+  if (deltaMode === DOM_DELTA_PAGE) return deltaY * pageHeight
+  return deltaY
+}
+
+const ACTIVE_SKILL_LIST_SELECTOR = '[role="tabpanel"][data-state="active"]'
+
+const [popoverContentElement, setPopoverContentElement] = useState<HTMLDivElement | null>(null)
+
+useEffect(() => {
+  if (!enableWheelScrollFallback || !open || !popoverContentElement) return
+
+  const handleSkillListWheel = (event: WheelEvent) => {
+    if (
+      event.ctrlKey ||
+      event.deltaY === 0 ||
+      Math.abs(event.deltaY) <= Math.abs(event.deltaX) ||
+      !(event.target instanceof Element)
+    ) {
+      return
+    }
+
+    const activeSkillList = event.target.closest<HTMLDivElement>(ACTIVE_SKILL_LIST_SELECTOR)
+    if (!activeSkillList || !popoverContentElement.contains(activeSkillList)) return
+
+    event.preventDefault()
+    activeSkillList.scrollTop += getWheelScrollDelta(
+      event.deltaY,
+      event.deltaMode,
+      activeSkillList.clientHeight
+    )
+  }
+
+  popoverContentElement.addEventListener("wheel", handleSkillListWheel, { passive: false })
+
+  return () => popoverContentElement.removeEventListener("wheel", handleSkillListWheel)
+}, [enableWheelScrollFallback, open, popoverContentElement])
+
+<PopoverContent
+  ref={setPopoverContentElement}
+  className="flex max-h-[min(24rem,var(--radix-popover-content-available-height))] w-[90vw] max-w-xl flex-col overflow-hidden p-2"
+  align="start"
+>
+```
+
+- [x] **Step 3: 在两个弹窗入口启用**
+
+```tsx
+<TaskSkillSelector
+  enableWheelScrollFallback
+  open={skillPopoverOpen}
+  onOpenChange={setSkillPopoverOpen}
+  selectedSkills={selectedSkill}
+  skills={skillList}
+  skillTags={skillTags}
+  activeSkillTag={activeSkillTag}
+  onActiveSkillTagChange={setActiveSkillTag}
+  onSkillChange={handleSkillChange}
+  triggerClassName="w-full justify-start rounded-md"
+/>
+```
+
+在 `CreateDefaultTaskDialog` 的现有 `TaskSkillSelector` 调用中同样增加 `enableWheelScrollFallback`，并保持 `TaskInput` 调用不传该属性。
+
+- [x] **Step 4: 运行回归测试**
+
+Run: `node --test test/task-skill-selector-wheel.test.mjs`
+
+Expected: 3 tests pass。
+
+- [x] **Step 5: 验证与 PR #874 的三方自动合并**
+
+Run: 使用当前 `main`、PR #874 head 和包含 Issue #875 工作树补丁的临时 tree 执行 `git merge-tree`。
+
+Expected: `task-skill-selector.tsx` 自动合并，不输出 conflict markers。
+
+- [x] **Step 6: 运行静态检查和 online 构建**
+
+Run: `pnpm lint`
+
+Expected: exit code 0。
+
+Run: `pnpm run build:online`
+
+Expected: TypeScript 和 Vite 构建成功，exit code 0。
+
+- [x] **Step 7: 构建三个变更的临时组合版本**
+
+在独立临时 worktree 中以最新 `main` 为基础，依次应用 PR #871、PR #874 和当前 Issue #875 补丁。该 worktree 只用于组合验证，不改变当前功能分支、索引和工作树。
+
+Run: `pnpm lint` 和 `pnpm run build:online`
+
+Expected: 三个变更自动组合，静态检查和构建均以 exit code 0 完成。
+
+- [x] **Step 8: 启动组合版本 SaaS 预览并人工验证**
+
+Run: `TARGET=https://monkeycode-ai.com pnpm dev:online`
+
+Expected: 黄色提示复制功能正常；技能搜索、空结果和关闭清理正常；“创建任务”和“启动 AI 任务”技能列表支持鼠标滚轮和触控板纵向滚动；任务首页行为保持正常。
+
+- [x] **Step 9: 用户验收后提交**
+
+```bash
+git add docs/superpowers/specs/2026-07-15-task-skill-wheel-scroll-design.md docs/superpowers/plans/2026-07-15-task-skill-wheel-scroll.md frontend/test/task-skill-selector-wheel.test.mjs frontend/src/components/console/task/task-skill-selector.tsx frontend/src/components/console/project/start-develop-task-dialog.tsx frontend/src/components/console/task/create-default-task-dialog.tsx
+git commit -m "修复启动任务技能列表滚轮失效"
+```
diff --git a/docs/superpowers/specs/2026-07-15-task-skill-wheel-scroll-design.md b/docs/superpowers/specs/2026-07-15-task-skill-wheel-scroll-design.md
@@ -0,0 +1,46 @@
+# 启动任务技能列表滚轮修复设计
+
+## 背景
+
+项目“创建任务”和“启动 AI 任务”弹窗中的技能选择器使用 Radix Dialog 和 Popover。Dialog 以模态方式锁定页面滚动，PopoverContent 通过 Portal 挂载到 DialogContent 之外。鼠标位于技能列表时，Dialog 的滚动锁会拦截滚轮事件，导致超出可视区域的技能无法通过鼠标滚轮浏览。
+
+关联 Issue：#875。
+
+## 范围
+
+- 修复“创建任务”和“启动 AI 任务”弹窗中的技能列表滚轮行为。
+- 保持任务首页技能选择器的现有交互。
+- 保持技能搜索、标签筛选、勾选状态、关闭行为和移动端布局。
+
+## 方案
+
+为共享 `TaskSkillSelector` 增加可选的 `enableWheelScrollFallback` 属性。在 `CreateDefaultTaskDialog` 和 `StartDevelopTaskDialog` 中启用该属性，任务首页的 `TaskInput` 保持默认行为。回退逻辑通过回调 ref 跟踪稳定的 `PopoverContent` DOM 节点，并在该节点注册 `{ passive: false }` 的原生 `wheel` 监听器。事件到达容器后，从事件目标定位当前活动的 `TabsContent` 技能列表并主动更新其 `scrollTop`。浮层关闭、节点变化或组件卸载时清理监听器。
+
+滚动距离根据浏览器 `WheelEvent.deltaMode` 换算：像素模式直接使用 `deltaY`，行模式按 16 像素换算，页模式按列表可视高度换算。处理器仅拦截来自活动技能列表的纵向滚轮事件；横向手势和带 `Ctrl` 的缩放手势保持浏览器默认处理。纵向滚动调用 `preventDefault()`，避免浏览器原生滚动和手动滚动叠加。
+
+该方案保留现有非模态 Popover 的焦点、关闭和外部点击行为，同时将回退逻辑限制在受影响入口。滚轮实现不修改 `skillTags.map()` 和 `TabsContent` 的渲染结构，因此与 PR #874 的搜索过滤及空结果展示可以按任意顺序自动合并。原 `modal` 方案移除，因为外层 Dialog 的 `RemoveScroll` 监听器仍会先取消 Portal 区域的原生滚动。
+
+## 交互
+
+1. 用户打开“创建任务”或“启动 AI 任务”弹窗并展开技能选择器。
+2. 用户打开技能选择器。
+3. 初始“全部”分类完成 Portal 挂载后，容器监听器立即可用，无需先切换分类。
+4. 鼠标或触控板位于技能列表区域时，列表可以纵向滚动。
+5. 点击模型、主机等其他控件时，技能列表关闭且目标控件响应本次点击。
+6. 关闭技能选择器后，焦点行为保持现状。
+7. 搜索、标签切换和技能选择继续使用现有状态逻辑。
+
+## 验证
+
+- 在“创建任务”和“启动 AI 任务”弹窗中验证鼠标滚轮和触控板纵向滚动。
+- 验证初次打开并保持“全部”分类时可直接滚动。
+- 验证切换到“前端”等分类后仍可滚动，切回“全部”后继续可滚动。
+- 验证像素、行和页三种滚轮增量换算。
+- 验证列表打开后首次点击其他表单控件仍可直接操作。
+- 验证搜索、标签切换、技能勾选及关闭后搜索词清理。
+- 验证纯横向触控板手势和 `Ctrl+滚轮` 不触发技能列表纵向滚动。
+- 验证任务首页 `TaskInput` 技能选择器行为保持正常。
+- 基于 PR #871、PR #874 和 Issue #875 构建临时组合版本，统一验证复制、搜索和滚轮功能。
+- 使用三方合并检查确认 PR #874 与 Issue #875 无文本冲突。
+- 执行 `pnpm lint`。
+- 执行 `pnpm run build:online`。
diff --git a/frontend/src/components/console/project/start-develop-task-dialog.tsx b/frontend/src/components/console/project/start-develop-task-dialog.tsx
@@ -454,6 +454,7 @@ export default function StartDevelopTaskDialog({
               <div className="space-y-2">
                 <Label>{t("taskWorkflow.skill.label")}</Label>
                 <TaskSkillSelector
+                  enableWheelScrollFallback
                   open={skillPopoverOpen}
                   onOpenChange={setSkillPopoverOpen}
                   selectedSkills={selectedSkill}
diff --git a/frontend/src/components/console/task/create-default-task-dialog.tsx b/frontend/src/components/console/task/create-default-task-dialog.tsx
@@ -573,6 +573,7 @@ export default function CreateDefaultTaskDialog({
             </DropdownMenu>
 
             <TaskSkillSelector
+              enableWheelScrollFallback
               open={skillPopoverOpen}
               onOpenChange={setSkillPopoverOpen}
               selectedSkills={selectedSkill}
diff --git a/frontend/src/components/console/task/task-skill-selector.tsx b/frontend/src/components/console/task/task-skill-selector.tsx
diff --git a/frontend/test/task-skill-selector-wheel.test.mjs b/frontend/test/task-skill-selector-wheel.test.mjs
