dsh-config-manager 0.1.68 → 0.1.70

package/README.md

@@ -19,6 +19,7 @@ Backup, restore, export, import, migrate and sync your complete DeepSeek Harness
 - 🔐 Encrypted backups with optional credentials
 - ☁️ **Git / WebDAV** configuration sync
 - 🛒 **Configuration market** — browse & one-click install shared configs
+- 🧳 **Import from other AI agents** — Claude Code, Cursor, Codex, Hermes, Antigravity … config **and chat history**
 - ↩️ Automatic snapshot and rollback before restore
 
 [English](README.md) · [简体中文](README.zh-CN.md)
@@ -46,7 +47,7 @@ DSH is your AI assistant workbench — it holds your settings: model configs, pl
 
 ### Backup DeepSeek Harness configuration
 
-Create a portable backup of your DSH settings, model providers, plugins, MCP servers, skills, agent presets and workspace — one ZIP file, no secret values included by default. (DSH's own profiles — `$DSH_HOME/profiles/<name>`, i.e. which plugin stack to boot — are machine-local and are not migrated; the **Profiles** page can list/create/rename/delete them and record which one the next launch should use.)
+Create a portable backup of your DSH settings, model providers, plugins, MCP servers, skills, agent presets and workspace — one ZIP file, no secret values included by default. (DSH's own profiles — `$DSH_HOME/profiles/<name>`, i.e. which plugin stack to boot — are machine-local and are **not** part of the backup; the **Profiles** page manages them instead — list / create / rename / delete, plus launching or stopping an independent instance for one.)
 
 ### Restore DeepSeek Harness on another machine
 
@@ -68,6 +69,10 @@ Turn on scheduled backups (6h / 12h / 24h / 7d — or a **custom weekly weekday
 
 Browse the built-in official market for ready-made configurations (model providers, plugins, MCP servers, skills, agent presets…), preview what would be imported (dry-run), and install with one click — supply-chain warnings are always shown and every section must be explicitly approved before anything is written.
 
+### Import from another AI agent (Claude Code, Cursor, Codex, …)
+
+Your setup — and your chat history — already live in another AI coding agent on this machine? Pick the source and DSH Config Manager **translates it into a standard bundle** (MCP servers, skills, global instructions, conversations and the workspaces they belong to) and hands it to the same review-first import flow: preview → per-item conflict decisions → automatic snapshot → apply → rollback. 30 sources are recognized and 29 of them can migrate **chat history** too. Secret **values** are never read — only the key names, so the import plan can ask you to re-enter them.
+
 ---
 
 ## 🆚 How it differs from the other DSH backup / sync plugins
@@ -77,7 +82,7 @@ Several DSH plugins live in this space and they solve different problems — pic
 | Plugin | Strongest at | Where DSH Config Manager goes further |
 |---|---|---|
 | [xiaoyuyu6420/dsh-backup](https://github.com/xiaoyuyu6420/dsh-backup) | One-command `~/.dsh` snapshots from the CLI, plus session doctor / upgrade snapshots / rescue console | Review-before-write GUI flow (dry-run preview, per-item conflict decisions, automatic rollback), cross-machine path remapping, encrypted credential payload, configuration marketplace |
-| [muyifc/dsh-config-sync](https://github.com/muyifc/dsh-config-sync) | Export / import DSH configuration to a portable, password-encrypted file, callable from tool calls | 13–14 sections incl. plugins / MCP / skills / profiles / workspaces, scheduled backups, Git + WebDAV sync per channel, session migration with path rebase |
+| [muyifc/dsh-config-sync](https://github.com/muyifc/dsh-config-sync) | Export / import DSH configuration to a portable, password-encrypted file, callable from tool calls | 13–14 sections (plugins / MCP / skills / workspaces / session logs …), scheduled backups, Git + WebDAV sync per channel, session migration with path rebase |
 | [dickpy/dsh-cloud-sync](https://github.com/dickpy/dsh-cloud-sync) · [weibaohui/dsh-sync](https://github.com/weibaohui/dsh-sync) | Keeping machines consistent through WebDAV / S3 or a private Git mirror | Sync is one of five capabilities here — alongside export/import, scheduling, marketplace and profile instance launch/stop |
 | `cp -r ~/.dsh` (or Git on the home dir) | Free, zero setup, fine for a purely textual config | No secret handling, no path remapping, no capture of `link:` / `file:` plugin installs, no session-log work, no conflict handling or rollback |
 
@@ -102,7 +107,13 @@ Several DSH plugins live in this space and they solve different problems — pic
 | 🛒 | **Config Marketplace** | Browse & one-click install community configs — supply-chain warnings + per-item content selection (change summary + in-place high-risk flags) |
 | 🗂️ | **Profiles (DSH profiles)** | Manage `$DSH_HOME/profiles/<name>` directly: list / create from a shipped template / rename / hard delete / **launch this profile (independent instance)** / **stop the instance** (the row button flips between Launch and Stop with the running state) |
 | 🌐 | **Bilingual UI** | Interface, reports and error details follow the DSH app language (中文 / English) |
+| 🧩 | **Local plugin migration** | `link:` / `file:` development plugins are packed into the backup, so switching machines does not lose them |
+| 🗄️ | **Configurable retention (GFS tiers)** | "keep the last N + one per month + one per year" — the defaults are equivalent to the previous behaviour |
 | 🤖 | **Agent tools** | Backup / snapshot / restore / sync right from an agent session |
+| 💾 | **Disk usage report** | The backups page shows how much space the plugin's own artifacts take (backups / snapshots / sync copies / caches / staging) with a three-tier cleanup policy; **one-click cleanup only touches regenerable caches and expired backups** — snapshots and sync data are never removed there |
+| ⬆️ | **Update check** | The About page reads the latest version from npm (read-only, cached 10 minutes); when there is a newer one it offers a copyable upgrade command **and** a one-click **Update now** that installs exactly that version — DSH must then be restarted, and the plugin never restarts it for you. Offline failures are reported honestly and affect nothing else |
+| 🧭 | **Compatibility explained** | Before importing you see "source DSH version / platform → local" plus **structured reasons** for the score (cross-platform / missing sections / newer source …) instead of a bare "partial" |
+| 🧳 | **Import from other AI agents** | Read Claude Code / Cursor / Codex / Hermes / Antigravity … configuration **and chat history** on this machine, translate it into a standard bundle, then import through the usual preview / conflict / rollback flow |
 
 ---
 
@@ -211,6 +222,27 @@ dsh plugin --profile web add dsh-config-manager@latest
 >
 > Then retry the install. As long as that global copy exists and is incompatible with your DSH, every profile (`web` / `desktop` / custom) is rejected the same way.
 
+### Installing from the GitHub source (`git+https://...`)
+
+When installed from a git source, pnpm first runs this package's `prepare` script (= `npm run build`) inside that clone to produce `lib/` — **npm ships a prebuilt `lib/`, a git install builds it on the spot**. pnpm 11 blocks that script by default, so the install fails with `dsh: plugin command failed` and this in the log:
+
+```
+ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED  Failed to prepare git-hosted package ...
+The git-hosted package "dsh-config-manager@x.y.z" needs to execute build scripts
+but is not in the "allowBuilds" allowlist.
+```
+
+**Fix**: copy the exact line pnpm prints (it includes the full git URL and commit sha) into the profile's `pnpm-workspace.yaml`:
+
+```yaml
+# ~/.dsh/profiles/web/pnpm-workspace.yaml
+allowBuilds:
+  dsh-config-manager@git+https://github.com/xiajiajun516/dsh-config-manager.git#<sha printed by pnpm>: true
+```
+
+> The key must be copied **verbatim** — the bare package name `dsh-config-manager` does not work (the allowlist matches on source + version).
+> The simpler path is the prebuilt npm release above (`dsh-config-manager@latest`), which needs no allowlist at all.
+
 ---
 
 ## 🚀 Quick start (3-minute tour)
@@ -283,6 +315,17 @@ When the target already has a same-named item, you choose:
 2. Lets you pick new paths
 3. Supports **batch prefix mapping** (`C:\Users\alice\` → `/Users/bob/` in one shot)
 
+### 🧳 Import from other AI agents (config + chat history)
+
+You do not have to rebuild another agent's setup by hand.
+
+- **30 sources recognized** — Claude Code, Hermes, Cursor, Codex, Antigravity, Gemini, OpenCode, Mimocode, ZCode, Grok Build, OpenClaw, Pi, Kimi, Kilocode, Qoder, ChatGPT, WorkBuddy, Qwen, Continue, Cline, Goose, Zed, Crush, TeleAgent, Trae, Vibe, Reasonix, Copilot, and DSH itself (importing from another DSH home — its v3 and v4 logs count as two ids). Sources **not** installed on this machine are still listed (greyed out, not selectable), so "this machine has no such tool" is never mistaken for "the feature is missing".
+- **Translation, not a second import path** — the source is converted into a standard bundle v1 ZIP and handed to the **existing** import wizard: same preview, same per-item conflict decisions, same pre-import snapshot and rollback, same dry-run.
+- **What travels** — MCP servers, skills, global instructions (as `AGENTS.md`), and **chat history together with the workspaces those conversations belong to** (29 sources; conversations are re-encoded into DSH's session-log format and placed by their recorded `cwd`).
+- **What does not** — secret **values** are never read: only the key names are recorded so the plan can ask you to re-enter them. Structures DSH has no equivalent for (Claude Code hooks, slash commands, …) are reported as explicit codes rather than silently dropped.
+- **Honest skips** — a conversation with no recorded `cwd` cannot be placed and is reported as skipped (never guessed into some other project); known lossy items are listed **before** the import runs.
+- **Entry points** — Settings → "Backup & Migration" → Import → **"Import from another agent"**, the ⌘K command, or the CLI: `dcm import --from <source> [--dry-run] [--out <path>]`.
+
 ### 🔒 Secrets
 
 | Scenario | Behavior |
@@ -301,7 +344,7 @@ Push / pull your portable config between machines through **either of two channe
 | **Endpoint** | `repoUrl` | `webdav.url` |
 | **Credentials** | auth token in DSH credentials (`DSH_CONFIG_MANAGER_SYNC_TOKEN`) | `username` stored in the config (echoed in the UI); **password never synced / never logged** — DSH credentials `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` |
 
-- **Same snapshot retention for both channels**: only the newest **10** snapshots are kept on the remote (`MAX_REMOTE_SNAPSHOTS=10`); older ones are deleted automatically.
+- **Remote retention follows your backup schedule**: both channels keep the same policy as local backups — by default the newest **10** snapshots, plus optional "one per month / one per year" tiers — and the snapshot you just pushed is always kept; older ones are deleted automatically.
 - **Switching channels starts fresh**: Git and WebDAV do **not** share snapshots or a common ancestor. When you switch transport, sync begins again from the new remote's empty baseline — push a fresh snapshot first.
 - **WebDAV auth** uses HTTP Basic: the `username` is stored in the config and may be echoed back into the UI, while the `password` is read live from the DSH credentials slot `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` — it never appears in any sync file or log.
 - **Plugins auto-install**: when pulling diffs, plugins that are new in the backup are **installed automatically** on confirm — no manual per-item ticking in the diff list. Only **version-conflict** plugins still ask you to pick "Keep Current / Use Imported".
@@ -369,6 +412,19 @@ Every import creates a **safety snapshot** first. If something feels off afterwa
 
 ---
 
+
+**Backup files & disk usage**: the **"Backup Files"** sub-tab (Backups → snapshot tab) manages everything in
+`exports/` (manual exports + scheduled backups): download, import straight back, inspect, delete, search by
+name or note. The **"Disk Usage"** card on the same page lists what this plugin itself occupies (exports,
+pre-import snapshots, sync config and Git working copies, marketplace cache, temp staging, logs, transaction
+log, …) and labels each item's cleanup policy: **regenerated on demand** (caches/staging), **retained**
+(exports for 7 days, scheduled backups keep the latest N), or **your data / safety net** (snapshots and sync —
+never auto-cleaned). **"Clean now"** clears only regenerable caches by default; reclaiming expired backups is
+an explicit opt-in with a confirmation. Snapshots and sync data are never touched, and unreadable directories
+are reported as "not measured" instead of a misleading 0 bytes.
+
+---
+
 ### 🚨 CLI — the first line of defense when DSH is broken
 
 The GUI lives *inside* DSH — it can't help you if DSH won't start. The `dsh-config-manager` **CLI is completely independent of the DSH runtime** (pure Node + the core engine, **zero `@deepseek-ai/*` imports** — it runs even when the DSH peer packages are broken or missing). That makes it your **first rescue tool** when the config is corrupted, the GUI won't boot, or you changed machines and need to bring an environment back.
@@ -382,22 +438,40 @@ npm install -g dsh-config-manager@latest --omit=peer
 
 > ⚠️ Installing/updating the plugin (`dsh plugin --profile web add ...`) only enables the GUI — it does **not** create the `dsh-config-manager` command. Run the install command above, then any of the commands below.
 
-All commands (also shown by `dsh-config-manager help`):
+All commands (also shown by `dsh-config-manager help`, which groups them by risk; `dsh-config-manager <command> --help` prints one command's options, exit codes and examples):
 
 ```text
-dsh-config-manager help                                        # list all commands & options
+# Rescue console (local web page — the least typing)
+dsh-config-manager web [--port <n>] [--no-open] [--home <dir>]
+                       [--data-root <dir>] [--idle-timeout <min>]
+
+# Inspect (never touches your config)
 dsh-config-manager snapshots [--data-dir <dir>]                # list snapshots (newest first)
-dsh-config-manager restore [--id <id>] [--dry-run]
-                           [--profile <name>] [--settings <path>]
-dsh-config-manager reinstall [--version <v>] [--yes] [--list]
-                             [--wipe-config] [--dry-run]       # one-click reinstall of DSH itself
-dsh-config-manager recover-stale-lock [--data-dir <dir>]       # clear a leftover lock (see below)
-dsh-config-manager verify [--id <file|path>] [--json]         # read-only check of backup ZIPs
-                          [--data-dir <dir>]
-dsh-config-manager backup [--sections <a,b,c>] [--out <path>] # offline file-level backup
+dsh-config-manager verify [<file|path>] [--json]               # read-only check of backup ZIPs
+                           [--data-dir <dir>]
+dsh-config-manager sessions list   [--home <dir>] [--json]     # list local sessions
+dsh-config-manager sessions doctor [--home <dir>] [--json]     # health check + advice
+
+# Backup & migrate (only writes new files)
+dsh-config-manager backup [--sections <a,b,c>] [--out <path>]  # offline file-level backup
                           [--dry-run] [--data-dir <dir>]
-dsh-config-manager sessions repair [--home <dir>] [--fix]     # offline session layout repair
+dsh-config-manager import --from <source> [--dry-run]          # foreign agent config → bundle ZIP
+                           [--out <path>] [--cwd <dir>] [--data-dir <dir>]
+
+# Repair (writes to this machine — preview with --dry-run first)
+dsh-config-manager restore [--id <id>] [--dry-run]             # roll back to a pre-import snapshot
+                           [--data-dir <dir>] [--data-root <dir>]
+                           [--profile <name>] [--settings <path>]
+dsh-config-manager sessions repair [--home <dir>] [--fix]      # offline session layout repair
                                    [--keep <dir>] [--map old=new]...
+dsh-config-manager recover-stale-lock [--data-dir <dir>]       # clear a leftover lock (see below)
+
+# Dangerous (changes your DSH install / may wipe data)
+dsh-config-manager reinstall [--version <v>] [--yes] [--list]
+                             [--wipe-config] [--dry-run] [--data-root <dir>]
+
+# Help
+dsh-config-manager help [command]                              # overview / one command's detail
 ```
 
 **`reinstall` — rescue when DSH is broken.** It reinstalls the `@deepseek-ai/dsh` launcher across platforms (uses the right command per OS: PowerShell on Windows, bash on Unix). By default it reinstalls the launcher + clears global caches; interactively it asks which **dangerous** clean-up items to include (settings / plugins / session data & credentials) — those are **not** selected by default, and any destructive choice requires a second confirmation by typing `YES` before anything runs. Before wiping any `~/.dsh` data it makes an emergency backup at `.reinstall-backup` (the `snapshots/` folder is deliberately never touched).
@@ -452,6 +526,8 @@ dsh-config-manager verify C:/backups/dsh-config.zip   # ...or by path
 
 **Credential files never enter a backup.** `.credentials.*`, `.env`, `*.pem` and friends are excluded by an explicit blacklist, only whitelisted directories are walked (never the whole home directory), and symlinks are skipped rather than followed.
 
+**Offline backup only covers on-disk skills.** Skills that live in the plugin registry (the ones the shell loads from a profile's plugin packages — see issue #71) need the DSH runtime to enumerate, so only the GUI export (or a scheduled backup while DSH is healthy) can include them; the CLI `backup` collects just the files under `$DSH_HOME/skills`. For a complete skills backup, use the GUI export while DSH is healthy.
+
 Structured sections (settings / UI / providers / plugins / MCP / prompts / workspaces) are **not** silently faked: they need the DSH service layer to read and redact, so they are left out and marked `false` in the manifest — the plan printout lists them under “not offline-collectable” so you know exactly what this backup does and does not contain. Use the GUI export when DSH is healthy for a full backup.
 
 ```bash
@@ -463,7 +539,7 @@ dsh-config-manager backup --sections skills,self          # narrow the scope
 
 `--sections` accepts `skills,agentPresets,agentInstructions,self,pluginFiles`. `pluginFiles` is **opt-in** (as in the GUI): it copies third-party plugin files verbatim, and `dsh-ssh.json` holds plaintext host passwords — select it only when you have looked at what is in there.
 
-**A typical rescue flow** when DSH won't start: ① `dsh-config-manager reinstall` to bring the launcher back (plus any clean-up), ② if DSH reports a session-log error (`corrupt session log` / `duplicate JSONL session id`), run `dsh-config-manager sessions repair --fix` first — it repairs the log layout offline, ③ `dsh web` to start DSH again, ③ re-add the plugin from the registry, and ④ pull a snapshot from the remote repo (or run `dsh-config-manager restore`) to bring your config back. The CLI works at every step regardless of DSH's health.
+**A typical rescue flow** when DSH won't start: ① `dsh-config-manager reinstall` to bring the launcher back (plus any clean-up), ② if DSH reports a session-log error (`corrupt session log` / `duplicate JSONL session id`), run `dsh-config-manager sessions repair --fix` — it repairs the log layout offline, ③ `dsh web` to start DSH again, ④ re-add the plugin from the registry, and ⑤ pull a snapshot from the remote repo (or run `dsh-config-manager restore`) to bring your config back. The CLI works at every step regardless of DSH's health.
 
 **`recover-stale-lock` — when every operation suddenly fails.** Before touching your config, the plugin claims a small environment lock (it records who is operating plus a heartbeat) so that two operations can never write your config at the same time. If a `dsh web` process is **force-killed** (Task Manager, `kill -9`), the lock file survives with a dead owner: the next operation is refused, and it stays refused **no matter how often you retry or restart DSH** — because the plugin deliberately never removes a lock on its own (a wrong guess could evict a live operation).
 
@@ -530,6 +606,17 @@ How it behaves:
 
 Alternative (host-wide): set `NODE_USE_ENV_PROXY=1` **before starting DSH** (Node 24+); note this also routes the host's own outbound traffic, not just this plugin's.
 
+**`web` — the offline rescue console (for when you would rather click than type).** It starts a small web page bound to **127.0.0.1 only** and lays out the same diagnostics and rescue actions in a browser:
+
+```bash
+dsh-config-manager web            # starts it and opens your browser (the terminal prints a one-time token URL)
+```
+
+- **Read-only:** running instances / SAFE MODE / leftover lock / snapshots / exported backups (with one-click verification) / disk usage / session health / profiles and their instances.
+- **Write actions (each needs an explicit confirmation in the page, and every one calls the same implementation as the CLI):** ① relocate misplaced sessions ② clear rebuildable caches and expired exports ③ reclaim a stale environment lock ④ start/stop a profile's standalone instance ⑤ **unlock an encrypted backup** (decrypted in memory, lists entries only — never written to disk) ⑥ **restore a snapshot** (see the per-item plan first, zero writes; restoring copies current files to `<snapshot>/pre-restore/` first) ⑦ **offline export** (file-based sections, self-checked right after writing) ⑧ **reinstall DSH** (uninstall + reinstall the global CLI; **requires a 6-character code printed only in the terminal**).
+- **Safety:** loopback-only binding; a one-time token printed to your terminal is exchanged for an HttpOnly + SameSite=Strict session cookie; the page has no scripts and no external resources. `Ctrl+C` or the idle timeout (30 minutes by default) shuts it down.
+- **Preconditions:** session relocation and restore need DSH stopped; with an unresolved SAFE MODE transaction or a leftover environment lock every write action is refused (the page says why). **Import** (writing a bundle back into this machine) stays on the GUI/CLI — structural sections need live DSH services.
+
 ### 🤖 Agent tools (for AI assistants)
 
 The plugin also registers **5 model tools** that an AI agent (a DSH assistant session) can call directly — the same backup / snapshot / sync engines, no GUI needed:
@@ -582,7 +669,7 @@ Yes. Dead absolute paths are detected and remapped (batch replacement supported)
 No. A checksum mismatch rejects the import outright (protects against corruption or tampering).
 
 **Q: Will re-importing duplicate things?**
-No. Items are deduplicated by stable IDs (plugin ID / MCP name / skill name…); existing items are skipped.
+No. Items are matched by stable IDs (plugin ID / MCP name / skill name…): identical ones are skipped, and ones that differ from the target surface as **conflicts you decide** (Keep Current / Use Imported) — nothing is overwritten silently.
 
 **Q: Why is the console quiet after `dsh web` — how do I get the plugin logs back?**
 By design. Routine progress logs (mount banner, scheduler skips, export/backup completion) are emitted at `info`, and the shipped default level is `warn` — so only warnings and errors reach the terminal. Set `DSH_CONFIG_MANAGER_LOG_LEVEL=info` (or `debug`) before starting DSH to bring the verbose lines back.
@@ -597,9 +684,11 @@ Yes. The import wizard asks for the export-time encryption password and verifies
 1. **Installing / updating plugins or MCP takes effect after restarting DSH**
 2. **Some UI state is not migrated** (e.g. task board data, panel widths — they live in the browser, not in DSH's config files)
 3. **keybindings / workflow configs / commands** — DSH has no such concepts, so nothing is exported for them. Global agent rules are covered by **Agent Instructions** (`~/.dsh/AGENTS.md`, injected into every session); per-project `AGENTS.md`/`CLAUDE.md` belong to each project's repo and are not migrated
-4. **History/session migration is off by default** (v1 copies files only)
+4. **History/session migration is opt-in** — DSH's own sessions are only exported/synced when you explicitly select the `sessions` section (the sync channel additionally needs both sides to allow it); **another agent's chat history is migrated when you pick that source** in the foreign import. Conversation state that DSH's session format has no room for (model reasoning traces, images, compaction checkpoints) is counted and reported, never fabricated
 5. **Encrypted backups**: a lost password means the `secrets.enc` can't be decrypted (by design — keep your password safe)
 6. **Snapshot restore is offline and honest**: entries the offline engine can't restore (settings namespaces / patch lines when the snapshot has no whole-file backup, workspace records stored in DSH storages) are reported as skipped with a pointer to online rollback; credential **values** are never auto-written (manual re-entry hint only); old snapshots without a plugin baseline only get a hint to remove added plugins manually
+7. **Foreign-agent import has two known blanks**: **Copilot has no chat-history import** (its session format could not be verified on this machine, so only its configuration is imported), and Cursor's per-project history is located through Cursor's own folder-slug scheme, which may not resolve for every project. Conversations already imported with an older build should be deleted and re-imported first (a second import of the same id is reported as a **skipped** `session-id-conflict`, not merged)
+8. **Local source plugins (`link:` / `file:`) are packed into the backup**: the export runs `npm pack` on plugins you are developing locally and stores the tarball in the backup; the import unpacks it under `$DSH_HOME/dsh-config-manager/local-plugins/` and installs it as `file:`. Three consequences: ① backup size grows with those plugins (a single plugin over 100 MB is skipped with a warning — publish it to a registry / git first); ② plugin **source code** enters the backup (this does not conflict with "no secrets in backups" — secrets stay excluded, what travels is code); ③ packing needs a working `npm` on this machine; without it the plugin falls back to the previous behaviour (the original spec is kept, and a new machine still needs a manual install)
 
 ## 💬 Feedback
 
@@ -629,6 +718,11 @@ Found a bug, a misaligned panel, a button that does nothing — or just have an
   contribution, commit `1248200` was landed on `main` through a **"keep the commit, take the mainline tree"** merge
   (`122317b`) — that merge takes **none** of its code (the resulting tree is byte-identical to the mainline) and exists purely
   to record authorship, so GitHub now counts this contribution instead of leaving it invisible behind a closed PR.
+- **OMSociety** — [PR #66](https://github.com/xiajiajun516/dsh-config-manager/pull/66), merged as `4170af4`: proposed and
+  implemented the 36×36 frame-less `icon.svg` (issue #61, aligning the plugin with the official bundle convention).
+  The report came with upstream evidence (host artwork frames of 48/36 px and 40/30 px, the official published bundle
+  icons, the fixture SVG) and the PR shipped a 16/30/36/48 × dark/light acceptance sheet plus a written argument for
+  keeping the proposal's palette over the plugin's brand blue.
 - **Bug reports**: `zhyx1996` (#38 sync "Export secrets" did nothing), `IPF-Sinon` (#39 the `.credentials.yaml` `refs:` block
   was not recognized — they also implemented and machine-tested a fix in their own fork), `zerginlaw` (#43 "Back up now"
   silently no-oped while toasting success). Each report drove one fix.

package/README.zh-CN.md

@@ -21,7 +21,7 @@ DSH Config Manager 是一个 DeepSeek Harness 配置备份与迁移插件：一
 > DSH 的 profile（`$DSH_HOME/profiles/<name>`）本身**不随备份迁移**（它是「用哪套插件组合启动」的机器本地选择）；
 > 本插件的「档案」页可以列表 / 新建 / 重命名 / 删除它们，也可以**用某个档案另起一个独立实例并随时停止它**（真正可用的切换）。
 
-把当前 DeepSeek Harness 环境导出为可移植备份，在另一台电脑上一键恢复；也支持通过 Git / WebDAV 跨机同步（密钥默认不同步，勾选「导出密钥」并加密后可随加密快照迁移）；还能通过内置**配置市场**浏览、一键安装社区分享的现成配置。
+把当前 DeepSeek Harness 环境导出为可移植备份，在另一台电脑上一键恢复；也支持通过 Git / WebDAV 跨机同步（密钥默认不同步，勾选「导出密钥」并加密后可随加密快照迁移）；还能通过内置**配置市场**浏览、一键安装社区分享的现成配置；并且能**从其它 AI Agent 导入**配置与历史会话（Claude Code / Cursor / Codex / Hermes / Antigravity 等 30 个来源）。
 
 [English](README.md) · [简体中文](README.zh-CN.md)
 
@@ -48,7 +48,7 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 
 ### 备份 DeepSeek Harness 配置
 
-把你的 DSH 设置、模型供应商、插件、MCP 服务器、技能、Agent 预设、配置档案与工作区打包成一个便携 ZIP 备份——默认不含任何密钥值。
+把你的 DSH 设置、模型供应商、插件、MCP 服务器、技能、Agent 预设与工作区打包成一个便携 ZIP 备份——默认不含任何密钥值（DSH 档案不随备份迁移，见上方说明）。
 
 ### 在另一台电脑上恢复 DeepSeek Harness
 
@@ -70,6 +70,10 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 
 在内置官方市场浏览现成配置（模型 / Provider、插件、MCP、技能、Agent 预设……），先 dry-run 预览再一键安装——供应链警示恒展示，确认导入前每个分区都须显式批准。
 
+### 从其它 AI Agent 导入（Claude Code / Cursor / Codex…）
+
+你在这台机器上已经用过别的 AI 编程 Agent，配置和历史对话都在？选一个来源，本插件会把它**翻译成标准 bundle**（MCP、技能、全局指令、历史会话及其所属工作区），再交给同一条「先审后写」的导入流程：预览 → 逐项冲突决策 → 自动快照 → 应用 → 可回滚。共识别 **30 个来源**，其中 **29 个**可一并迁移**历史会话**。密钥**值**绝不读取，只记下名字供导入计划提示补录。
+
 ---
 
 ## 🆚 与其它备份 / 同步插件的区别
@@ -79,7 +83,7 @@ DSH 生态里这个方向有几个插件，它们解决的问题并不相同—
 | 插件 | 最擅长 | 本插件更进一步的地方 |
 |---|---|---|
 | [xiaoyuyu6420/dsh-backup](https://github.com/xiaoyuyu6420/dsh-backup) | 一条命令从 CLI 给整个 `~/.dsh` 打快照，另有会话体检 / 升级快照 / 救援控制台 | 写盘前可审阅的 GUI 流程（dry-run 预览、冲突逐项决策、失败自动回滚）、跨机路径重映射、加密凭据载荷、配置市场 |
-| [muyifc/dsh-config-sync](https://github.com/muyifc/dsh-config-sync) | 把 DSH 配置导出/导入成可移植的密码加密文件，可被工具调用 | 13–14 个分区（含插件 / MCP / 技能 / 档案 / 工作区）、定时备份、Git + WebDAV 双通道同步、会话跨机迁移与路径重定基 |
+| [muyifc/dsh-config-sync](https://github.com/muyifc/dsh-config-sync) | 把 DSH 配置导出/导入成可移植的密码加密文件，可被工具调用 | 13–14 个分区（插件 / MCP / 技能 / 工作区 / 会话日志 …）、定时备份、Git + WebDAV 双通道同步、会话跨机迁移与路径重定基 |
 | [dickpy/dsh-cloud-sync](https://github.com/dickpy/dsh-cloud-sync) · [weibaohui/dsh-sync](https://github.com/weibaohui/dsh-sync) | 通过 WebDAV / S3 或私有 Git 镜像让多台机器保持一致 | 同步只是本插件五项能力之一——另有导出/导入、定时备份、配置市场与档案实例启停 |
 | `cp -r ~/.dsh`（或给 home 目录挂 Git） | 免费、零配置，纯文本配置够用 | 不处理密钥、不做路径重映射、抓不到 `link:` / `file:` 安装的本地插件、不动会话日志、没有冲突处理与回滚 |
 
@@ -105,7 +109,12 @@ DSH 生态里这个方向有几个插件，它们解决的问题并不相同—
 | 🗂️ | **档案 Profiles（DSH profile）** | 直接管理 `$DSH_HOME/profiles/<name>`：列表 / 新建（官方模板）/ 重命名 / 物理删除 / **启动该档案（独立实例）** / **停止实例**（行内按钮按运行状态在「启动 ↔ 停止」间切换） |
 | 🧩 | **本地插件随备份迁移** | `link:` / `file:` 安装的本地开发插件会被打包进备份，换机不再丢失 |
 | 🗄️ | **保留策略可配（GFS 分层）** | 「最近 N 份 + 每月留 1 份 + 每年留 1 份」，默认值等价旧行为 |
+| 🌐 | **双语界面** | 界面、报告与错误详情跟随 DSH 应用语言（中文 / English） |
 | 🤖 | **Agent 工具** | Agent 会话内直接备份 / 快照 / 恢复 / 同步 |
+| 💾 | **磁盘占用体检** | 备份页逐项列出本插件自身占了多少盘（备份 / 快照 / 同步副本 / 缓存 / 暂存），三档回收策略一目了然；**一键清理只碰可重建缓存与过期备份**，快照与同步数据永不在此删除 |
+| ⬆️ | **版本更新检查** | 「关于」页只读探测 npm 上的最新版本（缓存 10 分钟）；有新版本时既给可复制的升级命令，也提供一键**立即更新**（按该精确版本安装）——之后需重启 DSH 才生效，插件绝不代你重启；离线失败如实显示，不影响其它功能 |
+| 🧭 | **兼容性讲清楚** | 导入前显示「来源 DSH 版本 / 平台 → 本机」，并用**结构化原因**解释评分（跨平台 / 分区缺失 / 版本超前…），而不是只丢一句「部分兼容」 |
+| 🧳 | **从其它 AI Agent 导入** | 读取本机 Claude Code / Cursor / Codex / Hermes / Antigravity 等的配置**与历史会话**，翻译成标准 bundle，再走既有的预览 / 冲突 / 回滚流程导入 |
 
 ---
 
@@ -188,6 +197,27 @@ dsh plugin --profile web add dsh-config-manager@latest
 > ```
 >
 > 重启 DSH 后，可在 **设置 → 备份与迁移 → 关于** 看到实际运行的版本（版本变化时也会自动弹出更新内容）。
+
+### 从 GitHub 源码安装（`git+https://...`）
+
+用 git 源安装时，pnpm 会先在该 clone 里跑本包的 `prepare` 脚本（= `npm run build`）把 `lib/` 构建出来 —— **产物在 npm 上已预构建，从 git 安装则是现构建**。pnpm 11 默认**拦截**这个脚本，直接报 `dsh: plugin command failed`，日志里是：
+
+```
+ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED  Failed to prepare git-hosted package ...
+The git-hosted package "dsh-config-manager@x.y.z" needs to execute build scripts
+but is not in the "allowBuilds" allowlist.
+```
+
+**解决**：把它提示的那一行（**含完整 git URL 与 commit sha**，逐字复制）加进 profile 的 `pnpm-workspace.yaml`：
+
+```yaml
+# ~/.dsh/profiles/web/pnpm-workspace.yaml
+allowBuilds:
+  dsh-config-manager@git+https://github.com/xiajiajun516/dsh-config-manager.git#<pnpm 打印的 sha>: true
+```
+
+> 键必须**逐字**照抄 pnpm 打印的那一行 —— 只写包名 `dsh-config-manager` 不生效（该白名单按「来源 + 版本」匹配）。
+> 更省事的路径是直接装 npm 预构建版（上面的 `dsh-config-manager@latest`），无需任何白名单。
 >
 > - 或一行命令彻底关闭年龄门槛（在 profile 的 `pnpm-workspace.yaml` 顶部加 `minimumReleaseAge: 0`）：
 >   ```powershell
@@ -281,6 +311,17 @@ dsh plugin --profile web add dsh-config-manager@latest
 2. 让你选择新路径
 3. 支持**批量前缀映射**（如 `C:\Users\alice\` → `/Users/bob/` 一键替换所有相关路径）
 
+### 🧳 从其它 AI Agent 导入（配置 + 历史会话）
+
+不必手工重建另一个 Agent 里已经调好的那套配置。
+
+- **识别 30 个来源** —— Claude Code、Hermes、Cursor、Codex、Antigravity、Gemini、OpenCode、Mimocode、ZCode、Grok Build、OpenClaw、Pi、Kimi、Kilocode、Qoder、ChatGPT、WorkBuddy、Qwen、Continue、Cline、Goose、Zed、Crush、TeleAgent、Trae、Vibe、Reasonix、Copilot，以及 DSH 自己（从另一个 DSH home 导入，其 v3 / v4 日志算两个 id）。本机**没装**的来源照样列出来（置灰不可选）——「这台机器没有这个工具」不会被误解成「功能没做」。
+- **是翻译，不是第二套导入通道** —— 来源被转成标准 bundle v1 ZIP，交给**既有**导入向导：同一份预览、同一套逐项冲突决策、同一次导入前快照与回滚、同样的 dry-run。
+- **会带走什么** —— MCP Servers、技能、全局指令（落成 `AGENTS.md`），以及**历史会话连同这些对话所属的工作区**（29 个来源；会话会重新编码成 DSH 的会话日志格式，并按它记录的 `cwd` 归位）。
+- **不会带走什么** —— 密钥**值**一律不读：只记录键名，由导入计划提示补录。DSH 没有对等结构的东西（Claude Code 的 hooks、斜杠命令等）会**报出明确的码**，不会静默丢掉。
+- **如实跳过** —— 没记录 `cwd` 的对话无处归位，会列为跳过（绝不猜进别的项目）；已知的有损项在导入**之前**就摆明。
+- **入口** —— 设置 →「备份与迁移」→ 导入 → **「从其它 agent 导入」**、⌘K 命令，或 CLI：`dcm import --from <来源> [--dry-run] [--out <路径>]`。
+
 ### 🔒 密钥处理
 
 | 场景 | 行为 |
@@ -299,7 +340,7 @@ dsh plugin --profile web add dsh-config-manager@latest
 | **端点** | `repoUrl` | `webdav.url` |
 | **凭据** | 认证 token 存入 DSH credentials（`DSH_CONFIG_MANAGER_SYNC_TOKEN`） | `username` 存配置、可在界面回显；**密码永不同步、永不记日志**——存入 DSH credentials `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` |
 
-- **两通道保留策略一致**：远端只保留最新 **10** 个快照（`MAX_REMOTE_SNAPSHOTS=10`），更旧的自动删除。
+- **远端保留跟本地同一套策略**：两通道都按你的备份计划保留——默认最新 **10** 个快照，可另设「每月 1 份 / 每年 1 份」分层；刚推上去的那份恒保留，更旧的自动删除。
 - **切换通道重新开始**：Git 与 WebDAV 的快照 / 共同祖先**互不共享**。切换通道后，同步从新远端的空基线重新开始——请先推送一个新快照。
 - **WebDAV 认证**采用 HTTP Basic：`username` 存配置、可在界面回显；`password` 则实时从 DSH credentials 槽位 `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` 读取——绝不出现于任何同步文件或日志。
 - **插件自动安装**：拉取差异时，备份里新增的插件会在确认导入时**自动安装**，无需在差异列表里逐项手动勾选；只有**版本冲突**的插件仍需要你决定「保留当前 / 采用备份」。
@@ -351,6 +392,14 @@ dsh plugin --profile web add dsh-config-manager@latest
 
 **GUI**：设置 → 「备份与迁移」→「快照恢复」tab → 选择快照 → 预览恢复计划（dry-run，零写入）→ 确认执行。
 
+**备份文件与磁盘占用**：「备份与迁移」→「快照恢复」tab 下的**「备份文件」**子页统一管理 `exports/` 里的导出产物
+（手动导出 + 定时备份）——可下载、直接导入恢复、查看内容、删除，并按文件名/备注搜索。
+同页的**「磁盘占用」卡**会逐项列出本插件自己占用的空间（导出备份 / 导入前快照 / 同步配置与 Git 工作副本 /
+市场缓存 / 临时暂存 / 日志 / 事务日志 …），标注每项的回收策略：**可随时重建**（缓存与暂存）、
+**有保留期**（导出产物 7 天、定时备份保留最近 N 个）、**用户数据 / 安全网**（快照与同步，永不自动清理）。
+需要腾空间时点**「立即清理」**：默认只清可重建的缓存与暂存；要回收过期备份文件需显式勾选（并二次确认）。
+**快照与同步数据永远不会被这个按钮删掉**；目录读不到时如实显示「未统计」，不会伪报 0 字节。
+
 ---
 
 ### 🚨 CLI —— DSH 挂了时的第一救急手段
@@ -433,6 +482,8 @@ dsh-config-manager verify C:/backups/dsh-config.zip   # 或按路径
 
 **凭据文件永不进入备份。** `.credentials.*`、`.env`、`*.pem` 等由显式黑名单排除；只遍历白名单目录（绝不对整个主目录递归）；symlink 一律跳过而非跟随。
 
+**离线备份只覆盖磁盘上的技能。** 插件注册表里的技能（外壳从 profile 的插件包里加载的那些，见 issue #71）需要 DSH 运行时才能列举，因此**只有 GUI 导出（或 DSH 健康时的定时备份）能带上它们**；CLI `backup` 只收 `$DSH_HOME/skills` 目录下的文件——想要完整的技能备份，请在 DSH 健康时用 GUI 导出。
+
 结构化分区（设置 / UI / providers / 插件 / MCP / prompts / workspaces）**不会**被偷偷伪造：它们需要 DSH 服务层读值并脱敏，因此一律不写入、在 manifest 里标记为 `false`——计划输出会把它们列在「离线不可收集」下，让你清楚这份备份到底有什么、没有什么。DSH 健康时想要完整备份，请用 GUI 导出。
 
 ```bash
@@ -445,7 +496,22 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
 `--sections` 可选值为 `skills,agentPresets,agentInstructions,self,pluginFiles`。其中 `pluginFiles` 与 GUI 侧一致属**默认关闭**：它原样复制第三方插件自有文件，而 `dsh-ssh.json` 里是明文主机密码——确认过内容之后再选它。
 
 
-**典型救急流程**（DSH 起不来时）：① `dsh-config-manager reinstall` 先把启动器重装回来（必要时顺带清理），② `dsh web` 重新启动 DSH，③ 从仓库装回插件，④ 从远程仓库拉取快照（或执行 `dsh-config-manager restore`）把配置恢复回来。整个流程中 CLI 全程可用，与 DSH 是否健康无关。
+**典型救急流程**（DSH 起不来时）：① `dsh-config-manager reinstall` 先把启动器重装回来（必要时顺带清理），② 若 DSH 报会话日志错误（`corrupt session log` / `duplicate JSONL session id`），先跑 `dsh-config-manager sessions repair --fix` 把日志目录离线归位，③ `dsh web` 重新启动 DSH，④ 从仓库装回插件，⑤ 从远程仓库拉取快照（或执行 `dsh-config-manager restore`）把配置恢复回来。整个流程中 CLI 全程可用，与 DSH 是否健康无关。
+
+**`web` —— 离线救急台（不想在终端里敲命令时用这个）。** 它在本机起一个**只绑 127.0.0.1** 的小网页，
+把上面的诊断信息与救急动作都摊在浏览器里：
+
+```bash
+dsh-config-manager web            # 启动并自动打开浏览器（终端里会打印带一次性 token 的链接）
+```
+
+- **只读部分**：实例心跳 / SAFE MODE / 残留锁 / 快照 / 导出产物（可一键自检）/ 磁盘占用 / 会话体检 / 档案与实例状态。
+- **写动作（都要在网页里显式确认）**：会话布局归位、清理可重建缓存与过期导出产物、回收残留环境锁、
+启动/停止某个档案的独立实例。它们调用的是与命令行**同一套实现**，结果页逐条如实回执。
+- **安全**：只绑回环地址；启动时生成一次性 token（只打印在终端），换成一个 HttpOnly + SameSite=Strict 的
+会话 cookie，用过即废；页面零脚本、零外链。`Ctrl+C` 或空闲超时（缺省 30 分钟）即退出。
+- **门槛**：会话归位需要 DSH 已停止；有 SAFE MODE 未结案时写动作一律被拒（页面会写明原因）。
+  恢复快照（`restore`）与重装（`reinstall`）**不在网页里** —— 它们需要更强的确认，留在命令行/GUI。
 
 ### 🤖 Agent 可调用的模型工具
 
@@ -499,7 +565,7 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
 不能。校验和检查不通过会直接拒绝导入（防止损坏或篡改）。
 
 **Q：重复导入会重复吗？**
-不会。按插件 ID / MCP 名称 / 技能名等稳定标识去重，重复导入自动跳过已有项。
+不会。按插件 ID / MCP 名称 / 技能名等稳定标识配对：完全一致的跳过，与目标机有差异的会列为**冲突由你决定**（保留本机 / 用导入的），不会静默覆盖。
 
 **Q：加密备份导入时需要密码吗？**
 需要。导入向导会要求输入导出时设置的加密密码并验证通过后才能继续执行；密码仅存于内存、绝不保存。密码错误或缺失都会阻止导入（密码正确时凭据直接从备份解密恢复，无需重新填写）。
@@ -514,10 +580,11 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
 1. **安装/更新插件或 MCP 后需重启 DSH 才生效**
 2. **部分界面状态不迁移**（如任务看板数据、面板宽度——它们存在浏览器里，不在 DSH 配置文件内）
 3. **keybindings / workflows 配置 / commands**：DSH 当前没有这些概念，因此不会导出相关内容。全局 agent 规则已由**全局指令（Agent Instructions）**承接（`~/.dsh/AGENTS.md`，注入每个会话）；项目级 `AGENTS.md` / `CLAUDE.md` 属于各项目仓库本身，不在个人配置迁移范围内
-4. **历史会话默认不迁移**（v1 仅支持文件级复制）
+4. **历史会话是显式可选项** —— DSH 自己的会话只有在导出 / 同步时**显式勾选 `sessions` 分区**才会带走（同步通道还要求两侧都放行）；**其它 Agent 的历史会话在你选中那个来源时迁移**。DSH 会话格式里没有位置的对话状态（模型思考过程、图片、压缩检查点）一律**如实计数并报告**，绝不伪造
 5. **加密备份**：密码丢失则无法解密（设计使然——请牢记密码）
 6. **快照恢复是离线的、诚实的**：离线引擎无法恢复的条目（快照无整文件备份时的 settings namespace / patch 行、存在 DSH storages 里的 workspace 记录）会如实列为跳过并指向在线回滚；凭据**值**绝不自动改写（只提示人工补录）；无插件基线的旧快照只提示人工核对新增插件
-7. **本地源插件（`link:` / `file:`）随备份打包**：导出时执行 `npm pack` 把本地开发中的插件打成 tarball 一并备份，导入时解包到 `$DSH_HOME/dsh-config-manager/local-plugins/` 后按 `file:` 安装。因此：① 备份体积会随本地插件的体积增大（单插件超过 100 MB 会被跳过并告警，建议先发布到 registry / git 再备份）；② 插件**源码**会进入备份（与「密钥永不进备份」不冲突——密钥仍被排除，这里进的是代码）；③ 打包需要本机有可用的 `npm`，无 npm 时该插件退化为原行为（保留原 spec，换机后仍需手工安装）
+7. **从其它 Agent 导入有两处已知空白**：**Copilot 不支持导入历史会话**（其会话格式在本机无法取证，只导入它的配置）；Cursor 的项目历史要靠它自己的目录 slug 反解，个别项目可能对不上。用**旧版本**导入过的会话请先删掉再重导（同一 id 二次导入会如实报**跳过** `session-id-conflict`，不会合并）
+8. **本地源插件（`link:` / `file:`）随备份打包**：导出时执行 `npm pack` 把本地开发中的插件打成 tarball 一并备份，导入时解包到 `$DSH_HOME/dsh-config-manager/local-plugins/` 后按 `file:` 安装。因此：① 备份体积会随本地插件的体积增大（单插件超过 100 MB 会被跳过并告警，建议先发布到 registry / git 再备份）；② 插件**源码**会进入备份（与「密钥永不进备份」不冲突——密钥仍被排除，这里进的是代码）；③ 打包需要本机有可用的 `npm`，无 npm 时该插件退化为原行为（保留原 spec，换机后仍需手工安装）
 
 ## 💬 反馈与建议
 
@@ -545,6 +612,10 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
   摆到用户面前。此外，为了让 GitHub 的 Contributors 列表如实计入这次贡献，其提交 `1248200` 已通过一次
   **「保留其提交、树取主线」**的合并（`122317b`）成为 `main` 的祖先 —— 该合并**不取其代码**（合并后的树与主线
   逐字节一致），只用于记录署名；因此按 GitHub 的口径这次贡献已被计入（而非 closed 后无痕）。
+- **OMSociety** —— [PR #66](https://github.com/xiajiajun516/dsh-config-manager/pull/66)（合并提交 `4170af4`）：提出并实现了
+  36×36 无底框的 `icon.svg`（issue #61，对齐官方插件图标约定）。反馈自带上游取证（宿主图位 48/36 与 40/30、
+  官方随包发布的图标形态与官方 fixture），PR 里附 16/30/36/48 × 深浅双主题实况图，并对「不换成品牌蓝」写了
+  可复核的理由（后片若同色，深色模式下两层会融成一块、16px 读不出前后关系）。
 - **问题报告**：`zhyx1996`（#38 同步「导出密钥」未生效）、`IPF-Sinon`（#39 凭据 `refs:` 块未被识别，并在自己的 fork
   上完成实现与真机验证）、`zerginlaw`（#43「立即备份」空转却提示成功）—— 这三条报告各自驱动了一个修复。
 

package/icon.svg

@@ -1,11 +1,16 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="DSH Config Manager">
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none" role="img" aria-label="DSH Config Manager">
   <defs>
-    <linearGradient id="tile" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#5B7CFA"/>
-      <stop offset="1" stop-color="#3B3AD1"/>
+    <linearGradient id="cm-snapshot-back" x1="4" y1="4" x2="26.1" y2="26.1" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#45E7A4"/>
+      <stop offset="1" stop-color="#145AF3"/>
+    </linearGradient>
+    <linearGradient id="cm-snapshot-front" x1="9.9" y1="9.9" x2="32" y2="32" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#67C7FE"/>
+      <stop offset="1" stop-color="#324DE2"/>
     </linearGradient>
   </defs>
-  <rect width="512" height="512" rx="112" fill="url(#tile)"/>
-  <path fill="#FFFFFF" d="M196 142 254 226H224V364H168V226H138Z"/>
-  <path fill="#FFFFFF" d="M316 370 258 286H288V148H344V286H374Z"/>
+  <rect x="4" y="4" width="22.1" height="22.1" rx="5.2" fill="url(#cm-snapshot-back)" fill-opacity="0.9"/>
+  <rect x="9.9" y="9.9" width="22.1" height="22.1" rx="5.2" fill="url(#cm-snapshot-front)"/>
+  <path d="M20.95 15.8V26.1" stroke="#FFFFFF" stroke-width="2.9" stroke-linecap="round"/>
+  <path d="M17.27 22.4L20.95 26.1L24.63 22.4" stroke="#FFFFFF" stroke-width="2.9" stroke-linecap="round" stroke-linejoin="round"/>
 </svg>

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

@@ -1,6 +1,22 @@
+/**
+ * agentInstructions 分区 adapter（设计 §3.3 / dsh-agent-instructions 插件）：
+ * 数据源 = ~/.dsh/AGENTS.md（用户全局指令文件，dsh-agent-instructions 固定读取 $DSH_HOME/AGENTS.md，
+ * 注入每个会话的基线指令）。
+ *
+ * 与 skills/agentPresets 的差异：AGENTS.md 位于 $DSH_HOME 根目录，**不能对 homeDir 整目录递归枚举**，
+ * 因此覆写 `listRelPaths()` 返回单文件白名单（而不是目录扫描）。
+ * 仅迁移全局文件；项目级 AGENTS.md / CLAUDE.md 属于各项目仓库，默认不迁（研究报告 §2.2 同策略）。
+ * baseDir = ''（homeDir 根），与 core/backup.ts FILE_BASES 的 '' 基准一致，保证通用快照/回滚路径正确。
+ *
+ * 2026-09 修复（真机报告「总览/导出页变慢」）：本类此前只覆写了 `export()`（单文件），
+ * 却让 v0.1.68 新增的 `preview()` 走了基类的 `collect()` → 对 `baseDir=''` 递归**整个 $DSH_HOME**
+ * （实测 4.8 s / 4016 个文件 / 242 MB，且选择器冒出 21 个假单元：profiles、sessions、attachments…）。
+ * 现在 `export()` 与 `preview()` 都经 `collect()`，但清单来自同一个 `listRelPaths()` 白名单
+ * —— 既快，又保证「预览说的」与「导出做的」逐项一致（这正是基类 preview() 的存在意义）。
+ */
 import { FileCollectionAdapter } from './file-collection.ts';
-import type { FilesSection } from '../schema/types.ts';
-import type { ExportOptions, ExportSection, HostContext } from '../core/types.ts';
+import type { HostContext } from '../core/types.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
 export declare class AgentInstructionsAdapter extends FileCollectionAdapter {
     readonly id: 'agentInstructions';
     readonly displayName: string;
@@ -9,5 +25,14 @@ export declare class AgentInstructionsAdapter extends FileCollectionAdapter {
     readonly baseDir = "";
     /** 用户全局指令文件（相对 homeDir；同时是 schema 端该分区唯一的文件） */
     static readonly FILE = "AGENTS.md";
-    export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    /**
+     * 清单枚举 = **单文件白名单**（覆写基类的目录递归）。
+     *
+     * 为什么必须覆写：`baseDir` 是 ''（AGENTS.md 在 `$DSH_HOME` 根），基类会对整个 home 递归
+     * —— 4.8 s、4016 个文件，并把 `profiles/`/`sessions/` 等无关目录当成该分区的单元。
+     *
+     * 存在性判定优先走 `statSize`（只 stat）；门面未实现（旧宿主 / 测试 mock）时退回读一次文件
+     * （单文件代价可忽略，且 `collect` 之后还要读它）。读不到 → 空清单（与「文件不存在 = 空分区」同语义）。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
 }

package/lib/adapters/agent-instructions.js

@@ -3,13 +3,17 @@
  * 数据源 = ~/.dsh/AGENTS.md（用户全局指令文件，dsh-agent-instructions 固定读取 $DSH_HOME/AGENTS.md，
  * 注入每个会话的基线指令）。
  *
- * 与 skills/agentPresets 的差异：AGENTS.md 位于 $DSH_HOME 根目录，不能对 homeDir 整目录递归枚举，
- * 因此不复用 FileCollectionAdapter 的目录扫描，而是白名单固定收集单文件 AGENTS.md。
+ * 与 skills/agentPresets 的差异：AGENTS.md 位于 $DSH_HOME 根目录，**不能对 homeDir 整目录递归枚举**，
+ * 因此覆写 `listRelPaths()` 返回单文件白名单（而不是目录扫描）。
  * 仅迁移全局文件；项目级 AGENTS.md / CLAUDE.md 属于各项目仓库，默认不迁（研究报告 §2.2 同策略）。
  * baseDir = ''（homeDir 根），与 core/backup.ts FILE_BASES 的 '' 基准一致，保证通用快照/回滚路径正确。
+ *
+ * 2026-09 修复（真机报告「总览/导出页变慢」）：本类此前只覆写了 `export()`（单文件），
+ * 却让 v0.1.68 新增的 `preview()` 走了基类的 `collect()` → 对 `baseDir=''` 递归**整个 $DSH_HOME**
+ * （实测 4.8 s / 4016 个文件 / 242 MB，且选择器冒出 21 个假单元：profiles、sessions、attachments…）。
+ * 现在 `export()` 与 `preview()` 都经 `collect()`，但清单来自同一个 `listRelPaths()` 白名单
+ * —— 既快，又保证「预览说的」与「导出做的」逐项一致（这正是基类 preview() 的存在意义）。
  */
-import { sha256Hex } from '../utils/hashing.js';
-import { msgOf } from '../core/messages.js';
 import { FileCollectionAdapter } from './file-collection.js';
 import { sectionMeta } from '../schema/section-registry.js';
 export class AgentInstructionsAdapter extends FileCollectionAdapter {
@@ -21,28 +25,28 @@ export class AgentInstructionsAdapter extends FileCollectionAdapter {
     baseDir = '';
     /** 用户全局指令文件（相对 homeDir；同时是 schema 端该分区唯一的文件） */
     static FILE = 'AGENTS.md';
-    async export(ctx, _options) {
-        const files = [];
+    /**
+     * 清单枚举 = **单文件白名单**（覆写基类的目录递归）。
+     *
+     * 为什么必须覆写：`baseDir` 是 ''（AGENTS.md 在 `$DSH_HOME` 根），基类会对整个 home 递归
+     * —— 4.8 s、4016 个文件，并把 `profiles/`/`sessions/` 等无关目录当成该分区的单元。
+     *
+     * 存在性判定优先走 `statSize`（只 stat）；门面未实现（旧宿主 / 测试 mock）时退回读一次文件
+     * （单文件代价可忽略，且 `collect` 之后还要读它）。读不到 → 空清单（与「文件不存在 = 空分区」同语义）。
+     */
+    async listRelPaths(ctx) {
+        const empty = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+        const rel = AgentInstructionsAdapter.FILE;
         try {
-            const data = await ctx.fs.readFile(AgentInstructionsAdapter.FILE);
-            files.push({
-                relativePath: AgentInstructionsAdapter.FILE,
-                data,
-                contentHash: sha256Hex(data),
-            });
+            if (ctx.fs.statSize !== undefined) {
+                return (await ctx.fs.statSize(rel)) === null ? empty : { ...empty, paths: [rel] };
+            }
+            await ctx.fs.readFile(rel);
+            return { ...empty, paths: [rel] };
         }
         catch {
-            // 文件不存在 → 空分区（与 skills 目录不存在视为空一致），下方归档 dirEmpty 提示
+            return empty;
         }
-        const warnings = [];
-        if (files.length === 0)
-            warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
-        return {
-            sectionId: this.id,
-            data: { version: 1, files },
-            counts: { files: files.length },
-            warnings,
-        };
     }
 }
 //# sourceMappingURL=agent-instructions.js.map