# 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 可用命令集

将以下命令的 `supportedModes` 扩展到包含 `non_interactive` 和 `acp`，并确保其 action 实现可在无 UI 环境运行：

**直接可扩展**（action 已无 UI 依赖）：

- `/export`：文件 I/O，返回 `message`
- `/memory`：文件 I/O，返回 `message`
- `/plan`：返回 `submit_prompt`
- `/tools`：改为返回 `message`（文本列表，替换 UI 渲染）
- `/stats`：改为返回 `message`（文本格式，替换 UI 渲染）

**需要 local 子命令拆分**（当前只有 `local-jsx` 壳）：

| 命令           | 新增的 local 子命令                                                           |
| -------------- | ----------------------------------------------------------------------------- |
| `/model`       | `show`（当前模型）、`list`（可选列表）、`set <id>`（切换）                    |
| `/permissions` | `show`（当前权限模式）、`set <mode>`（设置）                                  |
| `/mcp`         | `list`（MCP 服务列表）、`show <server>`（服务详情）、`status`（所有服务状态） |
| `/memory`      | 已有 `show`/`add`/`refresh`（确认 non-interactive 下可用）                    |

> **注意**：上述 UI 壳命令不会被删除，`/model` 不带子命令时仍然打开 dialog（interactive 模式）。新增子命令是 **在现有命令上追加**，不是替换。

#### 2.2 prompt command 模型调用打通

- 在 `CommandService`（或 `CommandRegistry`）中实现 `getModelInvocableCommands()`，返回所有 `modelInvocable: true` 的命令
- 将 `BundledSkillLoader`、`FileCommandLoader`（用户/项目命令）、`McpPromptLoader` 加载的命令标记为 `modelInvocable: true`
- 改造 `SkillTool`：从只消费 `SkillManager.listSkills()` 改为同时消费 `CommandService.getModelInvocableCommands()`
- 构建统一的模型可调用命令描述，注入 `SkillTool` 的 description

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

- 在 `InputPrompt` 中检测光标附近的 slash token（不限于行首）
- 检测到 slash token 后触发补全菜单（展示命令名 + description）
- 补全菜单弹出位置跟随光标
- **不**包含 argument hints、source badge 等（Phase 3 做）

### 验收标准

- [ ] `/export`、`/memory`、`/plan`、`/tools`、`/stats` 在 non-interactive 模式下可正常执行并返回结构化输出
- [ ] `/model show`、`/model set <id>` 在 non-interactive / acp 下可执行
- [ ] `/permissions show`、`/permissions set <mode>` 在 non-interactive / acp 下可执行
- [ ] `/mcp list`、`/mcp show <server>` 在 non-interactive / acp 下可执行
- [ ] 模型在对话中可以通过 `SkillTool` 调用 bundled skill、file command（用户/项目）、MCP prompt
- [ ] 模型不可以调用 built-in commands（`userInvocable: true`，`modelInvocable: false`）
- [ ] mid-input slash：在正文中输入 `/` 后触发命令补全菜单
- [ ] `SkillTool` 的 description 包含所有 `modelInvocable` 命令的描述

---

## 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 不互相依赖，可以并行推进（或根据优先级调换部分子项）。