# Daily Summary Job 领域算法可视化升级设计

## 1. 目标

升级个人技能 `daily-summary-job`，使开发日报不只用文字和通用流程框陈述工作，而是先理解当天函数或算法的真实业务目标，再生成与该任务匹配的领域可视化。

页面必须让读者通过点击直接理解：

1. 原函数或算法解决什么问题、正常情况下如何工作；
2. 当前问题发生在哪个对象、区域或算法阶段；
3. 出错原因是什么，或当前有哪些待验证假设；
4. 问题会沿什么路径传播并导致什么结果；
5. 纠正方案会改变哪些对象、约束或处理步骤；
6. 纠正后的预期效果是什么；
7. 哪些内容是实际观测、静态分析、概念预演或已验证结果。

路径规划只是示例。技能必须根据当前任务选择合适的可视化，而不能把所有算法都硬编码成轨迹图或普通流程图。

## 2. 已确认的设计决策

- 使用混合生成策略：涉及函数或算法时自动生成基础领域视图；出现复杂问题时再生成深入诊断和修正前后对比。
- 使用“双层算法地图”：正常算法效果作为稳定底图，问题与修正方案作为可切换叠加层。
- 使用混合粒度：主图展示业务对象和算法阶段，点击后下钻到函数、源码、输入输出与约束。
- 严格区分三类变化状态：当前故障、候选修正预演、已验证修正结果。
- 使用“统一诊断外壳 + 领域可视化适配器”架构。
- 测试与验证场景由当前任务、算法约束和问题类型动态决定，不使用预设的固定领域清单代替任务匹配。
- 当前实施范围只交付通用声明式领域画布和统一诊断交互；路径规划、数值曲线、状态机等专用适配器在真实使用出现明确需求后再逐步增加。

## 3. 核心原则

### 3.1 领域效果优先

领域可视化必须展示算法实际处理的业务对象或结果：

- 空间或规划任务展示地图、边界、障碍物、姿态、搜索空间、候选路径或几何结果；
- 数值任务展示真实曲线、阈值、异常区间、收敛过程或误差变化；
- 搜索任务展示搜索空间、扩展顺序、代价变化、剪枝与最终路径；
- 状态相关任务展示状态、迁移、触发条件、错误跳转和恢复路径；
- 数据处理任务展示输入样本、中间变换、异常字段、影响传播与输出结果；
- 其他任务展示最能表达其业务对象和正确性约束的视图。

当算法天然具有空间、数值、时间、状态或数据结构语义时，通用流程图只能作为辅助导航，不能代替主领域效果图。

### 3.2 先理解，后选择图形

技能不能仅根据目录名或函数名选择模板。生成可视化前必须回答：

- 当前函数或算法的业务目的是什么；
- 输入、核心处理与输出是什么；
- 用户需要直接观察的业务对象是什么；
- 哪些约束决定结果是否正确；
- 当前问题与哪个对象、区域或阶段关联；
- 当前证据能支持展示哪些真实数据。

### 3.3 证据边界不可被动画掩盖

动画和交互只负责解释证据，不得制造证据。候选方案的预测画面必须明确标记为“概念预演”或“尚未验证”，不能显示成已经发生的修正结果。

## 4. 总体架构

```text
当天对话、Agent 汇报、源码、测试和运行证据
                       │
                       ▼
                任务与算法理解
                       │
                       ▼
            Algorithm Visualization Brief
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
   领域适配器选择             问题诊断关系构建
          │                         │
          └────────────┬────────────┘
                       ▼
        领域主视图 + 统一诊断叠加层
                       │
                       ▼
            Markdown / 交互式 HTML
                       │
                       ▼
       任务匹配验证与证据一致性检查
```

架构由五个逻辑组件组成。

### 4.1 任务与算法理解器

这是写入 `SKILL.md` 的 Agent 工作流程，不是只依赖关键词的确定性分类器。它负责：

1. 从当天证据中识别真正相关的函数、算法和业务任务；
2. 合并主 Agent 与子 Agent 的成果、问题、原因、验证和遗留事项；
3. 确定算法输入、输出、处理阶段、正确性约束和可观察对象；
4. 区分实际数据、源码静态重建、对话结论与方案推演；
5. 生成内部使用的可视化说明。

### 4.2 Algorithm Visualization Brief

可视化说明是技能内部生成的结构化事实，不要求用户手工填写。至少包含：

