# CLI 接口契约: Agent 会话监控

**特性分支**: `010-agent-session-monitor`
**日期**: 2025-12-05

## 1. 命令概览

### 1.1 现有命令增强

#### `frago agent <prompt>`

**变更**: 增加实时状态展示

**新增输出格式**:
```
[10:30:05] 🚀 会话已启动 (session: 48c10a46...)
[10:30:10] 📝 用户: 搜索某个信息
[10:30:12] 🤖 助手: 开始搜索...
[10:30:15] 🔧 工具调用: WebSearch (query="某个信息")
[10:30:18] ✅ 工具完成: WebSearch (1.2s)
[10:30:25] 🤖 助手: 找到以下结果...
[10:31:00] ✨ 会话完成 (耗时: 55s, 工具调用: 3次)
```

**新增参数**:
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `--quiet` | flag | false | 静默模式，不显示状态输出 |
| `--json-status` | flag | false | 状态输出使用 JSON 格式 |
| `--no-monitor` | flag | false | 禁用会话监控（仅原始输出） |

---

### 1.2 新增命令

#### `frago session list`

列出最近的监控会话。

**用法**:
```bash
frago session list [--limit N] [--agent-type TYPE] [--json]
```

**参数**:
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `--limit` | int | 10 | 显示的会话数量 |
| `--agent-type` | string | all | 筛选 agent 类型 |
| `--json` | flag | false | JSON 格式输出 |

**输出示例（默认）**:
```
最近的会话:
  1. [48c10a46] 2025-12-05 10:30 (完成, 55s, 3 工具调用)
     项目: /home/yammi/repos/Frago
  2. [a1b2c3d4] 2025-12-05 09:15 (完成, 2m30s, 12 工具调用)
     项目: /home/yammi/repos/ChimeOS
  3. [e5f6g7h8] 2025-12-04 18:00 (错误, 30s, 1 工具调用)
     项目: /home/yammi/repos/Frago
```

**输出示例（JSON）**:
```json
{
  "sessions": [
    {
      "session_id": "48c10a46-9f16-4d56-8c65-26de8a5af65c",
      "agent_type": "claude",
      "project_path": "/home/yammi/repos/Frago",
      "started_at": "2025-12-05T10:30:00Z",
      "status": "completed",
      "duration_ms": 55000,
      "tool_call_count": 3
    }
  ]
}
```

---

#### `frago session show <session_id>`

显示指定会话的详细信息。

**用法**:
```bash
frago session show <session_id> [--steps] [--tools] [--json]
```

**参数**:
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `session_id` | string | 必填 | 会话 ID（可用前缀匹配） |
| `--steps` | flag | false | 显示所有步骤 |
| `--tools` | flag | false | 显示工具调用详情 |
| `--json` | flag | false | JSON 格式输出 |

**输出示例（默认）**:
```
会话详情: 48c10a46-9f16-4d56-8c65-26de8a5af65c
  类型: claude
  项目: /home/yammi/repos/Frago
  状态: 完成
  开始: 2025-12-05 10:30:00
  结束: 2025-12-05 10:30:55
  耗时: 55 秒

统计:
  用户消息: 2
  助手消息: 5
  工具调用: 3 (成功: 3, 失败: 0)

使用的工具:
  - WebSearch (1次)
  - Read (1次)
  - Edit (1次)
```

**输出示例（--steps）**:
```
步骤历史:
  1. [10:30:05] 用户消息: 搜索某个信息
  2. [10:30:10] 助手消息: 我来帮你搜索...
  3. [10:30:12] 工具调用: WebSearch
  4. [10:30:15] 工具结果: WebSearch ✅
  5. [10:30:20] 助手消息: 找到以下结果...
  ...
```

---

#### `frago session watch [session_id]`

实时监控当前或指定会话。

**用法**:
```bash
frago session watch [session_id] [--json]
```

**参数**:
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `session_id` | string | 最近的 | 会话 ID（可选） |
| `--json` | flag | false | JSON 格式输出 |

**行为**:
- 如果未指定 session_id，自动监控最近启动的会话
- 实时显示新的步骤和工具调用
- 按 Ctrl+C 退出监控

**输出示例**:
```
监控会话: 48c10a46... (按 Ctrl+C 退出)
[10:30:05] 🚀 会话已启动
[10:30:10] 📝 用户: 搜索某个信息
[10:30:12] 🔧 工具调用: WebSearch
  → 等待中...
[10:30:15] ✅ WebSearch 完成 (1.2s)
[10:30:20] 🤖 助手: 找到以下结果...
```

---

#### `frago session clean [--before DATE] [--keep N]`

清理历史会话数据。

**用法**:
```bash
frago session clean [--before DATE] [--keep N] [--dry-run]
```

**参数**:
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `--before` | date | 无 | 清理指定日期之前的会话 |
| `--keep` | int | 100 | 保留最近 N 个会话 |
| `--dry-run` | flag | false | 仅预览，不实际删除 |

**输出示例**:
```
将删除 25 个会话:
  - 48c10a46 (2025-11-01)
  - a1b2c3d4 (2025-11-02)
  ...

确认删除? [y/N]
```

---

## 2. 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 一般错误 |
| 2 | 参数错误 |
| 3 | 会话未找到 |
| 4 | 监控失败（目录不存在、权限问题等） |

---

## 3. 环境变量

| 变量 | 默认值 | 描述 |
|------|--------|------|
| `FRAGO_SESSION_DIR` | `~/.frago/sessions` | 会话数据存储目录 |
| `FRAGO_CLAUDE_DIR` | `~/.claude` | Claude Code 数据目录 |
| `FRAGO_MONITOR_ENABLED` | `1` | 是否启用会话监控（0 禁用） |
