qidian-marketing-cloud

---
name: qidian-marketing-cloud
description: 腾讯企点营销云的营销业务查询、分析、策划与任务协同。覆盖五类场景：消费者运营（首购转化、新人券、加购未购、复购提频、一转二、沉睡唤醒、流失召回、拉新获客、老带新、会员等级、生日礼、积分与储值权益）；货品运营（新品推广、种子客户试推、老品带新、爆品复购、折扣清仓、临期促销、跨品类及跨品牌连带、搭配推荐、引流品）；事件营销（大促、双 11、618、节假日、店庆会员日、分人群权益、商品组合、预热/爆发/返场、多渠道节奏与频控）；门店管理（新店开业、区域与门店拉新分析、重装移铺、闭店通知与老客承接）；经营与洞察（营销问数、人群画像、生命周期分布与迁移、消费频次和品类偏好、渠道拉新、活动效果、领券核销、成交与增量复盘）。支持营销策划、预算分配、实验设计和短信、Push、私聊、客户群、朋友圈等渠道的文案与内容方案。企业微信私域运营为补充能力：我的排行、团队业绩、个人/团队客户与客户群资产、营销待办、员工活码/群活码、群发客户/客户群/朋友圈、跟进任务、欢迎语、客户搜索、标签与人群、会话存档、互动率、开口率、回复超时、敏感内容、会话情绪与满意度；营销虾、企业微信互动智能助手等名称同样触发。营销云内的企业微信办公协同（通讯录、日程与会议、原生待办、消息、邮件、文档与表格、微盘），以及营销海报、商品图、标签写入等请求，按正文支持范围判断授权、交付或页面操作，不承诺直接完成。用户提出上述营销业务诉求时使用，即使未点名营销云；查询数据与方案建议不等于已完成圈人、渠道配置或触达。使用 magic-agent-cli 发起任务，按正文展示结果卡、执行图和文件，收集用户真实回答后续读，不自行调用远程接口。
---

# 腾讯企点营销云

本 Skill 对应 CLI 1.2.4（`magic-agent-cli --version`）。版本不一致时更新完整连接器包并重新连接。

## 适用场景

- **消费者运营**：首购转化、复购提频、流失召回、拉新与会员权益，围绕生命周期分层、商品推荐和权益激励制定策略。
- **货品运营**：新品试推、爆品复购、折扣清仓、连带推荐与引流品，结合人群偏好设计推广方案。
- **事件营销**：大促、节假日及店庆会员日，设计分人群权益、商品组合、阶段节奏和触达频控。
- **门店管理**：新店开业、门店变更，制定拉新引流和老客承接方案。
- **经营洞察**：人群画像、生命周期分布与活动复盘，分析业务表现并提出优化建议。

## 提问示例

- 为注册后 3 天仍未首购的新会员设计新人券促首单方案，包含券面额、使用门槛和到期提醒文案。
- 为服饰新品设计一套种子客户试推方案，包含选人标准、推荐话术和效果评估指标。
- 为双 11 设计预热、爆发和返场三个阶段的营销方案，明确各阶段的目标人群、优惠权益和触达节奏。
- 为一家即将开业的服饰门店设计拉新引流方案，包含周边获客、引流商品和新客权益。
- 分析最近一个已结束活动的效果数据，给出复盘建议。

区分**方案建议**与**实际业务执行**：输出选人标准不等于已创建人群，输出触达文案不等于已发送消息，设计频控不等于已配置渠道。查询与执行依赖当前授权空间的数据和权限；缺少活动、商品、人群或门店信息时，按服务端追问让用户补充，不编造业务数据。收到执行计划时先收集用户真实确认，收到正文方案时将假设和建议值与实测数据区分。

## 对话内展示

有两类内容进对话内渲染，规则不同，先读 [结果呈现规范](references/rendering.md) 再动手：

- **结果卡 `result_card`**（业务结果）：按规范第二节的模板生成 HTML 片段，调用宿主实际提供的 `show_widget` 渲染。渲染成功后正文只保留一句简短结论。
- **执行图 `dag_snapshot`**（执行状态）：片段由 CLI 生成，把事件里的 `widgetCode` **原样**传给 `show_widget`，不重排节点、不改写依赖、不自己重画。**执行图不触发上面那条一句话规则**——正文、HITL 资料和文件说明照常完整输出。

