产出模块数据模型和接口-20260723

[JunLang-7]

产出模块数据模型和接口-20260723

[ZhaoXingPeng]

VoiceLife（声活）MVP 整体架构设计

文档状态：持续维护的架构共识

初始基线日期：2026-07-31

最近修订日期：2026-08-18

本次修订：增加 IM Gateway 多设备注册认证，以及设备与外部 IM
身份的一对一 active 绑定规则。

1. 核心目标

1.1 一句话目标

构建一个"语音优先、IM 辅助"的日程提醒系统，以本地为业务事实源，通过清晰的模块划分实现语音交互、日程管理、定时调度和 IM 消息投递的主链路闭环。

1.2 V0 范围

VoiceLife MVP 整体架构覆盖：

• 语音交互编排（AudioDevice → VoiceSessionCoordinator → XRobot）
• MCP 工具注册与调用路由（MCP Server）
• 日程 CRUD、周期规则、冲突检测与单次例外（Schedule Service）
• 定时任务注册与到点触发（TimingTask）
• IM 身份绑定、通知投递与用户动作处理（IM Application + Koishi Gateway）
• M Gateway 设备注册、多设备认证和设备所有者隔离
• 设备与外部 IM 身份的一对一 active 绑定

不进入 V0：

• 设备公网自注册、用户自助激活和设备所有权转让
• 同一设备同时向多个外部身份投递的复杂优先级或广播路由
• 企业微信、飞书、钉钉正式接入（仅通过 Koishi Adapter 预留扩展）
• 群聊提醒
• 断网/离线运行场景
• Satori 对外协议

运行假设：MVP 运行期间设备保持联网，XRobot/灵矽语音服务可用；系统不承诺断网时的语音交互、播报或日程操作能力。

1.3 核心质量目标

优先级	质量目标	可验证场景
P0	数据归属清晰	本地日程、周期规则、单次例外与定时任务注册表是完整事实源，IM 与 XRobot 不保存可替代副本
P0	跨边界幂等	工具调用、提醒投递、平台回执或用户动作重复到达时，不产生重复日程或重复业务动作
P0	状态可追踪	一次语音操作能从 sessionId 追踪到 toolCallId、scheduleId、taskId 和 IM deliveryId
P1	外部能力可替换	业务模块不依赖 XRobot 原始消息、Koishi Session、微信 XML 或平台专属字段
P1	失败可恢复	IM 临时失败可检测并降级，设备重启后可恢复未完成调度

---

2. 核心概念定义

2.1 部署单元

• 小智本地进程：部署在小智设备上的单进程，包含 AudioDevice、VoiceSessionCoordinator、MCP Server、Schedule、TimingTask、Local DB。MVP 的业务事实源。
• 灵矽（XRobot）：直接调用的外部 ASR/LLM/TTS 与 MCP Client 平台，通过 WebSocket 与灵矽平台进行语音识别、LLM 理解和 TTS 合成。MVP 语音交互和语音播报的必需依赖，不保存 VoiceLife 业务事实。
• VoiceLife IM Gateway：独立部署的服务端，承载 IM Application、Koishi Runtime、平台适配与能力插件。可独立扩缩容，不接管本地日程和调度。

2.2 模块角色

• AudioDevice Adapter：麦克风采集、音频编解码、播放。不持有会话状态或业务数据。
• VoiceSessionCoordinator：管理 Session/Turn/Generation，编排录音/播放，处理 XRobot WebSocket 连接与重连。不负责日程 CRUD 或 IM 投递。
• MCP Server：工具注册、Schema 校验、tools/list、tools/call、结果封装。不拥有日程或提醒状态。
• Schedule Service：日程 CRUD、周期规则、冲突检测、单次例外；到点后在 callback 中完成投递与下一次排程。回答"用户安排了什么、到点后做什么"。
• TimingTask：一次性 task 注册与到点触发（RegisterTask / CancelTask），不理解日程内容、提醒等级与 callback 的业务含义。回答"何时触发哪一次"。
• IM Application：身份绑定、路由选择、通知投递、回执归并和动作执行入口。不修改日程事实。
• Koishi Gateway：通用 IM Session、收发适配、标准事件归一化。不包含 VoiceLife 业务规则。
• Platform Capability Plugin：微信/企微/飞书/钉钉专属模板、卡片、验签和回调。不涉及平台无关业务规则。

2.3 关键标识

阶段	标识	用途
语音会话	sessionId、turnId、generation	隔离轮次、取消和迟到音频
工具调用	toolCallId、requestId	工具幂等与结果回传
日程业务	scheduleId、ruleId、exceptionId	日程、周期规则与单次例外
调度执行	taskId、triggerAt	单次触发实例与到点时刻
业务事件	eventId、correlationId	跨服务去重和链路追踪
IM 投递	notificationIntentId、deliveryId、attemptId	投递与重试审计
用户动作	actionId、commandId、operationId	关联 SSE 命令、执行结果并防止重复关闭或推迟

---

3. 核心业务流程

3.1 语音创建日程

sequenceDiagram
  actor User as 用户
  participant Device as AudioDevice
  participant Voice as VoiceCoordinator
  participant XR as XRobot
  participant MCP as MCP Server
  participant S as Schedule
  participant T as TimingTask
  participant DB as Local DB
  participant IM as IM Application

  User->>Device: 说出日程
  Device->>Voice: 音频帧
  Voice->>XR: 音频 + Session/Turn
  XR-->>Voice: ASR / ToolCall
  Voice->>MCP: tools/call(requestId)
  MCP->>S: schedule.create
  S->>S: 冲突检测
  S->>DB: BEGIN；保存 schedule / rule / exception
  DB-->>S: scheduleId / ruleId
  S->>T: RegisterTask(task_id, trigger_at, callback)
  T->>T: 命令进入 Runner 队列，应用到内存注册表
  T-->>S: accepted
  S->>DB: COMMIT
  S-->>MCP: 真实业务结果
  S-->>IM: ScheduleReceiptIntent
  MCP-->>XR: ToolResult
  XR-->>Voice: 回复文本 / TTS
  Voice-->>Device: 播放

Loading

3.2 到点提醒与 IM 投递

sequenceDiagram
  participant T as TimingTask
  participant S as Schedule
  participant IM as IM Application
  participant K as Koishi Gateway
  participant WX as 微信

  T->>T: esp_timer 到期，Runner 组装到期批次
  T->>S: 调用 callback on_task_due(task_id, trigger_at)
  S->>S: 先按最新规则注册下一次 task（RegisterTask）
  S->>S: 再投递本次提醒内容（IM / 语音）
  S-->>IM: NotificationIntent(taskId)
  IM->>IM: 校验 eventId、解析有效绑定
  IM-->>S: deliveryId + actionExpiresAt
  S->>IM: GET reminder-actions/stream（仅强提醒，SSE）
  IM-->>S: connected（有效窗口内）
  IM->>K: 创建 Delivery 并发送
  K->>WX: 模板/消息
  WX-->>K: accepted / delivered / failed
  K-->>IM: NormalizedImEvent
  IM->>IM: 幂等合并 Receipt

Loading

3.3 微信关闭或推迟提醒

sequenceDiagram
  actor User as 用户
  participant WX as 微信/H5
  participant K as Koishi Gateway
  participant IM as IM Application
  participant T as 本地日程模块

  User->>WX: 知道了 / 推迟 10 分钟
  WX->>K: Action UI POST / interaction/button
  K->>IM: ReminderActionHandler → IM Application.Action
  IM->>IM: 验签、版本、身份、Delivery、operationId 幂等校验
  IM-->>K: 动作已接收，等待设备执行
  K-->>WX: 显示处理中
  IM-->>T: SSE ReminderActionCommand(commandId)
  T->>T: 执行 dismiss / snooze；snooze 时取消旧 task、按新 trigger_at 注册新 task

  alt 执行成功
    T->>IM: POST ReminderActionResult(succeeded)
    IM->>IM: 更新 Action=succeeded
    IM-->>T: HTTP 200 Result Accepted
    IM--xT: 关闭当前 SSE
    IM-->>K: 更新消息或 H5 结果
    K-->>WX: 显示已知道 / 已推迟
    opt snooze
      Note over T,IM: 到下一次 trigger_at 再次触发时重新建立 SSE
    end
  else 可重试失败
    T->>IM: POST ReminderActionResult(retryable_failed)
    IM->>IM: Action 保持待执行
    IM-->>T: 保持 SSE，可重放同一 commandId
  else 已过期或不可重试
    T->>IM: POST ReminderActionResult(expired / failed)
    IM->>IM: 更新 Action=expired / failed
    IM-->>T: HTTP 200 Result Accepted
    IM--xT: 关闭当前 SSE
    IM-->>K: 更新失败或过期结果
    K-->>WX: 显示操作失败 / 已过期
  end

Loading

---

整体架构 - 详细技术设计 V1

一、总体架构

VoiceLife 是一个"语音优先、IM 辅助"的日程提醒系统。MVP 的部署分为三个边界：

部署单元	职责概要
小智本地进程	语音交互、MCP 工具路由、日程管理、定时调度、本地数据库
XRobot 平台	ASR/LLM/TTS、MCP Client（外部依赖，不保存业务数据）
VoiceLife IM Gateway	IM 身份绑定、消息投递、回执管理、平台适配（可独立部署）

六个核心模块

模块	一句话职责	数据归属
AudioDevice Adapter	麦克风采集、音频编解码、播放（小智已实现）	短期音频缓冲
VoiceSessionCoordinator	管理会话/轮次，编排语音交互，连接 XRobot	会话运行态
MCP Server	工具注册、参数校验、调用路由	工具定义表
Schedule Service	日程 CRUD、周期规则、冲突检测与单次例外	schedule、schedule_rule、schedule_exception
TimingTask	一次性 task 注册与到点触发（RegisterTask / CancelTask）	task 注册表（MVP 驻留内存）
IM Application	身份绑定、通知投递、回执归并、用户动作校验	IM 领域表（独立服务端）

关键边界决策

