ParkingRobot/docs/superpowers/specs/2026-08-09-daily-summary-job-adaptive-inquiry-visualization-design.md

Daily Summary Job 自适应取证与动态问题可视化设计

日期： 2026-08-09 状态： 已完成交互设计确认，等待书面规格复核 目标 skill： C:\Users\admin\.codex\skills\daily-summary-job

1. 背景

daily-summary-job 已能从开发证据生成 Markdown 日报和自包含交互 HTML，并支持算法场景、问题目标、四种视图模式、验证门禁和旧报告兼容。

当前仍有两类体验缺口：

1. 当证据不足时，skill 只能依据已有材料生成报告，不能主动向当前任务的 Agent 或用户补充询问，因此前后对比、原因可信度、解决机制和验证结果可能不完整。
2. HTML 中的问题诊断节点偏静态，连通关系、原因传播、解决方法和改善结果缺少统一、自然的动态表达。

本设计把 skill 升级为“主动取证与问题解释器”：先发现报告证据缺口，主动获取必要背景，再构造问题模型、自动选择可视化，并用轻量因果路径与活动检查器解释问题和解决效果。

2. 目标

• 在生成日报前，自适应判断是否需要补充信息。
• 优先询问仍在参与当前任务的主 Agent 或子 Agent，再询问用户。
• 用户追问最多四个，每个问题均可跳过。
• 将取得的信息整理为问题背景、现象、触发条件、原因链、影响、解决方法、作用机制和改善结果。
• 根据问题的主要可观察效果自动选择可视化；存在两个同等合理方案时才询问用户。
• 用轻量因果路径作为主连通骨架，用活动检查器展示原因流、证据、解决机制、前后效果和追问依据。
• 保持证据边界、离线自包含、安全校验和旧报告兼容。

3. 非目标

• 不把 HTML 升级成持久化日报编辑器。
• 不允许页面中的临时输入绕过报告事实合同或直接改写源报告。
• 不要求每次生成日报都进行固定问答。
• 不为了视觉丰富而虚构坐标、比例、指标或验证结果。
• 不将某一种领域视图固定为所有任务的通用模板。

4. 总体工作流

完整流程如下：

1. 证据扫描：读取当前对话、相关代码差异、提交、测试结果、计划、设计文档、检查点和可见 Agent 报告。
2. 缺口检测：检查当前事实是否缺少会改变日报结论或可视化的关键信息。
3. Agent 取证：若当前任务存在仍可联系的贡献 Agent，向其提出范围明确的问题。
4. 用户追问：只询问 Agent 和现有证据仍无法回答的高价值缺口，最多四问。
5. 问题建模：把证据和回答归一化为问题、原因、影响、方法和改善结果。
6. 视觉规划：按问题类型选择主视图、次级检查器、模式和前后对比方式。
7. 报告生成：渲染 Markdown 与离线 HTML，并验证问题、回答、节点和证据引用。

Agent 不可用时直接跳过第 3 步。现有证据已充分时跳过第 3、4 步。

5. 自适应取证

5.1 缺口优先级

按以下优先级决定是否追问：

1. 修改后是否存在相同条件下的匹配验证。
2. 修改前后是否存在可比较的数值、行为、状态、场景或截图。
3. 错误原因是已验证根因、静态分析、当前假设还是结论冲突。
4. 问题影响、剩余风险和下一步完成标准是否明确。

只有缺口会改变核心结论、证据等级、可视化模式或前后效果时才提问。剩余缺口不会改变这些内容时立即停止。

5.2 Agent 询问规则

• 仅询问参与当前任务且仍可联系的主 Agent 或子 Agent。
• 每个问题必须关联一个明确事实缺口，例如发现方式、变更范围、原因证据、验证命令或结果。
• 不要求 Agent 复述完整工作过程，只返回结论、证据位置和未解决项。
• 已有报告能回答的问题不得重复询问。
• Agent 无响应或不可用记为 unavailable，不占用用户四问额度。
• Agent 结论冲突时保留双方结论和来源，不由生成 Agent 猜测裁决。

5.3 用户追问规则

