官方文档GeWe API - GeWe API微信 API 开发文档一、业务痛点与技术背景私域运营链路通常是线索进线 → 通过好友 → 打标签 → 发欢迎语 → 拉群 → 阶段培育 → 转化提醒若用「if-else 脚本」堆砌会出现节点不可视、失败不可补偿、A/B 难做、风控规则散落。需要把 GeWe 能力编排成Workflow Engine类 Temporal / State Machine。GeWe 能力覆盖好友管理、消息、群管理、朋友圈、标签等详见官方核心能力说明。二、核心架构设计与数据流转TriggerWebhook事件 / CRM webhook / 定时器 │ ▼ Workflow Router按渠道/活动选择流程定义 │ ▼ State Machine Runtime states: PENDING_ACCEPT → WELCOMED → TAGGED → INVITED_GROUP → NURTURE → DONE │ ├─ Action: gewe.acceptFriend ├─ Action: gewe.sendText / sendLink ├─ Action: gewe.addTag ├─ Action: gewe.inviteToGroup └─ Action: wait(timer) / human_task │ ▼ Side Effects → CRM / 数据仓库 / 审计每个 Action 都走统一出站网关与风控不直接裸调 API。三、关键代码与配置示例3.1 流程定义YAMLid: lead_nurture_v3 version: 3 trigger: event: friend_request_accepted steps: - id: welcome action: send_text params: template: welcome_v2 on_error: retry(3, backoff2s) - id: tag action: add_tags params: tags: [线索-直播, 未购] - id: wait_1d action: delay params: { hours: 24 } - id: invite action: invite_group params: group_pool: vip_intro_groups strategy: least_members guard: risk: allow_invite - id: nurture_msg action: send_link params: template: product_intro when: crm.stage ! paid3.2 状态机运行时Python 简版class WorkflowRuntime: def __init__(self, store, actions, policy): self.store store self.actions actions self.policy policy def start(self, flow_id: str, ctx: dict) - str: inst self.store.create_instance(flow_id, ctx, step_index0) self._kick(inst.id) return inst.id def _kick(self, instance_id: str): inst self.store.load(instance_id) flow self.store.load_flow(inst.flow_id) if inst.step_index len(flow[steps]): self.store.mark_done(instance_id) return step flow[steps][inst.step_index] if step[action] delay: self.store.schedule(instance_id, step[params]) return decision self.policy.evaluate(inst.ctx, step) if decision ! ALLOW: self.store.park(instance_id, reasondecision) return self.actions.run(step[action], {**inst.ctx, **step.get(params, {})}) self.store.advance(instance_id) self._kick(instance_id)3.3 Action通过好友后欢迎语async function onFriendAccepted(evt: FriendEvent) { await workflow.start(lead_nurture_v3, { appid: evt.appid, peerId: evt.wxid, source: evt.scene, }); } // actions/send_text.ts export async function send_text(ctx: any) { const content await template.render(ctx.template, ctx); return guardedSend({ client_msg_id: ${ctx.instanceId}:welcome, appid: ctx.appid, to: ctx.peerId, kind: text, priority: 1, payload: { content }, }); }3.4 群池与最少人数策略SELECT group_id FROM wechat_groups WHERE pool vip_intro_groups AND member_count max_members AND status active ORDER BY member_count ASC LIMIT 1 FOR UPDATE SKIP LOCKED;3.5 失败补偿invite_group 失败群满→ 换群重试 → 仍失败 → 创建人工任务「手动拉群」 send_text 风控拒绝 → 流程 park不继续 invite避免半开状态扰民四、生产环境避坑与安全风控流程版本化在途实例绑死 version3发布 v4 不影响旧单。幂等每个 step 用instanceId:stepId作为 client_msg_id。长 delay用持久化调度不是进程内 sleep防重启丢失。人机协同高风险步骤设human_task运营确认后再 resume。指标转化漏斗按 step 统计定位是欢迎语问题还是拉群配额问题。API 细节以文首官方文档为准。五、本篇交付清单私域培育状态机模型YAML 流程定义与运行时群池选择与补偿与风控/网关集成点