1. Schedule 与 TimingTask 分离：Schedule 回答"用户安排了什么、到点后做什么"，TimingTask 回答"何时触发哪一次"。
2. 一次性 task 契约：日程模块把周期规则展开为具体 trigger_at 后注册一次性 task（task_id 永不复用）；到点时定时任务模块调用 callback，由 callback 完成投递与下一次排程。提醒配置与运行态操作（snooze / dismiss）全部归日程模块，定时任务模块不理解这些语义。
3. MCP Registry 与语音 ToolGateway 是同一逻辑模块：本地只保留一份工具定义和路由。
4. 业务回执由领域模块产生：例如 Schedule 事务提交成功后，由 Schedule 向 IM Application 发送 ScheduleReceiptIntent；MCP 只转发工具结果。
5. IM 用户动作不直写本地库：动作经过绑定、Token、目标提醒（日程模块）和 operationId 校验后，以命令回传本地日程模块执行。
6. 用户动作采用临时 SSE 下行：只有强提醒进入可操作窗口时，本地日程模块才建立 SSE；IM 通过 SSE 下发命令，本地通过 HTTPS 回传结果。连接在 dismiss、snooze 或 actionExpiresAt 到期时关闭，不维持第二条永久 WebSocket，也不引入 Local Outbox。

设计原则

1. 本地优先，IM 辅助：Schedule、ScheduleRule、ScheduleException 与定时任务注册表的权威数据位于本地。IM 服务端只保存外部身份、绑定、通知投递和用户动作审计。
2. 领域事实与适配器分离：XRobot、Koishi 和微信类型不进入业务核心模型。MCP 不拥有业务状态，Koishi Session 不进入领域逻辑。
3. 命令同步确认，事件异步传播：进程内领域操作使用同步 Port；跨网络回执、通知和状态传播使用异步事件，必须携带幂等标识。

---

二、语音模块（Voice）

1. 行业调研

语音模块参考了小智官方架构（xiaozhi-esp32），核心链路为：

MIC -> Audio Engine -> Opus Encoder -> Protocol -> XRobot Server
XRobot Server -> Protocol -> Opus Decoder -> Playback Queue -> Speaker

小智官方架构适合单设备固件，但在 XE6-15 中需解决：Application 中心化导致业务模块耦合；无开放 Session/Turn/Generation 模型；无通用主动文本播报接口。因此 XE6-15 在保留小智音频链路基础上增加稳定接口层。

2. 核心概念定义

概念	理解	作用
AudioDevice	耳朵和嘴巴	采集麦克风声音并播放回复音频
SpeechProvider	外接大脑	把语音转文字、理解意图。XRobot 是 V0 实现
VoiceSessionCoordinator	总调度员	安排录音、处理、工具调用、播放、取消和结束
ToolGateway	派单中心	按工具名路由到日程、提醒等模块
VoiceEvent	状态通知	告知 UI、IM 和诊断模块当前状态
Announcement	主动播报	无用户提问时，由模块主动请求播报

三个关联标识：

• VoiceSessionID（会话 ID）：一次完整语音交互，可包含多轮问答
• VoiceTurnID（轮次 ID）：用户一句话到系统回复的过程
• Generation（有效代次）：处理版本号，新一轮/取消时递增，识别迟到消息

例如：

Session S1
├── Turn T1：明天下午三点帮我开会
├── Turn T2：提前十五分钟提醒
└── Turn T3：算了，取消刚才的安排

Generation 只能阻止旧结果播放，不能回滚已提交的业务操作。

3. 核心业务流程

流程一：用户通过语音创建日程

按键/唤醒词 → 创建 Session/Turn → 采集音频 → XRobot 转写
→ XRobot 发出 ToolCall → ToolGateway 路由到业务模块
→ 业务执行并返回 ToolResult → XRobot 生成回复 → 播放
→ VoiceEvent 发布结果

流程二：提醒模块发起主动播报

Reminder 到点 → 提交 Announcement
→ 检查 Provider 是否支持播报
→ 支持：排队/打断当前播放 → 完成后发布 completed
→ 不支持：返回错误，降级到 IM

流程三：用户取消

用户停止/唤醒 → 取消当前 Turn → Generation +1
→ 停止旧处理 → 清理旧代次 → 丢弃迟到消息

4. 模块接口

4.1 接口总览

语音会话管理

Method	Path	说明
POST	/v1/voice/sessions	创建语音会话
GET	/v1/voice/sessions/{sessionId}	查询会话状态
DELETE	/v1/voice/sessions/{sessionId}	关闭会话
POST	/v1/voice/sessions/{sessionId}/turns	开始一轮语音输入
POST	/v1/voice/sessions/{sessionId}/turns/{turnId}/stop-input	结束本轮录音
POST	/v1/voice/sessions/{sessionId}/turns/{turnId}/cancel	取消本轮处理

业务工具接入

Method	Path	说明
POST	/v1/voice/tools	注册业务工具
GET	/v1/voice/tools	查询已注册工具
POST	/v1/voice/tool-calls/{toolCallId}/result	返回工具执行结果
POST	/v1/voice/tool-calls/{toolCallId}/cancel	请求取消工具调用

主动播报

Method	Path	说明
POST	/v1/voice/announcements	提交主动播报
GET	/v1/voice/announcements/{announcementId}	查询播报状态
POST	/v1/voice/announcements/{announcementId}/cancel	取消播报

事件订阅

Method	Path	说明
GET	/v1/voice/events	SSE 订阅语音事件

4.2 关键接口参数

创建语音会话

参数	类型	必填	说明
requestId	string	是	请求幂等 ID
deviceId	string	是	逻辑设备 ID
agentId	string	是	XRobot Provider 配置 ID
userId	string	否	当前用户 ID
trigger	string	是	button / wake_word / ui / system

提交主动播报

参数	类型	必填	说明
requestId	string	是	幂等 ID
sourceModule	string	是	请求来源，如 reminder
text	string	是	播放文本
interruptPolicy	string	是	wait_current_turn / interrupt_output / reject_if_busy
deviceId	string	是	目标设备 ID

5. 状态模型

Session 状态：opening → ready → closing → closed，任一步到 failed

Turn 状态：created → capturing → processing → speaking → completed，任一步到 cancelled / failed

Announcement 状态：queued → preparing → playing → completed，或 failed / expired / cancelled / rejected

---

三、MCP 模块

1. 行业调研

1. OpenClaw — 开源工具调用框架
2. ClaudeCode — Claude MCP 工具集成
3. 灵矽平台 — MCP 硬件接入协议

2. 核心概念定义

• 注册器（Registry）：所有工具统一注册，校验合法性，保证名称不重复
• 工具（Tool）：OpenAI 格式工具定义 + 业务逻辑 handler
• Tool Definition：约束各模块工具定义标准
• 业务 Tool：面向 Agent 暴露的稳定语义接口；负责在 ScheduleService 与 ScheduleRuleService 之间编排，不让 Agent 直接操作底层调度实体或 Repository

3. 核心业务流程

流程一：工具初始化

1. 各模块完成工具定义（name、description、inputSchema、handler）
2. 通过注册器注册，校验命名唯一性
3. 响应 tools/list 将工具列表发送给灵矽平台

流程二：工具回调

1. 灵矽平台发 tools/call 请求（含工具名和参数）
2. Registry 查找工具，校验参数
3. 调用 handler 执行业务逻辑；日程 Tool 在内部编排 Schedule 与 TimingTask Port
4. 返回标准 JSON-RPC 响应

流程三：日程 Tool 编排

1. schedule.create：无 repeat 时调用 ScheduleService::create_schedule；有 repeat 时调用 ScheduleRuleService::create_schedule_rule，返回 rule 并把首条已物化实例作为 schedule 返回
2. schedule.query：只读操作，不物化未来实例；查询已物化 schedule + 周期规则 + 例外，并用 recurrence planner 展开查询范围内的未来 occurrence，按条件过滤后汇总返回
3. schedule.update：按目标识别——已物化实例用 schedule_id，未来周期单次用 rule_id + original_start_time，整条周期规则用 rule_id + repeat
4. schedule.delete：传 schedule_id 取消实例、传 rule_id 取消整条规则、传 rule_id + original_start_time 跳过未来单次
5. 回调只做参数解析、按目标类型路由、结果组合与错误映射（failure / conflict），不直接使用 Repository

4. 核心数据模型

ToolDefinition
  ├── name           // String，工具名，全局唯一，建议命名空间格式
  ├── description    // String，工具功能描述，发送给模型
  ├── inputSchema    // Object，JSON Schema 入参定义
  ├── schemaVersion  // String，Schema 版本
  └── ownerModule    // String，归属模块（schedule / timer / binding）

5. 模块接口

5.1 接口总览

Registry 内部接口

方法	说明
register_tool(name, description, input, handler)	注册一个工具定义
get_tool(name)	查询已注册的工具
list_tools()	获取全部已注册工具

当前 XRobot JSON-RPC 接口：tools/list、tools/call。initialize、ping 或工具列表变更通知仅在灵矽接入协议明确要求时补充，不作为当前业务基线。

面向 Agent 的业务 Tool

Tool	说明	内部主要编排
schedule.create	创建一次性日程或周期日程规则	ScheduleService::create_schedule / ScheduleRuleService::create_schedule_rule
schedule.query	按自然语言友好的条件查询当前相关日程	ScheduleService::query_schedule + ScheduleRuleService::query_schedule_rules + recurrence planner
schedule.update	更新日程、更新周期规则、取消或跳过某次日程	ScheduleService::update_schedule / ScheduleRuleService::update_schedule_rule / update_schedule_occurrence / skip_schedule_occurrence
schedule.delete	删除单次日程或整条周期规则	ScheduleService::cancel_schedule / ScheduleRuleService::cancel_schedule_rule / skip_schedule_occurrence

5.2 关键接口参数

注册工具

参数	类型	必填	说明
name	String	是	命名空间格式，全局唯一
description	String	是	功能描述，发送给模型
input	Object	否	JSON Schema 入参定义
handler	Function	是	回调函数

tools/call 请求/响应示例

// 请求
{ "jsonrpc": "2.0", "id": "req-001", "method": "tools/call", "params": { "name": "schedule.create", "arguments": { "event": "明天下午三点开会" } } }
// 响应
{ "jsonrpc": "2.0", "id": "req-001", "result": { "content": [{ "type": "text", "text": "日程创建成功" }], "isError": false } }
// 未知工具
{ "jsonrpc": "2.0", "id": "req-001", "error": { "code": -32601, "message": "unknown tool" } }

6. 关键约定

• 注册时校验命名唯一性与 JSON Schema
• MVP 采用进程内直接调用 Application Port
• Handler 抛错必须转换为结构化 ToolResult，不能悬空请求
• Tool 返回结构化业务结果，不把底层 Port 或数据库对象直接暴露给 Agent
• 业务 Tool 统一返回 status（success / conflict / failure）+ message，冲突时附带 conflicts 列表
• 本轮范围不含操作撤销与提醒配置（reminder）工具

---