两者都遵守：工具可用时必须真正调用它，不能用 `present_files` 打开预览代替；以工具返回结果确认渲染成功（生成了文件、出现「正在渲染组件」都不算）；确认宿主不支持或调用失败时，说明限制并按规范里的顺序降级。

执行图的展示时机：**每收到一版新的 `dag_snapshot` 就展示一次**。快照只在节点状态、依赖或标题真的变化时才升版本，所以「又来一版」就等于「图变了」——**进行中的节点状态推进（某步从待执行变成进行中 / 已完成）同样要重画**，不要压成一句话进度。首个计划、每个新的待答、计划结构变化和运行终态必须有图。只有同一 `(executionId, version)` 已经展示过才不重复出图；一次命令输出里出现多版时只展示最高版本。没有执行图的任务不要编造流程图。

## 凭据与连接

- 本包使用浏览器 OAuth 登录。首次连接和重新连接由 WorkBuddy 调用 `auth login`；用户在授权页面确认企业与空间，CLI 校验身份后保存凭据。
- 只有错误明确要求重新授权时，才在连接器面板重新连接；临时错误按文末恢复规则处理。不运行 `configure`，不索取或展示凭据，不读取、展示或分享凭据文件及 cli.json，不打印环境变量，不把凭据写进命令参数。
- `magic-agent-cli auth status` 检查本机凭据，临近到期时在有限时间内静默续期；不打开浏览器、不创建任务。`configured=true` 表示本机凭据可用，业务请求仍由服务端校验。`configured=false` 时须同时查看 `retryable` 与 `reauthRequired`，不能一律要求重新授权。
- 仅在用户要求时运行 `magic-agent-cli auth logout`，清理本机凭据并请求撤销远端授权；远端撤销是否成功以命令结果为准。

## 发起任务

业务请求直接发起，不需要先检查连接。**企微私域运营类诉求必须带 `--skill`**，按类型选技能，照下面例子：

```text
# 六项创建 → 钉 wecom-scrm-bot-skill（对话补参与确认）。
# 仅这六类：创建员工活码、创建群活码、创建群发客户任务、创建群发客户群、创建群发朋友圈、创建跟进任务。
magic-agent-cli chat start --skill wecom-scrm-bot-skill --query "帮我创建一个员工活码"

# 其余企微私域运营 → 钉 wecom-scrm-intent。覆盖：我的排行、团队业绩、待办、
# 客户与客户群、活码/群发列表与效果、欢迎语、跟进任务列表、标签与人群、会话存档分析、营销文案
magic-agent-cli chat start --skill wecom-scrm-intent --query "查看我的团队业绩"
magic-agent-cli chat start --skill wecom-scrm-intent --query "上个月客户的会话开口率怎么样"

# 其它营销诉求 → 不带 --skill，让营销云自行选能力。
# 覆盖：营销策划、预算分配、会员体系、跨渠道内容包
magic-agent-cli chat start --query "为服饰新品设计一套种子客户试推方案，包含选人标准、推荐话术和效果评估指标。"
```

- 判不准属于哪一类时看诉求对象：**企业微信里的**客户、客户群、员工、活码、群发、标签、会话存档、业绩排行 → 带 `--skill`；跨渠道方案、预算、机制设计 → 不带。
- 已带 `--skill` 时再分：明确是上面六项**创建** → `wecom-scrm-bot-skill`；活码列表、群发详情 / 效果 / 催办 / 停用、欢迎语、跟进任务列表、其它查询与写操作 → `wecom-scrm-intent`。同一个对象由动词区分，对象说不清时先确认，判据见 [企微营销虾范围](references/wecom-assistant.md) 第 2.5 节。
- `--query` 用用户原话，不改写、不拆成多次请求；由营销云识别意图。**技能名只进 `--skill`，绝不写进 `--query`**。通过命令工具正确引用参数，避免 shell 展开。
- 宿主提供有效主会话 ID 时，CLI 自动复用唯一 Magic 会话；主代理和子代理共用绑定，`--session-id` 仅校验一致性。宿主 ID 真正缺失时可兼容执行：指定 `--session-id` 续接已知会话，不指定则新建。兼容模式无法保证 WorkBuddy 与 Magic 会话一一对应，继续任务必须保留 sessionId / runId。空白或无效 ID 仍报错；不得修改环境变量、删除绑定或伪造 ID 绕过校验。
- 历史未绑定任务保留可验证 OAuth 身份时，可用原 runId 续读、作答、取消和下载，不自动认领为当前宿主任务。已有宿主绑定、身份或环境冲突、部分损坏的绑定记录不能降级；缺少可验证身份时到营销云原会话核查，不反复新建分析任务。
- 命令逐行输出 JSON 事件，在**待答、完成、失败**或**约 90 秒的读取窗口结束**时返回；本地命令退出不会取消远端任务。
- 收到 `stream_paused`：任务仍在进行。先向用户展示这一段的新进度——**本窗口带来了新版执行图就把图渲染出来**，没有新版本才只用一两句话说明阶段与工具；再运行事件里的 `next`（`chat watch`）继续，直到待答或终态。不要缩短间隔高频读取，也不要重新 `chat start` 同一请求。