• 用户问题总数不得超过四个。
• 每次只提出当前信息价值最高的问题。
• 每个问题显示：询问原因、会补全的结论、2–3 个快捷建议、自由文本补充和“跳过/按现有证据生成”。
• 快捷建议只能来自已有证据能够支持的状态，例如“已执行匹配复测”“尚未验证”“只有静态分析”；不得提供带有虚构结果的选项。
• 跳过后将对应内容记录为缺失证据，不进行推断。
• 用户回答进入规范化事实源后，才用于 Markdown 和 HTML 渲染。

5.4 混合交互边界

真正的取证问答发生在 Agent 对话中。HTML 不负责保存或提交答案，而是展示：

• 为什么提出该问题；
• 问题询问了谁；
• 得到了什么精简回答；
• 回答改变了哪个问题字段、证据等级或视觉状态；
• 哪些问题被跳过或仍缺少证据。

这样既能让回答参与正式校验，又能让报告读者理解结论如何形成。

6. 数据合同

新增字段全部可选，旧报告可以完全省略。

6.1 inquiry_session

用于记录本轮主动取证的精简审计轨迹：

{
  "inquiry_session": {
    "status": "completed",
    "user_question_limit": 4,
    "gaps": [
      {
        "id": "gap-post-fix-validation",
        "kind": "validation",
        "reason": "缺少修改后相同输入的验证结果",
        "affected_fields": ["issues.issue-curvature.problem_analysis.before_after"]
      }
    ],
    "questions": [
      {
        "id": "question-post-fix-validation",
        "gap_id": "gap-post-fix-validation",
        "audience": "user",
        "prompt": "是否对修改后的相同输入重新运行了曲率扫描？",
        "reason": "决定验证结果模式能否启用",
        "affected_fields": ["issues.issue-curvature.verified_result"],
        "answer_status": "answered",
        "answer": "已重新扫描，峰值为 0.18。",
        "evidence_level": "已验证",
        "source_refs": ["本会话用户回答", "tests/output-after.json"]
      }
    ]
  }
}

status 允许 not-needed、in-progress、completed 和 partial。audience 允许 agent 和 user。answer_status 允许 answered、skipped、unavailable 和 conflict。

验证规则：

• 用户问题数量不得超过 user_question_limit，且该限制不得超过 4。
• 每个问题必须引用已声明缺口，并至少关联一个报告字段。
• answered 必须包含精简回答和来源；skipped、unavailable 不得伪造回答。
• conflict 必须包含至少两个有来源的相互冲突结论。

6.2 issues[].problem_analysis

用于表达可视化和解决机制需要的规范化问题模型：

{
  "background": "当前任务目标和问题发生的业务上下文。",
  "symptoms": [
    {"id": "symptom-peak", "statement": "P17 曲率峰值为 0.31。", "evidence_level": "已验证", "source_refs": ["tests/output.json"], "target_ids": ["curvature-peak"]}
  ],
  "triggers": [],
  "cause_chain": [
    {"id": "cause-derivative", "role": "direct-cause", "statement": "端点导数约束不足。", "evidence_level": "静态分析", "source_refs": ["LocalG2CandidateBuilder.cs"], "target_ids": ["candidate-window"]}
  ],
  "impact_chain": [],
  "solution_actions": [],
  "solution_mechanism": {
    "summary": "方法如何作用于问题机制。",
    "evidence_state": "static",
    "target_ids": ["preview-path"]
  },
  "before_after": {
    "comparison_kind": "metric",
    "before": {"label": "修改前", "value": "0.31", "target_ids": ["curvature-peak"], "source_refs": ["tests/output.json"]},
    "after": {"label": "修改后", "value": "0.18", "target_ids": ["verified-path"], "source_refs": ["tests/output-after.json"]},
    "matched_conditions": "相同输入、相同扫描命令"
  },
  "remaining_risks": []
}

原因链节点的角色允许 symptom、trigger、direct-cause、root-cause、impact、solution 和 result。每个节点必须带证据等级和来源边界。

6.3 algorithm_views[].visualization_plan

记录自动选图结论：

{
  "problem_types": ["causal", "numeric"],
  "primary_view": "causal-route",
  "secondary_inspector": "cause-flow",
  "selection_reason": "当前问题同时需要展示原因传播和修改前后曲率指标。",
  "mode_targets": {
    "baseline": ["current-path"],
    "current": ["curvature-peak", "candidate-rejected"],
    "proposed": ["preview-path"],
    "verified": ["verified-path"]
  },
  "comparison_presentation": "metric-and-overlay",
  "ambiguous_choices": []
}

