DeepSeek Harness 参考分析与工作区取舍

August 22, 2026 · View on GitHub

分析基线：DeepSeek Harness dsh-v0.1.1-rc.2，commit b150a551b8d465e31e418e1b2eaf5e79bbb7d28e（2026-08-21）。公开锁见 upstream/deepseek-harness.lock.json。

官方定位

官方产品页把 Harness 定义为让 Agent 理解环境、 使用工具并持续工作的运行层；模型、工具、Skills、Session、sandbox、storage、loop、 scheduling 与 UI 都可由插件替换和组合。

上游仓库进一步给出四个对插件开发最重要 的结构事实：

  1. Cordis 只负责插件挂载、依赖、服务、事件和可撤销 effect；没有应被外部插件修改的 特权核心。
  2. profile 是可启动组合，bundle 是分发配置层；配置按 bundle → profile patch → home patch → CLI overlay 的顺序叠加。
  3. Session 是追加式事件流。恢复、分叉、搜索、回放、Trajectory 和模型历史都从同一 事件源派生，因此“模型可见即必须可重建”。
  4. Standard、Code/PTC、Minimal 与 Creator 等运行模式共享同一能力组合思想；插件工具 必须给程序化调用方稳定 schema，不能要求 Code Mode 解析面向人的文案。

对本工作区的直接影响

1. 从 HTML 镜像改为 commit 锁定的源码文档

旧工作区从文档站 HTML 反解 Markdown，会损失表格、图和链接，也无法可靠证明文档与 源码版本一致。现在由 tools/harness_upstream.py 管理被忽略的第三方 checkout，公开 仓库只保留 commit、tag、版本和来源锁。

2. 把版本一致性放到每次插件任务之前

tools/check-harness-drift.py 同时检查上游 checkout 与 lock，以及每个本地 dsh-*/ manifest 写下的 @deepseek-ai/dsh-* preview 锚。即使 semver range 技术上允许新版， preview 的书面锚不同也会报告；这是一条迁移提醒，不是假装做过兼容性证明。

3. 不批量改所有插件依赖

分析时本地插件仍有锚定较早 preview 的情况，而上游已经到 0.1.1-rc.2。上游明确警告 developer preview 会有破坏性变化，所以正确迁移单位是“一个插件 + 同版本文档/.d.ts

  • 完整门禁 + tarball/真实加载验证”，不是一次全局替换版本字符串。

4. 技能从机器备忘改成可公开的版本化流程

dsh-docs-lookup 现在先核版本再路由；authoring、tool、bundle 和 workflow 技能引用上游 checkout 的新文档结构；dsh-local-verify 与 discovery 技能不再固化某台机器的 profile、 路径和私人插件清单。

5. 根仓库只发布控制层

各插件继续保留自己的仓库和发布节奏。第三方上游源码、旧派生文档、.ai 原始证据、 scratch、真实 Session、本机清单与任何凭据都被排除。公开核心仅包含原创技能、工具、 测试、工作流、上游锁和说明。

后续迁移顺序

对任意一个插件升级时：

  1. 读取 lock 与 drift 报告，确认目标 preview；
  2. 在该插件自己的分支升级依赖并重新安装；
  3. 以实际 .d.ts 修正编译面，以同版本 docs 修正语义面；
  4. 运行 tools/check-plugin.py，把缺失、跳过、失败和通过分开报告；
  5. pnpm pack，在隔离 profile 验证配置层、Host/Client 入口和真实加载；
  6. 只有证据通过后才发布或迁移下一个插件。