caesar-research

使用 Caesar API 进行深入研究 - 运行查询、通过聊天进行跟进、集思广益和管理集合。

# Caesar Research

CLI for [Caesar](https://www.caesar.org/) deep research. Runs multi-source research jobs with citations, follow-up chat, and brainstorming.

## Setup

```bash
go install github.com/alexrudloff/caesar-cli@latest
export CAESAR_API_KEY=your_key_here
```

## Research

Run a query (waits for completion by default, prints events as they happen):

```bash
caesar research create "What are the latest advances in mRNA vaccines?"
```

Returns JSON with `content` (synthesized answer with `[n]` citations) and a `results` array of sources.

Fire-and-forget:

```bash
caesar research create "query" --no-wait
# Returns: { "id": "uuid", "status": "queued" }
```

Then check on it:

```bash
caesar research get <job-id>
caesar research watch <job-id>
caesar research events <job-id>
```

### Research Options

| Flag | Description |
|------|-------------|
| `--no-wait` | Return immediately with job ID |
| `--model <name>` | `gpt-5.2`, `gemini-3-pro`, `gemini-3-flash`, `claude-opus-4.5` |
| `--loops N` | Max reasoning loops (default 1, higher = deeper research) |
| `--reasoning` | Enable advanced reasoning mode |
| `--auto` | Let Caesar auto-configure based on query |
| `--exclude-social` | Skip social media sources |
| `--exclude-domain x.com` | Exclude specific domains (repeatable) |
| `--system-prompt "..."` | Custom synthesis prompt |
| `--brainstorm <id>` | Use a brainstorm session for context |

### Status Lifecycle

`queued` → `searching` → `summarizing` → `analyzing` → `researching` → `completed` or `failed`

## Chat (Follow-Up Questions)

Ask follow-up questions about a completed research job:

```bash
caesar chat send <job-id> "How does this compare to traditional vaccines?"
```

Waits for the response by default. The answer includes inline `[n]` citations referencing the original research sources.

```bash
caesar chat send <job-id> "question" --wait=false
caesar chat history <job-id>
```

## Brainstorm

Get clarifying questions before research to improve results:

```bash
caesar brainstorm "How does CRISPR gene editing work?"
# Prints questions with multiple-choice options and a session ID
```

Then use the session ID:

```bash
caesar research create --brainstorm <session-id> "How does CRISPR gene editing work?"
```

## Collections

Group files for research context:

```bash
caesar collections create "Dataset Name" --description "Optional description"
```

## Tips

- For broad topics, use `--auto` to let Caesar pick optimal settings.
- Use `--loops 3` or higher for complex multi-faceted questions.
- Use `--reasoning` for questions requiring deep analysis.
- Pipe output through `jq` to extract specific fields: `caesar research get <id> | jq '.content'`
- Chain brainstorm → research for best results on ambiguous queries.

---

## 中文说明

# Caesar Research

用于 [Caesar](https://www.caesar.org/) 深度研究的 CLI。运行带引用的多来源研究任务、跟进聊天和头脑风暴。

## 设置

```bash
go install github.com/alexrudloff/caesar-cli@latest
export CAESAR_API_KEY=your_key_here
```

## 研究

运行一个查询（默认会等待完成，并在事件发生时打印出来）：

```bash
caesar research create "What are the latest advances in mRNA vaccines?"
```

返回 JSON，包含 `content`（带 `[n]` 引用的综合答案）和一个由来源组成的 `results` 数组。

发起后不等待（fire-and-forget）：

```bash
caesar research create "query" --no-wait
# Returns: { "id": "uuid", "status": "queued" }
```

然后查看：

```bash
caesar research get <job-id>
caesar research watch <job-id>
caesar research events <job-id>
```

### 研究选项

| 标志 | 说明 |
|------|-------------|
| `--no-wait` | 立即返回任务 ID |
| `--model <name>` | `gpt-5.2`、`gemini-3-pro`、`gemini-3-flash`、`claude-opus-4.5` |
| `--loops N` | 最大推理循环次数（默认 1，越高研究越深入） |
| `--reasoning` | 启用高级推理模式 |
| `--auto` | 让 Caesar 根据查询自动配置 |
| `--exclude-social` | 跳过社交媒体来源 |
| `--exclude-domain x.com` | 排除特定域名（可重复使用） |
| `--system-prompt "..."` | 自定义综合提示词 |
| `--brainstorm <id>` | 使用一次头脑风暴会话作为上下文 |

### 状态生命周期

`queued` → `searching` → `summarizing` → `analyzing` → `researching` → `completed` 或 `failed`

## 聊天（跟进提问）

就一个已完成的研究任务提出跟进问题：

```bash
caesar chat send <job-id> "How does this compare to traditional vaccines?"
```

默认会等待响应。答案中包含内联的 `[n]` 引用，指向原始研究来源。

```bash
caesar chat send <job-id> "question" --wait=false
caesar chat history <job-id>
```

## 头脑风暴

在研究前获取澄清性问题，以改进结果：

```bash
caesar brainstorm "How does CRISPR gene editing work?"
# Prints questions with multiple-choice options and a session ID
```

然后使用会话 ID：

```bash
caesar research create --brainstorm <session-id> "How does CRISPR gene editing work?"
```

## 集合

为研究上下文分组文件：

```bash
caesar collections create "Dataset Name" --description "Optional description"
```

## 提示

- 对于宽泛的主题，使用 `--auto` 让 Caesar 选择最佳设置。
- 对于复杂的多面问题，使用 `--loops 3` 或更高。
- 对于需要深入分析的问题，使用 `--reasoning`。
- 通过 `jq` 管道提取特定字段：`caesar research get <id> | jq '.content'`
- 对于含糊的查询，串联 brainstorm → research 以获得最佳结果。