ErisPulse 2.8.0.dev1__tar.gz → 2.8.0.dev2__tar.gz

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ErisPulse
-Version: 2.8.0.dev1
+Version: 2.8.0.dev2
 Summary: Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署
 Project-URL: Homepage, https://github.com/ErisPulse/ErisPulse
 Project-URL: Documentation, https://www.erisdev.com#docs
@@ -29,11 +29,16 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: fastapi>=0.116.1
 Requires-Dist: rich>=13.0.0
-Requires-Dist: toml>=0.10.2
+Requires-Dist: tomlkit>=0.15.1
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: websockets>=12.0
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
 Provides-Extra: test
 Requires-Dist: httpx>=0.24.0; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
@@ -44,8 +49,6 @@ Requires-Dist: pytest-xdist>=3.0.0; extra == 'test'
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-![ErisPulse](https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/mascot-hero.png)
-
 # ErisPulse
 
 **Write once, deploy on multiple platforms.**

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/README.pypi.md

@@ -1,5 +1,3 @@
-![ErisPulse](https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/mascot-hero.png)
-
 # ErisPulse
 
 **Write once, deploy on multiple platforms.**

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.8.0-dev.1"
+version = "2.8.0-dev.2"
 description = "Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署"
 readme = "README.pypi.md"
 requires-python = ">=3.10"
@@ -61,13 +61,14 @@ classifiers = [
 
 dependencies = [
     "rich>=13.0.0",
-    "toml>=0.10.2",
-
+    "tomlkit>=0.15.1",
     # network 相关
     "websockets>=12.0",
     "aiohttp>=3.9.0",
     "fastapi>=0.116.1",
     "uvicorn>=0.30.0",
+    # storage 相关（默认 SQLite 后端异步驱动，开箱即用）
+    "aiosqlite>=0.20.0",
 ]
 
 [project.urls]
@@ -79,6 +80,13 @@ Issues = "https://github.com/ErisPulse/ErisPulse/issues"
 Changelog = "https://github.com/ErisPulse/ErisPulse/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
+# 存储后端可选驱动：pip install ErisPulse[mysql] / ErisPulse[postgres]
+mysql = [
+    "aiomysql>=0.2.0",
+]
+postgres = [
+    "asyncpg>=0.29.0",
+]
 test = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/CLI/commands/create.py

@@ -86,7 +86,11 @@ class Main(BaseModule):
     # {text[module.config_hint]}
     @dataclass
     class ConfigClass(BaseConfig):
-        \"\"\"{text[module.config_doc]}\"\"\"
+        \"\"\"
+        {text[module.config_doc]}
+
+        :ivar advanced_threshold: 高级阈值（docstring :ivar: 声明即为字段描述，无需 metadata）
+        \"\"\"
 
         enabled: bool = field(
             default=True,
@@ -94,6 +98,11 @@ class Main(BaseModule):
                 \"description\": {{\"i18n\": \"module.{name}.enabled\", \"default\": \"Enable module\"}},
             }},
         )
+        # example 字段：默认不写入 config.toml（仅记录在 config.full.example，用户按需启用）
+        advanced_threshold: int = field(
+            default=100,
+            metadata={{\"example\": True, \"min\": 0}},
+        )
 
     # {text[module.i18n_hint]}
     class I18nClass(BaseI18n):
@@ -159,6 +168,9 @@ class Main(BaseModule):
             author=\"ErisDev\",
             group=\"default\",
             tags=[\"{name}\"],
+            # 对外服务白名单（可选）：声明后其他模块可经 sdk.module.call() 调用这些方法；
+            # 缺省时公开方法全开放（限制由用户通过 scope.actions 配置）
+            # services=[\"get_welcome_message\"],
         )
 
     @staticmethod
@@ -288,7 +300,11 @@ class {name}(BaseAdapter):
     # {text[adapter.config_hint]}
     @dataclass
     class ConfigClass(BaseConfig):
-        \"\"\"{text[adapter.config_doc]}\"\"\"
+        \"\"\"
+        {text[adapter.config_doc]}
+
+        :ivar request_timeout: 请求超时秒数（docstring :ivar: 声明即为字段描述，无需 metadata）
+        \"\"\"
 
         endpoint: str = field(
             default="https://api.example.com",
@@ -307,6 +323,11 @@ class {name}(BaseAdapter):
                 "ui": {{"widget": "password", "group": "basic", "order": 2}},
             }},
         )
