ErisPulse RFC EPRFC-2026-001 — ErisPulse 2.9.0 Roadmap Direction / ErisPulse 2.9.0 方向定调

ErisPulse RFC EPRFC-2026-001 — ErisPulse 2.9.0 Roadmap Direction / ErisPulse 2.9.0 方向定调

Status: RFC — Finalized Scope, Decisions & Examples · Delivery Status in Comments | Target Version: 2.9.0 | Published: 2026-09-13 | Revised: 2026-09-24

状态: RFC 定案——范围、决策与示例 · 交付进度见评论区 | 目标版本: 2.9.0 | 发布日期: 2026-09-13 | 修订日期: 2026-09-24

---

What 2.9 Covers / 一、2.9 要解决什么

ErisPulse 2.8 established the framework foundations (access scopes, multi-database storage, module RPC, lifecycle events). 2.9 focuses on the module development experience — turning every piece of boilerplate that every module author hand-writes into declarative framework capability:

ErisPulse 2.8 建立了框架能力基础（权限作用域、多数据库存储、模块间调用、生命周期事件）。2.9 聚焦**"写模块的体验"**——把每个模块作者都在手写的样板代码，上收为框架的声明式能力：

#	Direction / 方向	Problem Solved / 解决的问题
1	Command argument & option parsing / 命令参数与选项解析（args= + options=）	Manual parsing, manual type conversion, manual error replies / 手动解析参数、手动转换类型、手动报错
2	Dependency injection (unified across all injection points) / 依赖注入（统一颗粒度，全注入点一次做全）	Dependencies must be fetched manually and are hard to replace in tests / 依赖要自己获取，测试时难以替换
3	Testing toolkit / 测试框架	No official testing tools / 没有官方测试工具
4	Built-in data model layer (ORM) / 内置数据模型层	Only KV store and SQL builder — no model classes / 只有 KV 和 SQL 构建器，没有模型类
5	Module troubleshooting / 模块排查	When a module "doesn't respond", you dig through logs / 模块"没反应"时只能翻日志猜原因
6	Middleware event veto / 中间件事件否决权	Middleware can transform events but cannot drop them / 中间件只能改写事件、不能丢弃事件
7	Command governance (cooldown / rate_limit / usage_limit / deprecated) / 命令治理声明化	Hand-written cooldown timers, rate windows, usage quotas, deprecation notices / 手写冷却计时、限流窗口、用量配额、废弃提示
8	Event handler declaratives (throttle / debounce) / 事件处理器声明化	Hand-written anti-flood logic / 手写防刷屏逻辑
9	Config env mapping / 配置环境变量映射	Module config cannot be set via environment variables / 模块配置无法用环境变量注入
10	Module reload completeness (rollback & leak audit) / 模块重载完备性（失败回滚与泄漏审计）	Reload destroys the old instance when the new code fails to load; cleanup blind spots leak resources / reload 失败时旧实例已销毁、服务中断；清理盲区泄漏资源
11	Shadow modules & canary promote / 影子模块与灰度转正	Module upgrades replace in place — a buggy release hits real users / 模块升级直接替换，新版本有 bug 直接命中真实用户

---

1. Command Argument Parsing / 二、命令参数解析

Today / 现在的写法：

@command("roll")
async def roll(event):
    args = event.get_command_args()   # list of strings / 字符串列表
    verbose = "-v" in args or "--verbose" in args          # hand-written option handling / 手写选项处理
    args = [a for a in args if a not in ("-v", "--verbose")]
    count = int(args[0])              # manual conversion, user typos raise exceptions / 手动转换，输错直接抛异常
    ...

In 2.9 / 2.9 的写法：

@command(
    "roll",
    args="<count:int> [sides:int=6]",
    options={"verbose": "-v/--verbose", "label": "--label"},
    help="掷骰子",
)
async def roll(event, count: int, sides: int = 6, verbose: bool = False, label: str = ""):
    total = sum(random.randint(1, sides) for _ in range(count))
    await event.reply(f"掷了 {count} 次 {sides} 面骰，总点数：{total}")

Behavior / 行为说明：

