361 lines
17 KiB
Markdown
361 lines
17 KiB
Markdown
# 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 安全门禁和相应浏览器验收。
|