engagement-workflow

/digital-marketing-pro:engagement-workflow — 12 部分互动编排器

脚本位置。 如果宿主未设置 ${CLAUDE_PLUGIN_ROOT}，脚本位于此插件的 scripts/ 文件夹中，与 skills/ 并列。请使用 Python 3.10 或更高版本运行：python；如果找不到 python，则使用 python3（macOS 和许多 Linux 系统）。

此技能使用 12 部分顺序方法编排完整的营销互动。每次品牌互动都会按顺序经过相同的 12 个部分，并在每个阶段生成一组规范文件。

上下文效率

此技能开销较大。对任何引用的文件，先使用 Grep，再使用 Read；然后仅用 offset + limit 读取匹配范围。在打开文件之前，先列出品牌的工作区 ~/.claude-marketing/brands/{slug}/（如果设置了该环境变量，则为 $CLAUDE_PLUGIN_DATA/digital-marketing-pro/brands/{slug}/）。在会话中途重新调用时，跳过已在上下文中的文件。

生成输出前，请先阅读以下参考资料：

• engagement-flow-methodology.md — 完整的 12 部分流程
• two-views-model.md — v1 / v2 架构
• stone-vs-opinion.md — 置信度标注
• decision-matrix-rerun.md — 何时重新运行哪些内容
• update-back-rule.md — 版本控制协议
• living-instruction-file-spec.md — LIF 架构

运行模式

此技能通过 /digital-marketing-pro:engagement 命令系列调用。该命令只是一个轻量路由器——此技能是互动生命周期、检查点协议和各部分交付约定的唯一事实来源。每个子命令都映射到特定的生命周期操作。此技能通过以下方式调用 engagement-state.py 进行持久化：

python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" <subcommand> ...

切勿手动编辑 _engagement.json——始终通过 engagement-state.py 操作。

检查点与恢复（唯一事实来源）

每次耗时较长的互动运行都可以恢复。检查点协议为：初始化运行 → 每完成一个部分就保存 → 完成运行 → 发布到可见输出文件夹。 这样，当运行中断（上下文耗尽、用户取消、机器休眠）时，可以从下一个尚未保存检查点的部分继续，而不是从第 1 部分重新开始。

1. 执行 start 后，在品牌前置条件通过后，打开一个检查点运行，并将其关联到互动状态：

python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" init \
    --brand "{brand_slug}" --workflow engagement --topic "{engagement_id}"

# Record the returned run_id into _engagement.json so resume can find it:
python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" set-checkpoint-run \
    --brand "{brand_slug}" --id "{engagement_id}" --run-id "{run_id}"

set-checkpoint-run 会将 run_id 存储在 _engagement.json 中，从而建立实际的恢复关联（此前从未持久化 run_id）。

2. 每个部分完成并通过质量门槛后，编排器会保存该部分的输出：

python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" save \
    --brand "{brand}" --run-id "{run_id}" \
    --step {part_number} --content-file "{path_to_that_part_deliverable}" --extension md

传入该部分实际交付物的路径（例如，第 3 部分保存核心四份文档的路径；第 8 部分保存增长计划的路径）——绝不要传入其他部分的占位路径。

3. 保存第 5 部分（客户验证）和第 8 部分（增长计划）的交付物之前，运行完整质量门槛检查：

# BLOCKING gate — Part 5 and Part 8 deliverables cannot be checkpointed until this passes
/digital-marketing-pro:check "{path_to_deliverable}" --full --brand {brand}

如果 /digital-marketing-pro:check --full 返回 BLOCKED，请先修复 CRITICAL 问题，再为该部分保存检查点。

4. 完成最后一个部分后，将每件产物发布到用户可见的文件夹并完成运行：

python "${CLAUDE_PLUGIN_ROOT}/scripts/output-publisher.py" publish-run \
    --brand "{brand}" --run-id "{run_id}"

python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" finalize \
    --brand "{brand}" --run-id "{run_id}" --status completed