+        # example 字段：默认不写入 config.toml（仅记录在 config.full.example，用户按需启用）
+        request_timeout: int = field(
+            default=30,
+            metadata={{"example": True, "min": 1, "max": 300}},
+        )
 
     # {text[adapter.i18n_hint]}
     class I18nClass(BaseI18n):

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/CLI/commands/init.py

@@ -175,128 +175,16 @@ class InitCommand(Command):
         """
         生成完整的配置示例文本
 
-        配置注释跟随 CLI 语言（缺失语言回退英文），
-        文案键集中于 ``scaffold_text`` 的 ``cfg.*`` 键族维护。
+        生成逻辑收归 ``ErisPulse.runtime.example_config``（框架运行与 CLI 共用：
+        含自维护首行标记、静态框架段与已安装组件声明式段）。此处仅保留调用入口。
 
         :param adapter_list: [list] 适配器名称列表 (默认: None)
         :return: [str] 完整配置示例字符串
         """
-        from ..utils.scaffold_text import ScaffoldText
-
-        st = ScaffoldText()
-        lines = [
-            st.t("cfg.header.title"),
-            st.t("cfg.header.desc"),
-            st.t("cfg.header.usage"),
-            "",
-            st.t("cfg.section.server"),
-            "",
-            "[ErisPulse.server]",
-            f'host = "0.0.0.0"              # {st.t("cfg.server.host")}',
-            f"port = 8000                   # {st.t('cfg.server.port')}",
-            f"auto_start = true             # {st.t('cfg.server.auto_start')}",
-            f'ssl_certfile = "config/ssl/cert.pem"   # {st.t("cfg.server.ssl_certfile")}',
-            f'ssl_keyfile = "config/ssl/key.pem"    # {st.t("cfg.server.ssl_keyfile")}',
-            st.t("cfg.server.ssl_inline_hint"),
-            '# ssl_cert = """-----BEGIN CERTIFICATE-----',
-            "# ...",
-            '# -----END CERTIFICATE-----"""',
-            '# ssl_key = """-----BEGIN PRIVATE KEY-----',
-            "# ...",
-            '# -----END PRIVATE KEY-----"""',
-            "",
-            st.t("cfg.section.logger"),
-            "",
-            "[ErisPulse.logger]",
-            f'level = "INFO"                # {st.t("cfg.logger.level")}',
-            f"log_files = []                # {st.t('cfg.logger.log_files')}",
-            f'log_dir = ""                  # {st.t("cfg.logger.log_dir")}',
-            f'log_rotation = "size"         # {st.t("cfg.logger.log_rotation")}',
-            f"log_max_size_mb = 10          # {st.t('cfg.logger.log_max_size_mb')}",
-            f"log_backup_count = 5          # {st.t('cfg.logger.log_backup_count')}",
-            f'log_rotation_when = "midnight"  # {st.t("cfg.logger.log_rotation_when")}',
-            f"memory_limit = 1000           # {st.t('cfg.logger.memory_limit')}",
-            "",
-            st.t("cfg.section.storage"),
-            "",
-            "[ErisPulse.storage]",
-            f"use_global_db = false         # {st.t('cfg.storage.use_global_db')}",
-            "",
-            st.t("cfg.section.event"),
-            "",
-            "[ErisPulse.event.message]",
-            f"ignore_self = true            # {st.t('cfg.event.ignore_self')}",
-            "",
-            "[ErisPulse.event.command]",
-            f'prefix = "/"                  # {st.t("cfg.command.prefix")}',
-            f"case_sensitive = true         # {st.t('cfg.command.case_sensitive')}",
-            f"allow_space_prefix = false    # {st.t('cfg.command.allow_space_prefix')}",
-            f"must_at_bot = false           # {st.t('cfg.command.must_at_bot')}",
-            "",
-            st.t("cfg.section.framework"),
-            "",
-            "[ErisPulse.framework]",
-            f"enable_lazy_loading = true     # {st.t('cfg.framework.enable_lazy_loading')}",
-            f'plugins_dir = "plugins"        # {st.t("cfg.framework.plugins_dir")}',
-            f"uninit_timeout = 30            # {st.t('cfg.framework.uninit_timeout')}",
-            f"                                {st.t('cfg.framework.uninit_timeout_line1')}",
-            f"                                {st.t('cfg.framework.uninit_timeout_line2')}",
-            f"strict_mode = false            # {st.t('cfg.framework.strict_mode')}",
-            f"strict_mode_exceptions = {{ modules = [], adapters = [] }}  # {st.t('cfg.framework.strict_mode_exceptions')}",
-            f"handler_max_concurrency = 64   # {st.t('cfg.framework.handler_max_concurrency')}",
-            f"proactive_gc_interval = 300    # {st.t('cfg.framework.proactive_gc_interval')}",
-            f"proactive_gc_generation = 2    # {st.t('cfg.framework.proactive_gc_generation')}",
-            f"proactive_gc_full_every = 10   # {st.t('cfg.framework.proactive_gc_full_every')}",
-            f"proactive_gc_memory_growth_mb = 100  # {st.t('cfg.framework.proactive_gc_memory_growth_mb')}",
-            f"proactive_gc_idle_only = true  # {st.t('cfg.framework.proactive_gc_idle_only')}",
-            f"proactive_gc_gen0_min = 100    # {st.t('cfg.framework.proactive_gc_gen0_min')}",
-            f"offline_bot_expiry = 3600      # {st.t('cfg.framework.offline_bot_expiry')}",
-            "",
-            st.t("cfg.section.router"),
-            "",
-            "[ErisPulse.router.cors]",
-            "enabled = false",
-            'allow_origins = ["*"]',
-            'allow_methods = ["*"]',
-            'allow_headers = ["*"]',
-            "allow_credentials = false",
-            "max_age = 600",
-            "",
-            "[ErisPulse.router.security]",
-            "enabled = false",
-            "",
-            "[ErisPulse.router.security.headers]",
-            'X-Content-Type-Options = "nosniff"',
-            'X-Frame-Options = "DENY"',
-            "",
-            st.t("cfg.section.adapter_status"),
-            "",
-            "[ErisPulse.adapters.status]",
-        ]
-
-        if adapter_list:
-            lines.extend(f"# {adapter} = false" for adapter in adapter_list)
-        else:
-            lines.extend(
-                [
-                    "# yunhu = false",
-                    "# telegram = false",
-                    "# onebot11 = false",
-                ]
-            )
+        from ErisPulse.runtime.example_config import render_full_example
 
