Dsh Web Release

dsh-web 发布（release / publish）

本技能固化 dsh-web 全家桶的完整发版流程：全仓统一版本（四个卫星仓先发同版本）→ 提交 → 打 tag → 推送触发 GitHub Actions 发布管线（构建/测试/npm 发布/GitHub Release）→ 发布后验证。

授权与按需入口

• 先区分任务，不因加载本技能而执行发版。 发布管线/配置修复、版本核对、兼容性审计只读取相关章节并执行已授权的检查或修复；修复完成后交付证据，不自动 bump、合入 main、创建/推送 tag、npm publish、创建/修改 GitHub Release 或触发发布 dispatch。
• 只有用户当前明确要求实际发布时才进入完整流程；目标版本未指定时才适用下一 patch 默认。token、NPM_PUBLISH_ENABLED、已有 tag、历史发布许可和 CI 全绿均不是当前发布授权。
• 坏版本调查先只读核实影响。deprecate、删除/重推 tag、补发、回滚和修改已发布说明须在当前明确授权范围内；越界则报告所需决定，不自行补救历史未经授权发布。
• 根规则管安全与常规 dev 同步；本技能只补充获授权的发布集成与发布后版本提交回流。切分支/整合前遵循共享 checkout 保护，先核对基线、索引及其他会话占用；命令块是步骤示例，不是可整段无条件执行的脚本。
• 审计自动升级读第 0 节；实际发布依次完成版本选择、卫星仓对齐发版、兼容门禁、dev 集成、main 发版与第 5 节验证；失败时读取第 4 节恢复规则。只改文档无需构建、迁移矩阵或发布动作。

仓库事实（先读，决定每一步怎么做）