Item / 项	Description / 说明
Positional args / 位置参数	args= as proposed: str, int, float, bool, literal (enum), duration (e.g. 90s, 1h30m), rest / args= 维持原提案：str、int、float、bool、literal（枚举）、duration（如 90s、1h30m）、rest（剩余全部文本）
Options / 选项	options= dict declaration: key = handler parameter name, value = flag form(s). -v/--verbose = boolean flag; --label = valued option (--label hello or --label=hello), type follows the handler annotation / options= 字典声明：键 = 处理器参数名，值 = 旗标形式。-v/--verbose 为布尔旗标；--label 为带值选项（--label hello 或 --label=hello），类型跟随处理器注解
Parsing order / 解析顺序	Options are extracted first, remaining tokens are parsed by args= (so rest covers the text left after option removal) / 选项先被识别剔除，剩余 token 再交给 args= 解析（rest 为剔除选项后的剩余文本）
Invalid input / 用户输入错误	Framework automatically replies with a localized "invalid argument" message (5 languages) — no exceptions, no crashes / 框架自动回复本地化的"参数错误"提示（五种语言），不会抛异常崩溃
Usage help / 使用帮助	args= + options= auto-generate usage text (including options) shown by the built-in help command / 自动生成 usage（含选项），/help 命令自动展示
Permissions / 权限	Permission checks run before parsing — unauthorized users never trigger parsing / 权限检查在前，参数解析在后——无权限的用户不会触发解析
Compatibility / 兼容性	Existing modules are completely unaffected — without args= / options=, behavior is unchanged / 现有模块完全不受影响，不写即原行为

Not in this version / 本版本不包含：platform-specific types such as user/group (require adapter support, planned for later versions / 需要各适配器配合，后续版本支持)；Chinese duration units such as 5分钟 (planned via optional language packs / 后续通过可选语言包支持)。

---

2. Dependency Injection / 三、依赖注入

Today / 现在的写法：

@command("admin")
async def admin(event):
    db = await sdk.module.call("DB", "get_session")   # every function fetches its own dependencies / 每个函数自己拿依赖
    ...

In 2.9 / 2.9 的写法：

from ErisPulse.di import Depends

async def get_db(event):
    return await sdk.module.call("DB", "get_session")

# Command handler / 命令处理器
@command("admin")
async def admin(event, db=Depends(get_db)): ...

# Event handler / 事件处理器
@message.on_message()
async def on_msg(event, db=Depends(get_db)): ...

# Lifecycle hook / 生命周期钩子
@lifecycle.on("adapter.bot.online")
async def on_online(data, db=Depends(get_db)): ...

# HTTP / WebSocket route handler / 路由处理器
@sdk.router.http_route("GET", "/stats")
async def stats(request, db=Depends(get_db)): ...

---

3. Testing Toolkit / 四、测试框架（独立包 ErisPulse-Testing）

2.9 ships an official testing toolkit. Writing a module test becomes:

2.9 提供官方测试工具，写模块测试只需：

def test_hello():
    bot = TestBot()
    bot.load_module("MyModule")

    event = create_command_event("hello", user_id="123")
    bot.dispatch(event)

    assert bot.last_reply.text == "你好，123！"

Provides simulated command/message events, reply recording, and temporary dependency replacement, working together with pytest.

提供：模拟命令/消息事件、记录机器人回复、临时替换依赖等能力，与 pytest 配合使用。

Testing stays a separate package: it only depends on the framework one-way and is a development-time tool, not runtime infrastructure.
测试工具保持独立包：它单向依赖框架、属于开发期工具而非运行时基础设施。

---

4. Built-in Data Model Layer / 五、内置数据模型层（ORM）

Adjusted from the earlier draft / 与此前草案的差别：the ORM ships built into the framework (not as a separate package). Rationale: the ORM is built directly on the built-in storage layer (async-native, contextvar nested transactions, SQLite / MySQL / PostgreSQL), so they must co-evolve — a separate package would pin SDK versions and risk API drift, and would add an extra dependency for every module author. The storage three-backend test matrix doubles as the ORM verification base.

由独立包调整为框架内置。理由：ORM 直接构建在内置存储层之上（async 原生、contextvar 嵌套事务、SQLite / MySQL / PostgreSQL），二者必须同源演进——独立包意味着 SDK 版本钉子与 API 漂移风险，且给每个模块作者增加一层额外依赖。存储层的多后端测试矩阵天然成为 ORM 的验证基座。

Target capability / 目标能力：

# 已定稿（2026-09-23）：独立 Field() 描述符（候选 B）/ Decided: standalone Field() descriptors (candidate B)
class User(Model):
    id: int = Field(primary_key=True, autoincrement=True)
    name: str = Field(max_length=64, index=True)

user = await User.create(name="Alice")
users = await User.where(User.age > 18).order_by("-age").limit(10).all()

Behavior / 行为说明：

Item / 项	Description / 说明
Declaration API / 声明 API	已定（2026-09-23）：独立 Field() 描述符（候选 B）；配置基座保持 @dataclass 普通值不变，二者共享约束词表 / 校验器 / 类型类别注册表 / Decided: standalone Field() descriptors (candidate B); the config base keeps plain values, sharing the constraint vocabulary / validator engine / type-category registry
Built on internal storage / 构建于内部存储	switching between SQLite / MySQL / PostgreSQL is transparent to the model layer / SQLite / MySQL / PostgreSQL 切换对模型层透明
Model-as-table / 模型即表	define a model and get full CRUD, with automatic table creation / 定义好模型即可增删改查，支持自动建表
Phased scope / 分阶段范围	staged scope: model CRUD → auto-migration → relationships, all within 2.9 / 范围分三阶段：模型 CRUD、自动迁移、关系映射——全部纳入 2.9
Out of scope / 不在范围	KV-only backends / 仅 KV 的后端

