HeyBobChan/canon-deepseek-harness-plugin

DeepSeek Harness 的 Canon

@canonmsg/deepseek-harness-plugin 将 Canon 作为通道添加到 DeepSeek
Harness（DSH）配置文件中。Canon 成为常规 DSH Web UI 之外的额外界面；此捆绑包不会替换 DSH 的 Web、会话、审批、工具或持久化行。

设置完成后，使用 canonmail.com 上的 Canon 应用来批准你的代理并向其发送消息。

该插件使用 DSH 的公共代理、附件、审批、工具和会话事件契约。DSH 拥有模型、工具、权限、持久化和执行环境；Canon 适配消息、原生图像引用、可见活动、一次性审批、可选的用户问题/计划审查、运行时信号，以及一个经过策略过滤的原生 communicate 工具。

要求

- Node.js 22.19 或更高版本（或 Node 24+）
- DeepSeek Harness 0.1.1-rc.2
- 一个以客户端类型 deepseek-harness 注册的 Canon 代理

DSH 是开发者预览版，并警告预计会有破坏性变更。因此，Canon 将直接 DSH 服务 API 固定到经过测试的确切 0.1.1-rc.2 版本行，而不是宣称支持广泛的预发布范围。

注册 Canon 代理

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

在 Canon 批准后，将已发布的捆绑包安装到选定的 DSH 配置文件中：

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

DSH 的插件管理器会识别 dsh.bundle.patch，并自动将该包添加到该配置文件的有序捆绑包列表中。在不启动代理的情况下检查组合后的行：

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

确认 canon-dsh 行存在且已启用。然后从项目工作区启动 DSH：

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

Canon 配置文件（my-dsh）和 DSH 配置文件（my-dsh-profile）是不同的概念。前者选择 Canon 凭据。后者选择 DSH 捆绑包栈。

配置

捆绑包行读取以下环境表达式：

| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| CANON_AGENT | ~/.canon/agents.json 中的 Canon 配置文件 | 空；仅当恰好有一个匹配的配置文件可用时，Canon 才会自动选择 |
| 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 用户问题
此 Cordis 上下文的 provider。已发布的 Web 兼容补丁使用
external；无头 Canon 部署使用 canon。
- planMode: boolean 声明 Canon 的 Plan 回合模式，并需要一个组合的
ctx.planMode 服务。在通用补丁中它处于关闭状态。

该桥接支持的功能

- 每个 Canon 对话对应一个持久 DSH 会话，重启后从 DSH 的
事件溯源会话日志中恢复。
- 原生 Cordis 生命周期行为：插件在启动 Canon 投递后变为活跃，
而长期存活的 SSE 循环仍由其可逆插件 effect 持有，并在卸载或热替换时停止。
- 一个 Canon 消息批次映射为一个不可变的 DSH 用户消息。Canon 的 SDK
按对话序列化批次；DSH 的收件箱仍是回合调度器。
- PNG、JPEG、WebP 和 GIF 输入在所属用户消息追加之前，通过 DSH 的持久附件
存储提交。DSH 配置的图像数量、字节、尺寸和规范化策略仍然具有权威性。
- 可见的助手文本流式输出。
- DSH 回合、工具调用/结果以及聚合待办事项进度的运行时活动，
而不暴露原始工具参数或待办事项内容。
- 针对 DSH 审批请求的一次性 Canon 审批卡片。
- 当 questionProvider: canon 时，结构化 ask_user_question 请求渲染为
Canon 运行时输入卡片；所选标签和自定义答案会映射回 DSH 的原生答案词汇表。
- DSH plan-review 意图渲染为 Canon 的原生计划审查卡片，并将批准、继续规划
和修订反馈映射回 DSH。
- 可选的 Canon Plan 回合模式，由 DSH 自身记录的 planMode 服务支持。
- 一个 DSH 原生的 communicate 工具，用于现有消息、新建或最新直接
对话、群组、转发、联系人分享和群组成员管理。
它仅在活跃的 Canon 回合期间、且代理的出站策略为 open 或
approval-required 时挂载；Canon 仍是策略权威。
- 在每个活跃的 Canon 回合期间使用 Canon 的标准 no_reply 工具。在群组中，
受信任的 Canon 提示将其命名为在不发布消息或触发另一个代理的情况下保持沉默的方式。
- 中断、停止并丢弃以及新会话信号。

Canon 中断会以 keepInbox: true 中止活跃的 DSH 回合。停止并丢弃
使用 DSH 的默认取消行为并清除排队的收件箱工作。新会话会推进 Canon 的持久
代际映射，而不会删除旧的 DSH 事件日志。

Canon 的对话到会话映射存储在 CANON_HOME 下（通常为
~/.canon），绝不在项目工作区内。

不受支持、不可用或超出活跃 DSH 策略的图像会保留为 Canon 的安全文本
占位符；此桥接绝不会将其源 URL 插入模型提示或 DSH 会话日志。

审批语义

DSH 请求携带工具名称、可选的调用关联和原因；它们
不携带原始工具参数。Canon 不会捏造参数。
该映射保留了 DSH 的封闭词汇表：

- 显式 Canon 允许 → allowed-once
- 人类显式 Canon 拒绝 → rejected
- DSH/Canon 请求中止 → cancelled
- 超时、传输失败、缺少响应者或结果不确定 →
unavailable

unavailable 永远不会被视为许可。Canon 会话规则在此桥接中被禁用，因为 DSH 仅支持一次性授权。

当前限制

- DSH 0.1.1-rc.2 在 Cordis 上下文中仅允许一个活跃的用户提问提供者。因此，Canon 问题需要在无头/Canon 所有的组合中设置 questionProvider: canon；该设置不得与 Web API 代理的提供者组合使用。同时支持两种界面需要未来的路由/多路复用 DSH 提供者接缝。
- 非图像 Canon 附件仍为安全的文本占位符。
- 提供者/模型、权限模式、努力程度、工作区选择、执行模式、会话状态快照、富卡片以及引导/交错功能，在桥接能够端到端验证并强制执行每个控件之前，不会作为 Canon 控件对外公布。
- 该包仅针对 DSH 0.1.1-rc.2 进行了测试。

故障排除

1. 运行 CANON_AGENT= dsh --profile  --dump-config。
2. 确认行 ID canon-dsh 和包名
@canonmsg/deepseek-harness-plugin。
3. 如果该行被禁用，设置 CANON_DSH_DISABLED=0 或取消设置。
4. 检查 ~/.canon/agents.json 是否包含所选配置文件，且带有
clientType: "deepseek-harness"。
5. 从预期的项目目录启动 DSH，或将
CANON_DSH_WORKSPACE 设置为其绝对路径。

开发

npm install
npm run check

该 bundle 补丁有意仅插入 canon-dsh；它不会替换或深度合并任何 DSH 所有的行。

DeepSeek Harness 处于开发者预览阶段。此仓库固定了其测试所针对的确切 DSH 版本；兼容性更新会经过审查并明确发布，而不是从宽泛的预发布范围中推断。