四、日程模块（Schedule）

1. 行业调研

1. oh-my-task — 开源任务/日程管理
2. Agentscope-example — 多 Agent 工具调用模式

2. 核心概念定义

• Schedule（日程实例）：rule_id 为空表示一次性日程；rule_id 指向某条 ScheduleRule 表示周期实例。
• ScheduleRule（周期规则）：描述 daily / weekly / monthly / yearly 的重复规则（freq_type、interval_val、start_date、start_time、end_date、occurrence_count 等），并管理例外。
• ScheduleException（单次例外）：记录周期规则中某一次被修改（modify）或跳过（skip），通过 rule_id + original_start_time 定位那一次。
• original_start_time（原始发生时间）：周期实例的统一定位键，调用方从 query_schedule_rules 的返回结果中透传，不自行计算。
• 定位方式：一次性日程用 schedule_id；周期中的某一次用 rule_id + original_start_time（无论已生成/未生成）。
• 状态枚举：Schedule.status 与 ScheduleRule.status 均为 active / cancelled / completed。

3. 核心业务流程

流程一：日程增删改查（MCP Tool 编排）

1. 创建：schedule.create 无 repeat 时创建一次性日程；有 repeat 时创建周期规则并立即物化首条实例。ignore_conflict=false 时先做时间冲突检测，有冲突则只返回 conflicts、不执行写操作。
2. 查询：schedule.query 是只读操作，不物化未来实例；查询已物化 schedule、周期规则与例外，并用 recurrence planner 展开查询范围内的未来 occurrence，按 keyword / status / start_date / end_date 过滤后汇总返回。
3. 修改：schedule.update 按目标区分——已物化实例用 schedule_id，未来周期单次用 rule_id + original_start_time，整条周期规则用 rule_id + repeat；更新整条规则 = 用新规则覆盖未来、历史不动（破坏性操作，调用前需二次确认）。
4. 删除：schedule.delete 传 schedule_id 取消单次、传 rule_id 取消整条规则、传 rule_id + original_start_time 跳过未来单次；取消为标记 cancelled，不物理删除。

流程二：周期实例的生成（惰性 next-occurrence）

1. 创建规则时立即物化首条实例（从 start_date 起、且 ≥ now() 的第一个匹配日）。
2. 后续实例由 generate_next_schedule_instance 按需生成下一条：从 now() 向后按规则计算候选 original_start_time，查询该原始时间的例外（skip 跳过、modify 应用 override），物化前防重。
3. 规则已取消 / 到达 end_date / occurrence_count 用尽时不再生成。

流程三：与定时任务模块的协作（到点触发）

1. 日程模块把周期规则展开为具体 trigger_at，分配永不复用的 task_id，调用 RegisterTask(task_id, trigger_at, callback) 注册一次性 task。
2. 到点时定时任务模块调用 callback on_task_due(task_id, trigger_at)；callback 内先按最新规则注册下一次 task（有下一次才注册），再投递本次 IM / 语音内容。
3. 日程变更（含 snooze、dismiss 等提醒运行态操作）表达为"取消旧 task_id + 注册新 task_id"；"日程与定时 task 同时存在或同时不存在"的约束由 SaveScheduleWithTimingTask（CalendarStorePort）交给存储 Adapter 保证。

4. 核心数据模型

