ErisPulse-GovReport 0.1.0__py3-none-any.whl

GovReport/Config.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass, field
+
+from ErisPulse.Core.Bases import BaseConfig
+
+
+@dataclass
+class GovReportConfig(BaseConfig):
+
+    enabled: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "GovReport.enabled", "default": "是否启用模块"},
+            "ui": {"widget": "switch", "group": "basic", "order": 1},
+        },
+    )
+    collect_command_calls: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "GovReport.collect_command_calls", "default": "采集命令执行记录（command.executed）"},
+            "ui": {"widget": "switch", "group": "collect", "order": 2},
+        },
+    )
+    collect_blocked: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "GovReport.collect_blocked", "default": "采集事件拦截记录（中间件否决 / 作用域拦截）"},
+            "ui": {"widget": "switch", "group": "collect", "order": 3},
+        },
+    )
+    retention_days: int = field(
+        default=30,
+        metadata={
+            "description": {"i18n": "GovReport.retention_days", "default": "记录保留天数（0 永久保留，启动与每日清理）"},
+            "ui": {"widget": "number", "group": "collect", "order": 4},
+        },
+    )
+    top_n: int = field(
+        default=10,
+        metadata={
+            "description": {"i18n": "GovReport.top_n", "default": "统计报表单次展示的最大条目数"},
+            "ui": {"widget": "number", "group": "report", "order": 5},
+        },
+    )
+    render_card: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "GovReport.render_card", "default": "报表用 Takumi 渲染为卡片（不可用时降级文本）"},
+            "ui": {"widget": "switch", "group": "render", "order": 6},
+        },
+    )
+    theme: str = field(
+        default="auto",
+        metadata={
+            "description": {"i18n": "GovReport.theme", "default": "卡片配色 (auto=按时间自动切深浅色)"},
+            "ui": {
+                "widget": "select",
+                "options": ["auto", "light", "dark"],
+                "group": "render",
+                "order": 7,
+            },
+        },
+    )

GovReport/Core.py

@@ -0,0 +1,209 @@
+import asyncio
+import time
+
+from ErisPulse import i18n, sdk
+from ErisPulse.Core import Depends
+from ErisPulse.Core.Bases import BaseModule, ModuleMeta
+from ErisPulse.Core.Event import command
+from ErisPulse.loaders import ModuleLoadStrategy
+
+from .Config import GovReportConfig
+from .I18n import GovReportI18n
+from .Models import BlockEvent, CommandCall
+from .Stats import GovStatsService, parse_window
+from .Visualizer import CardVisualizer
+
+
+def get_stats_service(event):
+    from ErisPulse import module as module_mgr
+
+    inst = module_mgr.get("GovReport")
+    if inst is None:
+        raise RuntimeError("GovReport not loaded")
+    return inst._stats
+
+
+class Main(BaseModule):
+
+    ConfigClass = GovReportConfig
+    I18nClass = GovReportI18n
+
+    def __init__(self):
+        self.sdk = sdk
+        self.logger = sdk.logger.get_child("GovReport")
+        self._stats = GovStatsService(self.logger)
+        self._viz = CardVisualizer(sdk, self.logger)
+        self._daily_task = None
+
+    @staticmethod
+    def get_load_strategy() -> ModuleLoadStrategy:
+        return ModuleLoadStrategy(lazy_load=False, priority=20)
+
+    @staticmethod
+    def get_meta() -> ModuleMeta:
+        return ModuleMeta(
+            name="GovReport",
+            description="治理观测模块：采集命令执行与事件拦截记录，输出统计报表与配额消耗",
+            version="0.1.0",
+            author="ErisPulse-devs",
+            group="运维",
+            tags=["治理", "统计", "ORM", "观测"],
+            min_sdk_version="2.9.0",
+        )
+
+    async def on_load(self, event: dict) -> bool:
+        if not self.cfg.enabled:
+            self.logger.info("治理观测未启用（enabled=false）")
+            return True
+
+        await CommandCall.create_table()
+        await BlockEvent.create_table()
+        await self._stats.purge_expired(self.cfg.retention_days)
+
+        self._register_collectors()
+        self._register_commands()
+        self._daily_task = self.spawn(self._daily_purge_loop())
+        self.logger.info(i18n.t("GovReport.module_loaded", event=event))
+        return True
+
+    async def on_unload(self, event: dict) -> bool:
+        if self._daily_task is not None:
+            self._daily_task.cancel()
+            await asyncio.gather(self._daily_task, return_exceptions=True)
+            self._daily_task = None
+        self.logger.info(i18n.t("GovReport.module_unloaded", event=event))
+        return True
+
+    async def _daily_purge_loop(self):
+        while True:
+            await asyncio.sleep(86400)
+            try:
+                await self._stats.purge_expired(self.cfg.retention_days)
+            except Exception as e:
+                self.logger.warning(f"每日清理失败: {e}")
+
+    def _register_collectors(self):
+        @sdk.lifecycle.on("command.executed")
+        async def _on_command_executed(data):
+            if not self.cfg.collect_command_calls:
+                return
+            try:
+                await CommandCall.create(
+                    ts=time.time(),
+                    command=str(data.get("command", ""))[:128],
+                    platform=str(data.get("platform", ""))[:64],
+                    user_id=str(data.get("user_id", ""))[:128],
+                    success=bool(data.get("success")),
+                    error=str(data.get("error", "") or "")[:255],
+                )
+            except Exception as e:
+                self.logger.warning(f"记录命令执行失败: {e}")
+
+        @sdk.lifecycle.on("adapter.event.blocked")
+        async def _on_event_blocked(data):
+            if not self.cfg.collect_blocked:
+                return
+            raw = data.get("event") or {}
+            try:
+                await BlockEvent.create(
+                    ts=time.time(),
+                    source="middleware",
+                    middleware=str(data.get("middleware", ""))[:128],
+                    platform=str(data.get("platform", ""))[:64],
+                    detail_type=str(data.get("detail_type", ""))[:64],
+                    user_id=str(raw.get("user_id", "") or "")[:128],
+                )
+            except Exception as e:
+                self.logger.warning(f"记录拦截事件失败: {e}")
+
+        @sdk.lifecycle.on("scope.blocked")
+        async def _on_scope_blocked(data):
+            if not self.cfg.collect_blocked:
+                return
+            try:
+                await BlockEvent.create(
+                    ts=time.time(),
+                    source="scope",
+                    dimension=str(data.get("dimension", ""))[:16],
+                    module=str(data.get("module", "") or "")[:128],
+                    platform=str(data.get("platform", ""))[:64],
+                    user_id=str(data.get("user_id", "") or "")[:128],
+                    session_id=str(data.get("session_id", "") or "")[:128],
+                )
+            except Exception as e:
+                self.logger.warning(f"记录作用域拦截失败: {e}")
+
+    async def _reply_card(self, event, html, fallback_text: str):
+        if self.cfg.render_card:
+            png = await self._viz.render(html, theme=self.cfg.theme)
+            if png is not None:
+                try:
+                    await event.reply(png, method="Image")
+                    return
+                except Exception as e:
+                    self.logger.warning(f"图片回复失败，降级文本: {e}")
+        await event.reply(fallback_text)
+
+    def _register_commands(self):
+        @command("gov", master=True, help="治理观测")
+        async def gov_handler(event):
+            await event.reply(
+                "用法: /gov stats [窗口] | /gov user <用户ID> [窗口] | /gov blocked [窗口] | "
+                "/gov usage | /gov list [命令] | /gov purge <天数>"
+            )
+
+        @command("gov stats", master=True, help="命令执行统计", args="[window:str=24h]")
+        async def gov_stats_handler(event, window: str = "24h", stats=Depends(get_stats_service)):
+            secs = parse_window(window)
+            if secs is None:
+                await event.reply(i18n.t("GovReport.invalid_window", window=window))
+                return
+            await self._reply_card(
+                event,
+                await stats.command_stats_card(window, self.cfg.top_n, self._viz),
+                await stats.command_stats(secs, window, self.cfg.top_n),
+            )
+
+        @command("gov user", master=True, help="单用户统计", args="<user_id:str> [window:str=24h]")
+        async def gov_user_handler(event, user_id: str, window: str = "24h"):
+            secs = parse_window(window)
+            if secs is None:
+                await event.reply(i18n.t("GovReport.invalid_window", window=window))
+                return
+            await event.reply(await self._stats.user_stats(user_id, secs, window, self.cfg.top_n))
+
+        @command("gov blocked", master=True, help="拦截统计", args="[window:str=24h]")
+        async def gov_blocked_handler(event, window: str = "24h"):
+            secs = parse_window(window)
+            if secs is None:
+                await event.reply(i18n.t("GovReport.invalid_window", window=window))
+                return
+            await self._reply_card(
+                event,
+                await self._stats.blocked_stats_card(window, self.cfg.top_n, self._viz),
+                await self._stats.blocked_stats(secs, window, self.cfg.top_n),
+            )
+
+        @command("gov usage", master=True, help="配额消耗报表")
+        async def gov_usage_handler(event):
+            await self._reply_card(
+                event,
+                await self._stats.usage_report_card(self._viz),
+                await self._stats.usage_report(),
+            )
+
+        @command("gov list", master=True, help="治理声明清单", args="[cmd:str]")
+        async def gov_list_handler(event, cmd: str = ""):
+            await self._reply_card(
+                event,
+                self._stats.governance_list_card(cmd or None, self._viz),
+                self._stats.governance_list(cmd or None),
+            )
+
+        @command("gov purge", master=True, help="清理旧记录", args="<days:int>")
+        async def gov_purge_handler(event, days: int):
+            if days <= 0:
+                await event.reply(i18n.t("GovReport.invalid_window", window=str(days)))
+                return
+            calls, blocks = await self._stats.purge(days)
+            await event.reply(i18n.t("GovReport.purge_done", calls=calls, blocks=blocks, days=days))

