nexus-terminal/.helloagents/archive/2026-04/202604190322_quickcommands-cross-group-drag-move/proposal.md

变更提案: quickcommands-cross-group-drag-move

元信息

类型: 新功能
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-19
完成: 2026-04-19

---

1. 需求

背景

快捷指令视图已经支持分组拖拽排序、组内命令拖拽排序和扁平列表拖拽排序，但当前命令拖放逻辑仍然把拖拽限制在“同一分组内”。这会导致用户虽然能整理每个分组内部的顺序，却不能把命令从一个标签组直接拖到另一个标签组，也不能把“未标记”命令直接拖进目标标签组，和 Workbench 中“拖到目标容器即完成归类”的直觉交互不一致。

目标

• 让已标记分组中的命令可以拖到另一个已标记分组内，并在落点位置插入。
• 让“未标记”分组中的命令可以直接拖到已标记分组内，并自动添加目标标签。
• 跨分组移动后移除原分组标签，只保留目标分组与其它未受影响的既有标签。
• 修正快捷指令排序按钮在 manual / name / last_used 三种模式下的文案和图标映射。

约束条件

时间约束: 本轮完成前端实现、构建验证与知识库同步
性能约束: 不新增依赖，继续使用现有原生 drag/drop 与 store action
兼容性约束: 优先复用现有后端增量标签同步与重排接口，不新增后端路由
业务约束: 搜索过滤态仍禁止拖拽排序；本轮暂不支持把已标记命令拖入“未标记”分组

验收标准

• 开启标签分组时，把命令从标签 A 拖到标签 B 后，命令会移除标签 A、加入标签 B，并插入到标签 B 的目标位置。
• 开启标签分组时，把“未标记”命令拖到标签 B 后，命令会新增标签 B，并插入到标签 B 的目标位置。
• 当前轮次不支持把已标记命令拖入“未标记”分组，界面会给出非阻断提示而不是错误修改标签。
• 排序按钮能正确反映 manual / name / last_used 三种模式的标题与图标。
• npm run build --workspace @nexus-terminal/backend 与 npm run build --workspace @nexus-terminal/frontend 通过。

---

2. 方案

技术方案

本次改动只调整前端编排，继续复用已落地的快捷指令更新与顺序持久化能力，不新增后端接口。

第一步，在 QuickCommandsView.vue 放开命令拖放目标的“同组限制”，并补一个支持“源项不在目标列表中时插入”的列表工具函数。这样拖拽命中目标组后，既能处理原来的组内重排，也能处理跨组插入。

第二步，在命令 drop 分支中区分三类路径：同组重排继续沿用现有 reorderCommandsInTag / reorderQuickCommands；“未标记 -> 已标记”与“已标记 A -> 已标记 B”则先通过 updateQuickCommand(...) 更新标签集合，再按目标组当前列表调用 reorderCommandsInTag(targetTagId, ...) 固定落点顺序。

第三步，保留“拖到未标记分组”禁用策略。因为本轮已确认的业务语义是“移除原标签并加入目标标签”，而未标记分组没有可加入的标签，若开放该动作就会变成“删除标签”或“清空所有标签”，和当前确认范围冲突，所以只给用户提示，不执行实际写入。

最后顺手修正排序按钮在 manual 模式下的标题与图标，让拖拽完成后切回 manual 时，控件状态与实际排序一致。

影响范围

涉及模块:
  - frontend: QuickCommandsView 需要实现跨分组拖放与 manual 排序按钮修正
  - knowledge-base: 需要同步 frontend/backend 模块文档与 CHANGELOG
预计变更文件: 5-7

风险评估

风险	等级	应对
跨组移动先改标签、再改目标组顺序，中间刷新可能导致落点顺序丢失	中	在标签更新完成后立刻基于刷新后的目标组列表再次提交 reorderCommandsInTag
目标是“未标记”分组时语义不清，可能被误实现为清空全部标签	高	明确禁止该路径，仅提示用户本轮不支持
多标签命令跨组移动时若直接覆盖 tagIds，可能误删其他标签	中	基于原 tagIds 做“移除 sourceTagId、加入 targetTagId”的增量计算
manual 排序按钮状态未修正，用户会误判当前排序模式	低	同步补齐 sortButtonTitle 和 sortButtonIcon 的三态映射

---

3. 技术设计

架构设计

flowchart LR
    A[QuickCommandsView drop] --> B{是否跨分组}
    B -->|否| C[现有组内重排]
    B -->|是| D[updateQuickCommand 同步 tagIds]
    D --> E[reorderCommandsInTag 固定目标组落点]
    E --> F[(现有 reorder / association API)]

API设计

PUT /api/v1/quick-commands/:id

• 请求:

{
  "name": "Deploy",
  "command": "npm run deploy",
  "tagIds": [5, 9]
}

• 响应:

{
  "message": "快捷指令已更新"
}

