dsh-calendar：DeepSeek Harness 的 CalDAV 與中文日曆集成插件

前言¶

DeepSeek Harness (DSH) 生態強調模塊化，處理日程安排通常需要連接外部日曆服務或自行實現複雜的 iCalendar 規則。johnxu22786/calendar 是一個針對 DSH 的插件，它將 CalDAV 協議集成與中文日曆特性結合，作爲獨立的 npm 包提供。

核心功能¶

CalDAV 集成¶

插件支持標準的 CalDAV 協議，通過 REPORT/PROPFIND/GET/PUT/DELETE 方法實現事件的列表、創建、更新、刪除和搜索。它內置了自動發現機制（well-known → current-user-principal → calendar-home-set → calendars），並支持 Basic 認證和 Google OAuth2 設備流。

RRULE 擴展與單實例編輯¶

插件包含一個從零實現的 RFC 5545 重複規則引擎，支持 FREQ、INTERVAL、COUNT、UNTIL、BYDAY、BYMONTH 等參數。在編輯或刪除單個實例時，它通過 RECURRENCE-ID 生成覆蓋項（STATUS:CANCELLED），而不會修改系列主事件。

中文日曆支持¶

針對中文用戶，插件內置了天文計算的農曆轉換（覆蓋 2000-2100 年）、中國節假日（春節、國慶等）、干支/生肖（基於立春錨定）以及默認時區 Asia/Shanghai。

衝突檢測與時區¶

插件能檢測重疊事件（包括全天事件和跨重複實例的重疊）。它擁有嵌入式、無運行時依賴的時區引擎，能正確處理夏令時（DST）轉換。

安裝與啓用¶

先決條件：確保已安裝並配置好 DeepSeek Harness (DSH)。

1. 進入插件目錄。
2. 安裝依賴並構建。
3. 將插件安裝到指定的 DSH 配置文件中。

npm install
npm run build
dsh plugin --profile <name> add ./calendar

配置¶

配置通過插件的 Config schema 設置（通常在 cordis.patch.yml 或配置覆蓋層中）。

- insert:
    - id: calendar
      name: dsh-calendar
      config:
        defaultTimezone: Asia/Shanghai
        serverUrl: https://nextcloud.example.com/remote.php/dav/
        authMode: basic   # basic | google

憑證通過環境變量或 DSH 憑證服務管理（絕不記錄到日誌）。

Google OAuth2 設備流（適用於無頭環境）配置如下：

dsh-calendar auth google --device --client-id <CLIENT_ID>

典型用法¶

列出事件¶

dsh-calendar list  [--start "2026-01-01" --end "2026-01-31" --tz Asia/Shanghai]

創建重複事件¶

dsh-calendar create   --summary "Team sync" --start "2026-03-02 10:00" --end "2026-03-02 11:00" --rrule "FREQ=WEEKLY;COUNT=4"

更新單實例¶

dsh-calendar update   <uid> --summary "Renamed" --recurrence-id "2026-03-09 10:00" --start "2026-03-09 15:00"

檢查衝突¶

dsh-calendar conflicts --start "2026-06-01 14:00" --end "2026-06-01 15:00"

獲取節假日與干支¶

dsh-calendar holidays --days 60

適用場景與注意事項¶

適用場景：
* 需要連接 Google Calendar、iCloud、Nextcloud 或自定義 CalDAV 服務器的 DSH 智能體。
* 需要處理複雜的重複規則（RRULE）並支持單實例修改。
* 需要農曆、中國節假日及干支計算功能。

注意事項：
* 無運行時依賴： 插件本身無運行時依賴，peerDependencies 由 DSH 運行時提供。
* Google OAuth2： 在無頭環境中，Google 認證必須使用設備流。
* 權限安全： 插件以當前 DSH 進程的權限運行。安裝前請檢查源碼與許可證，確保信任。
* 憑證安全： 所有憑證通過環境變量或 DSH 憑證服務處理，輸出中會自動脫敏。

總結¶

該插件爲 DSH 提供了一套完整的日曆工具鏈，解決了外部日曆集成與中文日曆處理的痛點，同時通過嵌入式引擎避免了運行時依賴。

• GitHub 倉庫
• DSH 生態目錄