command 使用与定义说明

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、预置命令

/model 子命令说明：

/loop 子命令说明：

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

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

3.1 命令文件放置位置

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

3.2 Markdown 文件格式

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

---
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 字段说明

3.4 变量占位符

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

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

3.5 子目录命名空间

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

4、命令使用方式

4.1 CLI 模式

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

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

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

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

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

交互提示：

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

---
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

---
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

---
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

---
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