SA 主动整备：Agent 设计方案 (v2.0)

版本: v2.0 日期: 2026-06-03 状态: 重新设计版 废弃旧版: 旧版 SA_主动整备_逻辑设计.md、SA_主动整备_Agent设计.md(旧)、SA_主动整备_UserStory.md 已移至 docs/99_回收站
核心变更：废弃 HVAC 硬编码黄金三要素 + T_prep 温差计算模型；改为 LLM 一次决策 + 动作清单通用机制，零额外配置。

1. 设计背景与问题分析

1.1 当前设计的 3 项缺陷

#	缺陷	表现
1	仅限 HVAC 温控	硬编码 `hvac_power` / `hvac_target_temp` / `env_indoor_temp` 黄金三要素，灯、窗帘、新风等非 HVAC 设备无法被整备
2	季节限定	策略表仅制冷季(6-9月)和制热季(11-2月)激活，3-5月/10月 OFF，冷热交换季无任何整备能力
3	话术硬编码	推送消息写死空调描述，无法按实际动作动态生成

1.2 架构背景

空间控制面板已重构为纯数据类型驱动：面板渲染引擎按 data_type 自动选择 UI 组件（bool→switch、number→滑块、enum→选项列表），不依赖预设模板。但整备 Agent 仍停留在 HVAC 硬编码阶段，二者架构脱节。

2. 核心设计理念

2.1 零额外配置

整备 Agent 不引入新的每房间配置项。空间逻辑映射（SSOT）是整备的唯一数据源——管理员配置空间逻辑映射时，已经定义了该房间的可操作能力 (RW 语义列表)。整备 Agent 自动消费此列表。

2.2 一次 LLM 调用决策

trigger → LLM 一次调用 → 输出:
  - summary: 一句话概要（限 30 字）
  - actions: 整备动作清单 [{semantic_key, target_value}]

LLM 不逐条反复调用，一次性输出完整的整备指令。

2.3 知识库注入

LLM 的决策规则通过 Dify 知识库注入，非硬编码。规则包括：

标准语义操作规则表（§9.2）：按 semantic_key 指定整备行为
通用兜底规则（§9.3）：规则表未匹配的语义一律保持当前值
季节策略表（HVAC 参考）
限制约束（不可超出 range/options 范围）

3. 全量决策流

3.1 扫描与 LLM 决策（公共流程）

3.2 执行模式分支

4. 触发规则

4.1 触发条件

扫描到一个未来 N 分钟内的会议，且当前时间满足：

now >= meeting_start_time - prep_window

prep_window：Dify 参数，默认 15 分钟，可全局配置
扫描频率：Dify 参数，默认每 5 分钟
不再依赖 T_prep 温差计算：无论制冷季、制热季还是过渡季，有会议 + 到时间即触发
不再依赖季节拦截：3-5 月过渡季光照变化大，灯和窗帘整备更有价值

4.2 去重与沉默期（Quiet Period）

沉默期的作用：避免同一会议被重复触发。触发规则是面向未来 N 分钟的会议批量扫描，若同一会议已完成整备/用户取消/沉默期内，则跳过。

场景	表现
整备完成后	标记该会议为"已整备"，不再重复触发
用户点击"取消备场"	标记该会议为"已取消"，进入沉默期
用户点击"暂不需要"（CONFIRM）	标记该会议为"已取消"，进入沉默期
CONFIRM 超时	标记为"已过期"，进入沉默期

沉默期时长：默认 30 分钟（Dify 参数 quiet_period）
沉默期作用域：同一会议+同一房间
沉默期在 LLM 决策前拦截，避免无谓的 LLM 调用

4.3 Dify 参数表

参数名	默认值	说明
`prep_window`	15	会议开始前提前触发的时间（分钟）
`global_delay`	5	触发后等待执行的时间（分钟）。`prep_window - delay` = 动作实际生效时间距会议开始的时间
`scan_interval`	5	扫描频率（分钟）
`quiet_period`	30	沉默期（分钟）

5. LLM 决策规格

5.1 输入上下文

LLM 接收以下输入：

## 空间信息
房间名：A-101 大会议室
面积：60㎡

## 会议信息
主题：研发周会
时间：14:00 - 15:00
人数：8 人

## 当前状态
当前月份：6 月（制冷季）
舒适温度：24℃

