DEEPSEEK HARNESS · PLUGIN OPERATIONS · 0.1.11

DSH 插件发布与收录:实测约束清单

这份文档记录的是可复现的实测结果,不是设计意图或文档转述。每一条都附了验证命令,谁都能在本机重跑。写它的原因是:DSH 插件从「写完」到「别人真的能装上」,中间有四段各管一段的时钟,任何一段没走完,作者看到的都是「明明发布了却没人装」。

结论先行:发布成功 ≠ 可安装 ≠ 可被发现,三者各有各的时间常数。

只记四条

>

1. 24 小时:minimumReleaseAge 冷却。浮动的装法只会解析到「最高成熟版本」,装到旧版不报错。 2. 约一小时:registry 元数据滞后。这段时间两条 CLI 路径都拿不到新版 —— 精确版本会 ERR_PNPM_NO_MATCHING_VERSION,裸名解析到冷却允许的旧版本。tarball 可能已经可取(302),元数据还没更新。 3. 每天一次:目录重建(约 04:46Z)。市场卡片上的版本最多落后一天,但这不影响实际装到的版本。 4. 一次性:装法决定以后会不会自动更新。add <name> 写 ^,会更新;add <name>@<version> 写精确版本,此后再也不动。

0. 发布操作步骤

完整发布流程(版本号 → 发布 pin → 自举页烙印 → 构建校验 → publish → registry 验证 → 索引与站点收尾)见 RELEASE-RUNBOOK.md;本手册记录的是流程背后的实测约束,runbook 是可执行的操作顺序。

1. 发布到「别人真能装上」有四段时间常数

阶段谁负责实测节奏卡住时的表现
npm publish作者自己的动作约 2 分钟处理窗口后可见
minimumReleaseAge 冷却DSH 插件安装1440 分钟(24 小时)默认安装解析到旧版本,不报错
镜像同步registry.npmmirror.com 等国内镜像外部,分钟级到小时级解析到旧版本,或 ERR_PNPM_NO_MATCHING_VERSION
目录重建dsh-plugin-catalog每天一次,约 04:46Z 构建市场卡片上的版本落后最多一天

最容易误判的是第二行。 我们实测到:0.1.4 发布于 2026-11-09T14:42Z、0.1.5 发布于 15:05Z,当晚在健康 registry 上执行默认安装,解析结果仍是 0.1.3;把冷却改成 0 后立刻变成 0.1.5。

# 默认:解析到 0.1.3(新版本太新,被冷却挡住)
node "$PNPM" add dsh-review-outbox --dir "$X"

# 关掉冷却:解析到 0.1.5
node "$PNPM" add dsh-review-outbox --dir "$Y" --config.minimum-release-age=0

这不是镜像故障,也不是目录问题——DSH 自己的代码注释里写明了这件事:

The installed bundle's manifest version, when declared; pnpm's minimumReleaseAge can make it older than the newest release.

冷却值记录在 pnpm 的 lockfile-verified.jsonl 策略里("minimumReleaseAge":1440)。同一份策略还带 tarballUrlBinding、resolutionShapeCheck,是供应链防护的一部分,默认按设计工作。

市场侧怎么看这件事,已做界面验证(2026-11-10,dshmarket@1.73.16,隔离 Profile 实测):卡片上写的是目录里的 v0.1.3,点「安装 → 确认安装」之后,profile 里落地的是 0.1.9,耗时 5 秒——也就是最新发布版,不受冷却限制。原因是市场按精确版本安装,而精确版本规格会绕过 minimumReleaseAge。

所以三条路径的实际行为要分开记:

路径拿到的版本
市场一键安装最新发布版(精确版本,绕过冷却)
dsh plugin add <name>(浮动范围)最高成熟版本(受冷却)
dsh plugin add <name>@<version>指定版本(绕过冷却)

dshmarket 的 lib/updates.js 里另有 latestMaturityAt / nextMaturityAt 一套判定,用于更新检查那条路径;那条路径没有实测,不要与安装混为一谈。

对作者的实际含义:

实测的目录构建时刻(连续六次):

2026-11-09T04:49:06Z  2026-11-08T04:46:05Z  2026-11-07T21:13:53Z
2026-11-07T04:59:33Z  2026-11-06T04:47:52Z  2026-11-05T04:41:31Z

把两条时钟合成一条发布规则

冷却按「发布时刻 + 24h」到期,目录按每天固定时刻重建。两者可以对齐:在目录日构建之前不久发布,第二天那次构建就正好落在冷却到期之后,卡片与安装版本一致,没有空窗。

以实测的 04:46Z 构建估算,发布窗口是北京时间 12:00–12:40 左右(即 04:00Z–04:40Z):

实测样本(0.1.7,2026-11-10 01:05 发布,非窗口内):发布约 4 分钟后 npm 与镜像的 latest 都是 0.1.7,但默认安装解析到的仍是 0.1.3 —— 因为 0.1.4 到 0.1.7 全部发布在 24 小时窗口内,最高成熟版本刚好停在 0.1.3;钉版本 @0.1.7 则立刻装到。也就是说:发布成功、镜像同步成功、冷却照样让人装到四个版本之前。