GovReport/I18n.py

@@ -0,0 +1,173 @@
+from ErisPulse.Core.Bases import BaseI18n, I18nKey
+
+
+class GovReportI18n(BaseI18n):
+
+    enabled: I18nKey = I18nKey(
+        default="Enable module",
+        zh_CN="是否启用模块",
+        zh_TW="是否啟用模組",
+        en="Enable module",
+        ja="モジュールを有効化",
+        ru="Включить модуль",
+    )
+    collect_command_calls: I18nKey = I18nKey(
+        default="Collect command execution records",
+        zh_CN="采集命令执行记录（command.executed）",
+        zh_TW="採集命令執行記錄（command.executed）",
+        en="Collect command execution records",
+        ja="コマンド実行記録を収集",
+        ru="Собирать записи выполнения команд",
+    )
+    collect_blocked: I18nKey = I18nKey(
+        default="Collect blocked event records (middleware veto / scope)",
+        zh_CN="采集事件拦截记录（中间件否决 / 作用域拦截）",
+        zh_TW="採集事件攔截記錄（中介軟體否決 / 作用域攔截）",
+        en="Collect blocked event records (middleware veto / scope)",
+        ja="ブロック記録を収集（ミドルウェア拒否 / スコープ）",
+        ru="Собирать записи блокировки событий",
+    )
+    retention_days: I18nKey = I18nKey(
+        default="Retention days (0 = keep forever)",
+        zh_CN="记录保留天数（0 永久保留，启动与每日清理）",
+        zh_TW="記錄保留天數（0 永久保留，啟動與每日清理）",
+        en="Retention days (0 = keep forever)",
+        ja="保持日数（0 で無期限保持）",
+        ru="Срок хранения в днях (0 = бессрочно)",
+    )
+    top_n: I18nKey = I18nKey(
+        default="Max entries shown in one report",
+        zh_CN="统计报表单次展示的最大条目数",
+        zh_TW="統計報表單次展示的最大條目數",
+        en="Max entries shown in one report",
+        ja="レポート1回の最大表示件数",
+        ru="Максимум записей в одном отчёте",
+    )
+    render_card: I18nKey = I18nKey(
+        default="Render reports as image cards via Takumi (fallback to text)",
+        zh_CN="报表用 Takumi 渲染为卡片（不可用时降级文本）",
+        zh_TW="報表用 Takumi 渲染為卡片（不可用時降級文本）",
+        en="Render reports as image cards via Takumi (fallback to text)",
+        ja="レポートを Takumi でカード画像化（不可時はテキスト）",
+        ru="Рендер отчётов в карточки через Takumi (иначе текст)",
+    )
+    theme: I18nKey = I18nKey(
+        default="Card color theme (auto = light/dark by time)",
+        zh_CN="卡片配色 (auto=按时间自动切深浅色)",
+        zh_TW="卡片配色 (auto=按時間自動切深淺色)",
+        en="Card color theme (auto = light/dark by time)",
+        ja="カード配色（auto=時間で自動切替）",
+        ru="Тема карточек (auto = светлая/тёмная по времени)",
+    )
+    module_loaded: I18nKey = I18nKey(
+        default="GovReport loaded: {event}",
+        zh_CN="治理观测已加载: {event}",
+        zh_TW="治理觀測已載入: {event}",
+        en="GovReport loaded: {event}",
+        ja="GovReport を読み込みました: {event}",
+        ru="GovReport загружен: {event}",
+    )
+    module_unloaded: I18nKey = I18nKey(
+        default="GovReport unloaded: {event}",
+        zh_CN="治理观测已卸载: {event}",
+        zh_TW="治理觀測已卸載: {event}",
+        en="GovReport unloaded: {event}",
+        ja="GovReport を解除しました: {event}",
+        ru="GovReport выгружен: {event}",
+    )
+    stats_header: I18nKey = I18nKey(
+        default="Command stats in last {window}: total {total}, success {ok}, failed {failed}, deprecated uses {dep}",
+        zh_CN="近 {window} 命令统计：共 {total} 次，成功 {ok}，失败 {failed}，废弃命令使用 {dep} 次",
+        zh_TW="近 {window} 命令統計：共 {total} 次，成功 {ok}，失敗 {failed}，廢棄命令使用 {dep} 次",
+        en="Command stats in last {window}: total {total}, success {ok}, failed {failed}, deprecated uses {dep}",
+        ja="直近 {window} のコマンド統計：合計 {total}、成功 {ok}、失敗 {failed}、非推奨使用 {dep}",
+        ru="Статистика команд за {window}: всего {total}, успешно {ok}, ошибок {failed}, устаревших {dep}",
+    )
+    stats_empty: I18nKey = I18nKey(
+        default="No command records in window {window}",
+        zh_CN="窗口 {window} 内没有命令记录",
+        zh_TW="視窗 {window} 內沒有命令記錄",
+        en="No command records in window {window}",
+        ja="期間 {window} にコマンド記録がありません",
+        ru="За период {window} записей команд нет",
+    )
+    user_header: I18nKey = I18nKey(
+        default="User {user} in last {window}: total {total}, success {ok}, failed {failed}",
+        zh_CN="用户 {user} 近 {window}：共 {total} 次，成功 {ok}，失败 {failed}",
+        zh_TW="用戶 {user} 近 {window}：共 {total} 次，成功 {ok}，失敗 {failed}",
+        en="User {user} in last {window}: total {total}, success {ok}, failed {failed}",
+        ja="ユーザー {user} 直近 {window}：合計 {total}、成功 {ok}、失敗 {failed}",
+        ru="Пользователь {user} за {window}: всего {total}, успешно {ok}, ошибок {failed}",
+    )
+    user_empty: I18nKey = I18nKey(
+        default="User {user} has no records in window {window}",
+        zh_CN="用户 {user} 在窗口 {window} 内没有记录",
+        zh_TW="用戶 {user} 在視窗 {window} 內沒有記錄",
+        en="User {user} has no records in window {window}",
+        ja="ユーザー {user} は期間 {window} に記録がありません",
+        ru="У пользователя {user} нет записей за {window}",
+    )
+    blocked_header: I18nKey = I18nKey(
+        default="Blocked events in last {window}: total {total}",
+        zh_CN="近 {window} 拦截统计：共 {total} 次",
+        zh_TW="近 {window} 攔截統計：共 {total} 次",
+        en="Blocked events in last {window}: total {total}",
+        ja="直近 {window} のブロック統計：合計 {total}",
+        ru="Блокировки за {window}: всего {total}",
+    )
+    blocked_empty: I18nKey = I18nKey(
+        default="No blocked events in window {window}",
+        zh_CN="窗口 {window} 内没有拦截记录",
+        zh_TW="視窗 {window} 內沒有攔截記錄",
+        en="No blocked events in window {window}",
+        ja="期間 {window} にブロック記録がありません",
+        ru="За период {window} блокировок нет",
+    )
+    usage_header: I18nKey = I18nKey(
+        default="Usage quota consumption ({count} active key(s)):",
+        zh_CN="配额消耗（活跃键 {count} 个）：",
+        zh_TW="配額消耗（活躍鍵 {count} 個）：",
+        en="Usage quota consumption ({count} active key(s)):",
+        ja="クォータ消費（アクティブキー {count} 件）：",
+        ru="Потребление квот (активных ключей: {count}):",
+    )
+    usage_empty: I18nKey = I18nKey(
+        default="No usage quota records",
+        zh_CN="没有配额消耗记录",
+        zh_TW="沒有配額消耗記錄",
+        en="No usage quota records",
+        ja="クォータ消費記録がありません",
+        ru="Нет записей потребления квот",
+    )
+    gov_list_empty: I18nKey = I18nKey(
+        default="No command has governance declarations",
+        zh_CN="没有任何命令声明治理规则",
+        zh_TW="沒有任何命令聲明治理規則",
+        en="No command has governance declarations",
+        ja="治理宣言を持つコマンドはありません",
+        ru="Нет команд с правилами управления",
+    )
+    gov_list_header: I18nKey = I18nKey(
+        default="Governance declarations ({count} command(s)):",
+        zh_CN="治理声明清单（{count} 个命令）：",
+        zh_TW="治理聲明清單（{count} 個命令）：",
+        en="Governance declarations ({count} command(s)):",
+        ja="治理宣言一覧（{count} 件）：",
+        ru="Объявления управления ({count} команд):",
+    )
+    purge_done: I18nKey = I18nKey(
+        default="Purged {calls} call record(s) and {blocks} block record(s) older than {days} day(s)",
+        zh_CN="已清理 {days} 天前的记录：命令 {calls} 条，拦截 {blocks} 条",
+        zh_TW="已清理 {days} 天前的記錄：命令 {calls} 條，攔截 {blocks} 條",
+        en="Purged {calls} call record(s) and {blocks} block record(s) older than {days} day(s)",
+        ja="{days} 日より前の記録を削除：コマンド {calls} 件、ブロック {blocks} 件",
+        ru="Удалено записей старше {days} дн.: команд {calls}, блокировок {blocks}",
+    )
+    invalid_window: I18nKey = I18nKey(
+        default="Invalid window: {window} (examples: 30m / 24h / 7d)",
+        zh_CN="无效的时间窗口: {window}（示例: 30m / 24h / 7d）",
+        zh_TW="無效的時間視窗: {window}（示例: 30m / 24h / 7d）",
+        en="Invalid window: {window} (examples: 30m / 24h / 7d)",
+        ja="無効な期間指定: {window}（例: 30m / 24h / 7d）",
+        ru="Неверный период: {window} (примеры: 30m / 24h / 7d)",
+    )

