docs(小宝预警): 更新架构与 Agent 规范

docs/agent-spec.md

@@ -105,9 +105,26 @@
 - 不自动分配 assignee；AI 只提供可选推荐，用户确认采纳后才写入
 - 不做"上一版基准 diff"
 
-### Agent 2：Risk Watch Agent（风险预警）— 待规划
+### Agent 2：Risk Watch Agent（小宝预警解读）
 
-仅占位，正式规划见 roadmap.md V3.2。
+**目的**：解释小宝预警规则引擎输出的版本发版风险结果，生成项目经理可读的风险原因、延期预测、建议发版窗口和处理动作。
+
+**输入**：
+- 版本上下文：产品、项目、版本、期望发版日期。
+- 规则风险结果：`riskScore`、`riskLevel`、`forecastReleaseDate`、`delayDays`、`confidence`、风险信号。
+- 趋势和快照：风险分变化、连续上升/下降、关键 Bug、失败用例、阻塞和静默风险变化。
+- 日报与工作活动证据：今日交付、今日进展、今日风险、进展备注、需要补充进展的事项。
+
+**触发**：
+- `on_track` 不触发。
+- `at_risk`、`likely_delayed`、`blocked` 自动触发。
+- `attention` 在风险分明显上升、趋势连续上升、关键 Bug 增加、失败用例增加、阻塞增加、静默风险增加、置信度下降或预测发版日延后时触发。
+
+**输出**：`summary`、`why[]`、`forecast`、`recommendedReleaseWindow`、`suggestedActions[]`、`ownerHints[]`。
+
+**权限**：读规则结果和压缩证据；写 `xiaobao-risk-insights` 缓存。不修改 Version、Requirement、DevTask、TestCase、Bug、Member。
+
+**失败回退**：AI 不可用时保留规则预警，前端显示“规则预警已生成，AI 解读会在触发条件满足时自动补充”。AI 失败不影响快照保存和规则风险展示。
 
 ### Agent 3：Schedule Suggest Agent（排期建议）— 待规划
 

docs/architecture.md

@@ -177,3 +177,18 @@ The personal daily report is derived from two inputs:
 `workspace-daily-report.ts` remains a pure aggregation engine. It groups today's current-user activity into delivery, progress, creation, risk, and note sections, and also detects in-progress work that started before today but has no activity or progress note today.
 
 This is intentionally not a generic rules engine or event bus. The rule surface is explicit, typed, and local to the workspace/daily-report use case.
+
+## Xiaobao Warning Layer (2026-06-29)
+
+Xiaobao Warning is a version-level release-risk capability shown above `/workspace` in the main navigation. It answers whether a version can ship on the expected release date, why it may not, roughly how long it may slip, and which release window is safer.
+
+The rule surface stays in pure frontend engines:
+
+- `xiaobao-risk.ts`: risk score, level, forecast release date, confidence, and current snapshot.
+- `xiaobao-risk-evidence.ts`: version work aggregation, daily report/activity evidence, and silent-risk detection.
+- `xiaobao-risk-trend.ts`: daily snapshots, trend detection, and snapshot signatures.
+- `xiaobao-risk-ai.ts`: AI trigger policy, cache signature, and backend request mapping.
+
+Managers with `xiaobao.warning:manage` can see all unfinished versions. Non-managers with `xiaobao.warning:view` can only see unfinished versions where the current user is in `version.members`.
+
+AI explains rule results only. It writes interpretation cache to `xiaobao-risk-insights` and never mutates Version, Requirement, DevTask, TestCase, Bug, or Member data. Risk snapshots are saved to `xiaobao-risk-snapshots` when the page is opened. The first version uses page-triggered analysis rather than a background scheduled Agent.

docs/decisions.md

@@ -404,3 +404,15 @@
 - 没有明确角色匹配或成员匹配时，AI 不输出推荐字段，任务保持未分配，供成员后续领取或手动分配。
 
 **理由**：负责人推荐能减少项目经理初次分配成本，但分配本身是团队执行承诺，必须由人确认。把推荐和写入分开，可以复用版本成员上下文，又避免模型幻觉姓名或越权自动派单。
