14 KiB
Daily Summary Job 领域算法可视化升级设计
1. 目标
升级个人技能 daily-summary-job，使开发日报不只用文字和通用流程框陈述工作，而是先理解当天函数或算法的真实业务目标，再生成与该任务匹配的领域可视化。
页面必须让读者通过点击直接理解：
- 原函数或算法解决什么问题、正常情况下如何工作；
- 当前问题发生在哪个对象、区域或算法阶段；
- 出错原因是什么，或当前有哪些待验证假设；
- 问题会沿什么路径传播并导致什么结果；
- 纠正方案会改变哪些对象、约束或处理步骤；
- 纠正后的预期效果是什么；
- 哪些内容是实际观测、静态分析、概念预演或已验证结果。
路径规划只是示例。技能必须根据当前任务选择合适的可视化，而不能把所有算法都硬编码成轨迹图或普通流程图。
2. 已确认的设计决策
- 使用混合生成策略：涉及函数或算法时自动生成基础领域视图；出现复杂问题时再生成深入诊断和修正前后对比。
- 使用“双层算法地图”：正常算法效果作为稳定底图，问题与修正方案作为可切换叠加层。
- 使用混合粒度：主图展示业务对象和算法阶段，点击后下钻到函数、源码、输入输出与约束。
- 严格区分三类变化状态：当前故障、候选修正预演、已验证修正结果。
- 使用“统一诊断外壳 + 领域可视化适配器”架构。
- 测试与验证场景由当前任务、算法约束和问题类型动态决定，不使用预设的固定领域清单代替任务匹配。
- 当前实施范围只交付通用声明式领域画布和统一诊断交互；路径规划、数值曲线、状态机等专用适配器在真实使用出现明确需求后再逐步增加。
3. 核心原则
3.1 领域效果优先
领域可视化必须展示算法实际处理的业务对象或结果：
- 空间或规划任务展示地图、边界、障碍物、姿态、搜索空间、候选路径或几何结果；
- 数值任务展示真实曲线、阈值、异常区间、收敛过程或误差变化；
- 搜索任务展示搜索空间、扩展顺序、代价变化、剪枝与最终路径；
- 状态相关任务展示状态、迁移、触发条件、错误跳转和恢复路径；
- 数据处理任务展示输入样本、中间变换、异常字段、影响传播与输出结果；
- 其他任务展示最能表达其业务对象和正确性约束的视图。
当算法天然具有空间、数值、时间、状态或数据结构语义时，通用流程图只能作为辅助导航，不能代替主领域效果图。
3.2 先理解，后选择图形
技能不能仅根据目录名或函数名选择模板。生成可视化前必须回答：
- 当前函数或算法的业务目的是什么；
- 输入、核心处理与输出是什么；
- 用户需要直接观察的业务对象是什么；
- 哪些约束决定结果是否正确；
- 当前问题与哪个对象、区域或阶段关联；
- 当前证据能支持展示哪些真实数据。
3.3 证据边界不可被动画掩盖
动画和交互只负责解释证据，不得制造证据。候选方案的预测画面必须明确标记为“概念预演”或“尚未验证”，不能显示成已经发生的修正结果。
4. 总体架构
当天对话、Agent 汇报、源码、测试和运行证据
│
▼
任务与算法理解
│
▼
Algorithm Visualization Brief
│
┌────────────┴────────────┐
▼ ▼
领域适配器选择 问题诊断关系构建
│ │
└────────────┬────────────┘
▼
领域主视图 + 统一诊断叠加层
│
▼
Markdown / 交互式 HTML
│
▼
任务匹配验证与证据一致性检查
架构由五个逻辑组件组成。
4.1 任务与算法理解器
这是写入 SKILL.md 的 Agent 工作流程，不是只依赖关键词的确定性分类器。它负责：
- 从当天证据中识别真正相关的函数、算法和业务任务；
- 合并主 Agent 与子 Agent 的成果、问题、原因、验证和遗留事项；
- 确定算法输入、输出、处理阶段、正确性约束和可观察对象；
- 区分实际数据、源码静态重建、对话结论与方案推演；
- 生成内部使用的可视化说明。
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。
{
"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 页面区域
┌──────────────────────────────────────────────────────────┐
│ 算法选择器 / 问题选择器 / 证据状态 │
├───────────┬──────────────────────────┬───────────────────┤
│ 查看模式 │ 领域效果主画面 │ 对象诊断卡 │
│ │ │ │
│ 正常机制 │ 路径、曲线、状态、搜索树 │ 目前状况 │
│ 当前问题 │ 或其他任务匹配视图 │ 原因与影响 │
│ 修正预演 │ │ 方案与预期 │
│ 验证结果 │ │ 源码与测试证据 │
├───────────┴──────────────────────────┴───────────────────┤
│ 算法阶段导航 / 方案步骤 / 验证门 / 下一步 │
└──────────────────────────────────────────────────────────┘
6.2 四种查看模式
- 正常机制：展示算法原本的输入、处理、输出和正确性约束。
- 当前问题：在正常底图上高亮异常对象、实际状态和影响传播。
- 修正预演：逐步展示候选方案会改变什么，并明确标记尚未验证。
- 验证结果：仅在存在修正后测试或运行证据时启用，展示真实结果及证据。
6.3 一次完整交互
选择算法
→ 查看正常领域效果
→ 选择问题或点击异常对象
→ 播放原因与影响传播
→ 点击纠正步骤查看候选变化
→ 对比当前状态与预期状态
→ 有验证证据时切换到已验证结果
→ 下钻源码、测试和证据引用
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 变更。