官方文档：GeWe API - GeWe API｜微信 API 开发文档

一、业务痛点与技术背景

私域运营链路通常是：

线索进线 → 通过好友 → 打标签 → 发欢迎语 → 拉群 → 阶段培育 → 转化提醒

若用「if-else 脚本」堆砌，会出现：节点不可视、失败不可补偿、A/B 难做、风控规则散落。需要把 GeWe 能力编排成Workflow Engine（类 Temporal / State Machine）。

GeWe 能力覆盖：好友管理、消息、群管理、朋友圈、标签等（详见官方核心能力说明）。

二、核心架构设计与数据流转

Trigger（Webhook事件 / 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 流程定义（YAML）

id: lead_nurture_v3 version: 3 trigger: event: friend_request_accepted steps: - id: welcome action: send_text params: template: welcome_v2 on_error: retry(3, backoff=2s) - 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 != 'paid'"

3.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_index=0) 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, reason=decision) 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，避免半开状态扰民

四、生产环境避坑与安全风控

1. 流程版本化：在途实例绑死 version=3，发布 v4 不影响旧单。

2. 幂等：每个 step 用instanceId:stepId作为 client_msg_id。

3. 长 delay：用持久化调度（不是进程内 sleep），防重启丢失。

4. 人机协同：高风险步骤设human_task，运营确认后再 resume。

5. 指标：转化漏斗按 step 统计，定位是欢迎语问题还是拉群配额问题。

6. API 细节以文首官方文档为准。

五、本篇交付清单

• 私域培育状态机模型

• YAML 流程定义与运行时

• 群池选择与补偿

• 与风控/网关集成点