erDiagram
  SCHEDULE_RULE ||--o{ SCHEDULE : "物化"
  SCHEDULE_RULE ||--o{ SCHEDULE_EXCEPTION : "记录偏离"
  SCHEDULE_EXCEPTION ||--o| SCHEDULE : "关联已物化实例"

  SCHEDULE {
    int id PK
    int rule_id FK
    string event
    datetime start_time
    datetime end_time
    string location
    string notes
    int status
    datetime created_at
    datetime updated_at
  }

  SCHEDULE_RULE {
    int id PK
    string event
    string freq_type
    int interval_val
    date start_date
    time start_time
    time end_time
    date end_date
    int occurrence_count
    int weekdays_mask
    int day_of_month
    int month_of_year
    string monthly_mode
    int status
  }

  SCHEDULE_EXCEPTION {
    int id PK
    int rule_id FK
    datetime original_start_time
    string type
    int schedule_id FK
    string override_event
    datetime override_start_time
    datetime override_end_time
    string override_location
    string override_notes
  }

Loading

5. 模块接口

5.1 接口总览

MCP 工具层暴露 4 个工具（schedule.create / schedule.query / schedule.update / schedule.delete），封装以下业务 API：

一次性日程（4）

接口	用途
create_schedule	创建一次性日程
query_schedules	查询具体实例
update_schedule	修改一次性日程
delete_schedule	取消一次性日程

周期规则（4）

接口	用途
create_schedule_rule	创建周期规则并生成首条实例
query_schedule_rules	查询周期规则（含例外与未来 occurrence）
update_schedule_rule	修改整条周期规则
cancel_schedule_rule	取消整条周期规则

周期中的某一次（3）

接口	用途
update_schedule_occurrence	修改周期中的某一次
skip_schedule_occurrence	跳过周期中的某一次
generate_next_schedule_instance	生成规则的下一条实例

5.2 关键接口参数

create_schedule（创建一次性日程）

入参：

参数	类型	必填	说明
event	string	是	事件标题
start_time	datetime	否	开始时间；为空表示无固定时间的备忘
end_time	datetime	否	结束时间；需 > start_time
location	string	否	事件地点
notes	string	否	事件备注
ignore_conflict	bool	否（默认 false）	是否忽略时间冲突

出参：message、schedule（含自增 id）、conflicts、error。ignore_conflict=false 时先做冲突检测，有冲突只返回 conflicts、不创建。

query_schedules（查询具体实例）

入参：schedule_id / rule_id / keyword / start_from / start_to / status（默认 active，可选 all）/ limit（默认 10，最大 50）/ offset。

出参：schedules（按 start_time 升序）、total、error。只查 Schedule 表，不动态展开未来实例；多个条件为 AND；不传时间条件时默认查询未来（start_time >= now()）。

create_schedule_rule（创建周期规则）

入参：

参数	类型	必填	说明
event	string	是	默认标题
freq_type	string	是	daily / weekly / monthly / yearly
start_time	time	是	每次默认发生时间
start_date	date	是	规则生效日期
end_time	time	否	每次默认结束时间
location / notes	string	否	默认地点 / 备注
interval_val	int	否（默认 1）	周期间隔（每 N 天/周/月/年）
weekdays_mask	int	否	weekly 用：1~127，bit0=周一
monthly_mode	string	否	monthly 用：specific_day / last_day
day_of_month	int	否	monthly/yearly 用：1~31
month_of_year	int	否	yearly 用：1~12
end_date	date	否	失效日期（与 occurrence_count 二选一）
occurrence_count	int	否	最大次数（与 end_date 二选一）
ignore_conflict	bool	否（默认 false）	是否忽略冲突

处理规则：校验 freq_type 及对应参数（weekly 需 weekdays_mask；monthly 需 monthly_mode；yearly 需 month_of_year + day_of_month）；校验 end_date 与 occurrence_count 二选一（都不给 = 无限重复）；创建规则（status=active）；立即物化首条实例（从 start_date 起、且 ≥ now() 的第一个匹配日）；ignore_conflict=false 时对首条实例做冲突检测。

query_schedule_rules（查询周期规则）

入参：rule_id / keyword / status（默认 active）/ limit / offset。

出参：rules（每条附带 exceptions 与 upcoming_occurrences）、total、error。只查 ScheduleRule 表，不展开无限实例；exceptions 由 ScheduleException.rule_id 关联查出；upcoming_occurrences 由规则字段计算未来几次原始发生时间。

update_schedule_rule（修改整条周期规则）

入参：rule_id（必填）+ 可更新的规则字段 + ignore_conflict。破坏性操作，调用前需二次确认。

处理规则：校验 freq_type 及对应参数、end_date / occurrence_count 二选一；更新规则字段（不提供的保持原值）；保留历史实例（start_time < now()）；删除尚未发生的已物化实例和 ScheduleException（其 original_start_time 基于旧规则）；按新规则生成下一条实例；ignore_conflict=false 时做冲突检测。

update_schedule_occurrence（修改周期中的某一次）

入参：rule_id（必填）、original_start_time（必填）+ 可覆盖字段 + ignore_conflict。

处理规则：定位 (rule_id, original_start_time)；已物化则更新 Schedule 并写 modify 例外（防止改规则重生成时被默认值覆盖）；未物化则写 modify 例外（override_* 存改动），不立即物化，等 generate_next 到达时应用；改时间且 ignore_conflict=false 时做冲突检测。

skip_schedule_occurrence（跳过周期中的某一次）

入参：rule_id（必填）、original_start_time（必填）。

处理规则：定位 (rule_id, original_start_time)；已生成对应 Schedule 则标记 cancelled；写 skip 例外，之后 generate_next 走到这一天时跳过。

generate_next_schedule_instance（生成下一条实例）

入参：rule_id（必填）。

处理规则：读规则（status 须为 active）；从 now() 向后按规则计算下一个候选原始发生时间；查该原始时间的例外（skip 跳过继续、modify 应用 override 后物化、无例外直接物化）；物化前防重；无下一条（规则已取消 / 到达 end_date / occurrence_count 用尽）返回空 + 说明。

6. 关键约定

• 本轮范围：不含操作撤销（undo），不含提醒（reminder）配置工具。
• 字段修改语义：省略字段 = 不修改；空字符串 / null = 清空该字段。
• 冲突检测：创建或修改时间时，若 ignore_conflict=false，检测与其他 active 实例的时间重叠；有冲突则返回冲突列表且不执行写操作。
• 定位方式：一次性日程用 schedule_id；周期中的某一次用 rule_id + original_start_time；整条周期规则用 rule_id。
• 时间格式：实例时间 YYYY-MM-DD HH:mm:ss，查询日期范围 YYYY-MM-DD，周期每日时间 HH:mm:ss。
• 与定时任务模块协作（以 local/timer-task-module.md 第 7 节、local/schedule-timer-task-relationship.md 为准）：
  • 日程模块负责周期展开为具体 trigger_at、分配 task_id（不透明、永不复用）、到点后的投递（callback 内实现）。
  • 注册 / 取消走 RegisterTask / CancelTask（异步、单向）；task_id 单次唯一，更新 = 取消旧 id + 注册新 id，中间态由日程模块补偿。
  • 惰性 next-occurrence：每条活动周期日程通常只注册一个 future task，task 到期后依据当时最新规则计算下一次再注册。
  • "日程与定时 task 同时存在或同时不存在"由 SaveScheduleWithTimingTask（CalendarStorePort）交存储 Adapter 保证。
• 可追踪：request_id → schedule_id → task_id → event_id → delivery_id。

---

五、定时任务模块（TimingTask）

0. 核心目标

定时任务模块接收日程模块注册的 task_id 与具体 trigger_at，在到点时调用该 task 对应的 callback，并支持取消已注册 task，以及多个 task 同时或相近时间到期的执行管理。

本模块只回答"何时触发"，与"触发后做什么"完全解耦：日程内容、重复周期、提醒配置以及调用 IM、语音等外部接口的职责全部归日程模块。本模块不理解日程内容、提醒等级、IM、语音、用户、周期规则或 callback 的业务含义。

1. 行业调研

参考以下成熟方案：

1. ESP 平台定时支持 https://docs.espressif.com/projects/esp-idf/en/v6.0.2/esp32s3/api-reference/system/esp_timer.html
2. FreeRTOS Task Notification / 事件组（ESP-IDF 集成）
3. 设备侧定时能力与第三方库评估 <../docs/architecture/third-party-timing-library-evaluation.md>

调研聚焦嵌入式定时与任务唤醒机制，不涉及日历展开、提醒语义或消息投递。

2. 核心概念定义

• task_id task 标识

  • 上游：日程模块分配的不透明标识，单次唯一、永不复用；本模块只按标识管理，不理解其含义。
  • 术语消歧：本文中的 task 指业务调度单位；Runner 运行在 FreeRTOS task（系统任务/线程）中，文档中"Runner task""FreeRTOS task"均指系统线程，与业务 task 无关。

• trigger_at 到点时刻

  • 本模块唯一关注的业务字段。由日程模块把周期规则（RRULE、时区、例外、提醒偏移）计算为具体时间点后传入；本模块不解释它的由来。

• callback 到期回调

  • 注册 task 时绑定的回调，到点由 Runner 调用。本模块不解析其参数的业务含义，也不决定返回值如何处置；投递、内容组装、后续 task 注册全部由 callback 内部实现。

• Runner 执行单元

  • 运行在普通 FreeRTOS task 中，负责处理到期 task：取当前时间、组装到期批次、逐个调用 callback、计算下一次唤醒时间。

• 到期批次（due batch）

  • 一次唤醒后，所有 trigger_at <= now 的 task 组成的集合，按 (trigger_at, task_id) 稳定排序。

• 唤醒时间（next wake at）

  • 当前注册表中最早的 pending trigger_at；Runner 用它设置下一次 esp_timer 一次性唤醒。

3. 核心业务流程

流程一：注册与变更

1. 日程模块创建或更新日程后，把周期规则展开为具体 trigger_at，调用 RegisterTask 提交 task_id 与 trigger_at（并绑定 callback）。
2. task_id 是单次触发实例的标识：任何 task_id 只允许注册一次，重复注册返回 duplicate。
3. 日程变更（含 snooze、dismiss 等提醒运行态操作）由日程模块重新计算 trigger_at 后，以"取消旧 task + 注册新 task（新 task_id）"表达更新；本模块不解释变更原因，也不理解"推迟""关闭"等语义。取消与注册之间的中间态由日程模块负责补偿。

流程二：到点推进（多个 task 同时触发）

1. esp_timer 到期，其 callback 默认运行在 ESP-IDF 的 esp_timer task（ESP_TIMER_TASK dispatch，非中断上下文），只做轻量唤醒/通知 Runner，立即返回；必须短小、非阻塞，不得调用日程模块、IM、语音或任何业务代码。仅当显式选用 ESP_TIMER_ISR dispatch 时才运行在中断上下文，限制更严格。
2. Runner 被唤醒后，先消费命令队列中的 RegisterTask / CancelTask 命令（见"流程三"），再取得当前 now。
3. 找出全部 trigger_at <= now 的 task，而不是只取一个，组成当前到期批次。
4. 按稳定顺序排序：先按 trigger_at 升序，再按 task_id 升序。
5. 每个 task 在执行 callback 前，从待执行集合中移除或标记为 executing，避免同一次或重复唤醒时重复回调。
6. 默认顺序回调，不要求并发执行；某个 callback 较慢时，后续已到期 task 保留在注册表中，当前 callback 返回后继续处理，不得丢失。
7. callback 执行期间可能注册或取消其他 task，变更生效规则见"流程三"。
8. 本批次处理完成后，重新查找最早的待执行 task，将 esp_timer 设置为该 trigger_at 的一次性唤醒；无待执行 task 则不设置定时器。

流程三：变更生效规则（并发与批次语义）

注册表写者唯一：task 注册表只由 Runner task 读写。

• 外部任务（MCP、IM 等可能调用 RegisterTask / CancelTask 的上下文）不能直接改注册表：公开接口将命令异步投递到 Runner 的命令队列（FreeRTOS Queue），立即返回 accepted，由 Runner 独占消费并应用。Runner 每轮在组装到期批次之前消费命令，故外部变更反映到本轮或下一轮的批次组装。最终应用结果通过命令结果回调或事件通知调用方。
• callback 内部（已在 Runner task 中）可以直接调用 RegisterTask / CancelTask，立即作用于注册表。
• 命令与到期 task 都在 Runner 内顺序处理；命令积压不会丢失，但外部取消或注册要等 Runner 消费命令后才生效。

当前到期批次在开始执行时确定。

• 批次确定后新注册的 task 不加入当前批次，按 trigger_at 参与下一次调度。
• 批次内尚未执行的 task，轮到它时校验注册表中是否仍存在：
  • task 已不存在（被取消；更新 = 取消旧 id + 注册新 id，故旧 id 同样表现为不存在）→ 跳过执行。
  • 仍存在 → 正常执行。
• 由于 task_id 永不复用，批次项与注册表不会出现"同 id 双代际"，无需版本号区分。
• 上述规则保证：callback 与外部命令引起的变更不破坏当前批次的执行，也不会丢失任何 task。

流程四：取消

CancelTask 将 task 标记为 cancelled 并从注册表移除；若该 task 已在当前批次中且尚未执行，执行前跳过；正在执行的 task 不受影响（其 callback 已开始）。

流程五：硬件定时与唤醒

1. 只使用一个一次性 esp_timer，不为每个 task 创建一个定时器。每次设置为当前注册表中最早的 pending trigger_at。
2. esp_timer callback 必须短小、非阻塞，只允许轻量操作（如 Task Notification / 事件组通知 Runner），禁止调用日程模块、IM、语音或其他业务代码；仅选用 ESP_TIMER_ISR dispatch 时才进入中断上下文。
3. Runner 是普通 FreeRTOS task，负责批次处理、callback 调用与下一次唤醒时间计算；回调中较重的业务逻辑（内容组装、网络、投递）在 Runner task 中执行。
4. trigger_at 是墙上时钟的绝对时间；本模块通过 Clock 取得当前墙上时间，计算 max(0, trigger_at - now) 的相对微秒延时后调用 esp_timer_start_once()。Clock 由 Runtime 注入，本模块负责时间换算和重新设置定时器。
5. 无待执行 task 时不设置定时器，设备可进入低功耗。

4. 核心数据模型

4.1 task

字段名	类型	约束	说明
task_id	string	主键，唯一，非空	task 标识；任何 task_id 都不可复用
trigger_at	datetime	非空	到点时刻，由日程模块计算
status	string	非空，枚举	pending / executing / completed / cancelled
created_at	datetime	非空	创建时间
updated_at	datetime	非空	最后更新时间

说明：

• callback 为运行时绑定（注册时注入），不持久化；task 表只存调度所需字段。
• 注册表要求支持：按 trigger_at 快速取最早 task（设置下一次唤醒）、取全部 trigger_at <= now 的 task（组装批次）、按 task_id 精确查找（取消、校验存在性）。MVP 规模下用按 trigger_at 排序的有序集合 + task_id 索引即可；实现可用堆或排序数组。
• 持久化策略：设备在良好条件下持续运行，暂不考虑断电、重启场景，注册表可驻留内存。若后续需要跨重启保留，由日程模块在启动时重新注册全部 task（本模块不负责恢复业务状态）。

4.2 到期批次（运行时，不持久化）

一次唤醒确定的到期 task 快照，按 (trigger_at, task_id) 排序；执行中的 task 从注册表待执行集合移除，防止重复唤醒时重复回调；执行前校验 task 是否仍存在（见"流程三"）。

5. 模块接口

5.1 接口总览

接口	调用方	说明
RegisterTask	日程模块	异步提交注册 task（task_id + trigger_at + callback）
CancelTask	日程模块	异步提交取消已注册 task
RunDueTasks	Runner（内部）	推进到期 task 与下一次唤醒调度；不是面向业务调用方的查询 API

5.2 关键接口参数

RegisterTask

请求参数：

参数名	类型	必填	约束	说明
task_id	string	是	非空，单次唯一	task 标识；任何 task_id 都不可复用
trigger_at	datetime	是	ISO 8601	到点时刻，由日程模块计算
callback	function	是	注册时绑定	到点回调；运行时绑定，不持久化

返回参数：

参数名	类型	约束	说明
result	string	accepted	命令已进入 Runner 队列；最终结果通过命令结果回调或事件通知

约束：trigger_at 必须是绝对时间点，本模块不接收周期表达式、偏移量或提醒等级。task_id 为单次触发实例标识，任何 task_id 都不可复用；更新必须使用新的 task_id，并先取消旧 task。最终注册结果由 Runner 通过命令结果回调或事件通知 registered / duplicate。

CancelTask

请求参数：

参数名	类型	必填	约束	说明
task_id	string	是	非空	待取消 task 标识

返回参数：

参数名	类型	约束	说明
result	string	accepted	命令已进入 Runner 队列；最终结果通过命令结果回调或事件通知

RunDueTasks（Runner 内部）

请求参数：

参数名	类型	必填	约束	说明
now	datetime	是	ISO 8601	本轮到期边界，Runner 唤醒时取得

返回参数：

参数名	类型	约束	说明
processed_count	integer	>= 0	本轮已调用 callback 的 task 数
skipped_count	integer	>= 0	本轮批次中被取消而跳过的 task 数
next_wake_at	datetime	可空	Runner 应设置的最近唤醒时间

5.3 依赖与 Port

本模块只依赖：

• esp_timer：一次性定时唤醒。
• FreeRTOS Task Notification / 事件组：esp_timer callback 唤醒 Runner。
• Clock：提供当前墙上时间；本模块将绝对 trigger_at 换算为 esp_timer 所需的相对微秒延时。

没有输出 Port。到点后的业务动作（内容组装、IM 投递、语音播报、注册下一个周期 task）全部由 callback 内部完成，本模块不定义也不感知这些动作。

6. 状态模型

task.status

• pending：已注册，等待触发。
• executing：已从待执行集合取出，正在调用 callback（防重复回调）。
• completed：callback 已返回，终态。
• cancelled：已取消，终态。
• 允许流转：pending -> executing / cancelled，executing -> completed。
• 批次中尚未执行即被取消的 task：pending -> cancelled，跳过 callback。

7. 与日程模块的边界（callback 契约）

职责	归属
日程内容、周期规则、提醒配置	日程模块
周期展开为具体 trigger_at	日程模块
分配 task_id（不透明，永不复用）	日程模块
到点后的投递（IM、语音）与内容组装	日程模块（callback 内实现）
注册、取消 task	本模块（由日程模块异步提交）
到期调用 callback、批量执行、下一次唤醒调度	本模块

callback 建议签名：on_task_due(task_id, trigger_at)。日程模块在 callback 内部决定：投递什么内容、是否注册下一个周期 task、是否需要更新或取消其他 task。callback 的执行时间直接影响同批次后续 task 的处理，但不会导致它们丢失（"流程二"第 6 条）。

本模块没有下游事件契约：到点后的业务动作全部由 callback 内部完成，本模块不向 IM、语音等模块发出事件。

8. 运行假设与限制

• 设备默认在良好条件下持续运行，暂不考虑断电、重启、断网等极端场景；本模块不提供跨重启恢复和投递重试。
• 本模块不保证回调之间并发，默认顺序执行；并发是日程模块 callback 内部的取舍，不在本模块范围。
• trigger_at 精度取决于 esp_timer 与系统时钟；到点即处理，不承诺毫秒级精确。
• 时间表示：本模块使用微秒精度墙上时间（TriggerAt），日程模块内部精确到秒（DateTime）；跨边界的换算与字符串解析由边界适配器负责。

---

六、IM 模块

1. 行业调研

调研微信公众号、企业微信、飞书、钉钉能力差异：

能力	微信公众号	企业微信(机器人)	飞书	钉钉
入站方式	HTTPS Webhook	WebSocket	Webhook/长连接	HTTP/Stream
主动提醒	依赖获批模板	支持主动推送	支持	支持
原生按钮回调	否，使用 H5	是	是	是
通用已读回执	无	不应假设	部分支持	不应假设

架构决策：

方案	结论
分别维护原生 Adapter	可行但复杂：重复维护 SDK、鉴权与协议
Koishi Adapter + Capability Plugin	采用：基础消息统一，专属模板/卡片能力按需补充
业务核心通过 Satori 接入	仅作可选外部出口

2. 核心概念定义

概念	说明
ImPlatform	wechat_official / wecom_aibot / feishu / dingtalk
ChannelAccount	可独立鉴权的平台应用配置，例如一个微信公众号；一个 ChannelAccount 可服务任意数量设备
ExternalIdentity	用户在某个 ChannelAccount 下的平台身份，由渠道账号与平台用户标识共同确定
ImDevice	IM Gateway 注册的物理设备身份，包含唯一 deviceId、唯一 Token 摘要、所有者 userId 和状态
ImBinding	设备与 ExternalIdentity 的绑定历史；同一设备及同一 ExternalIdentity 分别最多存在一个 active Binding
ConversationRef	平台内的直接会话或群会话目标
NotificationIntent	业务向 IM 提交的语义化通知
ActionIntent	acknowledge / snooze / bind_confirm / bind_cancel / open_url 等平台无关动作
Delivery	一次通知经一个绑定的投递记录
DeliveryAttempt	一次真实平台 API 调用（重试递增）
DeliveryReceipt	平台明确返回的 delivered / failed 证据；用户动作单独记入 Action
NormalizedImEvent	规范化入站事件
ChannelCapabilities	Adapter 原生能力与 Action UI 补充能力的合并结果
ReminderActionCommand	IM 向本地日程模块下发的短时效用户动作命令
ReminderActionResult	本地执行命令后回传的成功、失败或新触发时间
ActionStream	强提醒有效窗口内由本地主动建立的临时 SSE 下行通道

3. 核心业务流程

流程一：设备注册与身份绑定

1. 内部 CLI 为指定 userId 注册设备，生成唯一 deviceId 和独立 deviceToken。
2. Gateway 只保存 Token 摘要；明文 Token 仅在创建或轮换时输出一次。
3. 交付人员通过 USB 将 gatewayOrigin、deviceId、deviceToken 和 userId 写入设备加密 NVS。
4. 设备使用 Bearer Token 创建一次性 PairingSession；Gateway 从认证主体取得可信 deviceId 和 userId。
5. Adapter 将配对码或扫码事件转换为 binding.requested。
6. BindingHandler 在同一事务中验证 PairingSession、设备状态和所有者。
7. 相同 userId + deviceId + ExternalIdentity 的新配对保持幂等，复用原 active Binding。
8. 设备绑定新 ExternalIdentity 时，旧 active Binding 变为 unbound。
9. ExternalIdentity 绑定新设备时，旧设备的 active Binding 变为 unbound。

流程二：业务提醒投递

1. 消费 NotificationIntent，创建平台无关通知
2. 根据 NotificationIntent 中的 deviceId 查找该设备唯一的 active ImBinding，
   再解析 ChannelAccount、ExternalIdentity 与 ConversationRef。
3. 根据 ChannelCapabilities 选择原生卡片或模板/文本 + Action UI。
4. 为当前 active Binding 创建一个 Delivery；不得按同一 userId 的其他设备绑定广播。
5. 平台返回回执，临时失败重试，永久失败入死信

流程三：平台消息与提醒动作分流

1. Adapter 接收平台消息；只有绑定相关输入进入 BindingHandler
2. H5/小程序经 plugin-server 进入 VoiceLife Koishi Plugin 的 Action Route，不经过平台 Adapter，也不构造 Koishi Session
3. 原生卡片由 Adapter/Capability Plugin 转为 interaction/button
4. 两条动作入口统一为 {token, action, params?}，交给 ReminderActionHandler
5. Handler 验签、校验版本与幂等后调用 IM Application.Action，将 Action 作为有过期时间的待执行命令保存
6. 本地在强提醒触发后主动建立临时 SSE；IM 通过该连接下发 ReminderActionCommand
7. 本地日程模块执行 dismiss / snooze，再通过 HTTPS 回传 ReminderActionResult
8. 收到结果或达到 actionExpiresAt 后关闭 SSE；snooze 后到下一次强提醒触发时重新建立
9. 微信公众号文字仅用于绑定，不解析“知道了/推迟”

流程四：平台回执更新

1. 平台发送结果转为 delivery.updated 事件
2. 通过 externalMessageId 找到对应 Delivery
3. 幂等写入 delivered / failed Receipt，不允许状态倒退；用户动作写入独立 Action

4. 总体架构

平台 IM → Koishi Adapter → Binding Handler → IM Application.Binding → Binding Service Port

H5/小程序 → plugin-server → VoiceLife Koishi Plugin / Action Route ─┐
未来原生卡片 → Adapter / Capability Plugin → interaction/button ——───┤
                                                                   └→ ReminderActionHandler
                                                                       → IM Application.Action
                                                                       → Reminder Command Port

NotificationIntent → IM Application.Delivery → Renderer / ImChannelPort
  → Koishi Runtime（WeChat / WeCom / Lark / DingTalk Adapter + Capability Plugin）

本地日程模块（callback 内）── HTTPS NotificationIntent ──→ IM Application
本地日程模块 ←─ 临时 SSE ReminderActionCommand ─ IM Application.Action
本地日程模块 ── HTTPS ReminderActionResult ─→ IM Application.Action

BindingHandler 与 ReminderActionHandler 是共享应用入口，不是平台 Adapter。当前 Demo 可单进程组合部署，但 Handler 不得直接依赖具体业务 Service；生产拆分时只替换 Port 的 IPC/RPC 实现。H5/小程序是同一微信公众号渠道的 Action UI，不是第二个 Adapter。

临时 SSE 只承担 IM → 本地 的命令下行，不传输执行结果。它由本地主动建立，适应设备位于 NAT 后的部署；没有活动强提醒时不保持连接。

5. 核心数据模型

ChannelAccount（通道账号配置）
  ├── id              // uuid, PK
  ├── platform        // wechat_official / wecom / feishu / dingtalk
  ├── credential_ref  // 凭据引用（不存明文 Secret）
  └── status          // active / disabled / error

ExternalIdentity（平台用户身份）
  ├── id                         // uuid, PK
  ├── channel_account_id         // FK
  ├── external_user_id_ciphertext // 加密保存
  ├── external_user_id_hash      // 查询和去重
  └── status                     // active / unreachable / revoked

ImBinding（内部用户与平台身份的绑定）
  ├── id                  // uuid, PK
  ├── user_id             // 内部用户ID
  ├── device_id           // 设备ID, Nullable
  ├── external_identity_id // FK
  ├── priority            // 绑定优先级
  └── status              // active / unbound / revoked

PairingSession（一次性配对会话）
  ├── id / display_code
  ├── user_id / device_id
  ├── expires_at
  └── status              // pending / confirmed / expired / cancelled

Delivery（一次业务投递记录）
  ├── id                  // uuid, PK
  ├── business_event_id   // 业务事件ID
  ├── correlation_id      // 关联ID
  ├── binding_id          // FK
  ├── status              // pending → sending → accepted → delivered / failed
  ├── external_message_id // 平台消息ID
  └── last_error_code

DeliveryAttempt（每次 API 调用）
  ├── id            // uuid, PK
  ├── delivery_id   // FK
  ├── attempt_no    // 从1递增
  ├── request_id    // Unique
  └── status        // sending / accepted / retryable_failed / permanent_failed

NormalizedImEvent（规范化入站事件）
  ├── type           // message.received / action.triggered / delivery.updated / binding.requested
  ├── platform       // wechat_official
  ├── channel_account_id
  ├── external_event_id // 平台事件ID，用于去重
  └── payload        // 平台无关结构化数据

DeliveryReceipt（平台投递证据）
  ├── delivery_id / attempt_id
  ├── stage          // delivered / failed
  └── dedupe_key     // Unique

Action（用户动作）
  ├── delivery_id / action_type
  ├── device_id / task_id
  ├── operation_id   // Unique
  ├── expected_identity_id / actual_identity_id
  └── status / dispatched_at / result / expires_at

6. 模块接口

6.1 接口总览

按部署边界分三类：设备侧（本地设备程序，NAT 后）与 Action UI（H5/小程序浏览器）的调用方在服务端进程之外，接口按已确定的 HTTP/SSE 契约交互；服务端应用接口（Koishi Plugin、Handler、Application、运维/bootstrap）在 Demo 单进程组合部署下直接调用应用方法或 Port、不经 HTTP。若未来跨出部署单元，再根据调用方与运行环境选择 HTTPS、RPC 或消息通道等 Port 适配器，不默认一律映射为 HTTP。

设备侧接口（跨进程，固定 HTTP/SSE）

Method	Path	说明
POST	/v1/im/pairing-sessions	创建配对会话
GET	/v1/im/pairing-sessions/{pairingSessionId}	查询配对状态
POST	/v1/im/schedule-receipts	提交日程操作回执（ScheduleReceiptIntent；URL 为项目补充约定）
POST	/v1/im/notifications	提交通知意图
GET	/v1/devices/{deviceId}/reminder-actions/stream	在强提醒有效窗口内建立临时 SSE
POST	/v1/devices/{deviceId}/reminder-actions/{commandId}/result	回传本地动作执行结果

Action UI（H5/小程序跨进程，HTTP）

Method	Path	说明
GET	/voicelife/reminder-actions/{token}	展示 H5/小程序动作页
POST	/voicelife/reminder-actions/{token}	执行统一提醒动作

服务端应用接口（Demo 单进程内直接调用）

应用方法	说明
channels.register(command)	创建通道账号
channels.health(accountId)	查询 Koishi Bot/Adapter 健康状态
bindings.list(userId)	查询绑定
bindings.unbind(bindingId)	解绑
deliveries.find(deliveryId)	查询投递与回执
deliveries.retryDeadLetter(deliveryId)	人工重试死信
postEvent(event)	接收 NormalizedImEvent

跨模块事件

方向	接口	说明
本地→IM（HTTPS）	ScheduleReceiptIntent	提交操作回执
本地→IM（HTTPS）	NotificationIntent	提交通知意图并获得动作有效期
IM→本地（临时 SSE）	ReminderActionCommand	在强提醒窗口内下发用户动作
本地→IM（HTTPS）	ReminderActionResult	回传命令执行结果

6.2 关键接口参数

ScheduleReceiptIntent 和 NotificationIntent 共用以下 HTTPS 传输约定：

• 请求体使用 application/json，字段使用 camelCase，时间使用带时区的 ISO 8601 字符串
• Authorization: Bearer <device-token> 必须存在。
• Gateway 对 Token 计算 SHA-256 摘要，并查询 active 设备记录。
• 认证结果产生可信 {deviceId, userId} 主体。
• 路径和请求体中的 deviceId/userId 必须与认证主体一致。
• 未知、格式错误、已轮换旧 Token 和 revoked 设备统一返回 401。
• Token 与路径或正文身份不一致时返回 403。
• Idempotency-Key 必须存在；日程回执取 eventId，通知意图取 businessEventId
• 首次受理或幂等重放均返回 202 Accepted；相同幂等键与不同请求体冲突时返回 409 Conflict
• 缺少必填字段或格式错误返回 400 Bad Request

以上共用约定仅适用于 ScheduleReceiptIntent（#### 3）和 NotificationIntent（#### 4）。配对接口（#### 1-2）、SSE 动作通道（#### 5）和 ReminderActionResult（#### 6）分别按各自条目定义认证、续传与幂等规则。Action UI（#### 7-8）使用 H5 Token。服务端应用接口（#### 9-15）在 Demo 单进程下由同进程组件直接调用、不经 HTTP。

1) 创建配对会话

• 方法与路径: POST /v1/im/pairing-sessions
• 说明: 创建配对会话，返回展示码 displayCode，供用户在 IM 侧发起绑定。
• 认证: Authorization: Bearer <device-token>，Token 绑定 deviceId 与入参 deviceId 一致。
• 入参 (Body): CreatePairingSessionCommand
• userId（兼容字段，可选）：如果提供，必须与认证主体的 userId 一致；生产 Device API 始终使用认证主体的 userId 保存 PairingSession。
• deviceId (string, 必填): 目标设备 ID
• allowedPlatforms (array, 可选): 允许绑定的平台枚举
• expiresInMinutes (number, 可选): 过期分钟数，默认 10
• 出参 (Body): { session, displayCode }
  • session (object): PairingSession，含 id、deviceId、status（pending）、expiresAt、createdAt；displayCodeHash、userId?、allowedPlatforms? 依入参
  • displayCode (string): 展示码明文，仅本次返回

2) 查询配对状态

