关键规则 - 处理任何邮件前必读

1. 绝对禁止直接调用gog直接调用- 必须使用包装脚本（create_event.sh、email_read.sh等）。直接调用gog会绕过追踪并导致重复记录。此项规定不容协商。
2. 忽略日历通知- 不要处理来自calendar-notification@google.com的邮件（已接受、已拒绝、暂定等）。这些是对现有邀请的回复，而非新事件。请运行process_calendar_replies.sh脚本将其归档。
3. 创建前必须确认- 未经当前对话中用户明确确认，切勿创建日历事件
4. 检查是否已处理- 处理任何邮件前，请先检查processed_emails在 index.json 中
5. 首先读取配置- 加载并应用ignore_patterns和auto_create_patterns在呈现事件之前
6. 读取 MEMORY.MD- 检查先前会话中存储的用户偏好
7. 包含所有已配置的参与者- 在创建/更新/删除事件时，始终包含配置中的参与者，使用--attendees标志（以及--send-updates all如果支持）
8. 首先检查已跟踪的事件- 使用lookup_event.sh --email-id在日历搜索之前查找现有事件（更快、更可靠）
9. 跟踪所有已创建的事件- 确保create_event.sh脚本会自动追踪事件；使用追踪到的ID进行更新/删除操作
10. 显示星期几- 在向用户展示事件以供核实时，始终包含星期几信息

⛔禁止：请勿使用gog直接命令⛔

错误示例： gog calendar create ...或gog gmail ... 正确示例： "$SCRIPTS_DIR/create_event.sh" ...或"$SCRIPTS_DIR/email_read.sh" ...

直接调用CLI命令会绕过事件追踪、破坏重复检测机制，并导致重复事件。 所有操作必须通过scripts/目录中的封装脚本来执行。

邮件转日历功能

从邮件中提取日历事件和待办事项，呈现给用户审核，并通过重复检测和撤销支持功能来创建/更新日历事件。

首次设置：请参阅SETUP.md了解配置选项和智能引导流程。

读取邮件内容

重要提示：提取事件前必须读取邮件正文。请使用封装脚本。

SCRIPTS_DIR="$HOME/.openclaw/workspace/skills/email-to-calendar/scripts"

# Get a single email by ID (PREFERRED)
"$SCRIPTS_DIR/email_read.sh" --email-id "<messageId>"

# Search with body content included
"$SCRIPTS_DIR/email_search.sh" --query "in:inbox is:unread" --max 20 --include-body

关于陈旧转发邮件的说明：请勿使用newer_than:1d因为该参数检查的是邮件原始日期标头，而非接收时间。请处理所有未读邮件，并依赖“已处理”检查机制。

工作流程

0. 预处理检查（强制步骤）

SCRIPTS_DIR="$HOME/.openclaw/workspace/skills/email-to-calendar/scripts"
CONFIG_FILE="$HOME/.config/email-to-calendar/config.json"
INDEX_FILE="$HOME/.openclaw/workspace/memory/email-extractions/index.json"

# Start activity logging
"$SCRIPTS_DIR/activity_log.sh" start-session

# Check email mode
EMAIL_MODE=$(jq -r '.email_mode // "forwarded"' "$CONFIG_FILE")

# Check if email was already processed
EMAIL_ID="<the email message ID>"
if jq -e ".extractions[] | select(.email_id == \"$EMAIL_ID\")" "$INDEX_FILE" > /dev/null 2>&1; then
    "$SCRIPTS_DIR/activity_log.sh" log-skip --email-id "$EMAIL_ID" --subject "Subject" --reason "Already processed"
    exit 0
fi

# Load ignore/auto-create patterns
IGNORE_PATTERNS=$(jq -r '.event_rules.ignore_patterns[]' "$CONFIG_FILE")
AUTO_CREATE_PATTERNS=$(jq -r '.event_rules.auto_create_patterns[]' "$CONFIG_FILE")

1. 查找待处理邮件

直接模式：扫描所有未读邮件中的事件指示符（日期、时间、会议关键词）。