## RW 能力清单（来自空间逻辑映射，继承产品级配置）
| 语义 Key | 名称 | 类型 | 当前值 | label/选项 | 量程/步长 | AI 指引 | LLM 增强描述 |
|:---------|:-----|:-----|:-------|:-----------|:----------|:--------|:-------------|
| hvac_power | 空调开关 | bool | false | 0→关闭, 1→开启 | - | 控制空调电源开关 | 用于控制暖通空调的启停 |
| hvac_target_temp | 设定温度 | number | 28 | - | 16-30, step 1 | 设定空调目标温度 | 用于调节暖通空调的目标温度值 |
| hvac_mode | 运行模式 | enum | 关 | 自动/制冷/制热/送风 | - | 切换空调运行模式 | 用于切换暖通空调的工作模式 |
| light_power | 灯光开关 | bool | false | 0→关闭, 1→开启 | - | 控制灯具开关 | 用于控制照明设备的开关状态 |

**字段说明**：

| 字段 | 来源 | 说明 |
|:-----|:-----|:-----|
| label/选项 | `产品.mappings[].values` | bool/enum 的 intent 映射标签，如 `0→关闭`, `1→开启` |
| AI 指引 | `产品.mappings[].ai_instruction` | 管理员填写的工程化操作说明，LLM 严格遵循 |
| LLM 增强描述 | `标准语义库.llm_desc` | MCP 工具元数据，辅助 LLM 理解该语义的用途 |
| 量程/步长 | `产品.mappings[].min/max/step` | number 类型的物理量程边界，LLM 不可越界 |

## 整备知识库规则
（见 §9 知识库规则）

5.2 输出 JSON Schema

json

{
  "s": "空调将调至 24℃，灯光将开启",
  "a": [["hvac_power", true], ["hvac_target_temp", 24], ["light_power", true]]
}

精简原则：

仅输出需要变更的语义（当前值已满足目标值的项不输出）
短 key：s = summary, a = actions, actions 内用 [key, value] 数组对

5.2.1 概要 `summary` 规范

约束	说明
字符数	不超过 30 个汉字/字符
语态	AUTO/CONFIRM 统一为陈述式将来时：`"空调将调至 24℃，灯光将开启"`
内容	仅描述用户最关心的 1-3 项关键动作，不要罗列全部。LLM 自行判断优先级
句式	逗号分隔，不加句号

5.2.2 `summary` 在卡片中的位置

text

+-------------------------------------------+
|                                           |
|   ✨ **「研发周会」已为您提前备场**       | ← 标题
|   -------------------------------------   |
|   **A-101 大会议室** (4F)                | ← 房间信息
|   🕒 14:00 - 15:00 (**10 min后开始**)    |
|   -------------------------------------   |
|                                           |
|   **空调将调至 24℃，灯光将开启**          | ← summary (≤30字)
|                                           |
|   [ 🛠️ 深度调节 ]  [ 🚫 取消备场 ]       |
+-------------------------------------------+

5.3 动作执行时序

meeting_start - prep_window:   触发（LLM 决策完成）
meeting_start - prep_window + global_delay: 动作统一下发
meeting_start:                  会议开始

prep_window = 15min（Dify 参数）
global_delay = 5min（Dify 参数）
动作实际在会议开始 10 分钟前 生效

所有动作同时下发，不按 action 维度区分延迟。原因：

灯/窗帘属秒级响应，提前 10 分钟亮灯不浪费
空调需物理时间降温，推迟执行反而影响效果
规避 per-action delay 带来的工程复杂度

5.4 用户手动干预的处理

用户可能在 trigger → global_delay → execute 的窗口期内打开深度调节面板进行操作。

规则：打开深度调节面板并操作即视为用户接管控制，取消该房间该会议的剩余自动整备执行。

用户 17:45 收到通知 "空调将调至 24℃"
用户 17:47 点击[深度调节]进入面板，手动调至 26℃ → 立即下发（现有面板行为）
         → 该会议的整备 session 标记为 "用户已干预"
17:50 自动下发时刻 → 检查 session 标记 → 跳过（不覆盖用户手动设置）

实现方案：每个 prep_session 记录一个 user_overridden 布尔值。当深度调节面板的「保存应用到现场」被触发时，user_overridden = true。执行层在 global_delay 到期后检查此标记，若为 true 则跳过本次执行。

6. 通知卡片设计

6.1 AUTO 模式（自动执行）

text

