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 智能体交互。