qwen-code/docs/design/slash-command/roadmap.md

Slash Command 重构路线图

总体目标

用 Qwen 内部架构风格，交付一个在外部体验上 95% 对齐 Claude Code 的 command 平台，同时修复三模式分裂、命令来源单一、prompt command 无法被模型调用三个核心问题。

---

核心设计原则

1. 每个 Phase 可独立 ship：完成后行为是自洽的，不依赖未来 Phase 才能运行
2. Phase 1 是纯基础设施：除修复 MCP_PROMPT 被错误拦截外，不改变任何现有可用命令集
3. 行为变化与架构变化分开：Phase 1 做架构，Phase 2 做能力扩展
4. 不照搬 Claude Code 内部架构：但对齐用户可感知的能力面

---

Phase 1：基础设施重建（纯架构，零行为变化）

目标

建立统一的命令元数据模型和跨模式管理机制，为后续所有 Phase 提供底层支撑。

功能点

1.1 扩展 SlashCommand 元数据模型

在现有 SlashCommand 接口上新增以下字段：

来源字段

• source: CommandSource：命令来源枚举（builtin-command / bundled-skill / skill-dir-command / plugin-command / mcp-prompt 等）
• sourceLabel?: string：展示用的来源标签（如 "Built-in" / "MCP: github-server"）

模式能力字段

• supportedModes: ExecutionMode[]：声明在哪些运行模式下可用（interactive / non_interactive / acp）

执行类型字段

• commandType: CommandType：声明执行类型（prompt / local / local-jsx）

可见性字段

• userInvocable: boolean：用户是否可通过 slash command 调用（默认 true）
• modelInvocable: boolean：模型是否可通过 tool call 调用（默认 false）

辅助元数据字段（为 Phase 3 预留，Phase 1 仅定义，不使用）

• argumentHint?: string：参数提示，如 "<model-id>" / "show|list|set"
• whenToUse?: string：何时调用该命令的说明（供模型使用）
• examples?: string[]：使用示例

1.2 Loader 填充 source/commandType 字段

每个 Loader 在构建 SlashCommand 时必须填充 source 和 commandType：

Loader	source	commandType
BuiltinCommandLoader	builtin-command	由各命令声明（local / local-jsx）
BundledSkillLoader	bundled-skill	prompt
FileCommandLoader（用户/项目）	skill-dir-command	prompt
FileCommandLoader（插件）	plugin-command	prompt
McpPromptLoader	mcp-prompt	prompt

1.3 内置命令声明 supportedModes 和 commandType

为所有 built-in 命令显式声明：

• commandType：local（无 UI 依赖）或 local-jsx（依赖 dialog/React）
• supportedModes：local 类命令声明 ['interactive', 'non_interactive', 'acp']；local-jsx 类命令声明 ['interactive']

1.4 用 capability-based 过滤替换硬编码白名单

• 删除 ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE 常量
• 删除 filterCommandsForNonInteractive 函数
• 新增 filterCommandsForMode(commands, mode) 函数，基于 supportedModes 字段过滤
• 新增 getEffectiveSupportedModes(cmd) 工具函数（考虑 CommandKind 默认策略）
• 修改 handleSlashCommand / getAvailableCommands 函数签名，移除 allowedBuiltinCommandNames 参数

1.5 CommandService 升级为统一 Registry

• 新增 getCommandsForMode(mode: ExecutionMode) 方法
• 新增 getModelInvocableCommands() 方法（Phase 2/3 使用，Phase 1 提供接口）
• 现有 getCommands() 保持不变（interactive 使用）

验收标准

• SlashCommand 接口包含所有新字段，TypeScript 编译通过
• 所有 Loader 填充 source 和 commandType 字段
• 所有 built-in 命令声明 commandType 和 supportedModes
• ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE 已删除，被 capability filter 取代
• non-interactive 下可用命令集与重构前完全一致（现有测试不 break）
• MCP prompt commands 在 non-interactive/acp 下可正常执行（修复原有错误限制）
• CommandService.getCommandsForMode('non_interactive') 返回正确的命令集
• 所有现有测试通过

---

Phase 2：能力扩展（命令整理与 prompt command 模型调用）

目标

基于 Phase 1 的元数据基础，扩展三种模式下的命令可用范围，并打通 prompt command 的模型调用通路。

功能点

2.1 扩展 non-interactive / acp 可用命令集

ACP 语义设计原则

将命令扩展到 ACP/non-interactive 模式前，需遵循以下设计原则：

