local-tools

本地工具技能

何时使用此技能

在需要以下操作时，使用 local-tools 技能：

• 日历管理 - 查看、创建、更新或删除日历事件

使用示例：

• 用户：“显示我明天的日程安排”
• 用户：“下午 3 点创建一个会议”
• 用户：“搜索包含‘项目’的日历事件”
• 用户：“删除明天的会议”

工作原理

┌──────────┐    Bash/PowerShell    ┌─────────────────────────────────────────────────────────────┐
│  Claude  │──────────────────────▶│  calendar.sh / calendar.ps1                                 │
│          │                       │  ├─ macOS: osascript -l JavaScript (JXA) ──▶ Calendar.app   │
│          │                       │  └─ Windows: PowerShell ──▶ Outlook COM API                 │
└──────────┘                       └─────────────────────────────────────────────────────────────┘

架构：

1. CLI 脚本 - 特定于平台的脚本，无需 HTTP 服务

   • calendar.sh - 适用于 macOS 的 Bash 脚本
   • calendar.ps1 - 适用于 Windows 的 PowerShell 脚本

2. 本地日历访问 - 直接访问系统日历

   • macOS：使用 JXA（JavaScript for Automation）控制 Calendar.app
   • Windows：使用 PowerShell COM API 控制 Microsoft Outlook

3. JSON 输出 - 结构化数据格式，便于解析

平台支持

平台	实现方式	日历应用	状态
macOS 10.10+	JXA + Calendar.app	Calendar.app	✅ 完全支持
Windows 7+	PowerShell + COM	Microsoft Outlook	✅ 完全支持
Linux	-	-	❌ 不支持

权限

macOS

• 需要“日历”访问权限
• 首次使用时会提示用户授权
• 可在以下位置管理：系统设置 > 隐私与安全性 > 日历

Windows

• 需要安装 Microsoft Outlook
• 使用 COM 访问可能需要管理员权限

日历操作

重要提示：如何定位脚本

使用 Read 工具读取此 SKILL.md 文件时，你会获得该文件的绝对路径（例如，/Users/username/.../SKILLs/local-tools/SKILL.md）。

构造脚本路径：

1. 获取此 SKILL.md 文件所在目录
2. 添加 /scripts/calendar.sh（macOS）或 /scripts/calendar.ps1（Windows）

示例：

# If SKILL.md is at: /Users/username/path/to/SKILLs/local-tools/SKILL.md
# Then the script is: /Users/username/path/to/SKILLs/local-tools/scripts/calendar.sh

bash "/Users/username/path/to/SKILLs/local-tools/scripts/calendar.sh" <operation> [options]

以下所有示例中的 <skill-dir>/scripts/calendar.sh 均为占位符。请将其替换为实际的绝对路径。

AI 助手最佳实践

应该：

• ✅ 直接执行命令，不要展示反复试错的过程
• ✅ 如果命令失败，告知用户可能存在权限问题，不要展示技术错误
• ✅ 使用 search 命令搜索生日/周年纪念日
• ✅ 如果未指定日历名称，脚本会自动使用第一个可用日历

不应该：

• ❌ 不要反复尝试不同的命令组合
• ❌ 不要向用户展示错误堆栈或技术细节
• ❌ 不要读取脚本源代码来分析问题
• ❌ 不要询问用户日历名称，使用默认行为

示例 - 搜索生日：

# Correct approach: Search directly, don't trial-and-error
bash "<skill-dir>/scripts/calendar.sh" search --query "birthday"

# If permission error returned, directly tell user:
# "Calendar access permission is required. Please open System Settings > Privacy & Security > Calendar, and authorize Terminal or LobsterAI"

列出事件

# List events for next 7 days (default)
bash "<skill-dir>/scripts/calendar.sh" list

# List events for specific date range
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-12T00:00:00" \
  --end "2026-02-19T23:59:59"

# List events from specific calendar (macOS)
bash "<skill-dir>/scripts/calendar.sh" list \
  --calendar "Work"

创建事件

# Create a simple event
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Team Meeting" \
  --start "2026-02-13T14:00:00" \
  --end "2026-02-13T15:00:00"

# Create event with location and notes
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Client Call" \
  --start "2026-02-14T10:00:00" \
  --end "2026-02-14T11:00:00" \
  --calendar "Work" \
  --location "Conference Room A" \
  --notes "Discuss Q1 roadmap"

