前言¶
DeepSeek Harness (DSH) 的核心設計理念之一是“一切皆插件”。在開發智能體時，讓 Agent 能夠直接讀寫用戶的任務管理工具（如滴答清單）是一個常見需求。現有的集成方式往往依賴第三方庫或非官方接口，存在安全風險和兼容性問題。dsh-ticktick 插件通過調用官方 Open API，爲 DSH 提供了標準化的雙向任務同步能力。
插件介紹¶
dsh-ticktick 是由用戶 zhengjy01 維護的 DSH 插件，旨在解決智能體與 TickTick / Dida365（滴答清單）之間的數據同步問題。該插件基於官方 OAuth 2.0 Open API 構建，支持拉取任務、創建任務、更新狀態以及一鍵去重同步，並提供了一個 Web 端設置面板用於管理憑證。
核心功能¶
該插件提供以下核心能力：
- 官方 API 集成：使用 OAuth 2.0 授權碼模式對接 TickTick / Dida365 開放平臺（
/open/v1），支持 401 響應時的令牌自動刷新。 - 多區域支持：支持國內版 Dida365（默認）和國際版 TickTick，可在設置面板或通過
ticktick_config切換。 - 拉取任務：
ticktick_tasks/ticktick_sync可跨所有列表（包括收集箱 Inbox，儘管 Open API 的項目列表可能不包含它）拉取未完成或已完成的任務，按截止日期排序並附帶列表名稱。 - 創建任務：
ticktick_add支持創建任務，參數包括標題、列表（通過 ID 或名稱，inbox/收集箱映射到 Inbox）、截止日期（ISO 8601 或YYYY-MM-DD）、優先級（0-5 或 none/low/medium/high）、標籤及內容。 - 單次同步：
ticktick_sync提供單向同步能力。direction=pull返回分組摘要；direction=push會創建缺失的任務，並在列表內按標題去重（包括 Inbox，重複運行不會產生重複任務）。 - 任務維護：提供
ticktick_update（更新）、ticktick_complete（完成）、ticktick_delete（刪除）接口，支持可選的項目 ID（自動解析，包含 Inbox）。 - Web 設置面板：在 DSH Web 設置中，可配置憑據、運行授權流程（彈窗 + 手動輸入驗證碼）、刷新令牌、快速添加任務（列表選擇器優先顯示 Inbox，排除已歸檔列表）。
- 安全存儲：憑證和令牌持久化至
~/.dsh/dsh-ticktick.（權限 0600），狀態查詢命令ticktick_status不會回顯密鑰。
安裝與啓用¶
安裝此插件需要 DSH 環境。
- 執行以下命令安裝：
dsh plugin --profile web add github:zhengjy01/dsh-ticktick
- 安裝完成後，重啓
dsh web服務。 - 插件無需構建步驟，依賴 Node.js 內置的
fetch和crypto（要求 Node 22+），無額外運行時依賴。
配置¶
在首次使用前，需完成 OAuth 授權並配置憑證。
- 創建應用：
在 TickTick / Dida365 開放平臺控制台創建應用，並設置重定向 URI。該 URI 必須與 DSH Web 服務監聽的本地地址匹配，例如：
http://127.0.0.1:3080/api/dsh-ticktick/oauth/callback
- 輸入憑據：
在 DSH 設置面板進入 TickTick 配置頁面，輸入client_id和client_secret。你也可以通過對話讓 Agent 執行ticktick_config來設置這些參數。 - 授權登錄：
在設置面板點擊“開始授權”，登錄後完成回調；若回調失敗，可手動粘貼驗證碼並調用ticktick_oauth_finish。 - 系統提示：
插件會向系統提示詞注入相關說明，告知智能體在何時應當使用此工具。
典型用法¶
配置完成後，Agent 可通過自然語言調用相關接口：
- 拉取今日未完成任務：
把今天滴答清單裏沒做完的任務同步給我
對應操作：`ticktick_sync` (pull)
- 推送新任務並去重：
幫我把這些任務同步到滴答清單：買牛奶、寫週報
對應操作：`ticktick_sync` (push, dedupes)
- 添加指定任務：
明天下午3點提醒我開會，加到「工作」清單
對應操作：`ticktick_add`
注意事項¶
- 安全風險：
client_secret和 OAuth 令牌是高權限憑證。插件將其存儲在本地文件~/.dsh/dsh-ticktick.（權限 0600）中。如果憑證泄露，請立即運行ticktick_config(reset: true)清除。 - 網絡限制：OAuth 回調路由僅允許本地迴環訪問；其餘
/api/dsh-ticktick/*路由僅允許本地和同源訪問。 - API 覆蓋範圍：Open API 不支持智能列表過濾和時間觸發提醒（
reminders/repeatFlag僅在存在時透傳，未建模爲參數）。
結語¶
dsh-ticktick 通過官方 Open API 實現了與滴答清單的雙向同步，爲 DSH 智能體提供了可靠的任務管理能力。無論是日常任務整理還是自動化流程編排，該插件都能提供落地的工具支持。更多細節與源碼，可訪問 GitHub 倉庫。
