deeptrade-quant 0.15.2__tar.gz → 0.16.0__tar.gz

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to DeepTrade. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and SemVer.
 
+## [v0.16.0] — 2026-05-30 — 框架层配置导入 / 导出
+
+新增 `deeptrade config export` / `deeptrade config import`，用于备份、迁移、审计和复制框架层配置。范围严格限定为 `ConfigService` 管理的框架配置：`app_config` 中的非敏感键，以及 `secret_store` 中由 `is_secret_key()` 路由的框架 secret；不导出插件安装、插件私有配置、插件业务表、运行记录、LLM 调用日志、Tushare 同步状态或报告文件。
+
+默认导出持久化配置且不写出 secret 明文，只记录 secret 的存在状态。显式使用 `--include-secrets` 时才会把 token / API key 明文写入文件；`--effective` 可导出当前进程解析后的有效值（包含默认值和环境变量覆盖），`--include-defaults` 可在持久化导出中补齐默认值。
+
+### Added
+
+- **服务层** `deeptrade.core.config_io`：
+  - `ConfigExportOptions` / `ConfigImportOptions` / `ConfigImportPlan`
+  - `ConfigIOService.export_payload()` / `plan_import()` / `apply_import_plan()`
+  - 文件格式 `schema_version=1`，顶层包含 `tool="deeptrade"`、`exported_at`、`mode`、`config`、`secrets`。
+- **CLI**：
+  - `deeptrade config export [PATH] [--format json|yaml] [--include-secrets] [--effective] [--include-defaults] [--force]`
+  - `deeptrade config import PATH [--format json|yaml] [--mode merge|replace] [--include-secrets] [--dry-run] [--yes]`
+  - `PATH=-` 导出到 stdout 时只输出 payload，摘要走 stderr，便于脚本管道消费。
+- **导入安全语义**：
+  - `merge` 默认只覆盖文件中出现的配置项；缺失项保持本地值。
+  - `replace --yes` 会删除所有框架层持久化配置和框架层 secret，再写入文件内容。
+  - 默认忽略文件中的 secret value；只有 `--include-secrets` 且 value 为非空字符串时才写入。
+  - 拒绝 masked secret（如 `********1234`）导入。
+  - 校验 `tool` / `schema_version` / key 命名空间 / Pydantic 配置值 / LLM provider 名称及环境变量归一化冲突。
+- **测试**：
+  - 核心单元测试覆盖默认不泄露 secret、显式导出 secret、persisted/effective 差异、merge/replace、dry-run 计划、secret 导入开关、非法 key 和 provider 名称冲突。
+  - CLI 测试覆盖文件导出、已存在文件保护、stdout JSON、dry-run 不写入、导入 secret 后仍脱敏展示、replace 必须显式 `--yes`。
+
+### Notes
+
+- 非敏感配置写入仍复用 `ConfigService.set()` / `delete()`，保持 Pydantic 校验和现有路由。
+- Secret 写入仍复用 `ConfigService.set(secret_key, value)`，保持 keyring 优先和 plaintext fallback 行为；跨 keyring 与 DuckDB 的事务一致性不做额外承诺。
+
 ## [v0.15.2] — 2026-05-27 — `set-llm` 新增 OpenRouter base_url 预设
 
 给交互式 `deeptrade config set-llm` 的 base_url 预设表（`cli_config.py::_DEFAULT_BASE_URLS`）补一条 OpenRouter。OpenRouter 是标准 OpenAI 兼容端点，本来就能用——base_url 不命中 `_TRANSPORT_BY_BASE_URL` 路由表，自动落到 `GenericOpenAITransport`（`thinking` 标志按契约静默丢弃）。这次纯属录入便利：provider 名取 `openrouter`（或 `openrouter-xxx`，`name.split("-")[0]` 仍命中）时自动带出 base_url，省去手填。无新增能力、无 transport 代码、不动配置 schema。

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deeptrade-quant
-Version: 0.15.2
+Version: 0.16.0
 Summary: LLM-driven A-share (Shanghai/Shenzhen main board) stock screening CLI
 Project-URL: Homepage, https://github.com/ty19880929/deeptrade
 Project-URL: Repository, https://github.com/ty19880929/deeptrade
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 > 📖 **在线文档**：[deeptrade.tiey.ai](https://deeptrade.tiey.ai) — 用户手册 + 开发者手册 + 官方插件目录
 
-[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.15.2-blue)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.16.0-blue)](CHANGELOG.md)
 
 ## ✨ 主要特性
 
