ErisPulse-ShadowOps 0.1.0__py3-none-any.whl

ShadowOps/Config.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass, field
+
+from ErisPulse.Core.Bases import BaseConfig
+
+
+@dataclass
+class ShadowOpsConfig(BaseConfig):
+
+    enabled: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "ShadowOps.enabled", "default": "是否启用模块"},
+            "ui": {"widget": "switch", "group": "basic", "order": 1},
+        },
+    )
+    diff_max_rows: int = field(
+        default=10,
+        metadata={
+            "description": {"i18n": "ShadowOps.diff_max_rows", "default": "对比报告单次展示的最大条目数"},
+            "ui": {"widget": "number", "group": "report", "order": 2},
+        },
+    )
+    audit_deep: bool = field(
+        default=False,
+        metadata={
+            "description": {"i18n": "ShadowOps.audit_deep", "default": "审计时附带 gc 实例普查（有全局暂停开销）"},
+            "ui": {"widget": "switch", "group": "report", "order": 3},
+        },
+    )
+    render_card: bool = field(
+        default=True,
+        metadata={
+            "description": {"i18n": "ShadowOps.render_card", "default": "报告用 Takumi 渲染为卡片（不可用时降级文本）"},
+            "ui": {"widget": "switch", "group": "render", "order": 4},
+        },
+    )
+    theme: str = field(
+        default="auto",
+        metadata={
+            "description": {"i18n": "ShadowOps.theme", "default": "卡片配色 (auto=按时间自动切深浅色)"},
+            "ui": {
+                "widget": "select",
+                "options": ["auto", "light", "dark"],
+                "group": "render",
+                "order": 5,
+            },
+        },
+    )

ShadowOps/Core.py

