#Task Playbook 改进建议

Historical research / Superseded（2026-07-15）：本文记录旧 Action Plan/prompt 问题，不是现行 Task/AI contract。请以 Task System Design 为准。

#背景

Tasks 页面里的 Action Plan 目前按 playbook 结构展示：

• What to do
• Why this matters
• How to do it
• You can offer
• Avoid
• When you're done
• Escalate

但当前数据并不是一份真正的 AI-generated task playbook。现有 task_playbooks.content 大多由 suggestedActions 和静态 task type guidance 派生，导致 What to do 和 How to do it 经常重复，You can offer / Avoid / When you're done 也不是真正针对当前客户和任务生成的内容。

这个问题的改进重点是 Task Playbook 生成链路。

#应该改哪个 prompt

主改：

• oliver-proposals/prompts/06-task-playbook-system-prompt.txt

原因：

• 06 的职责是“针对一个已存在的 selected task 生成 front-desk execution playbook”。
• 它明确不负责 create / update / close / reclassify task。
• 它正好对应 UI 中的 Action Plan / Playbook tab。
• 它的输出结构已经包含 playbook 需要的字段：
  • primaryAction
  • recommendedSteps
  • optionsYouCanOffer
  • avoid
  • closeGuidance
  • managerEscalation

配合改：

• 05-task-decision-system-prompt.txt

原因：

• 05 负责决定是否 create / update / close task，并输出 taskDecisions[]。
• 05 里的 suggestedActions 应该继续作为“task recommendation / objective”，但不应该承担完整 playbook 的职责。
• 如果 task 卡片、列表摘要、task 创建质量不够好，可以改 05。
• 如果要修 How to do it、You can offer、Avoid、When you're done，应该改 06。

不应该主改：

• 04-contact-profile-system-prompt.txt
  • 它负责客户画像，不应该创建 task，也不应该生成 task playbook。
• 01-triage-system-prompt.txt
  • 它只负责是否进入后续分析。
• 02-classification-system-prompt.txt
  • 它负责 call 分类。
• 03-coaching-system-prompt.txt
  • 它负责 coaching，不负责 staff task execution。

#当前 live 链路的问题

当前代码中的 writer 位于：

• callytics-infrastructure/lambda/contacts-analyzer/src/infrastructure/neon-repository.ts

当前逻辑大致是：

const recommendedSteps =
  params.suggestedActions.length > 0
    ? params.suggestedActions.map(formatSuggestedStep)
    : [params.reason];

return {
  primaryAction: recommendedSteps[0] ?? params.reason,
  recommendedSteps,
  optionsYouCanOffer: [],
  avoid: [],
  closeGuidance,
  ...
};

问题：

• primaryAction 直接取 recommendedSteps[0]。
• recommendedSteps 又是从 suggestedActions 拼出来的。
• optionsYouCanOffer 永远写 []。
• avoid 永远写 []。
• closeGuidance 来自静态 TASK_PLAYBOOK_GUIDANCE[typeCategory]。
• managerEscalation 是基于 close guidance 文案是否包含 manager 的固定补充。

所以当前 task_playbooks.content 不是独立生成的 playbook，而是 suggestedActions 的衍生物。

#目标数据边界

#05 Task Decision 应该产出什么

05 只应该回答：

• 是否需要创建 task；
• 是否需要更新 existing task；
• 是否需要关闭 existing task；
• task 的 typeCategory；
• task 的 staff-facing suggestedActions；
• task 创建 / 更新 / 关闭的原因。

05 的 suggestedActions 应该是“任务目标级建议”，例如：

Manager callback to understand the cancellation reason and offer playbook-approved save options; close if retained or cancellation is processed.

它不应该输出完整执行 playbook。

#06 Task Playbook 应该产出什么

06 应该在一个 selected task 已经存在之后，基于 task + contact + recent calls/messages + optional store playbook，生成可执行 playbook。

它应该回答：

