genviral Partner API Skill

一句话概括： 将 genviral 的 Partner API 封装为 50+ 个 bash 命令。核心流程：get-pack → 分析图像（元数据 + 视觉理解）→ 使用 pinned_images 调用 generate → render → 可视化审核（硬性关卡）→ create-post → 日志写入 workspace/performance/log.json。Studio AI 流程：studio-models → studio-generate-image（同步）或 studio-generate-video（异步）→ studio-video-status --poll（轮询状态）。认证通过 GENVIRAL_API_KEY 环境变量完成。配置位于 defaults.yaml。实例数据存于 workspace/ 目录下。

该 Skill 的功能

• 多平台发布： 支持 TikTok、Instagram、YouTube、Pinterest、LinkedIn、Facebook 等平台的视频或幻灯片形式内容发布
• Studio AI 内容生成： 通过 API 调用 AI 模型，同步生成图像、异步生成视频
• 文件管理： 将视频/图像上传至 genviral 的 CDN
• AI 幻灯片生成： 根据提示词自动生成照片轮播图，并渲染为图像
• 模板系统： 支持复用幻灯片结构；可将表现优异的幻灯片一键转为模板
• 素材包管理： 将图像包作为幻灯片背景使用
• 数据分析： 提供关键指标（KPI）、单条内容维度数据、已追踪账号列表、刷新触发机制
• 细分领域智能分析： 一次调用即可完成趋势调研（trend-brief），涵盖热门话题标签、音频、创作者、最佳发布时间窗口及钩子角度（hook angles）
• 内容流水线： 实现从提示词输入到内容发布的全链路自动化
• 效果追踪： 记录发布日志、钩子（hook）表现、支持周度复盘
• 钩子库： 持续维护并迭代经验证有效的钩子内容库

工作原理

1. 生成或上传媒体素材
2. 创建面向一个或多个账号的内容发布任务
3. 安排发布时间或立即发布（针对 TikTok 幻灯片，可选择保存为草稿，以便在发布前添加热门音频 —— 音频选择需依赖人工判断以获得最优效果）
4. 通过数据分析追踪内容表现
5. 持续学习与优化策略

所有配置均位于 defaults.yaml；密钥类信息通过环境变量注入。所有通过本 Skill 发布的内容均会在 Genviral 后台仪表盘中呈现。

首次设置

若为全新安装，请阅读 docs/setup.md，并以对话式引导用户完成入驻流程：

1. 设置 API 密钥并验证其有效性
2. 列出可用账号，由用户选择目标发布账号
3. 讨论图像策略（复用现有素材包、新建素材包、按每条内容单独生成，或混合使用）
4. 可选：协同设定产品上下文与品牌语调

无任何硬编码默认值。始终向用户征询偏好并动态适配。所有通过本 Skill 完成的操作均会同步显示在 Genviral 后台仪表盘中，确保用户拥有完全可见性与控制权。

文件结构

genviral/
  SKILL.md                  # 本文件（内核逻辑 + 路由说明）
  README.md                 # 面向用户的概览文档
  defaults.yaml             # API 配置与默认参数

  docs/
    setup.md                # 入驻指南（对话式，共 5 个阶段）
    api/
      accounts-files.md     # 账号管理、文件上传、文件列表
      posts.md              # create-post、update-post、retry、list、get、delete
      slideshows.md         # generate、render、review、update、regenerate、duplicate、list + 文字样式
      packs.md              # 素材包 CRUD 操作 + 智能图像筛选（任何涉及素材包的工作流均须必读）
      templates.md          # 模板 CRUD 操作 + 从幻灯片创建模板
      analytics.md          # 所有数据分析相关命令
      studio.md             # Studio AI：图像/视频生成、模型列表、状态轮询
      subscription.md       # 订阅状态、余额、服务等级
      pipeline.md           # 内容流水线、效果反馈闭环、CTA 测试、各平台发布建议
      errors.md             # 错误码说明与故障排查指南
    references/
      analytics-loop.md     # 完整的数据分析反馈闭环与周度复盘流程
      competitor-research.md # 竞品调研方法论
    prompts/
      slideshow.md          # 幻灯片生成提示词模板
      hooks.md              # 钩子创意头脑风暴提示词模板

  workspace/                # 所有实例/客户专属数据（可通过 GENVIRAL_WORKSPACE_DIR 环境变量覆盖路径）
    content/
      scratchpad.md         # 当前内容规划与草稿区
      calendar.json         # 即将发布的计划内容日历
    context/
      product.md            # 产品描述、核心价值主张、目标受众
      brand-voice.md        # 语调风格、表达规范（应做与不应做事项）
      niche-research.md     # 细分领域在各平台的研究成果
    hooks/
      library.json          # 钩子实例集合（随时间增长，持续追踪表现）
      formulas.md           # 钩子公式模式与心理学原理
    performance/
      log.json              # 权威发布记录（单一可信源）
      hook-tracker.json     # 钩子与 CTA 表现追踪（含量化指标，构成反馈闭环）
      insights.md           # 基于效果数据得出的 Agent 学习结论
      weekly-review.md      # 周度复盘笔记
      competitor-insights.md # 竞品调研发现汇总

  scripts/
    genviral.sh             # 主 API 封装脚本（包含全部命令）
    update-skill.sh         # 自动更新脚本

