10. HTML 报告产出
除了将查询结果导出为 CSV / Excel 等格式，Lantide Data 还支持将 Report 文件一键转换为独立 HTML 报告，直接在浏览器中呈现美观的数据分析成果。
10.1 什么是 HTML Report
HTML Report 是基于 Report 类型的 Markdown 文件产出的独立 HTML 文件。AI Agent 会读取 Report 内容，根据你选择的版面与样式设置，生成一份包含完整排版的 HTML 报告。产出的 .html 文件与原始 .md 文件存放在同一目录下，可直接以浏览器打开。
10.2 产出 HTML Report
- 打开一个 Report 类型的 Markdown 标签页。
- 在标签页工具列中，点击 HTML Report 下拉按钮（地球图标）。
- 选择 Generate Report。
- 系统会先自动保存当前文件，然后弹出报告配置对话框。
- 调整配置选项后，点击 Generate。
- AI 面板会自动展开，Agent 开始根据 Report 内容与你的配置生成 HTML。
- 生成完成后，工具列的 Open Report 按钮会自动启用。
10.3 报告配置选项
报告配置对话框提供以下选项，让你控制 HTML 报告的呈现方式。桌面版采双栏版面：左栏为版面与样式选项，右栏上方为 Use CDN 与 Custom Script 开关、下方为 Other Requirements 长文输入；手机版维持单栏堆叠，Cancel / Generate 固定于底部。
| 选项 | 可选值 | 说明 |
|---|---|---|
| Layout Mode | Standard / Presentation | Standard 为可卷动的数据报告页面；Presentation 为投影片式全荧幕展示（左栏） |
| Style Preset | Professional / Executive / Consulting | 分别适合正式报告、KPI 仪表板风格、策略谘询框架风格（左栏） |
| Color Scheme | Light / Dark / Corporate Blue / Neutral | 报告的整体配色方案（左栏） |
| Use CDN | 开 / 关 | Standard + 开启一定含受管理的 Chart.js（standard-chartjs）；Presentation + 开启用 reveal.js；关闭时产出离线 HTML |
| Custom Script | 开 / 关 | 允许自订 JavaScript（D3、Plotly 等）。每次 Generate 都须风险确认；Presentation 不可用。工具列与 Quick Edit 会显示黄色标记 |
| Other Requirements | 自由文字（上限 2000 字） | 位于开关下方；输入 / 可插入 User Skill 片段 |
提示： Presentation + CDN 使用 reveal.js；关闭 CDN 则是纯 CSS scroll-snap。Standard + CDN 一定含 Chart.js。Custom Script 不可与 Presentation 并用。
10.4 查看与导出 HTML Report
产出完成后，有三种方式查看报告：
- 工具列： 点击 HTML Report 下拉中的 Open Report，系统会以默认浏览器打开 HTML 文件。
- 工具列导出： 点击 Export HTML Report，透过系统「另存」对话框将项目内的
.html复制到本机任意路径；成功后会在 Finder／文件总管中定位该文件。仅桌面版（Electron）支持；导出的是当下磁碟上的 HTML 快照（含 CDN 的报告离线打开仍需网络）。 - AI 对话中： Agent 完成生成后，对话中会出现一个 「Open HTML Report」 按钮，点击即可在浏览器中打开。
- 侧边栏快捷按钮： 在 Projects 区块中，已产出 HTML report 的 Report 文件旁会显示一个 Globe 图标按钮，点击即可直接在浏览器中打开对应的 HTML 报告，无需先打开标签页。
10.5 重新产出
如果你修改了 Report 内容，或想调整配置重新生成：
- 点击工具列的 HTML Report 下拉 → Re-generate Report。
- 系统会提示确认是否覆盖现有的 HTML 文件。
- 确认后重新进入配置对话框，流程与首次产出相同。
Re-generate 与区块契约： 每次 Re-generate 会覆写整份 .html 并建立全新的区块编号（text_id）。若你在旧对话中让 Agent 修改某个 text_id，Regenerate 后该编号可能已失效，需请 Agent 重新读取报告（read_html_text）。
10.5.1 事后修改 HTML（AI 对话）
产出后可在 Project 已聚焦 且已存在对应 .html 档（或你正透过工具列 Generate / Re-generate 触发的 html_report 任务）时，请 Agent 微调报告，无需重新 Generate。
- Report 标签页：在该 Report
.md标签页上直接发修改请求，Agent 会自动使用区块/样式工具。 - 其他标签页（SQL、聊天等）：Agent 会先呼叫
activate_html_editing解锁编辑工具，再进行 patch；若项目内有多份 report 皆有 HTML，请在讯息中指明要改哪一份（如02_report.md）。 - 新对话 / 新一则讯息：与统计分析启动器类似，每轮对话需重新 activate 或回到 Report 标签页，不会跨 turn 记住编辑模式。
- 仅有
.md、磁碟尚无.html时，Agent 仅能使用create_html_report建立报告，不会暴露区块/样式 patch 工具。
| 要改什么 | Agent 做法 |
|---|---|
| 段落文字、表格、卡片结构 | 区块工具：read_html_text → get_html_chunk_by_id → patch_html_chunk_by_id |
Chart.js 图表（standard-chartjs 报告） |
get_html_chunk_by_id 读取 data-chart-spec → 修改 JSON → patch_html_chunk_by_id；完成后请重新 Open Report（或浏览器重新整理）才会重绘图表 |
配色、.card 外观、:root 变数等全域 CSS |
样式工具：get_html_styles → patch_html_styles（改 <style id="report-styles">） |
| Custom Script 的 JavaScript | get_html_scripts → patch_html_scripts，以 data-script-id 增删改；不要把 <script> 写入区块，系统 Chart.js 不可改 |
建议先改样式、再改区块 HTML，避免新建 class 却没有对应 CSS。Chart.js 报告的图表颜色会从 :root 的 --primary / --accent 自动套用（若 spec 未指定色盘）。
- 无契约的旧 HTML（没有
data-report-contract="1"）：区块与样式工具皆不可用，请 Re-generate。 - 有契约但缺少
#report-styles（早期 chunk 版产物）：区块工具仍可用；样式工具会失败，请 Re-generate 以启用样式编辑。 - 整体换版面、CDN／Custom Script 设置或旧契约：请用 Re-generate，不要只靠 patch。
10.5.2 Quick Edit HTML（手动区块编辑）
在已产出 HTML 报告后，可从 Report 标签页工具列 HTML Report → Quick Edit HTML 打开编辑对话框，无需透过 AI 对话即可修改单一区块内容。
操作流程：
- 左侧以卡片列出各区块（
desc、kind、文字摘要）；点击一张卡片。 - 右侧 Monaco 编辑该区块的 inner HTML（不含外层
data-text-id标签）。 - 点 Save 或按 Cmd/Ctrl+S 写入磁碟。保存成功后，编辑器会自动同步为服务端规范化后的 HTML（空白、标签格式可能与你输入的略有差异，属正常行为）。
- 可点 Open Live Preview 在默认浏览器打开本机预览页；Save 成功后预览页会在约 2 秒内自动重新加载（需保持该标签页打开）。
与 AI 编辑的差异：
| 项目 | Quick Edit | AI patch_html_chunk_by_id |
|---|---|---|
| 并发保护 | 保存时须带 content_hash；过期会 409，请重新加载区块 |
不检查 hash，可能覆写你刚手改的内容 |
| Agent 执行中 | 无法打开 Quick Edit；若对话框已开则暂停 Save | 可继续执行 |
| 全域 CSS | 本对话框不编辑；请用 AI patch_html_styles 或 Re-generate |
支持 patch_html_styles |
Live Preview 与安全： 预览使用独立的本机 origin，并以绑定该报告的短效 capability token 开启，不与主 API 共用 origin。Quick Edit 会标示 Custom Script 报告并提醒 runtime 可能盖住画面；请勿将主 API 暴露到公网。
Re-generate 会覆盖手动修改并重置所有 text_id。
10.6 按钮停用条件
| 情况 | 影响的按钮 | 提示 |
|---|---|---|
| AI Agent 正在执行中 | Generate / Re-generate、Open Report、Quick Edit HTML | Agent is busy |
| Plan 处于 Executing 状态 | Generate / Re-generate | Plan is executing |
| 尚未产出过 HTML 文件 | Open Report、Export HTML Report、Quick Edit HTML | 无可打开／编辑的文件 |
注意： HTML Report 功能仅适用于 Report 类型的 Markdown 文件，不适用于 Plan。
[图片] 报告配置对话框与 HTML Report 工具列按钮
设计说明： HTML 交付物定位见 Agent 时代的数据分析工作流 §四；契约与工具见 AI Agent 架构 §七。