Skip to content

Latest commit

 

History

History
127 lines (94 loc) · 9.21 KB

plugin-development-workflow.md

File metadata and controls

127 lines (94 loc) · 9.21 KB

插件开发工作流

环境与仓库边界

本仓库独立构建和发布,被 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:check

install 可能运行 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 残留不是功能仍存在的证明。

日常验证 gate

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:all

lint 使用 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维护。改变配色或规则后重新计算并更新两语言基线。

DSH 兼容提升

  1. 记录候选精确版本、对应 vendor、当前安装树和未提交修改,先审查公开 seams。
  2. 用 registry 依赖建立统一候选树,核对实际解析直接和间接 DSH 包;caret peers 漂移必须修正,不能通过跳过检查来掩盖混装。
  3. 新旧差异只放 compat/,保持同步返回、this、effect 所有权与公开入口。可移植主入口不得增加 Node 探测。
  4. 对候选运行相关 type/test/build/pack 与真实组合路径;候选不在声明前可在隔离副本审查与验证,不提前扩大正式支持。
  5. 正式提升时同步唯一清单、peers、最新 dev pin、overrides、age exceptions、lockfile、README、CHANGELOG,并让 compat:check 驱动一致性。
  6. 在全部既有版本的孤立树重跑矩阵;旧版失败必须处理或明确调整支持承诺,不悄悄跳过。
  7. 当前 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 定义当实际执行。

本地 profile 检查

构建后使用受支持 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 发布成功。