dsh-calendar: A CalDAV and Chinese Calendar Integration Plugin for DeepSeek Harness

Introduction¶

The DeepSeek Harness (DSH) ecosystem emphasizes modularity. Scheduling tasks usually require connecting to an external calendar service or manually implementing complex iCalendar rules. johnxu22786/calendar is a plugin for DSH that combines CalDAV protocol integration with Chinese calendar features and is provided as a standalone npm package.

Core Features¶

CalDAV Integration¶

The plugin supports the standard CalDAV protocol, using REPORT/PROPFIND/GET/PUT/DELETE methods to list, create, update, delete, and search events. It includes a built-in automatic discovery mechanism (well-known → current-user-principal → calendar-home-set → calendars) and supports Basic authentication and the Google OAuth2 device flow.

RRULE Extension and Single-Instance Editing¶

The plugin includes an RFC 5545 recurrence rule engine implemented from scratch, supporting parameters such as FREQ, INTERVAL, COUNT, UNTIL, BYDAY, and BYMONTH. When editing or deleting a single instance, it generates overrides (STATUS:CANCELLED) via RECURRENCE-ID without modifying the master event of the series.

Chinese Calendar Support¶

For Chinese users, the plugin builds in astronomical-based lunar calendar conversion (covering 2000-2100), Chinese holidays (Spring Festival, National Day, etc.), sexagenary cycle/Chinese zodiac (anchored to Lichun), and the default timezone Asia/Shanghai.

Conflict Detection and Time Zones¶

The plugin can detect overlapping events (including all-day events and overlap across recurring instances). It has an embedded, runtime-dependency-free timezone engine that correctly handles daylight saving time (DST) transitions.

Installation and Enablement¶

Prerequisites: Ensure DeepSeek Harness (DSH) is installed and configured.

1. Enter the plugin directory.
2. Install dependencies and build.
3. Install the plugin into the specified DSH configuration profile.

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

Configuration¶

Configuration is set through the plugin’s Config schema (usually in cordis.patch.yml or a configuration override layer).

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

Credentials are managed via environment variables or the DSH credential service (never logged).

Configure the Google OAuth2 device flow (suitable for headless environments) as follows:

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

Typical Usage¶

List Events¶

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

Create a Recurring Event¶

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

Update a Single Instance¶

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

Check Conflicts¶

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

Get Holidays and Sexagenary Cycle¶

dsh-calendar holidays --days 60

Use Cases and Notes¶

Use Cases:
* DSH agents that need to connect to Google Calendar, iCloud, Nextcloud, or custom CalDAV servers.
* Workloads requiring complex recurrence rules (RRULE) and single-instance modification support.
* Workloads requiring lunar calendar, Chinese holiday, and sexagenary cycle calculations.

Notes:
* No runtime dependencies: The plugin itself has no runtime dependencies; peerDependencies are provided by the DSH runtime.
* Google OAuth2: In headless environments, Google authentication must use the device flow.
* Permission security: The plugin runs with the permissions of the current DSH process. Review the source code and license before installation to ensure trust.
* Credential security: All credentials are handled through environment variables or the DSH credential service and are automatically redacted in output.

Summary¶

This plugin provides DSH with a complete calendar toolchain, addressing the pain points of external calendar integration and Chinese calendar processing, while avoiding runtime dependencies through embedded engines.

• GitHub Repository
• DSH Ecosystem Catalog