主题
M9 服务质量（场景 PRD）
| 项 | 内容 |
|---|---|
| 文档定位 | 08_移动端AI场景设计.md §10 管理者模块 M9 服务质量；本文为全量设计，当前不纳入本期演示（08 §10 未给 M9 加反引号）。写法见 公共规范.md §8 |
| 通用规范 | 前端形态、常驻会话、系统提示词边界、输出规范见 公共规范.md；本文只写 M9 场景本身 |
| 能力来源 | 巡检统计（05 巡检任务完成情况统计）、视觉巡检（04 AI智能巡检）、工单与投诉统计 |
| 版本 | v0.2 |
1. 场景定义
1.1 一句话
管理者一句话问「这个月巡检完成率、视觉巡检误报率、投诉闭环率怎么样」，Agent 按规则 / 视觉 / 人工三类分别取数，给出结论、指标表、一张对比图和缺口清单。
1.2 用户与价值
| 项 | 内容 |
|---|---|
| 用户 | 管理者（学院/项目运营负责人），示例固定账号 M1001 |
| 价值 | 不打开 BI 看板、不导 Excel，一句话拿到服务质量结论，并能立刻追问「哪个班组拖的」「和上月比呢」 |
| 频次 | 按需，周例会、月度复盘前 |
1.3 触发方式
- 被动问答，没有定时任务。
- 典型 query：
- 「这个月巡检完成率、视觉巡检误报率、投诉闭环率怎么样？」
- 「这周和上周比呢？」
- 「哪个楼层的巡检按时率最差？」
- 时间范围缺省时按
公共规范.md的对话习惯取「本月至今」；用户说了「上周 / 本月 / 上个月 / 自定义」则以其为准。
1.4 边界
| 不做 | 原因 |
|---|---|
| 不做定时推送日报/月报 | 日报归 O8，月度运营报告归 M10；M9 只做按需问答 |
| 不把三类合并成一个大数 | 规则/视觉/人工的执行方式和口径完全不同，合并会掩盖短板 |
| 不替工单系统派单、不建单 | M9 只读，不做写操作 |
| 不做个人绩效排名 | 默认只到楼层/班组/空间维度，避免被当成考核工具；个人排行列入待确认 |
| 不输出快捷按钮/业务卡片 | 单对话，追问直接打字 |
| 不重复 M10 的报告体例 | M9 答「指标是多少、哪里差」，M10 答「月报怎么写」；M9 的指标口径是 M10 第三、四节的取数来源 |
2. 形态约定
通用形态见 公共规范.md（小程序悬浮球打开 DeerFlow 聊天区、单会话、Markdown + Mermaid）。
本场景只约定：
- 纯对话触发，回答直接落在当前常驻会话里，不写首页洞察卡片（被动问答不属于 L4 主动服务）。
- 一次回答只覆盖一个主意图；用户在同一轮里既问巡检又问投诉时，先答巡检，末尾一句「投诉要不要一起看」。
- 多轮追问（换时间、换维度）沿用同一条会话上下文，不重新问一遍参数。
3. Agent 输出设计
3.1 输出元素
| 元素 | 用途 |
|---|---|
| Markdown 文字 | 结论段、短板判断、口径说明、数据缺口 |
| Markdown 表格 | 三类巡检指标表 + 投诉/工单行 |
Mermaid xychart-beta | 三类巡检完成率对比柱状图（一次回答最多 1 张图） |
3.2 指标口径（Agent 必须在回答里体现）
指标定义先于取数，口径含糊时先说明再给数：
| 指标 | 定义 | 备注 |
|---|---|---|
| 完成率 | 已完成任务数 ÷ 计划任务数 | 分母是任务数，不是巡检项数 |
| 按时率 | 计划时间窗口内完成的任务数 ÷ 计划任务数 | 提前完成算按时 |
| 漏检率 | 计划内无巡检记录的任务数 ÷ 计划任务数 | 设备停用/离线是否豁免待确认 |
| 异常率 | 异常数 ÷ 已完成巡检项数 | 同一异常重复上报按 1 条算 |
| 误报率 | 标记误报的异常数 ÷ 报出异常数 | 只对规则 / 视觉有效，人工巡检标「—」 |
| 复核率 | 需人工复核的巡检项数 ÷ 已完成巡检项数 | 视觉巡检主要看这个 |
| 闭环率 | 已闭环数 ÷ 应闭环数 | 巡检取异常转工单后的闭环；投诉取已闭环投诉 |
3.3 主模板
{结论段：一句话总体判断 + 指出短板}
| 类别 | 计划 | 已完成 | 完成率 | 按时率 | 异常数 | 误报率 | 需复核 |
|---|---|---|---|---|---|---|---|
| 规则巡检 | … | … | … | … | … | … | — |
| 视觉巡检 | … | … | … | … | … | … | … |
| 人工巡检 | … | … | … | … | … | … | … |
| 合计 | … | … | … | … | … | — | … |
（Mermaid 柱状图：三类完成率）
投诉：共 {N} 起，闭环 {M} 起（{X}%），平均 {H} 小时。
**环比**：{只写变化 ≥5pp 的指标}
**数据缺口**：{缺失项逐条列出}3.4 示例
示例数字与 M10-月度报告.md §3.3 的 10 月月报对齐；合计按时率 1,742 ÷ 1,860 = 93.66%，按 M10 口径截断记为 93.6%。
用户
这个月巡检完成率、视觉巡检误报率、投诉闭环率怎么样？
Agent
10 月服务质量整体尚可：巡检总完成率 96.4%、按时率 93.6%，短板在视觉巡检误报率 12.2%（9 月 6.8%）、人工巡检按时率 89.6%（9 月 95.8%）和投诉闭环率 63.0%。
类别 计划 已完成 完成率 按时率 异常数 误报率 需复核 规则巡检 900 882 98.0% 95.0% 38 5.3% — 视觉巡检 720 691 96.0% 93.3% 74 12.2% 28 人工巡检 240 220 91.7% 89.6% 9 — 3 合计 1,860 1,793 96.4% 93.6% 121 — 31 投诉：共 27 起，闭环 17 起（63.0%），平均 41.2 小时。
环比（对比 9 月可比区间）：
- 视觉巡检误报率 6.8% → 12.2%，+5.4pp，建议排查 B 楼公共区域抓拍点位的提示词与参考图。
- 人工巡检按时率 95.8% → 89.6%，−6.2pp，结合 12 条未填结论的记录核查执行质量。
- 投诉闭环率 71.4% → 63.0%，−8.4pp。
- 其余指标环比变化均小于 5pp，不单列。
数据缺口：
- 投诉分类只到保洁/设施/教学服务三档，无二级分类，无法定位具体问题类型。
- 人工巡检有 12 条记录未填巡检项结论，已计入完成数但未计入异常统计。
- 人工巡检另有 96 项临时补充任务，已全部闭环，未计入 240 项计划口径。
- 9 月前两周计划任务表缺失，环比只对可比区间计算。
3.5 环比规则
- 默认对比上一个等长周期（本月至今 → 上月同期；上周 → 上上周）。
- 只输出变化 ≥5pp 的指标，其余写「其余指标环比无显著变化」。
- 方向说明用绝对值 + pp，不说「提升了 6.2%」，避免和相对变化混淆。
3.6 异常与降级
| 情况 | 输出 |
|---|---|
巡检计划未配置（data_quality.plan_configured=false） | 不输出完成率/按时率，只给异常数、工单数，并说明「巡检计划未配置，完成率不可用」 |
投诉系统无数据（data_source=unavailable） | 写「投诉：暂无数据来源」，列入缺口，不写 0 起/0% |
部分日期缺数据（data_quality.missing_days 非空） | 在缺口里列出缺失日期，完成率按实际有数区间算并标注 |
| 某类别计划数为 0 | 该行写「本月未配置」，不参与合计 |
| 工具调用失败 | 说明哪个指标取不到、其余照常输出；不猜数、不补数 |
| 用户问个人排名 | 说明「当前只支持楼层/班组/空间维度」，给出班组维度结果 |
4. MCP 设计
4.1 巡检统计 MCP
Tool：query_inspection_stats
| 项 | 内容 |
|---|---|
| 作用 | 按类别取巡检完成情况与质量指标 |
| 入参 | start_date（YYYY-MM-DD）、end_date（YYYY-MM-DD）、category（rule / vision / manual / all，默认 all）、granularity（day / week / month / total，默认 total） |
返回：
| 字段 | 类型 | 说明 |
|---|---|---|
metrics | array | 每个类别一项，字段见下 |
metrics[].category | enum | rule / vision / manual |
metrics[].planned | int | 计划任务数 |
metrics[].completed | int | 已完成任务数 |
metrics[].on_time | int | 计划窗口内完成数 |
metrics[].missed | int | 漏检数 |
metrics[].abnormal | int | 异常数 |
metrics[].abnormal_closed | int | 已闭环异常数 |
metrics[].false_positive | int | 标记误报数；人工巡检返回 null |
metrics[].needs_review | int | 需人工复核数 |
metrics[].completion_rate | number | 0–100，计划数为 0 时 null |
metrics[].on_time_rate | number | 0–100，同上 |
metrics[].false_positive_rate | number | 0–100；人工巡检 null |
series | array | {date, category, completion_rate, abnormal}，供趋势与环比用 |
data_quality | object | {plan_configured: bool, missing_days: [], note: string} |
注：所有比率由 MCP 算好返回，不让模型做除法。人工巡检的 false_positive / false_positive_rate 返回 null，输出层渲染成「—」，不是 0。
4.2 投诉 MCP
Tool：query_complaints
| 项 | 内容 |
|---|---|
| 作用 | 取投诉受理与闭环情况 |
| 入参 | start_date、end_date |
返回：
| 字段 | 类型 | 说明 |
|---|---|---|
total | int | 投诉总数 |
closed | int | 已闭环数 |
close_rate | number | 0–100 |
avg_close_hours | number | 平均闭环时长（小时） |
by_category | array | {key, count, closed, close_rate} |
data_source | enum | available / unavailable |
注：data_source=unavailable 时其余字段为 null，模型必须输出「暂无数据来源」，不得渲染为 0。
4.3 工单统计 MCP
Tool：query_workorder_stats
| 项 | 内容 |
|---|---|
| 作用 | 取工单量与时效，回答「响应/闭环慢不慢」 |
| 入参 | start_date、end_date、dimension（type / status / space）、status（可选，过滤状态） |
返回：
| 字段 | 类型 | 说明 |
|---|---|---|
by_dimension | array | {key, count, avg_response_hours, avg_close_hours} |
total | int | 工单总数 |
overdue_count | int | 超时工单数 |
注：M9 只读工单统计。建单、派单、转办属 O4/工单系统，不在本场景范围。
5. Skill 设计
5.1 不封装 Skill 的理由
M9 是单意图查询 + 多轮参数调整：用户可能先问「这个月」，再问「换上周」，再问「只看视觉」。固定流程会把参数固化，反而让 Agent 无法按追问灵活换参数。因此由 ReAct 直接调 MCP，不建 Skill。
对照：T1 这类「每次输出格式必须完全一致」的定时任务才需要 Skill。
5.2 工具选择约束
| 约束 | 说明 |
|---|---|
| 一次回答最多调 3 个工具 | 巡检、投诉、工单各一次；避免重复调用刷数 |
| 巡检统计必调 | 任何服务质量问题都以 query_inspection_stats 为主 |
| 投诉工具按需调 | 用户提到投诉/闭环/满意度才调 |
| 工单工具按需调 | 用户问到响应时长、超时、工单量才调 |
| 环比要双周期取数 | 需要环比时，对上一周期再调一次同工具，最多 2 次 |
| 不调无关工具 | 不调能耗、空间、访客类工具 |
5.3 对话约束（追加到管理者助手提示词）
你是管理者助手，回答服务质量问题时：
- 巡检必须按规则 / 视觉 / 人工三类分别给出，不合并成一个大数。
- 所有比率直接使用工具返回值，不要自己计算或四舍五入后改写口径。
- 工具返回 null 时输出「—」或「暂无数据来源」，不得写成 0。
- 环比只描述变化 ≥5 个百分点的指标。
- 不把空数据解读为「表现良好」。
- 不输出个人绩效排名，只到楼层 / 班组 / 空间维度。
- 不做建单、派单、改任务等写操作。
- 一次回答最多 1 张图，优先用表格承载明细。6. 定时任务配置
不配置定时任务。
- M9 是管理者按需提问，没有固定时间点的必要；每天/每月自动推指标属于 O8（巡检日报）和 M10（月度报告）。
- 若后续需要「每周一自动出一份服务质量简报」，应作为 M10 的子项或新增模块单独设计，不在 M9 里加任务，避免同一指标两条推送口径。
7. 权限与数据范围
- 管理者助手按登录角色的授权范围取数；示例固定
M1001，范围为全院。 - 数据范围由 MCP 侧按组织/空间权限过滤，不靠提示词约束；越权范围直接返回空并由 Agent 说明「无权限查看该范围」。
- 不返回个人维度（巡检员姓名、处理人工号）的绩效数据；只到楼层、班组、空间。
- 只读：三个工具均为查询类，不提供写接口。
- 投诉涉及投诉人信息时只返回数量与分类，不返回投诉人姓名、联系方式。
8. 验收要点
| # | 验收项 | 标准 |
|---|---|---|
| 1 | 三类分列 | 指标表中规则/视觉/人工三行齐全，不出现只给合计的回答 |
| 2 | 数值准确 | 表格数字与 query_inspection_stats 返回值一致，率为工具返回值而非模型计算 |
| 3 | 误报率口径 | 人工巡检行误报率显示「—」，不显示 0 |
| 4 | 图表 | 恰好 1 张柱状图，数值与表格一致；不出现第二张图 |
| 5 | 环比 | 只列变化 ≥5pp 的指标，方向与数值正确 |
| 6 | 空数据 | 投诉无来源时写「暂无数据来源」，不出现 0 起 / 0% |
| 7 | 计划缺失 | plan_configured=false 时不输出完成率，改为说明原因 |
| 8 | 权限 | 只返回授权范围内的数据；个人排名请求被正确降级为班组维度 |
| 9 | 多轮 | 追问「这周呢」时直接改时间范围，不重新询问全部参数 |
9. 已确认与待确认
9.1 已确认
| # | 事项 | 结论 |
|---|---|---|
| 1 | 统计方式 | 规则 / 视觉 / 人工三类分别统计，不合并 |
| 2 | 触发方式 | 被动问答，无定时任务 |
| 3 | 空值处理 | 空值 ≠ 0；无来源写「暂无数据来源」并列入缺口 |
| 4 | 图表数量 | 一次回答最多 1 张图 |
| 5 | 写操作 | 无，M9 只读 |
| 6 | 个人排名 | 默认不做，只到楼层/班组/空间 |
| 7 | 本期演示范围 | 不纳入；08 §10 未给 M9 加反引号 |
9.2 待确认
- 巡检统计口径是否冻结：「完成」是提交即完成还是需审核通过；漏检是否豁免停用/离线设备。
- 投诉数据来源是否存在：是否有投诉受理系统、分类到几档、闭环以哪个状态为准。
- 视觉误报由谁认定：复核人认定、运维主管认定，还是复核结论直接作为误报口径。
- 人工巡检填报质量：未填结论的记录算什么状态，是否计入完成率。
- 是否允许个人/班组排名：如果甲方明确要用于考核，需要单独定义维度与展示边界。
- M9 是否纳入本期演示：当前 08 §10 未给 M9 加反引号，纳入后本条转为已确认。
10. 关联文档
| 文档 | 关联内容 |
|---|---|
05_巡检任务完成情况统计.md §2、§3、§5.1 | 指标口径表、分析维度、智能体工具设计 |
04_AI智能巡检-视觉巡检与日报.md §5.6、§6.1 | 误报/复核率来源、日报分类统计口径 |
M10-月度报告.md §3.3、§3.4、§4 | 月报第三、四节引用本文指标口径；本文 10 月示例与月报数字对齐 |
08_移动端AI场景设计.md §7、§10 | 管理者一天中的服务质量场景、M9 模块定义 |
公共规范.md | 前端形态、常驻会话、智能体边界、输出规范 |
注：上述文档与本文保持一致。如有差异，以本文为准，回写更新对应文档。