dsh-config-manager 0.1.0

package/README.md

@@ -0,0 +1,216 @@
+# DSH Config Manager
+
+**Backup · Export · Import · Migrate · Restore** — A configuration backup / export / import / migration manager for DSH.
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+One-click export of your main DSH configuration to a ZIP file, import it on another DSH, and restore your working environment as completely as possible.
+
+> ⚠️ **Security first: no Secret (API Key / Token / Password) is exported by default.** See [Security](#security).
+
+---
+
+## What it does
+
+DSH configuration is a hybrid model — one central `settings.yaml` plus multiple standalone files plus plugin-owned files (see `Docs/research/dsh-architecture.md`).
+This plugin does **not** copy `~/.dsh` wholesale. Instead it collects configuration by real config categories, packages them into a ZIP backup with a manifest and checksums, and runs a safe import flow on the target side:
+
+```
+Analyze → Preview → Snapshot → Apply → Validate → Rollback(if needed)
+```
+
+## Features
+
+- **Export**: Quick Export (one-click recommended config) and per-section custom export.
+- **Import**: ZIP validation → manifest read → integrity check → schema check → compatibility check → content scan → import-plan preview → user confirmation → automatic snapshot → apply → validate → result (automatic rollback on failure).
+- **Dry Run / Preview**: `analyzeImport()` + `createImportPlan()` are pure computation with zero writes — full preview before importing.
+- **Conflict handling**: global strategies `merge` (default) / `replace` / `skipExisting` plus per-item `Keep Current / Use Imported / Review`.
+- **Path mapping**: cross-device absolute-path detection and batch prefix mapping (workspace paths / MCP cwd / plugin config paths).
+- **Secret safety**: all sensitive fields are stripped by default; encrypted full backup (scrypt + AES-256-GCM) is an opt-in advanced feature.
+- **Automatic snapshot & rollback**: backs up the target state before import and restores it in reverse order on failure.
+- **Schema versioning & migration**: independent `schemaVersion`, migration logic centralized in `src/migrations/`.
+- **Idempotency**: re-importing the same ZIP creates no duplicates (keyed by Plugin ID / MCP serverName / Prompt name / Workspace id / Credential ref).
+- **Compatibility score**: Excellent / Good / Partial / Unsupported (rule-driven).
+- **Profiles**: save current config as a Profile / switch / duplicate / rename / export / import / delete; switching includes Preview + snapshot + rollback (`src/profiles/`).
+
+## Installation
+
+This plugin is a standard **DSH bundle plugin** (mirrors the dsh-ssh engineering pattern, research report §5.1): `package.json` declares
+`dsh.bundle.patch` (pointing to `cordis.patch.yml`, the CLI bundle hard criterion) and `dsh.client` (browser-half declaration);
+`npm run build` produces both halves (`lib/index.js` host half + `lib/client.js` browser half, the latter loaded into the Web GUI via
+`window.__ModuleLoader__.load(...)`).
+
+Two install options (choose one):
+
+```bash
+# ① Install from a local tgz / directory (recommended, after build)
+npm run build
+npm pack                       # produces dsh-config-manager-0.1.0.tgz
+dsh plugin --profile web add file:/absolute/path/to/dsh-config-manager-0.1.0.tgz
+
+# ② Install from a registry after publishing
+dsh plugin --profile web add dsh-config-manager
+```
+
+> **`--legacy-peer-deps` note**: some DSH core packages in peerDependencies (e.g.
+> `@deepseek-ai/dsh-plugin-marketplace`, `dsh-host-plugin-inventory`) are not published to the public npm registry
+> and only exist in a local DSH profile. If npm/pnpm fails while resolving peer dependencies, skip automatic peer installation:
+> - Direct npm install: `npm install --legacy-peer-deps`
+> - `dsh plugin add` (forwards to pnpm internally): `dsh plugin --profile web add <spec> --config.auto-install-peers=false`
+>
+> At runtime these packages are provided by the DSH profile itself (peerDependencies semantics); the plugin never reinstalls them.
+
+> **Local verification tip**: isolate testing with the `$DSH_HOME` environment variable — never touches `~/.dsh`:
+> ```bash
+> $env:DSH_HOME = "D:\tmp\dsh-home"        # Windows PowerShell
+> dsh plugin --profile test add file:<tgz> --config.auto-install-peers=false
+> dsh --profile test --dump-config | Select-String config-manager   # should show the mount line
+> ```
+
+## Export
+
+Two modes:
+
+- **Quick Export**: one-click export of the recommended sections (settings / ui / providers / plugins / mcp / prompts / skills / agentPresets / workspaces / credentialsStatus).
+- **Custom Export**: choose sections individually (`pluginFiles` and `sessions` are opt-in; `sessions` is off by default).
+
+Output: `dsh-config-<yyyy-MM-dd>.zip` containing `manifest.json` + per-section data + `integrity/checksums.json` (SHA-256).
+
+## Import
+
+```
+Select ZIP → Validate ZIP → Read Manifest → Check Integrity → Check Schema
+→ Check Compatibility → Scan Contents → Generate Import Plan → Show Preview
+→ User Confirms → Create Backup (Snapshot) → Import → Validate → Show Result
+```
+
+Import flow is enforced: **no writes happen before confirmation**; **a snapshot is always created before importing**; on failure `rollbackOnError` decides between full rollback or per-item honest reporting.
+
+## Security
+
+> **The default backup contains no Secret values.** This is a hard security invariant, enforced by the `Exporter`:
+
+- All structured section data passes a sensitive-field scan before being written to the ZIP (field-name blacklist: password / token / apiKey / secret / credential / authorization / cookie / privateKey / clientSecret etc., case-insensitive); matches are stripped.
+- `ctx.settings.describe({ redactSecrets: true })` is the first line of defense for DSH-known secrets; the sensitive-field scanner is the second line of defense for plugin-defined fields.
+- Credentials (`.credentials.yaml`) **never export values**, only state (`{ref, required, configured, hasValue:false}`); after import a "N credentials need attention" list is generated.
+- **Encrypted full backup (optional)**: when "Include secrets" is explicitly checked, a backup password is required; `node:crypto` (scrypt KDF + AES-256-GCM) is used, **the password is never written to the manifest**; `secrets.enc` is only written back via `ctx.credentials.set()` after decryption.
+- Without an encryption provider, `includeSecrets: true` is rejected (secrets are never leaked in plaintext).
+- Logging is fully redacted — Secret values never reach logs.
+- A ZIP is untrusted input: defends against Zip Slip / absolute paths / symlinks / zip bombs (entry count / compressed size / uncompressed size / compression-ratio limits) / malformed ZIPs / checksum mismatch — any trigger rejects the whole archive.
+
+## What is NOT exported
+
+By default **not** exported (spec §34.19/20):
+
+- API Key / Password / Token / Cookie / Session / auth credentials (values)
+- `~/.dsh/.anonymous-user-id` (device unique ID)
+- Conversation history (`sessions/`, off by default; v1 supports file-level copy only)
+- Logs / Cache / temp files
+- Browser localStorage UI state (no host-side channel; only `uiMigrationNotes` is exported)
+- Plugin binaries (never packaged — only the manifest is migrated, install goes through the official mechanism)
+
+## Secrets
+
+| Backup type | Import behavior |
+|---|---|
+| Normal backup (no secrets.enc) | All credentials → `MissingSecret`, filled in by the user after import |
+| Encrypted backup + correct password | Auto-decrypted and restored via `credentials.set()` (per-item confirmation in preview) |
+| Encrypted backup + no password | Same as normal backup: state-only, user fills in |
+
+## Compatibility
+
+| Status | Rule |
+|---|---|
+| Excellent | Same platform, no missing sections, supported schema |
+| Good | Backup from an older DSH (target is backward compatible) |
+| Partial | Cross-platform / missing sections / backup newer than target |
+| Unsupported | Schema beyond the supported range |
+
+## Backup format
+
+```
+dsh-config-2026-08-14.zip
+├── manifest.json                  # schemaVersion / exporter / source / sections / security
+├── config/settings.json           # non-UI settings namespaces (redacted + revision)
+├── config/ui.json                 # UI namespaces + uiMigrationNotes
+├── ai/providers.json              # llm-* providers/models (same section, not split)
+├── plugins/plugins.json + patch.json
+├── mcp/servers.json               # dsh-mcp-client entries extracted from the composed patch
+├── custom/prompts.json + skills/
+├── agents/presets/
+├── workspaces/workspaces.json
+├── plugin-files/                  # optional
+├── security/credentials.json      # credential state (never contains values)
+├── security/secrets.enc           # encrypted backups only
+└── integrity/checksums.json       # SHA-256
+```
+
+## Development
+
+```bash
+npm install --legacy-peer-deps   # peers include DSH core packages not on the public registry, see Installation
+npm run typecheck                # tsc --noEmit
+npm run build                    # tsc -p tsconfig.build.json (host half lib/) + tsdown (client bundle lib/client.js)
+npm run bundle                   # rebuild the client bundle only (tsdown)
+npm test                         # node --test "src/**/*.test.ts" "tests/**/*.test.ts"
+```
+
+Architecture: the core engine (`src/core`) depends only on the `ConfigAdapter` / `HostContext` interfaces (decoupled from the DSH runtime, testable with in-memory mocks); `src/adapters` implements each config category; `src/security` provides secret scanning / encryption / integrity / ZIP safety / redaction; `src/migrations` centralizes schema migration.
+
+## Testing
+
+Test framework: **node:test (Node built-in, zero dependency)**, following the choice made in the core module (no vitest). Tests live in `src/**/*.test.ts` and `tests/**/*.test.ts`.
+
+Coverage matrix (spec §33 + acceptance scenarios A–G):
+
+| Group | Coverage |
+|---|---|
+| Export | normal / empty / large (1MB+) / Unicode / special characters / secret filtering |
+| Import | normal / Merge / Replace / Skip (never deletes target-only items, §32) / Conflict / Missing plugin / Missing dependency / Missing secret / unconfirmed rejection |
+| Rollback (scenario E) | multi-adapter mid-flight failure → full restore (settings / file blobs / workspace / patch lines); `rollbackOnError=false` comparison; honest partial-rollback report |
+| Migration (scenario G) | `migrateToCurrent` mechanism-level: same version / too new / below minimum / no path / registry overlap / chained progression (**honest note: v1 is current, no real v2 exists for end-to-end verification**) |
+| Security (scenario F) | malformed ZIP / oversized entry count / checksum mismatch & missing / Zip Slip / absolute paths |
+| Cross-platform (scenario B) | win32→darwin / darwin→win32 / linux→win32 batch prefix mapping |
+| Redaction | log messages / meta / full pipeline never leaks secret values |
+| Schema | manifest structure validation / version predicate functions |
+
+Current test results: **186 tests, all passing** (`npm test`); `npm run typecheck` and `npm run build` both pass.
+
+## Known limitations
+
+1. **Workspace: create/rename title only**: DSH's workspace service has no "overwrite whole" write channel — import can create workspaces and update titles; paths and session lists are maintained by DSH itself from the real directory, cross-device paths are adapted via path mapping.
+2. **Some DSH core packages are not on the public npm registry** (e.g. `@deepseek-ai/dsh-plugin-marketplace`, `dsh-host-plugin-inventory`): features depending on their APIs only work in a local profile; installing this plugin requires skipping automatic peer installation (see the `--legacy-peer-deps` note in [Installation](#installation)).
+3. **No MCP management API** (research report §4.3): MCP is imported as composed patch lines and takes effect after restarting DSH; no add/remove/update API.
+4. **Plugin installation requires a restart**: `pluginMarketplace.installPlugin` only returns `needsRestart`; restarting depends on DSH Desktop.
+5. **Browser localStorage UI state is not migrated** (task board data, panel widths, etc.): no host channel.
+6. **keybindings / workflow configs / commands / rules files**: DSH currently has no such concepts; no sections are implemented (nothing invented).
+7. **Credential values cannot be rolled back**: DSH never reads credential values back; credentials overwritten during import can only be marked `manualHint` for manual re-entry on rollback.
+8. **Newly created items cannot be rollback-deleted**: DSH settings have no delete semantics; namespaces newly created by import can only be handled manually on rollback (honestly reported as partial).
+9. **Schema migration**: v1→v2 is a placeholder (current `CURRENT_SCHEMA_VERSION=1`); the mechanism is ready but no real v2 exists to verify.
+10. **History/session migration**: off by default; v1 supports file-level copy only.
+11. **Encrypted backups**: depend on a strong user-set password; a lost password makes `secrets.enc` undecryptable (by design).
+
+## Manual Test (shortest manual flow)
+
+> Prerequisites: two DSH instances (or two config directories on one machine); this plugin built and installed per [Installation](#installation).
+
+```
+DSH A
+→ open Config Manager → Export Configuration
+→ choose Quick Export → export dsh-config-<date>.zip (confirm in the report that Secrets are all excluded)
+→ copy the ZIP to DSH B
+
+DSH B
+→ open Config Manager → Import Configuration
+→ select the ZIP → wait for Analyzing... → review the Import Preview (sections/plugins/path mapping/credential re-entry list)
+→ if there are path issues → choose mapping directories (batch prefix mapping)
+→ resolve conflicts (Keep Current / Use Imported / Review)
+→ confirm Import → watch progress → review the result report
+→ fill in missing credentials (N credentials need attention)
+→ Verify: settings / plugins / MCP / Prompts / Skills / Workspaces are restored;
+    if the import failed midway → confirm it rolled back automatically and the original config still works
+```
+
+---
+
+**Product principles**: better to migrate one config less than to break a user's existing config. Every Import follows `Analyze → Preview → Backup → Modify → Validate → Rollback`; every Secret follows `never export by default / never log / never expose / never silently transfer`.

package/README.zh-CN.md

@@ -0,0 +1,218 @@
+# DSH Config Manager
+
+**Backup · Export · Import · Migrate · Restore** —— DSH 配置备份 / 导出 / 导入 / 迁移管理器。
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+在一台 DSH 中一键导出主要配置为 ZIP，在另一台 DSH 中导入并尽可能恢复原来的使用环境。
+
+> ⚠️ **安全第一：默认不导出任何 Secret（API Key / Token / 密码）。** 详见 [Security](#security)。
+
+---
+
+## What it does
+
+DSH 的配置是「一个集中 `settings.yaml` + 多个独立文件 + 插件自有文件」的混合模型（见 `Docs/research/dsh-architecture.md`）。
+本插件**不整包复制 `~/.dsh`**，而是按真实配置类别分区收集、打包为带清单（manifest）与校验和（checksums）的 ZIP 备份，并在导入端执行
+
+```
+Analyze → Preview → Snapshot → Apply → Validate → Rollback(if needed)
+```
+
+的安全导入流程。
+
+## Features
+
+- **Export**：Quick Export（推荐配置一键导出）与按分区选择导出。
+- **Import**：ZIP 校验 → manifest 读取 → 完整性校验 → schema 检查 → 兼容性检查 → 内容扫描 → 导入计划预览 → 用户确认 → 自动快照 → 执行 → 校验 → 结果（失败自动回滚）。
+- **Dry Run / Preview**：`analyzeImport()` + `createImportPlan()` 纯计算零写入，导入前完整预览。
+- **冲突处理**：`merge`（默认）/ `replace` / `skipExisting` 全局策略 + 逐项 `Keep Current / Use Imported / Review`。
+- **路径映射**：跨设备绝对路径检测与批量前缀映射（workspace 路径 / MCP cwd / 插件配置路径）。
+- **Secret 安全**：默认剥离所有敏感字段；加密完整备份（scrypt + AES-256-GCM）为可选高级功能。
+- **自动快照与回滚**：导入前备份将被修改的目标，失败时逆序补偿恢复。
+- **Schema 版本与迁移**：`schemaVersion` 独立演进，迁移逻辑集中在 `src/migrations/`。
+- **幂等**：同一 ZIP 重复导入不产生重复数据（按 Plugin ID / MCP serverName / Prompt name / Workspace id / Credential ref 识别）。
+- **兼容性评分**：Excellent / Good / Partial / Unsupported（规则驱动）。
+- **Profiles（配置 Profile）**：保存当前配置为 Profile / 切换 / 复制 / 重命名 / 导出 / 导入 / 删除；切换带 Preview + 快照 + 回滚（`src/profiles/`）。
+
+## Installation
+
+本插件是标准的 **DSH bundle 插件**（仿 dsh-ssh 工程范式，见研究报告 §5.1）：`package.json` 声明
+`dsh.bundle.patch`（指向 `cordis.patch.yml`，CLI 的 bundle 硬判据）与 `dsh.client`（浏览器半声明），
+`npm run build` 产出双半产物（`lib/index.js` Host 半 + `lib/client.js` 浏览器半，后者以
+`window.__ModuleLoader__.load(...)` 装载进 Web GUI）。
+
+两种安装方式（二选一）：
+
+```bash
+# ① 从本地 tgz / 目录安装（推荐，构建后）
+npm run build
+npm pack                       # 产出 dsh-config-manager-0.1.0.tgz
+dsh plugin --profile web add file:/absolute/path/to/dsh-config-manager-0.1.0.tgz
+
+# ② 发布后从 registry 安装
+dsh plugin --profile web add dsh-config-manager
+```
+
+> **`--legacy-peer-deps` 说明**：peerDependencies 中的部分 DSH 核心包（如
+> `@deepseek-ai/dsh-plugin-marketplace`、`dsh-host-plugin-inventory`）尚未发布到公共 npm registry，
+> 只在本地 DSH profile 环境存在。安装时若 npm/pnpm 尝试解析 peer 依赖并失败，请跳过 peer 自动安装：
+> - npm 直接安装：`npm install --legacy-peer-deps`
+> - `dsh plugin add`（内部转发 pnpm）：`dsh plugin --profile web add <spec> --config.auto-install-peers=false`
+>
+> 运行时这些包由 DSH profile 自身提供（peerDependencies 语义），插件不重复安装。
+
+> **本地验证提示**：可用 `$DSH_HOME=<临时目录>` 环境变量隔离测试，完全不触碰 `~/.dsh`：
+> ```bash
+> $env:DSH_HOME = "D:\tmp\dsh-home"        # Windows PowerShell
+> dsh plugin --profile test add file:<tgz> --config.auto-install-peers=false
+> dsh --profile test --dump-config | Select-String config-manager   # 应看到挂载行
+> ```
+
+## Export
+
+两种方式：
+
+- **Quick Export**：一键导出推荐分区（settings / ui / providers / plugins / mcp / prompts / skills / agentPresets / workspaces / credentialsStatus）。
+- **Custom Export**：按分区逐项选择（可选 `pluginFiles`、`sessions`；`sessions` 默认关闭）。
+
+导出产物：`dsh-config-<yyyy-MM-dd>.zip`，含 `manifest.json` + 各分区数据 + `integrity/checksums.json`（SHA-256）。
+
+## Import
+
+```
+Select ZIP → Validate ZIP → Read Manifest → Check Integrity → Check Schema
+→ Check Compatibility → Scan Contents → Generate Import Plan → Show Preview
+→ User Confirms → Create Backup (Snapshot) → Import → Validate → Show Result
+```
+
+导入流程强制：**未确认不执行任何写入**；**导入前必须生成快照**；失败按 `rollbackOnError` 决定整体回滚或单项如实记录。
+
+## Security
+
+> **默认备份不包含任何 Secret 值。** 这是硬性安全不变量，由 `Exporter` 强制：
+
+- 所有结构化分区数据在写入 ZIP 前经过敏感字段扫描（字段名黑名单：password / token / apiKey / secret / credential / authorization / cookie / privateKey / clientSecret 等，大小写不敏感），命中即剥离。
+- `ctx.settings.describe({ redactSecrets: true })` 作为第一道防线剥离 DSH 已知秘密；敏感字段扫描器作为第二道防线兜底插件自定义字段。
+- 凭据（`.credentials.yaml`）**永不导出值**，只导出状态（`{ref, required, configured, hasValue:false}`），导入后生成「N credentials need attention」补录清单。
+- **加密完整备份（可选）**：显式勾选「Include secrets」时，要求设置备份密码，使用 `node:crypto`（scrypt 派生 + AES-256-GCM 加密），**密码绝不写入 manifest**；`secrets.enc` 只有解密后经 `ctx.credentials.set()` 写回。
+- 无加密提供者时 `includeSecrets: true` 会被拒绝（绝不明文泄密）。
+- 日志系统全部经过 redaction，Secret 值永不进入日志。
+- ZIP 属于不可信输入：防御 Zip Slip / 绝对路径 / 符号链接 / zip bomb（条目数 / 压缩体积 / 解压体积 / 压缩比上限）/ 畸形 ZIP / checksum 不匹配，任何一条触发即整体拒绝。
+
+## What is NOT exported
+
+默认**不**导出（规范 §34.19/20）：
+
+- API Key / Password / Token / Cookie / Session / 认证凭据（值）
+- `~/.dsh/.anonymous-user-id`（设备唯一 ID）
+- 会话历史（`sessions/`，默认关闭；v1 仅支持文件级复制）
+- Logs / Cache / 临时文件
+- 浏览器 localStorage 中的 UI 状态（Host 侧无通道，仅导出 `uiMigrationNotes` 说明）
+- 插件二进制（绝不打包，只迁移清单并走官方安装机制）
+
+## Secrets
+
+| 备份类型 | 导入行为 |
+|---|---|
+| 普通备份（无 secrets.enc） | 全部凭据 → `MissingSecret`，导入后由用户补录 |
+| 加密备份 + 正确密码 | 自动解密并经 `credentials.set()` 恢复（预览时可逐条确认） |
+| 加密备份 + 不输密码 | 同普通备份：状态补录 |
+
+## Compatibility
+
+| 状态 | 规则 |
+|---|---|
+| Excellent | 同平台、无分区缺失、schema 受支持 |
+| Good | 备份来自更旧 DSH（目标向后兼容） |
+| Partial | 跨平台 / 分区缺失 / 备份比目标新 |
+| Unsupported | schema 超出支持范围 |
+
+## Backup format
+
+```
+dsh-config-2026-08-14.zip
+├── manifest.json                  # schemaVersion / exporter / source / sections / security
+├── config/settings.json           # 非 UI settings namespace（redacted + revision）
+├── config/ui.json                 # UI namespace + uiMigrationNotes
+├── ai/providers.json              # llm-* providers/models（同 section 不拆分）
+├── plugins/plugins.json + patch.json
+├── mcp/servers.json               # 组合 patch 提取的 dsh-mcp-client 条目
+├── custom/prompts.json + skills/
+├── agents/presets/
+├── workspaces/workspaces.json
+├── plugin-files/                  # 可选
+├── security/credentials.json      # 凭据状态（永不含值）
+├── security/secrets.enc           # 仅加密备份
+└── integrity/checksums.json       # SHA-256
+```
+
+## Development
+
+```bash
+npm install --legacy-peer-deps   # peer 含未发布公共 registry 的 DSH 核心包，见 Installation
+npm run typecheck                # tsc --noEmit
+npm run build                    # tsc -p tsconfig.build.json（Host 半 lib/）+ tsdown（client bundle lib/client.js）
+npm run bundle                   # 仅重新构建 client bundle（tsdown）
+npm test                         # node --test "src/**/*.test.ts" "tests/**/*.test.ts"
+```
+
+架构：核心引擎（`src/core`）只依赖 `ConfigAdapter` / `HostContext` 接口（与 DSH 运行时解耦，可用内存 mock 测试）；`src/adapters` 实现各配置类别；`src/security` 提供秘密扫描 / 加密 / 完整性 / ZIP 安全 / redaction；`src/migrations` 集中 schema 迁移。
+
+## Testing
+
+测试框架为 **node:test（Node 内置，零依赖）**，沿用核心模块的既有选择（不引入 vitest）。测试位于 `src/**/*.test.ts` 与 `tests/**/*.test.ts`。
+
+覆盖矩阵（规范 §33 + 验收场景 A-G）：
+
+| 组 | 覆盖 |
+|---|---|
+| Export | 正常 / 空配置 / 大配置(1MB+) / Unicode / 特殊字符 / Secret 过滤 |
+| Import | 正常 / Merge / Replace / Skip（不删目标独有 §32）/ Conflict / Missing plugin / Missing dependency / Missing secret / 未确认拒绝 |
+| Rollback（场景 E） | 多 adapter 混合中途失败 → 整体恢复（settings / 文件 blob / workspace / patch 行）；`rollbackOnError=false` 对照；部分回滚诚实报告 |
+| Migration（场景 G） | `migrateToCurrent` 机制级：同版本 / 过新 / 低于最低 / 无路径 / 注册重叠 / 链式推进（**如实说明：当前 v1 即最新，无真实 v2 可端到端验证**） |
+| Security（场景 F） | 畸形 ZIP / 超大条目数 / checksum 不匹配与缺失 / Zip Slip / 绝对路径 |
+| Cross-platform（场景 B） | win32→darwin / darwin→win32 / linux→win32 批量前缀映射 |
+| Redaction | 日志消息 / meta / 全链路不泄 Secret 值 |
+| Schema | manifest 结构校验 / 版本判定函数 |
+
+当前测试结果：**186 tests, all passing**（`npm test`），`npm run typecheck` 与 `npm run build` 均通过。
+
+## Known limitations
+
+1. **Workspace 只能建/改标题**：DSH 的 workspace 服务没有「整体覆盖」写通道——导入时可创建 workspace 与更新标题；path 与会话列表由 DSH 依真实目录自行维护，跨设备路径通过路径映射适配。
+2. **部分 DSH 核心包未发布公共 npm registry**（如 `@deepseek-ai/dsh-plugin-marketplace`、`dsh-host-plugin-inventory`）：依赖其 API 的功能只在本地 profile 环境可用；安装本插件需跳过 peer 自动安装（见 [Installation](#installation) 的 `--legacy-peer-deps` 说明）。
+3. **MCP 无管理 API**（研究报告 §4.3）：MCP 以组合 patch 行导入，需重启 DSH 生效；无增删改 API。
+4. **插件安装需重启**：`pluginMarketplace.installPlugin` 只返回 `needsRestart`，重启依赖 DSH Desktop。
+5. **浏览器 localStorage UI 状态不迁移**（任务看板数据、面板宽度等）：Host 无通道。
+6. **keybindings / workflows 配置 / commands / rules 文件**：DSH 当前无这些概念，不实现分区（不发明）。
+7. **凭据值无法回滚**：DSH 不回读凭据值，导入中覆盖的凭据在回滚时只能标记 `manualHint` 人工补录。
+8. **新建项无法删除回滚**：DSH settings 无删除语义，导入新建的 namespace 在回滚时只能人工处理（如实报告 partial）。
+9. **Schema 迁移**：v1→v2 为占位（当前 `CURRENT_SCHEMA_VERSION=1`），机制已就绪但无真实 v2 可验证。
+10. **历史会话迁移**：默认关闭，v1 仅文件级复制。
+11. **加密备份**：依赖用户设置强密码；密码丢失则 `secrets.enc` 无法解密（设计使然）。
+
+## Manual Test（最短人工测试流程）
+
+> 前提：两台 DSH（或同一台的两份配置目录）；本插件已按 [Installation](#installation) 打包并安装。
+
+```
+DSH A
+→ 打开 Config Manager → Export Configuration
+→ 选择 Quick Export → 导出 dsh-config-<date>.zip（确认报告中 Secret 均被排除）
+→ 将 ZIP 复制到 DSH B
+
+DSH B
+→ 打开 Config Manager → Import Configuration
+→ 选择 ZIP → 等待 Analyzing... → 查看 Import Preview（分区/插件/路径映射/凭据补录清单）
+→ 如有路径问题 → 选择映射目录（批量前缀映射）
+→ 解决冲突（Keep Current / Use Imported / Review）
+→ 确认 Import → 观察进度 → 查看结果报告
+→ 补充缺失凭据（N credentials need attention）
+→ Verify：确认 settings / 插件 / MCP / Prompts / Skills / Workspaces 已恢复；
+   若导入中途失败 → 确认已自动回滚、原配置可正常使用
+```
+
+---
+
+**产品原则**：宁可少迁移一个配置，也不要破坏用户现有配置。任何 Import 都遵循 `Analyze → Preview → Backup → Modify → Validate → Rollback`；任何 Secret 都遵循 `不默认导出 / 不记日志 / 不暴露 / 不静默转移`。

package/cordis.patch.yml

@@ -0,0 +1,45 @@
+# dsh-config-manager bundle patch: inserts the dual-face plugin row into the
+# web profile roster. Applied as a profile bundle layer (the `dsh.bundle.patch`
+# manifest field in package.json) over dsh-base; activate with
+#   dsh plugin --profile <name> add dsh-config-manager        # published
+#   dsh plugin --profile <name> add link:<abs-or-~-path>      # local dev
+# (the CLI forwards to pnpm inside the profile directory).
+#
+# CLI hard criterion (verified from `dsh plugin add` source): a package is
+# appended to the target profile's `dsh.profile.bundles` only when its
+# manifest carries `dsh.bundle.patch` (package.json does — it points at this
+# file); without that field the CLI treats the package as a plain dependency
+# and warns. So this file plus the package.json `dsh.bundle.patch` key are
+# what make dsh-config-manager a real bundle.
+#
+# Format mirrors @linxin666/dsh-ssh/cordis.patch.yml exactly (verified
+# against the installed dsh-ssh@0.1.12): a bare plugin row by package name —
+# the node half (exports ".") runs in the host process (backup/export/import
+# engine, /api/dsh-config-manager routes, agent tools), and the `dsh.client`
+# declaration in package.json makes the browser half (exports "./client")
+# load in the web GUI.
+#
+# Row id must match the Host plugin's `export const name` in src/index.ts
+# (dsh-ssh precedent: patch row id "ssh" == export const name "ssh").
+# ASSUMED here: "config-manager" — align when the Host half lands.
+#
+# Host services this plugin consumes — real DSH package names from the
+# architecture research report (Docs/research/dsh-architecture.md §1.4),
+# each listed as a peerDependency in package.json; plugin code declares them
+# via `inject` in src/index.ts:
+#   ctx.settings           -> @deepseek-ai/dsh-settings      (+ dsh-settings-file)
+#   ctx.credentials        -> @deepseek-ai/dsh-credentials   (+ dsh-credentials-local)
+#   ctx.llm                -> @deepseek-ai/dsh-llm
+#   ctx.pluginInventory    -> @deepseek-ai/dsh-host-plugin-inventory
+#   ctx.pluginMarketplace  -> @deepseek-ai/dsh-plugin-marketplace  (web profile)
+#   ctx.tools              -> @deepseek-ai/dsh-tools
+#   ctx.webServer          -> @deepseek-ai/dsh-host-webserver
+#   ctx.systemPrompt       -> @deepseek-ai/dsh-system-prompt
+#   ctx.agentPresets       -> @deepseek-ai/dsh-agent-presets
+# Settings namespaces read via ctx.settings.describe() — registered by these
+# provider plugins (report §2.2), not services:
+#   llm-deepseek (settings.yaml section) -> @deepseek-ai/dsh-llm-deepseek
+#   llm-pi-ai    (settings.yaml section) -> @deepseek-ai/dsh-llm-pi-ai
+- insert:
+    - id: config-manager
+      name: 'dsh-config-manager'

package/dsh.bundle.patch

@@ -0,0 +1,21 @@
+# dsh-config-manager bundle patch — standalone copy under the task-mandated
+# filename `dsh.bundle.patch`.
+#
+# NOTE on the real reference (@linxin666/dsh-ssh@0.1.12, verified): there is
+# NO file named `dsh.bundle.patch` in the wild. `dsh.bundle.patch` is the JSON
+# key inside package.json —
+#   "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+# — that points at the bundle patch FILE, which dsh-ssh names cordis.patch.yml.
+# This file is an equivalent duplicate for consumers expecting the name
+# `dsh.bundle.patch`. package.json currently points at ./cordis.patch.yml
+# (exactly like dsh-ssh). If you switch the pointer, update package.json:
+#   "dsh": { "bundle": { "patch": "./dsh.bundle.patch" } }
+# Reference only ONE of the two files at a time — the loader applies each
+# bundle's patch file once per bundle layer.
+#
+# Content is identical to ./cordis.patch.yml (same row, same id semantics:
+# row id must match the Host plugin's `export const name` in src/index.ts;
+# ASSUMED "config-manager" until the Host half lands).
+- insert:
+    - id: config-manager
+      name: 'dsh-config-manager'

package/dsh.client

@@ -0,0 +1,39 @@
+// dsh-config-manager — client-half manifest (task-mandated standalone file;
+// it mirrors the inline `dsh.client` block in package.json and adds the
+// entry/mount declarations for the parallel src/client implementation).
+//
+// NOTE on the real reference (@linxin666/dsh-ssh@0.1.12, verified): the
+// client half is declared inline in package.json as
+//   "dsh": { "client": { "inject": [...], "platform": "web" } }
+// and the browser bundle is served at /plugins/<id>/client.js through the
+// `./client` export. There is no standalone dsh.client file in the wild.
+// Keep this file and the package.json block in sync.
+{
+  // Services the client bundle needs injected (identical to dsh-ssh's block).
+  "inject": [
+    "@deepseek-ai/dsh-client-runtime",
+    "@deepseek-ai/dsh-client-connection",
+    "@deepseek-ai/dsh-client-ui-settings"
+  ],
+  "platform": "web",
+  "entry": {
+    // VERIFIED (p4, 2026-08): the actual build output matches the dsh-ssh
+    // shape — tsdown produces the single-file browser bundle lib/client.js
+    // (starting with `window.__ModuleLoader__.load({ id, factory(require) })`),
+    // served through the "./client" export in package.json:
+    //   "exports": { "./client": { "types": "./lib/client.d.ts",
+    //                               "default": "./lib/client.js" } }
+    // Source is the p1 client entry (src/client/index.ts): inject + apply
+    // registering the `settings.section` page (dsh-ssh src/client precedent).
+    "source": "src/client/index.ts",
+    "build": "lib/client.js"
+  },
+  "mount": {
+    // Official Slot contract (research report §1.5, design doc §11):
+    // settings.section registers a settings page. Design doc §11.4 picks it
+    // as the Config Manager main surface.
+    "slot": "settings.section",
+    "id": "config-manager",
+    "label": "Backup & Migration"
+  }
+}

package/lib/adapters/agent-presets.d.ts

@@ -0,0 +1,13 @@
+/**
+ * agentPresets 分区 adapter（设计 §3.3）：
+ * 数据源 = ~/.dsh/.agent-presets/（用户可写目录，每预设一个目录：agent.cordis.yml + preset.yml）。
+ * system 预设（安装目录）只记引用不复制（本 adapter 只读用户目录）。
+ */
+import { FileCollectionAdapter } from './file-collection.ts';
+export declare class AgentPresetsAdapter extends FileCollectionAdapter {
+    readonly id: "agentPresets";
+    readonly displayName = "Agent Presets";
+    readonly defaultIncluded = true;
+    readonly portability: "portable";
+    readonly baseDir = ".agent-presets";
+}

package/lib/adapters/agent-presets.js

@@ -0,0 +1,14 @@
+/**
+ * agentPresets 分区 adapter（设计 §3.3）：
+ * 数据源 = ~/.dsh/.agent-presets/（用户可写目录，每预设一个目录：agent.cordis.yml + preset.yml）。
+ * system 预设（安装目录）只记引用不复制（本 adapter 只读用户目录）。
+ */
+import { FileCollectionAdapter } from "./file-collection.js";
+export class AgentPresetsAdapter extends FileCollectionAdapter {
+    id = 'agentPresets';
+    displayName = 'Agent Presets';
+    defaultIncluded = true;
+    portability = 'portable';
+    baseDir = '.agent-presets';
+}
+//# sourceMappingURL=agent-presets.js.map

package/lib/adapters/agent-presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-presets.js","sourceRoot":"","sources":["../../src/adapters/agent-presets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,OAAO,mBAAoB,SAAQ,qBAAqB;IACnD,EAAE,GAAG,cAAuB,CAAC;IAC7B,WAAW,GAAG,eAAe,CAAC;IAC9B,eAAe,GAAG,IAAI,CAAC;IACvB,WAAW,GAAG,UAAmB,CAAC;IAClC,OAAO,GAAG,gBAAgB,CAAC;CACrC"}

package/lib/adapters/credentials.d.ts

@@ -0,0 +1,36 @@
+/**
+ * credentialsStatus 分区 adapter（设计 §3.3/§7.1）：
+ * 数据源 = ctx.credentials.describe(ref) 的状态（configured/source/writable），
+ * 以及 settings secrets 标记 / llm apiKeyEnv 中引用的凭据 ref 名。
+ *
+ * 安全不变量：永不导出值（hasValue 恒 false）；导入生成 MissingSecret 清单，
+ * 用户补录值经 ctx.secretInputs / decryptedCredentials（仅内存）→ credentials.set()。
+ * .credentials.yaml 文件字节交由 m4 加密层处理，本 adapter 不触碰。
+ */
+import type { CredentialsSection } from '../schema/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
+import { type NamespaceProvider } from './settings.ts';
+export type CredentialRefsProvider = (ctx: HostContext) => Promise<string[]>;
+/** 缺省 ref 收集：遍历 settings namespace，收集 llm apiKeyEnv / providers[].apiKeyEnv，
+ * 以及 secrets 标记中「引用类字段」（apiKeyEnv/tokenEnv…）的字段值。
+ * 注意 secrets[].path[0] 是 settings 文档内的字段路径（如 ['apiKey']），本身不是凭据 ref（设计 §4.2），
+ * 只有指向 env 名的引用字段才值得收集。 */
+export declare function defaultCredentialRefs(namespaces: string[] | NamespaceProvider): CredentialRefsProvider;
+export interface CredentialsAdapterOptions {
+    /** 凭据 ref 名收集器（缺省从 settings 推断） */
+    refs?: CredentialRefsProvider;
+    /** 供缺省 refs 使用的 namespace 清单 */
+    namespaces?: string[] | NamespaceProvider;
+}
+export declare class CredentialsAdapter implements ConfigAdapter<CredentialsSection> {
+    readonly id: "credentialsStatus";
+    readonly displayName = "Credentials";
+    readonly defaultIncluded = true;
+    readonly portability: "deviceSpecific";
+    private readonly refs;
+    constructor(options?: CredentialsAdapterOptions);
+    export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<CredentialsSection>>;
+    analyzeImport(_data: CredentialsSection, _ctx: ImportContext): Promise<PlanItem[]>;
+    applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+    validate(data: CredentialsSection): Promise<ValidationResult>;
+}