dsh-config-manager 0.1.67 → 0.1.69

package/README.md

@@ -103,6 +103,9 @@ Several DSH plugins live in this space and they solve different problems — pic
 | 🗂️ | **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) |
 | 🤖 | **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 and, when there is a newer one, hands you a copyable upgrade command (never auto-installs); 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" |
 
 ---
 
@@ -211,6 +214,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)
@@ -369,6 +393,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.
@@ -530,6 +567,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:
@@ -629,6 +677,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

@@ -106,6 +106,9 @@ DSH 生态里这个方向有几个插件，它们解决的问题并不相同—
 | 🧩 | **本地插件随备份迁移** | `link:` / `file:` 安装的本地开发插件会被打包进备份，换机不再丢失 |
 | 🗄️ | **保留策略可配（GFS 分层）** | 「最近 N 份 + 每月留 1 份 + 每年留 1 份」，默认值等价旧行为 |
 | 🤖 | **Agent 工具** | Agent 会话内直接备份 / 快照 / 恢复 / 同步 |
+| 💾 | **磁盘占用体检** | 备份页逐项列出本插件自身占了多少盘（备份 / 快照 / 同步副本 / 缓存 / 暂存），三档回收策略一目了然；**一键清理只碰可重建缓存与过期备份**，快照与同步数据永不在此删除 |
+| ⬆️ | **版本更新检查** | 「关于」页只读探测 npm 上的最新版本，有新版本时给一条可复制的升级命令（绝不自动安装）；离线失败如实显示，不影响其它功能 |
+| 🧭 | **兼容性讲清楚** | 导入前显示「来源 DSH 版本 / 平台 → 本机」，并用**结构化原因**解释评分（跨平台 / 分区缺失 / 版本超前…），而不是只丢一句「部分兼容」 |
 
 ---
 
@@ -188,6 +191,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
@@ -351,6 +375,14 @@ dsh plugin --profile web add dsh-config-manager@latest
 
 **GUI**：设置 → 「备份与迁移」→「快照恢复」tab → 选择快照 → 预览恢复计划（dry-run，零写入）→ 确认执行。
 
+**备份文件与磁盘占用**：「备份与迁移」→「快照恢复」tab 下的**「备份文件」**子页统一管理 `exports/` 里的导出产物
+（手动导出 + 定时备份）——可下载、直接导入恢复、查看内容、删除，并按文件名/备注搜索。
+同页的**「磁盘占用」卡**会逐项列出本插件自己占用的空间（导出备份 / 导入前快照 / 同步配置与 Git 工作副本 /
+市场缓存 / 临时暂存 / 日志 / 事务日志 …），标注每项的回收策略：**可随时重建**（缓存与暂存）、
+**有保留期**（导出产物 7 天、定时备份保留最近 N 个）、**用户数据 / 安全网**（快照与同步，永不自动清理）。
+需要腾空间时点**「立即清理」**：默认只清可重建的缓存与暂存；要回收过期备份文件需显式勾选（并二次确认）。
+**快照与同步数据永远不会被这个按钮删掉**；目录读不到时如实显示「未统计」，不会伪报 0 字节。
+
 ---
 
 ### 🚨 CLI —— DSH 挂了时的第一救急手段
