---
name: jarvis_agent_cli_invocation
description: 当需要通过命令行调用 Jarvis 通用代理或代码代理时使用此规则——Jarvis Agent CLI 调用规范。包括：判断任务属于通用需求还是代码开发需求；在启动前检测 jvs 或 jca 命令是否已正确安装；先进入目标工作目录再启动命令；始终使用非交互模式进行无人值守调用；在命令行直接传入清晰完整的需求描述；在需求中明确背景、目标、约束、交付物和验收标准；为通用任务选择 jvs，为代码开发任务选择 jca；在执行前后进行必要的结果检查与失败处理。每当用户提及"调用jvs"、"调用jca"、"无人值守执行Jarvis"、"命令行启动agent"、"让agent执行任务"或需要由其他agent通过 CLI 正确调用 Jarvis agent 时触发。
---

# Jarvis Agent CLI 调用规范

## 规则简介

本规则用于指导其他 agent 通过命令行正确调用 Jarvis 通用代理（`jvs`）和代码代理（`jca`）。目标是确保调用过程可自动化、可复现、可审计，并避免因为命令不存在、目录错误、交互阻塞或需求描述不完整而导致执行失败。

## 你必须遵守的原则

### 1. 正确选择代理类型

**要求说明：**

- **必须**：通用需求、信息整理、研究分析、文档撰写、流程性任务使用 `jvs`
- **必须**：代码开发、代码修改、重构、测试补充、构建修复等代码相关任务使用 `jca`
- **禁止**：把明确的代码开发任务交给 `jvs`
- **禁止**：把纯通用任务默认交给 `jca`

### 2. 启动前先检查命令是否可用

**要求说明：**

- **必须**：在调用 `jvs` 或 `jca` 前先检测命令是否已安装
- **必须**：如果命令不存在，立即报错并给出明确提示
- **禁止**：在未确认命令存在时直接调用

**示例：**

```bash
command -v jvs >/dev/null 2>&1 || {
  echo "ERROR: jvs 未安装或不在 PATH 中" >&2
  exit 1
}

command -v jca >/dev/null 2>&1 || {
  echo "ERROR: jca 未安装或不在 PATH 中" >&2
  exit 1
}
```

### 3. 启动前必须进入工作目录

**要求说明：**

- **必须**：先切换到目标工作目录，再执行代理命令
- **必须**：工作目录应与任务上下文一致，例如目标仓库根目录或指定子目录
- **禁止**：在未知目录、临时目录或错误目录中直接启动代理

**示例：**

```bash
cd /path/to/project || {
  echo "ERROR: 无法进入工作目录 /path/to/project" >&2
  exit 1
}
```

### 4. 必须使用非交互模式

**要求说明：**

- **必须**：使用非交互模式，避免等待人工输入
- **必须**：确保调用方式适合无人值守执行
- **禁止**：使用需要人工确认、手动补充输入或进入交互会话的调用方式

**示例：**

```bash
jvs -n --task "..."
jca -n --task "..."
```

### 5. 需求必须在命令行直接传入且描述完整

**要求说明：**

- **必须**：通过命令行参数直接传入需求，不依赖后续交互补充
- **必须**：需求描述清晰、完整、可执行
- **必须**：至少包含以下信息：
  - **背景**：当前任务背景、上下文、业务目的
  - **目标**：希望完成什么
  - **范围/约束**：可修改范围、禁止修改范围、技术限制、风格要求
  - **交付物**：希望输出什么结果
  - **验收标准**：如何判断任务完成
- **禁止**：只传入模糊短句，如“修一下”“看一下这个问题”“帮我处理”
- **禁止**：省略验收标准或关键上下文

**好的需求示例：**

```text
背景：当前项目是一个 Python CLI 工具，需要新增一个内置规则，供其他 agent 正确调用 jvs 和 jca。
目标：新增规则文件，并确保内容覆盖命令安装检测、工作目录切换、非交互调用和任务描述规范。
范围与约束：只允许修改 builtin/rules 目录下的规则文件；遵循现有内置规则格式；不要修改 Python 运行时代码。
交付物：新增 1 个规则文件；必要时补充规则索引或注册信息。
验收标准：规则文件命名合规、YAML header 完整、load_rule 可正常加载，且规则正文明确说明 jvs/jca 的正确调用方式。
```

**不好的需求示例：**

```text
帮我弄一下 agent 调用。
```