事件含义、展示方式、增量读取与作答契约见 [事件与 HITL 指引](references/events-and-hitl.md)，处理事件前先读它。

## 续读、作答与取消

- 继续读取（断线、读取上限、回答后等待）：`magic-agent-cli chat watch --run-id <runId>`。只看已落盘的新事件：`magic-agent-cli events --run-id <runId> --after-seq <上次 nextAfterSeq>`，立即返回。
- 收到 `input_required`：先按 `dagRef` 核对执行图（有变化或还没展示过就出图，失败就降级），再展示判断所需资料，然后实际调用 AskUserQuestion 让用户作答；图形展示失败不影响作答，照常提问。按指引写回答文件后运行事件 `answerContract.command` 给出的 `chat input` 命令。CLI 会重新核对服务端待答与题目版本，并按交互类型走同一运行内回复或恢复。
- **「执行已暂停：<步骤名>」是可以作答的**（`kind: execution_control`）：服务端给了继续 / 重新执行 / 跳过 / 修改执行计划 / 取消整个计划等选项，照常用 AskUserQuestion 让用户选；选「修改执行计划」要带上用户原话。不要把它说成需要到营销云页面完成。
- `supported: false` 的交互（例如需要逐字段填写的表单）才保持待答，说明需要在营销云页面完成；不要替用户选择或改用别的方式提交，也不要自己编造无法作答的原因。
- 跨轮用户说“继续”：先 `magic-agent-cli chat pending --run-id <runId>` 读取服务端当前待答，不从旧输出重建问题。
- 用户明确要求停止正在执行的任务：`magic-agent-cli chat cancel --run-id <runId>`；只有收到 `cancelled` 才能说已停止。等待回答且 `resumable: false` 时运行仍在执行，可发送取消；`resumable: true` 表示运行已暂停，只能提交用户真实选择的已有拒绝/不执行选项，不要编造答案或自动作答。

## 结果与文件