然后通过 /digital-marketing-pro:output-folder {brand} 告知用户可见输出文件夹的位置。

要恢复已中断的运行，请使用 /digital-marketing-pro:resume——它会重新加载所有已保存的部分，并从下一个尚未保存检查点的部分继续。

状态验证与返工上限

• 在将某个部分标记为完成前，根据清单验证其输出：

  python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" validate-part \
      --brand "{brand}" --id "{id}" --part {N}
  

  此操作会将磁盘上的实际文件与 PART_DEFINITIONS 清单进行比对，并标记缺失的交付物。在 file-tree 中以及执行 next 之前使用。

• 修复部分初始化的项目目录（而不是因目录非空而崩溃）：

  python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" init --repair \
      --brand "{brand}" --id "{id}"
  

  --repair 会为仅包含部分状态的目录补全规范目录树和状态文件。

• **v2 重新运行次数上限：**每个部分最多允许进行 2 轮 v2 重新运行，除非用户明确覆盖此限制。轮数存储在 _engagement.json 中。如果某个部分将超过 2 轮，请停止并询问用户是否明确批准进一步重新运行（并在状态中记录此覆盖）。这样可以避免无限循环重新运行。

子命令

/digital-marketing-pro:engagement start <brand-slug> <engagement-id>

**用途：**初始化新的项目。

步骤：

1. 验证品牌资料是否存在于 ~/.claude-marketing/brands/{brand-slug}/profile.json。如果不存在，提示用户先运行 /digital-marketing-pro:brand-setup。
2. 运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" init --brand {brand-slug} --id {engagement-id}。
3. 确认目录树已创建，并告知下一项所需操作（第 1 部分信息收集）。
4. 一次询问一组问题，引导用户完成第 1 部分的事实与观点信息收集。

第 1 部分信息收集问题（按此顺序询问）：

事实 — 客户确定知道的内容：

1. 公司基本情况：成立年份、员工人数、总部所在地、业务覆盖地区
2. 商业模式：收入来源、定价层级、主要产品／服务类别
3. 当前营销情况：正在使用的渠道、每月营销支出、当前可衡量的 KPI
4. 技术栈：CRM、电子邮件服务提供商、分析配置、广告账户
5. 客户规模：客户数量、最大的具名客户、已知的平均订单金额

对于每项事实，请记录：

• 事实本身
• 来源（用户如何得知／哪个文档予以确认）

通过以下命令保存每项内容：

python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" add-stone-fact --brand {slug} --id {id} --fact-json '{"category":"...","fact":"...","source":"..."}'

观点 — 客户的看法：

1. 品牌定位：客户如何描述自己在市场中的定位？
2. 客户群：他们认为自己的客户是谁？客户为何购买？
3. 竞争对手：他们认为主要竞争对手是谁？
4. 增长机会：他们认为最大的机会在哪里？
5. 哪些方面有效：客户认为哪些营销活动有效？
6. 哪些方面无效：客户认为哪些方面无效？

对于每项观点，请记录：

• 假设
• 客户为其提供的依据（可能是直觉、轶事或部分数据）
• 研究问题 — 无偏见的研究需要验证或证伪什么？

通过以下命令保存每项内容：

python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" add-opinion --brand {slug} --id {id} --hypothesis-json '{"category":"...","hypothesis":"...","client_evidence":"...","research_question":"..."}'

**第 1 部分完成后：**通过 mark-part-completed --part 1 将第 1 部分标记为已完成，并建议用户继续进行第 2 部分（外部研究）。

/digital-marketing-pro:engagement next [brand] [id]

**用途：**进入下一部分。

步骤：

1. 通过 engagement-state.py status 读取项目状态
2. 确定当前部分以及下一个尚未完成的部分
3. 向用户确认当前部分是否确实已完成（不要自动推进 — 请先询问）
4. 用户确认后，将当前部分标记为已完成，并推进 current_part 指针
5. 简要告知用户新部分的要求

/digital-marketing-pro:engagement status [brand] [id]

**用途：**显示项目状态。

步骤：

