本仓库独立构建和发布,被 Desktop subtree 镜像但不依赖外层 repo。Node.js engines 为 ^22.19.0 || >=24,packageManager 为 pnpm@11.7.0。当前开发依赖 DSH 精确 pin、Cordis 和 Schemastery 版本以 package.json、workspace overrides 和 lockfile 为准;pnpm compat:check 验证真实解析树。
新 checkout 先读根 AGENTS.md、docs/README.md 和相关 reference/ADR,检查工作树。不得覆盖用户未提交的 manifest/lockfile,不从其他 DSH 插件复制 Electron、koffi、kernel sandbox、provider replacement 或运行时 Node probe。
corepack enable
pnpm install --frozen-lockfile
pnpm docs:check
pnpm compat:checkinstall 可能运行 prepare/build;pnpm 的生命周期许可、release-age 和 peer 自动解析会影响安装,按实际日志解决。不要用 --ignore-scripts 的成功来代替已经有可用 artifact;矩阵的 ignore-scripts 安装后明确运行 build。
| 工作 | 入口 | 必须同步 |
|---|---|---|
| 增加 builtin | presets.ts、ChromePalette | locale、NAME_KEYS、token/contrast 参考与测试 |
| 增加派生 token | deriveChrome | 角色、解析支持、全部明暗名称、上游消费者审查 |
| 改 state 行为 | runtime.ts | snapshot/store/UI 与 runtime/reference 用例 |
| 改 public catalog | types/catalog/index | declarations、consumer lifecycle、ADR/API 文档 |
| 改 settings | compat/settings-host/client | 新旧 provider、transport 重供/切换 |
| 改兼容支持 | dsh-version.ts 与声明 | 统一安装树、README、矩阵及 evidence |
| 改构建发布 | standalone config/scripts/workflows | package exports/files、release docs、实际 tarball |
| 改文档 | 所属 canonical 文档 | README 语言配对、入链出链、docs:check |
build:types 运行 host/client tsc,生成 lib/types/ 下声明与中间 JS。build 再从中间 JS 用 standalone tsdown 输出 Host ESM lib/index.js 与 browser loader lib/client.js。Client CJS wrapper 由宿主 ModuleLoader 管理,不能用 Node import 当普通 ESM。
CSS Module helper 使用 lightningcss,编译 class mapping 并注入幂等 style 标签。runtime overlay 清理与 stylesheet cache 是不同生命周期。production packages 保持 external,@deepseek-ai/dsh-client-store 必须由宿主 ModuleLoader 提供;实际列表看 build 输出。pnpm bundle 经 tsdown.config 可以通过 DSH_BUILD_FACE 选择 host/client;独立 build 生成两半。
build 的 clean=false,不删除旧声明。发布验证前仅清理可再生成的 lib 目录,不要删除源码或用户产物:
rm -rf lib
pnpm build
pnpm pack --dry-run如果 lib 包含手工文件,先保留再清理;仓库约定它是生成目录。旧 plugin-page/invariant declarations 残留不是功能仍存在的证明。
pnpm docs:check
pnpm compat:check
pnpm lint
pnpm typecheck
pnpm build
pnpm test
pnpm audit:tokens
pnpm verify:package
pnpm smoke
pnpm docs:check
# 完整本地 gate:
pnpm verify:alllint 使用 ESLint 检查 TS/TSX 和工程脚本;verify:all 串行执行兼容、lint、类型、构建、单测、token、tarball、官方运行时/profile smoke 和文档检查。真实浏览器需另外设置 DSH_BROWSER_E2E=1 并安装 Playwright Chromium;不设置时 smoke:client 的 not-run 不能视为通过。
矩阵的临时安装目录在启动 pnpm 前经 realpathSync.native 展开;Vitest 的 root 从配置文件目录经同一 native 解析确定,setupFiles 和 renderer shim 使用同一根目录下的绝对路径。Windows 上普通 realpathSync 保留 RUNNER~1 等 8.3 短名称,native 版本展开长名称;必须统一子进程 CWD、工具自身模块路径和 Vite 根目录。相关症状与远端证据见Windows 测试 setup 排查。
| 覆盖层 | 实际机制 | 边界 |
|---|---|---|
| 纯规则 | adapter/presets/contrast/catalog specs | 不渲染全量 host DOM |
| state | runtime.spec | 内存 settings 与 override surface 替身 |
| UI | ThemeStudioRow.spec,jsdom/Testing Library | 动作、aria/live status;非视觉截图 |
| 组装 | apply.client.spec,真实 Cordis | provider/consumer、slots/locale 替身、settings 重供 |
| Host | settings.spec、settings-provider.spec | legacy installed provider 用例仅在具 register 时运行 |
| 官方主题 | integration/theme-runtime.spec | 实际已安装发布 bundle,未使用 UI primitives 被 stub |
| compatibility | 静态 checker 与孤立安装 matrix | type/build/test/pack,不是每个平台完整 UI e2e |
2026-10-02 Stage 2/3 基线 81 tests passed,1 legacy provider skip(新 Config 安装)。source map ENOENT warning 来自上游发布包缺 map,不影响测试退出码;若测试实际失败仍需处理。不要固定未来测试数量作为通过规则。
pnpm contrast:report
pnpm contrast:report --strict
pnpm build:types
node scripts/report-contrast.mjs --json > contrast-report.json默认结果能计算时退出 0,strict 会对当前已知低值退出 1;不能把 strict 与 test 的成功门禁混淆。算法、支持语法与完整基线在contrast reference维护。改变配色或规则后重新计算并更新两语言基线。
- 记录候选精确版本、对应 vendor、当前安装树和未提交修改,先审查公开 seams。
- 用 registry 依赖建立统一候选树,核对实际解析直接和间接 DSH 包;caret peers 漂移必须修正,不能通过跳过检查来掩盖混装。
- 新旧差异只放 compat/,保持同步返回、this、effect 所有权与公开入口。可移植主入口不得增加 Node 探测。
- 对候选运行相关 type/test/build/pack 与真实组合路径;候选不在声明前可在隔离副本审查与验证,不提前扩大正式支持。
- 正式提升时同步唯一清单、peers、最新 dev pin、overrides、age exceptions、lockfile、README、CHANGELOG,并让 compat:check 驱动一致性。
- 在全部既有版本的孤立树重跑矩阵;旧版失败必须处理或明确调整支持承诺,不悄悄跳过。
- 当前 checkout 保持最新受支持开发基线,更新 matrix evidence 与范围。不得执行旧 workflow 的最老 pin 恢复步骤。
pnpm compat:matrix
node scripts/run-dsh-matrix.mjs 0.2.1-alpha.3 0.2.1-alpha.4 0.2.1-alpha.5 0.2.1-rc.1 0.2.1-rc.2
node scripts/run-dsh-matrix.mjs --candidate <exact-version>
node scripts/upgrade-dsh.mjs --print-latest-prerelease
node scripts/upgrade-dsh.mjs --print-installed脚本只接受清单版本,另加一个 --candidate 精确版本。每版复制源码到临时目录,按该版本已发布包的依赖声明重钉 DSH、Cordis、Schemastery 和配套运行时,非开发 pin 删除 lockfile 后重新安装;当前开发 pin 保留 manifest/workspace 与 lockfile,使用 frozen 安装。安装后用结构化 lockfile 检查混装;间接 DSH 漂移只追加一次 override 并重装,仍然混装则失败。然后执行 compat、lint、typecheck、build、test、docs check、token audit、真实 tarball 安装和 profile smoke。成功清理大安装树,命令 log 和 results.json 留存;失败保留树用于诊断。脚本不切换本地 pin。upgrade-dsh.mjs 会改当前 checkout 的 manifest,因此在 package.json、pnpm-workspace.yaml 或 pnpm-lock.yaml 已有未提交修改时拒绝执行。--admit-candidate 拒绝修改普通本地 Git checkout,只允许没有 .git 的独立副本或一次性 GitHub Actions checkout。本地候选统一使用 run-dsh-matrix.mjs --candidate。候选成功不会写入支持清单。DSH_BROWSER_E2E=1 PLAYWRIGHT_MODULE=<Playwright绝对入口> pnpm compat:matrix 会在每个隔离版本上额外执行 Chromium 交互、刷新与 Host 重启后的磁盘恢复,报告和截图保留在 evidence 目录。兼容文档保存已执行日期与平台,不把 CI 定义当实际执行。
构建后使用受支持 runtime 安装本地路径或实际 tarball,检查 dump-config 存在 bare carrier、Web Themes row 与官方 Appearance。选择主题、preview/cancel/apply,改变 Light/Dark/System,重启确认 durable 选择,禁用/重载确认 overlays/UI 清理和 catalog consumers 重启。
dsh plugin --profile web add .
dsh --profile web --dump-config
dsh --profile web这是维护者复现步骤,不声称本轮已经执行这一完整旅程。headless 不期望 browser row;Desktop/不同 OS 的实际呈现需另记证据。故障入口见排查目录。
提交前运行相关 gate、semantic review、git diff --check,说明何种实现/文档 changed、证据与未覆盖项。不要因 docs 改动重写未发布的业务需求。schema/动态 catalog 等新范围先评审,不借现有 discover service 顺便增加写方法。
发布使用release workflow,双语 CHANGELOG 描述版本用户变更,路线图维护 release state;不能只改 version 数字或把 commit 成功当 npm 发布成功。