📦 Report Expert — 技能工具

将调研内容生成符合设计规范的 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. 报告页面（同站部署）
完整的调研报告、教程等，部署在报告主站的子目录下。
流程：
生成 HTML body 内容（只需