WotoHub 自动化

WotoHub Automation 是一项面向真实创作者触达场景的能力，其集成架构根植于 OpenClaw 时代，并与现有工作流保持原位兼容。

它串联以下环节：

• 产品理解
• 创作者搜索
• 初筛与推荐
• 外联邮件草拟
• 批量发送
• 收件箱审查
• 受控回复辅助

最适合的使用场景：

• TikTok Shop 推广活动
• Amazon 创作者触达
• Shopify 商品种草
• 周期性创作者挖掘与跟进

核心设计原则：

• 宿主模型（host model）负责理解与判断
• 脚本（scripts）负责确定性编译、API 执行及状态管理

本能力在发送与回复自动化方面采取有意保守的设计策略。

发布说明：

• wotohub-automation 是唯一权威的发布目录
• wotohub-automation-release 仅为镜像/参考副本，非主要发布源

如需深入了解集成细节，请阅读：

• references/integration-contract.md
• references/runtime-guardrails.md

环境与凭证

安装依赖：

pip install -r requirements.txt

环境变量：

• WOTOHUB_API_KEY：必需，用于认证操作，包括发送、收件箱访问、回复处理及活动周期执行
• WOTOHUB_BASE_URL：可选，显式指定 API 基础地址，默认指向生产环境
• WOTOHUB_STATE_DIR：可选，状态/日志输出目录

凭证作用域说明：

• WOTOHUB_API_KEY 授予对已认证 WotoHub 用户状态操作的访问权限
• 应将其视为具备发送与收件箱权限的凭证，而非仅限无害搜索的令牌
• 即使无凭证，仍可通过 openSearch 执行搜索；但所有认证端点均不可用

运行时要求：

• Python 环境需支持 ssl 模块
• TLS 校验默认启用
• 仅可在受控的调试环境中禁用 TLS 校验

本能力可执行的操作

1. 产品理解

输入来源包括：

• 纯文本产品描述
• 产品 URL（支持 TikTok Shop、Amazon、Shopify 及品牌官网等）

典型输出内容：

• 产品名称
• 核心卖点
• 目标受众
• 创作者适配方向
• 结构化、可直接用于搜索的理解结果

2. 创作者搜索

支持功能：

• 以产品为驱动的搜索词生成
• 按地区、语言、粉丝数、邮箱可用性等维度筛选
• 关键词辅助搜索
• 类目辅助搜索
• 默认过滤已联系过的创作者

搜索模式：

• 无 Token：使用 openSearch
• 有 Token：使用 clawSearch

3. 推荐与初筛

支持功能：

• 对搜索结果进行排序
• 返回精选初筛名单（shortlist）
• 建议下一步人选决策

默认行为为：完成推荐后即暂停，等待明确的创作者选择，再进入邮件生成阶段。

4. 外联邮件草拟

支持功能：

• 面向特定创作者的外联邮件草稿生成
• 以宿主模型为先的个性化草稿生成
• 发送前执行 HTML 标准化与主题行校验

最小活动简报通常需包含以下字段：

• productName
• senderName 或 signoff
• offerType（例如 sample、paid 或 affiliate）

5. 批量发送

默认发送路径为批处理导向。

特性说明：

• 面向多个创作者时，优先采用单次批量 API 请求
• 执行前对邮件结构进行标准化
• 若存在 HTML 正文，则优先使用 HTML 版本

6. 收件箱与回复辅助

支持功能：

• 收件箱列表获取
• 单封邮件详情查询
• 会话线程详情查询
• 安全的回复辅助
• 保守、低风险的自动回复处理

涉及价格、付款、合同条款、排他性、物流承诺或时间节点等敏感事项的回复，须默认由人工审核。

7. 活动周期（Campaign Cycle）

支持功能：

• 手动单次执行
• 通过 cron 或调度器执行单周期任务
• 调度式搜索理解桥接
• 活动状态持久化
• 周期摘要、状态摘要及人工摘要输出
• 标准退出语义：success、blocked 和 failed

工作流概览

步骤 0：认证与 Token 规则

默认情况下，搜索无需登录。

• 无 Token：搜索使用 openSearch
• 有 Token：搜索使用 clawSearch

以下用户侧操作必须提供 WOTOHUB_API_KEY：

• 发送
• 收件箱访问
• 回复处理
• 活动周期执行

若您发布、安装或评审该能力，请将凭证要求视为主操作契约的一部分，而非可选便利项。

可选预检命令：

python3 scripts/preflight.py --token YOUR_API_KEY

认证详情请参阅 appendix-auth.md。

能力入口

统一入口点：

python3 wotohub_skill.py

重要执行说明：