Relationship with the declarative config layer / 与声明式配置层的关系：

Model declarations follow the same declarative style as the existing config class (@dataclass + field(metadata=...)). The two domains share one field-declaration layer — but keep separate class bases by design:

模型声明与既有声明式配置类（@dataclass + field(metadata=...)）采用同一声明风格。两个领域共享同一字段声明层，但类基座有意分立：

Shared layer / 共享层	Separate bases / 分立基座
Field metadata vocabulary: default / description (i18n dict) / choices / constraints (max_length, ge/le) — one vocabulary consumed by both config and ORM / 字段元数据词表：默认值、描述（i18n 字典）、枚举、约束（max_length、ge/le）——配置与 ORM 消费同一词表	Class base / 类基座: config fields stay plain values (@dataclass, TOML round-trip) — fixed; the model base shape is decided: descriptors with column expressions / 配置字段保持普通值（既定）；模型基座形态已定：带列表达式的描述符
Type mapping registry: Python type → TOML type (config) and Python type → SQL dialect column type (ORM) derive from one registry / 类型映射注册表：Python 类型 → TOML 类型与 → SQL 方言列类型出自同一注册表	Consumption points: config keeps its five (schema / TOML template / defaults / dict fill / validation); ORM gets its own (schema / DDL / CRUD / validation / migration) / 消费点：配置保持既有五处；ORM 自成一套（schema / DDL / CRUD / 校验 / 迁移）
Validator engine: config write-validation and ORM insert/update validation share the same validator set (length / range / choices) / 校验器引擎：配置写入校验与 ORM 插入更新校验共用同一套校验器（长度 / 范围 / 枚举）	Instance lifecycle: config loads once + hot-reloads; models are per-row instances / 实例生命周期：配置一次加载 + 热更新；模型是逐行实例

Unifying the class bases themselves would force a breaking rewrite of every existing ConfigClass — deliberately not pursued. One declaration style, one shared field layer, two purpose-built bases / 不强行统一类基座——那将破坏性重写全部存量配置类。一份声明语法、一个共享字段层、两个各司其职的基座。

---

5. Module Troubleshooting / 六、模块排查

Pain point / 痛点：when a module "doesn't respond", you can only dig through logs / 模块"没反应"时，用户只能翻日志猜原因。

Scenario / 场景	Planned capability / 计划能力
Module failed to load / 模块没加载	Tell you exactly why (missing dependency / blocked by scope / SDK version too low) / 直接告知原因（依赖缺失 / 被作用域屏蔽 / SDK 版本不满足）
Event not received / 事件没响应	Check whether the event was filtered by scope or permission rules / 检查是否被作用域或权限规则过滤
Command not triggered / 命令没触发	Check prefix, aliases, permissions — and explain why it didn't match / 检查前缀、别名、权限，给出"为什么没匹配"的结论

---

6. Middleware Event Veto / 七、中间件事件否决权

Today / 现在的行为：

Middleware runs sequentially before dispatch and can transform the event, but it cannot stop the event from being dispatched. Firewalls, rate limiters and similar scenarios can only be implemented as high-priority event handlers as a workaround — and handlers can only block lower-priority processors, not the event itself.

中间件在分发前顺序执行、可以改写事件，但无法阻止事件继续分发。防火墙、限流等场景只能注册高优先级事件处理器绕行实现——且处理器只能阻断更低优先级的处理器，无法在事件层面丢弃。

In 2.9 / 2.9 的行为：

@sdk.adapter.middleware
async def rate_limit(data):
    if _is_banned(data):
        return False          # veto: event is dropped / 否决：事件被丢弃，不进入任何处理器
    data["rate_marked"] = True
    return data               # transform: same as today / 改写事件：与现在一致
    # returning None also keeps today's semantics / 返回 None 同样保持现有语义

Behavior / 行为说明：

Item / 项	Description / 说明
Veto / 否决	Returning False drops the event immediately: no handlers run, no side effects / 返回 False 立即丢弃事件：不进入任何处理器，无任何出站副作用
Transform / 改写	Returning a dict replaces the event payload — unchanged from today / 返回 dict 替换事件载荷——与现在一致
Pass-through / 放行	Returning None keeps today's semantics (payload unchanged) / 返回 None 保持现有语义（载荷不变）
Observability / 可观测	A veto emits a TRACE log and fires the adapter.event.blocked lifecycle hook (carrying the middleware name) for troubleshooting / 否决时输出 TRACE 日志并触发 adapter.event.blocked 生命周期钩子（携带中间件名），便于排查"为什么事件没响应"
Compatibility / 兼容性	Existing middlewares are completely unaffected — returning None / dict behaves exactly as before; only an explicit False vetoes / 现有中间件完全不受影响——返回 None / dict 行为不变，仅显式返回 False 才否决

