From d4818921ceb42ceaa9ecb1aff335aae49d6f4ec6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= <lby115@126.com>
Date: Sun, 9 Aug 2026 23:36:30 +0800
Subject: [PATCH] docs: design adaptive daily summary inquiry

---
 ...b-adaptive-inquiry-visualization-design.md | 360 ++++++++++++++++++
 1 file changed, 360 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-09-daily-summary-job-adaptive-inquiry-visualization-design.md

diff --git a/docs/superpowers/specs/2026-08-09-daily-summary-job-adaptive-inquiry-visualization-design.md b/docs/superpowers/specs/2026-08-09-daily-summary-job-adaptive-inquiry-visualization-design.md
new file mode 100644
index 0000000..8eeacf8
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-09-daily-summary-job-adaptive-inquiry-visualization-design.md
@@ -0,0 +1,360 @@
+# 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`
+
+用于记录本轮主动取证的精简审计轨迹：
+
+```json
+{
+  "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`
+
+用于表达可视化和解决机制需要的规范化问题模型：
+
+```json
+{
+  "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`
+
+记录自动选图结论：
+
+```json
+{
+  "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 单一运行时状态
+
+```javascript
+{
+  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 安全门禁和相应浏览器验收。