1. 接收方不同：ACP 模式下消息的接收方是 IDE（Zed/VS Code 插件），而非终端用户。消息内容以纯文本或 Markdown 格式为宜，不应包含 terminal 专用的 ANSI 样式。
2. 实现策略是增加模式分支，而非替换：正确做法是在命令的 action 内部新增模式判断——interactive 路径保持现有 UI 渲染逻辑不变，non_interactive/acp 路径返回适合机器消费的 message 或 submit_prompt。两条路径共存于同一个 action 函数中。
3. 有状态操作需说明语义：在单次非交互调用中（如 CLI -p 参数），/model set、/language set 等有状态命令的变更仅在本次 session 内有效，应在命令响应文本中注明。
4. 只读 vs 有副作用：只读命令（如 /about、/stats）直接返回当前状态文本；有副作用命令（如 /model set、/language set）需在响应中确认操作结果。
5. 避免环境相关副作用：打开浏览器（/docs、/insight）、操作剪贴板（/copy）等依赖图形环境的操作，在 non_interactive/acp 路径下应跳过，改为在响应文本中返回相关 URL 或内容本身。

待扩展命令总览

注：btw、bug、compress、context、init、summary 已在 Phase 1 中扩展到全模式，不在本阶段列表中。

以下 13 个命令将在 Phase 2 中扩展到 non_interactive 和 acp 模式：

A 类：action 已返回 message 或 submit_prompt，只需扩展 supportedModes 并设计 ACP 消息内容

命令	返回类型	ACP/non-interactive 处理要点
/copy	message	ACP 下无剪贴板，改为在响应文本中返回内容本身或提示
/export	message	返回导出文件的完整路径
/plan	submit_prompt	无需改动，直接扩展模式
/restore	message	返回恢复操作的结果描述
/language	message	返回当前语言设置或变更确认文本
/statusline	submit_prompt	无需改动，直接扩展模式

A' 类：有参数时正常执行，无参数时触发 dialog（需增加无参数路径的 non-interactive 处理）

命令	无参数 interactive 行为	无参数 non_interactive/acp 行为
/model	打开模型选择 dialog	返回当前模型名称及说明文本
/approval-mode	打开审批模式 dialog	返回当前审批模式及说明文本

B 类：action 内部使用 context.ui.addItem() 渲染 React 组件，需增加模式分支返回纯文本

命令	interactive 行为	non_interactive/acp 返回内容
/about	渲染版本/配置 React 组件	版本号、当前模型、关键配置的纯文本摘要
/stats	渲染 token/费用统计组件	session 统计数据的纯文本格式
/insight	渲染分析组件 + 打开浏览器	non_interactive 同步生成返回文件路径；acp 通过 stream_messages 推送进度和结果
/docs	渲染文档入口 + 打开浏览器	返回文档 URL，不打开浏览器

C 类：特殊处理

命令	interactive 行为	non_interactive/acp 行为
/clear	调用 context.ui.clear() 清空终端显示	返回上下文边界标记 message，内容为 "Context cleared. Previous messages are no longer in context."

2.2 prompt command 模型调用打通

• 在 CommandService（或 CommandRegistry）中实现 getModelInvocableCommands()，返回所有 modelInvocable: true 的命令
• 将 BundledSkillLoader、FileCommandLoader（用户/项目命令）加载的命令标记为 modelInvocable: true
• MCP prompt 不标记为 modelInvocable：MCP prompt 通过独立的 MCP tool call 机制由模型调用，无需经过 SkillTool 中转
• 改造 SkillTool：从只消费 SkillManager.listSkills() 改为同时消费 CommandService.getModelInvocableCommands()
• 构建统一的模型可调用命令描述，注入 SkillTool 的 description

2.3 mid-input slash command 检测（基础版）

• 在 InputPrompt 中检测光标附近的 slash token（不限于行首）
• 检测到 slash token 后通过 inline ghost text 提示最佳匹配命令名（Tab 接受）
• 不包含 dropdown 补全菜单、argument hints、source badge 等（Phase 3 做）
• ghost text 候选集仅限 modelInvocable: true 的命令（skill / file command）

验收标准

2.1 命令扩展