判断方法:

npm view dsh-plugin-catalog time --json --registry=https://registry.npmjs.org | tail -8
npm view dsh-plugin-catalog dist-tags --registry=https://registry.npmjs.org

把自己包的发布时间和最近一次目录构建时间对比:落在构建之后的,等下一版;落在 24 小时以内的,等冷却。

2. 安装走的是谁的 registry

DSH 的插件安装用的是应用内置的 pnpm,registry 来自用户的 npm 配置,不是写死的地址。在作者机器上,~/.npmrc 的 registry= 就是插件安装真正会请求的地址。

PNPM='/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs'
node "$PNPM" config get registry                       # 继承用户配置
node "$PNPM" config get registry --config.userconfig=/tmp/x/.npmrc   # 可被覆盖

这条约束解释的是「镜像故障时的失败形态」,而不是版本选择:

结论:版本落后先查冷却,装不动才查镜像。 顺序搞反会浪费一整晚。

3. 能不能自动更新,取决于装的时候写下的 spec

装完不是结束:profile 里记下的版本写法决定了它以后会不会自己动。三种写法,实测三条结果:

装的时候profile 里的 spec之后 pnpm update
dsh plugin add <name>^x.y.z会动:冷却过了就升到当时最高成熟版本
dsh plugin add <name>@<version>x.y.z(精确)永远不动:精确版本是上限,update 也不会越过
市场一键安装x.y.z(精确)不会随 pnpm update 动;要靠市场自己的更新动作改写 spec

复现(把冷却临时关掉等价于"等它成熟",不必真等一天):

cd "$DSH_HOME/profiles/web"
node "$PNPM" update dsh-review-outbox --config.minimum-release-age=0   # 精确 spec → 仍是旧版
# 改成 "dsh-review-outbox": "^0.1.3" 再跑一遍 → 升到当时最高成熟版本

作者最容易踩的坑:为了立刻验证新版本,用 @<version> 装了一次,于是这个 profile 从此不再自动更新,之后每发一版都"看不到效果"。这不是管线坏了,是那行 spec 被钉死了。

3b. 第五段时钟:解析到新版本 ≠ 运行中的进程加载了它

安装侧把版本解析成功(四段时钟走完)只是文件落盘。运行中的进程是否加载新代码,由 loader 决定:cordis-plugin-loader 的 Entry._init() 把 moduleNamespace 只捕获一次,Entry.update() 的 config 重载重建 fiber 时复用同一个命名空间(442 行的 HMR 注释在当前构建没有实现代码)。pnpm 原地升级只翻 symlink,没有 watcher 触发重载。

结论:升级生效需要重启 DSH。 重启后 import() 解析到新 symlink 目标,新代码自然进入。验证升级成功,看的是重启后的运行时,不是升级动作本身。

4. 三条安装回退路径(都实测过)

路径命令形态实测结果代价
应用内目录一键安装市场里点安装依赖镜像健康—
固定提交的 GitHub 源dsh plugin --profile web add 'github:OWNER/REPO#COMMIT'解析到 0.1.56 分 52 秒(走 git)
显式 npmjs registrypnpm add PKG@VER --registry=https://registry.npmjs.org解析到 0.1.5,9.4 秒需改配置

固定提交路径绕过 registry,是镜像故障期间唯一「不改用户配置」也能装到新版的路径。它的代价是慢,且要求包零运行时依赖、无安装脚本——否则依赖解析照样会撞上 registry。

5. 应用内索引的 pin 语义

应用内市场索引(format: 1)用「固定提交」表达版本,不是用分支头。我们用 market-release.json 显式持有被 pin 的提交:

这条语义直接决定了发布顺序:运行时提交 → 更新 pin → 重建索引 → 重建页面 → 校验 → 推送。

6. 验证只能在隔离 Profile 里做

桌面端 profile 由 Electron 应用独占管理,CLI 拒绝修改它。想验证安装、回填、审阅这类动作,必须另起 DSH_HOME:

H=$(mktemp -d /tmp/dsh-verify.XXXXXX)
DSH_HOME="$H" dsh plugin --profile web add PKG

好处是可以把真实状态拷进去跑:我们就是把日常 profile 里 75 条真实待审项复制到隔离环境,才验证出分组归档在生产数据上的行为(点 4 条那组 → {"archived":4} → pending 75→71、分组 10→9、零报错)。用自己的真实数据验证,和用造出来的 3 条假数据验证,发现的问题不是一个量级。

7. 消费兄弟插件的产物的正确接缝

上游插件如果把结果写成「冻结契约」(frozen contract),契约表面往往比实际可用的东西窄。以 dsh-research-report 为例,冻结的 AssembleReportResult 只暴露 reportDir、sealHash、verdicts,而实际拿到文件路径的稳定接缝是工具结果里的 tool/result.data.meta.reportFile。

判断哪个接缝是契约的、哪个是实现细节,问上游比猜便宜。我们把这个问题作为上游 issue提出,同时在自己的集成代码里按 reportFile 优先、reportDir 兜底的顺序处理,两边都不假设。