### 6. 命令应具备明确失败处理

**要求说明：**

- **必须**：在命令执行链中处理目录切换失败、命令缺失和执行失败
- **必须**：输出可定位问题的错误信息
- **禁止**：吞掉错误或静默失败

## 你必须执行的操作

### 操作 1：识别任务类型并选择命令

**执行步骤：**

1. 判断任务是否为通用需求
2. 判断任务是否为代码开发需求
3. 通用需求选择 `jvs`
4. 代码开发需求选择 `jca`

**判断规则：**

- 使用 `jvs` 的典型场景：调研、总结、文档、规划、知识整理、通用自动化流程
- 使用 `jca` 的典型场景：修改源码、补测试、修复构建、重构、实现功能、排查代码缺陷

### 操作 2：检测命令并准备执行命令

**执行步骤：**

1. 用 `command -v` 检查目标命令是否存在
2. 将切换工作目录与代理命令合并到同一条 shell 命令中执行
3. 如果任一步失败，立即退出

**说明：**

由于命令通常是逐条独立执行的，单独执行一条 `cd` 不会自动影响下一条新命令。因此，切换工作目录必须与 `jvs`/`jca` 调用放在同一条命令中。

**通用模板：**

```bash
command -v <agent_cmd> >/dev/null 2>&1 || {
  echo "ERROR: <agent_cmd> 未安装或不在 PATH 中" >&2
  exit 1
}

cd <work_dir> && <agent_cmd> -n --task "<完整任务描述>" || {
  echo "ERROR: 无法进入工作目录 <work_dir> 或 <agent_cmd> 执行失败" >&2
  exit 1
}
```

### 操作 3：以非交互模式直接传入完整需求

**执行步骤：**

1. 把需求整理为一段完整文本
2. 在文本中明确背景、目标、约束、交付物、验收标准
3. 使用 `--task` 在同一条命令中直接传入需求并执行
4. 保持无人值守模式

**jvs 调用模板：**

```bash
command -v jvs >/dev/null 2>&1 || {
  echo "ERROR: jvs 未安装或不在 PATH 中" >&2
  exit 1
}
cd /path/to/workdir && jvs -n --task "背景：<背景说明>。目标：<目标说明>。范围与约束：<约束说明>。交付物：<交付物说明>。验收标准：<验收标准说明>。" || {
  echo "ERROR: 无法进入工作目录或 jvs 执行失败" >&2
  exit 1
}
```

**jca 调用模板：**

```bash
command -v jca >/dev/null 2>&1 || {
  echo "ERROR: jca 未安装或不在 PATH 中" >&2
  exit 1
}
cd /path/to/workdir && jca -n --task "背景：<项目背景>。目标：<代码开发目标>。范围与约束：<可修改文件、技术约束、禁止事项>。交付物：<代码/测试/文档要求>。验收标准：<构建、测试、行为验证要求>。" || {
  echo "ERROR: 无法进入工作目录或 jca 执行失败" >&2
  exit 1
}
```

### 操作 4：执行后检查返回结果

**执行步骤：**

1. 检查命令退出码
2. 检查输出中是否存在明显错误信息
3. 必要时根据验收标准继续做构建、测试或结果核对
4. 如果失败，保留清晰的错误上下文供后续处理

## 实践指导

### 推荐做法

- **必须**：优先使用单行、可复制、可审计的命令
- **必须**：在任务文本中写明验收标准，而不是只写实现动作
- **必须**：让工作目录与目标仓库保持一致
- **建议**：在复杂任务中写清文件范围、技术栈和禁止事项

### 禁止做法

- **禁止**：在未 `cd` 到项目目录时直接执行 `jvs` 或 `jca`
- **禁止**：省略 `-n` 非交互参数
- **禁止**：把需求拆成“先启动，再交互输入”两阶段模式
- **禁止**：只给一句模糊命令，不提供背景和验收标准

## 检查清单

在完成调用设计或编排前，你必须确认：

- [ ] 已根据任务类型正确选择 `jvs` 或 `jca`
- [ ] 已在调用前检查目标命令是否安装
- [ ] 已在启动前进入正确的工作目录
- [ ] 已使用非交互模式
- [ ] 已在命令行直接传入完整需求
- [ ] 需求中已包含背景、目标、范围/约束、交付物、验收标准
- [ ] 命令具备明确的失败处理逻辑
