# 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 变更。