微信操作（发消息 / 加好友 / 拉群）如果散落在代码各处，新增一个操作就要改多处。指令系统的作用是"统一注册、统一路由、统一执行、统一回收"。一条指令从生到死有4个阶段，本文按生命周期来讲Eyun项目里怎么搭这套系统。
一、4个指令生命周期阶段
1. 注册阶段：指令登记入册
每个指令注册时声明4要素——name（指令名如 SendNotification）、trigger（触发条件：定时 / 事件 / 手动）、handler（执行函数）、timeout（超时时间如30秒）。注册后指令进入"待命"状态。
大白话：指令注册像新员工入职填表——姓名、岗位（触发条件）、技能（handler）、试用期（超时），填完归档待命。
2. 路由阶段：触发条件满足时分发到对应 handler
trigger 满足（定时到点 / 事件到达 / 手动调用）→ 指令系统查注册表找到匹配指令 → 把上下文（触发数据 + 参数）传给 handler → handler 开始执行。Eyun Webhook 回调是 trigger 的事件源之一（消息事件触发回复指令、好友事件触发欢迎指令）。按照 Eyun 开发文档 的回调规范，4类事件回调（消息 / 好友 / 群 / 状态）可映射为4类指令 trigger。
大白话：触发条件满足后，系统像调度中心一样把任务派给对应的人。
3. 执行阶段：handler 干活并反馈进度
handler 执行业务逻辑（调 Eyun 的 sendText 发消息 / 调业务系统 API 查数据）→ 执行中可反馈进度（"处理中..."→ sendText）→ 执行完返回结果。按照 Eyun 开发文档的规范，sendText 需要传 wId、toUser、content 三个必填参数。Eyun 的错误码体系保证执行可靠性：1002 触发刷新、1004 退避重试，5秒回调超时会重试3次。
大白话：handler 是干活的工人——干的过程中可以汇报进度，干完交结果。
4. 回收阶段：指令执行完做收尾
handler 返回结果后 → 指令系统记录执行日志（指令名 + 触发时间 + 执行耗时 + 结果状态）→ 释放占用的资源（会话锁 / 临时文件）→ 超时未完成的指令标记为"超时"并触发补偿逻辑。
大白话：活干完了要"交工"——记录干了什么、花了多久、成功没有，然后收拾工具。
二、4阶段对比
生命周期阶段 | 做什么 | 触发条件 | 关键技术点 | Eyun 接口 | 大白话说明 |
|---|---|---|---|---|---|
注册 | 登记入册 | 启动时 | 4要素声明 | - | 新员工填表 |
路由 | 分发到 handler | trigger 满足 | 注册表查找 | Webhook 回调 | 调度中心派活 |
执行 | handler 干活 | handler 调用 | 进度反馈 | sendText | 工人干活 |
回收 | 收尾归档 | handler 返回 | 日志+资源释放 | - | 交工收拾工具 |
三、4阶段指令系统框架
registry = {} def register(name, trigger, timeout=30): # 注册阶段 def deco(handler): registry[name] = {name, trigger, handler, timeout, "待命"} return handler return deco def route(trigger_data): # 路由阶段 [execute(c, trigger_data) for c in registry.values() if c["trigger"].match(trigger_data)] def execute(cmd, ctx): # 执行阶段 try: cmd["handler"](ctx); recycle(cmd, "成功") # 干活+反馈进度 except TimeoutError: recycle(cmd, "超时") # 触发补偿 def recycle(cmd, status): # 回收阶段 log(cmd.name, cmd.cost, status); release(cmd.lock) # 日志+释放资源四、落地建议
4个阶段让微信操作从"散落调用"变成"统一管理"——注册阶段集中登记、路由阶段统一分发、执行阶段规范反馈、回收阶段自动归档。好处是"可观测"：每个指令什么时间被谁触发、执行多久、成功没有，全有记录。新增操作时只写 handler + 注册一行，4阶段管理逻辑复用。
进阶方向：指令加优先级字段（高优先级插队）、加依赖声明（A 指令依赖 B 指令先完成）、加重试策略（失败自动补偿）。接口参数和回调规范见 Eyun 开发文档。
