dsh-plugin

DSH(DeepSeek Harness)插件维护主仓库(monorepo)。

仓库结构

dsh-plugin/
├── packages/         # DSH 插件包
├── DEVELOPMENT/      # 开发规约(AGENTS.md 拆分主题)
├── scripts/          # 发版/开发态链接/CI 聚合测试脚本、compat 与 echo-upstream 工位
├── tests/            # 仓库级测试(聚合器/compat 判定/dev-link/publish/echo-upstream 等)
├── .github/          # CI workflows(test/compat)
└── docs/             # 本地资料(除注明外不入库)

> npm 发行的包统一使用@mzzsfy/*格式

插件一览

安装与更新:缩短 pnpm 宽限期

pnpm 的 minimumReleaseAge 是新包发布后的安装宽限期(防供应链投毒)——刚发版的插件会因此装不上或装到旧版。建议永久改为 6 小时:

pnpm config set --global minimumReleaseAge 360

单位为分钟(6h = 6*60 = 360),写入全局 pnpm 配置,对所有项目生效。刚发版想立刻安装,可单次绕过:pnpm install --config.minimum-release-age=0。本仓库 node scripts/dev-link.mjs all 会把各已发布包线上最新版精确并集写入 profile 的 minimumReleaseAgeExclude(自家包装时不被拦;兜底参数 --allow-fresh 见 DEVELOPMENT/profile-link.md),故此建议只影响 profile 之外的场景。

开发与测试

要求 Node >= 22(各包 engines 字段;其中 dsh-settings-nav-icons 为 >=20)。各包 manifest 以 dsh.compatibility.dshReleases 逐版本声明 DSH 完整版本兼容性(实测过的版本记 compatible,未经实测验证的版本声明 unknown,以各包 manifest 为准)。

• 包内测试:18 个包全部含 test/ 目录,统一 npm test 入口(多数包为 node --test "test/*.test.mjs";cron-board/tunnel/turn-notify/usage-panel 四包经 --experimental-test-module-mocks --import ./test/_mocks.common-tools.mjs 预载公共依赖桩;shared-terminal 为自定义入口 node test/run.mjs,以各包 scripts.test 为准)
• CI 测试(.github/workflows/test.yml):push 按改动范围收敛(全部改动落在 packages// 只测 X + 冒烟与仓库根测试;触及非包路径回退全量),每 3 天定时与手动触发为全量;amd64/arm64 双架构并行,各跑 10 轮(smoke-load + 全部含 test/ 目录的包自动发现 + 仓库根 tests/ + 公共模拟器 scripts/echo-upstream 测试单元;测试文件按平台过滤,*.linux.test.mjs/*.win.test.mjs 专属,CI 只跑 linux 侧;宿主 peer 以钉版包装入仓库根 node_modules 作解析桥,包间依赖以 @mzzsfy 符号链接解析、不经 registry,均不入库)
• CI 兼容性测试(.github/workflows/compat.yml):每 3 天定时 + 手动触发,真实 dsh 宿主双槽窗口逐版本全家桶 boot(主测完全适配判定 + 基线不崩溃判定,均阻塞);不被 push 触发,方法见 docs/兼容性测试/测试与隔离方法.md(本地维护,不入库)

宿主兼容性

兼容性目标策略(2026-09-27 起):双槽窗口——主测 = 各渠道 dist-tag 指向版本中最新的 rc(渠道全无 rc 时取各渠道指向版本中语义化版本最大者;与基线同版本则窗口缩为单主测),完全适配(阻塞);基线 = dist-tag latest 指向版本,不崩溃底线(阻塞);三版本完全兼容不再执行(难度与收益不成比例)。窗口唯一规则实现为 node scripts/compat/window.mjs(实算随 dist-tag 滑动,本节版本号仅为写作日快照,与脚本输出不一致时以脚本为准):2026-10-26 实算 0.2.1-rc.3(主测)/ 0.2.1-rc.2(基线)。各包 manifest dsh.compatibility.dshReleases 为逐版本实测登记(存档非承诺,兼容面以窗口实测为准),dsh.hostMin 由 compat 装载层按包过滤(声明包:auto-trust-all/boss-simulator/llm-pi-gateway/shared-terminal/shell-select/tool-gate)。逐包测试进度见 docs/兼容性测试/逐包测试进度.md(仅该文件本地维护,不入库)。

以下为 2026-09-27 Round 30 实测记录(历史留档,当时窗口仍为三版本:0.1.2-rc.1 基线 / 0.1.5-rc.3 主测 / 0.1.7-rc.2 完全兼容目标;其中 dsh-shell-select 预设架构当时要求 ≥0.1.7-rc.1,对当时基线不可安装——该例外随窗口滑动已不再成立,hostMin 过滤现由装载层通用承载):

• 0.1.7-rc.2(完全兼容):宿主 SettingsForms 形态(settings 无 register/get)下,六包(context-manager/cron-board/session-manager/turn-notify/usage-dash/usage-panel)settings 读/写循环端到端可用——双形态适配:legacy 方法面(settings.register+update)与 0.1.7 静态 Config(volatile schema)+ configEditor.edit 写入并存,运行期以 register && update 双在检测分派。真机验收:六包 HTTP 写读闭环 + profile cordis.patch.yml 逐字段落盘 + Playwright UI 分区渲染(含 usage-dash 定价表格回读、turn-notify 深合并芯片态)。
• 0.1.5-rc.3 / 0.1.2-rc.1(不崩溃底线,实测通过):同套代码 legacy 分支回归,六包写读经宿主 settings.yaml 命名空间段,行为与适配前一致(双形态检测在旧宿主恒走原路径,零行为漂移)。
• 例外:dsh-shell-select 预设架构要求 ≥0.1.7-rc.1(@deepseek-ai/dsh-agent-preset 依赖),0.1.2-rc.1/0.1.5-rc.3 上不可安装(peerDependencies 已声明门槛;bundle patch 的 preset 行在旧宿主 import 失败会阻断 boot,隔离夹具以 --only 白名单排除该包);0.1.7-rc.2 全家桶全装。

开发态链接(dev-link)

node scripts/dev-link.mjs all          # 归一 profile 依赖行(^线上最新)+ 对账 dsh.profile.bundles + 挂工作副本 junction
node scripts/dev-link.mjs <包名>       # 单包模式
node scripts/dev-link.mjs all --unlink # 恢复纯 registry 版本
node scripts/dev-link.mjs all --allow-fresh # pnpm install 仍被 minimumReleaseAge 拦截时的兜底(仅限自家刚发的包)

• 开发态合法形态:已发布包依赖行 = ^线上最新,未发布包(线上 404)依赖行 = file:<仓库>/packages/<包>(dev-link 自动写入,出版本后重跑自动归一);工作副本挂载一律 = junction;公共依赖包无表层依赖行(残留行由 dev-link 删除),由消费插件 dependencies 声明随装 + dsh fallback 补链兜底
• dsh.profile.bundles 由 dev-link 对账(镜像官方 dsh plugin reconcilePlugins 语义):清单内插件包且依赖行已声明即入层,公共依赖包或无依赖行即出层;装载层变化不走热重载,重启 dsh 后生效
• link 时在 home 补丁层(~/.dsh/cordis.patch.yml)维护 hmr 覆盖行:仓库 packages 保存即热重载(host 半区约 1 秒,client 半区刷新页面),卸链时移除

dsh-usage-panel 的无 IO 纯逻辑层(src/parsers.mjs)由其 npm test 覆盖。包元数据:dsh-usage-panel peerDependencies 为 @deepseek-ai/dsh-settings(>=0.1.2-alpha.2)、@deepseek-ai/schemastery(>=3.18.0)与 react(^18.2.0);@mzzsfy/dsh-rs-workflow 为 @deepseek-ai/schemastery(^3.18.1)、@deepseek-ai/dsh-llm(>=0.1.2-rc.1)与 @deepseek-ai/dsh-tools(>=0.1.5-rc.2);@mzzsfy/dsh-maintain 为 @deepseek-ai/schemastery(>=3.18.4,volatile 引入线)与 react(^18.2.0),settings/configEditor 经服务注入使用不占 peer。peer 不落盘(profile pnpm autoInstallPeers: false),开发态由目录逐级兜底解析到 dsh 本体全局安装目录,CI 无 dsh 本体时以钉版包装入仓库根 node_modules 作解析桥。

发布

推荐走仓库级发版脚本(内置版本校验、测试、发布后回读验证与打 tag):

node scripts/publish.mjs dsh-usage-panel              # 发单个包
node scripts/publish.mjs all                          # 按序发全部
node scripts/publish.mjs <包名> --dry-run             # 只打印动作,不执行
node scripts/publish.mjs <包名> --bump patch          # 本地版本已发布时自动升 patch 再发

规则:

• 版本管控以 git tag 为事实源:每包独立 tag,形如 -v<版本>(如 @mzzsfy-dsh-usage-panel-v0.1.0);发布成功后脚本自动提交该包版本号变更并把 tag 打在该提交上,推送由维护者执行(git push --tags)
• 发版判定(本地版本==线上时)以 tag 后的包目录提交数为准:无提交 → 跳过(该包无需发版);有提交 → 拒绝发布并提示提交数,须显式 --bump 才发(防止代码已变而版本号未动被漏发);本地 tag 缺失 → 补打 tag 并跳过
• 本地版本低于线上时拒绝发布(防版本回退);高于线上时直接发布(--bump 仅适用于本地等于线上的场景)
• 各包 package.json 的 npmPublish 脚本是无校验的单包发布命令,仅在明确清楚后果时使用
• 发布要求本机已 npm login(2FA 账号按回车走浏览器认证,或使用 automation token)
• 单包发布只运行目标包的有效 npm test;缺少或为空的 test script 时拒绝发布。all 运行全仓聚合门后，只对有有效 test script 的包逐个运行测试;--skip-test 会跳过聚合门与目标包测试并警告未经测试发布,仅作显式豁免。

License

MIT,见 LICENSE。