+-------------------------------------------+
| [🤖 智能空间助手]                 [••• | ◎] |
+-------------------------------------------+
|                                           |
|   ✨ **「研发周会」已为您提前备场**        |
|   -------------------------------------   |
|   **A-101 大会议室** (4F)                 |
|   🕒 14:00 - 15:00 (**10 min后开始**)     |
|   -------------------------------------   |
|                                           |
|   **空调将调至 24℃，灯光将开启**          |
|   指令将在 5 分钟后自动下发               | ← global_delay 提示
|                                           |
|   [ 🛠️ 深度调节 ]  [ 🚫 取消备场 ]        |
+-------------------------------------------+

6.2 CONFIRM 模式（确认后执行）

初始态：询问卡片

text

+-------------------------------------------+
|   ❓ **「研发周会」建议提前整备**           |
|   -------------------------------------   |
|   **B-202 研讨室** (2F)                   |
|   🕒 14:00 - 15:00 (**10 min后开始**)     |
|   -------------------------------------   |
|                                           |
|   **空调将调至 24℃，灯光将开启**          |
|   点击「立即整备」后确认                   |
|                                           |
|   [ ✅ 立即整备 ]  [ 🚫 暂不需要 ]         |
+-------------------------------------------+

点击「立即整备」后：原位状态转换（与 AUTO 模式一致）

text

+-------------------------------------------+
|   ✅ **整备指令已下发**                    |
|   -------------------------------------   |
|   **B-202 研讨室** (2F)                   |
|   🕒 14:00 - 15:00                        |
|   -------------------------------------   |
|                                           |
|   **空调将调至 24℃，灯光将开启**           |
|   指令将在 5 分钟后自动下发               |
|                                           |
|   [ 🛠️ 深度调节 ]  [ 🚫 取消备场 ]        |
+-------------------------------------------+

5 分钟无响应：超时置灰

卡片全量置灰，按钮禁用。顶端辅助说明：[整备建议已过期]。

6.3 卡片结构说明

元素	数据来源	说明
标题	AUTO: `「{主题}」已为您提前备场` CONFIRM: `「{主题}」建议提前整备`	固定模板，主题从会议信息取
房间、时间	会议上下文	不变
工程提示（第 2 行）	AUTO: `指令将在 {global_delay} 分钟后自动下发` CONFIRM: `点击「立即整备」后确认`	固定模板
概要（核心）	LLM 输出的 `summary`	限 30 字，AUTO/CONFIRM 统一语态
按钮(左)	AUTO: 深度调节 CONFIRM: 立即整备（点击后转深度调节）	正向操作
按钮(右)	AUTO: 取消备场 CONFIRM: 暂不需要	负向操作

7. 管理后台变更

7.1 智能整备卡片（对比旧版）

变更点：

旧版	新版
黄金三要素硬编码校验（`hvac_power`/`hvac_target_temp`/`env_indoor_temp`）	改为动态检查：空间逻辑映射中是否有至少一条 `enabled=true` 的 RW 语义
依赖缺失时 switch 置灰 + 红底提示	空 RW 语义时 switch 置灰 + 提示"空间逻辑映射未配置可操作能力"
环境调节策略（月份策略表 + 调节强度系数）	移除 —— 策略表通过知识库注入 LLM，不再后台配置
执行逻辑 select（自动执行/确认后执行）	保留
本空间覆写系数	移除 —— `prep_window`/`global_delay` 放 Dify 全局参数

7.2 卡片原型 (v2.0)

text

+-------------------------------------------------------------+
| 🤖 智能整备 (Active Prep)          [ (ON) ]  [ 移除 ]         |
|-------------------------------------------------------------|
| 💡 空间逻辑映射中的 RW 语义即为整备能力范围，无需额外配置。      |
|                                                             |
| 执行逻辑: [ 自动执行 v ] (会前自动整备，完成后通知)             |
|                                                             |
| ✅ 能力检查: 已检测到 4 个 RW 语义 (空调开关/设定温度/灯光/窗帘) |
|                                                             |
| 💡 依赖能力: 空间逻辑映射（至少需配置 1 条 RW 语义）           |
|                                                             |
| 📅 参数配置移入 Dify，详见 §4.3                              |
+-------------------------------------------------------------+

8. Dify 编排参数

参数	类型	默认值	说明
`prep_window`	Integer	15	会议开始前提前触发的时间（分钟）
`global_delay`	Integer	5	触发后到统一下发之间的等待时间（分钟）
`scan_interval`	Integer	5	Cron 扫描间隔（分钟）
`quiet_period`	Integer	30	同会议沉默期（分钟），取消/完成后该会议不再重复触发