更新事件

# Update event title
bash "<skill-dir>/scripts/calendar.sh" update \
  --id "EVENT-ID" \
  --title "Updated Meeting Title"

# Update event time
bash "<skill-dir>/scripts/calendar.sh" update \
  --id "EVENT-ID" \
  --start "2026-02-13T15:00:00" \
  --end "2026-02-13T16:00:00"

删除事件

bash "<skill-dir>/scripts/calendar.sh" delete \
  --id "EVENT-ID"

搜索事件

# Search for events containing keyword (searches ALL calendars)
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "meeting"

# Search in specific calendar only
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "project" \
  --calendar "Work"

注意： 未指定 --calendar 时，搜索操作会遍历 macOS 和 Windows 上的所有可用日历。

输出格式

所有命令均返回以下结构的 JSON：

成功响应

{
  "success": true,
  "data": {
    "events": [
      {
        "eventId": "E621F8C4-...",
        "title": "Team Meeting",
        "startTime": "2026-02-13T14:00:00.000Z",
        "endTime": "2026-02-13T15:00:00.000Z",
        "location": "Conference Room",
        "notes": "Weekly sync",
        "calendar": "Work",
        "allDay": false
      }
    ],
    "count": 1
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "CALENDAR_ACCESS_ERROR",
    "message": "Calendar access permission is required...",
    "recoverable": true,
    "permissionRequired": true
  }
}

错误代码

代码	含义	是否可恢复
CALENDAR_ACCESS_ERROR	权限被拒绝或无法访问日历	是
INVALID_INPUT	缺少必需参数	否
EVENT_NOT_FOUND	未找到事件 ID	否
OUTLOOK_NOT_AVAILABLE	未安装 Microsoft Outlook（Windows）	是

日期格式指南

重要：日期格式指南

使用 list 命令查询时间范围时：

1. 始终使用 ISO 8601 格式：YYYY-MM-DDTHH:mm:ss
2. 使用本地时区：不要使用 UTC 或时区后缀（如 +08:00 或 Z）
3. 自行计算日期：不要使用 $(date ...) 这样的 Shell 命令替换
4. 由 Claude 计算日期：根据当前日期直接计算目标日期
5. 示例：
   • 今天凌晨：2026-02-13T00:00:00
   • 今天结束时：2026-02-13T23:59:59
   • 明天上午：2026-02-14T09:00:00
   • 下周一：2026-02-16T00:00:00

原因：脚本需要与系统时区匹配的本地时间字符串。在所有环境中，Shell 命令替换可能无法正确执行。

常见模式

模式 1：日程管理

# User asks: "What meetings do I have today?"
# Claude's approach: Calculate today's date and query full day from 00:00 to 23:59
# IMPORTANT: Claude should replace 2026-02-13 with the actual current date
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-13T00:00:00" \
  --end "2026-02-13T23:59:59"

# User asks: "What's on my schedule tomorrow?"
# Claude should calculate tomorrow's date (e.g., if today is 2026-02-13, tomorrow is 2026-02-14)
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-14T00:00:00" \
  --end "2026-02-14T23:59:59"

模式 2：安排会议

# User asks: "Schedule a meeting for tomorrow at 3 PM"
# Claude's approach:
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Meeting" \
  --start "2026-02-13T15:00:00" \
  --end "2026-02-13T16:00:00" \
  --calendar "Work"

模式 3：搜索事件

# User asks: "Find all meetings about the project"
# Claude's approach:
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "project" \
  --calendar "Work"

模式 4：检查可用时间

# User asks: "Am I free tomorrow afternoon?"
# Claude's approach:
# 1. List tomorrow's events
# 2. Analyze time slots
# 3. Report availability
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-14T00:00:00" \
  --end "2026-02-14T23:59:59"

已知行为

时间范围匹配

list 命令使用区间重叠检测：

• 返回与查询时间范围有任何重叠的事件
• 不要求事件完全包含在该范围内

示例：