• 仓库：zhu1090093659/dsh-web（PUBLIC），本机路径 /Users/zcl/code/dsh-web。
• 本仓家族包由 scripts/lib/family-packages.mjs 得到，版本与包数量以 node scripts/verify-version.mjs X.Y.Z 的输出为准，不在技能中手抄固定数量；全部发布到 npm scope @linxin666，registry 固定 registry.npmjs.org。
• 卫星仓（4 个）：皮肤中心、宠物、社区插件索引与预设中心拥有独立仓库 dsh-skins / dsh-pet / dsh-community-plugins / dsh-presets，各自持有 CI、门禁与 tag 发布管线，本仓以已发布的 npm 包消费它们；清单与市场 pin 的归属见 family-satellite Note。
• 卫星仓版本策略（从下一版本起，见第 2 节）：卫星仓不再各自持有版本线；每次发版四个卫星仓与本仓发同一个 X.Y.Z，且卫星先发、本仓后发。已有版本不追溯，对齐只从下一个版本开始。
• 版本策略：全仓统一版本（tag vX.Y.Z = 每个家族包与根别名包的 version，由管线强制校验）。
• 未指定具体版本号时：不追问版本号；以远端最新且已发布的正式 vX.Y.Z tag 为上一版本， 默认目标为下一个补丁版本 X.Y.(Z+1)。用户明确给出版本号，或明确要求 major/minor/prerelease 变更时，按该要求执行；远端 tag 与 npm 已发布版本不一致时，按下方失败恢复规则处理，不自行猜测。
• npm 不允许重复发布同一版本号：已发布过的版本号（如 0.1.3/0.1.4/0.1.5）不可重发， 只能 bump 到下一个版本。
• 发布通道：npm 发布全部由 GitHub Actions 管线完成，使用仓库 secret NPM_TOKEN （npm automation token，@linxin666 scope）；本机 npm 登录态不固定（无登录态时 npm whoami 401 属正常；本机当前以 linxin666 登录），发版不依赖本机登录态。
• npm 通道已恢复（2026-08-31 起）：release.yml 的 workflow env NPM_PUBLISH_ENABLED: 'true'；发布管线执行完整门禁、版本校验后运行 pnpm -r publish --tag latest 与 legacy 双发（均以该开关门控），发布后立即用 scripts/verify-registry.mjs 断言每个家族包的 tag 版本都能从 registry 解析 （带重试预算，覆盖 npm 传播延迟）。开关曾因家族跟踪未上 npm 的 @deepseek-ai/* alpha cohort 而被暂停（决策记录 .agents/notes/archived/process/2026-08-28-pause-release-npm-publish-unstable-dsh-alpha.md， 恢复记录 .agents/notes/archived/process/2026-08-30-restore-npm-publish-alpha.2.md）。 若将来 cohort 再次无法从 registry 解析，把开关改回 'false'，tag 推送即退回 GitHub-Release-only（此时 mount smoke 的 auto 模式以 workspace 打包的 file: tarball 验证本 tag 构建）。
• 根 package.json 是 private（不发布）；pnpm -r publish 自动跳过。它的 version 与家族包同步 bump：git / link 安装仓库根别名 bundle 时，插件管理器显示的就是它。
• 分支模型：dev 是开发分支（集成分支），本地开发与远程 PR 统一以 dev 为目标（远端默认分支）；main 是稳定分支（发布分支），只接收 dev 上测试通过后合入的代码，发版 tag 一律从 main 打。dev / main 均已启用分支保护（要求 PR + CI 全绿；管理员可绕过，维护者直推 仍可用，功能改动仍须先经 dev）。
• 仓库禁 emoji（所有文件含提交信息与 tag 信息）；CI 会校验。

0. 发版前检查（本地全绿才允许打 tag）

0.1 自动升级兼容性审计（发布硬门禁）

在修改版本号、合并到 main、创建或推送 tag 之前，先按第 1 节确定 PREVIOUS_VERSION 与 TARGET_VERSION，再完成本审计；全新安装成功不能替代存量用户自动升级成功。

自动升级至少要覆盖两条真实路径：plugin-manager 的 check-updates → update 路径，以及 Doctor 启动 DSH 前的自动迁移路径；如果某种启动方式绕过迁移器，必须明确标为不支持，并在 release notes 写出恢复方式，不能默认为兼容。

以 PREVIOUS_TAG..HEAD 的实际 diff、目标 npm tarball 和当前 profile 格式为依据，逐项检查以下兼容面：

• 包身份与加载契约：npm name、exports、dsh.bundle / cordis.patch.yml、dsh.client、浏览器 loader id、聚合包 self row、旧包别名和迁移元数据。
• 用户 profile 与写入文件：$DSH_HOME/profiles/*/package.json、pnpm-lock.yaml、dsh.profile.bundles、cordis.patch.yml、disabled 覆盖行、bundle 顺序和官方 CLI 写入行为。
• 持久化与线协议：设置 section id、API path、请求头、localStorage / 配置 key、IPC / wire shape、schema 默认值、旧字段读取和新字段写入。已经持久化或上线路径中的标识符默认视为冻结，除非有可验证的映射。
• 宿主与 SDK 契约：@deepseek-ai/* 公共 API、服务注入、模块表、DSH 最低版本、Node 版本、CLI 参数、进程启动和退出语义。包声明的 dsh.engines.dsh 下限必须不高于发布验证所使用的 DSH 版本；CI 固定版本低于声明下限时阻断发布。plugin-manager 与 Doctor 的 DSH 兼容判定必须一致，或在支持矩阵中明确差异与限制。
• 自动迁移入口：分别验证 plugin-manager 的更新任务、Doctor 启动前迁移和直接 dsh web；直接入口若绕过 Doctor 迁移，必须补齐迁移或在 release notes 给出明确的不支持声明和人工恢复步骤。两条自动迁移路径的安装顺序、目标版本、回滚结果必须一致，不能只在一条路径修复。
• 跨平台生命周期：macOS、Linux、Windows 的路径、权限、临时文件、备份、服务启动方式和崩溃恢复；不要只用当前 macOS 环境的路径或进程假设。
• 生成与发布产物：共享源与同步副本、lib/、aggregate manifest、market / skin 产物、npm 包内文件白名单；不能只检查源码而漏掉实际 tarball。

对每个变化记录 旧标识 → 新标识、唯一迁移 owner、读取旧值和写入新值的顺序、备份位置、回滚动作、幂等条件和验证断言；没有变化的持久化标识符也要明确写为 frozen，不要凭猜测重命名。

将每个变更归类为：无需迁移的向后兼容、带确定性迁移的兼容变更、或必须阻断自动升级的不兼容变更。带迁移的变更必须满足：目标资源先可用、只有官方写入器修改 profile、旧数据在目标安装并通过启动 / dump-config 预检前不删除、迁移可重复执行、失败能恢复备份、失败后不会留下双挂载 / 重复 row / 半写配置。

当前 @linxin666/dsh-web-ui-all → @linxin666/dsh-web-all 过渡以 packages/dsh-plugin-manager/src/host/legacy-migration.ts 和对应 Agent Note 为迁移映射的事实源；只有在过渡窗口仍有效且目标包已从 registry 验证可读时才双发布旧名，窗口结束后停止旧包发布并执行 deprecate，不要无条件重复发布已占用版本，也不要手工改写当前包替代迁移测试。

0.2 自动升级验证矩阵

使用隔离的临时 DSH_HOME 和官方 CLI，禁止把当前用户 profile 或运行中的 DSH 服务当作测试夹具。至少验证：

• 全新安装：目标版本能安装、加载、渲染，所有 bundle row / client loader / 设置 section 正常。
• 上一正式版本 → 目标版本：保留真实旧 profile、配置、启停状态、bundle 顺序和已安装扩展，执行用户会触发的自动升级路径，重启或执行 --dump-config 后确认数据和功能仍在。
• 仍受支持的最旧版本以及每一个 legacy mapping：验证旧字段、旧包名、旧路径和旧锁文件都能到达目标状态；一次跨多个版本的升级不能只测逐级升级。
• 失败与重试：注入目标不可用、安装成功但验证失败、旧包移除失败、进程中断和重复执行，确认旧状态可恢复、不会出现新旧包同时挂载，第二次执行是安全 no-op。
• 真实用户入口：分别验证 plugin-manager 更新按钮、Doctor 启动前迁移和任何 direct CLI 启动入口；入口行为不一致时阻断发布或明确限制。
• 跨平台：凡涉及路径、权限、服务、spawn、临时文件或锁的变更，至少在 macOS / Linux / Windows 各验证一次；不能以单平台单元测试代替。

发布前至少执行以下门禁，并把针对本次迁移的测试文件和证据一并纳入提交：

pnpm sync-shared:check
pnpm typecheck
pnpm test
pnpm test:scripts
pnpm aggregate:check
pnpm runtime-deps:check

如果缺少旧 profile fixture、失败注入或跨平台验证，不能用“测试暂缺”放行 tag；先补测试 / 修复迁移，或把该版本明确降级为不支持自动升级并提供可执行的人工恢复步骤。

0.3 兼容性阻断条件

出现以下任一情况，立即停止版本 bump、tag 和 npm publish：持久化或线协议标识符发生变化但没有映射；迁移不是幂等事务或没有备份 / 回滚；目标包尚未验证可用就删除旧包；更新路径与启动路径的迁移语义不一致；升级后出现双挂载、重复 row、配置丢失或锁文件半写；只验证了 fresh install；或失败后只能依赖手工编辑 profile 才能恢复。

兼容性修复完成后必须同步更新行为测试、对应 Agent Note 和双语 release notes；不要通过改成 major 版本、跳过自动升级检查或先发布后观察来绕过阻断条件。

cd /Users/zcl/code/dsh-web
git checkout dev                   # 本地工作分支以 dev 为基线（远端默认分支）
git fetch origin && git rebase origin/dev   # 先同步上游最新 dev
git status --short                 # 明确本次要提交的内容，无意外文件
pnpm test                          # 全仓测试
pnpm test:scripts                  # 脚本测试（link-profile 等）
pnpm runtime-deps:check             # 发布包运行时依赖安全门禁
node scripts/aggregate.mjs --check # 聚合清单与磁盘一致（改过 aggregate.yml 时必须先重跑生成）
pnpm market:check                   # market/dist 与已提交产物一致
git log --oneline -5               # 确认包含本次全部改动、无未推送提交

发版前提：待发布的全部改动先合入 dev 并在 dev 上全绿；发版时把 dev 合入 main（见第 3 节），tag 从 main 打。

卫星仓（dsh-skins / dsh-pet / dsh-community-plugins / dsh-presets）的改动不经过本仓发布：它们在各自仓库评审、提交并打 tag，发布时与本仓同版本（见第 2 节），市场内容按 submodule gitlink 固定的提交拉取（见 docs/publish-prep.md）。

版本 bump 后必须重建产物并同步市场资产（版本信息影响 bundle 内容）：

pnpm build             # 全仓重建 lib 产物（含新版本号）
pnpm market:build      # 重新生成 market/dist（manifest.js/styles.js 内嵌产物内容）
pnpm market:check      # 必须通过；产物与市场资产要同一次构建一起提交

1. 版本 bump（全仓统一）

选择目标版本

1. 用户明确给出 X.Y.Z，或明确要求 major/minor/prerelease 变更时，以该要求为准，并确认目标版本未在 npm 发布过。
2. 用户没有指定具体版本号时，直接运行以下命令得出默认目标，不向用户追问：

PREVIOUS_TAG="$(
  git ls-remote --tags --refs --sort=-version:refname origin 'v*' \
    | awk '$2 ~ /^refs\/tags\/v[0-9]+\.[0-9]+\.[0-9]+$/ { sub("refs/tags/", "", $2); print $2; exit }'
)"
test -n "$PREVIOUS_TAG" || { echo "No previous release tag"; exit 1; }

PREVIOUS_VERSION="${PREVIOUS_TAG#v}"
test "$(npm view "@linxin666/dsh-web-all@$PREVIOUS_VERSION" version)" = "$PREVIOUS_VERSION" \
  || { echo "Remote tag and npm publication disagree"; exit 1; }

IFS=. read -r MAJOR MINOR PATCH <<EOF
$PREVIOUS_VERSION
EOF
TARGET_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
printf 'Previous release: %s; default target: %s\n' "$PREVIOUS_VERSION" "$TARGET_VERSION"

TARGET_VERSION 即后续命令中的 X.Y.Z。如果没有可确认的上一正式发布，或远端 tag 和 npm 记录不一致，不编造版本号；先按下方失败恢复规则处理。

find packages -name package.json -not -path '*/node_modules/*' \
  -exec sed -i '' 's/"version": "[0-9][^"]*"/"version": "X.Y.Z"/' {} +
sed -i '' 's/"version": "[0-9][^"]*"/"version": "X.Y.Z"/' package.json
sed -i '' 's|"@linxin666/dsh-web-all": ".*"|"@linxin666/dsh-web-all": "^X.Y.Z"|' package.json
find packages package.json -name package.json -not -path '*/node_modules/*' \
  -exec grep -H '"version"' {} \; | grep -v '"version": "X.Y.Z"'   # 必须无输出
grep -H '"@linxin666/dsh-web-all"' package.json   # 必须是 "^X.Y.Z"（根依赖基线随 tag 走）
pnpm install --lockfile-only --ignore-scripts     # 刷新锁文件里该依赖的 specifier

pnpm-lock.yaml 不记录家族包的 version，无需为它们改动；家族包依赖用 workspace:*，发布时由 pnpm 自动替换为实际版本，无需手工改依赖链。根别名是例外：它的聚合包依赖是基线随 tag 走的 caret 范围 （^X.Y.Z，见 root alias caret Note）， 基线搬动后锁文件的 specifier 要一起刷新。卫星包不是 workspace 包，它们的依赖范围与锁文件条目在第 2 节随对齐一起更新。

2. 卫星仓同版本发版（先于本仓）

从下一版本起，四个卫星仓与本仓发布同一个 X.Y.Z，且卫星先发、本仓后发：聚合包把卫星作为 npm 外部行依赖（范围手写在 packages/dsh-web-all/package.json），本仓 CI 的 pnpm install --frozen-lockfile 只能解析 registry 上已存在的版本。卫星此前的 0.3.25 版本线不追溯，对齐从 TARGET_VERSION 一次性完成。

每个卫星仓按自己的分支模型与门禁重复同一套步骤（其 release.yml 会拒绝 package.json 与 tag 不一致的发布）：

cd <卫星仓检出>
git checkout main && git pull origin main
# 1. 该仓 package.json 的 version 改成同一个 X.Y.Z，并重建该仓自己的产物
# 2. 双语 release notes 写入该仓 docs/release-notes/vX.Y.Z.md
# 3. 提交、推 main、打 tag 并推送，触发该仓 release.yml
git tag "vX.Y.Z" && git push origin main && git push origin "vX.Y.Z"
# 4. 断言 registry 已解析（各仓管线自带重试，这里只做最终复核）
npm view <该仓包名>@X.Y.Z version

四个卫星版本都能从 registry 解析之后，才回到本仓完成对齐，再进入第 3 节：

# packages/dsh-web-all/package.json：卫星依赖范围改成 ^X.Y.Z（外部行版本手写并随生成器保留）
# pnpm-workspace.yaml 的 minimumReleaseAgeExclude：卫星条目改成 @X.Y.Z
pnpm install                       # 刷新 pnpm-lock.yaml，锁文件解析已发布的卫星版本
node scripts/aggregate.mjs --check # 外部行依赖范围与清单一致
for d in satellites/dsh-skins satellites/dsh-pet satellites/dsh-community-plugins satellites/dsh-presets; do
  git -C "$d" fetch origin main
  git add "$d"                     # gitlink 移到该仓本次发布提交，市场内容与发行版本一致
done

失败处理：

• 任一卫星未上 registry → 不得推送本仓 tag；先把它发出去（该仓管线支持对同一 tag 重跑 dispatch 车道），已发布的版本号不可重发。
• 卫星已发、本仓未发 → 本仓仍停在上一版本；下次发布整体 bump 到新版本时把四个卫星一起抬上去，不要只对齐一部分。
• 决定不再对齐 → 显式改回「各自版本线」并同步本技能与 owning note，不允许半对齐状态长期存在。