9. 知识库规则（注入给 LLM）

以下规则通过 Dify 知识库注入 LLM，分为两张表 + 通用规则。

9.1 表 1：HVAC 季节策略表

LLM 根据当前月份查询对应行。建议按当前月份仅注入 1 行，减少 token 消耗。

月份	激活	运行模式	舒适温度(℃)
11-2	ON	制热	22
6-9	ON	制冷	24
3-5	OFF	-	-

3-5 月过渡季策略 OFF，hvac_* 类语义不执行整备动作。非 hvac 类不受限。

9.2 表 2：标准语义操作规则表

每条标准语义都可以有一条操作规则，按 semantic_key 匹配。可选支持 room_id 维度覆写（P2）。

语义 key	整备操作规则	备注
hvac_power	整备时设为 true（开启）	如果策略表激活
hvac_target_temp	整备时设为季节策略表的舒适温度
hvac_mode	整备时按季节策略表设为"制冷"或"制热"
light_power	整备时设为 true（开启）
light_brightness	整备时不调整，保持当前值
curtain_position	整备时不调整，保持当前值
其他未匹配语义	保持当前值不做调整	兜底规则

注入策略：Dify 根据当前房间的 RW 语义清单，筛选匹配的行注入 LLM。

9.3 通用行为规则（顺序优先级）

1. 优先使用"标准语义操作规则表"(§9.2)中对该语义 key 的规则
2. 规则表中未匹配的语义 → 保持当前值，不做调整（不论 bool/number/enum）
3. 只读(RO)语义：永不操作
4. 所有 target_value 必须在对应语义的 range/options 范围内，不可越界
5. 参考"AI 指引"(ai_instruction) 和 "LLM 增强描述"(llm_desc) 了解语义的具体工程含义

9.4 表 3（预研）：个人偏好习惯表

本期不开发，仅做 PRD 级预研。后续版本引入。

背景：用户通过深度调节面板手动调整设备后，这些操作反映了用户的个人偏好。记录并回喂给 LLM，可实现"越用越懂你"。

数据模型：

json

{
  "user_id": "u_zhangsan",
  "room_id": "A-101",
  "habits": [
    {
      "semantic_key": "hvac_target_temp",
      "preferred_value": 22,
      "source": "manual_adjust",
      "recorded_at": "2026-06-01 14:00"
    },
    {
      "semantic_key": "light_brightness",
      "preferred_value": 60,
      "source": "manual_adjust",
      "recorded_at": "2026-06-01 14:00"
    }
  ]
}

采集时机：用户在深度调节面板中点击「保存应用到现场」时，记录该语义的最终值与 user_id + room_id 的映射。

注入 LLM：当同一用户预约同一房间时，LLM 输入上下文中注入该用户的习惯记录，作为整备决策的参考依据。LLM 可据此调整 target_value 覆盖全局默认规则。

未覆盖项：支持 room_id 为 * 的全局习惯（用户在所有房间的通用偏好）。

9.5 summary 生成规则

AUTO 和 CONFIRM 模式使用相同的 summary 语态：
- 使用陈述式将来时
- 示例："空调将调至 24℃，灯光将开启"
- 字数不超过 30 字
- 仅提及 1-3 项最重要的变化，不要罗列全部
- 保持简洁，用逗号分隔，不加句号
- 如果没有任何动作需要执行，summary 输出"当前环境已就绪"

10. 相关设计参考

文档	关系说明
SA_空间控制面板设计.md	深度调节面板设计，纯数据类型驱动。整备 Agent 不干预面板内容
空间语义管理.md	空间逻辑映射定义、空间插件能力配置。整备依赖来源
微信小程序_主动整备卡片_设计需求.md	端侧卡片交互与视觉规范，本设计与其对齐
SA_设备控制_Agent设计.md	设备控制 Agent，与整备 Agent 构成 SA 的平行双轨

11. 待定项 (Open Questions)

#	问题	状态
1	HVAC 季节策略表未来是否也改为知识库注入（与 Dify 解耦后在管理后台维护）？	M3 放知识库，P2 再议
2	沉默期是在 LLM 决策前拦截还是决策后？	决策前拦截，节省 LLM 调用

附录：与旧版设计的关键差异对照