1. 运行 engagement-state.py status — 获取完整状态
2. 读取 Living Project Instruction File 的标题部分
3. 整理为易读的摘要：
   • 项目：品牌 + id + 开始日期
   • 当前部分：部分名称 + 已进行天数
   • 已完成部分：列表
   • 待处理部分：列表
   • 尚未处理的重新运行决策：数量
   • LIF 最近更新时间：日期
4. 如果项目存在需要解决的未处理事项，列出这些事项

/digital-marketing-pro:engagement file-tree [brand] [id]

用途： 显示项目目录的文件树。

步骤：

1. 运行 engagement-state.py file-tree
2. 格式化为缩进树状结构
3. 标出规范结构中缺失的文件。使用 engagement-state.py validate-part --part {N} 对照 PART_DEFINITIONS 清单，比较每个已完成部分的实际文件（例如，如果第 3 部分标记为已完成，但缺少 3.1-business-and-sbu-analysis.md，validate-part 会明确标出，而无需人工检查）。

/digital-marketing-pro:engagement validate [brand] [id]

用途： 运行第 5 部分的客户验证流程。

前置条件： 第 2、3、4 部分必须已完成。

步骤：

1. 验证前置条件（第 2、3、4 部分已完成）
2. 调用 client-validation-document 技能——它会生成第 5 部分的交付成果：一份结构化文档，其中列出 v1 中的每项发现，并提供 ACCEPT/REJECT/EDIT/DEFER 选项
3. 在将第 5 部分的交付成果发送给客户前，运行完整的质量门禁： /digital-marketing-pro:check "{part5_path}" --full --brand {brand}。如果返回 BLOCKED，先修复 CRITICAL 问题（此门禁是第 5 和第 8 部分交付成果的强制要求）。
4. 用户审阅并提供决策后，按照决策矩阵的类别，将其解析为触发条件列表
5. 运行 engagement-state.py decision-matrix --triggers "{comma-separated}"，计算 v2 重跑计划
6. 向用户展示重跑计划
7. 将第 5 部分标记为已完成；用户批准重跑计划后，进入第 6 部分

/digital-marketing-pro:engagement re-run-decision [brand] [id]

用途： 应用决策矩阵，计算 v2 重跑项。

步骤：

1. 阅读第 5 部分客户验证文档
2. 将被拒绝或编辑的发现归类为决策矩阵中的触发条件
3. 显示触发条件和计算出的重跑项
4. 估算每次重跑的成本（大致的令牌数量）
5. 等待用户批准——用户可以接受、修改（跳过部分重跑项或添加其他项），也可以拒绝
6. 通过 engagement-state.py record-rerun-execution 记录已执行的计划

/digital-marketing-pro:engagement update-back [brand] [id] --doc <doc-id> --reason <reason>

用途： 在第 7 部分之后应用回写规则，提高源文档版本号。

前置条件： 用户已起草修正后的文档内容。

步骤：

1. 阅读文档的当前版本
2. 与用户确认修正内容（按照回写规则的验证步骤）
3. 通过 engagement-state.py bump-version --doc {id} --reason "{reason}" 提高版本号
4. 保存新版本文件，并在标题中注明 v(prev) → v(new) 的变更
5. 通过 lif-log-change 更新动态项目指令文件——它现在会将变更追加到 living-instruction-file.md 并刷新标题日期，因此动态项目指令文件会立即反映修正内容
6. 找出可能需要审查的下游文档，并将其加入项目的审查队列

/digital-marketing-pro:engagement lif-show [brand] [id]

用途： 显示动态项目指令文件。

步骤： 运行 engagement-state.py lif-show，并将 Markdown 输出整理为易读格式。

/digital-marketing-pro:engagement list-engagements [brand]

用途： 列出所有项目（可按品牌筛选）。

步骤： 运行 engagement-state.py list-engagements --brand {slug}，并将结果整理为表格。

生产快捷命令

