dsh-config-manager 0.1.63 → 0.1.65

package/README.md

@@ -79,7 +79,7 @@ Browse the built-in official market for ready-made configurations (model provide
 | 🔄 | **Remote Sync** | Push/pull portable config via **Git private repo or WebDAV** (secrets do not sync by default; encrypted snapshots can optionally carry encrypted credentials) |
 | ⏰ | **Scheduled backups** | Full backup on a fixed cadence (6h / 12h / 24h / 7d) — set-and-forget, secrets never included |
 | 🛒 | **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 / record which profile the next launch should use |
+| 🗂️ | **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 |
 
@@ -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) |
 
 ---
 
@@ -272,11 +276,18 @@ launched with `dsh --profile <name>`. This page reads and writes that directory
 | Create | Writes the standard three files under `$DSH_HOME/profiles/<name>` (equivalent to the shipped `initProfile`); starting templates: base / web / headless / sdk / sdk-minimal / acp |
 | Rename | Directory move + fixes the manifest name field; the running profile is refused |
 | Delete | **Hard-deletes the whole directory** (including node_modules); deleting the running profile needs an extra checkbox |
-| Next launch | Only records which profile to use next and shows the `dsh --profile <name>` restart command |
-
-> DSH **cannot switch profiles while running** (the profile comes from the launch flag and bundle layers resolve at boot),
-> so this page never touches processes — it records your choice and asks you to restart.
-> Third-party plugins must be installed into that profile separately (`dsh plugin --profile <name> add <pkg>`).
+| Launch this profile | The **switch that actually works**: starts an **independent DSH instance** for that profile (free port picked automatically, browser opened automatically); the running instance and its tasks are untouched. Web-shaped profiles only — non-web ones (e.g. the base template) have no browser UI, so the page shows the terminal command instead of failing silently |
+| Stop instance | While that profile has a running instance, the row button flips from Launch to Stop (the Runtime card also offers one); it asks the process to exit first (grace period) and terminates the process tree only after that, reporting which path was used. **Deleting a profile with a running instance is refused** |
+| No duplicate launches | “Which profiles are running” = the ledger of instances this plugin started ∪ **each instance's own heartbeat** (`<dataDir>/running/<profile>.json`, pid/port only — **never the auth token**). So even a profile you started by hand with `dsh web` will not be launched a second time (you get a clear “already running” message); the instance you are using right now offers no Stop button (that would kill your own session — close that window/terminal, or stop it from the instance that launched it) |
+
+> **Why there is no "set as next launch"** (button and marker removed in 2026-09): DSH has **no "default / next launch
+> profile" state** — the profile comes only from the launch arguments (`dsh <name>` / `--profile <name>`; `dsh web` is a
+> hard-coded alias), so any "which profile to use next" marker has **no consumer at all**: the `dsh web` you type
+> yourself still boots web after a restart. Only two mechanisms really switch profiles: ① this page's "launch this
+> profile" (an extra instance, no interruption, stoppable at any time), ② pointing your launch command/shortcut at
+> `dsh --profile <name>` (ecosystem tools such as dshm and DSH Launcher all spawn instances from an external launcher).
+> Instances started by this plugin are recorded in `<dataDir>/launches.json` (pid/port/log), which is why they can be
+> stopped; third-party plugins must be installed into that profile separately (`dsh plugin --profile <name> add <pkg>`).
 > The tab lives at Settings → "Backup & Migration" → **Profiles**.
 
 ### 📸 Snapshot restore (undo an import)
@@ -331,6 +342,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 +409,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 +426,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,14 +547,34 @@ 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
 