@@ -85,6 +85,8 @@ deeptrade config set-llm                  # 交互式增/改/删 LLM provider（
 deeptrade config list-llm                 # 列出已配置且可用的 provider
 deeptrade config test-llm                 # 对所有 provider 做连通性自检（也可加 <name> 单测）
 deeptrade config show                     # 表格展示当前配置（密钥脱敏）
+deeptrade config export deeptrade-config.json
+deeptrade config import deeptrade-config.json --dry-run
 
 # 可选：报告上传（v0.11+，全局开关默认关闭）
 deeptrade config set report.upload.enabled true
@@ -94,6 +96,8 @@ deeptrade config set report.upload.token   <bearer-token>   # 可选；空串走
 
 > **报告上传（v0.11+）**：框架提供 `ReportUploader` 公共服务，插件通过 `ctx.make_report_uploader().upload(path, plugin_name=..., trade_date=...)` 把执行报告 JSON 推到统一端点。配置键 `report.upload.{enabled,url,timeout}` 走 `app_config`，`report.upload.token` 走 `secret_store`；每次调用（含 skipped）都在 `report_uploads` 表留一行审计，token / Authorization 永不落库。上传失败永远只 WARN，不阻断 run。
 
+> **配置导入/导出**：`deeptrade config export [PATH]` 默认只导出框架层持久化配置和 secret 存在状态，不导出密钥明文；`--include-secrets` 会把 token / API key 明文写入文件，文件应按敏感凭据保存。导入使用 `deeptrade config import PATH --dry-run` 预览，默认 `--mode merge`；`--mode replace --yes` 会先删除所有框架层持久化配置和框架层 secret，再写入文件内容。
+
 > **LLM 复现性 & 缓存（v0.12+）**：相同 `(plugin_id, stage, provider, model, system+user prompt, profile, schema_version, input_fingerprint)` 下，重复执行直接命中已验证响应，不再向 provider 发起调用。
 >
 > - 配置键 `llm.replay.{enabled,write,ttl_days}` 全部走 `app_config`，默认 `enabled=true / write=true / ttl_days=null`（不过期）。
@@ -155,7 +159,7 @@ deeptrade volume-anomaly stats            # 收益统计聚合
 | `deeptrade init [--no-prompts]` | 建库 + 应用 core migrations |
 | `deeptrade db init` / `db upgrade` | 显式建库 / 应用待执行迁移 |
 | `deeptrade db llm-cache {list, purge, inspect}` (v0.13+) | LLM replay cache 横向运维：`list` 按 plugin/stage 过滤；`purge --yes --plugin/--stage/--before` 至少一个过滤器；`inspect <cache_key 前缀>` |
-| `deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm}` | 全局配置 |
+| `deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm, export, import}` | 全局配置 |
 | `deeptrade plugin search [keyword] [--no-cache]` | 浏览官方注册表 |
 | `deeptrade plugin install <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps] [-y]` | 注册表短名 / GitHub URL / 本地路径；依赖按 PEP 508 自动解析装入框架解释器 |
 | `deeptrade plugin list` / `info <id>` | 列表 / 详情（未安装时回退注册表条目） |

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/README.md

@@ -4,7 +4,7 @@
 
 > 📖 **在线文档**：[deeptrade.tiey.ai](https://deeptrade.tiey.ai) — 用户手册 + 开发者手册 + 官方插件目录
 
-[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.15.2-blue)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.16.0-blue)](CHANGELOG.md)
 
 ## ✨ 主要特性
 