Not in this version / 本版本不包含：negotiated veto (a later middleware overriding an earlier veto) / 后一个中间件推翻前一个否决的链式协商能力；if needed, it will be discussed in a follow-up issue / 如有需求将另开讨论。

---

7. Command Governance / 八、命令治理声明化（cooldown / rate_limit / usage_limit / deprecated）

Today / 现在的写法：

_last_use = {}

@command("daily")
async def daily(event):
    uid = event.get_user_id()
    if time.time() - _last_use.get(uid, 0) < 86400:   # hand-written cooldown / 手写冷却
        await event.reply("今天已签到")
        return
    _last_use[uid] = time.time()
    ...

In 2.9 / 2.9 的写法：

@command("daily", cooldown="1d", cooldown_key="user", cooldown_reply="今天已签到")
async def daily(event):
    await event.reply("签到成功")

@command("search", rate_limit="5/minute", rate_limit_key="user")
async def search(event): ...

@command("report", usage_limit="3/day", usage_limit_key="user")
async def report(event): ...   # business quota: 3 per natural day / 业务配额：每自然日 3 次

@command("oldcmd", deprecated="请用 /newcmd")
async def old(event): ...
# framework auto: help shows the deprecation mark + auto-reply on invocation / 框架自动：help 显示废弃标记 + 调用时自动回复

Behavior / 行为说明：

Item / 项	Description / 说明
cooldown / 冷却	Minimum interval per key; duration syntax identical to the args= duration type (90s, 1h30m, 1d) / 按键控最小间隔；时长语法与 args= 的 duration 类型完全一致（90s、1h30m、1d）
cooldown_key / 冷却键	user / session / global — reuses the framework session-key infrastructure / 复用框架会话键体系（platform:bot:user:target）
Hit behavior / 命中行为	Silently dropped by default (symmetric with scope silence); cooldown_reply provides the reply text. The command is claimed either way — never leaks to lower-priority message handlers / 默认静默丢弃（对称于作用域静默语义）；cooldown_reply 可选回复文案。命中时命令同样被认领——不会漏给低优先级消息处理器
rate_limit / 限流	Sliding window ("5/minute"); shares the limiter and session-key infrastructure with cooldown; router layer already has a precedent / 滑动窗口（"5/minute"）；与冷却共享限流器与会话键基础设施；路由层已有先例
usage_limit / 用量配额	Business quota per natural period ("3/day"), aligned to the local timezone — distinct from the rate_limit sliding window / 业务用量配额，对齐本地时区自然周期（"3/day"）；与 rate_limit 滑动窗口相区分
deprecated / 废弃	Help listing shows the deprecation mark; invocation auto-replies the deprecation text; deprecated_reject=True optionally refuses execution / 帮助列表显示废弃标记；调用时自动回复废弃文案；deprecated_reject=True 可选拒绝执行
Storage / 状态存储	In-memory per process; automatically cleared on module unload (owner cleanup) / 进程内内存态；模块卸载时自动清理（归属清理）
Compatibility / 兼容性	Existing modules are completely unaffected — without these params, behavior is unchanged / 现有模块完全不受影响，不写即原行为

Not in this version / 本版本不包含：distributed / multi-process shared state, persistence across restarts / 跨进程共享状态与重启后持久化（后续版本视需求）。

---

8. Event Handler Declaratives / 九、事件处理器声明化（throttle / debounce）

Today / 现在的写法：

@message.on_message()
async def handler(event):
    if not _should_process(event.get_user_id()):   # hand-written anti-flood / 手写防刷屏
        return
    ...

In 2.9 / 2.9 的写法：

@message.on_message(throttle="2s", throttle_key="user")
async def handler(event): ...
# at most one event per user per 2s; the rest are dropped / 同一用户 2s 内至多处理一条，其余丢弃

Behavior / 行为说明：

Item / 项	Description / 说明
throttle / 节流	Per-key minimum interval; events within the interval are dropped (implemented as a framework-provided condition wrapper over the existing handler-condition mechanism) / 按键控最小间隔，间隔内事件直接丢弃（实现为框架在既有处理器条件机制上提供的包装器）
throttle_key / 节流键	Same session-key infra as cooldown / 与冷却同一套会话键体系
debounce / 防抖	Multiple events within the window: only the last one is handled — implemented as a condition wrapper (delayed execution + predecessor cancellation); mutually exclusive with throttle=, declaring both fails at registration / 窗口内多条消息只处理最后一条——以条件包装器实现（延迟执行 + 取消前序任务）；与 throttle= 互斥，同时声明注册期抛错
Compatibility / 兼容性	Existing handlers are completely unaffected — without these params, behavior is unchanged / 现有处理器完全不受影响，不写即原行为

