SKILL.md

---
name: schedule-feishu
description: 飞书日程管理技能，自动创建飞书文档日程表，支持日程新增、状态更新、自动提醒，适配个人飞书账号使用
version: 1.1.3
author: 小龙虾助理
tags: ["飞书", "日程", "提醒", "待办"]
---

# SKILL.md - schedule-feishu 通用飞书日程管理技能

## 效果预览
![schedule-feishu 日程文档效果预览](https://picui.ogmua.cn/s1/2026/03/12/69b2b29e6cc6a.webp)
技能安装后自动在飞书生成结构化日程文档，按日期分组展示所有待办/已完成事项，自动跟踪行程进度，到期前30分钟触发提醒，超出保留天数的历史日程自动清理。

## 功能说明
通用飞书日程管理工具，安装后自动为当前飞书用户创建专属日程文档，支持日程新增、状态跟踪、智能提醒全流程管理。

## 安装配置
1. **前置依赖**：必须先安装 `feishu-doc` 技能并完成飞书应用授权，拥有文档读写权限
2. 安装时支持自定义最大日程保留天数，不配置则使用默认值7天，最多保留7天的日程数据
3. 安装后会自动执行初始化流程，在用户飞书根目录创建「个人日程安排」文档，自动生成标准结构

## 配置文件（自动生成）
所有配置项保存在技能目录下的`config.json`文件中，无需硬编码到其他文件：
```json
{
  "schedule_doc_url": "飞书文档完整URL",
  "doc_token": "飞书文档token",
  "max_retention_days": 7, // 最大保留天数，默认7
  "chatId": "ou_xxxxxxxxxxxxxxxx" // 飞书用户ID，从飞书对话中自动获取
}
```

### chatId获取方式
技能会自动从飞书消息上下文中提取用户ID：
- **首次使用**：当用户在飞书中与机器人对话时，自动提取ID并保存到config.json
- **无需手动配置**：技能会自动处理，用户无需手动获取或配置
- **自动更新**：如果检测到不同的ID，会自动更新配置

## 文档结构（固定）
### 结构规则
1. 以日期作为每个日程块的标题，格式：`## 📅 YYYY-MM-DD 周X`
2. 最新日期的日程块始终展示在文档最顶部
3. 每天的日程对应单独的表格
### 单天表格表头结构
| ✅ 状态 | 🕒 时间 | 📝 事项内容 | 📌 备注 |
状态列固定在第一列，不可修改顺序。
## 状态枚举
- ⏳ 未开始：待执行的行程
- ✅ 已完成：已经完成的行程
- ❌ 已取消：取消的行程
- ⚠️ 进行中：正在进行的行程

## 使用流程

### 阶段1：安装技能
1. 从ClawHub安装 `schedule-feishu` 技能
2. 系统自动检测前置依赖（feishu-doc技能）
3. 自动执行初始化流程，创建飞书日程文档
4. 生成配置文件 `config.json`

### 阶段2：用户首次使用
1. 用户在飞书中与机器人对话（发送日程相关请求）
2. 技能自动从消息上下文中提取用户ID
3. 自动保存到 `config.json` 文件
4. 发送确认消息："✅ 已自动配置你的飞书ID，现在可以接收日程提醒了！"

### 阶段3：日常使用
1. 用户通过自然语言添加日程："明天上午10点开会"
2. 技能解析日期时间，自动记录到飞书文档
3. **更新日程后发送链接地址**：每次添加或更新日程后，必须向用户发送日程文档的完整URL
4. 心跳检查时自动发送提醒（即将开始、超时）
5. 所有通知自动发送到用户飞书私聊

## 心跳检查
**将下面的检查清单追加到HEARTBETA.md文件中：**
- 读取当前飞书日程文档所有待办事项，检查即将开始和超时未完成的行程，自动发送提醒到用户飞书会话，文档地址读取配置文件(skills/schedule-feishu/config.json)。
- 每日6点删除超出最大保留天数的最早日程数据，最大保留天数和日程文档地址读取配置文件。

**配置来源：**
- 文档地址：从 `skills/schedule-feishu/config.json` 读取
- 最大保留天数：从同一配置文件读取
- chatId：自动从消息上下文提取

**提醒触发条件：**
- 即将开始：行程开始前30分钟
- 超时未完成：超过预定时间且状态为"⏳ 待完成"


## 通知与提醒

### 提醒触发条件
1. **即将开始提醒**：行程开始前30分钟
2. **超时提醒**：超过预定时间仍未完成
3. **每日检查**：每30分钟执行一次心跳检查

### 提醒消息格式
```
🦞 日程提醒

📅 即将开始：
- 去公司开会（10:00后30分钟）

⚠️ 超时未完成：
- 去健身房（原定09:00，已超时1小时）
```

## 日程更新反馈

### 文档链接发送规则
**重要：** 每次添加或更新日程后，必须向用户发送日程文档的完整URL

**实现要点：**
- 在完成日程写入操作后，从 `config.json` 读取 `schedule_doc_url`
- 将文档URL包含在确认消息中
- 格式示例：`🦞 已记录：明天上午9点去跑步\n\n📋 日程文档：https://feishu.cn/docx/xxxxx`

**用户价值：**
- `方便用户随时查看完整日程`
- `快速访问历史记录`
- `分享日程给他人`

## 自动清理

### 清理规则
1. **每日执行**：每天早上6点执行清理
2. **保留天数**：由配置文件中的 `max_retention_days` 控制（默认7天）
3. **清理范围**：删除超出保留天数的历史日期数据
4. **保留内容**：保留当天和未来的所有数据

## 错误处理

### 常见错误
1. **飞书文档未创建**：自动执行初始化流程
2. **chatId未配置**：从消息上下文自动提取
3. **配置文件缺失**：自动创建默认配置
4. **飞书API调用失败**：记录错误日志，提示用户检查权限

## 依赖工具
- `feishu_doc`：飞书文档读写操作
- `message`：发送飞书提醒消息
- `config`：读取和更新配置文件
- `heartbeat`：定时检查和清理
schedule-feishu

SKILL.md

related skills