- `answer` 是最终回复：保留数字、单位、统计时间与口径，不编造缺失数据，未知值保持「—」。命令完成不等于业务结果完整；只收到概要时如实说明。若正文只是已渲染卡片的重复数据或「结果已在卡片中展示」占位说明，按下述卡片总结规则处理，不重复展开。
- `result_card` 是业务结果卡（企微营销虾的结构化查询卡，常常是本轮唯一结果）：成功且含业务数据时，按 [结果呈现规范](references/rendering.md) 使用 `payload` 与 `timeRange` 渲染；`payloadTruncated: true` 时先读取 `dataFile` 中的完整 `payload`。`status: error` 时展示真实错误；选择卡按下文收集真实选择，不套用指标模板。卡片按钮不能在 CLI 中点击，需要操作时请用户到营销云页面完成。`client_action_unavailable` 同样需要到页面完成。
- **业务数据只有 `result_card` 走卡片**。以 `answer` 正文返回的长文本——营销策划案、营销文案、会话存档分析结论、跨渠道内容包——保持 markdown 原样，不要塞进卡片：卡片装不下，也会丢掉行文结构。执行图是另一类内联展示，用 CLI 给的片段，不套结果卡模板。
- **结果卡渲染成功后，与卡片重复的正文只写一句话总结（不超过 100 字）**，不要再用 Markdown 表格或列表把卡片里的数字重复一遍。这条只针对已渲染结果卡里的数据：独立的 `answer` 正文、HITL 决策资料、文件交付说明**不因为展示了执行图或结果卡而压缩**。仅生成 HTML 文件或看到 `fallbackText`，不能声称已在对话中渲染。
- `cardFile` 是同一份数据的完整 HTML 文件，`dataFile` 是原始 JSON。用户要求下载，或内联渲染不可用且需要文件预览时，才用 `present_files` 展示；打开文件预览不等于对话内卡片。默认不附这两个文件。
- 收到 `files_ready` 后调用宿主可用的 `present_files`，传事件中的真实本地路径，不重复展示同一路径；没有该工具时给出路径并说明限制。
- 收到 `file_unavailable` / `files_failed`：说明哪些文件未下载，按 `httpStatus`、`code`、`reason` 和 `message` 处理；修复权限、网络或本地写入问题后，运行 `magic-agent-cli chat files --run-id <runId>`，不重跑分析。OAuth 错误保留 `retryable` / `reauthRequired`，等待续期或恢复原授权后仍只重试文件下载，不能据此重发 `chat start`。相同原因持续失败时停止重复重试，不把下载失败或本地 ID 为空推断为服务端未生成、未注册文件。`completed.fileStatus: failed` 表示分析已完成但文件交付失败，不能宣称全部交付成功。
- `chat files` 通过所属模式的归属及授权检查后，从原会话历史事件补回遗漏的文件定位信息；可验证身份的历史未绑定任务也可恢复。`LEGACY_RUN_OWNER_UNVERIFIABLE` 表示没有可验证的历史身份，`HOST_SESSION_RECORD_INVALID` 表示绑定记录损坏，`ARTIFACT_METADATA_UNAVAILABLE` 表示定位信息无法恢复。按消息到营销云原会话下载，不猜测目录或修改本机状态。`files_none.reason: already_downloaded` 表示已记录文件均已下载；`no_artifacts` 只表示本机任务未收到文件交付记录。
- 内网存储的小文件由 CLI 自动通过营销云正文接口下载；客户端下载前无法解析 HTTPS 存储域名时也会尝试这条路径，不自行访问无法校验的签名地址。若正文超限、被截断，或旧服务端不支持完整历史回放，按错误提示到营销云原会话下载，不改地址校验、不以分批输出正文替代文件交付，也不重新执行分析。
- `dag_snapshot` 按 [结果呈现规范](references/rendering.md) 第三节展示：**每来一版就渲染一版**，原样传 `widgetCode`（`widgetCodeTruncated: true` 时读 `files.widget`），失败就 `present_files` 展示 `files.svg`，再不行用「编号、步骤、状态、直接依赖」表；只采纳更高版本，`notices` 要转达。边界事件的 `dagRef` 指回某一版快照，`freshness: cached` 表示这是上次读到的状态、不是当前进度。

## 企业微信私域运营（补充能力）

用户提到营销虾、企微营销虾、企微互动智能助手、企业微信私域运营，或提出我的排行、团队业绩、待办、客户与客户群、活码、群发、朋友圈、欢迎语、跟进任务、标签与人群、会话存档分析、营销文案等诉求时，先判断是不是六项创建，再转交原话。