该命令系列还提供了四个生产快捷命令，可直接路由到负责生成各部分内容的技能（详见下文的 各部分生产目标）。这些命令与命令接口一一对应：

• /digital-marketing-pro:engagement four-core <brand> <id> [--doc 3.X] [--view v2] [--combined] — 第 3 部分，调用 four-core-documents 技能
• /digital-marketing-pro:engagement growth-plan <brand> <id> — 第 8 部分，调用 growth-plan 技能
• /digital-marketing-pro:engagement yearly-planner <brand> <id> — 第 8 部分的配套命令，调用 yearly-planner 技能
• /digital-marketing-pro:engagement loop <brand> <id> — 第 12 部分，调用 continuous-improvement-loop 技能

各部分生产目标

每个部分均由真实存在的 Agent 和技能生成。本编排器会将任务分派给下方的目标——不存在名为 external-research / preparation-documents / channel-strategy-fanout / execution-artefacts / ai-creative-instructions 的包装技能；这些技能从未存在。请使用此处列出的确切目标：

部分	实际目标
1	（此技能——直接在此处完成接入）
2	Agent market-intelligence + competitive-intel；技能 audience-intelligence（作为技能调用）；参考资料 compliance-rules.md（作为上下文加载）
3	技能 four-core-documents（生成 3.1、3.2、3.3、3.4）
4	命令 competitor-analysis + 技能 audience-intelligence + Agent market-intelligence
5	技能 client-validation-document
6	重新运行时，调用技能 four-core-documents 并使用 --view v2
7	技能 content-engine + campaign-orchestrator + analytics-insights
8	技能 growth-plan + yearly-planner
9	各渠道技能：paid-advertising、aeo-geo、social-strategy、seo-plan、email-sequence（每个渠道类别对应一个）
10	技能 content-engine（执行／输出模式）
11	技能 content-engine + ad-creative + video-script（创意简报）；素材渲染由你自己的创意工具完成（设计团队、AI 图像／视频工具或已连接的设计平台），之后使用 c2pa-metadata 为成品素材签名
12	技能 continuous-improvement-loop

并行分派

这项工作中的若干部分包含彼此独立的子任务，应通过在同一条消息中调用多个 Task 工具并行分派，而不是按顺序执行。并发处理独立子任务的速度远快于逐一执行；实际耗时会因工作深度、模型和速率限制而异。并发子 Agent 数量应控制在少数几个（约 3–8 个）；超过此数会受到 API 速率限制，收益也会降低；少于 3 个则没有可并行处理的任务。

**成本说明：**总 token 用量大致相同（完成的工作相同），但由于每个并行子 Agent 都会重新加载上下文，按轮次计费的输入成本会略有上升。

适合并行分派的部分：

部分	可并行的工作	分派方式
Part 2 — 外部研究	市场规模、竞争格局、客户信号、监管环境——彼此互不依赖	并行调用 market-intelligence Agent 和 competitive-intel Agent 的 Task；将 audience-intelligence 作为技能调用；将 compliance-rules.md（参考文件）加载为上下文，而不是作为子 Agent
Part 4 — 竞争 + 客户 + 市场	四份文档（4.1、4.2、4.3、4.4）彼此独立——仅依赖 Part 2	在同一条消息中分派四个对应的子 Agent
Part 9 — 渠道策略分派	7 个系列中最多包含 17 份渠道文档。在系列 1（搜索与活动）和系列 6（网站 + 衡量）完成后，系列 2（付费平台）、3（自然流量与网红）、4（市场平台与 CRM）、5（内容/ATL/BTL/公关）彼此独立	顺序：F1 →（F2 ∥ F3 ∥ F4 ∥ F5 并行）→ F6 → F7。中间批次是在同一条消息中并行调用四个 Task。
Part 10 — 执行素材	各渠道的广告文案、帖子文案、标题、CTA——各渠道彼此独立	每个渠道并行分派一个子 Agent
Part 11 — AI 创意说明	视觉素材简报——各素材彼此独立	按素材并行分派

必须按顺序执行的部分（存在严格的数据依赖）：