-        lines.extend(
-            [
-                "",
-                st.t("cfg.section.module_status"),
-                "",
-                "[ErisPulse.modules.status]",
-                "# MyModule = true",
-                "",
-            ]
-        )
+        return render_full_example(adapter_list=adapter_list)
 
-        return "\n".join(lines)
 
     async def _fetch_available_adapters(self):
         """

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/CLI/utils/config_wizard.py

@@ -524,6 +524,9 @@ def fill_config_fields(config_class, current_values: dict) -> dict:
     """
     渲染整个配置类的表单并收集用户输入
 
+    ``example`` 字段不进入向导（默认值不落盘，仅记录在 config.full.example）；
+    嵌套 dataclass 字段（schema 含 ``fields`` 子树）递归渲染为子表单。
+
     :param config_class: dataclass 配置类
     :param current_values: 当前存储的配置字典（作为各字段初值）
     :return: 收集后的配置字典
@@ -531,12 +534,31 @@ def fill_config_fields(config_class, current_values: dict) -> dict:
     from ErisPulse.Core.Bases.config_schema import resolve_config_schema
 
     schema = resolve_config_schema(config_class)
-    current_store = dict(current_values or {})
-    values = dict(current_store)
-    for name, field_schema in _sort_fields(schema.get("fields", {})):
+    values = dict(current_values or {})
+    _fill_from_schema_fields(schema.get("fields", {}), values)
+    return values
+
+
+def _fill_from_schema_fields(fields_dict: dict, values: dict) -> None:
+    """
+    {!--< internal-use >!--}
+    按 schema 字段树渲染表单并就地收集到 values（嵌套子树递归）
+    """
+    current_store = dict(values)
+    for name, field_schema in _sort_fields(fields_dict):
+        if field_schema.get("example") and name not in current_store:
+            # example 字段仅当用户已显式设置时保留原值，不主动询问
+            continue
+        nested_fields = field_schema.get("fields")
+        if isinstance(nested_fields, dict):
+            sub_values = current_store.get(name)
+            if not isinstance(sub_values, dict):
+                sub_values = {}
+            _fill_from_schema_fields(nested_fields, sub_values)
+            values[name] = sub_values
+            continue
         has_value = name in current_store
         values[name] = _prompt_field(name, field_schema, values.get(name), has_value)
