前言¶
DeepSeek Harness (DSH) 采用插件化架构，旨在让智能体具备联网与工具调用能力。在开发涉及日历管理的智能体时，若需跨平台自动化管理 Apple iCloud 日历，会面临技术限制：苹果未公开 iCloud 日历的 REST API，且 EventKit 仅在 macOS 本机可用。跨平台唯一可行的自动化入口是 CalDAV（RFC 4791）。
dsh-icloud-calendar 是一个 DeepSeek Harness (DSH) 插件，它通过 CalDAV 协议读写 Apple iCloud 日历，内置跨平台凭据存储、请求超时重试机制以及确认式删除保护。
插件简介¶
插件名称：dsh-icloud-calendar
维护者：CaiMingshen
开源协议：MIT
核心价值：提供一套标准化的 CalDAV 客户端，解决 iCloud 日历无官方 API 下的自动化读写问题，并严格设计删除操作的安全闸门。
核心功能¶
该插件提供以下核心能力：
1. CalDAV 读写：通过标准协议连接 https://caldav.icloud.com/，支持日历的创建与事件管理。
2. 日历与事件操作：列出日历和事件（自动展开重复日程），支持创建事件。
3. 安全删除机制：实现四道闸门的删除保护（总开关、时间窗口、精确匹配、二次确认），默认不开启删除且默认为干跑。
4. 跨平台凭据存储：自动适配 Windows (DPAPI)、macOS (钥匙串) 和 Linux (libsecret) 的凭据存储。
5. 网络健壮性：支持请求超时、自动重试以及 HTTP 代理配置（需依赖 undici）。
安装与配置¶
安装前请确保环境满足以下要求：
* DSH 版本 >=0.2.0-rc.2
* Node.js 版本 ^22.19 || >=24
安装命令：
dsh plugin --profile web add github:<你的用户名>/dsh-icloud-calendar
插件安装后，需在 cordis.patch.yml 中插入配置以启用服务与工具。该插件以 Bundle 形式分发，配置分为两行：
1. dsh-icloud-calendar/host：注册服务，处理连接复用、缓存与策略。
2. dsh-icloud-calendar/tools：将服务暴露为 5 个模型可见的工具。
配置示例：
- insert:
- id: icloud-calendar-host
name: 'dsh-icloud-calendar/host'
config:
account: 'you@example.com' # iCloud 账号
secretEnv: ICLOUD_APP_PASSWORD # 密码所在环境变量
secretSource: auto # auto | env | store
allowWrites: true
allowDeletes: false # 默认关闭删除
maxDeletesPerCall: 1
timeoutMs: 30000
retries: 2
proxyUrl: '' # HTTP 代理地址
- id: icloud-calendar-tools
name: 'dsh-icloud-calendar/tools'
注意：插件配置文件中不会包含密码字段，这是为了防止明文泄露。密码通过系统凭据存储或环境变量读取。
凭据管理¶
插件强制要求使用 Apple App 专用密码，严禁使用 Apple ID 登录密码。
生成 App 专用密码：
1. 登录 Apple ID 账户管理页面。
2. 进入“登录与安全” -> “App 专用密码” -> “生成”。
3. 获得类似 abcd-efgh-ijkl-mnop 的字符串。
凭据来源：
* 系统凭据存储（推荐）：Windows 使用 DPAPI，macOS 使用钥匙串，Linux 使用 libsecret。
* 环境变量：通过 secretEnv 指定变量名（默认为 ICLOUD_APP_PASSWORD）。
* 读取方式：Windows/Linux 下密码从标准输入 (stdin) 读取；macOS 下通过命令行参数传递。
工具与用法¶
插件提供 5 个模型可见的工具和配套的命令行工具。
模型可见工具：
* calendar_status：检查配置、凭据来源与连通性。
* calendar_list_calendars：列出日历及属性。
* calendar_list_events：按时间窗读取事件（重复日程已展开）。
* calendar_create_event：创建事件。
* calendar_delete_events：删除事件。
CLI 命令示例：
# 1. 探测连接状态
dsh-icloud-calendar status --probe
# 2. 登录（密码从 stdin 读取）
dsh-icloud-calendar login --account you@example.com
# 3. 列出指定时间窗的事件
dsh-icloud-calendar events --start 2026-01-05T00:00:00+08:00 --end 2026-01-12T00:00:00+08:00
# 4. 创建事件
dsh-icloud-calendar add --summary '评审' --start 2026-01-05T09:00:00+08:00 --end 2026-01-05T10:00:00+08:00 --time-zone Asia/Shanghai
# 5. 删除事件（默认干跑，需确认参数）
dsh-icloud-calendar delete --start 2026-01-01T00:00:00+08:00 --end 2026-02-01T00:00:00+08:00 --uid <uid>
删除安全机制¶
为了防止误删，删除操作设计了四道闸门：
1. 总开关：默认 allowDeletes: false，必须手动开启。
2. 时间窗口：必须指定 start 和 end，且删除窗口上限（默认 90 天）通常小于读取窗口。
3. 精确匹配：只能使用 uid（来自列表事件）或 summaryEquals（完整标题，区分大小写），拒绝子串或模糊匹配。
4. 二次确认：默认 dryRun=true。真删需设置 dryRun=false 且 confirmCount 等于匹配到的对象数，同时受 maxDeletesPerCall（默认 1）限制。
注意事项¶
- 代理支持：HTTP 代理功能依赖可选依赖
undici，未安装时会给出明确提示。 - 默认行为：删除操作默认为干跑，真删需满足上述多重条件。
- 权限与网络：插件以 DSH 进程权限运行，请确保安装前检查源码与许可证。国内直连 iCloud 可能需要配置代理。
- 凭据安全：凭据不会出现在 profile 配置文件中，防止明文泄露。
结尾¶
dsh-icloud-calendar 为 DSH 插件生态提供了 iCloud 日历的标准接入方案。通过 CalDAV 协议和严格的删除闸门设计，它能够在保证跨平台兼容性的同时，提供安全可靠的日历自动化能力。
