dsh-config-manager 0.1.62 → 0.1.64

package/README.md

@@ -87,17 +87,21 @@ Browse the built-in official market for ready-made configurations (model provide
 
 ## 📸 Screenshots
 
+| Overview | Backups & Snapshots |
+|:---:|:---:|
+| ![Overview](assets/screenshot-overview-en.png) | ![Backups and snapshots](assets/screenshot-backups-en.png) |
+
 | Export | Import Preview |
 |:---:|:---:|
-| ![One-click Export](assets/screenshot-export.png) | ![Import Preview](assets/screenshot-import-preview.png) |
+| ![One-click Export](assets/screenshot-export-en.png) | ![Import Preview](assets/screenshot-import-en.png) |
 
-| Snapshot Restore | Remote Sync |
+| Remote Sync | Configuration Market |
 |:---:|:---:|
-| ![Snapshot Restore](assets/screenshot-snapshots.png) | ![Remote Sync](assets/screenshot-sync.png) |
+| ![Remote Sync](assets/screenshot-sync-en.png) | ![Configuration Market](assets/screenshot-market-en.png) |
 
-| Configuration Market |
+| Profiles (DSH profiles) |
 |:---:|
-| ![Configuration Market](assets/screenshot-market.png) |
+| ![Profiles](assets/screenshot-profiles-en.png) |
 
 ---
 
@@ -331,6 +335,8 @@ dsh-config-manager verify [--id <file|path>] [--json]         # read-only check
                           [--data-dir <dir>]
 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
+                                   [--keep <dir>] [--map old=new]...
 ```
 
 **`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).
@@ -396,7 +402,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), ② `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` 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.
 
 **`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).
 
@@ -413,6 +419,25 @@ Symptoms and the fix:
 dsh-config-manager recover-stale-lock
 ```
 
+**`sessions repair` — when DSH refuses to start over a session log.** DSH validates that each session log sits exactly where its own header says it belongs: `corrupt session log … header id and cwd identify …`, or `duplicate JSONL session id … in multiple project directories`. The plugin cannot help at that point (it only loads *inside* DSH), so this is the one repair path that works while DSH is down. It reads every session's first-frame cwd and moves the session directory under `projectKeyOf(cwd)` — the location DSH expects, derived from the log itself, never guessed.
+
+- **Dry run by default** (zero writes); `--fix` performs the moves. Exit code: dry runs always 0, `--fix` returns 1 if anything failed, conflicted or rolled back.
+- **`--map old=new`** (repeatable) is for cross-machine restores: a matching prefix rewrites the first-frame cwd before relocating the directory (every other frame is copied byte for byte). Targets that already exist are never overwritten.
+- **`--keep <dir>`** resolves duplicate ids: the copy you name is kept, the others are moved into `sessions/.cm-repair-quarantine-<timestamp>/` — moved, never deleted. Without `--keep` duplicates are reported only.
+
+```bash
+# see what would move (no writes at all)
+dsh-config-manager sessions repair
+# apply, mapping a source-machine prefix onto this machine
+dsh-config-manager sessions repair --fix --map 'C:/Users/alice=D:/Work'
+```
+
+If the two machines use **different DSH base paths** (e.g. `/opt/dsh/.dsh` vs a Windows drive path), the backup records the source base path and the import **rebases automatically** every path that lives under it (session cwd, workspace path, …) onto your local one — no mapping to type. User mappings still apply afterwards, so you can override anything.
+
+In the content picker, selecting sessions also selects the workspaces that own them (and unchecking a workspace unchecks its sessions).
+
+Cross-machine restores need no extra step in the GUI: **exporting sessions now carries the workspaces that own them**, and the path mapping you fill in the import wizard rewrites both the workspace paths and the sessions' first-frame cwd (relocating the directories accordingly) before the sessions are attached to those workspaces.
+
 **Plugins installed but the backup doesn't see them?** Check **Settings → DSH Config Manager → About**: it now shows which directory / profile the plugin list was read from, and how many plugins were detected. The list comes from `$DSH_HOME/profiles/<profile>/package.json` → `dependencies` (plus anything declared in `dsh.profile.bundles` that is not a dependency), where `<profile>` is resolved as `config.profile` → `--profile` → `web`. If the shown path is not the profile you installed into (Desktop builds may use a different profile or a different `DSH_HOME`), that is the cause — align `--profile` / `DSH_HOME` with it.
 
 ### 🌐 Behind a proxy? (GitHub login / sync)