• 方法与路径: GET /v1/im/pairing-sessions/{pairingSessionId}
• 说明: 查询配对会话状态（pending | confirmed | expired | cancelled）。
• 认证: Authorization: Bearer <device-token>，仅可查询归属本设备的配对会话。
• 入参 (Path):
  • pairingSessionId (string, 必填)
• 出参 (Body): PairingSession（不存在时返回 404）

3) 提交日程操作回执

• 方法与路径: POST /v1/im/schedule-receipts
• 说明: 本地 Schedule 事务提交成功后提交日程操作回执。Issue 产出模块数据模型和接口-20260723 #65 仅确定“本地→IM HTTPS”，未指定 URL；本架构补充映射为 POST /v1/im/schedule-receipts，不改变 Issue 中的事件语义。
• 入参 (Body): 完整 ScheduleReceiptIntent
  • schemaVersion (string, 必填): 契约版本，当前为 "1"
  • eventId (string, 必填): 日程操作事件唯一标识，同时作为幂等键
  • correlationId (string, 必填): 关联追踪 ID
  • userId (string, 可选): 内部用户 ID；未携带时，IM 根据已认证的 deviceId 查找有效绑定
  • deviceId (string, 必填): 本地设备 ID
  • operationType (string, 必填): created | updated | cancelled
  • scheduleId (string, 必填): 日程 ID
  • result (string, 必填): succeeded | failed
  • summary (string, 必填): 操作结果摘要
  • occurredAt (string, 必填): 事件发生时间（ISO 8601）