8. 把消费关系写成约定,而不是靠读对方代码

跨插件耦合写进文档才可能被讨论。我们把「第三方插件怎样把产物交给审阅方」写成七条可反驳的约定:REVIEWABLE-ARTIFACTS.md。它的价值不在措辞,而在于把隐性依赖变成可以被拒绝的提案——上游若不同意,可以直接说哪一条不成立。

9. 让验收单可以被脚本核对

验收单说"这些字节被审阅过,摘要如下"。人不该只有打开浏览器才能验证这一点:

node scripts/verify-receipt.mjs <receipt.html> <file>
#  匹配    → 退出码 0,打印 match <digest>
#  不一致  → 退出码 1,同时打印两个摘要并提示重新审阅当前字节
#  无法验证 → 退出码 2(例如在决定之前导出的验收单,本来就没有可核对的东西)
node scripts/verify-receipt.mjs <receipt.html> --print   # 只取摘要

退出码 0/1/2 是按测试工具的约定选的 —— 一个不能卡住 CI 的核对只是形式。

10. 度量:什么不算激活

用一条命令拿到这条度量,而不是靠感觉:

node scripts/report-usage.mjs ~/.dsh            # 人读
node scripts/report-usage.mjs --json ~/.dsh     # 可入库

它从状态文件里数出:成果总数、按状态与类型分布、人工动作次数(approve/return/archive/reopen,按动作与类型分开)、待审的中位与最久停留小时、积压最重的会话。输出里的最后一行会直说「没有任何人工决定」——待审深度不是采用。

插件生态里最容易自欺的三个数字:

我们采用的激活定义是「一次真实的人工审阅动作」:通过、退回或归档任意一条真实成果。到 0.1.5 为止,日常 profile 里这条计数是 0(75 条待审项,0 次人工动作)。这个 0 比任何发布里程碑都更能说明产品处在什么位置。

11. 一条命令看住发布状态

发布之后真正要盯的不是"有没有发成功",而是四个会各自漂移的数字:

node scripts/check-milestones.mjs            # 人读
node scripts/check-milestones.mjs --json     # 可入库

它一次打印:npm latest 与本地版本、目录条目版本与描述开头、默认安装解析到的版本(--with-install,会真的装一次)、本机漏斗(成果/待审/人工动作/最久停留)、以及上游 PR/issue 的状态与评论数。慢的步骤出声提示,避免"看起来卡住"。

按症状查的版本在排障页:ERR_PNPM_NO_MATCHING_VERSION、装到旧版、从此不更新、市场版本不一致、目录不收录、以及被连带拦住。

12. 发布后检查清单

八条,按顺序做,每条都有可观测的产出:

  1. pnpm run check 全绿(测试 + 索引重建 + 构建)。
  2. npm publish --registry=https://registry.npmjs.org,记下 shasum。
  3. 等 registry 处理窗口,npm view PKG version 确认 latest 已是新版。
  4. 触发镜像同步:curl -X PUT https://registry.npmmirror.com/-/package/PKG/syncs,确认返回 201。
  5. 用隔离 Profile 装一次,确认解析到的版本就是新版,而不是缓存里的旧版。
  6. 更新 pin → 重建索引与页面 → 确认线上 plugins.json 与首页的版本、提交一致。
  7. IndexNow 提交变更 URL,记录响应码(提交不等于收录,别当成流量)。
  8. 隔天核对目录条目版本,确认日构建已带上新版。

12b. 目录收录的实测 gate(2026-11-16 补)

awesome-dsh-plugin 的收录 PR 有两条会咬人的规则,都是从失败里读出来的:

这四条都来自 2026-11-15/16 的三轮收录实测(8 条拆成 3 PR、文件名打回一次、gate 信息挖错地方一次)。

13. 先用基线读数字,再谈采用

信号提案草案见 docs/SIGNAL-PROPOSAL.md:发布日形状的周数字应带「发布日」标记——可判定、成本低、不动排序,12-01 随月报正式开 issue。

看到任何插件(包括自己)的下载数,先对照 docs/ECOSYSTEM-BASELINE.md:目录里 58.6% 的条目停在每天 20–40 次的底部带,这一层与有没有人安装无关。周下载在低三位数时,它和「发布当天被镜像拉了一次」是同一个形状,不能作为采用证据。

node scripts/ecosystem-snapshot.mjs --package dsh-review-outbox   # 全量周分布,约 10 分钟
node scripts/ecosystem-snapshot.mjs --shapes 200 --seed 20261110  # 抽样 30 天形状

度量采用仍然只看两件能验的事:人工决策漏斗(scripts/report-usage.mjs)与验收单摘要可核对(scripts/verify-receipt.mjs)。

已知不确定项

写下来是为了以后不把它们当成结论:


本文的事实来源都在仓库里:发布记录见 docs/metrics/2026-11-09-release-0.1.5.json,收录与搜索分析见 docs/metrics/2026-11-09-market-listing.json,分发策略见 docs/DISTRIBUTION.md。

本文事实可在仓库中重跑验证:docs/OPERATIONS.md · Review Outbox 0.1.11