# calendar +suggestion

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。

根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。

**调用时机 (Agent Guidance):**
- ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。
- ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具

需要的scopes: ["calendar:calendar.free_busy:read"]

## 命令

```bash
# 获取默认的时间推荐方案（搜索范围：当前时刻至当天结束）
lark-cli calendar +suggestion

# 获取指定时间区间内的推荐方案（支持日期简写或完整 ISO 8601）
lark-cli calendar +suggestion \
  --start "2026-03-19" \
  --end "2026-03-20"

# 结合参与人及会议时长获取推荐方案（时长单位：分钟）
# --attendee-ids 支持传入用户（ou_ 前缀）和群组（oc_ 前缀）混合列表
lark-cli calendar +suggestion \
  --start "2026-03-19T14:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --attendee-ids ou_xxx,oc_yyy \
  --duration-minutes 60

# 排除特定时间段
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --exclude "2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00"

# JSON 格式输出
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --format json
```

## 参数

| 参数                              | 必填    | 说明                                                                  |
| ------------------------------- | ----- | ------------------------------------------------------------------- |
| `--start <time>`                | 否     | 搜索区间开始时间（支持日期/ISO 8601等格式，默认**当前时间**）                                |
| `--end <time>`                  | 否     | 搜索区间结束时间（默认与 `--start` 属于同一天，自动取当天结束时间）                                                     |
| `--attendee-ids <id_list>`     | 否     | 目标参与人 ID 列表。提取对应实体的 ID。支持用户（`ou_` 前缀）和群组（`oc_` 前缀）。多个 ID 使用英文逗号分隔 |
| `--event-rrule <rrule>`         | 否     | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1"                                              |
| `--duration-minutes <min>`      | 否     | 会议时长（分钟）。优先使用用户显式指定的值，若未指定则尝试根据上下文推断，推断失败则不传                                        |
| `--timezone <tz>`               | 否     | 对话中明确提及的预约日程所使用的时区（默认取用户设备时区，例如 `Asia/Shanghai`）                                |
| `--exclude <times>`             | 否     | 排除的时间块，支持 `start~end` 格式（如 `2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00`），多个用逗号分隔 |
| `--format <flag>`               | 否     | 输出格式（固定为 `json`） |
| `--dry-run`                     | 否     | 预览 API 调用，不执行                                                       |

## 时间格式

`--start`、`--end` 以及 `--exclude` 支持以下格式自动解析：

| 格式            | 示例                          | 说明                   |
| ------------- | --------------------------- | -------------------- |
| ISO 8601      | `2026-03-19T08:40:29+08:00` | 完整格式，精确包含日期、时间及带冒号的时区偏移 |
| 日期+时间       | `2026-03-19 08:40:29`       | 自动补全时区               |
| 仅日期          | `2026-03-19`                | start 取 00:00:00，end 取 23:59:59 |
| Unix 时间戳     | `1741564800`                | 秒级时间戳               |

## 输出格式

**将推荐结果整理为易读的选项列表，并附上润色后的推荐理由：**

```text
## 2026-03-19 周四

- **选项 1：10:00 - 10:30**
  推荐理由：所有参与者均空闲。

```
> **AI 行为指导：** 
> - **结构化展示选项与理由**：以清晰的列表呈现推荐时间方案，并直接询问用户意向。**必须**结合“用户原始需求”与“推荐理由”说明每个时间块的优势，输出话术需简明、直接、无歧义。
> - **如实反馈冲突情况**：注意，返回的推荐方案不一定都是完全空闲的（即使明确要求找空闲时间，系统在难以满足时也会返回包含忙闲冲突的方案）。判断推荐方案是否完全空闲，可以从推荐理由中是否表达了“完全空闲”或“没有任何忙闲冲突”来判断。如果推荐方案存在忙闲冲突，**必须**在展示方案时向用户如实说明冲突情况，绝不能误导用户认为是完全空闲。
> - **主动提供优化建议**：当满足以下任一条件时（1. 返回结果包含 `ai_action_guidance` 字段内容；2. 用户要求找个空闲时间，但所有推荐方案都不是完全空闲的），你**必须**主动提供优化建议。若存在 `ai_action_guidance` 字段，需严格依据其核心意图生成引导话术；否则，请基于实际冲突情况主动提供合理的替代方案（如：建议调整时间范围、会议时长或参与人）。

## 典型场景

### 1. 查找多人的共同空闲会议时间

```bash
# 指定两名参与人，并要求找一个 45 分钟的空闲时段
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --attendee-ids ou_member_a,ou_member_b \
  --duration-minutes 45
```

### 2. 用户对当前推荐不满意，要求“换一批”

```bash
# 将上一次推荐的时段作为排除条件传入
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --exclude "2026-03-19T10:00:00+08:00~2026-03-19T10:30:00+08:00"
```

## 与其他命令对比

| 命令                     | 用途       | 输出内容                |
| ---------------------- | -------- | ------------------- |
| `calendar +suggestion` | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 | 返回多个推荐时段及其理由，以及后续建议 |
| `calendar +freebusy`   | 查询忙闲时段   | 只返回忙碌时段列表和rsvp状态（无日程详情）    |

**选择建议**：

- **寻找可用时间（含开会等场景）** → 优先使用 `+suggestion`，直接获取智能推荐方案
- **了解个人当前忙碌情况** → 使用 `+freebusy`

## 参考

- [lark-calendar-create](lark-calendar-create.md) — 创建日程
- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态
- [lark-calendar](../SKILL.md) — 日历完整 API