• 出参 (Body): NotificationSubmission
  • businessEventId (string): 等于入参 eventId
  • status (string): accepted
  • deliveries (array, 必填): 每项 { deliveryId, bindingId, status: "pending" }

4) 提交通知意图

• 方法与路径: POST /v1/im/notifications
• 说明: 业务向 IM 提交语义化通知并获得动作有效期。端点在 Issue 产出模块数据模型和接口-20260723 #65 中已定义，此处仅补充完整入参/出参，不重复定义接口。
• 入参 (Body): 完整 NotificationIntent
  • schemaVersion (string, 必填): 契约版本，当前为 "1"
  • businessEventId (string, 必填): 提醒发生事件唯一标识，同时作为幂等键
  • correlationId (string, 必填): 关联追踪 ID
  • kind (string, 必填): reminder_due
  • recipient (object, 必填): { userId, deviceId }；设备侧通知无论 weak/strong 均必须携带 deviceId，并与设备 Token 绑定的设备一致
  • scheduleId (string, 必填): 来源日程 ID
  • taskId (string, 必填): 定时任务 ID，关联 SSE 与 Result
  • reminderType (string, 必填): weak | strong
  • content (object, 必填): { title, body? }
  • actions (array, 必填): { kind: "command", type: acknowledge|snooze, label, params? }；strong 非空，weak 为空数组
  • plannedAt (string, 必填): 计划提醒时间（ISO 8601）
  • triggerAt (string, 必填): 实际触发时间（ISO 8601）
  • occurredAt (string, 必填): 事件发生时间（ISO 8601）
• 出参 (Body): NotificationSubmission
  • businessEventId (string)
  • status (string): accepted
  • deliveries (array, 必填): 每项 { deliveryId, bindingId, status: "pending" }
  • actionStream (object, 仅 strong 返回): { taskId, expiresAt }
  • 弱提醒不支持用户动作，因此不返回 actionStream。

5) 临时 SSE 动作通道

• 方法与路径: GET /v1/devices/{deviceId}/reminder-actions/stream?taskId={taskId}
• 说明: 在强提醒有效窗口内下发 ReminderActionCommand；弱提醒不得建立动作流。本地仅在强提醒触发（日程模块在 callback 内投递）后建立连接。
• 入参 (Query/Headers):
  • query: taskId (string, 必填): 定时任务 ID
  • Accept: text/event-stream
  • Authorization: Bearer <device-token> (必填)
  • Last-Event-ID (可选): 断线续传游标；只是传输续接提示，不能代替业务 ACK
• 出参 (Body): SSE 事件流；响应头至少 Content-Type: text/event-stream、Cache-Control: no-cache、X-Accel-Buffering: no。命令事件：

id: action-1001
event: reminder.action
data: {"commandId":"action-1001","operationId":"op-1001","taskId":"task-9001","action":"snooze","params":{"minutes":10},"expiresAt":"2026-07-31T15:10:00+08:00"}

commandId 复用 Action ID，SSE id 与之相同。连接中断后，本地在有效期内携带 Last-Event-ID 重连；在收到 ReminderActionResult 前，服务端可以重放同一未过期命令，本地必须用 operationId 幂等执行。SSE 是单向下行协议，禁止用它承载 ReminderActionResult。

6) 回传动作执行结果

• 方法与路径: POST /v1/devices/{deviceId}/reminder-actions/{commandId}/result
• 说明: 本地执行后回传 ReminderActionResult，服务端据此推进 Action 状态并关闭动作流。deviceId、commandId 来自路径，Body 不再重复。
• 认证: Authorization: Bearer <device-token>，Token 绑定 deviceId 与路径 deviceId 一致。
• 入参 (Path/Body):
  • path: deviceId (string)、commandId (string, 即 Action ID)
  • Body 完整 ReminderActionResult:
    • schemaVersion (string, 必填): 契约版本，当前为 "1"
    • operationId (string, 必填): 关联命令的幂等 ID
    • status (string, 必填): succeeded | retryable_failed | failed | expired
    • taskId (string, 必填)
    • nextTriggerAt (string, 可选): snooze 成功时返回下次触发时间
    • errorCode (string, 可选)
    • details (object, 可选)
    • occurredAt (string, 必填): 执行完成时间（ISO 8601）
• 出参 (Body): 更新后的 Action 对象，含 status 与 result。

7) 展示 H5 动作页