---

9. Config Env Mapping / 十、配置环境变量映射

Today / 现状：

Framework config already supports ERISPULSE_* environment variable overrides — but module config does not. Docker / CI users must edit config.toml by hand or read os.environ themselves.

框架配置已有 ERISPULSE_* 环境变量覆盖——但模块自己的配置没有。Docker / CI 场景只能手改 config.toml 或自己读 os.environ。

In 2.9 / 2.9 的写法：

@dataclass
class MyConfig(BaseConfig):
    api_key: str = field(default="", metadata={
        "env": "MYMODULE_API_KEY",   # env var binding / 环境变量绑定
    })

Behavior / 行为说明：

Item / 项	Description / 说明
Precedence / 优先级	environment variable > config.toml > declared default / 环境变量 > config.toml > 声明默认值
Constraint / 实现约束	Must be implemented consistently across all five config-schema consumption points (schema / TOML template / defaults / dict fill / validation) so one declaration works everywhere / 必须在配置 Schema 的五处消费点（schema / TOML 模板 / 默认值 / dict 填充 / 校验）一致实现，保证声明一处、处处生效
Compatibility / 兼容性	Existing modules are completely unaffected — without env metadata, behavior is unchanged / 现有模块完全不受影响，不写 metadata 即原行为

---

10. Module Reload Completeness / 十一、模块重载完备性（完全卸载、失败回滚与泄漏审计）

Today / 现状：

reload("roll")
  → unload 旧实例（清理链执行）
  → 弹出 sys.modules 旧条目，重新 import 新代码
  → load() 失败（语法错误 / 依赖缺失 / 初始化异常）
  → 模块处于未加载状态，旧实例已销毁 —— 服务中断，需手动恢复

In 2.9 / 2.9 的行为：

reload("roll")
  → 快照：旧实例引用 + 注册表状态（轻量）
  → 卸载 → 导入 → load()
  → 任一步失败：自动回滚，旧实例继续服务
  → 日志: "reload failed, rolled back to previous instance"

Behavior / 行为说明：

Item / 项	Description / 说明
Snapshot rollback / 快照回滚	Unload / import / load() — if any step fails, the previous instance is restored and service continues; best-effort semantics / 卸载、导入、load() 任一步失败即恢复旧实例，服务不中断；尽力而为语义
Blind-spot fixes / 清理盲区修复	Platform event-method injections (register_event_method) are reclaimed on module unload; a failed on_load triggers a half-unload so __init__ side effects leave no orphan resources / 平台事件方法注入随模块卸载回收；on_load 失败时执行半卸载，__init__ 副作用不残留
Route unregister fix / 路由注销修复	Routes are unregistered by (namespace, path) — same-path routes of other namespaces are no longer deleted / 按 (namespace, path) 精确注销，不再误删其它命名空间的同 path 路由
Leak auditor / 泄漏审计器	Read-only per-owner resource counts + orphan-owner reverse scan (resources whose owner is gone) + weakref instance census + gc.get_referrers holder identification; runs automatically after unload/reload; CLI epsdk audit [module] (--json for the Dashboard) / per-owner 资源只读计数 + 孤儿 owner 反向扫描（资源在、主人已注销）+ weakref 实例普查 + gc.get_referrers 指认持有者；unload/reload 后自动运行；CLI epsdk audit [module]（--json 供 Dashboard）
Compatibility / 兼容性	Purely additive read-only APIs; persist=True user-config assets still survive unload (documented boundary unchanged); bare threads / third-party private containers remain out of reach — but become visible via the auditor / 纯新增只读 API；persist=True 用户配置语义资产仍不随卸载清理（设计边界不变）；裸线程 / 第三方私有容器引用依然清不掉——但从不可见变为可见
Not in this version / 本版本不包含	Cross-process rolling reload; adapter hot-reload; memory governance beyond forced GC / 跨进程级联重载编排；适配器热重载；强制 GC 之外的内存治理

Prerequisite for direction 11 (shadow modules): promote relies on "complete unload + verifiable zero residue" / 为方向 11（影子模块）提供前置能力——promote 依赖「完全卸载 + 无残留可验证」。

---

11. Shadow Modules & Canary Promote / 十二、影子模块与灰度转正

Today / 现状：

pip install -U roll-module → 重启/重载 → 祈祷

No "trial run first, promote later" intermediate state — real group chats always cover what test environments miss.