@@ -0,0 +1,148 @@
+from ErisPulse import i18n, sdk
+from ErisPulse.Core.Bases import BaseModule, ModuleMeta
+from ErisPulse.Core.Event import command
+from ErisPulse.loaders import ModuleLoadStrategy
+
+from .Config import ShadowOpsConfig
+from .I18n import ShadowOpsI18n
+from .Service import ShadowOpsService
+from .Visualizer import CardVisualizer
+
+
+class Main(BaseModule):
+
+    ConfigClass = ShadowOpsConfig
+    I18nClass = ShadowOpsI18n
+
+    def __init__(self):
+        self.sdk = sdk
+        self.logger = sdk.logger.get_child("ShadowOps")
+        self._service = ShadowOpsService(sdk, self.logger)
+        self._viz = CardVisualizer(sdk, self.logger)
+
+    @staticmethod
+    def get_load_strategy() -> ModuleLoadStrategy:
+        return ModuleLoadStrategy(lazy_load=False, priority=20)
+
+    @staticmethod
+    def get_meta() -> ModuleMeta:
+        return ModuleMeta(
+            name="ShadowOps",
+            description="影子灰度管理模块：启动/对比/转正/放弃影子模块，附归属权审计",
+            version="0.1.0",
+            author="ErisPulse-devs",
+            group="运维",
+            tags=["影子模块", "灰度", "热更新", "审计"],
+            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
+
+        self._register_commands()
+        self.logger.info(i18n.t("ShadowOps.module_loaded", event=event))
+        return True
+
+    async def on_unload(self, event: dict) -> bool:
+        self.logger.info(i18n.t("ShadowOps.module_unloaded", event=event))
+        return True
+
+    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 _shadow_error_text(self, error: Exception, name: str) -> str:
+        from ErisPulse.Core.Bases.errors import ShadowError
+
+        if isinstance(error, ShadowError):
+            return f"{type(error).__name__}: {error}"
+        return f"{type(error).__name__}: {error}"
+
+    def _register_commands(self):
+        @command("shadow", master=True, help="影子灰度管理")
+        async def shadow_handler(event):
+            await event.reply(
+                "用法: /shadow start <模块名> <v2路径> | /shadow list | /shadow diff <模块名> | "
+                "/shadow promote <模块名> confirm | /shadow dismiss <模块名> | /shadow audit <模块名>"
+            )
+
+        @command("shadow start", master=True, help="启动影子（新版代码以独立 owner 并存试运行）",
+                 args="<name:str> <source:rest>")
+        async def shadow_start_handler(event, name: str, source: str):
+            source = source.strip()
+            if not source:
+                await event.reply("缺少 v2 路径")
+                return
+            try:
+                owner = await self._service.start(name, source)
+            except Exception as e:
+                await event.reply(self._shadow_error_text(e, name))
+                return
+            await event.reply(i18n.t("ShadowOps.started", owner=owner, name=name))
+
+        @command("shadow list", master=True, help="列出运行中的影子")
+        async def shadow_list_handler(event):
+            await self._reply_card(
+                event,
+                self._service.list_card_html(self._viz),
+                self._service.format_list_text(),
+            )
+
+        @command("shadow diff", master=True, help="对比 v1 实际发送 × v2 意向发送", args="<name:str>")
+        async def shadow_diff_handler(event, name: str):
+            report = self._service.diff(name)
+            await self._reply_card(
+                event,
+                self._service.diff_card_html(name, report, self.cfg.diff_max_rows, self._viz),
+                self._service.format_diff_text(name, report, self.cfg.diff_max_rows),
+            )
+
+        @command("shadow promote", master=True, help="转正影子（需 yes 确认）",
+                 args="<name:str> [confirm:literal=no|yes]")
+        async def shadow_promote_handler(event, name: str, confirm: str = "no"):
+            if confirm != "yes":
+                await event.reply(i18n.t("ShadowOps.promote_need_confirm", name=name))
+                return
+            try:
+                ok = await self._service.promote(name)
+            except Exception as e:
+                await event.reply(self._shadow_error_text(e, name))
+                return
+            if ok:
+                await event.reply(i18n.t("ShadowOps.promoted", name=name))
+            else:
+                await event.reply(f"promote returned False: {name}")
+
+        @command("shadow dismiss", master=True, help="放弃影子", args="<name:str>")
+        async def shadow_dismiss_handler(event, name: str):
+            try:
+                ok = await self._service.dismiss(name)
+            except Exception as e:
+                await event.reply(self._shadow_error_text(e, name))
+                return
+            if ok:
+                await event.reply(i18n.t("ShadowOps.dismissed", name=name))
+            else:
+                await event.reply(f"dismiss returned False: {name}")
+
+        @command("shadow audit", master=True, help="归属权审计", args="<name:str>")
+        async def shadow_audit_handler(event, name: str):
+            try:
+                report = self._service.audit(name, deep=self.cfg.audit_deep)
+            except Exception as e:
+                await event.reply(self._shadow_error_text(e, name))
+                return
+            await self._reply_card(
+                event,
+                self._service.audit_card_html(name, report, self._viz),
+                self._service.format_audit_text(name, report),
+            )

ShadowOps/I18n.py

@@ -0,0 +1,125 @@
+from ErisPulse.Core.Bases import BaseI18n, I18nKey
+
+
+class ShadowOpsI18n(BaseI18n):
+
+    enabled: I18nKey = I18nKey(
+        default="Enable module",
+        zh_CN="是否启用模块",
+        zh_TW="是否啟用模組",
+        en="Enable module",
+        ja="モジュールを有効化",
+        ru="Включить модуль",
+    )
+    diff_max_rows: I18nKey = I18nKey(
+        default="Max entries shown in one diff report",
+        zh_CN="对比报告单次展示的最大条目数",
+        zh_TW="對比報告單次展示的最大條目數",
+        en="Max entries shown in one diff report",
+        ja="差分レポート1回の最大表示件数",
+        ru="Максимум записей в одном отчёте сравнения",
+    )
+    audit_deep: I18nKey = I18nKey(
+        default="Include gc instance census in audit (has global pause cost)",
+        zh_CN="审计时附带 gc 实例普查（有全局暂停开销）",
+        zh_TW="審計時附帶 gc 實例普查（有全域暫停開銷）",
+        en="Include gc instance census in audit (has global pause cost)",
+        ja="監査に gc インスタンス調査を含める（グローバル一時停止あり）",
+        ru="Включать обзор gc-экземпляров в аудит (глобальные паузы)",
+    )
+    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="ShadowOps loaded: {event}",
+        zh_CN="影子灰度管理已加载: {event}",
+        zh_TW="影子灰度管理已載入: {event}",
+        en="ShadowOps loaded: {event}",
+        ja="ShadowOps を読み込みました: {event}",
+        ru="ShadowOps загружен: {event}",
+    )
+    module_unloaded: I18nKey = I18nKey(
+        default="ShadowOps unloaded: {event}",
+        zh_CN="影子灰度管理已卸载: {event}",
+        zh_TW="影子灰度管理已卸載: {event}",
+        en="ShadowOps unloaded: {event}",
+        ja="ShadowOps を解除しました: {event}",
+        ru="ShadowOps выгружен: {event}",
+    )
+    started: I18nKey = I18nKey(
+        default="Shadow started: {owner} (shadowing {name})",
+        zh_CN="影子已启动: {owner}（对照模块 {name}）",
+        zh_TW="影子已啟動: {owner}（對照模組 {name}）",
+        en="Shadow started: {owner} (shadowing {name})",
+        ja="シャドーを開始しました: {owner}（対象 {name}）",
+        ru="Тень запущена: {owner} (для {name})",
+    )
+    promoted: I18nKey = I18nKey(
+        default="Shadow promoted: {name}",
+        zh_CN="影子已转正: {name}",
+        zh_TW="影子已轉正: {name}",
+        en="Shadow promoted: {name}",
+        ja="シャドーを本番化しました: {name}",
+        ru="Тень повышена: {name}",
+    )
+    dismissed: I18nKey = I18nKey(
+        default="Shadow dismissed: {name}",
+        zh_CN="影子已放弃: {name}",
+        zh_TW="影子已放棄: {name}",
+        en="Shadow dismissed: {name}",
+        ja="シャドーを破棄しました: {name}",
+        ru="Тень отклонена: {name}",
+    )
+    list_empty: I18nKey = I18nKey(
+        default="No active shadows",
+        zh_CN="当前没有运行中的影子",
+        zh_TW="當前沒有運行中的影子",
+        en="No active shadows",
+        ja="実行中のシャドーはありません",
+        ru="Нет активных теней",
+    )
+    list_header: I18nKey = I18nKey(
+        default="Active shadows ({count}):",
+        zh_CN="运行中的影子（{count} 个）：",
+        zh_TW="運行中的影子（{count} 個）：",
+        en="Active shadows ({count}):",
+        ja="実行中のシャドー（{count} 件）：",
+        ru="Активные тени ({count}):",
+    )
+    diff_no_shadow: I18nKey = I18nKey(
+        default="Module {name} has no active shadow",
+        zh_CN="模块 {name} 没有运行中的影子",
+        zh_TW="模組 {name} 沒有運行中的影子",
+        en="Module {name} has no active shadow",
+        ja="モジュール {name} に実行中のシャドーはありません",
+        ru="У модуля {name} нет активной тени",
+    )
+    diff_empty: I18nKey = I18nKey(
+        default="Shadow has no outbound entries yet",
+        zh_CN="影子还没有意向出站记录",
+        zh_TW="影子還沒有意向出站記錄",
+        en="Shadow has no outbound entries yet",
+        ja="シャドーの出站記録はまだありません",
+        ru="У тени пока нет записей исходящих",
+    )
+    promote_need_confirm: I18nKey = I18nKey(
+        default="Promote will unload {name} and switch to the shadow version; retry with: /shadow promote {name} yes",
+        zh_CN="转正会卸载 {name} 并切换到影子版本；确认请输入: /shadow promote {name} yes",
+        zh_TW="轉正會卸載 {name} 並切換到影子版本；確認請輸入: /shadow promote {name} yes",
+        en="Promote will unload {name} and switch to the shadow version; retry with: /shadow promote {name} yes",
+        ja="本番化は {name} をアンロードしてシャドー版に切替えます。確認するには: /shadow promote {name} yes",
+        ru="Повышение выгрузит {name} и переключит на версию-тень; подтвердите: /shadow promote {name} yes",
+    )

