member-marketing API / MCP

版本 0.3 · 面向商品中心、公众号数据采集、Agent 可验证交付及企微审批待办。

鉴权与调用身份

外部请求使用系统 Basic Auth；受保护的内部接口由工具网关注入 X-API-Key。Agent 不直接持有内部 API Key。

Agent 调用流程

1. 调用 mm_sandbox_run_start 登记隔离运行。
2. 在 workspace 中完成任务；需要业务数据时调用获准的 MCP 工具。
3. 调用 mm_artifact_upload 上传文件，获得 artifact_id、下载链接和 SHA-256。
4. 调用 mm_sandbox_run_complete 绑定交付物并结束运行。
5. 任务执行回写时携带 artifact_ids；没有真实证据的文字产出不能进入 verified。

双设备 Agent 团队调用方式

同一套系统支持两种调用模式：生产建议走中心队列调度；联调或单任务回放可走工作流直调。所有写操作仍需遵守审批与验收门禁。

Windows 设备团队（worker_windows_chengyuan）

Mac mini 设备团队（worker_macmini_guishuiyulong）

说明：main、product-agent、ops-agent、crm-sales-agent、sync-agent 属于 canonical 身份组别名。若队列 preflight 出现角色或 agent 不兼容，请改用对应 canonical Agent 重新 enqueue。

调度请求样例

{
  "task_id": "task_xxx",
  "agent_id": "huoke-agent",
  "preferred_device_id": "worker_windows_chengyuan",
  "workflow_id": "paid_content_growth_closed_loop",
  "idempotency_key": "task_xxx:huoke-agent:v1"
}

{
  "task_id": "task_yyy",
  "agent_id": "strategy-agent",
  "preferred_device_id": "worker_macmini_guishuiyulong",
  "workflow_id": "strategy-brain-weekly-growth-loop",
  "idempotency_key": "task_yyy:strategy-agent:v1"
}

核心 HTTP 接口

企微审批待办闭环

以下来源会自动同步到企微「审批」中的个人待办：战役名单与文案放行、社群发送、公众号草稿、朋友圈/群推送，以及没有独立审批对象且已绑定项目的 awaiting_approval Agent 任务。

1. 系统为每个来源版本计算 source_fingerprint，同一版本只创建一条企微审批，避免重复提醒。
2. 历史通用审批只同步最近 7 天内仍待处理的记录；战役和社群发送闸门按当前有效状态同步，避免旧任务污染个人待办。
3. 企微审批通过后才创建 Task Run 或调用对应执行接口；审批本身不计入发送、付款或业务完成。
4. 企微驳回会回写来源状态；审批期间名单、文案或物料发生变化时，旧审批不会执行。
5. 社群发送继续遵守单群串行门禁：后一群即使提前获批，也会等待前一群的企微确认和真实回执。

公众号文章数据字段

付费数据回写 Notion

把公众号后台最新付费快照中付费人数有变化的商品，回写到 Notion「付费文章库」的 付费人数 与 统计日期（统计日期为快照日期，不是运行当天）。实际收入（元） 等为 Notion 公式，不写入。只有匹配分不低于 0.8 且快照不早于 Notion 现有统计日期的商品才会更新。商品中心页的「Notion 回写触发器」卡片即使用下列接口。

writeback-status 返回字段：enabled、scheduler_running、interval_minutes、daily_time、next_daily_run_at（UTC ISO 时间）、min_match_score、in_flight（是否正在回写）、latest_run、runs。记录字段：id、trigger_source、status、snapshot_date、candidate_count、updated_count、skipped_count、failed_count、error、started_at、finished_at（数据库时间为 UTC）。

可靠性：单个 Notion 页面更新遇网络错误、429、5xx 最多重试 3 次；整次回写最长 20 分钟、下游商品同步最长 5 分钟，超时记为 failed 并释放运行锁；同一时间只运行一次，重复触发会复用进行中的任务。

curl -X POST "$BASE/api/products/writeback" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"dry_run": true, "trigger_source": "ops_check"}'

MCP 配置

{
  "mcpServers": {
    "member_marketing": {
      "command": "node",
      "args": ["D:/clawdbot/ops/member-marketing/mcp-tool-gateway/server.mjs"],
      "env": {
        "MEMBER_MARKETING_BASE_URL": "https://ops.chengyuan.team/member-marketing",
        "MEMBER_MARKETING_AGENT_ID": "huoke-agent"
      }
    }
  }
}

Basic Auth 只通过 Windows 服务或 OpenClaw 宿主进程环境变量注入。每个 Agent 使用独立配置文件，服务端仍会再次校验白名单。

完整机器可读规范

下载 OpenAPI 3.1 JSON。MCP 工具名称以 mm_ 开头，可在工具中心或 mm_tool_gateway_manifest 中查看当前 Agent 实际权限。