- 算法标识、名称、目的和领域语义；
- 输入、输出、处理阶段与关键约束；
- 适合的主视图类型和选择理由；
- 可用的真实样本、运行数据及其来源；
- 可视化对象与源码函数之间的关联；
- 问题、影响、修正和预期结果关联到哪些图形对象；
- 当前视图属于实际观测、静态重建、概念预演还是已验证结果。

### 4.3 领域可视化适配器

适配器负责把统一说明转换成领域主视图。适配器是可扩展能力，不是固定领域白名单。

当前版本提供可组合的声明式图元：

- 点、线、折线、曲线、区域、坐标轴和阈值；
- 节点、边、树、图和搜索空间；
- 状态、迁移、触发条件和时间线；
- 网格、边界、障碍物、姿态和空间对象；
- 输入输出样本、字段、数据块和转换关系；
- 标注、告警、影响范围和证据引用。

当前版本由 Agent 根据可视化说明组合图元，形成符合任务语义的视图；适配器注册表只保留扩展接口。路径规划、数值曲线、状态机等专用适配器不属于本轮实施范围。若证据不足以形成可信领域视图，必须明确显示缺失信息，不得退化为伪装成实际效果的通用图。

### 4.4 统一诊断叠加层

所有领域视图共享相同的诊断交互协议。每个问题通过稳定问题 ID 和目标对象 ID 关联到主视图。

点击异常对象后必须展示：

- 目前状况；
- 正常预期；
- 出错位置；
- 出错原因或待验证假设；
- 影响传播路径；
- 会导致的结果；
- 纠正方案及步骤；
- 纠正后的预期结果；
- 实施和验证状态；
- 函数、源码、测试和证据等级。

### 4.5 验证器

验证器继续检查 Markdown 与 HTML 的事实一致性和离线自包含性，并新增领域视图约束：

- 问题引用的算法、阶段和可视化对象必须存在；
- 实际数值或几何结果必须具有证据引用；
- 候选预演不能被标记成已验证结果；
- 修正前后比较必须具有相同场景、单位和比较条件；
- 每个可交互问题必须具有原因、影响、方案和预期结果；
- 所有视图必须具有证据状态和必要的“概念示意”标签。

## 5. 报告事实结构扩展

现有 `achievements`、`issues`、`validations`、`next_steps` 和 `sources` 保持兼容，新增顶层 `algorithm_views`。

```json
{
  "algorithm_views": [
    {
      "id": "planner-main",
      "name": "泊车路径规划",
      "purpose": "从起始姿态生成满足碰撞和运动学约束的可执行轨迹。",
      "domain": "spatial-planning",
      "adapter": "spatial-scene",
      "evidence_state": "actual",
      "inputs": [],
      "outputs": [],
      "constraints": [],
      "stages": [],
      "scene": {},
      "source_refs": []
    }
  ]
}
```

`algorithm_views[].scene` 使用声明式数据，不直接嵌入任意脚本。具体适配器解释该字段并渲染 SVG、Canvas 或 DOM 图形。

每个 `issue` 新增：

- `algorithm_view_id`：关联的算法视图；
- `target_ids`：主视图中需要高亮的对象；
- `effect_target_ids`：影响传播涉及的对象；
- `solution_preview`：候选修正会改变的对象和预期状态；
- `verified_result`：存在真实修正验证时的结果引用。

旧报告缺少 `algorithm_views` 时仍可使用现有问题诊断页面，不得导致更新失败。

## 6. 页面交互结构

### 6.1 页面区域

```text
┌──────────────────────────────────────────────────────────┐
│ 算法选择器 / 问题选择器 / 证据状态                       │
├───────────┬──────────────────────────┬───────────────────┤
│ 查看模式  │      领域效果主画面       │   对象诊断卡      │
│           │                          │                   │
│ 正常机制  │ 路径、曲线、状态、搜索树  │ 目前状况          │
│ 当前问题  │ 或其他任务匹配视图        │ 原因与影响         │
│ 修正预演  │                          │ 方案与预期         │
│ 验证结果  │                          │ 源码与测试证据     │
├───────────┴──────────────────────────┴───────────────────┤
│ 算法阶段导航 / 方案步骤 / 验证门 / 下一步                │
└──────────────────────────────────────────────────────────┘
```

### 6.2 四种查看模式

1. **正常机制**：展示算法原本的输入、处理、输出和正确性约束。
2. **当前问题**：在正常底图上高亮异常对象、实际状态和影响传播。
3. **修正预演**：逐步展示候选方案会改变什么，并明确标记尚未验证。
4. **验证结果**：仅在存在修正后测试或运行证据时启用，展示真实结果及证据。