• A 类：/copy、/export、/plan、/restore、/language、/statusline 在 non-interactive 和 acp 模式下可正常执行并返回有意义的文本输出
• A' 类：/model、/approval-mode 无参数时在 non-interactive/acp 下返回当前状态文本（不触发 dialog）；有参数时执行变更并返回确认文本
• B 类：/about、/stats、/docs 在 non-interactive/acp 下返回纯文本，/docs 不打开浏览器；/insight 在 non_interactive 下同步生成并返回文件路径 message，在 acp 下通过 stream_messages 推送进度
• C 类：/clear 在 non-interactive/acp 下返回上下文边界标记 message，不调用 context.ui.clear()
• 所有扩展命令在 interactive 模式下行为与重构前完全一致（无退化）

2.2 模型调用

• 模型在对话中可以通过 SkillTool 调用 bundled skill、file command（用户/项目）
• MCP prompt 不经过 SkillTool，通过 MCP tool call 机制由模型原生调用
• 模型不可以调用 built-in commands（userInvocable: true，modelInvocable: false）
• SkillTool 的 description 包含所有 modelInvocable 命令的描述

2.3 mid-input slash

• mid-input slash：在正文中输入 / 后通过 inline ghost text 提示最佳匹配命令（Tab 接受）

---

Phase 3：体验对齐（补全增强 + Claude Code 命令补齐）

目标

在 Phase 1/2 的元数据和命令能力基础上，补齐补全体验，并补充 Claude Code 中存在而 Qwen Code 缺失的命令。

功能点

3.1 补全体验增强

source badge

• 在补全菜单中展示命令来源标签（[MCP] 已有，扩展为 [Skill]、[Custom] 等）
• 使用 source / sourceLabel 字段渲染

argument hint

• 补全菜单中命令名后展示 argumentHint（如 set <model-id>）
• argumentHint 由 Phase 1 元数据字段提供

recently used 排序

• 记录用户最近使用的命令（session 级别，无需持久化）
• 在补全排序中给近期使用的命令加权

alias 命中高亮

• 当补全命中 altNames 而非主名时，在展示时注明（如 help (alias: ?)）

冲突策略对齐

• 明确优先级：built-in > bundled/skill-dir > plugin > mcp
• 冲突时将低优先级命令重命名（如 pluginName.commandName）

3.2 mid-input slash command 完整版

• 在 Phase 2 基础版上增加 argument hints 和 source badge 展示
• ghost text 提示（输入 /he 时显示 /help 的淡色提示）
• 有效命令 token 高亮（已完成匹配的 slash command 显示不同颜色）

3.3 Help 目录重构

将 /help 从平铺列表改为分组目录：

• Built-in Commands（local + local-jsx，注明 mode）
• Bundled Skills
• Custom Commands（用户/项目 file commands）
• Plugin Commands
• MCP Commands

每条命令展示：名称、argumentHint、description、source、supportedModes 标记

3.4 ACP available commands 元数据增强

在 sendAvailableCommandsUpdate() 中将更多元数据暴露给 ACP 客户端：

• argumentHint
• source
• supportedModes
• subcommands（名称列表）
• modelInvocable

3.5 Claude Code 缺失命令补齐

补充 Qwen Code 当前没有、Claude Code 有且常用的命令：

命令	类型	说明
/doctor	local	环境自检，输出配置/连接/工具状态诊断
/release-notes	local	展示当前版本的更新日志
/cost	local	展示当前 session 的 token 消耗和费用估算

注：/review、/commit 等任务类命令以 bundled skill 形式提供，不在此列。

验收标准

• 补全菜单展示 source badge（[MCP]、[Skill]、[Custom]）
• 补全菜单展示 argumentHint（如 set <model-id>）
• 近期使用的命令在补全列表中优先出现
• alias 命中时在补全项中注明原名
• mid-input slash：ghost text 提示正确渲染
• /help 输出按来源分组，每条命令展示支持模式标记
• ACP available commands 包含 argumentHint、source、subcommands 字段
• /doctor、/release-notes、/cost 三个命令可用
• /doctor 在 non-interactive 模式下可执行（返回 message）

---

各 Phase 依赖关系

Phase 1（元数据 + 统一过滤）
    │
    ├──► Phase 2（能力扩展）
    │        │
    │        ├──► slash command 子命令拆分
    │        └──► prompt command 模型调用（需要 getModelInvocableCommands()）
    │
    └──► Phase 3（体验对齐）
             │
             ├──► source badge（需要 Phase 1 source 字段）
             ├──► argument hint（需要 Phase 1 argumentHint 字段）
             └──► Help 分组（需要 Phase 1 source 字段）

Phase 2 和 Phase 3 不互相依赖，可以并行推进（或根据优先级调换部分子项）。