@logictan/dsh-config-manager 0.1.60

package/lib/core/migration-history.js

@@ -0,0 +1,411 @@
+/**
+ * Migration History & Auditability Engine（Phase 6）——统一、持久、append-only、可查询、可导出的
+ * 迁移/审计历史存储。
+ *
+ * 职责（严格限定）：
+ *  - migration-history/ 目录下 per-file append-only 条目存储；
+ *  - 原子写（atomicWriteFile，0600 + symlink-reject）；
+ *  - 读取（只认合法历史文件，忽略 tmp/脏文件；损坏文件跳过并计数）；
+ *  - 查询（kind / 结果 / 时间 / 分区 过滤）、统计、导出（JSON / Markdown）；
+ *  - retention（删最旧、幂等）；
+ *  - **Redaction 边界**：条目内仅有 summary / error 是自由文本，写入前必须经
+ *    scanAndRedact（含 high-entropy 档）+ redactJournalText 双重清洗；其余字段
+ *    （kind/result/source/sections/operationId/snapshotId/runId/at）均为常量或 UUID，
+ *    无 secret 承载面。
+ *
+ * 安全/架构纪律（Phase 6 §3）：
+ *  - **不建第二套 framework**：复用 Phase 1 atomicWriteFile、journal 的 per-file append
+ *    模式、security 脱敏、paths 保留前缀；本模块是新能力（审计史），非重复基础设施。
+ *  - **APPEND-ONLY**：条目写入即完整独立文件，无 update/delete API（编译层无暴露）；
+ *    仅 retention 删最旧。篡改文件 → 读回损坏识别并跳过（不静默接受）。
+ *  - **DURABLE**：落盘跨重启。
+ *  - **BOUND**：条目尽量关联 operationId / snapshotId / runId。
+ *
+ * 与 DSH 运行时解耦：IO 经可注入门面（测试注入失败点），引擎层零 DSH 依赖。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+import { redact } from '../security/redaction.js';
+import { scanAndRedact } from '../security/secret-scanner.js';
+import { sha256Hex } from '../utils/hashing.js';
+// ---------- 常量 ----------
+export const MIGRATION_HISTORY_SCHEMA_VERSION = 1;
+export const MIGRATION_HISTORY_DIR = 'migration-history';
+/** 默认保留上限（retention 删最旧）。 */
+export const DEFAULT_MIGRATION_RETENTION = 1000;
+/** 文件名正则：`<stamp>-<hex12>.<kind>.json`，只认合法历史文件。 */
+const HISTORY_BASENAME_RE = /^[0-9A-Za-z:.+-]{8,}-[0-9a-f]{12}\.[a-z-]+\.json$/i;
+const TMP_PREFIX = '.dshcm.';
+/** 合法 kind 集合（§5 COMPLETE 清单 + 评审补 'profile-import'）。 */
+const MIGRATION_KINDS = [
+    'import', 'restore', 'rollback',
+    'profile-switch', 'profile-delete', 'profile-rename', 'profile-save', 'profile-import',
+    'sync-apply', 'autosync', 'recovery',
+    'backup', 'snapshot-delete', 'snapshot-prune',
+];
+const defaultIo = {
+    async mkdir(d, o) { await fs.mkdir(d, o); },
+    async readdirNames(d) { try {
+        return await fs.readdir(d);
+    }
+    catch {
+        return [];
+    } },
+    async readFileText(p) { return (await fs.readFile(p, 'utf8')).toString(); },
+    async writeAll(t, c) { await atomicWriteFile(t, c, { mode: 0o600, symlink: 'reject' }); },
+    async rm(p, o) { await fs.rm(p, o); },
+    async lstat(p) { try {
+        return await fs.lstat(p);
+    }
+    catch {
+        return null;
+    } },
+    async exists(p) { try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    } },
+};
+// ---------- Redaction（双保险） ----------
+/** journal 级高熵长 token 掩码（复用 journal 语义，独立实现避免跨层依赖）。 */
+const HIGH_ENTROPY_RE = /([A-Za-z0-9+/_=-]{28,})/g;
+/** 结构化时间戳/文件名形态：日期段必须由连字符连接（ISO 日期 YYYY-MM-DD 或
+ *  紧凑时间戳 YYYYMMDD-HHMMSS）。连字符不存在于 hex/base64 token 中，豁免不会误放行随机密钥。 */
+const DATE_STAMP_RE = /\d{4}-\d{2}-\d{2}|\d{8}-\d{6}/;
+/** 高熵长 token 掩码（日期戳形态豁免）。 */
+function maskHighEntropy(text) {
+    return text.replace(HIGH_ENTROPY_RE, (run) => (DATE_STAMP_RE.test(run) ? run : '[REDACTED]'));
+}
+/**
+ * 历史文本强脱敏：redact（结构化字段 + 已知值形状）+ 高熵长 token 掩码。
+ * 用于 summary / error 等可能嵌入任意值的字段（REDACTED 不变量）。
+ */
+export function redactHistoryText(text) {
+    let out = text;
+    try {
+        out = redact(out);
+    }
+    catch { /* 脱敏失败保守处理 */ }
+    return maskHighEntropy(out);
+}
+/**
+ * 构造安全条目：对 summary / error 做强脱敏（scanAndRedact 高熵档 + redactHistoryText），
+ * 做白名单字段规范化，并计算 contentHash（对除 contentHash 外全字段的 SHA-256）。
+ * **历史写入的唯一出口入口**，禁止绕过。
+ */
+export function sanitizeEntry(raw) {
+    // 1) 无损子串掩码（redact 值形状 + 高熵长 token），保留周边可读文本——优先，
+    //    避免「一个 sk- 子串就整段清空」导致审计可读性全失。
+    const masked = {
+        summary: redactHistoryText(raw.summary ?? ''),
+        error: redactHistoryText(raw.error ?? ''),
+    };
+    // 2) scanAndRedact（高熵档）作为残留防线：若掩码后仍检测到威胁，保守整值清空，
+    //    绝不带敏感值落盘。（scanAndRedact 对裸 string 静默跳过 → 固定包对象。）
+    const { sanitized } = scanAndRedact({ summary: masked.summary, error: masked.error }, { highEntropy: true, valuePatterns: true });
+    const s = (sanitized ?? {});
+    const summary = typeof s.summary === 'string' ? s.summary : '';
+    const hasError = ((masked.error ?? '') !== '');
+    const error = hasError ? (typeof s.error === 'string' ? s.error : '') : undefined;
+    const entry = {
+        schemaVersion: MIGRATION_HISTORY_SCHEMA_VERSION,
+        at: raw.at,
+        kind: raw.kind,
+        result: raw.result,
+        sections: Array.isArray(raw.sections) ? raw.sections.filter((s) => typeof s === 'string') : [],
+        source: sourceGuard(raw.source),
+        summary,
+        error,
+    };
+    if (raw.operationId !== undefined && isUuid(raw.operationId))
+        entry.operationId = raw.operationId;
+    if (raw.snapshotId !== undefined && isUuid(raw.snapshotId))
+        entry.snapshotId = raw.snapshotId;
+    if (raw.runId !== undefined && isUuid(raw.runId))
+        entry.runId = raw.runId;
+    const stored = entry;
+    stored.contentHash = computeContentHash(entry);
+    return stored;
+}
+const VALID_SOURCES = new Set([
+    'api', 'autosync', 'backup-scheduler', 'recovery', 'cli', 'internal',
+]);
+/** 运行期校验 source 属合法枚举；非法回退 'internal'（防未知来源绕过/清洗不一致）。 */
+function sourceGuard(v) {
+    return typeof v === 'string' && VALID_SOURCES.has(v) ? v : 'internal';
+}
+/** 对除 contentHash 外全字段计算稳定 SHA-256（字段序稳定、无无关缩进/空白）。 */
+function computeContentHash(entry) {
+    const payload = Object.fromEntries(Object.entries(entry).filter(([k]) => k !== 'contentHash'));
+    return sha256Hex(canonicalStringify(payload));
+}
+/** 稳定 JSON 序列化（键排序 + 无多余空白），保证 hash 跨运行稳定。 */
+function canonicalStringify(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = sortKeys(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+function isUuid(v) {
+    return typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);
+}
+/** 合法 kind 判定（类型守卫 + 运行时校验）。 */
+export function isValidMigrationKind(k) {
+    return typeof k === 'string' && MIGRATION_KINDS.includes(k);
+}
+/** 判断文件 basename 是否是可追踪历史文件（<sortable>-<hex>.json）。忽略 tmp 及其它。 */
+export function isHistoryBasename(name) {
+    if (!HISTORY_BASENAME_RE.test(name))
+        return false;
+    return !name.startsWith(TMP_PREFIX);
+}
+/** 文件名安全：仅 basename（不含目录分隔符/穿越）。 */
+export function isSafeHistoryFilename(name) {
+    if (name === '' || name.includes('/') || name.includes('\\') || name.includes('\0'))
+        return false;
+    return name !== '.' && name !== '..';
+}
+/**
+ * 生成排序文件名（Windows-safe 定宽时间戳 + 随机后缀 + kind 标记）。
+ *
+ * 时间戳契约（Windows/排序可靠性）：`toISOString().replace(/[:Z]/g,'')`
+ * → `2026-08-30T120000.123`（UTC 定宽、仅 ASCII、无 Windows 非法字符 `<>:"/\|?*`、
+ * 字典序== 时间序）。**禁止**以原始 `toISOString()`（含 `:`）直接落文件名（Windows rename 失败）。
+ * 与既有 `dateStamp`（`YYYYMMDD-HHmmss`）语义同为「定宽 + 仅 ASCII + 可排序」，本实现用 UTC 含毫秒
+ * 以获得更高时序精度；排序可靠性一致。
+ */
+export function makeHistoryFilename(now, kind) {
+    const stamp = now.toISOString().replace(/[:Z]/g, '');
+    const rand = crypto.randomBytes(6).toString('hex');
+    return `${stamp}-${rand}.${kind}.json`;
+}
+// ---------- 解析 ----------
+function parseEntry(text) {
+    try {
+        const p = JSON.parse(text);
+        if (p === null || typeof p !== 'object')
+            return null;
+        if (p.schemaVersion !== MIGRATION_HISTORY_SCHEMA_VERSION)
+            return null;
+        if (!isValidMigrationKind(p.kind))
+            return null;
+        if (typeof p.at !== 'string' || p.at === '')
+            return null;
+        if (!['success', 'failed', 'skipped'].includes(p.result))
+            return null;
+        if (typeof p.source !== 'string')
+            return null;
+        if (typeof p.summary !== 'string')
+            return null;
+        // 可选字段校验
+        if (p.operationId !== undefined && !isUuid(p.operationId))
+            return null;
+        if (p.snapshotId !== undefined && !isUuid(p.snapshotId))
+            return null;
+        if (p.runId !== undefined && !isUuid(p.runId))
+            return null;
+        if (p.sections !== undefined && (!Array.isArray(p.sections) || p.sections.some((s) => typeof s !== 'string')))
+            return null;
+        if (p.error !== undefined && typeof p.error !== 'string')
+            return null;
+        // **append-only 篡改检测**：contentHash 必须匹配（对除 contentHash 外全字段）。
+        // 合法 JSON 内改任意字段值 → hash 不符 → 拒绝（计入 corrupted，不静默接受）。
+        if (typeof p.contentHash !== 'string' || p.contentHash === '')
+            return null;
+        const payload = Object.fromEntries(Object.entries(p).filter(([k]) => k !== 'contentHash'));
+        if (sha256Hex(canonicalStringify(payload)) !== p.contentHash)
+            return null;
+        const { contentHash, ...rest } = p;
+        return { ...rest, contentHash };
+    }
+    catch {
+        return null;
+    }
+}
+/** MigrationHistory：per-file append-only 历史存储。 */
+export class MigrationStore {
+    dir;
+    io;
+    constructor(opts) {
+        this.dir = opts.dir;
+        this.io = opts.io ?? defaultIo;
+    }
+    /** 追加一条历史（原子写）。best-effort：调用方须经 tryAppendHistory 处理失败降级。 */
+    async append(raw) {
+        try {
+            const at = raw.at ?? new Date().toISOString();
+            const entry = sanitizeEntry({ ...raw, at });
+            // **防覆盖**：目标已存在（同毫秒+同随机后缀碰撞，概率极低但非零）→ 换名，
+            // 绝不覆盖既有条目（APPEND-ONLY 硬不变量：条目一旦写入不可改）。
+            let filename = makeHistoryFilename(new Date(at), entry.kind);
+            let target = path.join(this.dir, filename);
+            await this.io.mkdir(this.dir, { recursive: true });
+            let guard = 0;
+            while (await this.io.exists(target)) {
+                if (++guard > 8)
+                    return { ok: false, entry, error: 'history filename collision (retry 上限)' };
+                filename = makeHistoryFilename(new Date(at + guard), entry.kind);
+                target = path.join(this.dir, filename);
+            }
+            await this.io.writeAll(target, `${JSON.stringify(entry, null, 2)}\n`);
+            return { ok: true, entry, file: filename };
+        }
+        catch (error) {
+            const entry = sanitizeEntry({ ...raw, at: raw.at ?? new Date().toISOString() });
+            return { ok: false, entry, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /** 读取全部合法历史条目（旧→新；损坏/非史文件跳过并计数）。 */
+    async read() {
+        const names = await this.io.readdirNames(this.dir).catch(() => []);
+        const entries = [];
+        const corrupted = [];
+        const sorted = names.filter(isHistoryBasename).sort();
+        for (const name of sorted) {
+            const p = path.join(this.dir, name);
+            let text;
+            try {
+                if ((await this.io.lstat(p))?.isSymbolicLink() === true) {
+                    corrupted.push(name);
+                    continue;
+                } // symlink 防御
+                text = await this.io.readFileText(p);
+            }
+            catch {
+                corrupted.push(name);
+                continue;
+            }
+            const parsed = parseEntry(text);
+            if (parsed === null) {
+                corrupted.push(name);
+                continue;
+            }
+            entries.push(parsed);
+        }
+        return { entries, corrupted };
+    }
+    /**
+     * 保留清理：按文件名排序删除最旧合法历史文件，幂等。只删合法历史文件（防误删）。
+     * 返回本次删除的文件名。
+     */
+    async retention(limit = DEFAULT_MIGRATION_RETENTION) {
+        const names = (await this.io.readdirNames(this.dir).catch(() => [])).filter(isHistoryBasename).sort();
+        const removed = [];
+        if (names.length <= limit)
+            return removed;
+        const toRemove = names.slice(0, names.length - limit);
+        for (const name of toRemove) {
+            try {
+                await this.io.rm(path.join(this.dir, name), { force: true });
+                removed.push(name);
+            }
+            catch { /* 单文件删失败不中断其余 */ }
+        }
+        return removed;
+    }
+}
+// ---------- 查询 / 统计 / 导出（纯函数） ----------
+/** 纯函数过滤（无 IO）。 */
+export function queryHistory(entries, q) {
+    return entries.filter((e) => {
+        if (q.kinds !== undefined && q.kinds.length > 0 && !q.kinds.includes(e.kind))
+            return false;
+        if (q.result !== undefined && q.result.length > 0 && !q.result.includes(e.result))
+            return false;
+        if (q.sections !== undefined && q.sections.length > 0) {
+            if (!e.sections.some((s) => q.sections.includes(s)))
+                return false;
+        }
+        const t = Date.parse(e.at);
+        if (!Number.isNaN(t)) {
+            if (q.from !== undefined && t < q.from)
+                return false;
+            if (q.to !== undefined && t > q.to)
+                return false;
+        }
+        return true;
+    });
+}
+/** 纯函数统计（kind/result 计数）。 */
+export function summarizeHistory(entries) {
+    const stats = { total: entries.length, byKind: {}, byResult: {} };
+    for (const e of entries) {
+        stats.byKind[e.kind] = (stats.byKind[e.kind] ?? 0) + 1;
+        stats.byResult[e.result] = (stats.byResult[e.result] ?? 0) + 1;
+    }
+    return stats;
+}
+/** 导出报告（纯函数）。渲染文本统一过 redact() 兜底（安全不变量）。 */
+export function renderExport(entries, format, locale = 'zh') {
+    const L = locale === 'zh'
+        ? { title: 'DSH 配置迁移历史', total: '总数', empty: '暂无迁移记录', kind: '操作', time: '时间', result: '结果', sections: '分区', detail: '摘要' }
+        : { title: 'DSH Config Migration History', total: 'Total', empty: 'No migration records', kind: 'Operation', time: 'Time', result: 'Result', sections: 'Sections', detail: 'Summary' };
+    const resultLabel = (r) => r === 'success' ? (locale === 'zh' ? '成功' : 'success') : r === 'failed' ? (locale === 'zh' ? '失败' : 'failed') : (locale === 'zh' ? '跳过' : 'skipped');
+    if (format === 'json') {
+        const stats = summarizeHistory(entries);
+        return redact(JSON.stringify({ title: L.title, stats, entries }, null, 2));
+    }
+    if (entries.length === 0)
+        return `# ${L.title}\n\n${L.empty}\n`;
+    const lines = [];
+    lines.push(`# ${L.title}`, '');
+    lines.push(`> ${L.total}: ${entries.length}`, '');
+    lines.push('| ' + [L.time, L.kind, L.result, L.sections, L.detail].join(' | ') + ' |');
+    lines.push('|' + ' --- |'.repeat(5));
+    for (const e of entries) {
+        const detail = redact(e.summary + (e.error !== undefined ? ` — ${e.error}` : ''));
+        lines.push(`| ${e.at} | ${e.kind} | ${resultLabel(e.result)} | ${redact(e.sections.join(', '))} | ${detail} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** 解析查询参数为 MigrationQuery（宿主路由复用；过滤非法输入）。 */
+export function parseHistoryQuery(raw) {
+    const q = {};
+    const kinds = parseList(raw['kind']);
+    if (kinds.length > 0)
+        q.kinds = kinds.filter(isValidMigrationKind);
+    const results = parseList(raw['result']);
+    if (results.length > 0)
+        q.result = results.filter((r) => r === 'success' || r === 'failed' || r === 'skipped');
+    const sections = parseList(raw['sections']);
+    if (sections.length > 0)
+        q.sections = sections;
+    const from = parseNum(raw['from']);
+    const to = parseNum(raw['to']);
+    if (from !== undefined)
+        q.from = from;
+    if (to !== undefined)
+        q.to = to;
+    return q;
+}
+function parseList(v) {
+    if (v === undefined)
+        return [];
+    if (typeof v === 'string')
+        return v.split(',').map((s) => s.trim()).filter((s) => s !== '');
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === 'string' && x !== '');
+    return [];
+}
+function parseNum(v) {
+    if (typeof v === 'string' && v !== '' && !Number.isNaN(Number(v)))
+        return Number(v);
+    if (typeof v === 'number' && !Number.isNaN(v))
+        return v;
+    return undefined;
+}
+//# sourceMappingURL=migration-history.js.map

package/lib/core/model-tools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * dsh-config-manager — Agent 可调用的模型工具。
+ *
+ * 在 host 半注册 2 个 Cordis 模型工具，让 Agent 能自主驱动配置同步：
+ *   config_sync_push        手动推送同步（写远端）
+ *   config_sync_pull        拉取差异预览（零写入）
+ *
+ * 设计遵循 AGENTS.md 铁律：
+ *   - 所有业务逻辑为可独立测试的纯编排函数（createModelTools），
+ *     复用 src/core 已解耦引擎（SyncEngine），不重复实现；
+ *   - React / HTTP 壳不参与；本文件是「引擎侧编排」，不放浏览器 src/ui/；
+ *   - ctx.tools 服务用可选读取（ctx.get）守卫：未组合 tools 的部署不注册、不崩溃。
+ *
+ * 安全不变量（硬约束，勿破坏）：
+ *   - config_sync_pull 零写入（只 analyze+plan 出差异）；落地需另走确认导入管道；
+ *   - 分区/路径走既有白名单（SECTION_IDS 过滤）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue } from '@deepseek-ai/dsh-tools';
+import type { SyncEngine } from '../sync/sync-engine.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { SyncConfig, SyncTransportType } from '../sync/sync-config.ts';
+import type { ConfigAdapter, HostContext } from './types.ts';
+/** 模型工具所需依赖（与 host 路由同一来源闭包）。 */
+export interface ModelToolsDeps {
+    /** HostContext 门面（homeDir / profile / msg / log） */
+    host: HostContext;
+    /** 全部分区适配器 */
+    adapters: ConfigAdapter[];
+    /** 同步状态目录（$DSH_HOME/dsh-config-manager/sync） */
+    syncDir: string;
+    /** SyncEngine 工厂（git/webdav 按配置分支构造传输；与 host 路由同一来源） */
+    makeSyncEngine: (cfg: SyncConfig) => SyncEngine;
+}
+/** 2 个工具的纯编排实现（可独立测试，不依赖 Cordis ctx）。所有返回均为 JsonValue（可序列化、无 undefined）。 */
+export declare function createModelTools(deps: ModelToolsDeps): {
+    /** 手动推送同步（写远端）。明文快照：勾选即同步，不加密、不脱敏。 */
+    syncPush(input: {
+        channel?: SyncTransportType;
+        sections?: SectionId[];
+    }): Promise<JsonValue>;
+    /** 拉取差异预览（零写入：只下载 + analyze + plan 出差异报告）。 */
+    syncPull(input: {
+        channel?: SyncTransportType;
+        snapshotId?: string;
+        strategy?: 'merge' | 'replace' | 'skipExisting';
+    }): Promise<JsonValue>;
+};
+/** 把 2 个模型工具注册进 ctx.tools；tools 服务未组合时静默跳过（不崩溃）。 */
+export declare function registerModelTools(ctx: Context, deps: ModelToolsDeps): void;

package/lib/core/model-tools.js

@@ -0,0 +1,148 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { SECTION_IDS } from '../schema/config.js';
+import { readFullSyncConfig, readSyncConfigFor } from '../sync/sync-config.js';
+import { runWithMutationLock } from '../utils/env-lock.js';
+/** SECTION_IDS 白名单过滤（未知/非法分区 id 丢弃，与 host 路由语义一致）。 */
+function filterSectionIds(ids) {
+    return ids.filter((id) => SECTION_IDS.includes(id));
+}
+/** 解析同步引擎：channel 缺省取已配置的活动通道（git/webdav），未配置则抛可操作错误。 */
+async function resolveEngine(deps, channel) {
+    let ch = channel ?? 'git';
+    if (channel === undefined) {
+        const full = await readFullSyncConfig(deps.syncDir);
+        if (full !== null && full.transport === 'webdav')
+            ch = 'webdav';
+    }
+    const cfg = await readSyncConfigFor(deps.syncDir, ch);
+    if (cfg === null) {
+        throw new Error(`同步通道 ${ch} 尚未配置（sync-config.json 缺失或损坏）`);
+    }
+    return { engine: deps.makeSyncEngine(cfg), channel: ch };
+}
+/* ------------------------------------------------------------ 纯编排函数 */
+/** 2 个工具的纯编排实现（可独立测试，不依赖 Cordis ctx）。所有返回均为 JsonValue（可序列化、无 undefined）。 */
+export function createModelTools(deps) {
+    return {
+        /** 手动推送同步（写远端）。明文快照：勾选即同步，不加密、不脱敏。 */
+        async syncPush(input) {
+            const { engine } = await resolveEngine(deps, input.channel);
+            const sections = input.sections === undefined ? undefined : filterSectionIds(input.sections);
+            // Phase 2 锁：push 写远端 + 本地散文件 + sync-state，属 GLOBAL mutation。
+            // Step 3 P0-A：外部 push 记 intent journal（crash 后不可证明 → NEEDS_ATTENTION，不自动重推）。
+            const doPush = () => engine.push({
+                ...(sections === undefined ? {} : { sections }),
+            });
+            const report = await runWithMutationLock(deps.host.mutationLock, { op: 'model-sync-push', isBlocked: () => deps.host.safeModeIsBlocked?.() ?? false }, async (lockCtx) => {
+                if (deps.host.phase3Recovery !== undefined && lockCtx !== null) {
+                    const r = await deps.host.phase3Recovery.runExternalIntent({
+                        operationType: 'model-sync-push',
+                        lockCtx,
+                        intent: { adapter: 'sync', ref: input.channel ?? 'default', kind: 'Push' },
+                        fn: doPush,
+                    });
+                    return r.result;
+                }
+                return doPush();
+            });
+            return {
+                ok: report.ok,
+                snapshotId: report.snapshotId,
+                sections: report.sections,
+                warnings: report.warnings,
+                ...(report.message === undefined ? {} : { message: report.message }),
+            };
+        },
+        /** 拉取差异预览（零写入：只下载 + analyze + plan 出差异报告）。 */
+        async syncPull(input) {
+            const { engine } = await resolveEngine(deps, input.channel);
+            const strategy = input.strategy === 'replace' || input.strategy === 'skipExisting' ? input.strategy : 'replace';
+            const report = await engine.pull({
+                strategy,
+                ...(input.snapshotId === undefined || input.snapshotId === '' ? {} : { snapshotId: input.snapshotId }),
+            });
+            return {
+                ok: report.ok,
+                snapshotId: report.snapshotId,
+                needsReview: report.needsReview,
+                changes: report.changes.map((c) => ({
+                    id: c.id,
+                    adapter: c.adapter,
+                    kind: c.kind,
+                    description: c.description,
+                    severity: c.severity,
+                })),
+                ...(report.message === undefined ? {} : { message: report.message }),
+            };
+        },
+    };
+}
+/** 把 2 个模型工具注册进 ctx.tools；tools 服务未组合时静默跳过（不崩溃）。 */
+export function registerModelTools(ctx, deps) {
+    const toolsSvc = ctx.get('tools');
+    if (toolsSvc === null || toolsSvc === undefined || typeof toolsSvc !== 'object') {
+        deps.host.log.warn?.('tools 服务不可用：跳过模型工具注册（引擎能力仍可用）');
+        return;
+    }
+    const tools = createModelTools(deps);
+    const disposers = [];
+    // 注意：必须经 ctx.get('tools') 的结果注册，绝不能用 ctx.tools 属性访问——
+    // Cordis 的属性访问要求插件声明 inject: ['tools']，未声明时即使服务存在也会抛
+    // "cannot get property X without inject"（tools 是可选服务，不应进 inject）。
+    const register = (def) => {
+        disposers.push(toolsSvc.register(def));
+    };
+    register(defineTool({
+        name: 'config_sync_push',
+        description: '手动推送 DSH 配置同步到远端（Git/WebDAV），复用已持久化的通道配置。写远端属主动操作；快照为明文（私有通道自用），勾选即同步。',
+        parameters: {
+            channel: {
+                type: 'string',
+                enum: ['git', 'webdav'],
+                description: '同步通道；缺省 = 已配置的活动通道',
+            },
+            sections: {
+                type: 'array',
+                items: { type: 'string', enum: [...SECTION_IDS] },
+                description: '仅推送的分区；缺省 = 全部推荐分区',
+            },
+        },
+        output: {
+            schema: { type: 'json', description: '推送报告（snapshotId / 实际同步分区 / 告警）' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args) {
+            return tools.syncPush(args);
+        },
+    }));
+    register(defineTool({
+        name: 'config_sync_pull',
+        description: '拉取远端同步差异预览（Git/WebDAV，零写入：只下载 + 分析出差异报告，绝不直接写配置）。若要落地差异需另走确认导入管道。',
+        parameters: {
+            channel: {
+                type: 'string',
+                enum: ['git', 'webdav'],
+                description: '同步通道；缺省 = 已配置的活动通道',
+            },
+            snapshotId: {
+                type: 'string',
+                description: '远端快照 id；缺省 = 最新',
+            },
+            strategy: {
+                type: 'string',
+                enum: ['replace', 'skipExisting'],
+                description: '差异全局策略；缺省 replace（远端值覆盖本地）',
+            },
+        },
+        output: {
+            schema: { type: 'json', description: '差异报告（changes 列表 / needsReview）' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args) {
+            return tools.syncPull(args);
+        },
+    }));
+    ctx.effect(() => () => { for (const d of disposers)
+        d(); }, 'config-manager: model tools');
+}
+//# sourceMappingURL=model-tools.js.map

package/lib/core/msg-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 消息翻译器的最小契约（引擎注入点）。
+ * 实现见 ./messages.ts（zh/en 目录 + makeMsg / msgOf）。
+ */
+/** 插值形参：{param} 占位符的值。 */
+export type MsgParams = Record<string, string | number>;
+/** 翻译函数：key → 当前语言文案（{param} 插值；未知键回退 zh/键名，绝不抛错）。 */
+export type MsgFunc = (key: string, params?: MsgParams) => string;

package/lib/core/msg-types.js

@@ -0,0 +1,6 @@
+/**
+ * 消息翻译器的最小契约（引擎注入点）。
+ * 实现见 ./messages.ts（zh/en 目录 + makeMsg / msgOf）。
+ */
+export {};
+//# sourceMappingURL=msg-types.js.map

package/lib/core/phase3-child-crash.d.ts

@@ -0,0 +1 @@
+export {};