ShadowOps/Service.py

@@ -0,0 +1,166 @@
+from typing import Any
+
+from ErisPulse import i18n
+
+
+def _shadow_manager():
+    from ErisPulse.Core.shadow import shadow_manager
+
+    return shadow_manager
+
+
+class ShadowOpsService:
+
+    def __init__(self, sdk, logger):
+        self.sdk = sdk
+        self.logger = logger
+
+    def list_shadows(self) -> list[dict[str, str]]:
+        items: list[dict[str, str]] = []
+        try:
+            shadows = getattr(_shadow_manager(), "_shadows", {}) or {}
+        except Exception:
+            shadows = {}
+        for real_name, info in sorted(shadows.items()):
+            items.append({
+                "real_name": real_name,
+                "shadow_owner": info.get("shadow_owner", ""),
+            })
+        return items
+
+    def format_list_text(self) -> str:
+        items = self.list_shadows()
+        if not items:
+            return i18n.t("ShadowOps.list_empty")
+        lines = [i18n.t("ShadowOps.list_header", count=len(items))]
+        for item in items:
+            lines.append(f"{item['real_name']} -> {item['shadow_owner']}")
+        return "\n".join(lines)
+
+    def list_card_html(self, viz) -> str:
+        import datetime
+
+        items = self.list_shadows()
+        if items:
+            rows = "".join(
+                viz.count_row(item["real_name"], "", f"shadow owner: {item['shadow_owner']}")
+                for item in items
+            )
+            body = rows
+            subtitle = f"共 {len(items)} 个影子在运行"
+        else:
+            body = "<div class='empty'>当前没有运行中的影子</div>"
+            subtitle = "共 0 个影子"
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("影子模块", subtitle)
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"ShadowOps · {stamp}", "shadow_start / diff / promote / dismiss")
+        )
+
+    def diff(self, name: str) -> dict[str, Any]:
+        return self.sdk.module.shadow_diff(name)
+
+    @staticmethod
+    def _entry_line(entry: dict) -> str:
+        kind = entry.get("kind", "?")
+        platform = entry.get("platform", "")
+        method = entry.get("method", "")
+        target = entry.get("target", "")
+        preview = str(entry.get("preview", "") or "")
+        return f"[{kind}] {platform}.{method} -> {target} {preview}".rstrip()
+
+    def format_diff_text(self, name: str, report: dict, max_rows: int) -> str:
+        if not report.get("shadow_owner"):
+            return i18n.t("ShadowOps.diff_no_shadow", name=name)
+        aligned = report.get("aligned") or []
+        if not aligned:
+            return i18n.t("ShadowOps.diff_empty")
+        lines = [f"影子 {report['shadow_owner']} · 在账 {report.get('count', len(aligned))} 条"]
+        for item in aligned[:max_rows]:
+            shadow = item.get("shadow") or {}
+            actual = item.get("actual") or []
+            lines.append(self._entry_line(shadow))
+            lines.append(f"  实际发送: {len(actual)} 条 (trace={shadow.get('trace_id', '-')[:8]})")
+        hidden = len(aligned) - max_rows
+        if hidden > 0:
+            lines.append(f"…其余 {hidden} 条已省略")
+        return "\n".join(lines)
+
+    def diff_card_html(self, name: str, report: dict, max_rows: int, viz) -> str:
+        import datetime
+
+        if not report.get("shadow_owner"):
+            return (
+                viz.head("行为对比", f"模块 {name}")
+                + "<div class='body'><div class='empty'>没有运行中的影子</div></div>"
+                + viz.foot("ShadowOps", "shadow_start")
+            )
+        aligned = report.get("aligned") or []
+        if not aligned:
+            body = "<div class='empty'>影子还没有意向出站记录</div>"
+        else:
+            matched = sum(1 for item in aligned if item.get("actual"))
+            rows = []
+            for item in aligned[:max(1, max_rows)]:
+                shadow = item.get("shadow") or {}
+                actual = item.get("actual") or []
+                line = self._entry_line(shadow)
+                chips = viz.chips([
+                    f"trace {str(shadow.get('trace_id', ''))[:12]}",
+                    f"实际发送 {len(actual)} 条",
+                ])
+                rows.append(viz.count_row(
+                    shadow.get("kind", "?"), "✓" if actual else "✗", line, chips,
+                ))
+            body = "".join(rows)
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("行为对比", f"模块 {name} · 影子 {report['shadow_owner']} · 在账 {report.get('count', 0)} 条")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"ShadowOps · {stamp}", f"展示上限 {max(1, max_rows)}")
+        )
+
+    async def start(self, name: str, source: str) -> str:
+        return await self.sdk.module.shadow_start(name, source=source)
+
+    async def promote(self, name: str) -> bool:
+        return await self.sdk.module.promote_shadow(name)
+
+    async def dismiss(self, name: str) -> bool:
+        return await self.sdk.module.dismiss_shadow(name)
+
+    def audit(self, name: str, deep: bool = False) -> dict[str, Any]:
+        return self.sdk.module.audit(name, deep=deep)
+
+    @staticmethod
+    def format_audit_text(name: str, report: dict) -> str:
+        lines = [f"归属审计: {name}"]
+        counts = report.get("counts") or {}
+        rendered = " ".join(f"{k}={v}" for k, v in sorted(counts.items()))
+        lines.append(f"counts: {rendered or '-'}")
+        orphans = report.get("orphans")
+        if orphans:
+            lines.append(f"orphans: {orphans}")
+        recyclable = report.get("instance_recyclable")
+        if recyclable is not None:
+            lines.append(f"instance_recyclable: {recyclable}")
+        return "\n".join(lines)
+
+    def audit_card_html(self, name: str, report: dict, viz) -> str:
+        import datetime
+
+        counts = sorted((report.get("counts") or {}).items())
+        body = viz.kv_section("归属资源计数", counts or [("-", "0")])
+        orphans = report.get("orphans")
+        if orphans:
+            body += viz.kv_section("孤儿 owner", [(str(o), "") for o in orphans])
+        recyclable = report.get("instance_recyclable")
+        if recyclable is not None:
+            body += viz.kv_section("实例可回收", [("instance_recyclable", str(recyclable))])
+        stamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return (
+            viz.head("归属权审计", f"模块 {name}")
+            + f"<div class='body'>{body}</div>"
+            + viz.foot(f"ShadowOps · {stamp}", "module.audit")
+        )