• 查询：2026-02-13 00:00:00 至 23:59:59
• 返回：
  • ✅ 完全在 2 月 13 日当天的事件（例如 10:00-11:00）
  • ✅ 跨越 2 月 13 日的多日事件（例如 2 月 12 日 10:00 - 2 月 14 日 10:00）
  • ✅ 跨越午夜的事件（例如 2 月 13 日 23:30 - 2 月 14 日 00:30）
  • ❌ 完全在 2 月 13 日之前的事件（例如 2 月 12 日 10:00-11:00）
  • ❌ 完全在 2 月 13 日之后的事件（例如 2 月 14 日 10:00-11:00）

全天事件

• 视为在其日期的 00:00:00 至 23:59:59 期间持续
• 多日全天事件（例如 2 月 12 日至 14 日）在查询该范围内任意日期时都会显示

时间精度

• 比较精确到秒
• 日期比较会忽略毫秒

重复事件

• 每次发生都视为单独的事件实例
• 脚本会返回查询时间范围内的各个事件实例

最佳实践

1. 创建前始终先检查

创建事件前，先列出已有事件以避免冲突：

# First check existing events
bash "<skill-dir>/scripts/calendar.sh" list

# Then create if no conflict
bash "<skill-dir>/scripts/calendar.sh" create ...

2. 使用特定日历（macOS）

指定日历以便整理事件：

bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Team Meeting" \
  --calendar "Work" \
  ...

3. 更新或删除前先搜索

始终先搜索，以获取正确的事件 ID：

# Search to find event ID
bash "<skill-dir>/scripts/calendar.sh" search --query "meeting"

# Then update or delete
bash "<skill-dir>/scripts/calendar.sh" update --id "FOUND-ID" ...

4. 妥善处理错误

解析响应并处理错误：

result=$(bash "<skill-dir>/scripts/calendar.sh" list)
if echo "$result" | grep -q '"success":true'; then
  # Process events
  events=$(echo "$result" | jq '.data.events')
else
  # Handle error
  error=$(echo "$result" | jq '.error.message')
  echo "Failed: $error"
fi

限制

macOS

• 需要 macOS 10.10 Yosemite 或更高版本（以支持 JXA）
• 需要日历访问权限
• 不支持高级重复事件查询
• 无法修改重复事件规则

Windows

• 需要安装 Microsoft Outlook
• 不支持其他日历应用（Windows Calendar、Google Calendar 等）
• 在企业环境中可能需要 COM 访问权限
• 枚举文件夹时可能会跳过受限日历

通用

• 所有日期都必须使用 ISO 8601 格式（YYYY-MM-DDTHH:mm:ss）
• 所有操作均使用本地时区
• 返回值会转换为 UTC（采用带 Z 后缀的 ISO 8601 格式）
• 不支持与会者或会议邀请

故障排除

macOS

权限被拒绝：

Error: Calendar access permission is required

**解决方案：**打开“系统设置”>“隐私与安全性”>“日历”，授权 Terminal 或 LobsterAI

找不到脚本：

bash: calendar.sh: No such file or directory

**解决方案：**确保使用 SKILL.md 所在目录下的绝对路径，并附加 /scripts/calendar.sh

Windows

找不到 Outlook：

Error: Microsoft Outlook is not installed or not accessible

**解决方案：**安装 Microsoft Outlook，并确保其配置正确

PowerShell 执行策略：

Error: Execution of scripts is disabled on this system

**解决方案：**以管理员身份运行 PowerShell 并执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

技术详情

macOS 实现

JXA（JavaScript for Automation）：

• 使用 osascript -l JavaScript 执行 JXA 代码
• 通过 Apple Events 控制 Calendar.app
• 适用于 Intel 和 Apple Silicon Mac
• 需要用户授予 Calendar 访问权限

日期处理：

• 使用 BSD date 命令（macOS 原生）
• 格式：date +%Y-%m-%dT%H:%M:%S（本地时区）
• 相对日期：date -v+7d（从现在起 7 天后）

Windows 实现

PowerShell + COM：

• 通过 PowerShell 使用 Outlook COM API
• 需要安装并配置 Outlook
• 适用于所有兼容 Outlook 的日历

日期处理：

• 使用 PowerShell [DateTime]::Parse() 解析日期
• 自动处理本地时区

跨平台一致性

两种实现均：

• 使用相同的 JSON 输出格式
• 支持相同的操作（列出、创建、更新、删除、搜索）
• 按本地时区处理日期
• 以 ISO 8601 格式返回 UTC 时间戳

相关技能

• imap-smtp-email - 用于基于电子邮件的会议邀请