前言¶

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 協議和嚴格的刪除閘門設計，它能夠在保證跨平臺兼容性的同時，提供安全可靠的日曆自動化能力。

• 插件目錄頁
• GitHub 倉庫