ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
125 lines
7.0 KiB
Markdown
125 lines
7.0 KiB
Markdown
# 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 |