• 默认宿主执行器（host executors）通过能力入口 / 路由包装器流程自动装配；scripts/build_search_payload.py 现在也将在解析 URL 输入前注入路由执行器默认值
• 在低置信度 URL 场景下，product_resolve.py 可能发出 hostUrlAnalysisRequest；scripts/build_search_payload.py 将尝试自动执行宿主 URL 分析 + 回写，再继续后续流程
• 若宿主分析仍无法解析，scripts/build_search_payload.py 将返回结构化的 needsUserInput / error 载荷，而非因 analysis=None 导致崩溃
• 调用方仍可显式传入 hostAnalysis / productSummary，以跳过桥接执行（当已具备宿主侧理解时）

最小请求示例：

{
  "requestId": "task-1",
  "action": "task",
  "type": "product_analysis",
  "input": {
    "input": "wireless earbuds with noise cancellation"
  },
  "auth": {
    "token": "YOUR_API_KEY"
  }
}

常用 action/type 组合：

• task/product_analysis
• task/search
• task/recommend
• task/generate_email
• task/send_email
• task/monitor_replies
• campaign/cycle

推荐注入字段：

• input.hostAnalysis
• input.productSummary
• input.hostDrafts
• input.replyModelAnalysis

宿主 URL 恢复 / 宿主语义理解的执行器发现顺序（推荐）：

• 第一优先级：显式请求级 config.hostAnalysisExecutor
• 第二优先级：活动简报中 brief.hostAnalysisExecutor 或周期流中的 brief.scheduler.hostAnalysisExecutor
• 第三优先级：环境变量默认值 WOTOHUB_HOST_ANALYSIS_EXECUTOR（或兼容别名 HOST_ANALYSIS_EXECUTOR）
• 推荐集成模式：若您的宿主平台始终具备浏览器/Web/模型能力，建议在包装器/启动器中设置环境变量默认值，使链接分析可自动闭环，避免每个调用方重复指定参数

回复理解的执行器发现顺序（推荐）：

• 第一优先级：显式请求级 config.hostReplyAnalysisExecutor / config.hostReplyBridgeExecutor
• 第二优先级：仅限周期流的 brief.scheduler.hostReplyBridgeExecutor（当回复辅助由活动运行时触发时）
• 第三优先级：环境变量默认值 WOTOHUB_HOST_REPLY_ANALYSIS_EXECUTOR（或兼容别名 HOST_REPLY_ANALYSIS_EXECUTOR）

宿主草稿生成的执行器发现顺序（推荐）：

• 第一优先级：显式请求级 config.hostDraftExecutor / config.hostBridgeExecutor
• 第二优先级：仅限周期流的 brief.scheduler.hostBridgeExecutor（当使用定时生成时）
• 第三优先级：环境变量默认值 WOTOHUB_HOST_DRAFT_EXECUTOR（或兼容别名 HOST_DRAFT_EXECUTOR）

标准字段规则：

• 新集成与新示例应默认使用上述标准字段
• 兼容别名仍受支持以利迁移，但不应进一步扩展
• 活动周期草稿回写应使用 host_drafts_per_cycle
• 当前标准字段与别名映射详见 references/alias-normalization-matrix.md

宿主 URL 回写规则：

• 若 scripts/product_resolve.py 返回 hostUrlAnalysisRequest，应将其视为弱 URL 或被屏蔽页面的标准宿主侧恢复触发信号
• 宿主侧应仅回写 hostAnalysis 与 productSummary，然后重新执行相同的 task/product_analysis、task/search、task/recommend 或 task/generate_email 请求
• 不得以理解缺失为由，直接回写接近最终形态的 WotoHub 搜索载荷；合约应维持在语义层
• 最自然的回写位置是 input.hostAnalysis 与 input.productSummary；metadata.* / config.* 仅保留为兼容性接口
• 实际运行中的关键细节：直接执行 python3 scripts/product_resolve.py --input 当前仅输出 hostUrlAnalysisRequest，不自动运行浏览器/Web 恢复，亦不自动应用回写
• 自动宿主分析执行目前仅存在于上层 / 活动编排路径中（依赖 hostAnalysisExecutor），而非裸调 product_resolve.py 路径

信任边界：

• 将宿主注入的模型输出视为未经验证的结构化输入，直至完成校验
• 禁止上游模型直接向执行流程注入接近最终形态的 WotoHub 载荷
• 在允许发送或回复执行前，须依据引用的 Schema 对注入的分析与草稿数据进行校验

完整集成细节见：references/integration-contract.md
第三方快速入门指南：references/third-party-integration-guide.md
一键启动器：

• run_skill_with_router.py
• run_cycle_via_skill.py（现已为周期运行自动装配路由默认值）
  执行器模板：