没有「先试运行、再转正」的中间态——真实群聊的消息分布永远是测试环境覆盖不到的。

In 2.9 / 2.9 的写法：

[modules.roll.shadow.v2]
source = "roll==2.0.0"          # PyPI spec, or a plugins/ local path / PyPI 规格，或 plugins/ 本地路径
sessions = ["telegram:*:*"]     # optional: roll out to a subset of sessions (scope syntax) / 可选：按 scope 语法放量到部分会话

The shadow instance runs as a separate owner (e.g. roll_shadow) alongside the old version — zero module-code changes; the shadow is a layer the bot owner enables in config:

影子实例以独立 owner（如 roll_shadow）与旧版并存，模块代码零改动——影子是主人在配置里启用的一层：

用户消息 ──┬─→ roll (v1)        ──→ 正常服务
           └─→ roll_shadow (v2) ──→ 正常运行，出站被闸门拦截记录

Behavior / 行为说明：

Item / 项	Description / 说明
Coexistence / 共存	The owner-ownership system isolates handlers / routes / tasks / waiting sessions / i18n / config by owner; the shadow inherits the original module's config section by default / owner 归属体系按 owner 隔离处理器、路由、任务、等待会话、i18n 与配置；影子默认继承原模块配置节
Event copy / 事件副本	Events admitted by scope are copied to the shadow with a shadow marker; the shadow is excluded from the dependency graph (module.call and dependency resolution still point to v1) / scope 准入后复制投递并带 shadow 标记；影子不参与生态依赖图（module.call 与依赖解析仍指向 v1，避免半成品被依赖）
Outbound gate / 出站闸门	All shadow Send DSL and Api calls are intercepted and recorded, never actually sent (reusing the outbound rule wrapper) — no duplicate replies / 影子的 Send DSL 与 Api 调用全部拦截记录、不真正发出（复用出站规则包装层）——不产生重复回复
Storage overlay / 存储覆盖层	Shadow writes land in an in-memory overlay and are discarded; reads pass through to the real database / 影子写入进入内存覆盖层、丢弃落库；读取放行真库
Name-keyed collisions / 名键冲突对策	Same-name commands → intercepted into a shadow command catalog (not real dispatch); platform event-method injection → forbidden for shadows; same-path routes → registered in the shadow manifest only / 同名命令 → 拦截进影子命令目录（不参与真分发）；平台事件方法注入 → 影子禁止注入真表；同 path 路由 → 仅登记影子清单
Diff & promote / 对比与转正	v1 actual sends (transcript) vs v2 intended sends (shadow ledger) aligned by trace_id; a failed promote rolls back to v1 automatically / v1 实际发送（transcript）vs v2 意向发送（影子账本）按 trace_id 对齐；promote 失败自动回滚 v1
Honest boundary / 诚实边界	Framework-routed sends / APIs / storage / the unified HTTP client are all intercepted; raw connections or threads bypassing the framework are not — documented, and visible to the auditor (direction 10) / 走框架的发送 / API / 存储 / 统一 HTTP 客户端全部拦得住；绕过框架的裸连接 / 线程拦不住——文档明示，审计器（方向 10）可见
Compatibility / 兼容性	Without shadow config, zero behavior change; module authors are unaware / 不写 shadow 配置时零行为变化；模块作者零感知
Not in this version / 本版本不包含	Multiple concurrent shadows; automatic A/B traffic splitting or auto-promotion (promotion is always human-confirmed); cross-process shadows / 多影子并存；A/B 自动流量切分与自动晋升（转正永远由人确认）；跨进程影子

Promote CLI / 转正命令：

$ epsdk module diff roll              # v1/v2 behavior diff summary / 行为差异摘要
$ epsdk module promote roll --to v2   # snapshot → full unload of v1 (direction 10 + audit) → v2 takes the real name
$ epsdk module dismiss roll           # discard the shadow / 放弃影子

---

Feedback / 十三、反馈

Reply by number. Direction-level disagreements are especially welcome — if you disagree, please describe your use case.

按编号回复即可，方向级反对尤其欢迎——反对时请描述你的使用场景。

