Command（命令）是 SolonCode 的交互控制机制。用户在 CLI 或 Web 终端输入 `/command` 形式的指令，即可触发预置功能或自定义 Prompt 模板。它既是人机交互的快捷通道，也是可扩展的能力注册中心。


### 1、核心架构

```
用户输入 (/command arg1 arg2 ...)
    │
    ▼
 isCommand()  ──→  不以 "/" 开头?  ──→  交给 AI Agent 处理
    │
    ▼ (以 "/" 开头)
 解析 cmdName + args
    │
    ▼
 CommandRegistry.find(cmdName)  ──→  未找到?  ──→  回退到 Agent
    │
    ▼ (找到 Command)
 构建 CommandContext（封装 engine, session, args 等）
    │
    ▼
 command.execute(ctx)
    │
    ├── 内置命令 → 直接处理（清空会话、切换模型等）
    │
    └── Markdown 命令 → ctx.runAgentTask(prompt, model) → 交给 Agent 执行
```


### 2、预置命令

| 命令 | 仅CLI | 说明 |
|------|-------|------|
| `/exit` | 是 | 退出进程 |
| `/clear` | 是 | 清空会话记录 |
| `/resume` | 否 | 恢复最后一个未完成的任务 |
| `/model [ls\|help\|<name>]` | 是 | 模型管理 (`ls, help, <name>`) |
| `/loop [ls, stop <id>, stop-all, <interval> <prompt>]` | 否 | 循环任务管理 (`ls, stop <id>, stop-all, <interval> <prompt>`) |

**`/model` 子命令说明：**

| 子命令 | 说明 |
|--------|------|
| `/model` | 列出所有可用模型（当前活跃模型会标记 `(active)`） |
| `/model ls` | 同上 |
| `/model help` | 显示 `/model` 用法帮助 |
| `/model <name>` | 切换到指定模型 |


**`/loop` 子命令说明：**

| 子命令 | 说明 |
|--------|------|
| `/loop` | 列出所有任务 |
| `/loop ls` | 同上 |
| `/loop stop <id>` | 停目一个任务 |
| `/loop stop-all` | 切换到指定模型 |
| `/loop <prompt>` | 添加一个任务（间隔时间为 5m） |
| `/loop 1m <prompt>` | 添加一个任务，间隔时间为 1m（1m 可改为其它时间） |

### 3、自定义命令（Markdown 命令）

除了预置命令外，用户可以通过在指定目录放置 `.md` 文件来定义自己的命令。Markdown 文件的内容即为 Prompt 模板，支持变量占位符替换，最终作为 Agent 任务执行。

#### 3.1 命令文件放置位置

| 位置 | 路径 | 作用域 | 优先级 |
|------|------|--------|--------|
| 用户级 | `~/.soloncode/commands/*.md` | 所有项目共享 | 先注册 |
| 项目级 | `.soloncode/commands/*.md` | 仅当前项目 | 后注册（可覆盖同名） |

> **加载顺序**：用户级命令先注册，项目级命令后注册。项目级可覆盖用户级同名命令。

#### 3.2 Markdown 文件格式

完整的 `.md` 命令文件包含可选的 YAML Frontmatter 和 Prompt 正文：

```markdown
---
description: Create a git commit with conventional commit message
model: deepseek-chat
---

Please create a git commit with the following message format:

$ARGUMENTS

If no message is provided, analyze the staged changes and generate one.
```

#### 3.3 Frontmatter 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `description` | string | 否 | 命令描述，显示在 `/help` 列表和 Tab 补全中。默认 `"Custom command: <name>"` |
| `model` | string | 否 | 指定执行模型标识。不设置则使用当前会话模型 |

#### 3.4 变量占位符

Prompt 正文中支持以下变量占位符，在命令执行时自动替换：

| 变量 | 说明 | 示例 |
|------|------|------|
| `$ARGUMENTS` | 所有参数拼接为单个字符串 | `/review src/App.java` → `$ARGUMENTS` = `"src/App.java"` |
| `$1`, `$2`, `$3`... | 按位置取单个参数（1-based） | `/find bug fix` → `$1` = `"bug"`, `$2` = `"fix"` |