@@ -47,6 +47,8 @@ deeptrade config set-llm                  # 交互式增/改/删 LLM provider（
 deeptrade config list-llm                 # 列出已配置且可用的 provider
 deeptrade config test-llm                 # 对所有 provider 做连通性自检（也可加 <name> 单测）
 deeptrade config show                     # 表格展示当前配置（密钥脱敏）
+deeptrade config export deeptrade-config.json
+deeptrade config import deeptrade-config.json --dry-run
 
 # 可选：报告上传（v0.11+，全局开关默认关闭）
 deeptrade config set report.upload.enabled true
@@ -56,6 +58,8 @@ deeptrade config set report.upload.token   <bearer-token>   # 可选；空串走
 
 > **报告上传（v0.11+）**：框架提供 `ReportUploader` 公共服务，插件通过 `ctx.make_report_uploader().upload(path, plugin_name=..., trade_date=...)` 把执行报告 JSON 推到统一端点。配置键 `report.upload.{enabled,url,timeout}` 走 `app_config`，`report.upload.token` 走 `secret_store`；每次调用（含 skipped）都在 `report_uploads` 表留一行审计，token / Authorization 永不落库。上传失败永远只 WARN，不阻断 run。
 
+> **配置导入/导出**：`deeptrade config export [PATH]` 默认只导出框架层持久化配置和 secret 存在状态，不导出密钥明文；`--include-secrets` 会把 token / API key 明文写入文件，文件应按敏感凭据保存。导入使用 `deeptrade config import PATH --dry-run` 预览，默认 `--mode merge`；`--mode replace --yes` 会先删除所有框架层持久化配置和框架层 secret，再写入文件内容。
+
 > **LLM 复现性 & 缓存（v0.12+）**：相同 `(plugin_id, stage, provider, model, system+user prompt, profile, schema_version, input_fingerprint)` 下，重复执行直接命中已验证响应，不再向 provider 发起调用。
 >
 > - 配置键 `llm.replay.{enabled,write,ttl_days}` 全部走 `app_config`，默认 `enabled=true / write=true / ttl_days=null`（不过期）。
@@ -117,7 +121,7 @@ deeptrade volume-anomaly stats            # 收益统计聚合
 | `deeptrade init [--no-prompts]` | 建库 + 应用 core migrations |
 | `deeptrade db init` / `db upgrade` | 显式建库 / 应用待执行迁移 |
 | `deeptrade db llm-cache {list, purge, inspect}` (v0.13+) | LLM replay cache 横向运维：`list` 按 plugin/stage 过滤；`purge --yes --plugin/--stage/--before` 至少一个过滤器；`inspect <cache_key 前缀>` |
-| `deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm}` | 全局配置 |
+| `deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm, export, import}` | 全局配置 |
 | `deeptrade plugin search [keyword] [--no-cache]` | 浏览官方注册表 |
 | `deeptrade plugin install <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps] [-y]` | 注册表短名 / GitHub URL / 本地路径；依赖按 PEP 508 自动解析装入框架解释器 |
 | `deeptrade plugin list` / `info <id>` | 列表 / 详情（未安装时回退注册表条目） |

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/deeptrade/__init__.py

@@ -2,5 +2,5 @@
 
 from __future__ import annotations
 
-__version__ = "0.15.2"
+__version__ = "0.16.0"
 __all__ = ["__version__"]

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/deeptrade/cli_config.py

@@ -11,10 +11,13 @@ v0.6 — multi-provider LLM (DESIGN §0.7 / §10):
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
 
 import questionary
 import typer
+import yaml
 from rich.console import Console
 from rich.table import Table
 
@@ -23,12 +26,20 @@ from deeptrade.core.config import (
     ConfigService,
     known_keys,
 )