+## 💬 Feedback
+
+Found a bug, a misaligned panel, a button that does nothing — or just have an idea? **All of it is welcome.** UI problems especially: they are the easiest thing to overlook and the part that real usage should decide.
+
+| What you want to say | Where |
+|---|---|
+| 🎨 **UI problem**: misaligned layout, broken styling, dark mode, scaling, a control that does nothing | [UI issue form](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=ui_bug.en.yml) — screenshot + browser version is enough |
+| 🐛 **Something is broken / an error / wrong data** | [Bug report](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=bug_report.en.yml) |
+| ✨ **New feature idea** | [Feature request](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=feature_request.en.yml) |
+| 💬 **Not sure whether it is a bug — just asking** | [Discussions](https://github.com/xiajiajun516/dsh-config-manager/discussions) |
+| 🔒 **Security issue / leaked credential** | [Private security advisory](https://github.com/xiajiajun516/dsh-config-manager/security/advisories/new) (please do not open a public issue) |
+
+**Report straight from the plugin**: Settings → Backup & Migration → **About** → "Issues"; or hit **Copy environment info** on that page — plugin version / DSH version / platform are included, so you can paste it into the issue instead of typing version numbers.
+
+**Every report gets followed up**: a new issue receives an immediate reply and the `needs-triage` label, and progress is visible in the labels (`needs-info` → `confirmed` → `fixed`). Fixed problems end up in [CHANGELOG.md](CHANGELOG.md) under the release that fixed them, tagged with the issue number (e.g. #38 / #43 / #45) — that is where a report finally lands.
+
+> ⚠️ Please search for an existing issue first, and **strip every API key / token / password** — including the ones visible in screenshots and logs.
+
 ## 🙏 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. Because that PR was closed as superseded, **his commits never landed and
-  he does not appear in GitHub's Contributors graph** — so he is credited here.
+  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.

package/README.zh-CN.md

@@ -13,7 +13,7 @@ DSH Config Manager 是一个 DeepSeek Harness 配置备份与迁移插件：一
 - Workspace / AGENTS.md
 
 > DSH 的 profile（`$DSH_HOME/profiles/<name>`）本身**不随备份迁移**（它是「用哪套插件组合启动」的机器本地选择）；
-> 本插件的「档案」页可以列表 / 新建 / 重命名 / 删除它们，并记录「下次启动用哪个」。
+> 本插件的「档案」页可以列表 / 新建 / 重命名 / 删除它们，也可以**用某个档案另起一个独立实例并随时停止它**（真正可用的切换）。
 
 把当前 DeepSeek Harness 环境导出为可移植备份，在另一台电脑上一键恢复；也支持通过 Git / WebDAV 跨机同步（密钥默认不同步，勾选「导出密钥」并加密后可随加密快照迁移）；还能通过内置**配置市场**浏览、一键安装社区分享的现成配置。
 
@@ -81,7 +81,7 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 | 🔄 | **远程同步** | 通过 **Git 私有仓库或 WebDAV** 推送 / 拉取可移植配置（密钥默认不参与同步；加密快照可选携带密文凭据） |
 | ⏰ | **定时全量备份** | 按固定周期（6h / 12h / 24h / 7d）自动全量备份，一劳永逸，密钥永不包含 |
 | 🛒 | **配置市场** | 浏览并一键安装社区分享的配置——供应链警示 + 逐项内容选择（可就地看到改动与高风险分区） |
-| 🗂️ | **档案 Profiles（DSH profile）** | 直接管理 `$DSH_HOME/profiles/<name>`：列表 / 新建（官方模板）/ 重命名 / 物理删除 / 记录「下次启动用哪个」 |
+| 🗂️ | **档案 Profiles（DSH profile）** | 直接管理 `$DSH_HOME/profiles/<name>`：列表 / 新建（官方模板）/ 重命名 / 物理删除 / **启动该档案（独立实例）** / **停止实例**（行内按钮按运行状态在「启动 ↔ 停止」间切换） |
 | 🧩 | **本地插件随备份迁移** | `link:` / `file:` 安装的本地开发插件会被打包进备份，换机不再丢失 |
 | 🗄️ | **保留策略可配（GFS 分层）** | 「最近 N 份 + 每月留 1 份 + 每年留 1 份」，默认值等价旧行为 |
 | 🤖 | **Agent 工具** | Agent 会话内直接备份 / 快照 / 恢复 / 同步 |
@@ -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) |
 
 ---
 
@@ -268,10 +272,17 @@ dsh plugin --profile web add dsh-config-manager@latest
 | 新建 | 在 `$DSH_HOME/profiles/<name>` 写标准三件套（与官方 `initProfile` 等价）；可选起步模板 base / web / headless / sdk / sdk-minimal / acp |
 | 重命名 | 目录级移动 + 同步修正 `package.json` 的 name；当前运行中的档案拒绝重命名 |
 | 删除 | **物理删除整个目录**（含 node_modules）；当前运行中的档案需额外勾选确认 |
-| 下次启动 | 只写「下次启动用哪个」标记 + 给出 `dsh --profile <name>` 重启命令 |
-
-> DSH **无法在运行中切换 profile**（profile 由启动参数决定，bundle 层在启动时解析），因此本页不做进程操作，
-> 只记录选择并提示你手动重启。第三方插件需要在该档案里单独安装（`dsh plugin --profile <name> add <pkg>`）。
+| 启动该档案 | **真正可用的切换**：以该档案另起一个**独立 DSH 实例**（自动挑空闲端口 + 自动打开浏览器），当前实例与正在跑的任务不受影响；只支持 **web 形态**档案：非 web 形态（如 base 模板）没有浏览器界面，点击后给出终端命令而不是静默失败 |
+| 停止实例 | 该档案有实例在跑时，行内「启动」自动变成「停止」（运行状态卡里也有一个）；先请它自己退出（优雅期），超时才结束进程树，并如实告诉你是哪种；**实例运行中拒绝物理删除该档案** |
+| 不会重复启动 | 「哪些档案在跑」= 本插件启动的实例台账 ∪ **每个实例自报的心跳**（`<dataDir>/running/<profile>.json`，只含 pid/端口，**不含认证 token**）→ 哪怕某个档案是你手动 `dsh web` 起来的，本页也不会再启动第二个同名实例（明确提示已在运行）；**当前这个实例本身**不给停止按钮（停自己会把你自己杀掉——请关窗口/终端，或到启动它的那个实例里停止） |
+
+> **为什么没有「设为下次启动」**（2026-09 该按钮与标记一并移除）：DSH **没有「默认 / 下次启动 profile」这种状态** ——
+> profile 只由启动参数决定（`dsh <名>` / `--profile <名>`，`dsh web` 是硬编码别名），任何「下次启动用哪个」的标记
+> **都没有消费者**：你自己敲的 `dsh web` 重启后当然还是 web。真正可用的切换只有两种：① 本页的「启动该档案」
+> 另起一个实例（不打断当前会话，随时可停）；② 把启动命令/快捷方式换成 `dsh --profile <名>`
+> （生态里的 dshm、DSH Launcher 也都是「外部启动器 spawn 实例」这一条路）。
+> 本插件启动的实例记在 `<dataDir>/launches.json`（pid/端口/日志），所以**关得掉**；
+> 第三方插件需要在该档案里单独安装（`dsh plugin --profile <name> add <pkg>`）。
 
 ### 📸 快照恢复（撤销一次导入）
 
@@ -454,13 +465,32 @@ 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，换机后仍需手工安装）
 
+## 💬 反馈与建议
+
+遇到 Bug、界面错位、按钮点了没反应，或者只是有个想法 —— **都欢迎提出来**。界面问题尤其欢迎：这是最容易被自己忽略、也最该由真实使用场景决定的部分。
+
+| 你想说什么 | 去哪儿 |
+|---|---|
+| 🎨 **界面问题**：布局错位、样式异常、深色模式、缩放、按钮无响应 | [UI 问题表单](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=ui_bug.yml)（只要截图 + 浏览器版本） |
+| 🐛 **功能出错 / 报错 / 数据不对** | [Bug 报告](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=bug_report.yml) |
+| ✨ **新功能建议** | [功能建议](https://github.com/xiajiajun516/dsh-config-manager/issues/new?template=feature_request.yml) |
+| 💬 **不确定是不是 Bug，想先问问** | [Discussions](https://github.com/xiajiajun516/dsh-config-manager/discussions) |
+| 🔒 **安全问题 / 密钥泄露** | [私密安全公告](https://github.com/xiajiajun516/dsh-config-manager/security/advisories/new)（请不要开公开 issue） |
+
+**在插件里就地反馈**：设置 → 备份与迁移 → **关于** → 「反馈问题」；或点「关于」里的**复制环境信息**按钮，插件版本 / DSH 版本 / 平台会自动带上，粘进 issue 即可 —— 不用手抄版本号。
+
+**每条都会跟进**：新 issue 会立刻收到一条回复并打上 `needs-triage`，处理进度体现在标签上（`needs-info` → `confirmed` → `fixed`）。修好的问题会出现在 [CHANGELOG.md](CHANGELOG.md) 的对应版本条目里，带 issue 编号（例：#38 / #43 / #45）—— 这就是一条反馈最终的落地记录。
+
+> ⚠️ 提交前请先搜一下是否已有同类 issue，并**抹掉任何 API Key / Token / 密码**（截图和日志里也算）。
+
 ## 🙏 贡献者
 
 - **lux-liang (Jialiang Liang)** —— [PR #44](https://github.com/xiajiajun516/dsh-config-manager/pull/44)：独立修复了 issue #43
   「立即备份」假报成功的问题。其中两点比主线实现更稳，已采纳进 `main`：① `failed` 且宿主错误文本为空 / 全空白时
   回退通用文案（否则会渲染出「备份失败：」这种半截提示）；② 未知 `skipReason` 归一为本地化说明，不把机器 token
-  摆到用户面前。他的提交未合并（该 PR 作为 superseded 关闭），因此**不会出现在 GitHub 的 Contributors 图上** ——
-  名单在此登记。
+  摆到用户面前。此外，为了让 GitHub 的 Contributors 列表如实计入这次贡献，其提交 `1248200` 已通过一次
+  **「保留其提交、树取主线」**的合并（`122317b`）成为 `main` 的祖先 —— 该合并**不取其代码**（合并后的树与主线
+  逐字节一致），只用于记录署名；因此按 GitHub 的口径这次贡献已被计入（而非 closed 后无痕）。
 - **问题报告**：`zhyx1996`（#38 同步「导出密钥」未生效）、`IPF-Sinon`（#39 凭据 `refs:` 块未被识别，并在自己的 fork
   上完成实现与真机验证）、`zerginlaw`（#43「立即备份」空转却提示成功）—— 这三条报告各自驱动了一个修复。
 

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>;
 }