Dsh-dev

August 22, 2026 · View on GitHub

这是 DeepSeek Harness 外部插件的共享 开发控制层。这里维护 Agent Skills、上游版本锁、发现/校验/诊断工具；真正的插件放在 dsh-*/ 独立 Git 仓库中，本根仓库不吞并它们的历史，也不修改 dsh 内核。

官方产品页：https://www.deepseek.com/harness/。上游源码由 upstream/deepseek-harness.lock.json 固定，默认 checkout 在 vendor/deepseek-harness/，不会进入本仓库历史。

开始工作前

python3 tools/harness_upstream.py status
python3 tools/check-harness-drift.py

锁定版本是已经审阅过的参考面，不等于要求所有插件立刻升级。DeepSeek Harness 处于 developer preview；如果插件的 @deepseek-ai/dsh-* 依赖锚与锁不同：

  1. 先明确这次改动针对哪个版本；
  2. 语义读那个版本的文档，签名读插件实际安装的 .d.ts；
  3. 不要用新文档猜旧 API，也不要只因为 semver range 能覆盖就宣称兼容；
  4. 升级时一次迁移一个插件，跑完它自己的门禁和发布产物验证再继续。

目录地图

Dsh-dev/
├── README.md / README.en.md       公开项目说明
├── CLAUDE.md                      本文件
├── .claude/skills/                项目级 dsh 开发技能
├── tools/harness_upstream.py      克隆、刷新和核验上游 checkout
├── tools/check-harness-drift.py   上游锁与插件依赖漂移报告
├── tools/check-plugin.py          跑插件声明的门禁并报告缺口
├── tools/find-dsh-plugins.py      查 npm / GitHub 上现有插件
├── tools/session-log-repair/      默认只读的会话日志诊断与修复工具
├── upstream/                      可审计的上游锁
├── vendor/deepseek-harness/       上游源码（第三方、忽略）
└── dsh-*/                         独立插件仓库（忽略）

旧的 vendor/dsh-docs/ 是 HTML 反解镜像，只作历史参考。新工作一律优先读上游 checkout 里的原始中英文 Markdown；tools/sync-dsh-docs.py 仅作为旧命令兼容入口。

架构铁律

  1. 一切皆插件。 不改、不 fork dsh 内核；新能力挂到文档化的 Cordis 服务、事件 或配置 seam 上。
  2. 组合属于配置层。 profile/bundle/overlay 按顺序组成插件树；覆盖一行时按上游 patch 语义重述完整配置。
  3. 注册必须可撤销。 用 ctx.effect()、ctx.on() 和服务注册 disposer；有顺序 要求的释放在同一个 disposer 中串行完成。
  4. 模型可见即已记录。 新的模型可见事实必须能从追加式 Session event log 重建。
  5. 值与展示分离。 工具返回稳定、类型化的规范值；模型 render 和 UI presentation 是独立、可回放的投影。
  6. 配置不硬编码。 部署之间可能变化的值进入 Config schema，非法配置在加载时失败。
  7. 预览版兼容性要实证。 文档、源码、已安装 .d.ts 与真实测试必须指向同一版本。

常用命令

# 第一次取得被锁定的上游源码
python3 tools/harness_upstream.py sync --locked

# 主动分析新版上游并更新锁（会移动第三方 checkout 和锁文件）
python3 tools/harness_upstream.py sync --ref origin/master

# 查看本地插件有没有仍锚在别的 preview 版本
python3 tools/check-harness-drift.py
python3 tools/check-harness-drift.py --strict

# 写新插件前先查生态，改完后跑真实门禁
python3 tools/find-dsh-plugins.py --query <topic>
python3 tools/check-plugin.py dsh-my-plugin --conformance
python3 tools/check-plugin.py dsh-my-plugin

Skill 索引

Skill什么时候用
dsh-docs-lookup查上游规定、扩展点、签名、事件或配置；先核版本再路由到源码文档
dsh-plugin-discovery写新插件前查本地与公开生态，避免重复和不可信安装
dsh-plugin-authoring写插件本体：Config、生命周期、服务、事件、能力 seam
dsh-tool-authoring写模型工具：schema、执行契约、后台工作、策略钩子与展示
dsh-bundle-and-profilebundle/profile/patch、安装、客户端半和发布产物
dsh-plugin-workflow改完准备提交：门禁、反向测试、生成物和版本一致性
dsh-local-verify任何会碰真实 ~/.dsh、profile、会话或凭据边界的验证

公开边界

根仓库是 public。不要提交：

  • .ai/ 原始运行证据、scratch/、真实 Session 日志或聊天内容；
  • ~/.dsh 的凭据、settings、profile、用户数据或其副本；
  • .claude/skills/dsh-plugin-discovery/references/my-plugins.md 本机插件清单；
  • vendor/ 第三方 checkout/派生镜像；
  • dsh-*/ 插件仓库内容（它们各自发布）；
  • token、cookie、私有路径、真实用户名和未审查的命令输出。

需要记录本机事实时，从 my-plugins.example.md 复制出被忽略的 my-plugins.md。

代码与提交风格

  • 代码注释、公开 README 和 commit message 用英文；中文说明放在对应 .zh.md 或本文件。
  • conventional commits 描述行为变化和原因。
  • 包内相对 import 使用项目当前配置要求的显式扩展名；不要把上游仓库内部构建规则 原样强加给外部插件。
  • 默认分支上先建 feature branch；只暂存本次确认过的路径。