- **六项创建钉 `--skill wecom-scrm-bot-skill`**，在对话内补参并由用户确认后提交；六类各自的常见说法、以及同一对象哪些说法不算创建，见 [企微营销虾范围](references/wecom-assistant.md) 第 2.5 节。同一会话内补参、改字段、回复「确认」时继续钉 `wecom-scrm-bot-skill`，Magic sessionId 由 CLI 自动沿用。
- **其余企微私域运营钉 `--skill wecom-scrm-intent`**。加 `--skill` 是因为这些诉求靠意图描述不一定能路由到营销虾；钉住后本轮只走该能力。营销策划、预算分配、会员体系、跨渠道内容包等**不属于企微私域运营**的请求不要加，让营销云自己选能力。
- **说法笼统时会先收到一张选择卡**（如只说「待办」「会话」「发消息」「找人」「创建文档」）：它以带 `actions` 的 `result_card` 到达，按钮在 CLI 里点不了。此时把 `actions` 原文作为选项用 AskUserQuestion 问用户，拿到真实选择后**新起一轮 `chat start`**，`--query` 只传所选能力名原文（如「企微通讯录」「创建员工活码」），人名、时间等槽位从上一轮原话补在后面；`--skill` 仍按上面两条二选一。**第二轮的 `--skill` 不能省**——裸能力名没有业务上下文，漏掉就会掉回通用问答。禁止把出卡前的长原话再发一次，那会再出同一张卡。
- **企微办公域需要先在营销云页面完成企微扫码授权**（通讯录、日程与会议、企微原生待办、消息、邮件、文档与表格、微盘）。未授权时服务端下发二维码卡，CLI 不能代为扫码；如实告知用户去页面授权，不反复重试。
- **个人数据只属于当前授权用户**：「我的 XX」（我的排行、我的客户、我的待办等）由服务端按 OAuth 身份和权限处理。不得指定或伪造其他用户、企业或空间身份；不能把企业级、他人或空的结果说成个人数据。
- 我的与团队、营销待办与企微原生待办、客户与客户群、群发客户与群发朋友圈与给同事发消息、统计时间与任务时间，都是不同口径，分别保持，不合并、不互相替代；表述不清时先确认。
- 写操作必须由用户在提问中真实确认。六项创建走 `wecom-scrm-bot-skill` 的对话补参与确认闸门；欢迎语、批量打标签、群发催办 / 停用等仍走 `wecom-scrm-intent`，可能落到页面。支持范围与已知限制见 [企微营销虾范围](references/wecom-assistant.md)，发起前先读它，不承诺范围外的能力。

## 错误恢复

- `reason: HOST_SESSION_REQUIRED`：该任务已强绑定，当前环境缺少主会话标识；回到原 WorkBuddy 会话操作，不能降级。不手动设置环境变量，不回退到子代理 ID，不反复重连 OAuth。
- `HOST_SESSION_INVALID`：宿主变量已设置但为空白或格式无效；检查宿主注入配置，不能伪造值或静默按兼容模式执行。
- `HOST_SESSION_RUN_MISMATCH` / `HOST_SESSION_OWNER_MISMATCH`：回到原 WorkBuddy 会话及原授权身份、环境处理原任务，不自动新建 Magic 会话。
- `LEGACY_RUN_OWNER_UNVERIFIABLE`：旧任务缺少可验证的授权信息，无法安全恢复；到营销云原会话核查，不用当前凭据补写归属。
- `HOST_SESSION_RECORD_INVALID`：绑定字段损坏或模式矛盾，不能当作未绑定任务；保留原记录供人工核查。
- `HOST_SESSION_ID_MISMATCH` / `HOST_SESSION_BINDING_MISSING` / `HOST_SESSION_STORAGE_INVALID` 等绑定错误：停止操作，保留记录供核查，不通过更换 sessionId 或清理文件恢复。

- `failed` 且 `status: not_sent`、`requestSent: false`：本次业务请求尚未发送，没有创建远端任务。`retryable: true` 时可稍后按原参数重试 `chat start`；`reauthRequired: true` 时先恢复授权。不要删除会话绑定；本次 runId 只可用于本机 `events` 核查，不能 `chat watch`。`HOST_SESSION_NOT_STARTED` 同样表示没有对应的远端任务。
- 其余 OAuth 错误含 `retryable: true`、`reauthRequired: false`：续期正在进行或身份校验暂不可用；稍后用原 `runId` 执行 `chat pending` / `chat watch`，不要断开连接或重新创建任务。提交回答后出现错误时先核对待答状态，不自动重复提交。
- OAuth 错误含 `reauthRequired: true`：按错误说明恢复对应授权环境；重新连接后先续读原任务，不因授权恢复而自动重跑。

- `failed` 且 `status: rejected`：服务端在创建任务前拒绝，按 `httpStatus` 处理——401 授权失效或通道未开启，请用户在连接器面板断开后重新连接；403 没有该空间权限，不自动切换空间；503 暂不可用或暂不接受新任务，稍后再试；400 核对请求内容。不自动重发，也不改用其他通道。
- `failed` 且 `status: start_unconfirmed`，或 `reason: HOST_SESSION_CREATION_UNKNOWN`：创建结果未确认，不能重发原请求、删除绑定或换 ID 重建。保留原 `runId`，可以读取本机 `events` 供核查；缺少 Magic sessionId 时不能续读远端，需在营销云核查。
- `error` 事件含 `AUTH_REQUIRED`：连接尚未完成，请用户在连接器面板连接。
- 命令不存在：请用户更新整个连接器包并重新连接，不从公网安装同名包。