-    return values
 
 
 def _validate_dataclass(config_class, data: dict) -> list[str]:

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/CLI/utils/scaffold_text.py

@@ -96,6 +96,8 @@ _EN_FALLBACK: dict[str, str] = {
     "cfg.section.router": "# ==================== Router ====================",
     "cfg.section.adapter_status": "# ==================== Adapter Status ====================",
     "cfg.section.module_status": "# ==================== Module Status ====================",
+    "cfg.section.components": "# ==================== Installed Components (declarative, auto-generated) ====================",
+    "cfg.section.components_hint": "# Rendered from each installed adapter/module ConfigClass; example: fields only live here (not auto-persisted to config.toml)",
     "cfg.server.host": "Listen address",
     "cfg.server.port": "Listen port",
     "cfg.server.auto_start": "Auto start HTTP server (set false for pure WS/polling adapters)",
@@ -112,6 +114,9 @@ _EN_FALLBACK: dict[str, str] = {
     "cfg.logger.log_rotation_when": "date mode: rotation period S/M/H/D/midnight",
     "cfg.logger.memory_limit": "In-memory log entries limit",
     "cfg.storage.use_global_db": "Use global database",
+    "cfg.storage.backend": "Storage backend: \"sqlite\" / \"mysql\" / \"postgres\"",
+    "cfg.storage.mysql": "MySQL connection params (effective when backend = \"mysql\"), requires: pip install ErisPulse[mysql]",
+    "cfg.storage.postgres": "PostgreSQL connection params (effective when backend = \"postgres\"), requires: pip install ErisPulse[postgres]",
     "cfg.event.ignore_self": "Ignore self messages",
     "cfg.command.prefix": "Command prefix",
     "cfg.command.case_sensitive": "Case sensitive",
@@ -196,6 +201,8 @@ _TRANSLATIONS: dict[str, dict[str, str]] = {
     "cfg.section.router": "# ==================== 路由增强 ====================",
     "cfg.section.adapter_status": "# ==================== 适配器状态 ====================",
     "cfg.section.module_status": "# ==================== 模块状态 ====================",
+    "cfg.section.components": "# ==================== 已安装组件（声明式自动生成） ====================",
+    "cfg.section.components_hint": "# 由各已安装适配器/模块的 ConfigClass 渲染；example: 字段仅记录于此（不会自动写入 config.toml）",
     "cfg.server.host": "监听地址",
     "cfg.server.port": "监听端口",
     "cfg.server.auto_start": "是否自动启动 HTTP 服务器 (纯 WS/轮询适配器可设 false)",
@@ -211,6 +218,9 @@ _TRANSLATIONS: dict[str, dict[str, str]] = {
     "cfg.logger.log_rotation_when": "date 模式轮转周期: S/M/H/D/midnight",
     "cfg.logger.memory_limit": "内存日志条数上限",
     "cfg.storage.use_global_db": "是否使用全局数据库",
+    "cfg.storage.backend": "存储后端: \"sqlite\" / \"mysql\" / \"postgres\"",
+    "cfg.storage.mysql": "MySQL 连接参数（backend = \"mysql\" 时生效），需安装: pip install ErisPulse[mysql]",
+    "cfg.storage.postgres": "PostgreSQL 连接参数（backend = \"postgres\" 时生效），需安装: pip install ErisPulse[postgres]",
     "cfg.event.ignore_self": "忽略自身消息",
     "cfg.command.prefix": "命令前缀",
     "cfg.command.case_sensitive": "区分大小写",

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/Core/Bases/__init__.py

@@ -9,7 +9,8 @@ from .converter import BaseConverter
 from .send_rules import SendContext
 from .send_builder import SendBuilder, BatchContext
 from .module import BaseModule, ModuleMeta
-from .storage import BaseStorage, BaseQueryBuilder
+from .storage import AsyncBridge, BaseStorage, BaseQueryBuilder
+from .sql_base import AlterTableBuilder, SQLDialect, SQLQueryBuilder, SQLStorageBase
 from .kv_builder import KVQueryBuilder
 from .errors import (
     ErisPulseError,
@@ -17,6 +18,14 @@ from .errors import (
     ClientConnectionError,
     ClientTimeoutError,
     HTTPStatusError,
+    InteractionError,
+    ModuleCallError,
+    ModuleCallTimeoutError,
+    ModuleError,
+    ModuleNotAvailableError,
+    ServiceNotProvidedError,
+    StorageError,
+    StorageUnreachableError,
     WebSocketError,
     WebSocketDisconnect,
 )
@@ -66,16 +75,30 @@ __all__ = [
     "I18nConfig",
     # i18n 单键声明
     "I18nKey",
+    "AsyncBridge",
+    "InteractionError",
     "KVQueryBuilder",
+    "ModuleCallError",
+    "ModuleCallTimeoutError",
+    "ModuleError",
     "ModuleMeta",
+    "ModuleNotAvailableError",
     "RequestDSL",
     "SendBuilder",
     "SendContext",
     "SendDSL",
+    "ServiceNotProvidedError",
     "SseEmitter",
+    "StorageError",
+    "StorageUnreachableError",
     "WSMessage",
     "WebSocketConnection",
     "WebSocketConnectionBase",
     "WebSocketDisconnect",
     "WebSocketError",
+    # SQL 存储基类（自定义 SQL 后端扩展用）
+    "AlterTableBuilder",
+    "SQLDialect",
+    "SQLQueryBuilder",
+    "SQLStorageBase",
 ]

{erispulse-2.8.0.dev1 → erispulse-2.8.0.dev2}/src/ErisPulse/Core/Bases/adapter.py

@@ -162,6 +162,37 @@ def _wrap_to_task(result: Any):
     return asyncio.ensure_future(_const())
 
 
+def _append_send_receipt(ledger: list, response: Any, ctx: dict) -> None:
+    """
+    {!--< internal-use >!--}
+    从发送响应提取回执并记入消息事务账本
+
+    仅当响应为 dict 且含非空 ``message_id`` 时记录（标准 API 响应格式）；
+    消息事务撤回时按账本逆序调用适配器 ``delete_message``。
+
+    :param ledger: 当前事务的账本列表（send_receipts ContextVar 值）
+    :param response: 发送方法返回的响应（标准格式为 dict）
+    :param ctx: 发送上下文（platform / bot_id / trace_id 等）
+    """
+    if not isinstance(response, dict):
+        return
+    message_id = response.get("message_id")
+    if not message_id:
+        data = response.get("data")
+        if isinstance(data, dict):
+            message_id = data.get("message_id")
+    if not message_id:
+        return
+    ledger.append(
+        {
+            "platform": str(ctx.get("platform") or ""),
+            "bot_id": str(ctx.get("bot_id") or ""),
+            "message_id": str(message_id),
+            "trace_id": ctx.get("trace_id"),
+        }
+    )
+
+
 def _wrap_send_method(method_name: str, original_method: Callable, send_dsl: "SendDSL"):
     """
     为发送方法注入生命周期钩子
@@ -198,16 +229,50 @@ def _wrap_send_method(method_name: str, original_method: Callable, send_dsl: "Se
         if isinstance(result, SendDSL):
             return result
 
+        # 非 Task 同步返回值：直接记入消息事务账本后原样返回
         if not isinstance(result, asyncio.Task):
+            from ...runtime.context import send_receipts as _sr
+
+            _sync_ledger = _sr.get()
+            if _sync_ledger is not None:
+                _append_send_receipt(
+                    _sync_ledger,
+                    result,
+                    {
+                        "platform": getattr(send_dsl._adapter, "_platform", "") or "",
+                        "method": method_name,
+                        "detail_type": send_dsl._target_type or "",
+                        "target_id": send_dsl._target_id or "",
+                        "bot_id": send_dsl._account_id or "",
+                    },
+                )
             return result
 
         platform = getattr(send_dsl._adapter, "_platform", "") or ""
+
+        # 链路追踪：出站发送携带当前事件的 trace-id（不在事件上下文内时为 None）
+        from ...runtime.context import current_trace_id, send_receipts
+
+        _trace_id = current_trace_id.get()
+        # 消息事务账本：仅在 message_tx 事务内记账（None = 事务外零开销）
+        _ledger = send_receipts.get()
+
+        # 消息文本预览（截断）：供收件箱（transcript）/ 审计类钩子使用
+        _preview = ""
+        if args:
+            _preview = str(args[0])
+            if len(_preview) > LOG_MESSAGE_TRUNCATE_CHARS:
+                _preview = _preview[:LOG_MESSAGE_TRUNCATE_CHARS] + "..."
+
         send_ctx = {
             "platform": platform,
             "method": method_name,
             "detail_type": send_dsl._target_type or "",
             "target_id": send_dsl._target_id or "",
             "bot_id": send_dsl._account_id or "",
+            "trace_id": _trace_id,
+            # 消息文本预览（截断），供收件箱 / 审计类钩子使用
+            "preview": _preview,
         }
 
         # 循环依赖：Core/adapter.py 顶层导入本模块（BaseAdapter）
@@ -216,13 +281,14 @@ def _wrap_send_method(method_name: str, original_method: Callable, send_dsl: "Se
         target_type = send_dsl._target_type or ""
         target_id = send_dsl._target_id or ""
         log_target = f"{target_type}/{target_id}" if target_type and target_id else target_id or "?"
+        _trace_tag = f" [trace:{_trace_id}]" if _trace_id else ""
         if method_name in ("Text", "Markdown", "Html") and args:
             content = str(args[0])
             if len(content) > LOG_MESSAGE_TRUNCATE_CHARS:
                 content = content[:LOG_MESSAGE_TRUNCATE_CHARS] + "..."
-            _msg_logger.event(f"[Send] {platform}/{method_name} -> {log_target}: {content}")
+            _msg_logger.event(f"[Send] {platform}/{method_name} -> {log_target}{_trace_tag}: {content}")
         else:
-            _msg_logger.event(f"[Send] {platform}/{method_name} -> {log_target}")
+            _msg_logger.event(f"[Send] {platform}/{method_name} -> {log_target}{_trace_tag}")
 
         # 预判是否有生命周期监听者：无监听时跳过 Task 创建与 emit 调度，
         # 避免每条发送消息都无条件 spawn 两个后台任务
@@ -242,6 +308,15 @@ def _wrap_send_method(method_name: str, original_method: Callable, send_dsl: "Se
 
             spawn_background(_emit_hooks())
 
+        # 消息事务：发送完成（含重试终态）后从响应提取 message_id 记入账本
+        if _ledger is not None:
+
+            def _record_receipt(t: "asyncio.Task") -> None:
+                try:
+                    _append_send_receipt(_ledger, t.result(), send_ctx)
+                except Exception:
+                    pass
+
         # 若附加了发送规则，用规则执行器统一包装 Task
         if _has_rules(send_dsl):
             from .send_rules import apply_send_rules
@@ -275,11 +350,15 @@ def _wrap_send_method(method_name: str, original_method: Callable, send_dsl: "Se
             # 不绑定到首次内部 result（避免失败重试时提前触发）
             if _has_sent_hooks:
                 wrapped.add_done_callback(lambda t: asyncio.ensure_future(_emit_hooks_done(t)))
+            if _ledger is not None:
+                wrapped.add_done_callback(_record_receipt)
             return wrapped
 
         # 无规则：保持原有行为，message.sent 在单次发送完成后触发
         if _has_sent_hooks:
             result.add_done_callback(lambda t: asyncio.ensure_future(_emit_hooks_done(t)))
+        if _ledger is not None:
+            result.add_done_callback(_record_receipt)
         return result
 
     return hooked
@@ -2112,18 +2191,15 @@ class BaseAdapter(ABC):
 
         if self.ConfigClass is None:
             return
-        from .config_schema import (
-            dataclass_to_defaults_dict,
-            dataclass_to_toml_with_comments,
-        )
+        from .config_schema import dataclass_to_toml_with_comments
 
         key = self._get_config_key()
         data = config_mgr.getConfig(key)
 
         if data is None:
-            data = dataclass_to_defaults_dict(self.ConfigClass)
+            # 模板以带注释文本直接落盘（注释保留写入），字段描述对用户可见
             toml_str = dataclass_to_toml_with_comments(self.ConfigClass)
-            config_mgr.setConfig(key, data, immediate=True)
+            config_mgr.setConfigTemplate(key, toml_str, immediate=True)
             self._get_logger().info(i18n.t("core.adapter.config_template_generated", key=key, toml=toml_str))
 
     def _ensure_i18n_registered(self):