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&reactpeer 检查、三态兼容判定)+ 六维冲突过滤,自动标注本机已装插件。 - 第 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*。
7. 许可与商业授权(个人 & 20 人内公司免费)
dsh-self 及其嵌入在打包桌面客户端内的原创桌面壳运行时与内置适配器,采用 PolyForm Noncommercial License 1.0.0 + 20 人以内公司内部免费附加许可 + OctoLab 商业授权:
| 使用场景 | 费用 | 说明 |
|---|---|---|
| 个人自用 / 公益免费分享 / 学术与非营利机构 | 免费 | 适用 PolyForm Noncommercial License 1.0.0,分发须保留 LICENSE、COMMERCIAL-LICENSE.md 与 THIRD_PARTY_NOTICES.md。 |
| 公司 / 团队内部免费自用(总计 ≤ 20 人) | 免费,无需申请 | 公司及关联主体内总人数不超过 20 人且严格限于内部自用,不得对外售卖或向外部客户收费交付。 |
| 公司内部使用超过 20 人(> 20 人) | 需商业授权 | 超规模内部部署请联系 octoooo@octoooo.com。 |
| 打包独立客户端对外售卖 / 订阅 / 外包交付 / 白标 | 需商业授权 | 无论团队人数多少,只要对外售卖或收费交付打包客户端,须事先联系 octoooo@octoooo.com 签署商业授权;详见 COMMERCIAL-LICENSE.md。 |
第三方社区插件提醒:若你在打包客户端时引入第三方社区 DSH 插件(如 dsh-plugin-bidkit、dsh-design-studio 等),需另行遵守该社区插件原作者的许可协议。