• scripts/host_executor_router.py（面向分析 / 回复 / 草稿的单入口路由）
• scripts/host_analysis_executor_example.py
• scripts/host_reply_analysis_executor_example.py
• scripts/host_draft_executor_example.py
• scripts/host_model_bridge_executor_example.py（面向周期的草稿桥接示例）

步骤参考

步骤 1：产品分析

请阅读 steps/01-product-analysis.md

推荐执行路径：

python3 scripts/product_resolve.py --input "推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理"

步骤 2：创作者搜索

请阅读 steps/02-influencer-search.md

推荐路径：先构建载荷，再执行搜索：

python3 scripts/build_search_payload.py --input '推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理'
python3 scripts/claw_search.py --payload-file /tmp/woto_payload.json

或使用单步执行：

python3 scripts/build_search_payload.py --input '...' --run-search
python3 scripts/build_search_payload.py --input '...' --run-search --token YOUR_API_KEY

步骤 3：推荐

请阅读 steps/03-influencer-recommend.md

默认流程先返回初筛名单，再等待明确的创作者选择。

步骤 4：邮件草拟

请阅读 steps/04-email-generation.md

建议仅在以下条件满足后执行：

1. 目标创作者已选定
2. 最小活动简报已完备

步骤 5：发送

请阅读 steps/05-send-email.md

发送协议：

• prepare_only：仅准备候选邮件
• manual_send：经人工确认后发送
• scheduled_send：在调度流程中自动发送

默认行为：

• 单次手动运行默认采用 prepare_only
• 调度任务与活动简报运行默认采用 scheduled_send，即调度流程下的默认真实发送路径

步骤 6：收件箱与回复辅助

请阅读 steps/06-inbox-management.md

主路径：

1. 收集待处理回复
2. 基于完整会话线程构建模型输入
3. 产出结构化分析
4. 产出回复预览
5. 应用风险分级
6. 仅允许低风险的信息性回复自动发送

失败处理

缺失活动宿主分析

• 对于 scheduled_cycle，若搜索阶段缺少有效 hostAnalysis，则停在 waiting_for_host_analysis
• 优先使用 --host-analysis-bridge-executor 或发出的 hostAnalysisRequest，而非将接近最终形态的搜索载荷硬塞进简报
• 宿主分析解决后，交由标准编译器重建 WotoHub 搜索参数

Token 校验失败

• 提示用户刷新 Token
• 禁止继续执行任何需认证的 API 操作

搜索失败或认证失败

• 提示用户检查 Token、请求头及运行环境
• 禁止伪造结果

URL 获取失败

• 返回结构化降级响应或 needsUserInput=true
• 若可行，优先通过轻量级宿主辅助恢复机制 hostUrlAnalysisRequest 获取 hostAnalysis / productSummary，再退回到用户提供的产品字段
• 宿主回写应落至标准字段 input.hostAnalysis + input.productSummary，随后重试相同任务，使现有路由与编译链路可自然延续
• 不得将 URL slug 视为有效的产品理解而继续执行

发送或回复执行失败

• 保留结构化错误信息
• 禁止静默吞没执行失败

安全说明

• 已完成对本版本中 SKILL.md 及配套 Markdown 提示/参考文件的隐藏字符审查，未发现 Unicode 双向控制符（bidi）或控制字符。
• 示例环境变量与 JSON 文件仅为占位符或测试用例。使用前请务必审查，切勿盲目将占位 ID 或样例值复制到生产环境。
• “宿主模型优先”不等于“宿主模型可信”。请持续启用 Schema 校验与发送防护机制。

核心入口文件

• wotohub_skill.py：能力入口适配器
• run_campaign.py：公开活动入口
• run_campaign_cycle.py：单周期调度入口
• run_cycle_via_skill.py：面向 cron / 调度器的安全轻量封装，可避免复杂的内联 JSON 或繁重的 Python CLI 引号转义

run_campaign_cycle.py 中常用的调度桥接参数：

• --host-analysis-bridge-executor
• --host-analysis-bridge-request
• --host-analysis-bridge-payload
• --host-bridge-executor
• --host-bridge-request
• --host-bridge-payload

参考文档地图

实用文档：

• steps/01-product-analysis.md
• steps/02-influencer-search.md
• steps/03-influencer-recommend.md
• steps/04-email-generation.md
• steps/05-send-email.md
• steps/06-inbox-management.md
• references/campaign-brief-schema.md
• references/model-analysis-schema.md
• references/conversation-analysis-schema.md
• references/outreach-email-schema.md
• references/search-params.md
• references/integration-contract.md
• references/runtime-guardrails.md

一句话总结

WotoHub Automation 是一项面向真实营销运营的创作者触达能力：以模型为先实现理解，以脚本为先驱动执行，核心工作流稳定可靠，并在发送与回复行为上设置了明确的安全边界。