• staff 现在应该做什么；
• 为什么这件事重要；
• 具体怎么做；
• 可以给客户什么选项；
• 什么话术或动作要避免；
• 什么时候 close；
• 什么时候 keep open；
• 是否需要 manager escalation。

#建议的 PlaybookContent 语义

#primaryAction

一句话说明当前 staff 该做的核心动作。

要求：

• 简短；
• 目标明确；
• 不包含长篇解释；
• 不应该和第一条 recommendedSteps 完全相同。

示例：

"primaryAction": "Call Jessica back today to handle the cancellation risk and try approved save options before processing cancellation."

#whyThisMatters

建议新增字段，或明确从 task/suggestion reason 映射。

用途：

• 解释业务风险或机会；
• 说明为什么这条 task 需要现在处理；
• 不应该混入执行步骤。

示例：

"whyThisMatters": "Jessica has explicitly requested cancellation and has not had a live retention conversation yet. A same-day manager callback may preserve recurring revenue or at least prevent a poor cancellation experience."

如果暂时不改 DB schema，可以继续由前端用：

• task.action_needed_reason
• task_suggestions.content.reason
• legacy task.suggested_actions[].reason

但长期最好让 playbook artifact 自带 whyThisMatters。

#recommendedSteps

真正的步骤，不是把 suggestedActions 再拼一遍。

要求：

• 2–5 条；
• 每条都是具体操作；
• 顺序可执行；
• 可以包含简短话术；
• 不重复 primaryAction。

示例：

"recommendedSteps": [
  "Review recent notes and confirm whether cancellation reason is schedule, injury, price, or experience.",
  "Call Jessica and open with: \"I saw your cancellation request and wanted to understand what changed before we process anything.\"",
  "If the reason is schedule or temporary absence, offer approved freeze or downgrade options from the studio playbook.",
  "If she still wants to cancel, explain next steps clearly and document the reason before closing the task."
]

#optionsYouCanOffer

只列出 prompt / store playbook / policy 明确允许的选项。

要求：

• 不编造价格；
• 不编造 promotion；
• 不编造 manager approval；
• 如果缺少具体 policy，用 “use approved studio playbook” 兜底。

示例：

"optionsYouCanOffer": [
  "Freeze option if allowed by studio policy",
  "Downgrade or schedule adjustment if available",
  "Manager review for policy exception"
]

#avoid

列出当前场景下最容易犯的错误。

要求：

• 针对当前 task / customer；
• 不要只给通用销售建议；
• 可以包括 forbidden wording。

示例：

"avoid": [
  "Do not say \"I understand you want to cancel\" as the opener because it confirms the cancellation path.",
  "Do not promise refunds, freezes, or rates unless they are approved in the store playbook.",
  "Do not close the task after leaving one voicemail if no live retention conversation happened."
]

#closeGuidance

应该从静态 type guidance 升级为 task-specific completion criteria。

建议结构：

"closeGuidance": {
  "closeWhen": "Close when the customer is retained, cancellation is fully processed, or outreach path is exhausted according to policy.",
  "keepOpenWhen": "Keep open if staff only left voicemail, sent SMS, or is waiting on manager approval.",
  "suggestedCloseResult": "cancel_saved"
}

#managerEscalation

不要再用 “close guidance 包含 manager” 这种字符串规则派生。

应该由 06 直接判断。

建议结构：

"managerEscalation": {
  "needed": true,
  "reason": "Cancellation save may require manager-approved freeze, downgrade, or policy exception."
}

#建议的实施路径

#Phase 1：前端降噪

目的：避免当前 UI 继续显示明显重复内容。

建议：

• 如果 recommendedSteps[0] 与 primaryAction 相同或高度相似，隐藏第一条 step 并对剩余 steps 重新索引，避免 UI 渲染出现序号断层。
• 如果没有剩余 step，则隐藏 How to do it。
• 保留 What to do 和 Why this matters。
• 把 You can offer / Avoid 标记为静态 guidance，或暂时弱化展示。

优点：

