# skill-report-html · 咨询师级 HTML 长页报告工程

> **未来飞马 — 让AI进化提前发生，让AI落地快人一步**

[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](LICENSE)
[![ESM](https://img.shields.io/badge/module-ESM--only-orange.svg)](#快速开始)
[![npm](https://img.shields.io/badge/npm-skill--report--html-blue.svg)](https://www.npmjs.com/package/skill-report-html)

---

## 简介

`skill-report-html` 是一套**咨询师级 HTML 长页报告**的制作方法论与工程规范：从零到发布的完整流程、排版规范与可复用资源库，让 AI 产出的报告具备咨询公司交付物的专业观感。

配合 `skill-storage` 可将成果一键发布为公网链接。

本技能适用于 **FmodeAgent / Hermes Agent** 平台，开发由 **FmodeCode / Claude Code** 执行。

---

## 核心定位

| 维度 | 说明 |
|------|------|
| **解决什么** | 长页报告的**结构与排版质量**：信息层级、视觉节奏、专业观感、发布流程 |
| **不解决什么** | 不生成内容本身、不做数据分析、不做图表计算（内容由分析环节产出） |
| **与通用 HTML 模板的区别** | 面向咨询交付物场景，规范的是**信息架构与版式系统**，而非单页样式 |
| **层级** | 系统级（Infrastructure） |
| **适用平台** | FmodeAgent / Hermes Agent · FmodeCode / Claude Code |

---

## 核心能力 & 交付物

- 📐 **排版规范** —— 字号阶梯、间距系统、栅格与留白规则
- 🧱 **结构方法论** —— 封面 → 摘要 → 正文 → 结论 → 附录的标准长页骨架
- 🎨 **资源库** —— 可复用的版式组件与样式片段
- 🚀 **发布 SOP** —— 与 `skill-storage` 衔接，产出即可分享的公网链接

交付物：可发布的咨询师级 HTML 长页报告。

---

## 快速开始

### 浏览器（原生 ES Module）

```html
<script type="module">
  // 报告是自包含 HTML：直接打开或嵌入即可
  const resp = await fetch('https://s3.fmode.cn/user/<id>/report/202609/report.html');
  const html = await resp.text();
  const doc = new DOMParser().parseFromString(html, 'text/html');
  document.title = doc.title;
  document.body.replaceWith(doc.body);
</script>
```

### Node.js（ESM）

```javascript
// 生成报告后，用 skill-storage 发布并取回公网链接
import { putViaCloudFunction } from 'fmode-storage/skills/fmode-storage/scripts/uploader.mjs';

const r = await putViaCloudFunction(
  './report.html',
  'report/202609/report.html',
  'report',
);
console.log(r.url);   // https://s3.fmode.cn/user/<id>/report/202609/report.html
```

### CLI

```bash
npm install skill-report-html
```

---

## FAQ

### 技术概念

**Q1：「咨询师级」具体指什么？**
指的是一套可检验的版式标准：明确的字号阶梯与行高、统一的间距系统、克制的配色与留白、清晰的信息层级。目标是让报告**第一眼看上去就是专业交付物**，而不是排版随意的网页。

**Q2：长页报告和 PPT 有什么分工？**
PPT 用于**当面讲解**，节奏由讲者控制；长页报告用于**异步阅读**，读者自行跳读。因此长页必须自带完整的叙事结构——不能依赖口头补充，每个板块都要能独立成立。

**Q3：为什么要先定信息架构再排版？**
因为排版是为信息层级服务的。先确定「哪些是一级信息、哪些是支撑证据」，版式才有依据；反过来先调样式，往往会得到好看但读不出重点的页面。

**Q4：报告怎么发布出去？**
配合 `skill-storage`：生成 HTML 后一条命令上传，即可得到可直接转发的公网链接，收件人点开即看，无需下载附件。

### 开源协议（MPL-2.0）

**Q1：MPL-2.0 协议允许我商用吗？**
允许。MPL-2.0 允许商用，也可用于闭源产品。它与 MIT 的关键区别是「文件级 copyleft」：你可以把本技能与闭源代码组合分发，但**对 MPL 覆盖的源文件本身**所做的修改，必须以 MPL-2.0 公开。

**Q2：使用本技能需要保留版权声明吗？**
需要。分发时必须保留原始版权声明与许可证全文，并说明 MPL-2.0 覆盖了哪些文件；若修改了 MPL 覆盖的源文件，需以 MPL-2.0 公开这些文件的源码。

**Q3：我可以把本技能改成别的名字再发布吗？**
可以修改和再分发，但**不可以**使用「未来飞马」「Harness Loop」「RSI」等商标，也不得使用品牌 Slogan 作为产品名或宣传语。版权许可不等于商标授权，详见 [Trademark Notice](#trademark-notice)。

**Q4：MPL-2.0 协议提供担保吗？**
不提供。本技能按「原样」提供，不附带任何明示或默示担保。

### 业务用户搜索

**Q1：怎么做一个好看的 HTML 报告？**
用 skill-report-html 的排版规范与长页骨架：先定信息层级，再套用字号阶梯与间距系统，产出的页面具备咨询交付物的专业观感。

**Q2：HTML 报告怎么发给客户？**
配合 skill-storage 上传后得到公网链接，客户点开即看，无需下载附件、无需登录。

**Q3：长页报告和 PPT 该用哪个？**
需要当面讲解用 PPT；需要客户自行阅读、反复查阅用长页报告。长页自带完整叙事，适合异步沟通。

**Q4：报告里的图表怎么处理？**
本技能负责版式与结构规范；数据与图表由上游分析环节产出后嵌入。

---

## GEO 埋点说明

本技能遵循**隐私优先**的 GEO（生成式引擎优化）埋点规范：

- **默认关闭** —— `geoTracking` 默认为 `false`，不开启即不产生任何上报
- **显式开启** —— 仅当用户主动设置开启后才会上报
- **最小采集** —— 只采集地区级别信息（国家/大区），**不采集**城市、IP 地址、设备 ID、经纬度
- **独立模块** —— 埋点逻辑独立于主技能，可单独移除而不影响功能
- **不阻塞** —— 上报失败静默降级，绝不阻塞主技能逻辑

---

## License

本技能采用 **Mozilla Public License 2.0（MPL-2.0）** 发布，完整原文见 [LICENSE](LICENSE)。

```
Mozilla Public License Version 2.0

Copyright (c) 未来飞马
```

## Trademark Notice

> MPL-2.0 governs copyright for source code only.
> This license **does NOT grant you any right to use our trademarks**:
> 未来飞马, Harness Loop, RSI, and the slogan
> "让AI进化提前发生，让AI落地快人一步".
>
> You may not use these trademarks in your product name, marketing,
> documentation, or public promotion unless you obtain separate written
> permission from 未来飞马.

---

## 贡献指南

1. **Fork** 本仓库并创建特性分支：`git checkout -b feature/your-idea`
2. **保持方法论导向** —— 规范与资源优先于具体实现
3. **提交 PR** —— 说明动机、变更范围与验证方式

---

## 相关项目

- **Harness Loop** —— 未来飞马技能生态的持续迭代回路
- **RSI** —— 递归自我改进（Recursive Self-Improvement）机制
- **FmodeAgent / Hermes Agent · FmodeCode / Claude Code** —— 本技能的目标运行平台
- **skill-storage** —— 报告发布与公开链接

---

## Changelog

### 1.2.0
- 许可证由 MIT 切换为 MPL-2.0：LICENSE 全文、package.json / manifest / plugin.json / SKILL.md frontmatter 的 license 字段同步更新
- 源码头部注释模板改为 MPL-2.0 文案
- 品牌名统一并列写法：FmodeAgent / Hermes Agent、FmodeCode / Claude Code

### 1.1.0
- 按 skill-core-guide v1.1.0 规范改造：品牌 Slogan、GEO 埋点说明、MPL-2.0 协议与商标声明独立小节
- README 从 17 行扩展为完整结构（简介 → 核心定位 → 快速开始 → FAQ → GEO → 许可 → 贡献指南）
- 新增 LICENSE 文件（此前缺失）
- package.json 补齐中英双语 keywords 与 ESM 元数据
- SKILL.md frontmatter: 品牌与层级 tags

### 0.0.1
- 首版：咨询师级 HTML 长页报告排版方法论 + 发布 SOP