Report Expert

---

name: report-expert description: "生成 HTML 报告页面并部署到 Cloudflare Pages 站点。涵盖设计系统、页面结构、索引管理、iframe 内嵌查看、自动部署全流程。触发词：写报告、发布报告、部署报告、生成报告页面、report publisher、报告专家、升级报告专家、更新报告技能、发布技能升级。"

---

报告专家

将调研内容生成符合设计规范的 HTML 报告页面，支持两种内容类型：报告页面（同站部署）和外部页面（独立部署，iframe 内嵌查看）。

---

技能版本管理

所有远程地址均从 manifest.json 的 repository 字段动态获取，不硬编码任何绝对 URL。

安装方式

技能支持两种安装渠道：

| 渠道 | 安装命令 | 特点 | |------|---------|------| | ClawHub | clawhub install report-expert | 自动管理版本，安全扫描，推荐 | | | CF Pages | 将 manifest.json 地址发送给 Agent | 包含 upgrade.py 自更新脚本 |

拉取升级（用户指令触发）

当用户说「升级报告专家」「更新报告技能」「检查技能更新」时，根据安装方式选择升级命令：

ClawHub 安装的技能：

clawhub update report-expert

CF Pages 安装的技能： > 安全提示： 升级会从 manifest.repository 指定的远端下载文件并覆盖本地技能文件（含 SHA256 校验）。请确认你信任该远端来源。

SKILL_DIR="<技能实际目录路径>"
python3 "${SKILL_DIR}/upgrade.py"

> 注意： upgrade.py 仅随 CF Pages 渠道分发，ClawHub 渠道通过 clawhub update 管理，不包含该文件。

发布升级（修改技能后触发）
当用户说「发布技能升级」「发布报告专家」「提交技能更新」时，执行发布流程。
> 安全提示： 发布会将技能文件部署到 Cloudflare Pages，需要 CLOUDFLARE_API_TOKEN。请确认 token 权限范围合理（仅需 Pages 编辑权限）。

bash SKILL_DIR="<技能实际目录路径>"

SKILL_DIR="$SKILL_DIR" python3 << 'PYEOF' import json, hashlib, os, sys from datetime import date

skill_dir = os.environ.get("SKILL_DIR", os.path.dirname(os.path.abspath(__file__))) manifest_path = os.path.join(skill_dir, "manifest.json")

with open(manifest_path, "r", encoding="utf-8") as f: manifest = json.load(f)

1. 版本递增

old_ver = manifest.get("version", "0.0.0") parts = old_ver.lstrip("v").split(".") parts[-1] = str(int(parts[-1]) + 1) new_ver = ".".join(parts) manifest["version"] = new_ver manifest["updated"] = date.today().isoformat()

2. 远程基础地址（从 repository 字段读取）

repo = manifest.get("repository", "").rstrip("/")

3. 重算所有文件哈希

for root, dirs, fnames in os.walk(skill_dir): dirs[:] = [d for d in dirs if d not in (".git", "__pycache__")] for fname in fnames: fpath = os.path.join(root, fname) rel = os.path.relpath(fpath, skill_dir) if rel == "manifest.json": continue with open(fpath, "rb") as f: sha = hashlib.sha256(f.read()).hexdigest() sz = os.path.getsize(fpath) if rel not in manifest.get("files", {}): manifest.setdefault("files", {})[rel] = {} manifest["files"][rel]["sha256"] = sha manifest["files"][rel]["size"] = sz # url 保持相对路径 manifest["files"][rel]["url"] = rel

4. 清理已删除的文件

existing = set() for root, dirs, fnames in os.walk(skill_dir): dirs[:] = [d for d in dirs if d not in (".git", "__pycache__")] for fname in fnames: rel = os.path.relpath(os.path.join(root, fname), skill_dir) if rel != "manifest.json": existing.add(rel) for rel in list(manifest.get("files", {}).keys()): if rel not in existing: del manifest["files"][rel]

5. 写入 manifest

with open(manifest_path, "w", encoding="utf-8") as f: json.dump(manifest, f, ensure_ascii=False, indent=2)

5.5. 同步版本号到技能介绍页面

index_html = os.path.join(skill_dir, "index.html") if os.path.exists(index_html): ih = open(index_html, "r", encoding="utf-8").read() # 替换版本号标记（匹配 v数字.数字.数字 格式） import re ih = re.sub(r'v\d+\.\d+\.\d+', f'v{new_ver}', ih, count=1) open(index_html, "w", encoding="utf-8").write(ih) print(f"📄 介绍页版本已同步: v{new_ver}")

print(f"✅ 版本: v{old_ver} → v{new_ver}") print(f"📦 文件: {len(manifest['files'])} 个") for rel, meta in manifest["files"].items(): print(f" {meta['sha256'][:12]}... {meta['size']:>6}B {rel}") PYEOF

6. 发布到预览环境（自动升级版本号 + 同步所有文件版本）

SKILL_DIR="$SKILL_DIR" python3 "${SKILL_DIR}/deploy.py" publish

7. 验证预览内容（检查输出的预览地址）

- manifest.json 版本号正确

- index.html 版本号正确

- SKILL.md 版本号正确

8. 验证无误后，发布到生产环境

python3 "${SKILL_DIR}/deploy.py" publish-prod

验证发布
发布后执行以下命令确认：

bash SKILL_DIR="<技能实际目录路径>" REPO=$(python3 -c "import json; print(json.load(open('${SKILL_DIR}/manifest.json'))['repository'])")

检查 manifest 可达

curl -sL "${REPO}/manifest.json" | python3 -c "import json,sys; m=json.load(sys.stdin); print(f'v{m[\"version\"]} — {len(m[\"files\"])} files')"

检查各文件可达

curl -sI "${REPO}/SKILL.md" | head -1 curl -sI "${REPO}/deploy.py" | head -1

前置配置（使用者必须完成）
四组部署目标配置
在 TOOLS.md 中按需配置：

markdown

Report Expert 技能配置

部署模式： local

REPORT_DEPLOY_MODE=local

REPORT_LOCAL_DIR=/path/to/site # 本地站点根目录

REPORT_LOCAL_URL=https://example.com/claw # 站点访问地址

REPORT_SITE_NAME=传琪

远程报告部署（可选）

REPORT_CF_PROJECT=reports-site # 报告站 CF Pages 项目名

技能 CF 发布（可选）

SKILL_CF_PROJECT=report-expert-skill # 技能站 CF Pages 项目名

技能 ClawHub 发布（可选）

SKILL_CLAWHUB_SLUG=report-expert

SKILL_CLAWHUB_NAME=报告专家

共用凭据
CLOUDFLARE_API_TOKEN — 环境变量或 TOOLS.md，一个 token 管所有 CF 操作
  - 建议使用最小权限 token（仅需 Cloudflare Pages 编辑权限）
  - 建议使用环境变量方式配置，不要提交到公共仓库
两种内容类型
1. 报告页面（同站部署）
完整的调研报告、教程等，部署在报告主站的子目录下。
流程：
1. 生成 HTML body 内容（只需