+
+## 36. 小宝预警规则优先，AI 只做解释
+
+**问题**：如果直接让 AI 判断版本能否发版，模型可能忽略系统内的任务、Bug、测试、日报和权限事实，结论不可追溯；如果只按风险等级触发 AI，又会漏掉同等级内风险剧变，例如 P1 Bug 从 0 到 3、测试失败、发版日只剩 1 天。
+
+**决策**：
+- 小宝预警先由确定性规则计算 `riskScore`、`riskLevel`、`forecastReleaseDate`、`confidence`、趋势、静默风险和证据摘要。
+- `on_track` 不触发 AI；`at_risk`、`likely_delayed`、`blocked` 自动触发 AI；`attention` 只有在风险分、趋势、关键 Bug、失败用例、阻塞、静默风险、置信度或预测日期出现明显恶化时触发。
+- AI 解读自动触发，不提供人工“AI 解读”按钮。缓存签名必须覆盖趋势、原因、静默风险、日报/活动证据、风险信号和置信度，避免复用过期解读。
+- AI 只写入 `xiaobao-risk-insights` 缓存，不修改 Version、DevTask、TestCase、Bug、Requirement 或 Member。
+
+**理由**：规则结果可测试、可追溯、可复盘；AI 文案提升可读性，但不能替代系统事实判断。趋势、静默风险和置信度能弥补“当前风险等级”过于静态的问题。

docs/roadmap.md

@@ -97,13 +97,15 @@ NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSO
 - 不做"上一版基准 diff"（按 decisions.md #17 决议）
 - 单 Agent 单 Round，不做多 Agent 编排
 
-### V3.2 — Risk Watch Agent + Schedule Suggest Agent
+### V3.2 — 小宝预警 / Risk Watch Agent
 
-**Risk Watch Agent**：自动识别延期/阻塞集中/工时偏差大的任务，提前预警
+小宝预警以版本发版风险为核心，先通过规则引擎计算风险分、趋势、静默风险、预计可发日期和置信度，再由 Risk Watch Agent 自动解释高风险版本。第一版已落地页面触发模式：打开 `/xiaobao-warning` 时保存当天快照，并在满足触发条件时自动生成 AI 解读。
 
-**Schedule Suggest Agent**：基于成员负载和历史耗时，建议下一阶段任务分配
+当前不做后台定时 Agent。后续如果需要主动通知，再在已有 `xiaobao-risk-snapshots` 和 `xiaobao-risk-insights` 基础上增加定时巡检与消息推送。
 
-**多 Agent 协作设计**：到 V3.2 才真正涉及，当前 agent-spec.md 仅占位
+**Schedule Suggest Agent**：基于成员负载和历史耗时，建议下一阶段任务分配，仍作为后续候选。
+
+**多 Agent 协作设计**：等 Risk Watch 与 Schedule Suggest 都稳定后再设计编排策略。
 
 ### V3.3 — 其他场景候选
 

docs/workflow.md

@@ -226,6 +226,19 @@ Implementation convention:
 - Daily report grouping belongs in `apps/web/lib/workspace-daily-report.ts`.
 - Page components should consume report output, not rebuild report rules.
 
+## 小宝预警工作流
+
+小宝预警位于主导航“工作区 / 小宝预警”，展示在“与我相关”上方。可见范围由角色权限控制：
+
+- `xiaobao.warning:manage`：查看所有未结束版本的预警。
+- `xiaobao.warning:view`：仅查看当前用户在 `version.members` 中的未结束版本。
+
+页面打开时会聚合版本下的计划、开发任务、测试用例、Bug、日报和工作活动，计算当前风险并保存当天快照。页面使用 `buildXiaobaoWorkItems` 做版本级聚合，不使用个人工作台的 `aggregateWorkItems(userName, ...)` 过滤。
+
+AI 解读不由人工按钮触发。`at_risk`、`likely_delayed`、`blocked` 自动触发；`attention` 在风险分明显上升、趋势连续上升、关键 Bug 增加、测试失败、阻塞增加、静默风险增加、置信度下降或预测发版日延后时触发。缓存命中时复用解读；缓存保存时间使用客户端时间，不信任模型返回的 `generatedAt` 作为缓存新鲜度。
+
+静默风险包括长期无更新、无日报、无活动、进行中事项无人处理等信号。日报和工作活动是风险解释的重要证据，必须进入 AI 解读输入。
+
 ## 日期选择与计划时间
 
 - 调研、产品方案、UI 设计、开发任务、测试用例、Bug 创建时使用统一工作日日期时间选择器。