• Part 1 → Part 2（信息收集结果决定研究范围）
• Part 3 → Part 4（四份核心文档为竞争/客户/市场分析提供依据）
• Part 5 → Part 6（客户验证决定哪些文档需要重新运行 v2）
• Part 7 → Part 8（准备文档为增长计划提供依据）
• Part 8 → Part 9（增长计划决定渠道分派）

跨环节规则：

1. 绝不能分派需要同时写入同一文件的并行 Agent——应按输出文件拆分任务。
2. 每个并行子 Agent 都会获得工作项目标识和 LIF 路径，以便读取共享上下文，但只能写入自己的编号分部子目录（01-… 12-…）。
3. **子 Agent 绝不能修改工作项目状态。**子 Agent 不得调用 lif-log-change、mark-part-completed、bump-version 或任何其他 engagement-state.py 写入操作，也不得触碰 _engagement.json 或 living-instruction-file.md。这些文件采用无锁的读取-修改-写入方式；并发写入会导致更新丢失。每个子 Agent 只能将输出保存为分部文件。并行批次完成后，只有编排器可以应用状态变更——每个批次调用一次 lif-log-change，并根据需要调用 mark-part-completed / bump-version——随后在进行下一步前重新读取 LIF。
4. 如果并行批次中途失败，不会自动回滚失败子 Agent 的输出——只需重新分派失败的子 Agent；已成功完成的同伴任务仍然有效。

对于 12 部分流程之外的多维命令（例如 /digital-marketing-pro:competitor-analysis、/digital-marketing-pro:seo-audit、/digital-marketing-pro:content-engine），也适用相同模式——通过在同一条消息中调用多个 Task，并行分派彼此独立的维度。

在单次对话中推进一项合作项目

上下文窗口较大的模型可以在一个工作会话中处理一项合作项目的大部分内容——需求收集、外部调研、四份核心文档（61 个步骤）、竞争对手／客户／市场分析、客户验证、选择性重新运行 v2、准备文档、增长计划 + 年度规划器、渠道扩展、执行产物、创意简报以及持续改进循环——（完整的合作项目通常会产出 50–60 份规范文档）。

检查点 + 持久化模式始终是默认做法——务必遵循。 即使所有内容都能放进一次对话中：

• engagement-state.py + checkpoint-manager.py 仍然是权威记录来源：审计轨迹、跨对话恢复，以及多用户／多天的连续性都依赖持久化状态。
• 不要因为“所有内容都在上下文里”就跳过 LIF 更新或状态写入。中断仍会丢失内存中的工作，而接手合作项目的队友读取的是持久化状态，而不是你的对话。
• 单次对话唯一带来的便利，是会话中途无需重新读取那么多文件，因为它们已经在上下文里。这并不意味着可以不持久化、不创建检查点或不更新 LIF。

质量规范

1. 绝不手动编辑 _engagement.json。 始终通过 engagement-state.py 操作。
2. 绝不删除 v1。 生成 v2 时，两者都要保留。
3. 源文档发生变化时，始终更新 LIF。 使用 lif-log-change——它会将内容追加到 living-instruction-file.md 的变更日志部分并刷新标题日期，确保 LIF 始终保持最新。
4. 始终为每条事实标注来源。 客观事实应引用验证来源；观点假设应引用客户提供的证据。
5. 绝不自动推进部分。 由用户明确确认部分完成。
6. 始终并行处理独立工作。 当一个 Part 有 2 个或更多独立子任务时（参见上文的并行调度），在一条消息中通过多个 Task 调用同时分派。按顺序分派独立工作会浪费实际用时和 API 调用次数。
7. 未经用户批准，绝不自动执行 v2 重新运行。 展示计划，获得批准后再执行。每个部分最多重新运行 v2 两轮，除非用户明确覆盖此限制（记录在状态中）。

示例

示例：开始一项新的合作项目

User: I want to start a new engagement for Acme Corp this quarter.

