主题
T3 智能整备（Demo 场景 PRD）
| 项 | 内容 |
|---|---|
| 文档定位 | 08_移动端AI场景设计.md §4 教师时间线、§10 教师模块 T3 智能整备 的场景 PRD。本场景是主动执行，不是对话能力 |
| 通用规范引用 | 公共规范.md（常驻会话、首页洞察卡片、定时任务、输出规范）；本文只写 T3 场景本身 |
| 能力来源 | 既有 Dify 整备 Agent（space-agent SA_Prep 生产工作流，Webhook/定时触发）；空间语义管理中的整备配置；课表；教室中控/BA |
| 复用关系 | 执行完全复用既有 Dify 整备 Agent：扫描、决策、下发、重试、通知、执行日志都在它内部完成。本项目不重写整备流程、不新建 Skill、不新建 MCP、不做设备控制。本文只定义两件事：①整备结果如何呈现在 ReAct 智能体的 chatbox；②摘要如何进入「本周 AI 运行洞察」 |
| 版本 | v0.1 |
1. 场景定义
1.1 一句话
课前，已配置整备的教室由既有 Dify 整备 Agent 自动执行；本项目把执行结果以统一口径呈现到教师 chatbox，并生成一条「本周 AI 运行洞察」摘要。
1.2 用户与价值
| 用户 | 价值 |
|---|---|
| 当日有课的教师 | 到教室即可上课，不用逐台开设备；失败时知道已被接管，不用自己找人 |
| 运维 | 失败项集中到运维侧处置，不靠教师报修 |
| 管理者 | 课前保障有统一记录，可追溯 |
1.3 触发方式
- 主动执行，没有用户 query；不通过对话触发，也不通过本项目的智能体触发。
- 触发由空间语义管理里的整备配置决定：
- 房间配置了整备（整备开关打开，且至少一条 RW 语义）→ 有课前日程时执行；
- 房间没配置 → 不执行，也不产生任何消息（不输出「今天没有整备项」这类噪声）。
- 执行者是既有 Dify 整备 Agent：它自己负责扫描、决策、下发、重试。
- 本项目不新增定时任务、不重写触发窗口与沉默期。
1.4 边界
| 不做 | 原因 / 归属 |
|---|---|
| 不接受「帮我开灯」这类对话控制 | 属设备控制（T5）；本场景不响应设备指令 |
| 不做教师追问的问答流程 | 追问设备状态/原因属 T5 与设备查询；本场景只呈现一次执行结果 |
| 不重写触发、决策、下发、重试 | 全部在既有 Dify 整备 Agent 内 |
| 不新建 Skill / MCP | 本项目只做消息呈现，不重复编排 |
| 不自动换教室，不给换教室建议 | 失败只交运维处置 |
| 不控窗帘 | 窗帘归 T5 案例讨论模式 |
| 不做课前巡检报告、欢迎屏 | 巡检归 O3；欢迎屏未确认 |
| 不做微信模板消息 / 系统通知 | 结果进常驻会话 + 洞察卡片 |
| 不把「未接入」当失败 | 未接入是配置缺口，不是设备故障 |
| 不展示其他教室、其他教师的整备结果 | 数据范围只在本人课程教室 |
1.5 职责划分
| 环节 | 谁负责 |
|---|---|
| 扫描课表、判断是否到整备时间、去重与沉默期 | 既有 Dify 整备 Agent |
| 读空间语义配置、LLM 决策、下发、重试 | 既有 Dify 整备 Agent |
| 写执行日志 / Action Log | 既有 Dify 整备 Agent |
| 失败通知运维 | 既有 Dify 整备 Agent（沿用其现有通知渠道） |
| 结果消息呈现在 chatbox | 本项目（ReAct 智能体接收结果并渲染） |
| 摘要写入「本周 AI 运行洞察」 | 本项目（小程序壳） |
2. Demo 形态
通用形态见 公共规范.md。本场景只约定：
- 结果写入该教师的常驻会话，不新建会话；同一条结果的摘要写入首页「本周 AI 运行洞察」卡片，保留 7 天。
- 不弹系统通知；教师打开小程序后看到结果。
- 一次执行只产生一条消息，不分段推送。
- Demo 直接触发既有 Dify 整备工作流，用四种预置结果验证呈现：全部成功、部分失败、有未接入项、房间未配置整备。
3. Agent 输出设计
3.1 输出元素
| 元素 | 用途 | 约束 |
|---|---|---|
| 结论行 | 一句话说清结果 | 成功 / 部分失败 / 未接入 / 已就绪 |
| 结果表 | 逐项列整备结果 | 最多 4 行（灯光、空调、投影、幕布） |
| 未接入标注 | 区分「没配」和「坏了」 | 写「未接入」，不计失败 |
| 洞察摘要 | 首页卡片 | ≤40 字，一卡一条 |
- 本场景不用 Mermaid：四项结果用表更清楚。
- 不输出 JSON、不用 HTML、不放编号选项（本场景没有需要用户选择的内容）。
3.2 通用规则
- 只呈现既有 Agent 的执行结果，不做二次判断：不重新判成败、不重新下发、不补发通知。
- 结论先行：先写「已整备 / 部分失败 / 未接入」，再列表格。
- 空值 ≠ 0；设备当前值缺失写「暂无」，不写「正常」。
- 教师侧不出现设备语义 key、错误码、设备地址，也不出现「换教室」及其同义表达。
- 未接入 ≠ 失败，单独标注，不计入失败数。
- 房间未配置整备时不产生任何消息。
3.3 示例①：全部成功
系统（既有整备 Agent 执行完成）
A 楼 302 已整备完成：灯光、空调、投影、幕布 4 项就绪，09:00《公司金融》可正常开始。
整备项 目标 结果 灯光 开启 · 讲课模式 已开启 空调 开启 · 24℃ 已开启，当前 24℃ 投影 开启 · HDMI 1 已开启 幕布 降下 已降下
3.4 示例②：部分失败
系统（既有整备 Agent 执行完成）
A 楼 302 已整备，3 项就绪、1 项失败：投影未开启，已通知运维。
整备项 目标 结果 灯光 开启 · 讲课模式 已开启 空调 开启 · 24℃ 已开启，当前 24℃ 投影 开启 · HDMI 1 失败 幕布 降下 已降下 运维已收到失败项，将在课前处理；课程可正常开始。
3.5 示例③：有未接入项
系统（既有整备 Agent 执行完成）
A 楼 302 已整备，3 项就绪：幕布未接入中控，未执行，不计入失败。
整备项 目标 结果 灯光 开启 · 讲课模式 已开启 空调 开启 · 24℃ 已开启，当前 24℃ 投影 开启 · HDMI 1 已开启 幕布 降下 未接入
3.6 示例④：房间未配置整备
不产生任何消息，也不生成洞察卡片。执行日志里记一条：「A 楼 302 未配置整备，跳过」。教师侧无感。
3.7 关于教师追问
本场景不设追问示例。整备是主动执行、结果一次性呈现；教师问「投影为什么没开」「帮我开一下投影」属于设备状态查询与设备控制（T5），由那个场景回答，本文不承担。
4. 结果接入契约
4.1 执行结果字段
既有 Dify 整备 Agent 每次执行完成后，向本项目提交一份结果。字段建议如下（以实际工作流为准，缺字段按 §4.5 降级）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prep_id | string | 是 | 本次整备唯一 ID，用于去重 |
executed_at | string | 是 | 执行时间，YYYY-MM-DD HH:mm |
course.course_id / course_name | string | 是 | 课程 |
course.start_time / end_time | string | 是 | 起止时间 |
room.room_id / room_name | string | 是 | 教室 |
actions[] | array | 是 | 每条 name、target、result、error_message |
actions[].result | enum | 是 | success / failed / not_connected / skipped |
planned_summary | string | 否 | 既有 Agent 生成的概要，可作结论行素材 |
failed_count | int | 是 | 失败项数；0 表示无失败 |
notification_id | string | 否 | 失败通知编号；无失败为 null |
4.2 字段到消息元素的映射
| 消息元素 | 取值 |
|---|---|
| 结论行 | room_name + actions 汇总 + failed_count |
| 结果表 | actions[]（name / target / result） |
| 「已通知运维」 | notification_id 非空时追加一句 |
| 未接入标注 | result=not_connected 的项 |
| 已就绪 | actions 全是 success 且无变更动作时，按 planned_summary 输出「当前环境已就绪」 |
4.3 洞察卡片
| 项 | 规则 |
|---|---|
| 数量 | 一次执行一条卡片 |
| 摘要 | {教室} 整备完成 或 {教室} 整备：{N} 项就绪、{M} 项失败，≤40 字 |
| 保留 | 7 天，超期自动移出 |
| 点击 | 回到会话看完整结果 |
| 未配置 | 不生成卡片 |
4.4 去重与幂等
- 以
prep_id去重：同一prep_id重复回调只呈现一次。 - 同一课程 + 同一教室的重复回调（重试、重放）合并为一条，不追加第二条消息。
- 不按时间窗口猜是否重复。
4.5 异常与降级
| 情况 | 处理 |
|---|---|
| 回调超时 / 失败 | 不向教师呈现错误；记日志，由既有 Agent 重试 |
room_name 缺失 | 用 room_id 兜底；仍缺失写「暂无」 |
actions 为空 | 按 planned_summary 输出「当前环境已就绪」 |
failed_count > 0 但 notification_id 为空 | 写「失败项已记录」，不写「已通知运维」 |
result 出现未知枚举 | 按原值展示，不擅自归为成功或失败 |
5. 呈现规则
5.1 只呈现，不重算
本项目对既有 Agent 的结论只做排版与降级，不判断对错、不改变结论、不尝试修复失败项。
5.2 消息结构固定
结论行 → 结果表（≤4 行）→ 失败说明（如有）。一条消息发完，不分段、不中途追问。
5.3 教师侧不展示
设备语义 key、错误码、中控协议、设备地址、其他教室的结果、换教室建议。
5.4 留痕
呈现即留痕：保存 prep_id、课程、教室、结果与消息映射关系，便于后续按课程追溯。
6. 定时任务配置
本项目不新增定时任务。
| 项 | 值 |
|---|---|
| 本项目是否建定时任务 | 否 |
| 触发与执行 | 既有 Dify 整备 Agent（Webhook / 定时扫描由它自身配置） |
| 本项目职责 | 接收结果 → 渲染消息 → 写洞察卡片 |
| Demo 触发方式 | 在既有 Dify 工作流里手动触发一次，观察呈现结果 |
与
公共规范.md§4「主动服务由 DeerFlow 定时任务触发」的差异：本场景的执行器是既有 Dify Agent，本项目不重复建任务。若后续要统一到 DeerFlow 调度，再迁移。
7. 权限与数据范围
| 角色 | 可见 | 可执行 | 数据范围 |
|---|---|---|---|
| 教师 | 本人课程的整备结果、失败项名称 | 只读 | 本人课程对应教室 |
| 运维 | 负责区域的失败项与执行明细 | 只读；处置走运维工具 | 负责楼栋 / 楼层 |
| 管理者 | 授权范围的整备汇总 | 只读 | 授权范围 |
| 其他角色 | 无 | 无 | 无 |
- 结果按「课程教师 + 教室」路由，不广播。
- 教师侧只看到整备项与结果，不暴露错误码与设备地址。
8. 验收要点
| # | 验收项 | 标准 |
|---|---|---|
| 1 | 配置驱动 | 配置了整备的房间有课前日程 → 有结果；未配置 → 不产生任何消息 |
| 2 | 全部成功 | 四项均成功，输出「已整备完成」+ 结果表，与执行结果一致 |
| 3 | 部分失败 | 失败项标注清楚，教师看到「已通知运维」，不出现换教室建议 |
| 4 | 未接入 | 标「未接入」，不计入失败，不硬开 |
| 5 | 无配置不产生噪声 | 不输出「今天没有整备项」之类的消息 |
| 6 | 一条消息 | 一次执行只产生一条消息，不分段推送 |
| 7 | 幂等 | 同一 prep_id 重复回调只呈现一次 |
| 8 | 洞察卡片 | 一卡一条、≤40 字、保留 7 天、点击回到会话 |
| 9 | 信息边界 | 不出现设备语义 key、错误码、设备地址、其他教室 |
| 10 | 无对话控制 | 回复中不出现设备控制动作，也不引导教师「让 AI 开设备」 |
9. 已确认与待确认
9.1 已确认
| # | 事项 | 结论 |
|---|---|---|
| 1 | 执行主体 | 复用既有 Dify 整备 Agent，本项目不重写流程 |
| 2 | 触发口径 | 由空间语义管理中的整备配置决定：有配置才执行，没有就不执行 |
| 3 | 本项目范围 | 只做结果呈现 + 洞察卡片，不做 Skill / MCP / 设备控制 |
| 4 | 呈现位置 | 教师常驻会话 + 首页「本周 AI 运行洞察」（保留 7 天） |
| 5 | 失败处理 | 只通知运维，教师侧只显示「已通知运维」 |
| 6 | 追问 | 本场景不设追问；追问归 T5 与设备查询 |
| 7 | 未接入 | 以空间语义配置为准，缺失标「未接入」，不算失败 |
9.2 待确认
- 既有 Dify 整备 Agent 的实际输出字段是否与 §4.1 一致？回调方式是 Webhook、消息队列还是轮询？
- 「配置了整备」的判定口径：整备开关 + RW 语义，还是只要求存在 RW 语义？
- 失败通知运维目前走哪个渠道？是否要统一到本项目的运维助手会话？
- 洞察卡片摘要由本项目生成，还是直接取 Agent 的
planned_summary？ - 投影 / 幕布是否接入中控？会否长期显示「未接入」？
- 设备回读是否可得？决定写「已开启」还是「已下发」。
- 课表变更 / 换教室时，既有 Agent 的行为与新教室补整备策略。
- 寒暑假、单双周、调停课、补课如何排除。
- 同一教室连堂课是否只整备一次，由谁去重。
- 未接入项是否在首次发现时通知运维，还是只进配置缺口清单。
10. 关联文档
| 文档 | 关联内容 |
|---|---|
08_移动端AI场景设计.md §4、§10、§11、§12 | T3 场景来源、教师时间线、跨系统兜底 |
公共规范.md §2.7、§4、§5、§6 | 洞察卡片、主动服务展示方式、数据规范、输出规范 |
07_课程系统-课表同步与实时引导.md §2.2、§3.3 | 课表字段、教室端「环境随课走」 |
T1-到校前简报.md | 同属主动服务，呈现方式保持一致 |
space-agent SA_主动整备_Agent设计.md | 既有整备 Agent 的决策与执行设计（本文只消费其输出，不改其流程） |
注：上述文档与本文不一致时，以本文为准，回写更新对应文档。