harness - 自定义命令

自定义命令是一种把“常用提示词模板”固化为可复用指令的能力（兼容 Claude Code 的 Custom Commands 规范）。命令本质是带参数占位的 Markdown 模板，执行时替换参数后作为 Agent 任务运行。

1、命令定义文件

命令以 Markdown 文件定义，放在 {harnessHome}/commands/ 目录下：YAML Front Matter 描述元数据，正文即提示词模板。

---
description: 生成一条 git 提交信息
argument-hint: [message]
model: deepseek-v4-flash
---
请根据当前暂存区的变更，生成一条简洁的提交信息。
补充说明：$ARGUMENTS

元数据字段：

2、参数占位符

模板正文支持两种占位符（兼容 Claude Code）：

• $1、$2、$3 …：按位置取单个参数。
• $ARGUMENTS：把所有参数拼接为一个字符串。

替换顺序为“先位置参数、后 $ARGUMENTS”。例如模板 部署 $1 到 $2 环境（$ARGUMENTS），传入 ["web", "prod"] 后得到 部署 web 到 prod 环境（web prod）。

3、命名空间（子目录）

commands/ 支持子目录递归扫描，子目录会成为命令的命名空间（用冒号分隔）。例如：

• commands/deploy/staging.md → 命令名 deploy:staging
• commands/git/commit.md → 命令名 git:commit

4、注册与查找

命令由 CommandRegistry 管理，可从目录加载，也可用代码注册：

CommandRegistry registry = engine.getCommandRegistry();

// 从目录加载（递归扫描 .md）
registry.load(Paths.get(engine.getWorkspace(), engine.getHarnessCommands()));

// 查找与列举
Command cmd = registry.find("git:commit");
List<Command> all = registry.all();        // 排序后的全部命令
List<String> names = registry.names();     // 命令名列表（用于 Tab 补全）

同名命令只会注册一次，重复注册会被忽略并打印告警。