前言¶

DeepSeek Harness（命令名 dsh）是 DeepSeek AI 開源的智能體運行時，核心理念寫在官方倉庫裏：Everything is a Plugin（一切皆插件）。模型、工具、技能、會話、沙箱、存儲、循環、調度和界面，都可以按 profile 增刪，不必改 harness 源碼。官方入門路徑是裝好 Node.js 後執行 npx @deepseek-ai/dsh web。目前仍是面向開發者的預覽版，接口還會變。

智能體很擅長改代碼、跑命令，但日程通常不在倉庫裏，而在 Google 日曆、iCloud 或自建 Nextcloud 上。你讓它「明天下午兩點排一次評審」，它既看不到現有佔用，也無法把事件寫回去。社區插件 dsh-calendar 補的就是這一段：用 CalDAV 把列表、創建、更新、刪除、搜索五件套交給模型。

需要先分清來源。本文引用的插件目錄 deepseek-harness-plugin.com 是獨立社區站點，用來發現和對比插件，與 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。下面按該目錄詳情頁、插件 GitHub 倉庫（含 README、package.json、cordis.patch.yml、源碼入口）以及 DeepSeek Harness 官方資料交叉覈對後整理。

這是什麼¶

dsh-calendar 是一款 工具與能力 插件，由 STARDUSTLC666 維護，源碼在 STARDUSTLC666/dsh-calendar。npm 包名同樣是 dsh-calendar，當前版本 0.3.2（package.json 與 npm registry 一致）。package.json 與 npm 元數據聲明許可證爲 MIT；倉庫根目錄目前沒有獨立的 LICENSE 文件，GitHub 倉庫元數據裏的 license 字段爲空，安裝前建議自行覈對。

2026 年 8 月 18 日打開目錄頁和 GitHub 時，星標均爲 3。目錄頁顯示主要語言爲 JavaScript，收錄日期 2026-08-15，最近推送 2026-08-16。倉庫源碼在 src/ 下是 TypeScript，構建產物在 lib/；運行時要求 Node.js 18 或更高。依賴是 tsdav、ical.js 和 undici，沒有原生擴展，README 寫成「純 Node 全平臺」。

一句話定位：它把 CalDAV 日曆變成五個面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），兼容 Google、iCloud、Nextcloud 以及任意自定義 CalDAV 端點。本輪是 node 半身，沒有 Web 設置頁，配置全部寫在 profile 的 cordis.patch.yml 裏。

缺配置時插件照常加載，不會把 dsh 拖垮；工具真正被調用時，纔會拋出帶中文指引的錯誤，提示補全配置後重啓。這是 README 和 cordis.patch.yml 註釋裏寫明的行爲。

核心功能¶

按倉庫 README 與源碼入口 src/index.ts，插件在 apply(ctx, config) 裏向宿主的 ctx.tools 註冊五個工具。事件的穩定標識 uid 是 CalDAV 對象的完整 href，更新和刪除都用它。

1. calendar_list：列出某時間段內的事件。start / end 用 ISO 8601，缺省是未來 7 天。默認展開 RRULE 重複事件（expand 默認 true，maxOccurrences 默認 30，範圍夾在 1–200）：每個實例單獨一行，帶 isOccurrence: true 和 seriesStart；非重複事件保持 isOccurrence: false。把 expand 設爲 false 時，重複事件按原始單條返回並帶 rrule。結果按開始時間穩定排序。
2. calendar_create：新建事件。summary / start / end 必填，description / location / allDay / rrule 可選。會校驗真實日曆日期，並要求 end >= start，拒絕 2025-02-30 這類不存在的日期。
3. calendar_update：按 uid 改事件。未提供的字段保留原值。0.3.2 修過「改其他字段時把 rrule 弄丟」的問題。
4. calendar_delete：按 uid 刪事件。
5. calendar_search：按關鍵詞在標題、描述、地點、UID 上做客戶端過濾，不區分大小寫。limit 默認 50，範圍夾在 1–200，結果按開始時間排序。搜索返回的是原始系列，不會展開重複實例。

時間約定也寫在 README 裏：輸入輸出統一 ISO 8601。定時事件輸出爲 UTC（例如 2025-01-15T01:00:00Z），全天事件輸出 YYYY-MM-DD。輸入可以帶時區偏移（例如 2025-01-15T09:00:00+08:00），插件內部轉成 UTC 再存儲。帶 TZID 的事件輸出會轉成 UTC；全天邊界、夏令時等複雜規則不做精細處理。

另外兩個實現細節值得單獨記下：

• 插件級代理：配置項 proxyUrl（例如 http://127.0.0.1:7890）只把本插件的 CalDAV 請求轉到本機代理端口，不改系統代理，也不影響其他插件。README 寫明：中國大陸訪問 Google / iCloud 的 CalDAV 端點通常需要填這項；國內可直連的服務（例如自建 Nextcloud）可以不填。
• 客戶端失敗可重試：0.3.2 起，CalDAV 客戶端創建失敗後會清空緩存，下一次調用可以重新建連，不再永久複用被拒絕的 Promise。

安裝與啓用¶

目錄頁給出的安裝命令如下，以頁面原文爲準：

dsh plugin add github:stardustlc666/dsh-calendar