### 6.3 一次完整交互

```text
选择算法
  → 查看正常领域效果
  → 选择问题或点击异常对象
  → 播放原因与影响传播
  → 点击纠正步骤查看候选变化
  → 对比当前状态与预期状态
  → 有验证证据时切换到已验证结果
  → 下钻源码、测试和证据引用
```

## 7. 任务匹配验证

报告生成时不得运行或引用与当前任务无关的固定测试场景。技能必须动态构建验证清单：

1. 识别当前任务和算法目标；
2. 从源码、设计、测试和运行证据中提取正确性约束；
3. 确定当前问题的复现条件和失败判据；
4. 查找与这些条件直接匹配的现有测试或运行证据；
5. 只在安全且成本合理时运行针对性验证；
6. 将已运行、未运行和仍缺失的验证严格分开；
7. 为没有匹配测试的结论生成任务专属验证建议。

示例：泊车规划任务可以匹配碰撞、安全间距、可达性、曲率和车辆运动学约束；并发缓存任务可以匹配竞争、重复写入、超时和一致性约束。这些示例用于说明匹配原则，不是固定覆盖列表。

## 8. 证据状态与视觉语义

| 状态 | 含义 | 页面表达 |
| --- | --- | --- |
| 实际观测 | 来自测试、运行或可复核数据 | 实线、明确数值和证据引用 |
| 静态重建 | 根据源码控制流或公式重建 | 静态分析标签，不声称运行复现 |
| 概念预演 | 候选方案的预测效果 | 虚线或半透明，并显示尚未验证 |
| 已验证结果 | 修正后经过匹配测试确认 | 已验证标签和测试证据 |
| 结论冲突 | 多个可信证据不一致 | 同时保留视图与结论，显示冲突状态 |

颜色不能成为唯一状态区分方式；同时使用文字、线型、图标和可访问标签。

## 9. 降级与错误处理

- 当天没有函数或算法工作：生成普通开发日报，不强制创建算法视图。
- 找到算法但缺少运行数据：允许静态重建或概念示意，并明确证据状态。
- 无法确认算法业务目的：列出缺失证据，不生成伪领域效果。
- 多个算法同时出现：提供算法选择器，分别维护视图与问题关联。
- 数据量过大：允许抽样、聚合或简化，页面必须说明简化规则并保留原始证据位置。
- 适配器无法渲染某个图元：显示可读的局部错误卡，其他报告内容仍可访问。
- 修正方案没有验证：禁用“已验证结果”模式，而不是复制候选预演内容。

## 10. 文件和组件变化

预计修改：

- `SKILL.md`：增加任务理解、可视化说明、领域适配器选择和任务匹配验证流程。
- `references/report-schema.md`：增加 `algorithm_views`、问题对象关联和证据状态字段。
- `scripts/prepare_report.py`：验证新结构、保持旧结构兼容、向模板注入领域视图数据。
- `assets/interactive-report-template.html`：重构为统一诊断外壳和适配器注册表。
- `scripts/test_prepare_report.py`：增加结构、适配器协议、交互和证据边界测试。

可以按复杂度把适配器拆入 `assets/visual-adapters/`，但最终报告仍必须是一个无外部依赖的 HTML 文件。

## 11. 验收标准

- 技能先识别任务目的和业务对象，再选择可视化，不按固定目录名盲选。
- 路径、数值、状态、搜索或其他算法能够呈现各自真实领域效果，而不是统一文字流程框。
- 点击图中异常对象可查看目前状况、原因、后果、纠正方案和预期结果。
- 正常机制、当前问题、候选预演和已验证结果可以明确切换。
- 候选方案在没有验证证据时不会显示为已修复。
- 问题、图形对象、源码和测试证据能够互相追踪。
- 验证清单根据当前任务动态生成，不以固定领域测试替代任务匹配。
- 无法形成可信领域视图时诚实降级，不编造运行数据。
- Markdown 与 HTML 保持事实一致，HTML 离线可用并支持键盘和移动端。
- 旧日报数据仍可生成和更新。

## 12. 非目标

- 不在生成日报时自动修改业务代码。
- 不为了可视化而运行昂贵、破坏性或未经授权的测试。
- 不要求每种算法预先拥有专用硬编码模板。
- 不把动画效果当作算法正确性的证明。
- 不自动暂存、提交或推送 Git 变更。