转发模式：仅处理包含转发标识的邮件（Fwd:、转发邮件标头）。

2. 提取事件（由代理直接执行）

阅读邮件并提取事件作为结构化数据。为每个事件包含以下信息：

• 标题：描述性名称（最多80个字符）
• 日期：事件日期
• 星期几：用于验证
• 时间：开始/结束时间（默认：上午9点 - 下午5点）
• 是否为多日事件：是否跨越多个日期
• 是否为重复事件：是否重复（及模式）
• 置信度：高/中/低
• 网址：邮件中找到的任何网址（必需 - 始终查找注册链接、信息页面、票务网站等）
• 截止日期：RSVP/注册/票务截止日期（如找到）
• 截止行动：用户需要做什么（例如，“RSVP”、“获取门票”、“注册”）
• 截止网址用于采取行动的直接链接（通常与活动网址相同）

网址提取规则：务必扫描邮件中的网址，并将最相关的一个放在活动描述的开头。

2.1 截止日期检测

扫描邮件中表示活动前需采取行动的截止日期模式：

常见截止日期模式：

• "请在[日期]前回复"，"请于[日期]前回复"
• "在[日期]前注册"，"注册截止日期[日期]"
• "门票销售至[日期]"，"请在[日期]前购票"
• "早鸟优惠截止[日期]"，"提前注册截止日期[日期]"
• "必须在[日期]前回复"，"请在[日期]前回复"
• "在[日期]前报名"，"报名截止日期[日期]"
• "截止日期：[日期]"，"需在[日期]前完成"
• "[行动]的最后一天：[日期]"

当发现截止日期时：

1. 提取截止日期
2. 确定所需行动（回复、注册、购票等）
3. 找到执行该行动的网址
4. 标记该事件以便特殊处理（见以下部分）

3. 向用户呈现选项并等待

应用事件规则后，以编号选择形式呈现：

I found the following potential events:

1. ~~ELAC Meeting (Feb 2, Monday at 8:15 AM)~~ - SKIP (matches ignore pattern)
2. **Team Offsite (Feb 2-6, Sun-Thu)** - PENDING
3. **Staff Development Day (Feb 12, Wednesday)** - AUTO-CREATE

Reply with numbers to create (e.g., '2, 3'), 'all', or 'none'.

停止并等待用户响应。

呈现后，记录待处理的邀请以便后续提醒：

# Record pending invites using add_pending.sh
"$SCRIPTS_DIR/add_pending.sh" \
    --email-id "$EMAIL_ID" \
    --email-subject "$EMAIL_SUBJECT" \
    --events-json '[{"title":"Event Name","date":"2026-02-15","time":"14:00","status":"pending"}]'

4. 检查重复项（强制步骤）

创建任何事件前必须检查：

# Step 1: Check local tracking first (fast)
TRACKED=$("$SCRIPTS_DIR/lookup_event.sh" --email-id "$EMAIL_ID")
if [ "$(echo "$TRACKED" | jq 'length')" -gt 0 ]; then
    EXISTING_EVENT_ID=$(echo "$TRACKED" | jq -r '.[0].event_id')
fi

# Step 2: If not found, try summary match
if [ -z "$EXISTING_EVENT_ID" ]; then
    TRACKED=$("$SCRIPTS_DIR/lookup_event.sh" --summary "$EVENT_TITLE")
fi

# Step 3: Fall back to calendar search using wrapper script
if [ -z "$EXISTING_EVENT_ID" ]; then
    "$SCRIPTS_DIR/calendar_search.sh" --calendar-id "$CALENDAR_ID" --from "${EVENT_DATE}T00:00:00" --to "${EVENT_DATE}T23:59:59"
fi

使用LLM语义匹配检查模糊重复项（例如"团队外出活动"与"团队外出活动 下午5-6点"）

5. 创建或更新日历事件

使用create_event.sh脚本（推荐）- 处理日期解析、跟踪和变更日志：