命令路由

按当前任务按需加载对应文档：

细分领域调研模式（当用户要求调研某细分领域时）

当用户提出类似“调研该细分领域”、“找出该领域有效内容方向”或“提供细分领域情报”等请求时：

1. 首先对细分领域关键词运行 trend-brief（默认采用 7d 时间窗口；如需时效性更强的结果，可追加运行 24h 版本）。
2. 提取并汇报：热门话题标签、热门音频、头部创作者、推荐发布时间窗口（UTC）、推荐钩子角度。
3. 依据 docs/references/competitor-research.md 开展竞品深度分析（至少覆盖 3–5 个账号）。
4. 输出一份简明、可执行的结论，包括：
   • 3 个待测试的钩子角度
   • 2 条 CTA 建议
   • 2 个最佳发布时间窗口
   • 5 个起始使用的话题标签
   • 1 条“可利用的市场空白”洞察
5. 将调研结果保存至 workspace/performance/competitor-insights.md，并在后续内容提示词中复用这些发现。

不可协商规则

无论已加载哪些文档，以下规则必须严格遵守：

1. 使用素材包生成幻灯片时，务必始终指定 pinned_images。禁止仅传入 --pack-id 调用 generate —— 此时服务端将随机选取图像。执行任何与素材包相关的操作前，请务必通读 docs/api/packs.md。

2. 每次渲染完成幻灯片后，必须进行人工视觉审核，确认无误后方可发布。若任一幻灯片存在可读性问题，必须修正。此为强制性关卡，非建议项。

3. 每次发布后，必须立即写入日志至 workspace/performance/log.json。该文件是唯一权威的发布记录来源。

4. 每次发布后，必须新增一条 hook-tracker 记录。未追踪即无法学习。

5. 禁止在任何生成内容中使用中文破折号（em-dash）。

6. 尊重 workspace/ 目录结构 —— 所有实例数据均存放于此。请勿将状态文件写入 Skill 根目录。

脚本使用方式

/path/to/genviral/scripts/genviral.sh  [options]

需设置环境变量 GENVIRAL_API_KEY（格式为：public_id.secret）。默认从 defaults.yaml 加载配置。可通过设置 GENVIRAL_WORKSPACE_DIR 环境变量覆盖 workspace 路径（默认为 Skill 目录下的相对路径 workspace/）。

自动更新

本 Skill 内置自更新机制，可将 Skill 自有文件与 GitHub 仓库 fdarkaou/genviral-skill 的最新版本保持同步。

bash scripts/update-skill.sh           # 检查更新并应用（如有）
bash scripts/update-skill.sh --dry-run # 仅预览变更，不执行实际更新
bash scripts/update-skill.sh --force   # 强制重新应用（即使当前已是最新版）

被更新的文件（Skill 所有）： SKILL.md、scripts/、docs/（及其全部子目录）

永不修改的文件（用户所有）： workspace/ —— 您的数据、上下文、钩子库及效果日志将始终得到完整保留。

备注

• 兼容 genviral 支持的所有平台（TikTok、Instagram 等）
• 同时支持视频与幻灯片形式的内容发布
• 兼容托管账号与 BYO（Bring Your Own）账号
• 内容支持定时发布或立即发布
• TikTok 幻灯片草稿：使用 post_mode: MEDIA_UPLOAD 可将内容暂存至草稿箱，便于后续添加热门音频