ShadowOps/Visualizer.py

@@ -0,0 +1,160 @@
+import asyncio
+from typing import Optional
+
+PALETTES = {
+    "light": {
+        "page": "#f4f6f9", "card": "#ffffff", "ink": "#2b3440", "sub": "#7d8a99",
+        "accent": "#8a6db5", "accent2": "#5aa27b", "warn": "#c0804a",
+        "accent_soft": "#ece5f6", "border": "#dfe6ee", "chipbg": "#f0f4f9", "codebg": "#eef2f7",
+    },
+    "dark": {
+        "page": "#171b21", "card": "#20262e", "ink": "#e6ebf1", "sub": "#93a1b0",
+        "accent": "#ab8fd6", "accent2": "#7fc29a", "warn": "#d3a569",
+        "accent_soft": "rgba(171,143,214,0.14)", "border": "#2c343e",
+        "chipbg": "rgba(171,143,214,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.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; }
+.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__; }
+.row-count.ok { color: __ACCENT2__; }
+.row-count.miss { color: __WARN__; }
+.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; }
+.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 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 count_row(name: str, right: str, dim: str = "", chips: str = "", right_cls: 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 {right_cls}'>{_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>"

ShadowOps/__init__.py

@@ -0,0 +1,3 @@
+from .Config import ShadowOpsConfig
+from .I18n import ShadowOpsI18n
+from .Core import Main

erispulse_shadowops-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: ErisPulse-ShadowOps
+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 ShadowOps" />
+
+# ErisPulse ShadowOps
+
+**影子灰度管理模块 —— 在聊天中启动、对比、转正、放弃影子模块。**
+
+基于 ErisPulse 2.9 影子模块运行时 API 的运营工具，附归属权审计，报告经 Takumi 渲染为卡片。
+
+<p>
+  <a href="https://pypi.org/project/ErisPulse-ShadowOps/"><img src="https://img.shields.io/pypi/v/ErisPulse-ShadowOps?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/ErisPulse-ShadowOps/"><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-ShadowOps"><img src="https://img.shields.io/github/stars/ErisPulse/ErisPulse-ShadowOps?style=for-the-badge&logo=github&color=brightgreen" alt="Stars"></a>
+  <a href="https://pepy.tech/project/ErisPulse-ShadowOps"><img src="https://img.shields.io/pepy/dt/ErisPulse-ShadowOps?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>
+
+---
+
+## 简介
+
+ShadowOps 是基于 [ErisPulse](https://github.com/ErisPulse/ErisPulse/) 架构开发的影子灰度运营模块。影子 = 同一模块的新版本，以独立 owner 与线上旧版并存试运行：收到真实事件副本、出站被拦截记账而非真正发出。本模块把这些运行时操作暴露为聊天命令：
+
+- `shadow start`：把 v2 代码目录装载为影子
+- `shadow diff`：对比 v1 实际发送 × v2 意向发送（按 trace_id 对齐）
+- `shadow promote`：确认后一键转正（失败自动回滚）
+- `shadow dismiss`：放弃影子
+- `shadow audit`：归属权审计（资源计数 / 孤儿 owner）
+
+要求 ErisPulse >= 2.9.0。
+
+---
+
+## 效果展示
+
+| `/shadow list` | `/shadow diff` | `/shadow audit` |
+|:---:|:---:|:---:|
+| ![list](.github/assets/demo/list-light.png) | ![diff](.github/assets/demo/diff-light.png) | ![audit](.github/assets/demo/audit-light.png) |
+
+---
+
+
+---
+
+## 安装
+
+```bash
+epsdk install ErisPulse-ShadowOps
+```
+
+---
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `/shadow` | 显示用法 |
+| `/shadow start <模块名> <v2路径>` | 启动影子（v2 代码目录或单 .py 文件，建议放在插件目录之外） |
+| `/shadow list` | 列出运行中的影子 |
+| `/shadow diff <模块名>` | 行为对比报告 |
+| `/shadow promote <模块名> yes` | 转正（必须带 `yes` 确认） |
+| `/shadow dismiss <模块名>` | 放弃影子 |
+| `/shadow audit <模块名>` | 归属权审计 |
+
+全部命令需要框架主人权限。
+
+---
+
+## 使用示例
+
+```bash
+# 1. 把新版代码放到服务器任意目录（如 downloads/roll_v2/）
+
+# 2. 启动灰度
+/shadow start roll downloads/roll_v2
+
+# 3. 试运行一段时间后对比行为
+/shadow diff roll
+
+# 4. 确认无害后转正（失败自动回滚旧版本）
+/shadow promote roll yes
+
+# 或放弃
+/shadow dismiss roll
+```
+
+---
+
+## 配置说明
+
+```toml
+[ShadowOps]
+enabled = true          # 是否启用模块
+diff_max_rows = 10      # 对比报告单次展示条目数
+audit_deep = false      # 审计附带 gc 实例普查（有全局暂停开销）
+render_card = true      # 报告用 Takumi 渲染为卡片
+theme = "auto"          # 卡片配色 (auto/light/dark)
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enabled` | bool | `true` | 是否启用模块 |
+| `diff_max_rows` | int | `10` | 对比报告条目上限 |
+| `audit_deep` | bool | `false` | gc 实例普查 |
+| `render_card` | bool | `true` | 卡片渲染 |
+| `theme` | str | `auto` | 卡片配色 |
+
+---
+
+## 注意事项
+
+1. 影子源为本地路径；同一 PyPI 包无法在同解释器内新旧并存
+2. promote 是运行时切换，重启后需持久化安装新版本（`pip install -U`）
+3. 走框架的发送/API/KV 全部拦得住；绕过框架的副作用不可拦截（audit 可见资源归属）
+
+---
+
+## 参考链接
+
+- [ErisPulse 主库](https://github.com/ErisPulse/ErisPulse/)
+- [影子模块文档](https://github.com/ErisPulse/ErisPulse/tree/main/docs/zh-CN/advanced/shadow.md)

erispulse_shadowops-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ShadowOps/Config.py,sha256=hCAmuBaTZuv3untrH2BLRKjVMJp-eKeE_Fh24ePUnSU,1644
+ShadowOps/Core.py,sha256=ytAh0qqe8j_sBI2xVt-vC19T4apKhydIC2_FWhhotAk,6124
+ShadowOps/I18n.py,sha256=vjqdXbl734Oyps_QDCmcviPmR55dWheAhgVlpCNZ3bI,6338
+ShadowOps/Service.py,sha256=cPnFCXB5E1-c7kkN3FVD7_WHiKn10xIShXu03UEI_Hk,6630
+ShadowOps/Visualizer.py,sha256=AwYPKfMjnEgEpNDGlQYpxoLvHEyNpsWTMxSkbg6xqHw,6908
+ShadowOps/__init__.py,sha256=xaiGuD9Rbj-TxCkPUmjV5own_F28Z-g_f76XOWkM6WY,91
+erispulse_shadowops-0.1.0.dist-info/licenses/LICENSE,sha256=OO7qHOo6QdvZahvf8NTfkgcVGuh8fqFcxKTvxmbmz_k,1065
+erispulse_shadowops-0.1.0.dist-info/METADATA,sha256=vkI6BGHdogXhtHMhPTeZPl_AlorkPxkcx6vmErjxIZ8,5020
+erispulse_shadowops-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+erispulse_shadowops-0.1.0.dist-info/entry_points.txt,sha256=p_6Eg-446l31m3PqNO7bk0JnHrcVzDNxBWNH4BLHNyk,46
+erispulse_shadowops-0.1.0.dist-info/top_level.txt,sha256=HT3nYaeNe5BoCNxhDlZMOZBUn-MvF9i_meHQdr8wN6c,10
+erispulse_shadowops-0.1.0.dist-info/RECORD,,

erispulse_shadowops-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_shadowops-0.1.0.dist-info/entry_points.txt

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

erispulse_shadowops-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_shadowops-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ShadowOps