Skill response:
1. Verify Acme has a brand profile (slug: acme-corp). Found.
2. Initialise engagement: engagement-state.py init --brand acme-corp --id 2026-q2
3. Engagement directory created at ~/.claude-marketing/brands/acme-corp/engagements/2026-q2/
4. Walk Part 1 intake. Begin with Stone questions:
   "Let's start with what we know for certain. What year was Acme founded? Where is it headquartered? How many employees today?"
5. (User answers; each fact captured via add-stone-fact)
6. Move to Opinion questions:
   "Now let's capture what you believe but haven't formally validated. How would you describe Acme's positioning in the market today?"
7. (User answers; each hypothesis captured via add-opinion)
8. Mark Part 1 completed. Advise: "Part 1 is complete. The unbiased External Research (Part 2) is next — recommend running it now or scheduling it for the next session."

示例：合作项目进行中的状态检查

User: Where are we on the Beta Industries engagement?

Skill response:
- Reads engagement-state.py status --brand beta-industries --id 2026-h1
- Shows:
  Engagement: beta-industries / 2026-h1
  Started: 2026-04-01 (32 days in)
  Current part: Part 9 — Channel Strategy Fan-out (in progress)
  Completed parts: 1, 2, 3, 4, 5, 6, 7, 8
  Pending parts: 9 (in progress), 10, 11, 12
  Open re-run decisions: 1 (Part 6 v2 re-runs in progress)
  Open items requiring resolution: 2 (LinkedIn Ads CPL forecast pending; Q3 budget envelope pending)
  LIF last updated: 2 days ago
  Next required action: complete remaining Part 9 channel docs (5 of 9 complete)

示例：应用决策矩阵

User: We just finished Part 5 client validation. The client rejected our positioning recommendation and added two new competitors. What re-runs do we need?

Skill response:
1. Categorise the changes:
   - Two new competitors → trigger "competitors_changed"
   - Positioning rejected → trigger "positioning_changed"
2. Run engagement-state.py decision-matrix --triggers "competitors_changed,positioning_changed"
3. Output the triggered re-runs:
   Triggered re-runs: 3.1, 3.2, 3.3, 3.4, 4.1, 4.2
   (competitors_changed triggers all four Core Docs + 4.1 + 4.2; positioning_changed adds 3.3 which is already in scope)
4. Estimate token cost: ~85K tokens for the full re-run set
5. Ask: "Approve all? Modify? Skip any?"
6. On user approval, mark Part 6 started and invoke four-core-documents skill with view=v2 for each triggered doc

示例：Update-Back 修正进行中

User: We've been live for two months. Q1 channel data shows our actual CAC for Segment X is INR 4,800 — but Core Doc 3.1 v2.0 had it estimated at INR 3,000. Need to update.

Skill response:
1. Validate the correction: 60+ days of data, statistically meaningful sample. ✓
2. Read current 3.1 v2.0
3. Bump version: engagement-state.py bump-version --doc 3.1 --reason "Segment X CAC corrected from INR 3,000 to INR 4,800 based on Q1 channel data"
4. Save 3.1 v2.1 with header note: "v2.0 → v2.1 changes: Section 4 (Unit Economics) — Segment X CAC corrected. LTV:CAC drops from 4.0 to 2.5; below 3.0 health threshold."
5. lif-log-change --section "Recent Corrections" --summary "Segment X CAC corrected to INR 4,800. Channel mix for Segment X under review."
6. Identify downstream review needed: Core Doc 3.4 (DMFlow) channel allocation for Segment X may need revision
7. Add to engagement review queue

相关技能

• four-core-documents — 生成 Part 3 的交付成果
• client-validation-document — 生成 Part 5 的交付成果
• growth-plan + yearly-planner — 生成 Part 8 的交付成果
• continuous-improvement-loop — 处理 Part 12

相关参考资料

• engagement-flow-methodology.md
• four-core-documents-spec.md
• decision-matrix-rerun.md
• update-back-rule.md
• living-instruction-file-spec.md
• stone-vs-opinion.md
• two-views-model.md