• 方法与路径: GET /voicelife/reminder-actions/{token}
• 说明: 展示 H5/小程序动作页，返回可用动作与有效期。
• 入参 (Path):
  • token (string, 必填): H5 Token
• 出参 (Body): ActionUiView
  • actionId (string)
  • actions (array): 可用动作 acknowledge | snooze
  • expiresAt (string): ISO 8601

8) 执行统一提醒动作

• 方法与路径: POST /voicelife/reminder-actions/{token}
• 说明: 从 H5 执行一个提醒动作，服务端验签后返回待下发的命令。
• 入参 (Path/Body):
  • path: token (string, 必填): H5 Token
  • Body:
    • action (string, 必填): acknowledge | snooze
    • params (object, 可选): { minutes }；snooze 必填
• 出参 (Body): ReminderActionCommand

9) 创建通道账号

• 接口形式: 应用方法 channels.register(command)，Demo 单进程内由运维/bootstrap 直接调用（非 HTTP）。
• 说明: 注册一个 IM 通道账号（Koishi Bot/Adapter 的通道配置），供后续投递、配对与健康检查使用。
• 入参 (参数): RegisterChannelAccountCommand
  • platform (string, 必填): wechat_official | wecom_aibot | feishu | dingtalk
  • tenantExternalId (string, 必填): 租户外部 ID
  • koishiBotId (string, 必填): Koishi Bot 标识
  • credentialRef (string, 必填): 凭据引用，不存明文 Secret
  • connectionMode (string, 必填): webhook | websocket | both
  • capabilityConfig (object, 可选): 通道能力配置
• 出参: ChannelAccount
  • id (string): 通道账号 ID
  • platform / tenantExternalId / koishiBotId / credentialRef / connectionMode: 同入参
  • capabilityConfig (object, 可选)
  • status (string): active | disabled | error
  • createdAt / updatedAt (string): ISO 8601

10) 查询通道健康状态

• 接口形式: 应用方法 channels.health(accountId)，Demo 单进程内直接调用（非 HTTP）。
• 说明: 查询 Koishi Bot/Adapter 的实时健康状态。
• 入参 (参数):
  • accountId (string, 必填): 通道账号 ID
• 出参: ChannelHealth
  • accountId (string)
  • status (string): healthy | degraded | unavailable
  • checkedAt (string): ISO 8601
  • detail (string, 可选)

11) 查询绑定

• 接口形式: 应用方法 bindings.list(userId)，Demo 单进程内直接调用（非 HTTP）。
• 说明: 查询某用户的有效绑定列表。
• 入参 (参数):
  • userId (string, 必填): 内部用户 ID
• 出参: ImBinding[]
  • 每项含 id、userId、deviceId?、externalIdentityId、priority、status（active | unbound | revoked）、boundAt、unboundAt?、revokedAt?

12) 解绑

• 接口形式: 应用方法 bindings.unbind(bindingId)，Demo 单进程内直接调用（非 HTTP）。
• 说明: 解绑指定绑定（status → unbound）。
• 入参 (参数):
  • bindingId (string, 必填)
• 出参: 无

13) 查询投递与回执

• 接口形式: 应用方法 deliveries.find(deliveryId)，Demo 单进程内直接调用（非 HTTP）。
• 说明: 查询一次投递的详情、attempts 与 receipts。
• 入参 (参数):
  • deliveryId (string, 必填)
• 出参: DeliveryDetails
  • delivery (object): Delivery，含 id、businessEventId、correlationId、bindingId、channelAccountId、kind（reminder_due | schedule_receipt）、semanticPayload、presentationType、status、externalMessageId?、expiresAt?、lastErrorCode?、createdAt、updatedAt
  • attempts (array): DeliveryAttempt[]，含 id、deliveryId、attemptNo、requestId、renderedPayload、status、platformMessageId?、errorCode?、startedAt、completedAt?
  • receipts (array): DeliveryReceipt[]，含 id、deliveryId、attemptId?、stage（delivered | failed）、dedupeKey、externalEventId?、detail?、occurredAt、receivedAt

14) 人工重试死信

• 接口形式: 应用方法 deliveries.retryDeadLetter(deliveryId)，Demo 单进程内直接调用（非 HTTP）。
• 说明: 对 dead_letter / permanent_failed 投递手动重试，恢复为 pending。
• 入参 (参数):
  • deliveryId (string, 必填)
• 出参: Delivery（status 为 pending）

15) 内部标准事件入口

• 接口形式: 应用服务方法 postEvent(event: NormalizedImEvent)，Demo 单进程组合部署时由 VoiceLife Koishi Plugin 直接调用（非 HTTP）。
• 说明: 接收平台/适配器标准化后的入站事件 NormalizedImEvent，按 type 分发处理；重复事件幂等返回。
• 入参 (参数): NormalizedImEvent（按 type 判别联合）
  • 公共字段：id、externalEventId、platform、channelAccountId、externalIdentityId?、occurredAt
  • type: "message.received" — payload (object): 平台消息体
  • type: "binding.requested" — payload: { displayCode, externalUserId, userId?, displayName? }
  • type: "delivery.updated" — payload: NormalizedDeliveryReceipt，含 externalEventId、channelAccountId、externalMessageId、attemptId?、dedupeKey、stage（delivered | failed）、occurredAt、platformCode?、detail?
  • type: "action.triggered" — payload: { token, action, params? }
• 出参: void；action.triggered 时返回 ReminderActionCommand

7. 能力降级策略

原生互动卡片 → 模板/富文本 + H5 → 纯文本 + H5

8. 投递状态机

Delivery：pending → sending → accepted → delivered
                    ↘ retryable_failed → pending
                    ↘ permanent_failed / dead_letter

Receipt：delivered / failed
Action：pending → dispatched → processing → succeeded / failed
          └──────────────────────────────→ expired

ActionStream：closed → connected → closed

ActionStream 不是长期会话：默认窗口建议 10 分钟、最大 30 分钟，以 actionExpiresAt 为准。dismiss、snooze、动作成功或到期均立即关闭；snooze 后在下一次强提醒触发时重新建立。

9. 幂等策略

场景	幂等键
消费业务事件	business_event_id
平台入站事件	channel_account_id + external_event_id
平台投递回执	dedupe_key
用户业务动作	operation_id
SSE 命令与结果关联	command_id（复用 Action ID）
SSE 断线续传	Last-Event-ID
发送 API 请求	delivery_id + attempt_no

10. 关键约定

• 本地业务事务不依赖 IM 是否成功
• IM 用户动作不直写本地库
• HTTP JSON 使用 camelCase，数据库字段使用 snake_case；时间使用 ISO 8601，数据库保存 UTC
• 平台受理记录在 DeliveryAttempt，delivered / failed 记录在 DeliveryReceipt，用户动作记录在 Action，三者不可合并
• 凭据加密保存，不存明文 Secret
• H5 Token 需签名，含 action_id、delivery_id、expires_at，不放身份明文
• 一个 IM 平台只保留一个 Koishi Adapter；Action UI 不计为 Adapter
• 业务层只能依据 ChannelCapabilities 选能力，不得按平台名称分支
• 临时 SSE 仅为强提醒下发 ReminderActionCommand；弱提醒不得建立动作流
• SSE 每 15～30 秒发送注释型 heartbeat，代理层必须关闭响应缓冲
• 设备 Token 必须绑定 deviceId，命令还需校验 taskId、身份和 expiresAt
• 未确认命令仅在 IM 服务端 Action 记录中保存到过期，不新增 Local Outbox
• 一个内部用户可以拥有多台设备，每台设备使用唯一 deviceId 和独立 Token。
• 一个 ChannelAccount 可以服务任意数量设备。
• 一个设备最多绑定一个 active ExternalIdentity。
• 一个 ExternalIdentity 最多绑定一台 active 设备。
• Gateway 数据库只保存设备 Token 摘要；明文 Token 只保存在设备加密 NVS，并仅在创建或轮换时向操作者显示一次。
• 用户拿到设备前必须完成设备注册和 USB provisioning；用户只执行 Wi-Fi 配网和外部 IM 身份绑定。
• Wi-Fi 配网和切换网络不得删除或覆盖 IM 设备凭据。
• revoked 设备不能发起新的 HTTP 请求、SSE 或绑定确认，但历史 Binding、Delivery 和 Receipt 保留。

---

七、跨模块接口契约

边界	接口方式	说明
Voice ↔ XRobot	WebSocket	上行音频、下行 TTS、MCP 控制消息
XRobot ↔ MCP Server	JSON-RPC	当前基线：tools/list / tools/call
MCP Server ↔ Schedule	MCP Tool + Application Port	schedule.create / schedule.query / schedule.update / schedule.delete（封装 ScheduleService 与 ScheduleRuleService 业务 API）
Schedule ↔ TimingTask	异步 Port（单向）	RegisterTask(task_id, trigger_at, callback) / CancelTask(task_id)；立即返回 accepted，由 Runner 消费
MCP/IM ↔ 日程模块（提醒运行态）	同步 Port / Command	提醒运行态操作（snooze / dismiss）由日程模块处理，经"取消旧 task + 注册新 task"表达；不再暴露定时任务模块接口
本地 → IM Gateway	HTTPS	ScheduleReceiptIntent / NotificationIntent / ReminderActionResult
IM Gateway → 本地	临时 SSE	强提醒有效窗口内下发 ReminderActionCommand；dismiss / snooze / 到期后关闭
IM Application ↔ Koishi	Handler + ImChannelPort	出站：发送意图；入站：BindingHandler / ReminderActionHandler / NormalizedImEvent

---

八、数据库表结构设计

时间统一保存 UTC，API 层按 ISO 8601 输出。

1. 本地核心表

1.1 schedules

字段	类型	约束	说明
id	integer	PK, AutoIncrement	自增主键
rule_id	integer	FK, Nullable	所属周期规则 ID；一次性日程为 NULL
event	varchar(100)	Not Null	事件标题
start_time	datetime	Nullable	开始时间
end_time	datetime	Nullable	结束时间
location	varchar(100)	Nullable	地点
notes	varchar(200)	Nullable	备注
status	varchar(16)	Not Null, Default 'active'	active / cancelled / completed
created_at	datetime	Not Null	创建时间
updated_at	datetime	Not Null	更新时间

1.2 schedule_rules