PUT /api/v1/quick-commands/reorder-by-tag

• 请求:

{
  "tagId": 9,
  "commandIds": [12, 7, 19]
}

• 响应:

{
  "message": "标签内快捷指令顺序已更新"
}

数据模型

字段	类型	说明
QuickCommandFE.tagIds	number[]	命令当前绑定的标签集合，跨组移动时按“移除源标签 + 加入目标标签”增量计算
QuickCommandFE.tagOrders	Record<number, number>	命令在各标签组中的局部顺序，更新标签后通过目标组重排接口重新固定
GroupedQuickCommands.commands	QuickCommandFE[]	分组视图当前命令列表，跨组插入后用于计算目标顺序
QuickCommandSortByType	`'manual'	'name'

---

4. 核心场景

场景: 已标记命令拖到另一个已标记分组

模块: frontend 条件: 用户开启快捷指令标签分组，当前不处于搜索过滤状态。
行为: 用户把标签 A 中的命令拖到标签 B 的某个命令上，前端先移除标签 A、加入标签 B，再按落点重排标签 B。
结果: 命令从标签 A 消失，出现在标签 B 的目标位置，刷新后保持一致。

场景: 未标记命令拖到已标记分组

模块: frontend 条件: 用户开启快捷指令标签分组，存在“未标记”分组且当前不处于搜索过滤状态。
行为: 用户把“未标记”命令拖到某个标签组内，前端为命令新增目标标签，并在目标组内固定插入顺序。
结果: 命令离开“未标记”分组，进入目标标签组。

场景: 已标记命令拖到未标记分组

模块: frontend 条件: 用户尝试把某个标签组中的命令拖到“未标记”分组。
行为: 前端识别为当前轮次未支持的路径，只给出提示，不提交更新请求。
结果: 原有标签关系保持不变，避免误清空标签。

---

5. 技术决策

quickcommands-cross-group-drag-move#D001: 优先复用现有更新与重排接口，而不是新增“跨组移动”专用后端接口

日期: 2026-04-19 状态: 已采纳 背景: 现有后端已经提供 updateQuickCommand、reorder-by-tag 和增量标签关联同步能力，理论上足以表达“移除原标签、加入目标标签、固定目标组顺序”。 选项分析:

选项	优点	缺点
A: 新增后端 move-between-tags 专用接口	前端调用简单，语义集中	需要新增 controller/service/repository 路径，改动面更大
B: 复用现有更新命令 + 标签内重排接口	后端零新增接口，改动集中在前端编排	前端需要串联两步请求
决策: 选择方案 B
理由: 当前用户确认的是交互增强，不是后端能力缺失。复用现有接口可以最小代价完成需求，并降低本轮回归面。
影响: frontend

quickcommands-cross-group-drag-move#D002: 本轮禁止“已标记 -> 未标记”拖放

日期: 2026-04-19 状态: 已采纳 背景: 已确认的业务语义是“拖到目标分组后，移除原分组标签并加入目标分组标签”。未标记分组没有可加入的标签，因此该路径语义不完整。 选项分析:

选项	优点	缺点
A: 拖入未标记时清空全部标签	交互看起来完整	会把“移动分组”变成“清空标签”，风险高且和当前确认不一致
B: 拖入未标记时只移除源标签	语义比清空全部标签更保守	对多标签命令仍不清晰，用户难以预期
C: 本轮禁用该路径，只提示用户	范围清晰，不引入隐式删除语义	功能覆盖面少一步
决策: 选择方案 C
理由: 当前需求边界已经确认到“加入目标标签”，而未标记不具备该条件。禁用比猜测性实现更安全。
影响: frontend

---

6. 成果设计

设计方向

• 美学基调: 延续现有快捷指令工作台的深色工具面板风格，不做视觉重设计，只强化“卡片可以被移入另一组”的操作感。
• 记忆点: 命令卡片在跨组拖放时仍使用现有虚线高亮占位，用户可以直接感知落点是在目标组内部而不是只做选中。
• 参考: 复用当前 QuickCommandsView.vue 中已存在的组内拖拽高亮和手动排序交互。

视觉要素

• 配色: 继续沿用主题变量和当前 qc-drop-target 虚线反馈，不新增独立拖拽色板。
• 字体: 沿用现有标题和命令 monospace 体系，不调整文本层级。
• 布局: 保持现有分组头和命令卡结构，仅扩展拖放命中逻辑与排序按钮状态表达。
• 动效: 继续使用现有 hover / 拖放过渡，不增加额外动画。
• 氛围: 保持克制、偏工程控制台的交互表达，让跨组归类像“拖入目标容器”一样直接。

技术约束

• 可访问性: 不能破坏现有单击选中、双击执行、右键菜单和键盘选择逻辑。
• 响应式: 继续兼容紧凑模式与 Workbench 窄栏布局，不增加额外结构占位。