@@ -447,6 +479,21 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
 
 **典型救急流程**（DSH 起不来时）：① `dsh-config-manager reinstall` 先把启动器重装回来（必要时顺带清理），② `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 可调用的模型工具
 
 插件还向宿主注册了 **5 个模型工具**，让 AI agent（DSH 助手会话）能在对话中直接驱动配置运维——与 GUI 共用同一套备份 / 快照 / 同步引擎，无需打开界面：
@@ -545,6 +592,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

@@ -0,0 +1,16 @@
+<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="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 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

package/lib/adapters/file-collection.d.ts

@@ -1,6 +1,7 @@
 import type { MsgFunc } from '../core/messages.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
 import type { FilesSection, SectionId } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, Portability, ValidationResult } from '../core/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, Portability, SectionPreview, ValidationResult } from '../core/types.ts';
 /**
  * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
  *
@@ -66,6 +67,44 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
         warnings: string[];
     } | null>;
     export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    /**
+     * 只读预览（`/export-preview`）：与 `export()` **共用同一个内核**（`collect`），
+     * 只把「读文件内容 + SHA-256」换成 `ctx.fs.statSize`。
+     *
+     * 为什么必须共用：预览说的「会带哪些单元、各多大」就是用户勾选的依据，一旦与真实导出
+     * 分叉，用户会按预览勾选却拿到不同的包（`file-collection.test.ts` 逐项断言两者相等）。
+     */
+    preview(ctx: HostContext, options: ExportOptions): Promise<SectionPreview<FilesSection>>;
+    /**
+     * 分区收集内核（`export` / `preview` 共用）。
+     *
+     * - `mode === 'content'`：读文件内容 + 算 SHA-256（真实导出）；
+     * - `mode === 'size'`：只取字节数（`ctx.fs.statSize`），不解码、不哈希（预览）。
+     *
+     * 两种模式共用**同一套**单元分组、条目级白名单、单分区字节闸门与告警生成 ——
+     * 因此「预览的单元 / 体积 / 告警」与「导出的单元 / 体积 / 告警」逐项相等。
+     *
+     * 返回值里的 `entries` **只含** `relativePath`/`data`/`contentHash` 三个字段：
+     * `FilesSection` 是备份格式的一部分，多带内部字段会被序列化出去；体积走旁路 `sizes`。
+     */
+    private collect;
+    /**
+     * 分区清单枚举（`export` / `preview` 共用；两者必须走同一份清单，否则预览与导出分叉）。
+     *
+     * **单文件分区必须覆写它**：`AgentInstructionsAdapter` 的 `baseDir` 是 ''（AGENTS.md 就放在
+     * `$DSH_HOME` 根），走缺省实现会递归**整个 home** —— 实测 4016 个文件 / 242 MB / 4.8 s，而且
+     * 选择器会把 `profiles/`、`sessions/`、`attachments/` 这些无关目录当成该分区的「单元」。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
+    /**
+     * 读一个成员文件。
+     *
+     * - `content`：读内容并按需算 SHA-256（真实导出）；
+     * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
+     *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
+     *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     */
+    private readMember;
     /** 单元清单（零 I/O：直接由 export 产物归并）。 */
     listUnits(section: ExportSection<FilesSection>): ExportUnit[];
     analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;

package/lib/adapters/file-collection.js

@@ -16,7 +16,7 @@ import { sha256Hex } from '../utils/hashing.js';
 import { isReservedInternalRel, normalizePath } from '../utils/paths.js';
 import { msgOf, zhMsg } from '../core/messages.js';
 import { linkWarnings, listFilesDetailed } from './link-report.js';
-import { defaultUnitId, unitAllowed, unitsFromFiles } from './units.js';
+import { defaultUnitId, unitAllowed, unitsFromEntries, unitsFromFiles } from './units.js';
 import { validateJsonSection } from './json-section.js';
 /**
  * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
@@ -40,6 +40,14 @@ import { validateJsonSection } from './json-section.js';
 export const MAX_FILE_SECTION_BYTES = 256 * 1024 * 1024;
 /** 字节闸门告警里最多列出的单元数（其余折叠成 "(+ N)"，避免大分区把报告撑爆；与 link-report 同口径） */
 const MAX_UNITS_PER_GATE_WARNING = 5;
+/**
+ * 只读预览下文件条目的占位内容（长度 0）。
+ *
+ * 为什么可用空内容：预览产出的 `FilesSection` 只在内存里流转（选择器只需要 `relativePath`
+ * 与体积），**绝不**进 ZIP / 快照 / 导入路径 —— 空内容一旦被误当导出产物，写出去的会是空文件。
+ * 因此 `preview()` 的返回值在类型注释里明确标注「不是格式的一部分」（见 types.ts 的 SectionPreview）。
+ */
+const EMPTY_DATA = new Uint8Array(0);
 /** 告警文案里的体积（人类可读；纯数值格式化，不含用户可见散文） */
 function formatBytes(bytes) {
     if (bytes < 1024)
@@ -95,14 +103,60 @@ export class FileCollectionAdapter {
         return null;
     }
     async export(ctx, options) {
+        const collected = await this.collect(ctx, options, 'content');
+        return {
+            sectionId: this.id,
+            data: { version: 1, files: collected.entries },
+            counts: { files: collected.entries.length },
+            warnings: collected.warnings,
+        };
+    }
+    /**
+     * 只读预览（`/export-preview`）：与 `export()` **共用同一个内核**（`collect`），
+     * 只把「读文件内容 + SHA-256」换成 `ctx.fs.statSize`。
+     *
+     * 为什么必须共用：预览说的「会带哪些单元、各多大」就是用户勾选的依据，一旦与真实导出
+     * 分叉，用户会按预览勾选却拿到不同的包（`file-collection.test.ts` 逐项断言两者相等）。
+     */
+    async preview(ctx, options) {
+        const collected = await this.collect(ctx, options, 'size');
+        return {
+            section: {
+                sectionId: this.id,
+                data: { version: 1, files: collected.entries },
+                counts: { files: collected.entries.length },
+                warnings: collected.warnings,
+            },
+            sizeBytes: collected.totalBytes,
+            items: unitsFromEntries(this.id, collected.sizes, (rel) => this.unitIdOf(rel)),
+            // 本趟 stat 顺带取到的时间（宿主有 statInfo 时才有）：调用方据此省掉第二趟逐文件 stat。
+            ...(collected.statTimes.size > 0 ? { statTimes: collected.statTimes } : {}),
+        };
+    }
+    /**
+     * 分区收集内核（`export` / `preview` 共用）。
+     *
+     * - `mode === 'content'`：读文件内容 + 算 SHA-256（真实导出）；
+     * - `mode === 'size'`：只取字节数（`ctx.fs.statSize`），不解码、不哈希（预览）。
+     *
+     * 两种模式共用**同一套**单元分组、条目级白名单、单分区字节闸门与告警生成 ——
+     * 因此「预览的单元 / 体积 / 告警」与「导出的单元 / 体积 / 告警」逐项相等。
+     *
+     * 返回值里的 `entries` **只含** `relativePath`/`data`/`contentHash` 三个字段：
+     * `FilesSection` 是备份格式的一部分，多带内部字段会被序列化出去；体积走旁路 `sizes`。
+     */
+    async collect(ctx, options, mode) {
         const files = [];
+        const statTimes = new Map();
+        const sizes = [];
         const warnings = [];
         const allow = options.includeItems?.[this.id];
         // issue #37：用「跟随 junction/符号链接」的遍历，并把跟随/跳过的链接写进告警——
         // 此前链接目录及其全部内容被静默排除，备份仍报成功。
+        // 枚举走 listRelPaths 钩子（单文件分区覆写它，避免对 home 根整目录递归）。
         let listing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
         try {
-            listing = await listFilesDetailed(ctx.fs, this.baseDir);
+            listing = await this.listRelPaths(ctx);
         }
         catch {
             // 目录不存在视为空
@@ -148,11 +202,15 @@ export class FileCollectionAdapter {
             const pending = [];
             let unitBytes = 0;
             for (const member of unitEntries.get(unitId) ?? []) {
-                const data = await ctx.fs.readFile(member.rel);
-                unitBytes += data.byteLength;
+                const read = await this.readMember(ctx, member.rel, mode, statTimes);
+                unitBytes += read.sizeBytes;
                 if (unitBytes > room)
                     break;
-                pending.push({ rel: member.rel, file: { relativePath: member.relPath, data, contentHash: sha256Hex(data) } });
+                pending.push({
+                    rel: member.rel,
+                    sizeBytes: read.sizeBytes,
+                    entry: { relativePath: member.relPath, data: read.data, contentHash: read.contentHash },
+                });
             }
             if (unitBytes > room) {
                 droppedUnits.push(unitId);
@@ -160,13 +218,15 @@ export class FileCollectionAdapter {
             }
             usedBytes += unitBytes;
             for (const p of pending)
-                keptByRel.set(p.rel, p.file);
+                keptByRel.set(p.rel, { entry: p.entry, sizeBytes: p.sizeBytes });
         }
         // ③ 按 ① 的顺序落盘（未触发闸门时与改造前的文件顺序逐项一致）
         for (const rel of considered) {
-            const file = keptByRel.get(rel);
-            if (file !== undefined)
-                files.push(file);
+            const kept = keptByRel.get(rel);
+            if (kept === undefined)
+                continue;
+            files.push(kept.entry);
+            sizes.push({ relativePath: kept.entry.relativePath, sizeBytes: kept.sizeBytes });
         }
         // 绝不静默：被整块剔除的单元写进告警（导出报告可见），并给出上限与实际保留量
         if (droppedUnits.length > 0) {
@@ -183,12 +243,43 @@ export class FileCollectionAdapter {
         if (rels.length === 0)
             warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
         warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
-        return {
-            sectionId: this.id,
-            data: { version: 1, files },
-            counts: { files: files.length },
-            warnings,
-        };
+        return { entries: files, sizes, totalBytes: usedBytes, warnings, statTimes };
+    }
+    /**
+     * 分区清单枚举（`export` / `preview` 共用；两者必须走同一份清单，否则预览与导出分叉）。
+     *
+     * **单文件分区必须覆写它**：`AgentInstructionsAdapter` 的 `baseDir` 是 ''（AGENTS.md 就放在
+     * `$DSH_HOME` 根），走缺省实现会递归**整个 home** —— 实测 4016 个文件 / 242 MB / 4.8 s，而且
+     * 选择器会把 `profiles/`、`sessions/`、`attachments/` 这些无关目录当成该分区的「单元」。
+     */
+    async listRelPaths(ctx) {
+        return listFilesDetailed(ctx.fs, this.baseDir);
+    }
+    /**
+     * 读一个成员文件。
+     *
+     * - `content`：读内容并按需算 SHA-256（真实导出）；
+     * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
+     *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
+     *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     */
+    async readMember(ctx, rel, mode, statTimes) {
+        if (mode === 'size') {
+            // 优先 statInfo：一次 stat 同时拿体积与 mtime（sessions 的排序时间顺带就有了，
+            // 省掉 unitActivityTimes 的第二趟逐文件 stat —— 实测会话树 983 个文件）。
+            if (ctx.fs.statInfo !== undefined) {
+                const info = await ctx.fs.statInfo(rel);
+                if (info !== null) {
+                    statTimes?.set(rel, info.mtimeMs);
+                    return { data: EMPTY_DATA, sizeBytes: info.size, contentHash: '' };
+                }
+            }
+            const size = (await ctx.fs.statSize?.(rel)) ?? null;
+            if (size !== null)
+                return { data: EMPTY_DATA, sizeBytes: size, contentHash: '' };
+        }
+        const data = await ctx.fs.readFile(rel);
+        return { data, sizeBytes: data.byteLength, contentHash: mode === 'content' ? sha256Hex(data) : '' };
     }
     /** 单元清单（零 I/O：直接由 export 产物归并）。 */
     listUnits(section) {

package/lib/adapters/plugins.d.ts

@@ -7,7 +7,9 @@ export declare const USER_PATCH_FILE = "cordis.patch.yml";
  * 本地源插件打包钩子（由宿主注入，见 src/index.ts createAdapters）。
  * 返回打包结果（含字节与重写后的 spec）；不注入 = 不做本地源打包（保持旧行为）。
  */
-export type LocalPluginPackHook = (plugins: PluginEntry[], ctx: HostContext) => Promise<PackLocalPluginsResult>;
+export type LocalPluginPackHook = (plugins: PluginEntry[], 
+/** 结构化类型：HostContext 满足它（core 侧刻意不 import adapters 的 HostContext 类型） */
+ctx: Pick<HostContext, 'profile' | 'profileDir'>) => Promise<PackLocalPluginsResult>;
 /** 本地插件 tarball 解包到 homeDir 内的固定缓存目录（相对 $DSH_HOME）。 */
 export declare const LOCAL_TARBALL_CACHE_REL = "dsh-config-manager/local-plugins";
 /** 归档内相对路径 → 缓存目录下的安全文件名（拒绝任何路径穿越）。 */

package/lib/adapters/self.d.ts

@@ -1,5 +1,37 @@
-import type { ExportOptions, ExportSection, HostContext } from '../core/types.ts';
-import type { FilesSection } from '../schema/types.ts';
+/**
+ * self 分区 adapter（插件自身配置，设计「self 分区」）：
+ * 数据源 = $DSH_HOME/dsh-config-manager/ 下的插件自身配置文件（白名单收集，非递归）：
+ *   - sync/sync-config.json     同步通道配置（git repoUrl / webdav url+username；凭据值走 credentials 槽位，不含 secret）
+ *   - sync/sync-autosync.json   自动同步调度配置
+ *   - sync/sync-selection.json  同步分区选择（默认/高级模式 + 勾选分区）
+ *   - sync/ui-prefs.json        插件 UI 偏好（如上次选择的同步通道；从 localStorage 迁入）
+ *   - market/market-config.json 配置市场配置
+ *
+ * 排除项：sync/sync-history.json（执行记录，属数据非配置）、market/cache/（缓存）、
+ * snapshots/（快照）、tmp/ exports/（临时/导出产物）——只备份「配置」，不备份数据。
+ *
+ * 实现：继承 FileCollectionAdapter 复用 analyzeImport/applyItem/validate（幂等 hash 比对、
+ * 快照/回滚路径一致）；**清单来自覆写的 listRelPaths()（白名单），export() 与 preview() 都经
+ * 基类 collect()**（self 目录内存在大量非配置子目录，不能像 skills/sessions 那样整体递归）。
+ *
+ * 为什么必须靠 listRelPaths() 而不是覆写 export() 来收窄（2026-10 真机报告）：
+ * `preview()` / `listRelPaths()` 是后来才加进基类的。本类此前只覆写 export()，于是只读预览
+ * 落到基类的目录递归 —— 把整个 $DSH_HOME/dsh-config-manager（快照、config-snapshots、
+ * sync/work 的 Git 工作副本与远端快照、transactions、exports、遗留 profiles）都当成该分区的
+ * 可勾选单元：实测 2460 个文件 / 11.44 MB，而真实导出只有 6 个文件 / 1936 B；界面上
+ * 「插件自身配置 已选 2460/2460 11.5 MB」即由此而来。同款缺陷已在 agent-instructions.ts 踩过
+ * 并修复（那边 baseDir='' 时更夸张：把整个 home 当该分区）。覆写 listRelPaths() 让两条路径
+ * 共用同一份清单 —— 这正是基类 preview() 存在的意义。
+ *
+ * relativePath 一律是「相对 baseDir」的路径（如 sync/sync-config.json），与
+ * FileCollectionAdapter 的基准目录语义一致：导入时按 path.join(baseDir, rel) 写回
+ * $DSH_HOME/dsh-config-manager/<rel>；ZIP 内位于 self/<rel>。
+ *
+ * 安全不变量：配置文件本身不含凭据值（同步凭据走 DSH credentials 槽位引用），
+ * 且文件类分区不进 SecretScanner（与 pluginFiles/skills 同语义）。
+ */
+import type { HostContext } from '../core/types.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
 import { FileCollectionAdapter } from './file-collection.ts';
 /** self 分区白名单文件（相对 baseDir，即 $DSH_HOME/dsh-config-manager/）。 */
 export declare const SELF_CONFIG_FILES: readonly string[];
@@ -11,10 +43,24 @@ export declare class SelfAdapter extends FileCollectionAdapter {
     /** 插件自身配置目录（相对 homeDir；宿主按 dataDir 解析注入，缺省 dsh-config-manager） */
     readonly baseDir: string;
     constructor(baseDir?: string);
-    /** 白名单收集：只导出配置类文件（存在才收），不递归（排除快照/历史/缓存/临时产物）。
-     *  relativePath 产出相对 baseDir 的路径（与 analyzeImport/applyItem 的 path.join(baseDir, ref) 匹配）。 */
     /** self 的白名单文件彼此独立（同步配置 / 市场配置 / UI 偏好…），不构成 bundle
      *  → 覆写为「逐文件单元」，用户可以只带走其中几项。 */
     protected unitIdOf(relativePath: string): string;
-    export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    /**
+     * 清单枚举 = **白名单文件**（覆写基类的目录递归）。
+     *
+     * 为什么必须覆写：self 目录下并存着插件自身的数据（snapshots/、config-snapshots/、
+     * sync/work/ 的 Git 工作副本与远端快照、transactions/、exports/、遗留 profiles/），
+     * 整目录递归会把它们全部当成「可勾选单元」（实测本机 2460 个文件 / 11.44 MB）。
+     * 覆写后 export()（基类 collect，content 模式）与 preview()（size 模式）拿到**同一份清单**，
+     * 选择器显示的条目/体积与真实导出逐项一致。
+     *
+     * 存在性判定优先 statSize（只 stat；白名单最多 7 个文件）；旧宿主未实现时退回读一次文件
+     * （单文件代价可忽略，且 collect 之后还要读它）。读不到 / 未创建 → 跳过，
+     * 与「文件不存在 = 非白名单命中」同语义（如从未配置市场/同步）。
+     *
+     * 路径一律用 POSIX 分隔符拼：relativePath 是**备份格式的一部分**（ZIP 内为 self/<rel>），
+     * 同时是单元 id（self:<rel>）与 includeItems 的比对键 —— 不能随平台漂移成反斜杠。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
 }