如果存在两个同等合理的主视图，ambiguous_choices 保存候选项和差异，并在生成前询问用户；确定选择后保留最终选择理由。

7. 自动可视化选择

问题类型	识别信号	默认主视图	前后效果
空间/几何	位置、路径、碰撞、覆盖、形状	场景叠加与局部焦点	同坐标叠加、擦除或切换
数值/性能	超限、波动、耗时、误差、资源	曲线、阈值和指标卡	同尺度曲线和差值
状态/流程	状态错误、分支、生命周期、阻塞	状态迁移与当前路径	修改前后迁移路径
搜索/决策	候选、代价、扩展、剪枝、失败节点	搜索树或图与决策焦点	搜索范围和选择差异
时间/事件	顺序、延迟、切换、并发、时序异常	时间线与事件窗口	对齐事件序列
因果诊断	现象、触发、原因、影响、修正	轻量因果路径	原因链与改善结果
数据转换	输入、清洗、映射、聚合、错误输出	输入/中间态/输出对照	转换前后数据对照
混合	两类以上可信证据	一个主视图配一个次级检查器	主证据决定比较方式

选择原则：

1. 优先展示业务领域中可直接观察的问题效果。
2. 只使用证据支持的数据和关系。
3. 一个报告问题只选一个主视图，其他维度进入检查器或图层。
4. 两种方案同样有效时才询问用户，不为细微风格差异打断生成。
5. 没有可信数值或坐标时使用因果或状态关系，并明确证据状态。

8. 交互与视觉设计

8.1 主布局

• 主画布采用已确认的 轻量因果路径。
• 节点沿连续主路径排列，解决方法和验证结果作为清晰分支。
• 避免散乱矩形、交叉斜线和覆盖画布的大型对比条。
• 节点只显示名称、核心值和证据状态；长内容进入活动检查器。
• 主路径可表达输入、处理、异常、影响和结果，也可由具体领域适配器替换为空间、数值或状态主视图。

8.2 活动检查器

点击或键盘选择节点后，主画布保持位置稳定，检查器切换到该节点，包含以下标签：

• 背景；
• 原因流；
• 解决机制；
• 证据来源；
• 前后效果；
• 取证与追问。

原因流按“观察现象 → 触发条件 → 原因或假设 → 影响传播 → 修正与结果”展开，每个节点同时显示证据等级。

8.3 四种模式

1. baseline：展示正常机制、输入、输出和约束。
2. current：聚焦当前问题，按顺序展示现象和影响传播。
3. proposed：展示解决方法及其作用机制，必须标为 conceptual 或 static。
4. verified：只在存在匹配验证引用时启用，展示实际改善结果。

切换模式时，主视图、检查器、前后效果和验证门禁通过同一状态同步更新。

8.4 单一运行时状态

{
  algorithmId,
  issueId,
  mode,
  selectedTargetId,
  inspectorTab,
  questionId,
  comparisonState,
  visibleLayerIds,
  evidenceLevel
}

切换问题时重置目标焦点和检查器页签；用户关闭所有图层后保持关闭；不可用的 verified 模式必须回退并同步正确图层。

8.5 动态效果

• 一次只突出一个当前焦点。
• 原因传播按数组顺序逐步显现，不让所有节点同时闪动。
• 选中节点使用轻量位置、阴影和边框反馈，不改变画布布局。
• 解决预演展示从问题目标到方案目标的作用路径。
• 验证结果展示修改前后对象、指标或状态的匹配比较。
• prefers-reduced-motion: reduce 下直接显示最终状态，取消移动和传播动画。

9. 异常处理与降级

• 没有可联系 Agent：跳过 Agent 取证。
• Agent 无回答：标记 unavailable，继续其他证据路径。
• 用户跳过：记录缺失证据，保留较低结论等级。
• 回答冲突：设置 结论冲突，保留来源并增加解决冲突的验证动作。
• 没有修改后数据：隐藏 verified，允许明确标注的解决预演。
• 没有解决方案：隐藏 proposed，只展示问题和下一步。
• 没有可信坐标或数值：改用因果路径或状态关系，不绘制虚假比例。
• 视觉对象或证据引用失效：渲染前拒绝数据。
• HTML 发现外部资源：验证失败。