1. Are the argument/option types enough? Is the dict-style options= declaration the right fit? / 参数与选项类型够用吗？字典式 options= 声明是否合意？
2. Does the unified DI cover all your injection points? Anything missing (e.g. module RPC entry, scheduled tasks)? / 统一依赖注入覆盖了你的全部注入点吗？还有遗漏（如模块 RPC 入口、定时任务）？
3. What else does the testing toolkit need? / 测试工具还缺什么能力？
4. The ORM now ships built-in instead of a separate package — thoughts? And which capability do you need most: CRUD / auto-migration / relationships? Declaration style preference: config-class style (@dataclass + field(metadata=...)) or standalone Field() descriptors? / ORM 改为内置交付（原独立包）——你的意见？最期待哪个能力：增删改查 / 自动迁移 / 关系映射？声明风格偏好：配置类同款（@dataclass + field(metadata=...)) 还是独立 Field() 描述符？
5. Which troubleshooting scenario should be solved first? / 模块排查你最想先解决哪个场景？
6. Any disagreement on the priority order? What is missing from 2.9? (Candidates not on the main line: command_group registrar sugar, CLI config overrides — both P2 / 优先级排序有不同意见吗？2.9 还漏了什么？未入主线的候选：command_group 注册器语法糖、CLI 式配置覆盖——均为 P2)
7. Is explicit False as the middleware veto signal sufficient for your firewall / rate-limit scenarios? / 防火墙/限流场景下，显式返回 False 作为否决信号是否够用？
8. Is "silent by default + optional cooldown_reply" the right default for cooldown hits? And is "5/minute" the right rate-limit syntax? / 冷却命中"默认静默 + 可选回复文案"是否合意？"5/minute" 限流语法是否合适？
9. Module reload completeness: is instance-reference-level snapshot enough for the rollback? Should the leak auditor run automatically after unload/reload by default? / 模块重载完备性：回滚快照取实例引用级别是否足够？泄漏审计器默认随 unload/reload 自动运行是否合适？
10. Shadow modules: prefer a separate sub-registry (module.shadow("roll")) over the roll_shadow owner naming? Is "read the real database, write to the overlay" the right storage semantics? / 影子模块：独立子注册表（module.shadow("roll")）与 roll_shadow 命名孰优？存储「读真库、写覆盖层」口径是否合适？

---

ErisPulse Core Team — 2026-09-13 发布 / 2026-09-14 修订 / 2026-09-23 修订（交付状态与后续候选）/ 2026-09-24 修订（结构拆分：交付状态移至进度评论；usage_limit= 并入治理章节；新增方向 10/11：模块重载完备性、影子模块与灰度转正）

[wsu2059q]

Status: Implementation Progress Update — All Nine Directions Delivered | Date: 2026-09-21 | Revised: 2026-09-24

状态：实现进度更新——九方向已全量交付 | 日期：2026-09-21 | 修订日期：2026-09-24

Status: Implementation Progress Update — All Eleven Directions Delivered | Date: 2026-09-21 | Revised: 2026-09-25

状态：实现进度更新——十一方向已全量交付 | 日期：2026-09-21 | 修订日期：2026-09-25

Directions 1–9 are delivered on Develop/v2 (now the main development branch, 2.9.0-dev.0), with full unit coverage. Directions 10–11 (module reload completeness, shadow modules) were added to the 2.9 scope on 2026-09-24 and delivered on 2026-09-25 — same branch, full unit coverage.

方向 1–9 已交付至 Develop/v2（现为主开发分支，2.9.0-dev.0），全部带完整单测覆盖。方向 10–11（模块重载完备性、影子模块）于 2026-09-24 纳入 2.9 范围、2026-09-25 交付——同分支、同测试覆盖标准。