+from deeptrade.core.config_io import (
+    ConfigExportOptions,
+    ConfigImportOptions,
+    ConfigImportPlan,
+    ConfigIOError,
+    ConfigIOService,
+)
 from deeptrade.core.db import Database
 
 if TYPE_CHECKING:  # pragma: no cover
     pass
 
 app = typer.Typer(help="查看 / 编辑配置", no_args_is_help=True)
+ConfigFileFormat: TypeAlias = Literal["json", "yaml"]
 
 
 # ---------------------------------------------------------------------------
@@ -42,6 +53,49 @@ def _open_service() -> tuple[Database, ConfigService]:
     return db, ConfigService(db)
 
 
+def _infer_format(
+    path: str,
+    explicit: str | None,
+    *,
+    for_import: bool,
+) -> ConfigFileFormat:
+    if explicit is not None:
+        if explicit not in {"json", "yaml"}:
+            raise typer.BadParameter("--format must be json or yaml")
+        return cast(ConfigFileFormat, explicit)
+    suffix = Path(path).suffix.lower()
+    if suffix == ".json" or path == "-":
+        return "json"
+    if suffix in {".yaml", ".yml"}:
+        return "yaml"
+    if for_import:
+        raise typer.BadParameter("--format is required when PATH has no .json/.yaml suffix")
+    return "json"
+
+
+def _dump_payload(payload: dict[str, Any], fmt: ConfigFileFormat) -> str:
+    if fmt == "json":
+        return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+    return yaml.safe_dump(payload, allow_unicode=True, sort_keys=False)
+
+
+def _load_payload(text: str, fmt: ConfigFileFormat) -> dict[str, Any]:
+    loaded = json.loads(text) if fmt == "json" else yaml.safe_load(text)
+    if not isinstance(loaded, dict):
+        raise ConfigIOError("config file must contain an object")
+    return loaded
+
+
+def _print_import_plan(plan: ConfigImportPlan, *, source: str, mode: str) -> None:
+    typer.echo(f"导入预览：{source}")
+    typer.echo(f"模式：{mode}")
+    typer.echo(f"将写入非敏感配置：{len(plan.set_config)} 项")
+    typer.echo(f"将写入 secret：{len(plan.set_secrets)} 项")
+    typer.echo(f"将删除配置：{len(plan.delete_config) + len(plan.delete_secrets)} 项")
+    for warning in plan.warnings:
+        typer.echo(f"警告：{warning}", err=True)
+
+
 # ---------------------------------------------------------------------------
 # show
 # ---------------------------------------------------------------------------
@@ -77,6 +131,144 @@ def cmd_show() -> None:
         db.close()
 
 
