Canon for DeepSeek Harness 插件

前言¶

DeepSeek Harness (DSH) 採用了插件化的架構，旨在通過模塊化組件構建智能體執行環境。heybobchan/canon-deepseek-harness-plugin 是一個 Canon 集成插件，它將 Canon 作爲一個額外的交互渠道添加到 DSH 配置中。該插件不替代 DSH 的 Web UI、會話或持久化機制，而是負責將 Canon 的消息映射到 DSH 的協議中，處理審批流程、工具調用以及會話恢復。DSH 擁有模型、權限、持久化和執行環境，而 Canon 負責適配消息、展示活動以及處理特定的交互卡片。

安裝與註冊¶

要在 DSH 環境中使用 Canon，需要先註冊 Canon 代理，然後安裝插件包。

註冊 Canon 代理
使用 canon-dsh-register 命令在 Canon 中創建一個代理，並指定其客戶端類型爲 deepseek-harness。

    canon-dsh-register \
      --name "My DSH Agent" \
      --description "Coding agent in DeepSeek Harness" \
      --phone "+15551234567" \
      --profile my-dsh

安裝插件
在選定的 DSH 配置文件中添加插件包。DSH 的插件管理器會識別 dsh.bundle.patch 並將包添加到配置列表中。

    dsh plugin --profile my-dsh-profile add @canonmsg/deepseek-harness-plugin

驗證配置
在啓動代理之前，可以檢查配置是否正確加載。設置 CANON_AGENT 環境變量以指向剛纔註冊的配置文件。

    CANON_AGENT=my-dsh dsh --profile my-dsh-profile --dump-config

確認輸出中包含 `canon-dsh` 行且已啓用。

啓動 DSH
從項目工作目錄啓動 DSH。

    cd /path/to/project
    CANON_AGENT=my-dsh dsh --profile my-dsh-profile

核心功能¶

該插件實現了 Canon 與 DSH 之間的協議映射，主要包含以下能力：

會話持久化與恢復：爲每個 Canon 對話建立一個持久的 DSH 會話。DSH 的會話日誌是事件源的，插件可以從中恢復會話狀態。
生命週期管理：遵循 Cordis 生命週期行爲。插件在啓動後變爲活躍狀態，SSE（Server-Sent Events）循環由插件的可逆效果管理，卸載或熱替換時會停止。
消息批處理：Canon 的消息批處理被映射爲一條不可變的 DSH 用戶消息，由 DSH 的收件箱進行調度。
圖片支持：通過 DSH 的持久化附件存儲支持 PNG、JPEG、WebP 和 GIF 輸入。DSH 對圖片的數量、字節、尺寸和歸一化策略擁有最終決定權。
流式響應與活動：展示助手的文本流式傳輸。提供 DSH 輪次、工具調用結果和聚合 todo 進度的運行時活動，但不暴露原始的工具參數或 todo 內容。
審批機制：將 DSH 的審批請求渲染爲 Canon 的一鍵式審批卡片。
用戶問題與計劃審查：將 DSH 的 ask_user_question 請求渲染爲運行時輸入卡片（需配置 questionProvider）。將 DSH 的 plan-review 意圖渲染爲 Canon 原生的計劃審查卡片。
工具支持：
- 提供 DSH 原生的 communicate 工具，用於消息、對話、羣組、轉發和聯繫人共享。
- 提供 Canon 標準的 no_reply 工具，用於保持靜默而不發送消息或觸發其他代理。
信號處理：支持中斷、停止並丟棄（Stop-and-drop）以及新建會話信號。

配置¶

插件通過環境變量和配置字段進行控制。

環境變量¶

變量名	用途	默認值
`CANON_AGENT`	Canon 配置文件名稱，位於 `~/.canon/agents.json`	空（當只有一個匹配配置時自動選擇）
`CANON_DSH_WORKSPACE`	DSH 工作區根目錄的絕對路徑	DSH 調用目錄
`DSH_PROVIDER`	Canon 創建的代理使用的可選提供者路由	DSH 默認設置
`DSH_MODEL`	Canon 創建的代理使用的可選模型	DSH 默認設置
`CANON_DSH_DISABLED`	設置爲 `1` 時僅禁用 Canon 行	啓用

DSH_PROVIDER 和 DSH_MODEL 必須同時提供。若兩者均不提供，則使用配置文件的默認模型選擇。

插件字段¶

以下字段由插件定義，而非推斷：

questionProvider: external \| canon：選擇 DSH 用戶問題提供者。通用 Web 補丁使用 external，無頭部署使用 canon。
planMode: boolean：聲明 Canon 的計劃輪次模式，需要組合的 ctx.planMode 服務支持，默認補丁中關閉。

當前限制¶

該插件處於開發者預覽階段，存在以下已知限制：

版本鎖定：Canon 將直接 DSH 服務 API 鎖定在 0.1.1-rc.2，插件也僅針對此版本測試。
用戶問題提供者限制：DSH 0.1.1-rc.2 在 Cordis 上下文中僅允許一個活躍的用戶問題提供者。因此，Canon 問題需要配合 questionProvider: canon 使用。
非圖片附件：非圖片的 Canon 附件將保留爲安全文本佔位符。
控制權未完全暴露：Provider/Model、權限模式、effort、workspace 選擇、執行模式、會話狀態快照、富卡片以及 steering/interleave 等控制項尚未作爲 Canon 控制項公開，因爲橋接層尚未完成端到端的驗證和強制執行。
會話規則：Canon 會話規則在此橋接中已被禁用。

總結¶

該插件爲 DeepSeek Harness 提供了基於 Canon 的消息通道。開發者可以通過命令行工具完成代理註冊和插件安裝，利用插件提供的審批卡片、工具映射和會話恢復功能，在 Canon 應用中直接與 DSH 智能體交互。