Report Expert

报告专家 v2.0

将调研内容生成 HTML 报告，部署到 Cloudflare Pages 小站，自动检查修复 HTML 结构问题，验证线上正确性。支持多种输入格式（HTML/Markdown/URL/纯文本）自动适配，CF双向同步保证本地与线上一致。

---

前置配置

TOOLS.md 中添加：

### Report Expert 技能配置
- `CLOUDFLARE_API_TOKEN=cfat_xxxx`    # 必需
- `REPORT_CF_PROJECT=xuedi`           # 必需，CF Pages 项目名
- `REPORT_SITE_NAME=雪地`              # 必需，小站显示名
- `REPORT_CUSTOM_DOMAIN=xue.mei.pub`  # 可选，不填用 *.pages.dev

---

五模块架构

依赖：adapter → report → html_lint → page → config，site → html_lint → page → config → remote_deploy，verify → html_lint → config

html_lint 是 report/site 的共享守门人——produce 和 update_pages 都用同一套管线。

---

输入适配

支持四种输入类型，自动检测转换：

• HTML — 直接使用，无需转换
• Markdown — markdown 库渲染（表格、代码块、目录）
• URL — curl 抓取网页，提取 body 清洗（移除 script/nav/sidebar）
• 纯文本 — 按段落包裹 `` 标签

检测逻辑：看扩展名 → 看 URL 前缀 → 读前 2000 字符判断内容特征。标题从 Markdown 首行标题、HTML `` 标签、URL 页面标题自动提取。

---

HTML 结构检查修复（核心能力）

lint+fix 管线保证产出 HTML 结构完整。每条规则同时具备 check+fix，发现问题就修。流程：检查 → 修复 → 确认（最多 3 轮）。

规则清单

新增规则只需定义 LintRule 子类，注册到 default_pipeline()。

---

工作流程

一键部署（自动适配输入类型）

uv run deploy.py deploy   --title "标题" --desc "描述"
# source 支持: .html / .md / URL / 纯文本文件

分步操作

uv run deploy.py produce   --title "标题"  # 适配+生产到 dist
uv run deploy.py publish                                    # 部署到 CF
uv run deploy.py sync                                       # 从 CF 线上同步缺失文件到 dist
uv run deploy.py verify                                     # 验证线上结果

维护命令

uv run deploy.py add  --title T --desc D --category C [--url U]
uv run deploy.py remove 
uv run deploy.py rebuild_index
uv run deploy.py update              # 用最新模板+lint 重新包裹所有页面
uv run deploy.py check               # 检查配置

---

CF双向同步

sync_from_cf() 从线上站点拉取缺失文件到 dist，保证本地与线上一致：

1. 拉取线上 index.json 获取页面列表
2. 对比 dist 中缺失的文件逐个下载
3. 合并线上索引到本地索引

应用场景：dist 被意外清理后恢复、新环境初始化、多人协作同步。

---

索引安全

三层保障防止 dist 被清理时丢失：

1. dist/index.json — 正常路径
2. 技能根目录 index.json — 每次写索引时同步备份
3. 线上 index.json — 终极恢复源

load_index_safe() 按优先级依次恢复。

---

验证流程

部署后 agent 用 web_fetch 逐项验证。验证清单从 lint 管线 online stage 规则自动生成。失败 → diagnose → 修复 → publish → 再验证，最多 3 次。

---

文件清单

deploy.py              — CLI 入口
lib/adapter.py         — 输入适配（HTML/Markdown/URL/纯文本 → HTML）
lib/config.py          — 配置加载 + 索引读写 + 分类常量
lib/html_lint.py       — lint+fix 管线（LintRule + LintPipeline + 12 规则）
lib/page.py            — 页面 HTML 生成（纯模板渲染）
lib/report.py          — 报告生产（提取 → lint → 图片 → 生成 → 写入）
lib/site.py            — 小站维护（索引 + 资源 + CF双向同步 + 更新 + 部署）
lib/remote_deploy.py   — CF Pages wrangler 调用
lib/verify.py          — 验证修复（URL 清单 + 诊断）
references/            — 详细规范
templates/base.css     — 设计系统
templates/index.html   — 首页模板
scripts/main.js        — 交互系统