@@ -515,6 +540,20 @@ Yes. The import wizard asks for the export-time encryption password and verifies
 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
 
+## 🙏 Contributors
+
+- **lux-liang (Jialiang Liang)** — [PR #44](https://github.com/xiajiajun516/dsh-config-manager/pull/44): independently fixed the
+  issue #43 "Back up now" false-success bug. Two details from that patch were more robust than the mainline implementation and
+  have been adopted into `main`: (1) when `failed` comes back with an empty / whitespace-only error text, fall back to the
+  generic message instead of rendering a dangling "Backup failed:"; (2) an unknown `skipReason` is mapped to a localized
+  message rather than echoing the raw machine token. In addition, so that GitHub's contributor list records the
+  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.
+- **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.
+
 > Maintainers & developers: see [DEVELOPERS.md](DEVELOPERS.md) for build, testing, auto-publishing and full technical notes.
 
 ---

package/README.zh-CN.md

@@ -90,17 +90,21 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 
 ## 📸 功能截图
 
+| 总览 | 备份与快照 |
+|:---:|:---:|
+| ![总览](assets/screenshot-overview-zh.png) | ![备份与快照](assets/screenshot-backups-zh.png) |
+
 | 导出备份 | 导入预览 |
 |:---:|:---:|
-| ![一键导出](assets/screenshot-export.png) | ![导入预览](assets/screenshot-import-preview.png) |
+| ![一键导出](assets/screenshot-export-zh.png) | ![导入预览](assets/screenshot-import-zh.png) |
 
-| 快照恢复 | 远程同步 |
+| 远程同步 | 配置市场 |
 |:---:|:---:|
-| ![快照恢复](assets/screenshot-snapshots.png) | ![远程同步](assets/screenshot-sync.png) |
+| ![远程同步](assets/screenshot-sync-zh.png) | ![配置市场](assets/screenshot-market-zh.png) |
 
-| 配置市场 |
+| 档案 Profiles |
 |:---:|
-| ![配置市场](assets/screenshot-market.png) |
+| ![档案 Profiles](assets/screenshot-profiles-zh.png) |
 
 ---
 
@@ -454,6 +458,17 @@ dsh-config-manager backup --sections skills,self          # 收窄范围
 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，换机后仍需手工安装）
 
+## 🙏 贡献者
+
+- **lux-liang (Jialiang Liang)** —— [PR #44](https://github.com/xiajiajun516/dsh-config-manager/pull/44)：独立修复了 issue #43
+  「立即备份」假报成功的问题。其中两点比主线实现更稳，已采纳进 `main`：① `failed` 且宿主错误文本为空 / 全空白时
+  回退通用文案（否则会渲染出「备份失败：」这种半截提示）；② 未知 `skipReason` 归一为本地化说明，不把机器 token
+  摆到用户面前。此外，为了让 GitHub 的 Contributors 列表如实计入这次贡献，其提交 `1248200` 已通过一次
+  **「保留其提交、树取主线」**的合并（`122317b`）成为 `main` 的祖先 —— 该合并**不取其代码**（合并后的树与主线
+  逐字节一致），只用于记录署名；因此按 GitHub 的口径这次贡献已被计入（而非 closed 后无痕）。
+- **问题报告**：`zhyx1996`（#38 同步「导出密钥」未生效）、`IPF-Sinon`（#39 凭据 `refs:` 块未被识别，并在自己的 fork
+  上完成实现与真机验证）、`zerginlaw`（#43「立即备份」空转却提示成功）—— 这三条报告各自驱动了一个修复。
+
 > 维护者与开发者：构建、测试、自动发布与完整技术说明见 [DEVELOPERS.md](DEVELOPERS.md)。
 
 ---

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

@@ -3,9 +3,9 @@ import type { FilesSection } from '../schema/types.ts';
 import type { ExportOptions, ExportSection, HostContext } from '../core/types.ts';
 export declare class AgentInstructionsAdapter extends FileCollectionAdapter {
     readonly id: 'agentInstructions';
-    readonly displayName = "Agent Instructions";
-    readonly defaultIncluded = true;
-    readonly portability: 'portable';
+    readonly displayName: string;
+    readonly defaultIncluded: boolean;
+    readonly portability: import("../schema/section-registry.ts").SectionPortability;
     readonly baseDir = "";
     /** 用户全局指令文件（相对 homeDir；同时是 schema 端该分区唯一的文件） */
     static readonly FILE = "AGENTS.md";

package/lib/adapters/agent-instructions.js

@@ -11,11 +11,13 @@
 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 {
     id = 'agentInstructions';
-    displayName = 'Agent Instructions';
-    defaultIncluded = true;
-    portability = 'portable';
+    // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
+    displayName = sectionMeta('agentInstructions').displayName;
+    defaultIncluded = sectionMeta('agentInstructions').defaultIncluded;
+    portability = sectionMeta('agentInstructions').portability;
     baseDir = '';
     /** 用户全局指令文件（相对 homeDir；同时是 schema 端该分区唯一的文件） */
     static FILE = 'AGENTS.md';

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

@@ -6,8 +6,8 @@
 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 displayName: string;
+    readonly defaultIncluded: boolean;
+    readonly portability: import("../schema/section-registry.ts").SectionPortability;
     readonly baseDir = ".agent-presets";
 }

package/lib/adapters/agent-presets.js

@@ -4,11 +4,13 @@
  * system 预设（安装目录）只记引用不复制（本 adapter 只读用户目录）。
  */
 import { FileCollectionAdapter } from './file-collection.js';
+import { sectionMeta } from '../schema/section-registry.js';
 export class AgentPresetsAdapter extends FileCollectionAdapter {
     id = 'agentPresets';
-    displayName = 'Agent Presets';
-    defaultIncluded = true;
-    portability = 'portable';
+    // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
+    displayName = sectionMeta('agentPresets').displayName;
+    defaultIncluded = sectionMeta('agentPresets').defaultIncluded;
+    portability = sectionMeta('agentPresets').portability;
     baseDir = '.agent-presets';
 }
 //# sourceMappingURL=agent-presets.js.map

package/lib/adapters/credentials.d.ts

@@ -25,9 +25,9 @@ export interface CredentialsAdapterOptions {
 }
 export declare class CredentialsAdapter implements ConfigAdapter<CredentialsSection> {
     readonly id: 'credentialsStatus';
-    readonly displayName = "Credentials";
-    readonly defaultIncluded = true;
-    readonly portability: 'deviceSpecific';
+    readonly displayName: string;
+    readonly defaultIncluded: boolean;
+    readonly portability: import("../schema/section-registry.ts").SectionPortability;
     private readonly refs;
     constructor(options?: CredentialsAdapterOptions);
     export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<CredentialsSection>>;

package/lib/adapters/credentials.js

@@ -1,5 +1,7 @@
 import { msgOf, zhMsg } from '../core/messages.js';
 import { resolveNamespaces } from './settings.js';
+import { sectionMeta } from '../schema/section-registry.js';
+import { validateJsonSection } from './json-section.js';
 /** 缺省 ref 收集：遍历 settings namespace，收集 llm apiKeyEnv / providers[].apiKeyEnv，
  * 以及 secrets 标记中「引用类字段」（apiKeyEnv/tokenEnv…）的字段值。
  * 注意 secrets[].path[0] 是 settings 文档内的字段路径（如 ['apiKey']），本身不是凭据 ref（设计 §4.2），
@@ -47,9 +49,10 @@ export function defaultCredentialRefs(namespaces) {
 }
 export class CredentialsAdapter {
     id = 'credentialsStatus';
-    displayName = 'Credentials';
-    defaultIncluded = true;
-    portability = 'deviceSpecific';
+    // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
+    displayName = sectionMeta('credentialsStatus').displayName;
+    defaultIncluded = sectionMeta('credentialsStatus').defaultIncluded;
+    portability = sectionMeta('credentialsStatus').portability;
     refs;
     constructor(options = {}) {
         this.refs = options.refs ?? defaultCredentialRefs(options.namespaces ?? []);
@@ -95,28 +98,22 @@ export class CredentialsAdapter {
         return { ok: true };
     }
     async validate(data, msg = zhMsg) {
-        const issues = [];
-        if (data === null || typeof data !== 'object') {
-            return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.object', { subject: 'credentials' }), severity: 'error' }] };
-        }
-        if (data.version !== 1) {
-            issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
-        }
-        if (!Array.isArray(data.credentials)) {
-            issues.push({ path: 'credentials', message: msg('adapter.validate.array', { subject: 'credentials' }), severity: 'error' });
-        }
-        else {
-            for (const c of data.credentials) {
-                if (c === null || typeof c !== 'object' || typeof c.ref !== 'string' || c.ref === '') {
-                    issues.push({ path: 'credentials[]', message: msg('adapter.validate.credentialRef'), severity: 'error' });
-                }
-                if (c.hasValue === true) {
-                    // 安全不变量：普通导出恒不携带值；若备份声称有值，视为结构异常
-                    issues.push({ path: `credentials.${c.ref}.hasValue`, message: msg('adapter.validate.hasValueFalse'), severity: 'error' });
+        return validateJsonSection('credentialsStatus', data, msg, (section, issues) => {
+            if (!Array.isArray(section.credentials)) {
+                issues.push({ path: 'credentials', message: msg('adapter.validate.array', { subject: 'credentials' }), severity: 'error' });
+            }
+            else {
+                for (const c of section.credentials) {
+                    if (c === null || typeof c !== 'object' || typeof c.ref !== 'string' || c.ref === '') {
+                        issues.push({ path: 'credentials[]', message: msg('adapter.validate.credentialRef'), severity: 'error' });
+                    }
+                    if (c.hasValue === true) {
+                        // 安全不变量：普通导出恒不携带值；若备份声称有值，视为结构异常
+                        issues.push({ path: `credentials.${c.ref}.hasValue`, message: msg('adapter.validate.hasValueFalse'), severity: 'error' });
+                    }
                 }
             }
-        }
-        return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+        }, 'credentials');
     }
 }
 //# sourceMappingURL=credentials.js.map

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

@@ -1,7 +1,29 @@
 import type { MsgFunc } from '../core/messages.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';
+/**
+ * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
+ *
+ * 取值依据（不是随手拍的数）：
+ *  1) **对称性** —— 导入侧对上传的备份包有硬上限 256 MiB（MAX_UPLOAD_BYTES，src/index.ts 与
+ *     src/routes/kit.ts 的上传路径）；导出侧此前**没有任何体积约束**，于是会出现「导出成功、
+ *     传不回来」（审计 core-flow F-12 / sync#F-12）。取同一个 256 MiB 作**单分区**上限：
+ *     任何单个分区都落在导入侧上传路径能收的范围内。
+ *  2) **内存峰值** —— 导出时文件内容以完整 Uint8Array 驻留内存（ZIP 组装前全量在内存里），同步通道
+ *     还要再写一份。闸门把「单分区常驻」钳在 256 MiB 以内（峰值 ≈ 上限 + 正在读的那个单元），
+ *     不再是「会话附件多大就多吃多少」。
+ *  3) **与既有同类上限同量级** —— MAX_MARKET_ZIP_BYTES = 64 MiB、DEFAULT_MAX_JSON_BYTES = 64 MiB、
+ *     MAX_LOCAL_TARBALL_BYTES = 100 MiB、MAX_PATCH_FILE_BYTES = 2 MiB。文件类分区装的是**用户真实
+ *     文件**，所以取「导入侧能收」的 256 MiB，而不是为省内存随意调小（那会平白少带用户数据）。
+ *  4) **为什么按分区而不是按整包** —— 整包体积由用户勾选跨分区决定；闸门要能给出「哪些分区、哪些
+ *     单元没进去」的可执行信息，落在分区/单元层才可解释。
+ *
+ * 超限时**绝不静默**：被整块剔除的单元清单进 ExportSection.warnings（导出报告可见）。
+ */
+export declare const MAX_FILE_SECTION_BYTES: number;
 export declare abstract class FileCollectionAdapter implements ConfigAdapter<FilesSection> {
+    /** 文件集合：`relativePath` 是身份而非配置 → 永不被导入时的前缀映射改写（见 ConfigAdapter.fileCollection） */
+    readonly fileCollection = true;
     abstract readonly id: SectionId;
     abstract readonly displayName: string;
     abstract readonly defaultIncluded: boolean;
@@ -18,6 +40,14 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
     protected unitIdOf(relativePath: string): string;
     /** 清单里的路径 → 相对 baseDir 的路径（baseDir 为空表示整目录即根）。 */
     protected relPathOf(rel: string): string;
+    /**
+     * 单分区累计字节上限（缺省 MAX_FILE_SECTION_BYTES = 256 MiB，见该常量注释）。
+     *
+     * 生产代码不覆写；留成受保护方法只为让测试能构造「超限」场景（真实阈值 256 MiB 无法在单测里
+     * 造出来而不吃掉 256 MiB 内存）。若要给用户配置入口，应走 ExportOptions（src/core/types.ts），
+     * 而不是在子类里飘一个隐式默认值。
+     */
+    protected sectionByteLimit(): number;
     /**
      * 条目级选择（Phase 1）：只导出白名单命中的单元。
      *
@@ -40,5 +70,18 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
     listUnits(section: ExportSection<FilesSection>): ExportUnit[];
     analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+    /**
+     * 结构校验（5 个文件类分区共用：skills / agentPresets / agentInstructions / sessions / self）。
+     *
+     * **整段样板都接入共享骨架 `validateJsonSection`** —— t7 接入 version 守卫与形状检查收尾，t11 接入
+     * object 守卫；dataVersion 由注册表按 `this.id` 派生，等价于此前的字面量 `!== 1`
+     * （SECTION_DATA_VERSION = 1）。本类里已无手写样板。
+     *
+     * object 守卫的**文案**为什么还要参数：文件类分区历史上用的是**专用消息键**
+     * `adapter.validate.fileSection`（'文件分区数据必须是对象'，不含 `{subject}` 占位符），与骨架缺省的
+     * `adapter.validate.object` + `{subject}` 是**键**级差异 —— 第 5 参 subject 补不了它。t11 给骨架加了
+     * 可选第 6 参 `objectMessageKey`，这里传专用键：5 个分区的用户可见报错文案与改造前**逐字相同**，
+     * 同时不放任何手写样板。等价由 src/adapters/file-collection.test.ts 与 outputs/t7-equiv/ 的差分脚本钉住。
+     */
     validate(data: FilesSection, msg?: MsgFunc): Promise<ValidationResult>;
 }

package/lib/adapters/file-collection.js

@@ -6,6 +6,10 @@
  *
  * 文件内容以真实文件进入 ZIP（custom/skills/… 等前缀由 exporter 按 SECTION_FILE_PREFIXES 处理）。
  * 幂等：相对路径 + 内容 SHA-256 hash 比对（重复导入 → Skip）。
+ *
+ * 导出的**单分区字节闸门**（审计 core-flow F-12 / sync#F-12）：累计到 MAX_FILE_SECTION_BYTES 后，
+ * 放不下的单元**整块**剔除并写进告警（见 export()）。覆盖 skills / agentPresets / sessions；
+ * agentInstructions（单文件 AGENTS.md）与 self（白名单配置小文件）各自覆写 export，不在本闸门射程内。
  */
 import path from 'node:path';
 import { sha256Hex } from '../utils/hashing.js';
@@ -13,7 +17,40 @@ 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 { validateJsonSection } from './json-section.js';
+/**
+ * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
+ *
+ * 取值依据（不是随手拍的数）：
+ *  1) **对称性** —— 导入侧对上传的备份包有硬上限 256 MiB（MAX_UPLOAD_BYTES，src/index.ts 与
+ *     src/routes/kit.ts 的上传路径）；导出侧此前**没有任何体积约束**，于是会出现「导出成功、
+ *     传不回来」（审计 core-flow F-12 / sync#F-12）。取同一个 256 MiB 作**单分区**上限：
+ *     任何单个分区都落在导入侧上传路径能收的范围内。
+ *  2) **内存峰值** —— 导出时文件内容以完整 Uint8Array 驻留内存（ZIP 组装前全量在内存里），同步通道
+ *     还要再写一份。闸门把「单分区常驻」钳在 256 MiB 以内（峰值 ≈ 上限 + 正在读的那个单元），
+ *     不再是「会话附件多大就多吃多少」。
+ *  3) **与既有同类上限同量级** —— MAX_MARKET_ZIP_BYTES = 64 MiB、DEFAULT_MAX_JSON_BYTES = 64 MiB、
+ *     MAX_LOCAL_TARBALL_BYTES = 100 MiB、MAX_PATCH_FILE_BYTES = 2 MiB。文件类分区装的是**用户真实
+ *     文件**，所以取「导入侧能收」的 256 MiB，而不是为省内存随意调小（那会平白少带用户数据）。
+ *  4) **为什么按分区而不是按整包** —— 整包体积由用户勾选跨分区决定；闸门要能给出「哪些分区、哪些
+ *     单元没进去」的可执行信息，落在分区/单元层才可解释。
+ *
+ * 超限时**绝不静默**：被整块剔除的单元清单进 ExportSection.warnings（导出报告可见）。
+ */
+export const MAX_FILE_SECTION_BYTES = 256 * 1024 * 1024;
+/** 字节闸门告警里最多列出的单元数（其余折叠成 "(+ N)"，避免大分区把报告撑爆；与 link-report 同口径） */
+const MAX_UNITS_PER_GATE_WARNING = 5;
+/** 告警文案里的体积（人类可读；纯数值格式化，不含用户可见散文） */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
 export class FileCollectionAdapter {
+    /** 文件集合：`relativePath` 是身份而非配置 → 永不被导入时的前缀映射改写（见 ConfigAdapter.fileCollection） */
+    fileCollection = true;
     /**
      * 最小可拆单元的 id（相对 baseDir 的路径）。
      *
@@ -31,6 +68,16 @@ export class FileCollectionAdapter {
         const prefix = this.baseDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         return rel.replace(new RegExp('^' + prefix + '[\\\\/]'), '');
     }
+    /**
+     * 单分区累计字节上限（缺省 MAX_FILE_SECTION_BYTES = 256 MiB，见该常量注释）。
+     *
+     * 生产代码不覆写；留成受保护方法只为让测试能构造「超限」场景（真实阈值 256 MiB 无法在单测里
+     * 造出来而不吃掉 256 MiB 内存）。若要给用户配置入口，应走 ExportOptions（src/core/types.ts），
+     * 而不是在子类里飘一个隐式默认值。
+     */
+    sectionByteLimit() {
+        return MAX_FILE_SECTION_BYTES;
+    }
     /**
      * 条目级选择（Phase 1）：只导出白名单命中的单元。
      *
@@ -66,6 +113,12 @@ export class FileCollectionAdapter {
         if (restricted !== null)
             warnings.push(...restricted.warnings);
         const keep = restricted?.keep ?? null;
+        // ① 先按「单元」分组（零 I/O：只看路径）。单元的成员文件**不保证**在遍历结果里连续，
+        //    必须整组一起判定，否则同一单元会被拦腰劈开（半个技能目录 / 半个会话目录）。
+        //    `considered` 保序记录，收尾按它还原改造前的文件顺序（未触发闸门时逐项一致）。
+        const considered = [];
+        const unitOrder = [];
+        const unitEntries = new Map();
         for (const rel of rels) {
             const relPath = this.relPathOf(rel);
             const unitId = this.unitIdOf(relPath);
@@ -73,8 +126,59 @@ export class FileCollectionAdapter {
                 continue;
             if (!unitAllowed(allow, `${this.id}:${unitId}`))
                 continue;
-            const data = await ctx.fs.readFile(rel);
-            files.push({ relativePath: relPath, data, contentHash: sha256Hex(data) });
+            let members = unitEntries.get(unitId);
+            if (members === undefined) {
+                members = [];
+                unitEntries.set(unitId, members);
+                unitOrder.push(unitId);
+            }
+            members.push({ rel, relPath });
+            considered.push(rel);
+        }
+        // ② 逐单元读取 + 累计字节闸门（审计 core-flow F-12 / sync#F-12）。超出 sectionByteLimit() 的
+        //    单元**整块**不进备份（仓库语义：单元不可拆分 —— 宁可少带，不可半带）；一旦判定该单元放不下，
+        //    它的剩余文件不再读盘（省 I/O，也不为「统计精确」多吃内存）。放不下的单元跳过后**继续尝试
+        //    后面的单元**：一个巨型会话不该把它之后的所有内容一起带走（后面的小单元仍可能入选）。
+        const limit = this.sectionByteLimit();
+        let usedBytes = 0;
+        const droppedUnits = [];
+        const keptByRel = new Map();
+        for (const unitId of unitOrder) {
+            const room = limit - usedBytes;
+            const pending = [];
+            let unitBytes = 0;
+            for (const member of unitEntries.get(unitId) ?? []) {
+                const data = await ctx.fs.readFile(member.rel);
+                unitBytes += data.byteLength;
+                if (unitBytes > room)
+                    break;
+                pending.push({ rel: member.rel, file: { relativePath: member.relPath, data, contentHash: sha256Hex(data) } });
+            }
+            if (unitBytes > room) {
+                droppedUnits.push(unitId);
+                continue;
+            }
+            usedBytes += unitBytes;
+            for (const p of pending)
+                keptByRel.set(p.rel, p.file);
+        }
+        // ③ 按 ① 的顺序落盘（未触发闸门时与改造前的文件顺序逐项一致）
+        for (const rel of considered) {
+            const file = keptByRel.get(rel);
+            if (file !== undefined)
+                files.push(file);
+        }
+        // 绝不静默：被整块剔除的单元写进告警（导出报告可见），并给出上限与实际保留量
+        if (droppedUnits.length > 0) {
+            const shown = droppedUnits.slice(0, MAX_UNITS_PER_GATE_WARNING);
+            const rest = droppedUnits.length - shown.length;
+            warnings.push(msgOf(ctx)('adapter.fileSectionByteLimit', {
+                type: this.displayName,
+                limit: formatBytes(limit),
+                kept: formatBytes(usedBytes),
+                count: String(droppedUnits.length),
+                detail: (rest > 0 ? [...shown, `(+ ${rest})`] : shown).join(', '),
+            }));
         }
         if (rels.length === 0)
             warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
@@ -152,25 +256,33 @@ export class FileCollectionAdapter {
         await ctx.target.fs.writeFile(path.join(this.baseDir, ref), file.data);
         return { ok: true };
     }
+    /**
+     * 结构校验（5 个文件类分区共用：skills / agentPresets / agentInstructions / sessions / self）。
+     *
+     * **整段样板都接入共享骨架 `validateJsonSection`** —— t7 接入 version 守卫与形状检查收尾，t11 接入
+     * object 守卫；dataVersion 由注册表按 `this.id` 派生，等价于此前的字面量 `!== 1`
+     * （SECTION_DATA_VERSION = 1）。本类里已无手写样板。
+     *
+     * object 守卫的**文案**为什么还要参数：文件类分区历史上用的是**专用消息键**
+     * `adapter.validate.fileSection`（'文件分区数据必须是对象'，不含 `{subject}` 占位符），与骨架缺省的
+     * `adapter.validate.object` + `{subject}` 是**键**级差异 —— 第 5 参 subject 补不了它。t11 给骨架加了
+     * 可选第 6 参 `objectMessageKey`，这里传专用键：5 个分区的用户可见报错文案与改造前**逐字相同**，
+     * 同时不放任何手写样板。等价由 src/adapters/file-collection.test.ts 与 outputs/t7-equiv/ 的差分脚本钉住。
+     */
     async validate(data, msg = zhMsg) {
-        const issues = [];
-        if (data === null || typeof data !== 'object') {
-            return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.fileSection'), severity: 'error' }] };
-        }
-        if (data.version !== 1) {
-            issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
-        }
-        if (!Array.isArray(data.files)) {
-            issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
-        }
-        else {
-            for (const f of data.files) {
-                if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
-                    issues.push({ path: 'files[]', message: msg('adapter.validate.fileRelativePath'), severity: 'error' });
+        // 第 5 参 subject 传 this.id 即骨架缺省语义（专用键不含 {subject}，取值不影响输出）
+        return validateJsonSection(this.id, data, msg, (section, issues) => {
+            if (!Array.isArray(section.files)) {
+                issues.push({ path: 'files', message: msg('adapter.validate.array', { subject: 'files' }), severity: 'error' });
+            }
+            else {
+                for (const f of section.files) {
+                    if (f === null || typeof f !== 'object' || typeof f.relativePath !== 'string' || f.relativePath === '') {
+                        issues.push({ path: 'files[]', message: msg('adapter.validate.fileRelativePath'), severity: 'error' });
+                    }
                 }
             }
-        }
-        return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+        }, this.id, 'adapter.validate.fileSection');
     }
 }
 //# sourceMappingURL=file-collection.js.map

package/lib/adapters/index.d.ts

@@ -55,3 +55,4 @@ export { PluginFilesAdapter, DEFAULT_PLUGIN_FILE_WHITELIST } from './plugin-file
 export { SessionsAdapter } from './sessions.ts';
 export { SelfAdapter, SELF_CONFIG_FILES } from './self.ts';
 export { FileCollectionAdapter } from './file-collection.ts';
+export { validateJsonSection, type SectionIssues } from './json-section.ts';

package/lib/adapters/index.js

@@ -52,4 +52,15 @@ export { PluginFilesAdapter, DEFAULT_PLUGIN_FILE_WHITELIST } from './plugin-file
 export { SessionsAdapter } from './sessions.js';
 export { SelfAdapter, SELF_CONFIG_FILES } from './self.js';
 export { FileCollectionAdapter } from './file-collection.js';
+/* JSON 分区共享校验骨架（本导出是其接入点）。收敛轨迹：
+ *  · t31 抽出骨架，settings / ui / providers / plugins / mcp / prompts / credentials /
+ *    pluginFiles 八个分区的样板并入；
+ *  · t7 接上 workspaces.ts 与 file-collection.ts 基类的 version 守卫 + 形状检查收尾；
+ *  · t11 给骨架加了可选第 6 参 `objectMessageKey`（object 错误的文案键，缺省
+ *    `adapter.validate.object`），file-collection 的 object 守卫也并入并沿用文件类分区原专用键
+ *    `adapter.validate.fileSection`，故 5 个文件类分区的用户可见报错文案逐字不变。
+ * 现状：**9 个分区全部走共享骨架**（settings / ui / providers / plugins / mcp / prompts /
+ * credentialsStatus / pluginFiles / workspaces），文件类基类（skills / agentPresets /
+ * agentInstructions / sessions / self）同样走它 —— src/adapters 下不再有任何手写 validate 样板。 */
+export { validateJsonSection } from './json-section.js';
 //# sourceMappingURL=index.js.map

package/lib/adapters/json-section.d.ts

@@ -0,0 +1,32 @@
+import type { SectionId } from '../schema/types.ts';
+import type { MsgFunc, zh } from '../core/messages.ts';
+import type { ValidationResult } from '../core/types.ts';
+/** 校验问题列表（各 adapter 的形状检查直接 push 到这里，与历史 `issues` 数组同一形状）。 */
+export type SectionIssues = ValidationResult['issues'];
+/**
+ * JSON 分区通用结构校验骨架。
+ *
+ * 执行顺序（与改造前逐字一致，保证行为等价）：
+ *  1. object 守卫：非对象 → **直接返回**单条 `objectMessageKey` 错误（缺省 `adapter.validate.object`；后续检查不再执行）；
+ *  2. version 守卫：`version !== sectionMeta(sectionId).dataVersion` → push 一条 `version` 错误，
+ *     **不提前返回**（继续做形状检查，与历史实现一致）；
+ *  3. `shape` 回调：分区特有的载荷形状检查（可选）。
+ *
+ * @param sectionId 分区 id —— 同时是 object 错误的默认 subject 与 dataVersion 的查表键
+ * @param data 反序列化后的分区载荷（来自不可信备份 → 必须按 unknown 处理）
+ * @param msg 文案翻译器（adapter 的 `validate(data, msg = zhMsg)` 原样传入）
+ * @param shape 分区特有的形状检查（在 version 守卫之后调用）
+ * @param subject object 错误里的显示名；缺省 = sectionId。历史上 credentials 用的是
+ *   `'credentials'`（而非分区 id `credentialsStatus`），此参数为保留该原文案而存在 ——
+ *   改文案属独立的行为变更，不在本任务射程内。
+ * @param objectMessageKey object 错误的**消息键**（t11 新增，可选）；缺省 `adapter.validate.object`
+ *   （`'{subject} 数据必须是对象'`）。为什么需要它：文件类分区历史上用的是专用键
+ *   `adapter.validate.fileSection`（`'文件分区数据必须是对象'`，**不含** `{subject}` 占位符），
+ *   那是**键**级差异 —— `subject` 参数补不了它（把 subject 拼成"文件分区"后中文模板仍多一个空格），
+ *   而硬换键会让 skills / agentPresets / agentInstructions / sessions / self 五个分区的用户可见
+ *   报错文案一起变。有了这个可选键，那处也能并入骨架而文案逐字不变。
+ *   键必须存在于 `src/core/messages.ts` 目录（`MsgFunc` 形参是 string，编译器只能校验到键名集合）。
+ */
+export declare function validateJsonSection<S extends {
+    version?: unknown;
+}>(sectionId: SectionId, data: unknown, msg: MsgFunc, shape?: (section: S, issues: SectionIssues) => void, subject?: string, objectMessageKey?: keyof typeof zh): ValidationResult;