更新: 77 个文件 - 2026-03-17 00:30:01

2026-03-17 00:30:01 -07:00
--- a/docs/frontend-dashboard-design.md
+++ b/docs/frontend-dashboard-design.md
@@ -0,0 +1,309 @@
+# 本地前端工作台设计文档
+
+> `LAB ONLY` | `AUTHORIZED TARGETS ONLY`
+
+## 1. 设计目标
+
+本地 dashboard 要从“简单索引页”升级成“完整的授权攻防实证工作台”。它需要同时满足三类使用场景：
+
+1. 运行中观察
+   - 看当前 run 进度
+   - 看失败原因和阻塞点
+   - 实时打开日志和证据
+2. 复盘分析
+   - 查看 timeline、思路、利用路径、来源与修复主题
+   - 对比真实版本与 synthetic 复现差异
+3. 审阅归档
+   - 从一个前端入口点进 `report.md`, `report.html`, `run.json`, 原始日志和截图
+
+## 2. 页面定位
+
+### 2.1 页面名称
+
+- 页面名称：`Authorized Lab Dashboard`
+- 页面语境：本地静态前端 + 本地文件 JSON 数据源
+- 非目标：在线 SaaS、多用户后端、生产管理台
+
+### 2.2 核心原则
+
+- 所有展示都围绕授权目标
+- 失败信息不能被隐藏在深层页面里
+- 信息密度高，但必须可折叠、可筛选、可逐层展开
+- 日志与原始 JSON 必须能直接预览
+- 页面视觉应更生动，但不能牺牲扫描效率
+
+## 3. 信息架构
+
+```mermaid
+flowchart LR
+  A["Hero + Global Status"] --> B["Sidebar Filters"]
+  A --> C["Run Queue List"]
+  C --> D["Run Detail Hero"]
+  D --> E["Progress Timeline"]
+  D --> F["Attack Plan & Reasoning"]
+  D --> G["Evidence Explorer"]
+  D --> H["Live Log Viewer"]
+  D --> I["Sources & Fix Topics"]
+  D --> J["Raw JSON Panels"]
+```
+
+## 4. 页面布局
+
+### 4.1 顶部 Hero
+
+必须展示：
+
+- 页面名称
+- 授权实验语境说明
+- 刷新按钮
+- 自动刷新开关
+- 当前同步状态
+- 核心 metric cards
+
+视觉要求：
+
+- 不能是纯白表格页
+- 需要有分层背景、渐变光晕、轻微动态氛围
+- 顶栏 sticky，滚动时仍可看到刷新和状态
+
+### 4.2 左侧侧栏
+
+包含四块：
+
+- Filters
+  - 搜索
+  - system filter
+  - status filter
+  - profile filter
+- Systems
+  - 系统覆盖度
+  - browser evidence 覆盖
+  - latest update
+- Recent Failures
+  - 最近 blocker
+  - status
+  - 原因摘要
+- Run Queue View
+  - 最近 run 卡片列表
+  - 可选中并切换到 detail panel
+
+### 4.3 右侧 Detail Workspace
+
+必须包含：
+
+- Run Hero
+  - advisory 标题
+  - system / profile / artifact / verification 状态
+  - report / bundle / markdown 入口
+- Progress Timeline
+  - 每一步的时间、状态、说明
+- Attack Plan & Reasoning
+  - success criteria
+  - seed / attack notes
+  - failure reason
+  - 当前 blocker
+- Evidence Explorer
+  - reports
+  - compose
+  - browser evidence
+  - request logs
+  - container logs
+- Live Log Viewer
+  - 预览 text/json/html/image
+  - refresh preview
+  - open artifact
+- Sources & Fix Topics
+  - official source
+  - secondary sources
+  - aliases
+  - secure code topics
+- Raw JSON
+  - run JSON
+  - advisory JSON
+  - profile JSON
+
+## 5. 交互要求
+
+### 5.1 折叠 / 展开
+
+所有 detail 分区都应支持折叠：
+
+- Progress Timeline
+- Attack Plan & Reasoning
+- Evidence Explorer
+- Live Log Viewer
+- Sources & Fix Topics
+- Raw JSON sections
+
+折叠要求：
+
+- 默认展开常用分区
+- 次级原始数据可以默认收起
+- 折叠状态视觉要清晰，不靠小箭头弱提示
+
+### 5.2 Run 切换
+
+- 点击左侧 run card 后，右侧 detail panel 即时刷新
+- 当前选中项要有强视觉区别
+- URL hash 应保留 `#run=<id>`，方便直接打开特定 run
+
+### 5.3 Artifact 预览
+
+点击 artifact button 后：
+
+- JSON 自动格式化
+- 日志文件以 `<pre>` 方式显示
+- 图片以内联方式展示
+- HTML 报告可 iframe 预览或新窗口打开
+
+### 5.4 自动刷新
+
+- 默认每 5 秒刷新一次 dashboard JSON
+- 用户可以关闭自动刷新
+- 当前正在查看的 artifact 在自动刷新开启时应支持重新抓取
+
+### 5.5 失败原因高亮
+
+对于 `blocked-*` 和 `triage-manual`：
+
+- 顶部 hero 要显示状态 pill
+- reasoning 面板要显示 failure callout
+- 左侧 Recent Failures 要保留最近失败摘要
+
+## 6. 展示字段清单
+
+### 6.1 Hero 区
+
+- run_id
+- advisory_id
+- advisory title
+- verification_status
+- verification_mode
+- artifact_mode
+- system_id
+- repro_profile_id
+- finished_at
+
+### 6.2 Timeline 区
+
+- `timeline[].at`
+- `timeline[].step`
+- `timeline[].status`
+- `timeline[].detail`
+
+### 6.3 Reasoning 区
+
+- advisory summary
+- profile seed messages
+- profile attack messages
+- profile success criteria
+- blocked reason
+
+### 6.4 Sources 区
+
+- official_source_url
+- secondary_source_urls
+- aliases
+- secure_code_topics
+
+### 6.5 Evidence 区
+
+- report.html
+- report.md
+- timeline.mmd
+- bundle json
+- compose.yaml
+- browser screenshots / DOM / console / network
+- request logs
+- container logs
+
+## 7. 动效与视觉要求
+
+### 7.1 必须有的视觉增强
+
+- 顶部背景渐变和环境光
+- status pill 发光色彩区分
+- 卡片 hover 浮起
+- sticky hero
+- 折叠面板开合层次
+- gallery 缩略图点击查看
+
+### 7.2 推荐但必须受控
+
+- 状态小圆点 pulse
+- 背景网格或轻微数据面纹理
+- 面板玻璃感和浅透视阴影
+
+### 7.3 不允许
+
+- 花哨但影响可读性的动画
+- 大面积纯装饰 3D 效果
+- 自动播放噪音式动效
+- 让日志区难以复制文本的视觉处理
+
+## 8. 实时日志与细节查看要求
+
+### 8.1 日志查看器
+
+日志查看器必须支持：
+
+- 选中文件后即刻预览
+- JSON 格式化
+- text/json/html/image 四类预览
+- 打开原文件
+- 在自动刷新开启时重新抓取当前文件
+
+### 8.2 重点要看的日志
+
+- compose / environment 文件
+- baseline / attack / browser json
+- container logs
+- request logs
+- timeline / bundle
+
+### 8.3 失败排查导向
+
+失败时应优先展示：
+
+- `blocked_reason`
+- 当前 step
+- 上一个完成 step
+- 当前可打开的日志 / 报告 / run bundle
+- 对应 advisory 来源与 profile success criteria
+
+## 9. 数据源契约
+
+前端依赖的本地 JSON/文件源：
+
+- `summary.json`
+- `runs.json`
+- `systems.json`
+- `advisories.json`
+- `profiles.json`
+- `runs/<run-id>/report.html`
+- `runs/<run-id>/report.md`
+- `runs/<run-id>/run.json`
+- `runs/<run-id>/logs/*`
+- `runs/<run-id>/assets/*`
+
+前端不直接写这些数据，只读取并展示。
+
+## 10. 落地约束
+
+- 保持静态前端，不引入长期运行后端
+- 本地 `serve-dashboard` 即可查看
+- 对于正在跑的 case，前端通过轮询读取新 JSON 实现“近实时”
+- 不依赖第三方 CDN UI 库
+- 优先使用原生 HTML/CSS/JS，可长期维护
+
+## 11. 验收标准
+
+页面完成后，应满足：
+
+- 能从 run list 切换到 detail panel
+- 能折叠与展开各信息区
+- 能打开并预览 JSON / text / image / html artifact
+- 能看到失败原因、思路、来源、修复主题
+- 能筛选 system / status / profile
+- 能在自动刷新开启时重新载入 dashboard 数据
+- 页面视觉比“普通表格页”更生动，但仍适合高密度阅读