mcpField
P
publish-html-report

publish-html-report

github.com/loxosceles-dev文档处理60 次安装
代码仓库

关于 publish-html-report

publish-html-report 是一套参考技能，用于将可视化报告制作为独立 HTML，并通过 secret GitHub gist 发布预览。它面向需要超越 Markdown 图表表现力、并希望在评审中分享临时报告的开发者。

主要功能

  1. 01单文件 HTML 报告模板
  2. 02Mermaid 与手工图表技巧
  3. 03secret gist 发布流程
  4. 04浏览器预览链接生成
  5. 05Markdown 备选与清理指引

适用场景

  1. 01展示依赖关系或数据流
  2. 02对比变更前后的架构
  3. 03分享测试覆盖率或性能报告
  4. 04在 Pull Request 中发布临时可视化报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/loxosceles-dev/dev-skills --skill publish-html-report

安装后在 Claude Code 中输入/publish-html-report确认已加载。

详细介绍

发布 HTML 报告

这是一个参考模式。 借鉴其中的方法，并根据你的情境进行调整——不要照搬。

问题：Markdown 对丰富的可视化支持有限——依赖关系图、前后架构图、分层剖面图和交互式 Mermaid 图表在 GitHub Markdown 中显示效果不佳（甚至完全无法显示）。

解决方案：使用 Tailwind + Mermaid CDN 生成独立的 HTML 文件，将其发布为私密 GitHub gist，并通过 htmlpreview.github.io 构造可查看的 URL。

模式

工作流：

Generate HTML → Write to docs/  → Push to branch
                                → Create secret gist
                                → Construct preview URL (htmlpreview.github.io)
                                → Link in PR description

这样做的好处：

  • 私密 gist 不会列出，但可通过原始 URL 公开访问
  • htmlpreview.github.io 会获取并渲染任意原始 GitHub HTML
  • 无需 GitHub Pages、付费计划或托管基础设施

HTML 脚手架

每份报告都是一个独立文件——除 CDN 外不依赖外部资源：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{{Report Title}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>
        <h1 class="text-3xl font-bold">{{Title}}</h1>
        <p class="text-sm text-slate-500">{{date}} · {{repo-name}}</p>
      </header>
      
    </main>
  </body>
</html>

规则：

  • 只允许使用 CDN 脚本：Tailwind 和 Mermaid
  • 不包含应用代码，除 Mermaid 渲染外不添加交互功能
  • 文件必须能在本地正确渲染（open file.html）

图表技巧

混合使用这些技巧——不要让每张图表看起来都一样：

Mermaid——用于图结构关系（调用流程、依赖关系、时序）：

<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[Module] --> B[Dependency]
      B -.-> C[Leaking concern]
  </pre>
</div>

手工构建的 div——当 Mermaid 的布局不合适时使用（质量图、分层剖面图、模块深度对比）：

<div class="relative border rounded p-4">
  <div class="h-8 border-l-4 border-indigo-500 pl-3 flex items-center text-xs">Interface</div>
  <div class="h-32 border-l-4 border-slate-300 pl-3 flex items-center text-xs">Implementation</div>
</div>

内联 SVG——用于定位元素之间的箭头和连接线。

发布工作流

1. 编写报告

将报告放在 docs/reports/<date>-<slug>.html。同时在相同路径下生成 Markdown 备用版本，扩展名为 .md。

2. 创建私密 gist
gh gist create docs/reports/<date>-<slug>.html \
  --desc "<Report Title> — <repo-name> (<date>)"
3. 构造预览 URL
GIST_ID=$(gh gist list --limit 1 | head -1 | awk '{print $1}')
RAW_URL=$(gh api gists/$GIST_ID --jq '.files | to_entries[0].value.raw_url')
echo "https://htmlpreview.github.io/?$RAW_URL"
4. 在 PR 描述中添加链接
📄 **[Report Title — Visual](<HTMLPREVIEW_URL>)** — opens in browser
📄 **[Markdown fallback](docs/reports/<date>-<slug>.md)** — renders on GitHub
5. 清理约定

在合并前，将 docs/reports/ 标记为待删除：

> ⚠️ **CLEANUP**: Delete `docs/reports/` directory before merging.

报告是供审查使用的临时产物，不是永久文档。

集成：架构审查（mattpocock/skills）

与 improve-codebase-architecture skill 配合使用时：

  1. 运行架构分析（探索、识别候选项）
  2. 按照该 skill 的 HTML-REPORT 格式生成 HTML 报告（候选项卡片、前后对比图、建议徽标）
  3. 使用本 skill 的 gist 工作流发布
  4. 创建 PR，附上候选项表格和预览链接
  5. 添加后续工作的多 Agent 工作流说明：
### How to Work on This

1. `/to-prd` — generate PRD from candidates
2. `/to-issues` — one issue per candidate
3. Execute each issue in a separate session
4. `/grill-me` for deeper design decisions

架构以外的使用场景

对于任何适合用 HTML 而非 Markdown 展示的可视化内容，这种模式都适用：

  • 依赖关系图——通过颜色区分健康状况的模块关系
  • 测试覆盖率图——直观展示覆盖率缺口的热力图
  • 性能报告——配有图表的前后耗时对比
  • 迁移进度——直观展示多步骤迁移的状态
  • 数据流图——带有分支逻辑的复杂管道
  • API 范围——接口宽度可视化

根据内容调整脚手架和图表技巧。发布工作流保持不变。

样式指南

  • 采用编辑风格，而非企业仪表盘风格。留出充足的空白。
  • 谨慎使用颜色：一种强调色（emerald/indigo）+ 用红色表示问题 + 用琥珀色表示警告
  • 图表高度约为 320px，以便前后对比图并排显示
  • 示意图标签使用 text-xs uppercase tracking-wider
  • 标题可选用衬线字体（font-serif），并搭配 stone/slate 配色

备用方案

如果 gh gist create 失败（身份验证问题、速率限制）：

  1. 改用纯 Markdown 版本
  2. 附上在本地打开 HTML 的说明：open docs/reports/<file>.html

持续改进

如果开发者纠正了本 skill 本应避免的行为，请提出对此 skill 的具体修订建议，以防止将来再次出现同样的问题。

评论

支持 Markdown