• 不依赖 infra 改动；
• 可以立即改善 UI；
• 不改变数据 contract。

#Phase 2：接入 06 Task Playbook 生成链路

目的：让 task_playbooks.content 真正来自 06 prompt，而不是从 suggestedActions 派生。

建议：

• 在 callytics-infrastructure 中增加 task playbook generation step。
• 输入：
  • selected task；
  • task suggestedActions；
  • task reason；
  • contact profile；
  • recent calls/messages；
  • relevant store playbook / OTF playbook guidance；
  • previous task close history。
• 输出：
  • PlaybookContent。
• 写入：
  • task_playbooks.content。

需要注意：

• 05 仍然负责 task mutation。
• 06 只负责 playbook artifact。
• 06 不能 create / update / close task。
• 06 输出失败时，可以 fallback 到当前静态 writer，避免影响 task 创建主链路。

#Phase 3：收紧 schema

目的：让 UI 字段和 AI 输出字段一一对应。

建议把 PlaybookContent 从当前 string-only shape 升级为更结构化 shape：

interface PlaybookContent {
  primaryAction: string;
  whyThisMatters?: string;
  recommendedSteps: string[];
  optionsYouCanOffer: string[];
  avoid: string[];
  closeGuidance: {
    closeWhen: string;
    keepOpenWhen: string;
    suggestedCloseResult?: string;
  };
  managerEscalation: {
    needed: boolean;
    reason: string;
  };
}

如果为了兼容现有前端和 API，也可以先保持旧 shape：

interface PlaybookContent {
  primaryAction: string;
  recommendedSteps: string[];
  optionsYouCanOffer: string[];
  avoid: string[];
  closeGuidance: string;
  managerEscalation?: string;
}

但即使用旧 shape，也应该让内容由 06 prompt 生成，而不是从 suggestedActions 拼接。

#06 prompt 本身的建议改动

当前 06-task-playbook-system-prompt.txt 方向是对的，但需要强调以下点：

1. primaryAction 必须是目标，不是步骤。
2. recommendedSteps 必须是独立执行步骤，不得重复 primaryAction。
3. optionsYouCanOffer 只能来自 prompt / store playbook / approved policy。
4. avoid 必须针对当前客户和任务，不要泛泛而谈。
5. closeGuidance 必须明确 close vs keep open 的边界。
6. managerEscalation 必须由场景判断，不得用关键词派生。
7. 当输入信息不足时，明确写 “use approved studio playbook”，不要编造。

建议在 06 prompt 的 OUTPUT FORMAT 后增加校验规则：

Field separation rules:
- primaryAction is the one-sentence objective.
- recommendedSteps are execution steps and must not repeat primaryAction.
- optionsYouCanOffer must only include approved or explicitly provided options.
- avoid must name concrete mistakes likely in this task.
- closeGuidance must define closeWhen and keepOpenWhen.
- managerEscalation must be based on authority/policy/risk, not keyword matching.

#05 prompt 的配合建议

05 不需要生成完整 playbook，但应该继续保证 suggestedActions 质量。

建议保留/强化：

• suggestedActions.action 必须说明 channel、objective、evidence、close condition；
• 不要输出 generic call back / send SMS；
• 不要编造价格、promotion、policy；
• 不要用 suggestedActions 代替完整 playbook。

可以在 05 中补一句边界：

Do not output detailed playbook steps, offer lists, avoid lists, or close guidance. Those are generated by the downstream Task Playbook prompt.

这样 05 和 06 的职责会更清楚：

• 05：是否应该有 task，以及 task 的目标是什么。
• 06：已有 task 应该怎么执行。

#最终判断

这个问题本质是 Task Playbook artifact 没有真正生成，不是单纯 UI 字段读错。

正确方向：

1. 短期：Studio Web 避免重复展示。
2. 中期：callytics-infrastructure 接入 06-task-playbook-system-prompt.txt。
3. 长期：让 task_playbooks.content 的 schema 和 UI 结构稳定对齐。