# Create new event
"$SCRIPTS_DIR/create_event.sh" \
    "$CALENDAR_ID" \
    "Event Title" \
    "February 11, 2026" \
    "9:00 AM" \
    "5:00 PM" \
    "Description" \
    "$ATTENDEE_EMAILS" \
    "" \
    "$EMAIL_ID"

# Update existing event (pass event_id as 8th parameter)
"$SCRIPTS_DIR/create_event.sh" \
    "$CALENDAR_ID" \
    "Updated Title" \
    "February 11, 2026" \
    "10:00 AM" \
    "6:00 PM" \
    "Updated description" \
    "$ATTENDEE_EMAILS" \
    "$EXISTING_EVENT_ID" \
    "$EMAIL_ID"

关于直接gog命令和高级选项，请参阅references/gog-commands.md文件

6. 邮件处理（自动）

邮件处理（标记为已读和/或归档）由自动通过create_event.sh脚本完成根据配置设置。无需手动操作 - 邮件在事件创建后即被处置。

手动处置邮件：

"$SCRIPTS_DIR/disposition_email.sh" --email-id "$EMAIL_ID"

处理日历回复邮件（接受、拒绝、暂定）：

"$SCRIPTS_DIR/process_calendar_replies.sh"           # Process all
"$SCRIPTS_DIR/process_calendar_replies.sh" --dry-run # Preview only

# End activity session
"$SCRIPTS_DIR/activity_log.sh" end-session

事件创建规则

日期/时间处理

• 单日事件：默认 上午 9:00 - 下午 5:00
• 多日事件（例如，2月2日至6日）：使用--rrule "RRULE:FREQ=DAILY;COUNT=N"
• 具有特定时间的事件：使用邮件中的确切时间

事件描述

按此顺序格式化事件描述：

1. 行动警告（如果存在截止日期）：

   *** ACTION REQUIRED: [ACTION] BY [DATE] ***
   

2. 事件链接（如果找到URL）：

   Event Link: [URL]
   

3. 事件详情：从邮件中提取的信息

包含截止日期的示例：

*** ACTION REQUIRED: GET TICKETS BY FEB 15 ***

Event Link: https://example.com/tickets

Spring Concert at Downtown Theater
Doors open at 7 PM
VIP meet & greet available

无截止日期的示例：

Event Link: https://example.com/event

Spring Concert at Downtown Theater
Doors open at 7 PM

重复检测

如果满足以下条件，则视为重复：

• 相同日期 AND 相似标题（语义匹配）AND 时间重叠

始终更新现有事件，而不是创建重复项。

创建截止日期事件

当事件有截止日期（如RSVP、注册、购票等）时，创建两个日历事件：

1. 主事件（如常，但在描述中加上警告）：

"$SCRIPTS_DIR/create_event.sh" \
    "$CALENDAR_ID" \
    "Spring Concert" \
    "March 1, 2026" \
    "7:00 PM" \
    "10:00 PM" \
    "*** ACTION REQUIRED: GET TICKETS BY FEB 15 ***

Event Link: https://example.com/tickets

Spring Concert at Downtown Theater
Doors open at 7 PM" \
    "$ATTENDEE_EMAILS" \
    "" \
    "$EMAIL_ID"

2. 截止日期提醒事件（在截止日期上的独立事件）：

# Use create_event.sh for deadline reminders too (ensures tracking)
"$SCRIPTS_DIR/create_event.sh" \
    "$CALENDAR_ID" \
    "DEADLINE: Get tickets for Spring Concert" \
    "2026-02-15" \
    "09:00" \
    "09:30" \
    "Action required: Get tickets

Event Link: https://example.com/tickets

Main event: Spring Concert on March 1, 2026" \
    "" \
    "" \
    "$EMAIL_ID"

截止日期事件属性：

• 标题格式：截止日期：[行动] 为 [事件名称]
• 日期：截止日期
• 时间：上午9:00（持续30分钟）
• 提醒：提前1天邮件提醒 + 提前1小时弹出提醒
• 描述：需要采取的行动，网址，主要事件的参考

截止日期的电子邮件通知

创建带有截止日期的事件时，发送通知邮件以提醒用户：