字段	类型	约束	说明
id	integer	PK, AutoIncrement	周期规则 ID
event	varchar(100)	Not Null	默认标题
freq_type	varchar(16)	Not Null	daily / weekly / monthly / yearly
interval_val	integer	Not Null, Default 1	周期间隔（每 N 天/周/月/年）
start_date	date	Not Null	规则生效日期
start_time	time	Not Null	每次默认发生时间
end_time	time	Nullable	每次默认结束时间
end_date	date	Nullable	失效日期（与 occurrence_count 二选一）
occurrence_count	integer	Nullable	最大次数（与 end_date 二选一）
weekdays_mask	integer	Nullable	weekly 用：1~127，bit0=周一
monthly_mode	varchar(16)	Nullable	monthly 用：specific_day / last_day
day_of_month	integer	Nullable	monthly/yearly 用：1~31
month_of_year	integer	Nullable	yearly 用：1~12
status	varchar(16)	Not Null, Default 'active'	active / cancelled / completed
created_at	datetime	Not Null	创建时间
updated_at	datetime	Not Null	更新时间

约束：end_date 与 occurrence_count 二选一（都不给 = 无限重复）；weekly 需 weekdays_mask；monthly 需 monthly_mode；yearly 需 month_of_year + day_of_month。

1.3 schedule_exceptions

字段	类型	约束	说明
id	integer	PK, AutoIncrement	例外 ID
rule_id	integer	FK, Not Null	所属周期规则 ID
original_start_time	datetime	Not Null	原始发生时间，定位周期中的那一次
type	varchar(16)	Not Null	modify / skip
schedule_id	integer	FK, Nullable	例外已关联的日程 ID；未关联时为 NULL
override_start_time	datetime	Nullable	覆盖后的开始时间
override_end_time	datetime	Nullable	覆盖后的结束时间
override_event	varchar(100)	Nullable	覆盖后的事件标题
override_location	varchar(100)	Nullable	覆盖后的地点
override_notes	varchar(200)	Nullable	覆盖后的备注
created_at	datetime	Not Null	创建时间
updated_at	datetime	Not Null	更新时间

复合唯一：(rule_id, original_start_time, type)。

1.4 timer_tasks（task 注册表）

字段	类型	约束	说明
task_id	varchar(64)	PK	task 标识；任何 task_id 都不可复用
trigger_at	datetime	Not Null	到点时刻，由日程模块计算
status	varchar(16)	Not Null	pending / executing / completed / cancelled
created_at	datetime	Not Null	创建时间
updated_at	datetime	Not Null	最后更新时间

说明：callback 为运行时绑定（注册时注入），不持久化。MVP 阶段注册表可驻留内存，本表仅在需要持久化时使用；若后续需要跨重启保留，由日程模块在启动时重新注册全部 task（定时任务模块不负责恢复业务状态）。

2. IM 服务端核心表

2.1 im_channel_accounts

字段	类型	约束	说明
id	uuid	PK	主键
platform	varchar(32)	Not Null	平台类型
tenant_external_id	varchar(128)	Not Null	公众号 AppID 等非密钥标识
koishi_bot_id	varchar(128)	Not Null	Koishi Runtime 内 Bot 标识
credential_ref	varchar(256)	Not Null	凭据引用
connection_mode	varchar(16)	Not Null	webhook / websocket / both
capability_config	jsonb	Nullable	模板、卡片等非敏感配置
status	varchar(16)	Not Null	active / disabled / error
created_at	timestamptz	Not Null	创建时间

2.2 im_pairing_sessions

字段	类型	约束	说明
id	uuid	PK	配对会话 ID
display_code_hash	varchar(128)	Unique, Not Null	一次性配对码哈希
user_id	varchar(128)	Nullable	内部用户 ID
device_id	varchar(128)	Not Null	设备 ID
allowed_platforms	jsonb	Nullable	允许绑定的平台
status	varchar(16)	Not Null	pending / confirmed / expired / cancelled
expires_at	timestamptz	Not Null	过期时间

2.3 im_external_identities

字段	类型	约束	说明
id	uuid	PK	主键
channel_account_id	uuid	FK, Not Null	关联通道
external_user_id_ciphertext	text	Not Null	加密保存
external_user_id_hash	varchar(128)	Not Null	查询和去重
status	varchar(16)		active / unreachable / revoked

复合唯一：(channel_account_id, external_user_id_hash)。

2.4 im_bindings

字段	类型	约束	说明
id	uuid	PK	主键
user_id	varchar(128)	Not Null	内部用户ID
device_id	varchar(128)	Nullable	设备ID
external_identity_id	uuid	FK, Not Null	外部身份
priority	integer	Default 100	绑定优先级
status	varchar(16)		active / unbound / revoked
bound_at	timestamptz	Not Null	绑定时间

索引：(user_id, status, priority)。

2.5 im_deliveries

字段	类型	约束	说明
id	uuid	PK	主键
business_event_id	varchar(128)	Not Null	业务事件ID
correlation_id	varchar(128)	Not Null	关联ID
binding_id	uuid	FK, Not Null	关联绑定
channel_account_id	uuid	FK, Not Null	发送通道快照
kind	varchar(64)		reminder_due 等
semantic_payload	jsonb	Not Null	平台无关通知快照
presentation_type	varchar(32)	Not Null	卡片 / 模板 / Action UI / 文本
status	varchar(32)		pending / sending / accepted / delivered / failed
external_message_id	varchar(256)	Nullable	平台消息ID
expires_at	timestamptz	Nullable	过期时间

复合唯一：(business_event_id, binding_id, kind)。

2.6 im_delivery_attempts

字段	类型	约束	说明
id	uuid	PK	主键
delivery_id	uuid	FK, Not Null	关联投递
attempt_no	integer	Not Null	从1递增
request_id	varchar(128)	Unique	请求标识
rendered_payload	jsonb	Not Null	脱敏后的平台载荷
status	varchar(24)		sending / accepted / retryable_failed / permanent_failed
started_at	timestamptz	Not Null	开始时间

复合唯一：(delivery_id, attempt_no)。

2.7 im_delivery_receipts

字段	类型	约束	说明
id	uuid	PK	回执 ID
delivery_id	uuid	FK, Not Null	所属投递
attempt_id	uuid	FK, Nullable	对应发送尝试
stage	varchar(16)	Not Null	delivered / failed
dedupe_key	varchar(256)	Unique, Not Null	回执幂等键
external_event_id	varchar(256)	Nullable	平台回执事件 ID
detail	jsonb	Nullable	脱敏状态信息
occurred_at / received_at	timestamptz		平台发生/系统接收时间

2.8 im_actions

字段	类型	约束	说明
id	uuid	PK	用户动作 ID，同时作为 commandId 和 SSE Event ID
delivery_id	uuid	FK, Not Null	所属投递
device_id	varchar(128)	Not Null	目标本地设备
task_id	varchar(64)	Not Null	目标强提醒对应的定时任务 ID
action_type	varchar(32)	Not Null	acknowledge / snooze
action_params	jsonb	Nullable	动作参数
action_key_hash	varchar(128)	Unique, Not Null	Token/平台 action key 哈希
operation_id	varchar(128)	Unique, Not Null	业务动作幂等 ID
expected_identity_id / actual_identity_id	uuid	FK	预期/实际执行身份
status	varchar(32)	Not Null	pending / dispatched / processing / succeeded / failed / expired
dispatched_at	timestamptz	Nullable	最近一次通过 SSE 下发时间
result	jsonb	Nullable	业务执行结果
expires_at	timestamptz	Not Null	过期时间

索引：(device_id, status, expires_at)。SSE 重连查询同一设备与 task 下尚未确认、未过期的 Action；Last-Event-ID 用于识别续接位置，但只有 ReminderActionResult 才能确认命令完成。该表承担短时 Command Inbox，不增加本地 Outbox。

2.9 im_inbound_events

字段	类型	约束	说明
id	uuid	PK	主键
channel_account_id	uuid	FK, Not Null	关联通道
external_event_id	varchar(256)	Not Null	平台事件ID
event_type	varchar(64)		事件类型
payload	jsonb		规范化载荷
status	varchar(16)		received / processing / processed / failed
occurred_at / received_at	timestamptz		时间

复合唯一：(channel_account_id, external_event_id)。

2.10 im_devices

字段	类型	约束	说明
device_id	text	PK	唯一物理设备 ID
user_id	text	Not Null	唯一所有者；一个用户可拥有多台设备
token_digest	bytea	Unique, Not Null	SHA-256 原始 32 字节摘要，不保存明文 Token
status	text	Not Null	active / revoked
created_at	timestamptz	Not Null	创建时间
updated_at	timestamptz	Not Null	更新时间

约束：

• octet_length(token_digest) = 32
• userId 创建后不可修改
• 每台设备使用独立 Token
• 本次不提供公网注册、激活、设备转让或所有者修改

3. 实体关系

本地数据库：
schedule_rules 1 ── N schedules
schedule_rules 1 ── N schedule_exceptions
schedule_exceptions 0..1 ── 1 schedules（exception 关联已物化实例）
schedules 1 ── 1 timer_tasks（逻辑关联：task_id 由日程模块分配，注册表 MVP 驻留内存）

IM 服务端：

内部用户 1 ── N im_devices
im_devices 1 ── N im_pairing_sessions

im_channel_accounts 1 ── N im_external_identities

im_devices 1 ── N im_bindings（包含历史）
im_devices 1 ── 0..1 active im_binding

im_external_identities 1 ── N im_bindings（包含历史）
im_external_identities 1 ── 0..1 active im_binding

im_pairing_sessions 1 ── 0..1 im_bindings
im_bindings 1 ── N im_deliveries
im_deliveries 1 ── N im_delivery_attempts
im_deliveries 1 ── N im_delivery_receipts
im_deliveries 1 ── N im_actions
im_channel_accounts 1 ── N im_inbound_events

---

九、总结

VoiceLife MVP 以本地日程 + 定时任务为业务事实源，以语音为主要交互方式、IM为辅助通道，通过六个核心模块的分工协作实现完整主链路:

• 语音模块负责交互编排，不执行业务
• MCP 模块负责工具路由，不持有状态
• 日程 + 定时任务负责业务事实与调度，是系统核心（日程模块把周期规则展开为具体 trigger_at 后注册一次性 task，到点由 callback 完成投递与下一次排程）
• IM 模块负责消息通道，通过 Handler、Application Port、Koishi Adapter 与 Capability Plugin 隔离业务语义和平台差异；强提醒动作使用临时 SSE 下发，HTTPS 回传执行结果

数据流向：用户语音 → 意图 → 日程 → 定时触发 → 提醒投递 → 临时 SSE 等待动作 → 用户确认 → HTTPS 回传结果 → 闭环