dsh-config-manager 0.1.47 → 0.1.49

package/README.md

@@ -81,6 +81,7 @@ Browse the built-in official market for ready-made configurations (model provide
 | 🛒 | **Config Marketplace** | Browse & one-click install community configs — supply-chain warnings + per-section approval |
 | 🗂️ | **Profiles** | Save multiple setups (Work / Personal) and switch anytime |
 | 🌐 | **Bilingual UI** | Interface, reports and error details follow the DSH app language (中文 / English) |
+| 🤖 | **Agent tools** | Backup / snapshot / restore / sync right from an agent session |
 
 ---
 
@@ -326,6 +327,20 @@ Every overwrite/delete is first copied to `<snapshotDir>/pre-restore/` so you ca
 
 **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.
 
+### 🤖 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:
+
+| Tool | What it does |
+|---|---|
+| `config_backup` | Full backup of DSH config to the local `exports` dir — **no secrets by default**; pass `password` for an encrypted backup. Returns ZIP name / size / included sections / encryption state |
+| `config_list_snapshots` | List local rollback snapshots (id / created / source / status / entry count) for use with `config_restore` |
+| `config_restore` | Restore to a snapshot. **Default is a zero-write plan preview**; pass `confirm: true` to actually execute (overwrites / deletes `$DSH_HOME` files and uninstalls plugins added during import — destructive, always preview first) |
+| `config_sync_push` | Push config sync to the remote (Git / WebDAV) using the persisted channel config. Writing the remote is an explicit action; encryption / credentials require `password` and the engine forces `encrypt` |
+| `config_sync_pull` | Pull a remote diff **preview** (zero-write: download + analyze only). Landing the diff requires the separate confirm-import pipeline |
+
+Once the plugin is installed the tools appear automatically in every agent session (hosts without an agent `tools` service silently skip registration). The agent calls them when the task matches — e.g. "back up my config", "what snapshots do I have", "restore to that snapshot", "sync to my repo" or "show me the remote diff". Safety invariants are built in: `config_restore` is dry-run by default, `config_sync_pull` never writes, `config_sync_push` is an explicit remote write, and secret values never enter tool inputs / outputs / logs.
+
 ---
 
 ## 🛡️ Security

package/README.zh-CN.md

@@ -80,6 +80,7 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 | ⏰ | **定时全量备份** | 按固定周期（6h / 12h / 24h / 7d）自动全量备份，一劳永逸，密钥永不包含 |
 | 🛒 | **配置市场** | 浏览并一键安装社区分享的配置——供应链警示 + 逐分区批准 |
 | 🗂️ | **配置档案 Profiles** | 保存多套配置（工作 / 个人），随时切换 |
+| 🤖 | **Agent 工具** | Agent 会话内直接备份 / 快照 / 恢复 / 同步 |
 
 ---
 
@@ -325,6 +326,20 @@ dsh-config-manager restore --id <snapshot-id>                 # 执行恢复（
 
 **典型救急流程**（DSH 起不来时）：① `dsh-config-manager reinstall` 先把启动器重装回来（必要时顺带清理），② `dsh web` 重新启动 DSH，③ 从仓库装回插件，④ 从远程仓库拉取快照（或执行 `dsh-config-manager restore`）把配置恢复回来。整个流程中 CLI 全程可用，与 DSH 是否健康无关。
 
+### 🤖 Agent 可调用的模型工具
+
+插件还向宿主注册了 **5 个模型工具**，让 AI agent（DSH 助手会话）能在对话中直接驱动配置运维——与 GUI 共用同一套备份 / 快照 / 同步引擎，无需打开界面：
+
+| 工具 | 作用 |
+|---|---|
+| `config_backup` | 全量备份 DSH 配置到本地 `exports` 目录（**默认不含 secret**；传 `password` 可加密导出）。返回 ZIP 文件名 / 大小 / 分区清单 / 加密状态 |
+| `config_list_snapshots` | 列出本地回滚快照（id / 创建时间 / 来源 / 状态 / 条目数），供 `config_restore` 使用 |
+| `config_restore` | 恢复到指定快照。**默认只返回动作计划（零写入）**；传 `confirm: true` 才真实执行（会覆盖 / 删除 `$DSH_HOME` 文件并卸载导入期间新增插件——破坏性操作，务必先预览） |
+| `config_sync_push` | 手动推送配置同步到远端（Git / WebDAV），复用已持久化的通道配置。写远端属主动操作；加密 / 含凭据必须传 `password` 且引擎强制 `encrypt` |
+| `config_sync_pull` | 拉取远端差异**预览**（零写入：只下载 + 分析出差异报告）。要落地差异需另走确认导入管道 |
+
+安装插件后，这 5 个工具会自动出现在任意 agent 会话的工具清单里（宿主未组合 agent `tools` 服务时静默跳过注册）。由 agent 在任务相关时自主调用，例如「备份我的配置」「看看有哪些快照」「恢复到那个快照」「同步到我的仓库」「给我看远端差异」。安全不变量内建：`config_restore` 默认 dry-run、`config_sync_pull` 永不写入、`config_sync_push` 是显式远端写操作，且 secret 值永不进入工具入参 / 出参 / 日志。
+
 ---
 
 ## 🛡️ 安全

package/lib/client.d.ts

@@ -281,8 +281,8 @@ interface SnapshotMeta {
 }
 //#endregion
 //#region src/core/run-registry.d.ts
-/** run 类型：导出 / 导入 / 自动同步 / 一键同步逐项应用 / 定时备份。 */
-type RunKind = 'export' | 'import' | 'autosync' | 'sync-apply' | 'backup-schedule';
+/** run 类型：导出 / 导入 / 自动同步 / 一键同步逐项应用 / 定时备份 / 快照恢复。 */
+type RunKind = 'export' | 'import' | 'autosync' | 'sync-apply' | 'backup-schedule' | 'restore';
 /** run 状态：进行中 / 完成 / 失败。 */
 type RunStatus = 'running' | 'done' | 'failed';
 /** 单个 run 的实时状态（/progress 返回体；纯 JSON 可序列化）。 */
@@ -312,6 +312,40 @@ interface RunState {
   updatedAt: number;
 }
 //#endregion
+//#region src/sync/backup-schedule-config.d.ts
+/** 定时备份间隔档位（全量备份无需太频繁；默认 24h） */
+type BackupInterval = '6h' | '12h' | '24h' | '7d';
+/** 最近一次定时备份执行状态 */
+type BackupRunStatus = 'success' | 'skipped' | 'failed';
+//#endregion
+//#region src/sync/backup-scheduler.d.ts
+interface BackupRunResult {
+  status: BackupRunStatus;
+  zip?: string;
+  sizeBytes?: number;
+  sections?: string[];
+  skipReason?: string;
+  error?: string;
+  consecutiveFailures: number;
+}
+//#endregion
+//#region src/ui/backup-schedule.d.ts
+/** 设置草稿（表单编辑态：总开关 + 间隔档位）。 */
+interface BackupScheduleDraft {
+  enabled: boolean;
+  interval: BackupInterval;
+}
+/** 定时备份配置的浏览器侧视图（与 sync/backup-schedule-config.ts 的持久化面一致；无敏感字段）。 */
+interface BackupScheduleStatus {
+  enabled: boolean;
+  interval: BackupInterval;
+  startupMinIntervalMs: number;
+  consecutiveFailures: number;
+  lastRunAt?: string;
+  lastRunStatus?: BackupRunStatus;
+  lastRunMessage?: string;
+}
+//#endregion
 //#region src/ui/i18n.d.ts
 /**
  * 客户端展示层（src/ui/*、src/client/common/*）的渲染文案目录（zh 源语言 / en 镜像）。
@@ -604,11 +638,13 @@ interface DecryptArchiveResponse {
   /** 解密覆盖的凭据 ref 名（非值）；UI 据此从补录阶段剔除已恢复项 */
   refs: string[];
 }