> **替换顺序**：先替换 `$1`, `$2`...，再替换 `$ARGUMENTS`，避免 `$1` 的内容被 `$ARGUMENTS` 误替换。

#### 3.5 子目录命名空间

文件路径映射为命令名时，使用冒号 `:` 作为命名空间分隔符，支持按功能分组管理命令：

| 文件路径 | 注册为命令 |
|---------|-----------|
| `commit.md` | `/commit` |
| `deploy/staging.md` | `/deploy:staging` |
| `ci/docker/build.md` | `/ci:docker:build` |


### 4、命令使用方式

#### 4.1 CLI 模式

在交互式终端中直接输入 `/command`：

```
User
> /model ls                # 列出所有模型

User
> /model deepseek-chat     # 切换模型

User
> /commit fix login bug    # 执行自定义命令

User
> /(tab)                   # Tab 补全，列出所有可用命令
```

**交互提示：**

| 快捷键 | 说明 |
|--------|------|
| `/(tab)` | Tab 补全，列出所有命令及其描述 |
| `esc` / `回车` | 中断当前正在执行的 Agent 任务 |

#### 4.2 Web 模式

在 Web 端使用时：

- **`cliOnly = true` 的命令不会出现在 Web 端**（如 `/exit`, `/clear`, `/model`）
- API 接口 `GET /chat/commands` 返回所有非 CLI 专属的命令列表
- 自定义 Markdown 命令（`cliOnly` 默认为 `false`）在 CLI 和 Web 端均可用


### 5、自定义命令示例

#### 5.1 代码审查

文件路径：`.soloncode/commands/review.md`

```markdown
---
description: Review code changes in current branch
---

Review the code changes in the current branch compared to $1 (default: main).

Review checklist:
1. **Correctness**: Are there logic errors or edge cases?
2. **Security**: Any injection risks, exposed secrets, or auth issues?
3. **Performance**: Any obvious bottlenecks or unnecessary operations?
4. **Readability**: Is the code clear and well-documented?
5. **Testing**: Are critical paths covered by tests?

For each issue found, provide:
- File and line reference
- Severity (critical / warning / suggestion)
- Suggested fix
```

使用：

```
> /review main
> /review develop
```

#### 5.2 Git 提交

文件路径：`.soloncode/commands/commit.md`

```markdown
---
description: Generate a git commit with staged changes
---

Analyze the staged changes and create a git commit.

Requirements:
- Write a clear, concise commit message in conventional commit format
- Use the provided message as reference: $ARGUMENTS
- If no message is provided, generate one based on the diff
- Do not push the commit

Steps:
1. Run `git status` to see what's staged
2. Run `git diff --cached` to review staged changes
3. Run `git commit -m "<message>"` with the generated commit message
```

使用：
```
> /commit fix login timeout bug
> /commit
```

#### 5.3 子目录命名空间：CI 命令组

利用子目录可以将命令按功能分组管理：

**`.soloncode/commands/ci/build.md`** → 注册为 `/ci:build`

```markdown
---
description: Run CI build pipeline locally
---

Run the local CI build pipeline:

1. Run `mvn clean compile` to compile
2. Run `mvn test` to execute unit tests
3. Run `mvn package -DskipTests` to package
4. Report the build result summary

Additional options: $ARGUMENTS
```

**`.soloncode/commands/ci/test.md`** → 注册为 `/ci:test`

```markdown
---
description: Run tests with optional filters
---

Run the test suite.

If $ARGUMENTS is provided, run only the matching tests.
Otherwise, run all tests.

Steps:
1. If argument provided: `mvn test -Dtest=$ARGUMENTS`
2. If no argument: `mvn test`
3. Summarize test results: passed, failed, skipped
4. Highlight any failures with details
```

使用：
```
> /ci:build
> /ci:test UserServiceTest
> /ci:test *IntegrationTest
```