#	Direction / 方向	Status / 状态	Notes / 说明
1	Command args & options (args= + options=) / 命令参数与选项解析	✅ 2.9.0 done / 已完成	7 types (str/int/float/bool/literal/duration/rest), localized error replies (5 languages), auto usage in /help / 七类型、五语言错误回复、/help 自动用法
2	Dependency injection / 依赖注入	✅ 2.9.0 done / 已完成	All injection points + request-level cache (use_cache, default on) + Depends.module sugar / 全注入点 + 请求级缓存（默认开启）+ Depends.module 语法糖
3	Testing toolkit / 测试框架	✅ Shipped / 已交付	ErisPulse-Testing 0.1.0: TestBot, event factories, reply recording, patch_dependency, pytest fixtures / 0.1.0：TestBot、事件工厂、回复记录、依赖替换、pytest fixtures
4	ORM phase 1 (models & CRUD) / 内置 ORM 阶段一	✅ 2.9.0 done / 已完成	Model + Field descriptors (candidate B), auto table creation, Active Record CRUD, transaction reuse, dialect-aware DDL (SQLite/MySQL/PostgreSQL) / 候选 B 的 Field() 描述符、自动建表、Active Record CRUD、事务复用、方言 DDL
4b	ORM phase 2: auto-migration / ORM 阶段二自动迁移	✅ 2.9.0-dev.0 交付（提前）	automatic ADD COLUMN migration for new fields / 新增字段自动加列迁移
4c	ORM relationships / ORM 关系映射	✅ 2.9.0-dev.0 交付（提前）	relationship(related, foreign_key) mapping / relationship(related, foreign_key) 关系映射
5	Module troubleshooting / 模块排查	✅ 2.9.0 done / 已完成	All three scenarios delivered（2026-09-23 修订）：explain_module / explain_event diagnostics + the dispatch decision chain (Core/Event/trace) — every decision point of a command dispatch (match → scope → ACL → master → permission → cooldown → args → execution → middleware veto) recorded as a causal chain; DispatchTrace.verdict / explain() answers "why didn't my command trigger". Troubleshooting guide at docs/zh-CN/developer-guide/module-troubleshooting.md / 三场景全量交付：explain_module / explain_event 诊断器 + 分发决策链——命令分发的每个判定点串成因果链，直接回答"命令为什么没触发"；排查指南见 docs/zh-CN/developer-guide/module-troubleshooting.md
6	Middleware event veto / 中间件否决权	✅ 2.9.0 done / 已完成	Explicit False drops the event; TRACE log + adapter.event.blocked hook with middleware name / 显式 False 丢弃事件；TRACE 日志 + 携带中间件名的钩子
7	Command governance — cooldown= / 命令治理·冷却	✅ 2.9.0 done / 已完成	Duration syntax shared with args=, cooldown_key user/session/global reusing session keys, silent-drop by default + optional reply, unload cleanup / 时长与 args= 同口径、三粒度复用会话键、默认静默 + 可选回复、卸载清理
7b	rate_limit= / deprecated= / usage_limit=	✅ 2.9.0-dev.0 交付（含新增 usage_limit=）	Sliding-window rate_limit=, deprecation mark + auto-reply (deprecated_reject=True optionally refuses), natural-period usage_limit= quota; all share the session-key infra and unload cleanup / 滑动窗口限流、废弃标记 + 调用自动回复（deprecated_reject=True 可选拒绝执行）、自然周期配额 usage_limit=；共用会话键体系与卸载清理
8	Handler throttle / debounce / 事件处理器声明化	✅ 2.9.0-dev.0 交付（提前）	throttle= + debounce= both shipped as condition wrappers (debounce: delayed execution + predecessor cancellation); mutually exclusive — declaring both fails at registration / throttle= 与 debounce= 双双以条件包装器交付（防抖为延迟执行 + 取消前序任务）；二者互斥，同时声明注册期抛错
9	Config env mapping / 配置环境变量映射	✅ 2.9.0 done / 已完成	metadata={"env": ...}, precedence env > toml > default, consistent across all five schema consumption points / 五处消费点一致
10	Module reload completeness / 模块重载完备性	✅ 2026-09-25 交付（Develop/v2）	Snapshot rollback on reload failure, cleanup blind-spot fixes, route unregister fix, leak auditor epsdk audit / reload 失败快照回滚、清理盲区修复、路由注销修复、泄漏审计器
11	Shadow modules & canary promote / 影子模块与灰度转正	✅ 2026-09-25 交付（Develop/v2）	Independent-owner coexistence, five isolation gates, sdk.module.shadow_start / shadow_diff / promote_shadow / dismiss_shadow / 独立 owner 共存、五道隔离闸、运行时 API 驱动（无配置项）

A note on direction 5: the dispatch decision chain is also exposed to tests — TestBot.dispatch() returns the DispatchTrace directly, so "why didn't my command trigger" becomes a first-class assertion in module tests.

关于方向五补充一句：分发决策链同时暴露给了测试——TestBot.dispatch() 直接返回 DispatchTrace，"命令为什么没触发"在模块测试里成为一等断言。

Remaining on the 2.9.0 line: ORM MySQL / PostgreSQL real-machine verification (SQLite passed), ecosystem compatibility checks (ErisPulse-Dashboard, core adapters), then soak and cut 2.9.0 final. Feedback questions above remain open.

2.9.0 线上剩余：ORM MySQL / PostgreSQL 真机验证（SQLite 已通过）、生态兼容验证（ErisPulse-Dashboard、核心适配器）、dev 浸泡后收口 2.9.0 正式版。上方反馈问题持续开放。

Before 2.9.0 final / 正式版收尾清单

• usage_limit= 补记 CHANGELOG（done / 已完成）
• 模块排查指南 docs/zh-CN/developer-guide/module-troubleshooting.md（done / 已完成）
• ORM MySQL / PostgreSQL 真机验证（2026/09/25 真机通过：存储引擎 12+12、ORM 14+14，SQLite 单测 32；顺带修复 asyncpg 提交句柄跳过 / PG 布尔 DDL 默认值 / 列枚举执行类型三问题）
• 生态兼容验证（ErisPulse-Dashboard、核心适配器 / ecosystem compatibility check）
• dev 浸泡后 2.9.0 收口（soak, then cut 2.9.0 final）

---

ErisPulse Core Team — 2026-09-21 / 2026-09-24 修订（全量交付状态；主帖交付表述已迁入本评论）