GovReport/Models.py

@@ -0,0 +1,30 @@
+from ErisPulse.Core.Bases import Field, Model
+
+
+class CommandCall(Model):
+
+    __tablename__ = "gov_command_calls"
+
+    id: int = Field(primary_key=True, autoincrement=True)
+    ts: float = Field(index=True)
+    command: str = Field(max_length=128, index=True)
+    platform: str = Field(max_length=64, default="")
+    user_id: str = Field(max_length=128, default="", index=True)
+    success: bool = Field(default=True)
+    error: str = Field(max_length=255, default="")
+
+
+class BlockEvent(Model):
+
+    __tablename__ = "gov_block_events"
+
+    id: int = Field(primary_key=True, autoincrement=True)
+    ts: float = Field(index=True)
+    source: str = Field(max_length=16, choices=["middleware", "scope"], index=True)
+    middleware: str = Field(max_length=128, default="")
+    dimension: str = Field(max_length=16, default="")
+    module: str = Field(max_length=128, default="")
+    platform: str = Field(max_length=64, default="")
+    detail_type: str = Field(max_length=64, default="")
+    user_id: str = Field(max_length=128, default="")
+    session_id: str = Field(max_length=128, default="")

GovReport/Stats.py

@@ -0,0 +1,331 @@
+import time
+from typing import Any, Optional
+
+from ErisPulse import i18n
+
+from .Models import BlockEvent, CommandCall
+
+USAGE_KEY_PREFIX = "erispulse.usage"
+SEP = "\x00"
+
+
+def parse_window(window: str) -> Optional[float]:
+    from ErisPulse.Core.Event import command_args
+
+    try:
+        seconds = command_args.parse_duration(window)
+    except Exception:
+        return None
+    if seconds is None or seconds <= 0:
+        return None
+    return float(seconds)
+
+
+def _fmt_window(window: str) -> str:
+    return window
+
+
+class GovStatsService:
+
+    def __init__(self, logger):
+        self._logger = logger
+
+    async def _command_window(self, window_secs: float) -> list:
+        cutoff = time.time() - window_secs
+        return await CommandCall.where(CommandCall.ts >= cutoff).all()
+
+    @staticmethod
+    def _top(rows: list, key: str, top_n: int) -> list:
+        counter: dict[str, int] = {}
+        for r in rows:
+            k = getattr(r, key) or "-"
+            counter[k] = counter.get(k, 0) + 1
+        return sorted(counter.items(), key=lambda kv: -kv[1])[:top_n]
+
+    async def _usage_entries(self) -> dict:
+        from ErisPulse import sdk
+
+        storage = sdk.storage
+        try:
+            root = await storage.aget("erispulse")
+        except Exception as e:
+            self._logger.warning(f"读取配额根键失败: {e}")
+            return {}
+        if not isinstance(root, dict):
+            return {}
+        return {
+            k: v for k, v in root.items()
+            if isinstance(k, str) and k.startswith("usage" + SEP)
+        }
+
+    async def command_stats_card(self, window_text: str, top_n: int, viz) -> str:
+        import datetime
+
+        rows = await self._command_window(parse_window(window_text) or 0)
+        total = len(rows)
+        if not total:
+            body = "<div class='empty'>窗口内没有命令记录</div>"
+        else:
+            ok = sum(1 for r in rows if r.success)
+            dep = sum(1 for r in rows if r.error == "deprecated")
+            body = viz.nums([
+                ("总调用", total, ""),
+                ("成功", ok, "ok"),
+                ("失败", total - ok, "bad"),
+                ("废弃使用", dep, "warn"),
+            ])
+            body += viz.bar_section("命令 Top", self._top(rows, "command", top_n))
+            body += viz.bar_section("用户 Top", self._top(rows, "user_id", top_n), color="accent2")
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("命令执行统计", f"窗口 {window_text} · 共 {total} 次调用")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"GovReport · {stamp}", f"Top {top_n}")
+        )
+
+    async def blocked_stats_card(self, window_text: str, top_n: int, viz) -> str:
+        import datetime
+
+        cutoff = time.time() - (parse_window(window_text) or 0)
+        rows = await BlockEvent.where(BlockEvent.ts >= cutoff).all()
+        total = len(rows)
+        if not total:
+            body = "<div class='empty'>窗口内没有拦截记录</div>"
+        else:
+            mw = sum(1 for r in rows if r.source == "middleware")
+            body = viz.nums([
+                ("总拦截", total, ""),
+                ("中间件否决", mw, "warn"),
+                ("作用域拦截", total - mw, ""),
+            ])
+            by_name: dict[str, int] = {}
+            for r in rows:
+                if r.source == "middleware":
+                    name = r.middleware or "-"
+                else:
+                    name = f"{r.dimension or '-'}:{r.module or '-'}"
+                by_name[name] = by_name.get(name, 0) + 1
+            pairs = sorted(by_name.items(), key=lambda kv: -kv[1])[:top_n]
+            body += viz.bar_section("拦截来源", pairs, color="err")
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("事件拦截统计", f"窗口 {window_text} · 共 {total} 次")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"GovReport · {stamp}", "middleware / scope")
+        )
+
+    async def usage_report_card(self, viz) -> str:
+        import datetime
+
+        entries = await self._usage_entries()
+        if not entries:
+            body = "<div class='empty'>没有配额消耗记录</div>"
+        else:
+            limits = self._usage_limits()
+            rows = []
+            for key in sorted(entries, key=lambda k: -entries[k]):
+                parts = key[len("usage" + SEP):].split(SEP)
+                main_name = parts[0]
+                scope = parts[1] if len(parts) > 1 else "?"
+                period = parts[2] if len(parts) > 2 else "?"
+                limit, unit = limits.get(main_name, (None, ""))
+                right = f"{entries[key]}/{limit}" if limit is not None else str(entries[key])
+                chips = viz.chips([f"period {period}", f"scope {scope}"])
+                rows.append(viz.count_row(main_name, right, unit or "", chips))
+            body = "".join(rows)
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("配额消耗", f"活跃键 {len(entries)} 个")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"GovReport · {stamp}", "usage_limit")
+        )
+
+    def governance_list_card(self, name_filter, viz) -> str:
+        import datetime
+
+        from ErisPulse.Core.Event import command
+
+        registry = command.get_commands()
+        rows = []
+        for cmd_name, info in sorted(registry.items()):
+            if cmd_name != info.get("main_name"):
+                continue
+            if name_filter and name_filter not in cmd_name:
+                continue
+            chips = []
+            cooldown = info.get("cooldown_seconds")
+            if cooldown:
+                chips.append(f"cooldown {cooldown:g}s · {info.get('cooldown_key') or 'user'}")
+            rate = info.get("rate_limit_spec")
+            if rate:
+                chips.append(f"rate {rate[0]}/{rate[1]:g}s · {info.get('rate_limit_key') or 'user'}")
+            usage = info.get("usage_spec")
+            if usage:
+                chips.append(f"usage {usage[0]}/{usage[1]} · {info.get('usage_limit_key') or 'user'}")
+            deprecated = info.get("deprecated")
+            if deprecated:
+                chips.append(f"deprecated{'(reject)' if info.get('deprecated_reject') else ''}: {deprecated}")
+            if chips:
+                rows.append(viz.count_row(
+                    cmd_name, "", "",
+                    viz.chips(chips, cls="warn" if deprecated else ""),
+                ))
+        body = "".join(rows) if rows else "<div class='empty'>没有任何命令声明治理规则</div>"
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("治理声明清单", f"{len(rows)} 个命令声明了治理规则")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"GovReport · {stamp}", "cooldown / rate / usage / deprecated")
+        )
+
+    async def command_stats(self, window_secs: float, window_text: str, top_n: int) -> str:
+        cutoff = time.time() - window_secs
+        rows = await CommandCall.where(CommandCall.ts >= cutoff).all()
+        if not rows:
+            return i18n.t("GovReport.stats_empty", window=_fmt_window(window_text))
+        total = len(rows)
+        ok = sum(1 for r in rows if r.success)
+        dep = sum(1 for r in rows if r.error == "deprecated")
+        lines = [i18n.t(
+            "GovReport.stats_header",
+            window=_fmt_window(window_text), total=total, ok=ok, failed=total - ok, dep=dep,
+        )]
+        by_cmd: dict[str, int] = {}
+        for r in rows:
+            by_cmd[r.command] = by_cmd.get(r.command, 0) + 1
+        for cmd, count in sorted(by_cmd.items(), key=lambda kv: -kv[1])[:top_n]:
+            lines.append(f"{cmd}: {count}")
+        return "\n".join(lines)
+
+    async def user_stats(self, user_id: str, window_secs: float, window_text: str, top_n: int) -> str:
+        cutoff = time.time() - window_secs
+        rows = await CommandCall.where(
+            (CommandCall.ts >= cutoff) & (CommandCall.user_id == user_id)
+        ).all()
+        if not rows:
+            return i18n.t("GovReport.user_empty", user=user_id, window=_fmt_window(window_text))
+        total = len(rows)
+        ok = sum(1 for r in rows if r.success)
+        lines = [i18n.t(
+            "GovReport.user_header",
+            user=user_id, window=_fmt_window(window_text), total=total, ok=ok, failed=total - ok,
+        )]
+        by_cmd: dict[str, int] = {}
+        for r in rows:
+            by_cmd[r.command] = by_cmd.get(r.command, 0) + 1
+        for cmd, count in sorted(by_cmd.items(), key=lambda kv: -kv[1])[:top_n]:
+            lines.append(f"{cmd}: {count}")
+        return "\n".join(lines)
+
+    async def blocked_stats(self, window_secs: float, window_text: str, top_n: int) -> str:
+        cutoff = time.time() - window_secs
+        rows = await BlockEvent.where(BlockEvent.ts >= cutoff).all()
+        if not rows:
+            return i18n.t("GovReport.blocked_empty", window=_fmt_window(window_text))
+        lines = [i18n.t("GovReport.blocked_header", window=_fmt_window(window_text), total=len(rows))]
+        by_source: dict[str, int] = {}
+        by_name: dict[str, int] = {}
+        for r in rows:
+            by_source[r.source] = by_source.get(r.source, 0) + 1
+            if r.source == "middleware":
+                name = f"middleware:{r.middleware or '-'}"
+            else:
+                name = f"scope:{r.dimension or '-'}:{r.module or '-'}"
+            by_name[name] = by_name.get(name, 0) + 1
+        rendered = " ".join(f"{k}={v}" for k, v in sorted(by_source.items()))
+        lines.append(f"by_source: {rendered}")
+        for name, count in sorted(by_name.items(), key=lambda kv: -kv[1])[:top_n]:
+            lines.append(f"{name}: {count}")
+        return "\n".join(lines)
+
+    async def usage_report(self) -> str:
+        from ErisPulse import sdk
+
+        storage = sdk.storage
+        root_key = USAGE_KEY_PREFIX.split(".")[0]
+        nested_prefix = USAGE_KEY_PREFIX.split(".", 1)[1] + SEP
+        try:
+            root = await storage.aget(root_key)
+        except Exception as e:
+            self._logger.warning(f"读取配额根键失败: {e}")
+            root = None
+        entries: dict[str, Any] = {}
+        if isinstance(root, dict):
+            entries = {
+                k: v for k, v in root.items()
+                if isinstance(k, str) and k.startswith(nested_prefix)
+            }
+        if not entries:
+            return i18n.t("GovReport.usage_empty")
+
+        limits = self._usage_limits()
+        lines = [i18n.t("GovReport.usage_header", count=len(entries))]
+        for key in sorted(entries):
+            parts = key[len(nested_prefix):].split(SEP)
+            main_name = parts[0] if parts else "?"
+            scope = parts[1] if len(parts) > 1 else "?"
+            period = parts[2] if len(parts) > 2 else "?"
+            used = entries[key]
+            limit, unit = limits.get(main_name, (None, ""))
+            limit_text = f"/{limit}({unit})" if limit is not None else ""
+            lines.append(f"{main_name}: {used}{limit_text} period={period} scope={scope}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _usage_limits() -> dict[str, tuple[Any, str]]:
+        from ErisPulse.Core.Event import command
+
+        limits: dict[str, tuple[Any, str]] = {}
+        try:
+            registry = command.get_commands()
+        except Exception:
+            return limits
+        for info in registry.values():
+            spec = info.get("usage_spec")
+            main_name = info.get("main_name")
+            if spec and main_name:
+                limits[main_name] = (spec[0], spec[1])
+        return limits
+
+    def governance_list(self, name_filter: Optional[str] = None) -> str:
+        from ErisPulse.Core.Event import command
+
+        registry = command.get_commands()
+        lines = []
+        for cmd_name, info in sorted(registry.items()):
+            if cmd_name != info.get("main_name"):
+                continue
+            if name_filter and name_filter not in cmd_name:
+                continue
+            parts = []
+            cooldown = info.get("cooldown_seconds")
+            if cooldown:
+                parts.append(f"cooldown={cooldown:g}s({info.get('cooldown_key') or 'user'})")
+            rate = info.get("rate_limit_spec")
+            if rate:
+                parts.append(f"rate={rate[0]}/{rate[1]:g}s({info.get('rate_limit_key') or 'user'})")
+            usage = info.get("usage_spec")
+            if usage:
+                parts.append(f"usage={usage[0]}/{usage[1]}({info.get('usage_limit_key') or 'user'})")
+            deprecated = info.get("deprecated")
+            if deprecated:
+                reject = "reject" if info.get("deprecated_reject") else "notice"
+                parts.append(f"deprecated[{reject}]={deprecated}")
+            if parts:
+                lines.append(f"{cmd_name}: {' '.join(parts)}")
+        if not lines:
+            return i18n.t("GovReport.gov_list_empty")
+        return "\n".join([i18n.t("GovReport.gov_list_header", count=len(lines))] + lines)
+
+    async def purge(self, days: int) -> tuple[int, int]:
+        cutoff = time.time() - days * 86400
+        calls = await CommandCall.delete_all(CommandCall.ts < cutoff)
+        blocks = await BlockEvent.delete_all(BlockEvent.ts < cutoff)
+        return calls, blocks
+
+    async def purge_expired(self, retention_days: int) -> None:
+        if retention_days <= 0:
+            return
+        calls, blocks = await self.purge(retention_days)
+        if calls or blocks:
+            self._logger.info(f"清理过期记录: 命令 {calls} 条, 拦截 {blocks} 条")

GovReport/Visualizer.py

@@ -0,0 +1,190 @@
+import asyncio
+from typing import Optional
+
+PALETTES = {
+    "light": {
+        "page": "#f4f6f9", "card": "#ffffff", "ink": "#2b3440", "sub": "#7d8a99",
+        "accent": "#4a7fb5", "accent2": "#5aa27b", "warn": "#c0804a", "err": "#bf6a6a",
+        "accent_soft": "#e3edf7", "border": "#dfe6ee", "chipbg": "#f0f4f9", "codebg": "#eef2f7",
+    },
+    "dark": {
+        "page": "#171b21", "card": "#20262e", "ink": "#e6ebf1", "sub": "#93a1b0",
+        "accent": "#7aa9d9", "accent2": "#7fc29a", "warn": "#d3a569", "err": "#d98a8a",
+        "accent_soft": "rgba(122,169,217,0.14)", "border": "#2c343e",
+        "chipbg": "rgba(122,169,217,0.08)", "codebg": "#262d36",
+    },
+}
+
+_FONTS = '"Noto Sans SC", "Roboto", "PingFang SC", "Microsoft YaHei", sans-serif'
+_FONTS_MONO = '"JetBrains Mono", "Cascadia Code", Consolas, ui-monospace, monospace'
+
+_CSS_TPL = """
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: __FONTS__; color: __INK__; -webkit-font-smoothing: antialiased; }
+.page { background: __PAGE__; padding: 24px; }
+.card { background: __CARD__; border: 1px solid __BORDER__; border-radius: 16px; overflow: hidden; }
+.head { display: flex; justify-content: space-between; align-items: center; padding: 18px 24px; border-bottom: 1px solid __BORDER__; }
+.title { font-size: 19px; font-weight: 700; letter-spacing: 0.5px; }
+.subtitle { font-size: 12.5px; color: __SUB__; margin-top: 3px; }
+.body { padding: 18px 24px 22px; }
+.nums { display: flex; gap: 12px; }
+.num { flex: 1; background: __CODEBG__; border-radius: 12px; padding: 14px 16px; text-align: center; }
+.num .label { font-size: 12px; color: __SUB__; }
+.num .value { font-size: 26px; font-weight: 700; color: __ACCENT__; margin-top: 4px; }
+.num.ok .value { color: __ACCENT2__; }
+.num.bad .value { color: __ERR__; }
+.num.warn .value { color: __WARN__; }
+.section { margin-top: 18px; }
+.section-title { font-size: 12.5px; color: __SUB__; font-weight: 600; letter-spacing: 1px; margin-bottom: 8px; text-transform: uppercase; }
+.bars { display: flex; flex-direction: column; gap: 8px; }
+.bar-row { display: flex; align-items: center; gap: 10px; }
+.bar-label { flex: 0 0 170px; font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: __FONTMONO__; }
+.bar-track { flex: 1; height: 16px; background: __CODEBG__; border-radius: 9999px; overflow: hidden; }
+.bar-fill { height: 100%; border-radius: 9999px; background: __ACCENT__; }
+.bar-value { flex: 0 0 52px; text-align: right; font-size: 12.5px; color: __SUB__; font-family: __FONTMONO__; }
+.kv-grid { display: flex; flex-wrap: wrap; gap: 8px; }
+.kv { background: __CHIPBG__; border: 1px solid __BORDER__; border-radius: 8px; padding: 6px 12px; font-size: 13px; }
+.kv b { color: __ACCENT__; font-weight: 600; }
+.row { padding: 10px 12px; border-radius: 10px; margin-bottom: 6px; background: __CHIPBG__; border: 1px solid __BORDER__; }
+.row:last-child { margin-bottom: 0; }
+.row-main { display: flex; align-items: center; gap: 10px; }
+.row-name { font-family: __FONTMONO__; font-size: 13px; background: __CODEBG__; border-radius: 6px; padding: 3px 8px; }
+.row-dim { font-size: 12px; color: __SUB__; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.row-count { font-size: 15px; font-weight: 700; color: __ACCENT__; font-family: __FONTMONO__; }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 6px; }
+.chip { font-size: 11.5px; background: __ACCENT_SOFT__; color: __ACCENT__; border-radius: 9999px; padding: 2px 10px; }
+.chip.warn { color: __WARN__; }
+.chip.err { color: __ERR__; }
+.empty { text-align: center; color: __SUB__; font-size: 13px; padding: 18px 0; }
+.foot { padding: 12px 24px; border-top: 1px solid __BORDER__; font-size: 11.5px; color: __SUB__; display: flex; justify-content: space-between; }
+"""
+
+
+def _esc(text) -> str:
+    import html
+
+    return html.escape(str(text))
+
+
+class CardVisualizer:
+
+    CARD_WIDTH = 780
+
+    def __init__(self, sdk, logger):
+        self.sdk = sdk
+        self.logger = logger
+        self._takumi_inst = None
+
+    @property
+    def takumi(self):
+        if self._takumi_inst is None:
+            inst = None
+            try:
+                inst = self.sdk.module.get("Takumi")
+            except Exception:
+                inst = None
+            if inst is None:
+                inst = getattr(self.sdk, "Takumi", None)
+            self._takumi_inst = inst
+        return self._takumi_inst
+
+    def resolve_palette(self, theme: str) -> dict:
+        import datetime
+
+        if theme in PALETTES:
+            mode = theme
+        else:
+            hour = datetime.datetime.now().hour
+            mode = "dark" if (hour >= 19 or hour < 7) else "light"
+        return dict(PALETTES[mode])
+
+    def _css(self, palette: dict) -> str:
+        css = _CSS_TPL.replace("__FONTS__", _FONTS).replace("__FONTMONO__", _FONTS_MONO)
+        for key, value in palette.items():
+            css = css.replace(f"__{key.upper()}__", value)
+        return css
+
+    async def render(self, body_html: str, theme: str = "auto") -> Optional[bytes]:
+        takumi = self.takumi
+        if takumi is None or not hasattr(takumi, "render_html"):
+            self.logger.debug("Takumi 不可用，跳过渲染")
+            return None
+        try:
+            result = takumi.render_html(
+                f"<div class='page'>{body_html}</div>",
+                stylesheets=[self._css(self.resolve_palette(theme))],
+                width=self.CARD_WIDTH,
+                height=None,
+                lang="zh-CN",
+            )
+            if asyncio.iscoroutine(result):
+                result = await result
+            return result if isinstance(result, (bytes, bytearray)) else None
+        except Exception as e:
+            self.logger.warning(f"渲染卡片失败: {e}")
+            return None
+
+    def head(self, title: str, subtitle: str) -> str:
+        return (
+            f"<div class='head'><div><div class='title'>{_esc(title)}</div>"
+            f"<div class='subtitle'>{_esc(subtitle)}</div></div></div>"
+        )
+
+    def foot(self, left: str, right: str) -> str:
+        return f"<div class='foot'><span>{_esc(left)}</span><span>{_esc(right)}</span></div>"
+
+    @staticmethod
+    def nums(items) -> str:
+        cells = "".join(
+            f"<div class='num {cls}'><div class='label'>{_esc(label)}</div>"
+            f"<div class='value'>{_esc(value)}</div></div>"
+            for label, value, cls in items
+        )
+        return f"<div class='nums'>{cells}</div>"
+
+    @staticmethod
+    def bars(pairs, color: str = "accent") -> str:
+        if not pairs:
+            return "<div class='empty'>无数据</div>"
+        top = max(v for _, v in pairs) or 1
+        fill = f"__ACCENT__" if color == "accent" else f"__{color.upper()}__"
+        rows = "".join(
+            f"<div class='bar-row'><span class='bar-label'>{_esc(k)}</span>"
+            f"<div class='bar-track'><div class='bar-fill' style='width:{max(3, round(v / top * 100))}%;background:{fill}'></div></div>"
+            f"<span class='bar-value'>{_esc(v)}</span></div>"
+            for k, v in pairs
+        )
+        return f"<div class='bars'>{rows}</div>"
+
+    @staticmethod
+    def kv_section(title: str, pairs) -> str:
+        chips = "".join(f"<div class='kv'>{_esc(k)} <b>{_esc(v)}</b></div>" for k, v in pairs)
+        return (
+            f"<div class='section'><div class='section-title'>{_esc(title)}</div>"
+            f"<div class='kv-grid'>{chips}</div></div>"
+        )
+
+    @staticmethod
+    def bar_section(title: str, pairs, color: str = "accent") -> str:
+        return (
+            f"<div class='section'><div class='section-title'>{_esc(title)}</div>"
+            f"{CardVisualizer.bars(pairs, color)}</div>"
+        )
+
+    @staticmethod
+    def count_row(name: str, right: str, dim: str = "", chips: str = "") -> str:
+        return (
+            f"<div class='row'><div class='row-main'>"
+            f"<span class='row-name'>{_esc(name)}</span>"
+            f"<span class='row-dim'>{_esc(dim)}</span>"
+            f"<span class='row-count'>{_esc(right)}</span></div>{chips}</div>"
+        )
+
+    @staticmethod
+    def chips(items, cls: str = "") -> str:
+        if not items:
+            return ""
+        rendered = "".join(
+            f"<span class='chip {cls}'>{_esc(t)}</span>" for t in items
+        )
+        return f"<div class='chips'>{rendered}</div>"

GovReport/__init__.py

@@ -0,0 +1,4 @@
+from .Config import GovReportConfig
+from .I18n import GovReportI18n
+from .Models import BlockEvent, CommandCall
+from .Core import Main

erispulse_govreport-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: ErisPulse-GovReport
+Version: 0.1.0
+Summary: 治理观测模块：采集命令执行与事件拦截记录，输出统计报表与配额消耗
+Author: wsu2059q
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21; extra == "test"
+Requires-Dist: ErisPulse-Testing; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+
+<img src=".github/assets/ErisPulseLogo.png" width="180" alt="ErisPulse GovReport" />
+
+# ErisPulse GovReport
+
+**治理观测模块 —— 命令执行、事件拦截与配额消耗的统计报表。**
+
+基于 ErisPulse 2.9 命令治理与生命周期事件的观测模块，使用内置 ORM 持久化记录，报表经 Takumi 渲染为卡片。
+
+<p>
+  <a href="https://pypi.org/project/ErisPulse-GovReport/"><img src="https://img.shields.io/pypi/v/ErisPulse-GovReport?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/ErisPulse-GovReport/"><img src="https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue" alt="Python"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
+  <a href="https://github.com/ErisPulse/ErisPulse-GovReport"><img src="https://img.shields.io/github/stars/ErisPulse/ErisPulse-GovReport?style=for-the-badge&logo=github&color=brightgreen" alt="Stars"></a>
+  <a href="https://pepy.tech/project/ErisPulse-GovReport"><img src="https://img.shields.io/pepy/dt/ErisPulse-GovReport?style=for-the-badge&color=blue" alt="Downloads"></a>
+  <a href="https://github.com/ErisPulse/ErisPulse"><img src="https://img.shields.io/badge/Powered_by-ErisPulse-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white" alt="ErisPulse"></a>
+</p>
+
+<p>
+  <a href="./README.md">简体中文</a> | <a href="./README.en.md">English</a>
+</p>
+
+</div>
+
+---
+
+## 简介
+
+GovReport 是基于 [ErisPulse](https://github.com/ErisPulse/ErisPulse/) 架构开发的治理观测模块：
+
+- 采集 `command.executed` 命令执行记录（成功/失败/废弃）
+- 采集 `adapter.event.blocked`（中间件否决）与 `scope.blocked`（作用域拦截）记录
+- 读取 `usage_limit` 配额计数（`erispulse.usage` 存储键），对照声明上限展示消耗
+- 枚举全部命令的治理声明（cooldown / rate_limit / usage_limit / deprecated）
+- 记录用内置 ORM（`Model` / `Field`）持久化，按保留天数自动清理
+- 报表经 Takumi 渲染为图片卡片，不可用时降级文本
+
+要求 ErisPulse >= 2.9.0。
+
+---
+
+## 效果展示
+
+| `/gov stats` | `/gov blocked` |
+|:---:|:---:|
+| ![stats](.github/assets/demo/stats-light.png) | ![blocked](.github/assets/demo/blocked-light.png) |
+
+| `/gov usage` | `/gov list` |
+|:---:|:---:|
+| ![usage](.github/assets/demo/usage-light.png) | ![list](.github/assets/demo/list-light.png) |
+
+---
+
+
+---
+
+## 安装
+
+```bash
+epsdk install ErisPulse-GovReport
+```
+
+---
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `/gov` | 显示用法 |
+| `/gov stats [窗口]` | 命令执行统计（调用 Top / 成功率 / 废弃使用），窗口如 `24h`、`7d`，默认 `24h` |
+| `/gov user <用户ID> [窗口]` | 单用户调用统计 |
+| `/gov blocked [窗口]` | 拦截统计（中间件否决 / 作用域拦截） |
+| `/gov usage` | 配额消耗报表（used/limit + 周期 + 作用域） |
+| `/gov list [命令]` | 治理声明清单（可按命令名过滤） |
+| `/gov purge <天数>` | 清理指定天数之前的记录 |
+
+全部命令需要框架主人权限。
+
+---
+
+## 使用示例
+
+```toml
+# 给命令声明治理规则（本模块负责观测这些规则的运行效果）
+[ErisPulse.event.command]
+prefix = "/"
+
+# Python 侧
+# @command("translate", usage_limit="100/day", usage_limit_key="user")
+```
+
+```python
+from ErisPulse.Core.Event import command
+
+@command("translate", cooldown="30s", rate_limit="5/minute",
+         usage_limit="100/day", usage_limit_key="user", help="翻译")
+async def translate_handler(event):
+    await event.reply("结果")
+
+@command("oldcmd", deprecated="请用 /translate", deprecated_reject=True)
+async def old_handler(event):
+    ...
+```
+
+---
+
+## 配置说明
+
+```toml
+[GovReport]
+enabled = true                  # 是否启用模块
+collect_command_calls = true    # 采集命令执行记录
+collect_blocked = true          # 采集拦截记录
+retention_days = 30             # 记录保留天数（0 永久保留）
+top_n = 10                      # 报表单次展示条目数
+render_card = true              # 报表用 Takumi 渲染为卡片
+theme = "auto"                  # 卡片配色 (auto/light/dark)
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enabled` | bool | `true` | 是否启用模块 |
+| `collect_command_calls` | bool | `true` | 采集 `command.executed` |
+| `collect_blocked` | bool | `true` | 采集中间件否决与作用域拦截 |
+| `retention_days` | int | `30` | 保留天数（0 永久，启动与每日清理） |
+| `top_n` | int | `10` | 报表单次展示条目数 |
+| `render_card` | bool | `true` | 报表渲染为图片卡片 |
+| `theme` | str | `auto` | 卡片配色 |
+
+---
+
+## 注意事项
+
+1. 配额消耗读取自治理系统的存储键（`erispulse.usage`），重启不丢
+2. 冷却/限流命中默认静默，不在采集范围内（可用 ErisPulse-Testing 的 DispatchTrace 排查单条命令）
+3. 记录写入框架存储后端（SQLite / MySQL / PostgreSQL 由存储配置决定）
+
+---
+
+## 参考链接
+
+- [ErisPulse 主库](https://github.com/ErisPulse/ErisPulse/)
+- [命令治理文档](https://github.com/ErisPulse/ErisPulse/tree/main/docs/zh-CN/getting-started/event-handling.md)
+- [ORM 文档](https://github.com/ErisPulse/ErisPulse/tree/main/docs/zh-CN/developer-guide/orm.md)

erispulse_govreport-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+GovReport/Config.py,sha256=5iKlKXcOgSyhZ2URLYxLASNaw4aKkU0Kd82IsFCAJiY,2250
+GovReport/Core.py,sha256=VXayibRRZXKRHU108hr6ceSPQo-YtHILk1p1t3dSLw8,8517
+GovReport/I18n.py,sha256=dy4BiCerl5m7ZHnQdAlo_qvlfVVdkIGObXm7nA108eQ,9667
+GovReport/Models.py,sha256=tJI-_xhMjzSDKJxmreia3i2UhGEMCzkw2ciCSa_9LsM,1094
+GovReport/Stats.py,sha256=aFIYPd78oc58Q8eeHggc8oCPSOXbAs9zwoEp4ozemGE,13828
+GovReport/Visualizer.py,sha256=dTHCgkB-jLd7vjzzaA_GTsbx3gMscFvr4ObfLp_EJxk,8420
+GovReport/__init__.py,sha256=SffgNmAK1lNORgDCsR-JDNcKMZRwf1Vpm1jU9PGS0Cg,135
+erispulse_govreport-0.1.0.dist-info/licenses/LICENSE,sha256=OO7qHOo6QdvZahvf8NTfkgcVGuh8fqFcxKTvxmbmz_k,1065
+erispulse_govreport-0.1.0.dist-info/METADATA,sha256=38j8h2yw3z2ZZztvnQdm_TyGjniIMcNI_-InX7jEmvE,5911
+erispulse_govreport-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+erispulse_govreport-0.1.0.dist-info/entry_points.txt,sha256=-sFfjdLvyPa2Yc5689_Sg31sgFd-nx-jSy6tTTfQob8,46
+erispulse_govreport-0.1.0.dist-info/top_level.txt,sha256=ZgBDF5xOVYAHdI38LKA153-RJ98OOBl29MFIiKXQVV4,10
+erispulse_govreport-0.1.0.dist-info/RECORD,,

erispulse_govreport-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

erispulse_govreport-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[erispulse.module]
+GovReport = GovReport:Main

erispulse_govreport-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wsu2059q
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erispulse_govreport-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+GovReport