SA 交互组件与对接规范 - 技术预研 (Pre-research)

文档目的：针对 SA 模块审计发现的空白点，提供初步的 UI 组件交互规范、第三方 API 报文样例及 RAG 切片策略，为下周开发提供参考。

---

1. 前端交互卡片规范 (UI/UX Components)

Agent 在执行流程中需返回结构化卡片，由前端渲染。

1.1 会议室候选卡片 (Meeting Room Recommendation)

• 触发时机：Resource Pipeline 返回 SUCCESS 且包含候选列表。
• JSON Schema 示例：

{
  "card_type": "ROOM_PICKER",
  "title": "为您找到以下可用会议室：",
  "rooms": [
    {
      "room_id": "SP_001",
      "name": "火星厅",
      "floor": "3F",
      "capacity": 12,
      "tags": ["有投影", "24℃ 舒适"],
      "action": "book_now"
    },
    {
      "room_id": "SP_002",
      "name": "金星厅",
      "floor": "3F",
      "capacity": 8,
      "tags": ["有白板"],
      "action": "book_now"
    }
  ]
}

1.2 物联控制确认卡片 (IoT Confirmation)

• 触发时机：设备控制意图精细化匹配完成后（强制确认）。
• JSON Schema 示例：

{
  "card_type": "IOT_CONFIRM",
  "title": "确认执行以下操作吗？",
  "entity": "305培训室 - 空调",
  "action_desc": "调整温度至 26℃",
  "payload": {
    "device_id": "DEV_101",
    "intent": "set_temp",
    "value": 26
  }
}

---

2. 第三方平台对接报文样例 (Task C: API Payloads)

2.1 飞书 (Feishu) 创建日程 API

• Endpoint: POST /open-apis/calendar/v4/calendars/:calendar_id/events
• Payload 样例:

{
  "summary": "研发周会",
  "start_time": { "timestamp": "1674291600" },
  "end_time": { "timestamp": "1674295200" },
  "attendees": [
    { "type": "user", "user_id": "ou_xxx" }
  ],
  "rooms": [
    { "room_id": "omm_xxx" } // 对应 ai_entities 表中的 resource_id
  ]
}

---

3. 知识库 (RAG) 切片策略预研

针对空间及设备手册的 RAG 检索指引。

内容类型	切片规则 (Chunking)	元数据要求 (Metadata)
空间位置指南	按“房间/楼层”为最小单位拆分。	space_id, layer=POSITION
设备操作手册	按“故障现象”或“功能模块”拆分。	device_type, layer=MANUAL
空间管理政策	按“规定条款”段落拆分。	policy_type=MEETING_ROOM

---

4. 下周工作建议

1. Mock 验证：在 Dify 中配置上述 JSON 格式，观察前端渲染效果。
2. 鉴权打通：获取飞书测试应用的 App ID 与 Secret，验证 Token 获取流程。

---

5. 补充调研重点 (Backlog)

下周需重点突破以下两个非技术确定性问题：

1. [多平台适配性]：目前的 API 逻辑重度参考飞书。需评估钉钉及自有会议系统的接口能力，确认“产品化”的兼容边界。
2. [新场景接入]：根据 访客预约原始需求20260317.md，分析访客场景下对于 Space/Device 的特殊权限要求与交互流程。