dsh-profile-port

English | 中文

DeepSeek Harness（dsh）profile 的导出/导入工具：把一个 profile 打包成自包含目录，在另一台机器（或另一个 DSH_HOME）一条命令复刻。

三个零依赖 Node 脚本（Node ≥ 20，建议 24），不需要构建：导出（含 lock 冻结）、导入（含校验与验证）、diff。

为什么需要它

dsh 的 profile 是声明式的（package.json + cordis.patch.yml），理论上可复制，但直接拷贝目录有三个坑，每一个都在真实使用中炸过：

1. github: 直链依赖每次 install 都静默拉上游 HEAD——上游改包名、删构建产物、发布不兼容变更，你的 profile 下次 dsh plugin add 时突然起不来；
2. file: 引用是本机绝对路径，换台机器全部失效；
3. git 依赖可能缺 lib/ 构建产物（git 安装只拉源码不跑构建），装载即 ERR_MODULE_NOT_FOUND。

profile-export 把所有 file/git 依赖从当前已安装的 node_modules 打成 tgz（即通过验证的当前状态快照），改写为导出包内的相对路径，并生成 profile.lock.json 冻结工具链版本、每个依赖的解析版本与 tgz/配置文件的 sha256；profile-import 还原、校验 lock、安装，并逐 bundle 检查 + dsh --dump-config 验证插件树能组合；profile-diff 对比两个 profile 的依赖 / bundle / patch 差异。

用法

# 导出（默认输出到 ~/.dsh/exports/<profile>-<时间戳>/，同时生成 profile.lock.json）
node bin/profile-export.mjs <profile> [输出目录]

# 导入（目标机器需已装 dsh；拒绝覆盖已有同名 profile）
node bin/profile-import.mjs <导出目录> [新 profile 名] [--no-install] [--no-verify] [--no-lock-check]

# 只验证不安装：对已存在的 profile 跑 lock 校验 + 逐 bundle 检查 + dump-config
node bin/profile-import.mjs --verify-only <profile> [--no-lock-check]

# 对比两个 profile（profile 名或导出包目录均可）；无差异退出码 0，有差异 1
node bin/profile-diff.mjs <A> <B>

--no-install 只还原文件不装依赖（迁移中途检查、离线暂存时用）；--no-verify 跳过导入后的 bundle 检查与 --dump-config 验证；--no-lock-check 跳过 tgz/配置文件的 sha256 校验（默认开启，哈希不符直接中止、不留半截 profile；旧版无 lock 的导出包提示但不阻断）。

profile.lock.json 记录：dsh / node / pnpm 版本；每个依赖的原始 spec、解析出的实际版本、file/git 快照 tgz 的 sha256（registry 依赖若 pnpm-lock.yaml 里有 integrity 也带上）；cordis.yml / cordis.patch.yml / pnpm-workspace.yaml 的 sha256。

profile-diff 输出三类差异：依赖（新增/移除/规格或解析版本变化，解析版本依次取 lock → manifest → node_modules）、bundle 列表（package.json 的 dsh.profile.bundles）、cordis.patch.yml 行级差异（只出现在某一侧的行）。

测试

npm test   # node --test，零依赖，覆盖规格分类/导出改写/往返/拒绝覆盖/lock 生成与校验/diff/verify

导出包结构：

<profile>-<时间戳>/
├── package.json        # file/git 依赖已改写为 ./pkgs 相对路径
├── cordis.yml / cordis.patch.yml / pnpm-workspace.yaml
├── pkgs/               # 固定下来的 tgz 快照
├── manifest.json       # 导出时间、registry 依赖的实际安装版本
├── profile.lock.json   # 工具链版本、依赖解析版本、tgz/配置文件 sha256
└── README.md           # 导入说明

已验证

• 同机导出→导入→--dump-config 组合通过；
• 干净 DSH_HOME 导入（模拟新机器）→ pnpm install 全量安装通过；
• 真实启动 web profile 并访问：HTTP 200 正常返回页面。

边界

• registry 依赖（npm 上的包）导入时仍需联网；版本稳定但不做离线固定（manifest/lock 里有记录解析版本）。如需全离线，可以把 registry 包也打成 tgz，欢迎 PR。
• settings.yaml（API key、provider 配置）不属于 profile，迁移机器时需另行配置。
• 导入会执行 pnpm install（经 dsh plugin 转发），依赖 npm registry 可达性。
• lock 校验只覆盖 tgz 快照与配置文件的内容哈希，不做签名校验——它防的是「静默漂移/篡改」，不是恶意供应链攻击。
• diff 的 cordis.patch.yml 对比是行级集合差（只出现在某一侧的行），不是带位置的最小编辑序列。

与上游的关系

这被认为是 dsh 本体「profile export/import」能力的社区原型（见 dsh-TUI#115 的讨论）。官方 harness 仓库目前不接受外部 PR；若官方日后内置等价能力，本仓库即完成使命。

License

MIT

---

English

Export/import/diff tools for DeepSeek Harness (dsh) profiles: pack a profile into a self-contained directory and replicate it on another machine (or another DSH_HOME) with one command.

Three zero-dependency Node scripts (Node ≥ 20, 24 recommended), no build step.

Why: copying a profile directory breaks in practice — github: deps silently re-pull upstream HEAD on every install (renames / missing build output / breaking changes land without warning), file: refs are machine-local absolute paths, and git-installed packages may lack built lib/. Export packs every file/git dependency from the currently installed node_modules into tarballs (a snapshot of the verified-working state) and rewrites specs to relative paths; it also emits profile.lock.json freezing the toolchain versions, resolved dependency versions, and sha256 of every tarball and config file. Import verifies the lock, restores, installs, and verifies per-bundle (package present + entry file exists) plus dsh --dump-config. Diff compares two profiles (names under DSH_HOME or export dirs) on dependencies (added/removed/spec or resolved-version changes), the dsh.profile.bundles list, and line-level cordis.patch.yml differences — exit code 0 when identical, 1 when different.

node bin/profile-export.mjs <profile> [outDir]
node bin/profile-import.mjs <exportDir> [newProfileName] [--no-install] [--no-verify] [--no-lock-check]
node bin/profile-import.mjs --verify-only <profile>   # lock + bundle + dump-config, no install
node bin/profile-diff.mjs <A> <B>                     # exit 0 = no diff, 1 = diff

Verified: same-machine round trip; clean-DSH_HOME import (simulating a fresh machine); real web-profile boot serving HTTP 200. Unit tests: npm test (node --test, zero dependencies).

--no-install restores files without installing (for inspection / offline staging); --no-verify skips the post-import bundle + --dump-config checks; --no-lock-check skips the sha256 verification of tarballs and config files (on by default — a hash mismatch aborts before anything is copied; legacy exports without a lock file warn but proceed).

Limits: registry deps still need network at import time; settings.yaml (API keys, providers) is not part of a profile and travels separately. The lock guards against silent drift/tampering via hashes — it is not a signature mechanism. The patch diff is a set-of-lines comparison, not a positional minimal edit script.

MIT