12 KiB
小宝预警设计规格
日期：2026-06-29
背景
小宝预警是版本级项目风险预警能力，目标是帮助项目管理人员和版本成员提前判断版本是否能按期发版。如果不能按期发版，需要说明原因、预计延期到多久、建议什么时间点发版，以及当前风险是在变好还是变坏。
本功能与现有健康度不同。现有健康度更偏当前状态评分；小宝预警需要覆盖发版预测、风险趋势、静默风险、AI 解读和日报证据。
目标
- 在主导航工作区中增加“小宝预警”，位置在“与我相关”上方。
- 管理人员可以查看所有版本预警；非管理人员只能查看自己作为版本成员参与的版本预警。
- 以规则引擎为主，稳定计算风险分、风险等级、预计可发日期、延期天数、风险原因、趋势和置信度。
- 当风险达到触发条件时，自动生成 AI 解读，不要求用户手动点击按钮。
- 将日报和工作活动数据纳入风险证据，避免只看任务状态。
- 支持静默风险，识别长期无更新、无日报、无活动、无人处理的版本。
非目标
- 不在第一版实现独立后台定时 Agent 编排。
- 不让 AI 自动修改版本截止日期、任务状态、成员或任何业务实体。
- 不用 AI 直接替代规则判断；AI 只解释规则结果和证据。
- 不把小宝预警塞入
/workspace页面内部，而是作为独立页面。
导航和权限
新增导航项：
工作区
- 小宝预警
- 与我相关
- 产品
- 项目
- 版本
- 需求池
- 加班记录
路径：
/xiaobao-warning
新增权限组“小宝预警”：
xiaobao.warning:view
xiaobao.warning:manage
可见范围：
- 有
xiaobao.warning:manage：查看所有未结束版本预警。 - 只有
xiaobao.warning:view：只查看version.members中包含当前用户的版本预警。 - 没有
xiaobao.warning:view：不显示“小宝预警”导航。
默认角色：
- 超级管理员：
* - 产品经理：
xiaobao.warning:view+xiaobao.warning:manage - 开发工程师：
xiaobao.warning:view - 测试工程师：
xiaobao.warning:view - 设计师：
xiaobao.warning:view
已有角色数据已持久化在 members AppData key 中。新增权限时，需要在成员 store 读取旧角色时为系统预置角色补齐新权限，避免老数据中的产品经理无法看到小宝预警。
分析范围
小宝预警只分析未结束版本：
planned
developing
paused
不分析：
released
closed
版本来源使用产品概览中的版本树。开发任务通过需求的 versionId 归属到版本，测试用例和 Bug 直接通过 versionId 归属到版本，计划任务通过 versionId 归属到版本。
风险模型
新增独立风险分 riskScore，范围 0-100，数值越高表示风险越高。它不复用现有健康度分，避免“健康度高是好、风险分高是坏”的语义混淆。
等级：
on_track // 风险低，可按期
attention // 需要关注，但暂未预测延期
at_risk // 有明显延期风险
likely_delayed // 预计会延期
blocked // 当前不具备发版条件
核心输出：
interface XiaobaoVersionRisk {
versionId: string;
riskScore: number;
riskLevel: 'on_track' | 'attention' | 'at_risk' | 'likely_delayed' | 'blocked';
expectedReleaseDate?: string;
forecastReleaseDate?: string;
delayDays: number;
confidence: number;
confidenceLevel: 'low' | 'medium' | 'high';
reasons: RiskReason[];
silentRisks: SilentRisk[];
trend: RiskTrend;
dailyEvidence: VersionDailyEvidence;
aiInsight?: XiaobaoRiskInsight;
}
预测依据
风险引擎输入：
- Version：状态、开始日期、期望发版日期、当前阶段、成员。
- VersionPlan：调研、产品方案、UI 计划状态、计划结束时间、实际开始和完成时间、超期原因。
- Requirement：当前版本关联需求范围。
- DevTask：状态、阻塞、预计开始和截止、执行预估、AI 预估、实际开始和结束。
- TestCase：轮次、状态、计划测试时间、执行预估、AI 预估、失败和阻塞原因。
- Bug：状态、严重程度、计划修复时间、执行预估、AI 预估、修复和关闭时间。
- WorkActivity：今日和最近工作日的交付、推进、新增、风险、进展说明。
- TaskWorklog：日报和手工进展说明。
- 工作日历：复用中国工作日历和
addWorkHours推算预计完成时间。
剩余工作量估算：
- DevTask：按状态进度扣减剩余工时，
todo=100%、in_progress=50%、testing=20%、submitted=0%。 - TestCase：未执行、执行中、阻塞的用例计入剩余测试工作量。
- Bug：未关闭 Bug 计入剩余修复工作量。缺少估时时按严重程度给兜底值。
- VersionPlan：未完成计划若计划截止晚于版本截止，计入计划风险；若已经实际进行中但长期无更新，计入静默风险。
预计可发日期：
forecastReleaseDate = addWorkHours(now, remainingWorkHours)
如果 forecastReleaseDate 晚于 expectedReleaseDate，计算 delayDays 并提高风险等级。
AI 自动触发
AI 解读不通过按钮手动触发，而是在风险触发后自动生成。
不触发：
on_track
默认不触发，仅展示规则摘要：
attention
但 attention 出现明显风险变化时也触发 AI。
自动触发：
at_risklikely_delayedblocked
额外触发条件：
riskScoreDelta >= 15forecastReleaseDate较上次延后至少 1 个工作日- P1/P2 Bug 数增加
- 测试失败数增加
- 阻塞项新增
- 距离期望发版日期小于等于 1 天且仍有未完成项
- 静默风险新出现
confidence明显下降
AI 输入必须是压缩后的事实和证据，不传整页 UI 状态。
AI 输出：
interface XiaobaoRiskInsight {
summary: string;
why: string[];
forecast: string;
recommendedReleaseWindow?: string;
suggestedActions: string[];
ownerHints: string[];
generatedAt: string;
}
AI 不写业务实体，只写预警解读缓存。
AI 解读缓存
新增 AppData key：
xiaobao-risk-insights
缓存结构：
interface XiaobaoRiskInsightCacheItem {
versionId: string;
riskSignature: string;
insight: XiaobaoRiskInsight;
generatedAt: string;
providerInfo?: {
providerId?: string;
model?: string;
};
}
riskSignature 根据版本风险输入生成。签名未变化时复用缓存，签名变化时重新生成 AI 解读，避免管理人员打开全量版本时重复消耗 token。
风险趋势
新增 AppData key：
xiaobao-risk-snapshots
每次生成风险时记录快照：
interface XiaobaoRiskSnapshot {
versionId: string;
date: string;
riskScore: number;
riskLevel: XiaobaoRiskLevel;
forecastReleaseDate?: string;
openBugCount: number;
failedTestCount: number;
blockedCount: number;
silentRiskCount: number;
confidence: number;
createdAt: string;
}
页面展示最近 7 天趋势：
- 当前风险分。
- 较昨日变化。
- 连续上升、连续下降、基本稳定等趋势文案。
- AI 解读需要读取趋势摘要，解释风险是在变坏还是变好。
第一版在用户打开小宝预警页面时写入当天快照。后续若需要更可靠的无人访问场景趋势，可升级为服务端定时快照，但这不是第一版硬要求。
静默风险
静默风险作为独立风险因子进入 riskScore，也可以触发 AI 解读。
默认阈值：
noUpdateDays >= 5 // 5 天无更新
noReportDays >= 8 // 8 天无日报
noActivityDays >= 4 // 4 天无活动
unhandledDays >= 3 // 3 天无人处理
数据来源：
work-activities判断版本是否有交付、推进、风险和进展说明。task-worklogs判断版本成员是否有日报。- DevTask/TestCase/Bug 的
updatedAt判断是否长期无人处理。 - 当前未完成项判断是否存在无人接手、阻塞未解除、Bug 未推进。
静默风险不一定立即判定延期，但需要提高风险分，并在 AI 解读中说明“风险来自缺少可见推进证据”。
置信度
新增预测置信度 confidence，范围 0-100。它表达数据是否足以支撑预测，不表示 AI 主观自信。
影响因素：
- 是否设置期望发版日期。
- 未完成 DevTask/TestCase/Bug 是否有估时。
- 测试用例是否存在并覆盖当前版本。
- Bug 是否有计划修复时间或估时。
- 版本成员是否完整。
- 最近是否有日报或工作活动。
- 风险快照是否连续。
- AI 解读缓存是否匹配当前风险签名。
置信度等级：
low
medium
high
低置信度时，小宝需要提示：
当前数据不足，预测仅供参考。建议补充估时、测试计划、Bug 修复计划或近期进展说明。
日报证据
小宝预警不直接复用 DailyReportPanel 的展示结构，而是复用底层数据，按版本生成证据摘要：
interface VersionDailyEvidence {
todayDeliveries: EvidenceItem[];
todayProgress: EvidenceItem[];
todayRisks: EvidenceItem[];
progressNotes: EvidenceItem[];
needsProgressItems: EvidenceItem[];
recentActivityCount: number;
lastActivityAt?: string;
}
默认纳入今天和最近 3 个工作日证据。这样可以避免某一天没有日报导致误判，也能发现连续多天无推进。
页面交互
小宝预警页面包含：
- 顶部汇总：高风险版本数、预计延期版本数、阻塞版本数、低置信度版本数。
- 筛选：产品、项目、风险等级、趋势、静默风险、低置信度。
- 版本预警卡片：版本上下文、风险分、趋势、期望发版日期、预计可发日期、延期天数、AI 摘要。
- 详情 Drawer：预测依据、日报证据、小宝建议、风险快照趋势。
卡片点击进入 Drawer，不直接跳转离开页面。Drawer 中可提供跳转版本详情的入口。
降级和错误处理
- AI 配置不可用：仍展示规则预警，AI 区域显示“AI 解读暂不可用”。
- AI 调用失败：保留规则结论，不写入 insight 缓存。
- 风险数据不足：风险等级可为
attention，同时降低confidence。 - 快照缺失：趋势显示“暂无趋势”，不阻塞当前风险判断。
- 日报证据为空：正常展示，并可能触发静默风险。
- 管理人员版本很多：只对可见且触发条件满足的版本请求 AI 解读，并通过
riskSignature去重。
测试范围
需要覆盖：
- 权限过滤：管理人员全量、非管理人员仅版本成员、无权限不显示。
- 风险分计算：开发剩余、测试失败、Bug 增加、阻塞、临近发版。
- AI 触发：等级触发、
attention风险剧变触发、on_track不触发。 - 趋势：风险连续上升、下降、稳定。
- 静默风险：无更新、无日报、无活动、无人处理。
- 置信度：缺少截止日期、缺少估时、缺少日报、快照不连续。
- AI 缓存：签名不变复用缓存，签名变化重新生成。
- 日报证据：按版本聚合
work-activities和task-worklogs。
文档影响
实现时需要同步更新：
docs/architecture.md：新增小宝预警引擎、趋势快照和 AI 解读缓存。docs/decisions.md：新增关于规则优先、AI 自动解读、风险趋势和静默风险的设计决策。docs/workflow.md：补充小宝预警可见范围、AI 触发和日报证据工作流。docs/roadmap.md：将 Risk Watch Agent 从规划项升级为小宝预警计划项。docs/agent-spec.md：补充 Risk Watch Agent 的输入、输出、权限和失败回退。