+@app.command("export")
+def cmd_export(
+    path: str = typer.Argument(
+        "deeptrade-config.json",
+        help="输出路径；使用 '-' 写到 stdout",
+    ),
+    fmt: str | None = typer.Option(
+        None,
+        "--format",
+        help="输出格式：json 或 yaml；默认按扩展名推断",
+    ),
+    include_secrets: bool = typer.Option(
+        False,
+        "--include-secrets",
+        help="导出 secret 明文；导出文件将包含敏感密钥",
+    ),
+    effective: bool = typer.Option(
+        False,
+        "--effective",
+        help="导出当前进程解析后的有效配置，包含默认值和环境变量覆盖",
+    ),
+    include_defaults: bool = typer.Option(
+        False,
+        "--include-defaults",
+        help="持久化导出时补齐 AppConfig 默认值，不包含环境变量覆盖",
+    ),
+    force: bool = typer.Option(False, "--force", help="允许覆盖已存在文件"),
+) -> None:
+    """导出框架层配置。默认不导出 secret 明文。"""
+    if effective and include_defaults:
+        typer.echo("--effective 不能与 --include-defaults 同时使用", err=True)
+        raise typer.Exit(2)
+    file_format = _infer_format(path, fmt, for_import=False)
+    output_path = None if path == "-" else Path(path)
+    if output_path is not None and output_path.exists() and not force:
+        typer.echo(f"目标文件已存在：{output_path}；使用 --force 覆盖", err=True)
+        raise typer.Exit(2)
+
+    db, svc = _open_service()
+    try:
+        payload = ConfigIOService(db, svc).export_payload(
+            ConfigExportOptions(
+                include_secrets=include_secrets,
+                include_defaults=include_defaults,
+                effective=effective,
+            )
+        )
+        text = _dump_payload(payload, file_format)
+        if output_path is None:
+            typer.echo(text, nl=False)
+            err = True
+            target = "stdout"
+        else:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(text, encoding="utf-8")
+            err = False
+            target = str(output_path)
+
+        if include_secrets:
+            plaintext = sum(1 for item in payload["secrets"].values() if item.get("value"))
+            typer.echo(f"警告：导出文件包含 {plaintext} 项明文 secret，请妥善保存。", err=True)
+        typer.echo(f"已导出框架配置：{target}", err=err)
+        typer.echo(f"非敏感配置：{len(payload['config'])} 项", err=err)
+        present = sum(1 for item in payload["secrets"].values() if item.get("present"))
+        plaintext = sum(1 for item in payload["secrets"].values() if item.get("value"))
+        typer.echo(f"Secret：{present} 项已记录存在状态，{plaintext} 项导出明文", err=err)
+        for warning in payload.get("warnings", []):
+            typer.echo(f"警告：{warning}", err=True)
+    finally:
+        db.close()
+
+
+@app.command("import")
+def cmd_import(
+    path: str = typer.Argument(..., help="输入配置文件路径"),
+    fmt: str | None = typer.Option(
+        None,
+        "--format",
+        help="输入格式：json 或 yaml；默认按扩展名推断",
+    ),
+    mode: str = typer.Option(
+        "merge",
+        "--mode",
+        help="导入模式：merge 只覆盖文件内项目；replace 先删除框架层持久化配置",
+    ),
+    include_secrets: bool = typer.Option(
+        False,
+        "--include-secrets",
+        help="允许导入文件中的 secret 明文；默认忽略 secret value",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="只解析、校验并展示计划，不写入"),
+    yes: bool = typer.Option(False, "--yes", help="确认 replace 模式的破坏性删除"),
+) -> None:
+    """导入框架层配置。默认忽略文件中的 secret 明文。"""
+    if mode not in {"merge", "replace"}:
+        typer.echo("--mode 必须是 merge 或 replace", err=True)
+        raise typer.Exit(2)
+    if mode == "replace" and not yes and not dry_run:
+        typer.echo("replace 模式会删除所有框架层持久化配置和 secret；请加 --yes 确认", err=True)
+        raise typer.Exit(2)
+
+    file_format = _infer_format(path, fmt, for_import=True)
+    source_path = Path(path)
+    try:
+        payload = _load_payload(source_path.read_text(encoding="utf-8"), file_format)
+    except (OSError, json.JSONDecodeError, yaml.YAMLError, ConfigIOError) as e:
+        typer.echo(f"读取配置文件失败：{e}", err=True)
+        raise typer.Exit(2) from e
+
+    db, svc = _open_service()
+    try:
+        service = ConfigIOService(db, svc)
+        options = ConfigImportOptions(
+            include_secrets=include_secrets,
+            mode=cast(Literal["merge", "replace"], mode),
+            dry_run=dry_run,
+        )
+        try:
+            plan = service.plan_import(payload, options)
+        except (ConfigIOError, ValueError) as e:
+            typer.echo(f"配置文件无效：{e}", err=True)
+            raise typer.Exit(2) from e
+
+        if dry_run:
+            _print_import_plan(plan, source=path, mode=mode)
+            return
+
+        service.apply_import_plan(plan)
+        typer.echo(f"已导入框架配置：{path}")
+        typer.echo(f"写入非敏感配置：{len(plan.set_config)} 项")
+        typer.echo(f"写入 secret：{len(plan.set_secrets)} 项")
+        typer.echo(f"删除配置：{len(plan.delete_config) + len(plan.delete_secrets)} 项")
+        for warning in plan.warnings:
+            typer.echo(f"警告：{warning}", err=True)
+    finally:
+        db.close()
+
+
 # ---------------------------------------------------------------------------
 # set
 # ---------------------------------------------------------------------------