-/** restore 端点响应：dryRun=true 返回 plan；执行返回 report（与 CLI 一致的诚实报告） */
+/** restore 端点响应：dryRun=true 返回 plan；执行返回 report（与 CLI 一致的诚实报告）。
+ *  runId 仅真实执行时存在（宿主 RunRegistry 登记；/runs + /progress 刷新恢复用）。 */
 interface RestoreResponse {
   dryRun: boolean;
   plan?: RestorePlan;
   report?: RestoreReport;
+  runId?: string;
 }
 /** Star 引导弹窗状态（GET /star-prompt；纯偏好，无 secret） */
 interface StarPromptStatus {
@@ -712,6 +748,15 @@ declare class ConfigManagerApi {
   snapshots(): Promise<SnapshotMeta[]>;
   /** 快照恢复：dryRun=true 只取动作计划（零写入）；false 执行并返回诚实报告 */
   restoreSnapshot(snapshotId: string, dryRun: boolean): Promise<RestoreResponse>;
+  /** 读取定时备份配置（enabled / interval / 上次运行状态；无敏感字段）。 */
+  backupSchedule(): Promise<BackupScheduleStatus>;
+  /** 保存定时备份设置（enabled + interval）；Host 校验后原子写 + 重排调度器。 */
+  saveBackupSchedule(draft: BackupScheduleDraft): Promise<BackupScheduleStatus>;
+  /** 立即执行一次全量备份（复用调度器 runOnce，防重；返回执行结果 + 最新配置）。 */
+  runBackupNow(): Promise<{
+    run: BackupRunResult;
+    schedule: BackupScheduleStatus;
+  }>;
 }
 //#endregion
 //#region src/sync/sync-engine.d.ts
@@ -1526,6 +1571,7 @@ declare const zh$2: {
   readonly 'import.importing': "正在导入…（插件安装较多时可能需要几分钟，请勿关闭页面）";
   readonly 'import.log.title': "导入日志";
   readonly 'import.log.empty': "等待命令输出…";
+  readonly 'import.log.newOutput': "↓ 新输出";
   readonly 'import.skipCurrent': "跳过当前插件";
   readonly 'import.skipPending': "正在跳过…其余项将继续导入";
   readonly 'import.retrySkipped': "重试失败/跳过的项 ({count})";
@@ -1571,6 +1617,7 @@ declare const zh$2: {
   readonly 'snapshots.noActions': "该快照无可用恢复动作（或全部跳过）。";
   readonly 'snapshots.execute': "执行恢复";
   readonly 'snapshots.executing': "恢复执行中…";
+  readonly 'snapshots.confirmTitle': "确认恢复";
   readonly 'snapshots.confirmRestore': "确认执行恢复？当前文件会先备份到快照的 pre-restore 目录，插件通过官方 dsh plugin remove 卸载。";
   readonly 'snapshots.reportTitle': "恢复报告";
   readonly 'snapshots.restored': "已还原";
@@ -1578,6 +1625,26 @@ declare const zh$2: {
   readonly 'snapshots.manualHints': "需人工处理";
   readonly 'snapshots.failed': "失败";
   readonly 'snapshots.skipped': "跳过";
+  readonly 'backupSchedule.title': "定时全量备份";
+  readonly 'backupSchedule.hint': "按固定间隔在后台自动导出全量备份 ZIP（恒不含 secret、不加密；要加密请手动导出）。配置存 sync/backup-schedule.json，随 self 分区备份 / 远程同步迁移。";
+  readonly 'backupSchedule.enabled': "启用定时备份";
+  readonly 'backupSchedule.enabledHint': "开启后 DSH 在后台按间隔自动备份；每次启动时立即执行一次（距上次运行不足 1 小时则跳过启动触发）。";
+  readonly 'backupSchedule.interval': "备份间隔";
+  readonly 'backupSchedule.interval.6h': "每 6 小时";
+  readonly 'backupSchedule.interval.12h': "每 12 小时";
+  readonly 'backupSchedule.interval.24h': "每 24 小时";
+  readonly 'backupSchedule.interval.7d': "每 7 天";
+  readonly 'backupSchedule.save': "保存设置";
+  readonly 'backupSchedule.saved': "设置已保存";
+  readonly 'backupSchedule.runNow': "立即备份";
+  readonly 'backupSchedule.running': "备份中…";
+  readonly 'backupSchedule.lastRun': "上次运行";
+  readonly 'backupSchedule.never': "从未运行";
+  readonly 'backupSchedule.status.success': "成功";
+  readonly 'backupSchedule.status.skipped': "已跳过";
+  readonly 'backupSchedule.status.failed': "失败";
+  readonly 'backupSchedule.loading': "加载定时备份设置…";
+  readonly 'backupSchedule.error': "定时备份设置加载失败";
   readonly 'report.export.title': "导出完成";
   readonly 'report.import.title': "导入结果";
   readonly 'report.rollback.title': "回滚报告";