对比项	旧版	新版
触发模型	T_prep = \|T_curr - T_comfort\| × λ_env × Area/20 + Buffer	prep_window（固定 15min，Dify 参数）
触发门槛	季节策略表激活期 + 温差 > 0	有未来会议 + 到达 prep_window
设备类型	仅 HVAC（空调开关/温度/室温）	空间逻辑映射中的所有 RW 语义
黄金三要素	hvac_power + hvac_target_temp + env_indoor_temp	无，空间逻辑映射自动成为整备范围
目标值来源	季节策略表 T_comfort（硬编码）	LLM 按知识库规则决策
通知话术	硬编码("制冷运行中, 当前室温 28℃")	LLM 动态生成 summary（限 30 字）
每房间配置	调节强度系数 + 环境策略表引用	无额外配置，空间逻辑映射为唯一数据源
执行逻辑	AUTO / CONFIRM + 黄金三要素阻断式校验	AUTO / CONFIRM + RW 语义动态检查
LLM 角色	无（工程规则驱动）	一次调用输出 summary + actions

SA 主动整备：Agent 设计方案 (v2.0) ​

1. 设计背景与问题分析 ​

1.1 当前设计的 3 项缺陷 ​

1.2 架构背景 ​

2. 核心设计理念 ​

2.1 零额外配置 ​

2.2 一次 LLM 调用决策 ​

2.3 知识库注入 ​

3. 全量决策流 ​

3.1 扫描与 LLM 决策（公共流程） ​

3.2 执行模式分支 ​

4. 触发规则 ​

4.1 触发条件 ​

4.2 去重与沉默期（Quiet Period） ​

4.3 Dify 参数表 ​

5. LLM 决策规格 ​

5.1 输入上下文 ​

5.2 输出 JSON Schema ​

5.2.1 概要 summary 规范 ​

5.2.2 summary 在卡片中的位置 ​

5.3 动作执行时序 ​

5.4 用户手动干预的处理 ​

6. 通知卡片设计 ​

6.1 AUTO 模式（自动执行） ​

6.2 CONFIRM 模式（确认后执行） ​

初始态：询问卡片 ​

点击「立即整备」后：原位状态转换（与 AUTO 模式一致） ​

5 分钟无响应：超时置灰 ​

6.3 卡片结构说明 ​

7. 管理后台变更 ​

7.1 智能整备卡片（对比旧版） ​

7.2 卡片原型 (v2.0) ​

8. Dify 编排参数 ​

9. 知识库规则（注入给 LLM） ​

9.1 表 1：HVAC 季节策略表 ​

9.2 表 2：标准语义操作规则表 ​

9.3 通用行为规则（顺序优先级） ​

9.4 表 3（预研）：个人偏好习惯表 ​

9.5 summary 生成规则 ​

10. 相关设计参考 ​

11. 待定项 (Open Questions) ​

附录：与旧版设计的关键差异对照 ​

SA 主动整备：Agent 设计方案 (v2.0)

1. 设计背景与问题分析

1.1 当前设计的 3 项缺陷

1.2 架构背景

2. 核心设计理念

2.1 零额外配置

2.2 一次 LLM 调用决策

2.3 知识库注入

3. 全量决策流

3.1 扫描与 LLM 决策（公共流程）

3.2 执行模式分支

4. 触发规则

4.1 触发条件

4.2 去重与沉默期（Quiet Period）

4.3 Dify 参数表

5. LLM 决策规格

5.1 输入上下文

5.2 输出 JSON Schema

5.2.1 概要 `summary` 规范

5.2.2 `summary` 在卡片中的位置

5.3 动作执行时序

5.4 用户手动干预的处理

6. 通知卡片设计

6.1 AUTO 模式（自动执行）

6.2 CONFIRM 模式（确认后执行）

初始态：询问卡片

点击「立即整备」后：原位状态转换（与 AUTO 模式一致）

5 分钟无响应：超时置灰

6.3 卡片结构说明

7. 管理后台变更

7.1 智能整备卡片（对比旧版）

7.2 卡片原型 (v2.0)

8. Dify 编排参数

9. 知识库规则（注入给 LLM）

9.1 表 1：HVAC 季节策略表

9.2 表 2：标准语义操作规则表

9.3 通用行为规则（顺序优先级）

9.4 表 3（预研）：个人偏好习惯表

9.5 summary 生成规则

10. 相关设计参考

11. 待定项 (Open Questions)

附录：与旧版设计的关键差异对照