{deeptrade_quant-0.15.2 → deeptrade_quant-0.16.0}/deeptrade/core/config.py

@@ -32,7 +32,7 @@ from typing import Any, Literal
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from deeptrade.core.db import Database
-from deeptrade.core.secrets import SecretStore
+from deeptrade.core.secrets import SecretRecord, SecretStore
 from deeptrade.plugins_api.llm import StageProfile
 
 # ---------------------------------------------------------------------------
@@ -337,6 +337,10 @@ class ConfigService:
         accessible OS keyring."""
         return sum(1 for r in self._secrets.list_records() if r.method == "plaintext")
 
+    def list_secret_records(self) -> list[SecretRecord]:
+        """Return secret metadata rows without forcing keyring reads."""
+        return self._secrets.list_records()
+
     # --- read ----------------------------------------------------------
 
     def get(self, key: str) -> Any:

deeptrade_quant-0.16.0/deeptrade/core/config_io.py

@@ -0,0 +1,296 @@
+"""Import/export support for framework-level configuration.
+
+This module intentionally handles only framework-owned configuration:
+``app_config`` non-secret rows and ``secret_store`` entries routed by
+``ConfigService``. It does not snapshot plugin installs, plugin data, reports,
+runtime logs, or environment variables unless explicitly asked for the
+effective runtime view.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from deeptrade.core.config import (
+    AppConfig,
+    ConfigService,
+    env_var_for,
+    is_secret_key,
+    known_keys,
+)
+from deeptrade.core.db import Database
+
+SCHEMA_VERSION = 1
+
+
+class ConfigIOError(ValueError):
+    """Raised when a config import/export payload is invalid."""
+
+
+class ConfigExportOptions(BaseModel):
+    include_secrets: bool = False
+    include_defaults: bool = False
+    effective: bool = False
+
+    @model_validator(mode="after")
+    def _defaults_not_effective(self) -> Self:
+        if self.include_defaults and self.effective:
+            raise ValueError("--include-defaults cannot be combined with --effective")
+        return self
+
+
+class ConfigImportOptions(BaseModel):
+    include_secrets: bool = False
+    mode: Literal["merge", "replace"] = "merge"
+    dry_run: bool = False
+
+
+class ConfigImportPlan(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    set_config: dict[str, Any] = Field(default_factory=dict)
+    delete_config: list[str] = Field(default_factory=list)
+    set_secrets: dict[str, str] = Field(default_factory=dict)
+    delete_secrets: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+
+
+class ConfigIOService:
+    """Build export payloads and apply validated import plans."""
+
+    def __init__(self, db: Database, config: ConfigService) -> None:
+        self._db = db
+        self._config = config
+
+    def export_payload(self, options: ConfigExportOptions) -> dict[str, Any]:
+        config = self._export_config(options)
+        secrets, warnings = self._export_secrets(options, config)
+        payload: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "tool": "deeptrade",
+            "exported_at": datetime.now(UTC).replace(microsecond=0).isoformat(),
+            "mode": "effective" if options.effective else "persisted",
+            "config": config,
+            "secrets": secrets,
+        }
+        if warnings:
+            payload["warnings"] = warnings
+        return payload
+
+    def plan_import(
+        self,
+        payload: dict[str, Any],
+        options: ConfigImportOptions,
+    ) -> ConfigImportPlan:
+        self._validate_envelope(payload)
+        config = payload.get("config", {})
+        secrets = payload.get("secrets", {})
+        if not isinstance(config, dict):
+            raise ConfigIOError("config must be an object")
+        if not isinstance(secrets, dict):
+            raise ConfigIOError("secrets must be an object")
+
+        set_config = self._validate_config_values(config)
+        set_secrets, warnings = self._validate_secret_values(secrets, options)
+
+        delete_config: list[str] = []
+        delete_secrets: list[str] = []
+        if options.mode == "replace":
+            delete_config = self._persisted_config_keys()
+            delete_secrets = sorted(
+                self._framework_secret_keys(
+                    payload_config=set_config,
+                    payload_secrets=secrets,
+                )
+            )
+
+        return ConfigImportPlan(
+            set_config=set_config,
+            delete_config=delete_config,
+            set_secrets=set_secrets,
+            delete_secrets=delete_secrets,
+            warnings=warnings,
+        )
+
+    def apply_import_plan(self, plan: ConfigImportPlan) -> None:
+        """Apply a plan.
+
+        Non-secret config is written in one DuckDB transaction. Secret writes
+        can hit keyring backends and are not guaranteed to be transactionally
+        tied to DuckDB, matching the design's first-version trade-off.
+        """
+        with self._db.transaction():
+            for key in plan.delete_config:
+                self._config.delete(key)
+            for key, value in plan.set_config.items():
+                self._config.set(key, value)
+
+        for key in plan.delete_secrets:
+            self._config.delete(key)
+        for key, value in plan.set_secrets.items():
+            self._config.set(key, value)
+
+    # --- export helpers -------------------------------------------------
+
+    def _export_config(self, options: ConfigExportOptions) -> dict[str, Any]:
+        if options.effective:
+            cfg = self._config.get_app_config().model_dump(mode="json")
+            return {key: cfg[field] for key, field in _non_secret_key_fields().items()}
+
+        if options.include_defaults:
+            defaults = AppConfig().model_dump(mode="json")
+            out: dict[str, Any] = {}
+            persisted = self._persisted_config_map()
+            for key, field in _non_secret_key_fields().items():
+                out[key] = persisted.get(key, defaults[field])
+            return out
+
+        return self._persisted_config_map()
+
+    def _export_secrets(
+        self,
+        options: ConfigExportOptions,
+        exported_config: dict[str, Any],
+    ) -> tuple[dict[str, dict[str, Any]], list[str]]:
+        out: dict[str, dict[str, Any]] = {}
+        warnings: list[str] = []
+        records = {r.key: r for r in self._config.list_secret_records()}
+        keys = self._framework_secret_keys(payload_config=exported_config, payload_secrets={})
+
+        for key in sorted(keys):
+            record = records.get(key)
+            env_value = os.environ.get(env_var_for(key)) if options.effective else None
+            present = env_value is not None or record is not None
+            value: str | None = None
+            if options.include_secrets and present:
+                if env_value is not None:
+                    value = env_value
+                else:
+                    value = self._config.get(key)
+                    if value is None and record is not None:
+                        warnings.append(f"unreadable_secret:{key}")
+            out[key] = {"present": present, "value": value}
+        return out, warnings
+
+    # --- import validation ---------------------------------------------
+
+    def _validate_envelope(self, payload: dict[str, Any]) -> None:
+        if payload.get("schema_version") != SCHEMA_VERSION:
+            raise ConfigIOError(f"unsupported schema_version: {payload.get('schema_version')!r}")
+        if payload.get("tool") != "deeptrade":
+            raise ConfigIOError("tool must be 'deeptrade'")
+
+    def _validate_config_values(self, config: dict[str, Any]) -> dict[str, Any]:
+        known = set(known_keys())
+        fields = _non_secret_key_fields()
+        out: dict[str, Any] = {}
+        for key, value in config.items():
+            if key not in known or is_secret_key(key):
+                raise ConfigIOError(f"invalid non-secret config key: {key!r}")
+            if key == "llm.providers":
+                self._validate_provider_names(value)
+            field = fields[key]
+            validated = AppConfig(**{field: value})
+            out[key] = validated.model_dump(mode="json")[field]
+        return out
+
+    def _validate_secret_values(
+        self,
+        secrets: dict[str, Any],
+        options: ConfigImportOptions,
+    ) -> tuple[dict[str, str], list[str]]:
+        set_secrets: dict[str, str] = {}
+        warnings: list[str] = []
+        for key, item in secrets.items():
+            if not is_secret_key(key):
+                raise ConfigIOError(f"invalid secret key: {key!r}")
+            if not isinstance(item, dict):
+                raise ConfigIOError(f"secret entry must be an object: {key!r}")
+            value = item.get("value")
+            if not options.include_secrets:
+                if value not in (None, ""):
+                    warnings.append(f"secret_value_ignored:{key}")
+                continue
+            if value in (None, ""):
+                continue
+            if not isinstance(value, str):
+                raise ConfigIOError(f"secret value must be a string: {key!r}")
+            if value.startswith("********"):
+                raise ConfigIOError(f"masked secret values cannot be imported: {key!r}")
+            set_secrets[key] = value
+        return set_secrets, warnings
+
+    @staticmethod
+    def _validate_provider_names(value: Any) -> None:
+        if not isinstance(value, dict):
+            raise ConfigIOError("llm.providers must be an object")
+        normalized: dict[str, str] = {}
+        for name in value:
+            if not isinstance(name, str) or not name or "." in name:
+                raise ConfigIOError(
+                    f"invalid provider name: {name!r}; must be non-empty and contain no '.'"
+                )
+            env_name = name.replace("-", "_")
+            if env_name in normalized:
+                raise ConfigIOError(
+                    f"provider name {name!r} collides with {normalized[env_name]!r} "
+                    "after env-var normalization"
+                )
+            normalized[env_name] = name
+
+    # --- persistence introspection -------------------------------------
+
+    def _persisted_config_map(self) -> dict[str, Any]:
+        known_non_secret = set(_non_secret_key_fields())
+        rows = self._db.fetchall("SELECT key, value_json FROM app_config ORDER BY key")
+        out: dict[str, Any] = {}
+        for key, value_json in rows:
+            if key in known_non_secret:
+                out[key] = json.loads(value_json)
+        return out
+
+    def _persisted_config_keys(self) -> list[str]:
+        return sorted(self._persisted_config_map().keys())
+
+    def _framework_secret_keys(
+        self,
+        *,
+        payload_config: dict[str, Any],
+        payload_secrets: dict[str, Any],
+    ) -> set[str]:
+        keys = {key for key in known_keys() if is_secret_key(key)}
+        current = self._config.get("llm.providers")
+        if isinstance(current, dict):
+            keys.update(f"llm.{name}.api_key" for name in current)
+        payload_providers = payload_config.get("llm.providers")
+        if isinstance(payload_providers, dict):
+            keys.update(f"llm.{name}.api_key" for name in payload_providers)
+        keys.update(key for key in payload_secrets if is_secret_key(key))
+        keys.update(r.key for r in self._config.list_secret_records() if is_secret_key(r.key))
+        return keys
+
+
+def _non_secret_key_fields() -> dict[str, str]:
+    return {
+        "app.timezone": "app_timezone",
+        "app.locale": "app_locale",
+        "app.log_level": "app_log_level",
+        "app.close_after": "app_close_after",
+        "tushare.rps": "tushare_rps",
+        "tushare.timeout": "tushare_timeout",
+        "tushare.max_retries": "tushare_max_retries",
+        "app.profile": "app_profile",
+        "llm.providers": "llm_providers",
+        "llm.audit_full_payload": "llm_audit_full_payload",
+        "llm.replay.enabled": "llm_replay_enabled",
+        "llm.replay.write": "llm_replay_write",
+        "llm.replay.ttl_days": "llm_replay_ttl_days",
+        "report.upload.enabled": "report_upload_enabled",
+        "report.upload.url": "report_upload_url",
+        "report.upload.timeout": "report_upload_timeout",
+    }