# Load config
CONFIG_FILE="$HOME/.config/email-to-calendar/config.json"
USER_EMAIL=$(jq -r '.deadline_notifications.email_recipient // .gmail_account' "$CONFIG_FILE")
NOTIFICATIONS_ENABLED=$(jq -r '.deadline_notifications.enabled // false' "$CONFIG_FILE")

# Send notification if enabled (using wrapper script)
if [ "$NOTIFICATIONS_ENABLED" = "true" ]; then
    "$SCRIPTS_DIR/email_send.sh" \
        --to "$USER_EMAIL" \
        --subject "ACTION REQUIRED: Get tickets for Spring Concert by Feb 15" \
        --body "A calendar event has been created that requires your action.

Event: Spring Concert
Date: March 1, 2026
Deadline: February 15, 2026
Action Required: Get tickets

Link: https://example.com/tickets

Calendar events created:
- Main event: Spring Concert (March 1)
- Deadline reminder: DEADLINE: Get tickets for Spring Concert (Feb 15)

---
This notification was sent by the email-to-calendar skill."
fi

何时发送通知：

• 仅当deadline_notifications.enabled为true在配置中时
• 仅针对有需要采取行动截止日期的事件
• 包含截止日期、行动、网址和事件详情

活动日志

# Start session
"$SCRIPTS_DIR/activity_log.sh" start-session

# Log skipped emails
"$SCRIPTS_DIR/activity_log.sh" log-skip --email-id "abc" --subject "Newsletter" --reason "No events"

# Log events
"$SCRIPTS_DIR/activity_log.sh" log-event --email-id "def" --title "Meeting" --action created

# End session
"$SCRIPTS_DIR/activity_log.sh" end-session

# Show recent activity
"$SCRIPTS_DIR/activity_log.sh" show --last 3

变更日志与撤销

变更可在24小时内撤销：

# List recent changes
"$SCRIPTS_DIR/changelog.sh" list --last 10

# List undoable changes
"$SCRIPTS_DIR/undo.sh" list

# Undo most recent change
"$SCRIPTS_DIR/undo.sh" last

# Undo specific change
"$SCRIPTS_DIR/undo.sh" --change-id "chg_20260202_143000_001"

待处理邀请

未立即处理的事件会被追踪以便提醒：

# Add pending invites (after presenting events to user)
"$SCRIPTS_DIR/add_pending.sh" \
    --email-id "$EMAIL_ID" \
    --email-subject "Party Invite" \
    --events-json '[{"title":"Birthday Party","date":"2026-02-15","time":"14:00","status":"pending"}]'

# List pending invites (JSON)
"$SCRIPTS_DIR/list_pending.sh"

# Human-readable summary
"$SCRIPTS_DIR/list_pending.sh" --summary

# Update reminder tracking
"$SCRIPTS_DIR/list_pending.sh" --summary --update-reminded

# Auto-dismiss after 3 ignored reminders
"$SCRIPTS_DIR/list_pending.sh" --summary --auto-dismiss

事件追踪

# Look up by email ID
"$SCRIPTS_DIR/lookup_event.sh" --email-id "19c1c86dcc389443"

# Look up by summary
"$SCRIPTS_DIR/lookup_event.sh" --summary "Staff Development"

# List all tracked events
"$SCRIPTS_DIR/lookup_event.sh" --list

# Validate events exist (removes orphans)
"$SCRIPTS_DIR/lookup_event.sh" --email-id "abc" --validate

文件位置

参考资料

• 设置指南:SETUP.md- 配置与入门
• CLI 参考：references/gog-commands.md- 详细的 gog CLI 使用说明
• 提取模式：references/extraction-patterns.md- 日期/时间解析
• 工作流程示例：references/workflow-example.md- 完整示例

注意事项

日期解析

处理常见格式：

• 2026年1月15日，星期三 1月15日
• 2026/01/15, 15/01/2026
• 日期范围，如“2月2日至6日”

时区

所有时间均假定为本地时区。时区信息在描述中保留。