如需可復現安裝，按目錄頁說明固定 commit 哈希。撰寫時倉庫 main 最新提交是 596f0420ac0f72db190d078cec91a4c18916b60b（2026-08-16）：

dsh plugin add github:stardustlc666/dsh-calendar#596f0420ac0f72db190d078cec91a4c18916b60b

倉庫 README 還寫了一種按 npm 包名、並指定 web profile 的裝法：

dsh plugin --profile web add dsh-calendar

兩種寫法指向同一份社區插件。目錄頁強調：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；安裝前請檢查源代碼倉庫和許可證。

安裝後需要重啓 dsh。插件會向 profile 插入一行 id 爲 calendar 的配置（見包內 cordis.patch.yml）。默認 provider 爲 custom，且未填憑證。

配置與典型用法¶

所有配置都在當前 profile 的 cordis.patch.yml 裏，按 id 覆蓋 calendar 這一行的整個 config。通用字段如下：

• provider：google | icloud | nextcloud | custom
• caldavUrl：完整日曆集合 URL（custom / icloud 必填；google / nextcloud 也可手填覆蓋預設）
• username：CalDAV 賬號（Google / iCloud 用賬號郵箱）
• password：密碼；Google / iCloud 請用應用專用密碼。推薦改用環境變量 DSH_CALENDAR_PASSWORD，避免明文寫進配置文件
• proxyUrl：本機代理地址
• calendarId：僅 Google，日曆 ID（通常是郵箱）
• host / user / calendar：僅 Nextcloud

Google 示例（URL 由插件拼成 https://apidata.googleusercontent.com/caldav/v2/<calendarId>/events）：

- id: calendar
  name: dsh-calendar
  config:
    provider: google
    username: you@gmail.com
    calendarId: you@gmail.com
    # password 推薦用環境變量 DSH_CALENDAR_PASSWORD
    # 若 CalDAV 端點無法直連，再填：
    # proxyUrl: http://127.0.0.1:7890

iCloud 需要完整日曆集合 URL（含用戶 ID 與日曆 ID），倉庫說明可在 iCloud 的日曆 CalDAV 設置裏找到，插件不做 principal 自動發現：

- id: calendar
  name: dsh-calendar
  config:
    provider: icloud
    username: you@icloud.com
    caldavUrl: https://caldav.icloud.com/123456789/calendars/<日曆ID>/

Nextcloud 示例（插件會拼成 https://cloud.example.com/remote.php/dav/calendars/alice/personal/）：

- id: calendar
  name: dsh-calendar
  config:
    provider: nextcloud
    username: alice
    host: https://cloud.example.com
    user: alice
    calendar: personal

自定義 CalDAV：

- id: calendar
  name: dsh-calendar
  config:
    provider: custom
    caldavUrl: https://dav.example.com/calendars/me/work/
    username: me

應用專用密碼不要和登錄密碼搞混。README 的路徑是：

• Google：myaccount.google.com → 安全 → 兩步驗證（需先開啓）→ 應用專用密碼，生成 16 位密碼。
• iCloud：appleid.apple.com → 登錄與安全 → App 專用密碼。

調用返回 401/403 時，倉庫說明多半是用了登錄密碼而不是應用專用密碼，插件會給出中文提示。認證方式只有 Basic，沒有 Google / iCloud 的 OAuth 流程。

配好之後，在會話裏可以直接讓模型調用這些工具，例如：列出接下來一週的事件、新建一場帶 rrule 的週會、按關鍵詞搜「評審」、或按 uid 改時間 / 刪除。工具參數以倉庫當前 README 爲準，本文不另編對話記錄。

適用場景與注意事項¶

適合已經在用 CalDAV 的個人或小團隊：希望 DeepSeek Harness 裏的智能體能查看空檔、寫入會議、改時間或按標題搜索，而不必再切到日曆網頁。自建 Nextcloud 或其它可直連的 CalDAV 服務，配置相對簡單；接 Google / iCloud 時，要準備應用專用密碼，並按網絡環境決定是否填寫 proxyUrl。

使用前把下面這些限制看清楚，它們都來自倉庫「已知限制」，不是推斷：

1. 重複事件：calendar_list 默認用 ICAL.RecurExpansion 展開，受 maxOccurrences 封頂；calendar_search 不展開。calendar_update / calendar_delete 針對整個重複系列，不能只改或只刪某一次發生（不支持 RECURRENCE-ID）。
2. 不做 OAuth、不做日曆發現：iCloud 必須手填完整集合 URL；沒有多日曆選擇器。
3. 沒有設置頁 UI：本輪配置只走 cordis.patch.yml。
4. 超時：工具整體超時 timeoutMs 爲 60 秒，不會把 AbortSignal 透傳到每一次網絡請求。
5. 憑證與權限：密碼會出現在配置或環境變量裏，插件能列出、創建、修改和刪除日曆事件。它以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。

小結¶

dsh-calendar 做的事情很具體：把 CalDAV 日曆接到 DeepSeek Harness 的工具層，讓智能體在已有的 Google / iCloud / Nextcloud / 自定義日曆上完成列表到搜索這一套操作。它不提供設置頁，也不做 OAuth；換來的是純 Node、缺配置不崩啓動、以及只作用於本插件的 proxyUrl。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-calendar/

GitHub：https://github.com/STARDUSTLC666/dsh-calendar