dsh-self 使用与发布指南

面向 DeepSeek Harness(dsh@0.2.2-rc.5)用户、插件维护者与桌面客户端打包作者的完整实操手册。

1. 快速启动与隔离演示

环境要求:Node.js >= 24.9(基线 26.12.1)、pnpm 11.28.5、以及官方 DeepSeek Harness 0.2.2-rc.5。

npm run build
node scripts/launch-official-dsh-demo.mjs

演示脚本会自动将自包含的 dsh-self-studio 安装到 .dev/official-dsh-demo/dsh-home 隔离 profile,并在 http://127.0.0.1:14567 启动官方 dsh web,不会修改你日常使用的 ~/.dsh 目录。

2. Studio 6 步工作台说明

  • 第 1 步 · 写需求:支持一键用 dsh 默认模型扩写需求(离线自动补全)、上传参考图(区分「参考配色与布局」与「放进工作区编辑」)、SSRF 防护读取参考网址,或直接导入既有 product.json 开启二次迭代。
  • 第 2 步 · 选方案:基于闭集组件目录生成极简 / 标准 / 专业三套方案,实时对比浅色/深色 1:1 窗口。
  • 第 3 步 · 选插件:四步静态准入(dsh.bundle.patch 与禁 !!js、平台/Node/--ignore-scripts 原生门禁、cordis & react peer 检查、三态兼容判定)+ 六维冲突过滤,自动标注本机已装插件。
  • 第 4 步 · 改外观:支持 4 种布局骨架(single-column / list-detail / three-pane / dashboard-grid)、自定义图标、8 项亮暗语义种子色与首页模块增删排序。
  • 第 5 步 · 试用微调:独立子进程启动 1:1 隔离预览,支持桌面/窄屏切换、右侧自然语言微调与历史修订回退。
  • 第 6 步 · 生成安装包:多选 Windows / Linux / macOS 目标平台;本机直打 Windows NSIS .exe,跨平台生成便携迁移包、GitHub Actions 工作流或 Docker/远程脚本,所有发布记录自动持久化。

3. DSH 插件发布准备(10 项门禁)

由于主仓库采用 monorepo,packages/dsh-self-studio 开发态包含 workspace:*。发布前务必使用统一发布脚本产出独立自包含包并过 10 项门禁:

# 1. 打包并运行 10 项 DSH 插件发布校验
node scripts/prepare-plugin-release.mjs --pack

# 2. 本机安装 .tgz 冒烟验证
dsh plugin --profile web add .dev/plugin-release/dsh-self-studio-0.1.0.tgz

# 3. 发布到 npm(仅从校验通过的独立目录发布)
npm publish .dev/plugin-release/dsh-self-studio --access public

# 4. 同步到独立公开 Git 分发仓库(供 github: 安装、dsh.pub 与 dsh.so)
node scripts/prepare-plugin-release.mjs --sync-dist ../dsh-self-studio

同时,本站已在 https://dsh-self.octoooo.com/dsh/index.json 托管符合官方 format: 1 规范的自定义插件索引(含 dsh/icons/dsh-self-studio.svg),公开发布至 npm 后即可直接被官方 DSH「发现」标签页拉取安装。

4. CLI 独立打包器

tools/builder 作为独立信任根,可在无界面或 CI 环境下一次性快照 product.json 与平台锁文件,执行三步预打包流水线:

npm run build
npm run assemble:base-shell

node tools/builder/dist/cli.js \
  --product fixtures/qinghe-bids/product.json \
  --lock fixtures/qinghe-bids/locks/plugins.win32-x64.lock.json \
  --target win32-x64 \
  --base-shell .dev/base-shell/win32-x64 \
  --out .dev/out/qinghe-bids

真实 5 包 Windows E2E 验收(并存、同名消歧、改名升级、双槽切槽、防降级拦截与单边卸载)可运行 node scripts/verify-win-e2e.mjs。

5. product.json 核心契约

跨平台唯一产品源定义采用严格 Zod Schema(拒绝任意布局树、脚本表达式或原始 HTML/CSS),明确区分创建时冻结的 identity与随修订可变的 brand / theme / home:

字段 可变性 约束与作用
identity.* 创建后不可变 productId、internalSlug(<= 21 字符)、appId、appUserModelId、nsisGuid、executableName、userDataDirName;用于隔离注册表、安装目录与用户数据。
brand 随修订可变 中英文 displayName(<= 64 字符、去控制字符)、iconSha256、图标预设或上传图片;改名升级自动清理旧 .lnk。
theme.seeds 随修订可变 亮/暗各 8 项 #RRGGBB 语义种子色,纯函数统一派生 110+ --dsw-* 变量与 Electron 原生窗口底色,并钳制 WCAG 4.5:1 对比度。
home & requiredActions 随修订可变 仅限闭集 4 种骨架、9 种组件与 13 种标准动作(panel-open / host-service / seeded-session)。

6. 隐私默认值、双槽自愈与脱敏诊断

  • 零默认外发:种子层 cordis.patch.yml 关闭 session-log-deepseek 与 plugin-package-inventory-deepseek,启动环境强制 DSH_TELEMETRY_DISABLED=1。
  • 最小环境白名单:Host 与构建子进程剥离 NODE_OPTIONS 与外部模型 API Key,仅保留 OS 基础变量、企业代理及 SSL_CERT_FILE / NODE_EXTRA_CA_CERTS。
  • 双槽自愈:安装更新以 seedHash 切换 <userData>/h/profiles/p-<hash>,保留上一健康槽并在连续 2 次冷启失败时自动回退。
  • 脱敏诊断包:导出前校验非符号链接,自动脱敏密钥、Bearer、JWT、PEM 私钥与本地路径,物理排除 .credentials.yaml 与 .env*。