10. 响应式、无障碍与离线要求

• 桌面端使用主画布和右侧活动检查器。
• 900px 以下检查器移动到画布下方。
• 560px 以下使用单列控制和内容布局。
• 节点支持点击、Enter 和 Space；方向键只在非表单控件聚焦时切换问题。
• 所有交互提供可见焦点、aria-pressed、角色和证据状态文本。
• 颜色不能作为唯一状态信号，必须配合标签、线型或图标。
• HTML 继续内联 CSS、数据和 JavaScript，不包含外部 URL、link 或 script src。

11. 向后兼容

• inquiry_session、problem_analysis 和 visualization_plan 均为可选。
• 缺少新字段时继续使用现有 issues、algorithm_views 和 task_validation。
• 无 algorithm_views 的 legacy 报告继续隐藏领域画布并保留文本诊断。
• 现有 Markdown 基础章节语义不变；存在问题模型时增加主动取证摘要、问题机制和前后效果内容。
• 更新模式按稳定 issue ID 合并，不擦除历史证据状态变化。

12. 预期文件范围

• SKILL.md：增加主动取证、停止规则、问题建模和自动选图流程。
• references/report-schema.md：增加三个可选扩展合同。
• scripts/prepare_report.py：验证新字段，渲染 Markdown，并校验 HTML 引用。
• scripts/test_prepare_report.py：新增合同、追问预算、自动选图、兼容和交互回归。
• assets/interactive-report-template.html：增加活动检查器页签和取证摘要区域。
• assets/visualization-runtime.js：扩展单一状态、因果路径、检查器和比较联动。
• assets/visualization-adapters.js：增加轻量因果路径适配策略，同时保留通用回退。
• assets/visualization-styles.css：实现确认后的轻量路径、原因流、响应式与 reduced-motion。
• agents/openai.yaml：更新 UI 描述和默认提示。

不修改 ParkingRobot 业务代码。

13. 测试与验收

13.1 Python 合同与工作流测试

• 无缺口时不生成问题。
• Agent 能回答时不重复询问用户。
• 用户问题按既定优先级产生且最多四个。
• 跳过、不可用、回答和冲突状态均正确归一化。
• 问题必须关联缺口和报告字段。
• 已验证原因、结果和 after 数据必须有来源。
• 原因链、解决机制和前后对象必须引用存在的视觉目标。
• 八类问题能选择预期视图；真正歧义时产生候选选择。
• legacy 报告继续完成 render、validate 和 update 往返。

13.2 HTML 与 JavaScript 测试

• 轻量因果路径、活动检查器页签和取证摘要钩子存在。
• 节点选择同步检查器、原因流、解决机制和前后效果。
• proposed 和 verified 门禁遵守证据状态。
• 关闭最后一个图层后保持全隐藏。
• 问题切换、模式回退和图层状态不漂移。
• 影响传播顺序和 reduced-motion 行为正确。
• 输出不包含外部资源。

13.3 端到端与浏览器 QA

• 临时 legacy 报告和新问题模型报告均通过 CLI 往返。
• 分别验证无需追问、Agent 已回答、用户补充、用户跳过和结论冲突场景。
• 浏览器验证算法/问题选择、四模式、节点点击、Enter/Space、活动检查器页签、图层和前后效果。
• 验证桌面、900px、560px 和 reduced-motion。
• 若浏览器运行时不可用，明确记录为 待验证风险，不得以源码检查替代。

14. 完成标准

• skill 能在证据不足时按三级策略主动取证，并遵守最多四个用户问题。
• 取得的回答可追溯到缺口、报告字段和证据来源。
• 问题背景、原因、影响、解决机制和改善结果形成结构化问题模型。
• 自动选图规则覆盖八类问题，并只在真正歧义时询问用户。
• HTML 使用轻量因果路径和活动原因检查器，动态展示问题、方案机制和验证效果。
• 新旧报告均通过自动化、CLI 安全门禁和相应浏览器验收。