Retaintive

    Task 生命周期（Prompt 设计视角）

    Historical research（2026-07-23 校准）：本文基于 2026-05 prompt snapshot，不能代表 current code 或未来设计。当前 Task V2 parity 和 Task V2+ 路线见 工程审计与实施基线；Task V3 proposal 尚未 finalized。

    本文从四个 AI prompt 的实际逻辑反推 Task 的整个生命周期——即「prompt 是怎么设计 Task 的」，与 Task 生成、更新与关闭机制（产品设计视角）互补。

    来源：基于 2026-05 四 prompt 改动版（triage / classification / coaching / contact-analyzer）逐句提取。

    Prompt 是 AI 行为的最终权威；本文如实记录 prompt 怎么写，不替 prompt 做产品判断。文末「与现有 spec 的差异」标出了 prompt 与设计文档对不上的地方。

    一、全景：四个 prompt 的 Task 分工

    Task 设计高度集中在 contact-analyzer（99 处提及）。其余三个 prompt 对 Task 只做一件事——显式声明「我不碰 Task」，这是刻意的职责隔离。

    Prompt层级对 Task 的设计
    Triage入口闸门只输出 worth_analyzing——这是 call analysis 管道的触发条件（决定这通要不要进 Classification / Coaching / Contact Analyzer），与 task 无直接关系：prompt 原文明确「不是 coaching 触发器，本身不得创建 task、改 lifecycle、改 lead 状态」
    Classification单通分析完全不创建/关闭 task；只输出 follow_up.needed 信号（见下）供下游用
    Coaching单通分析只产出员工话术反馈，「不得创建 task、改 lifecycle、清 DNC、决定跟进归属」
    Contact Analyzer跨通话分析唯一产出 Task 的 prompt：taskDecisions[] 决定 create / update / close

    两条核心设计原则：

    1. Task 不在「单通电话」层产生，在「跨通话 + SMS + 历史」层产生。单通信息不足以判断一个「未解决的人工工作目标」。

    2. Task 由「未解决的目标」驱动，不由「事件」驱动——原文出自 contact-analyzer prompt § TASK LIFECYCLE DECISION FRAMEWORK：

      A task represents one open human-work objective for one contact. Do not create tasks from events alone. First identify the unresolved objective staff can act on.

      For every new call, SMS, voicemail, lead record, or system event, decide:

      1. Does this event create a specific customer-level human-work objective?
      2. Is that objective still unresolved?
      3. Can staff action change the business outcome?
      4. Is there already a pending task for the same objective?
      5. Is the contact blocked from outreach or outside this workflow?

    二、上游信号 → 下游决策

    上游三个 prompt 不下结论，只给 contact-analyzer 喂信号；contact-analyzer 才把信号变成 Task 决策。

    上游 prompt喂给下游的信号性质
    Triageworth_analyzing = true/falsecall analysis 的触发条件——决定这通要不要进 Classification / Coaching / Contact Analyzer 继续分析。与 task 无直接关系（不创建 task、不触发 task 决策）
    Classificationfollow_up.needed = yes/no + reason 码Task 触发信号之一
    ClassificationDNC/STOP、wrong-number、corporate/vendor 写进 summary/evidence双用途信号：让 contact-analyzer 既阻止建新 task，也关闭已有 pending task（下方有详表）
    Coaching（无）coaching 反馈不进入 task 决策

    Classification 的 follow_up reason 码（三选一，禁止自创）：

    reason 码触发条件
    no_cc_captured该销售/intro 电话需要捕卡但本通未成功
    needs_manager_approval员工升级给经理 / 客户要求管理层
    complaint_feedback客户表达不满或投诉

    完整的 task 触发信号集合

    follow_up.needed 是最显式的一条，但 contact-analyzer 还从这些地方读信号做决策：

    来源信号
    RECENT CALLS 结构化字段（classification 产物）outcome.result(booked / cancelled / pending_follow_up)、category / subcategory、customer_profile.type(检测 corporate/vendor)、credit_card_captured
    RECENT MESSAGES（SMS / voicemail）客户主动回复表意（高意向）、STOP / UNSUBSCRIBE 关键词（DNC）
    系统事件lead 进入、booking 状态变化、payment 失败
    联系人当前状态（Contacts 快照）lifecycleStage(lead/member/churned)、leadStatus、已有 doNotContact
    PENDING TASKS / RECENTLY CLOSED TASKS同类 task 是否已存在 / 最近刚关过（防重复 + 影响 priority）

    双用途关闭信号

    DNC/STOP、wrong-number、corporate/vendor 这 3 类信号既阻止建新 task，也关闭已有 pending task（closeResult 是关键）：

    信号对新 task对已有 pending task
    DNC / STOP不建 outreach task关掉，closeResult = do_not_contact
    wrong-number不建 task关掉，closeResult = wrong_number
    corporate/vendor不建 fitness task关掉（如果之前误建），closeResult = other

    prompt 原文（DNC 段）：close existing pending outreach/customer-workflow tasks with closeResult = do_not_contact when a matching taskId is shown

    Per-Call AI（Pipeline 1）设 follow_up_needed=yes 还会直接触发 Pipeline 2（contact-analyzer）运行——触发机制详见 Task 生成机制 §一。

    三、Contact Analyzer 的 Task 决策机制

    定位：每日批处理（或员工 Refresh AI），读全量通话 + SMS + 历史 + 当前 Contacts 快照，输出 taskDecisions[] 写入 Tasks 表。一个 Task = 一个联系人的一个开放的人工工作目标。

    3.1 决策框架：5 问 → 4 路径

    对每一个新通话 / SMS / voicemail / lead 记录 / 系统事件，先问 5 个问题：

    1. 这个事件是否产生了一个客户级的人工工作目标？
    2. 该目标是否仍未解决？
    3. 员工行动能否改变业务结果？
    4. 同一目标是否已有 pending task？
    5. 联系人是否被 block（DNC / 不属于本流程）？

    然后为该目标选恰好一条路径：

    路径条件
    CREATE有新的未解决目标，且无同类 pending task
    UPDATE同一目标仍开放，新事件改变了时机 / 优先级 / 证据 / 下一步
    CLOSE目标完成 / 失效 / 耗尽 / 被 DNC、wrong-number 阻断 / 不再属于本流程
    NO CHANGE新事件没带来有用的 task 信息——什么都不动

    NO CHANGE 这条最容易被忽略,但它正是 prompt 反复强调的"不要见到事件就反射性建 / 改 task"。4 条路径互斥,prompt 原文要求 "choose exactly one task path for that objective"(每个目标恰好选一条)。

    外呼电话/短信只算外联尝试，不自动完成任务。禁止普遍套用「一次有效尝试就关闭任务」——只有场景规则明确允许时才在一次尝试后关闭（如：已充分外联且无新高意向回应的 lead follow-up；已发付款链接但付款未确认的 billing 补救）。cancellation/complaint/upgrade/manager-callback/referral/win-back 类必须保持 pending，直到系统数据变化、员工手动关闭、对话明确解决，或满足场景关闭规则。

    3.2 typeCategory（按 lifecycleStage 分发）

    CREATE 时按联系人当前 lifecycleStage 选 typeCategory：

    lifecycleStagetypeCategory含义
    leadlead_follow_uplead 是 new/attempted/connected/neglected、非 terminal、未预约，需人工外联或推预约
    leadbooked_not_convertedV1 保守触发——仅在有可靠「已上完首课」证据时（如员工问 "How was your first class?"），不可从群发短信推断
    membercancellation_risk会员表达取消/冻结/降级意向，或需经理挽留介入
    memberretention会员有未解决投诉、账单纠纷、服务质量问题，或需解决后满意度回访
    memberupgrade会员有升级方案/加购（如私教）意向
    memberrenewal冻结到期（freeze recovery），或付款方式失败需人工催回
    memberreferral会员符合活动/挑战赛推广，或企业/特别推广跟进
    churnedwin_back前会员表达回归意向（回电、回 SMS、咨询重新加入）

    排除：lead_outreach（Lead 首次联系）由 lead-tracking 系统在 Lead 到达时创建，不归这条 pipeline——prompt 明确「these are created by the lead-tracking system, not by this pipeline」。

    3.3 closeResult（关闭结果枚举）

    CLOSE 时按结果匹配 closeResult（必须引用 PENDING TASKS 里的真实 taskId）：

    场景closeResult
    目标达成converted / win_back / issue_resolved / cancel_saved / renewed / upgraded / referral_obtained
    客户拒绝继续联系do_not_contact
    外联完成但无定论attempted
    号码无效wrong_number
    无明确分类other

    约束：

    • converted 仅在有可靠会员购买/会员数据时用，不因 lead 订了 intro 就用 converted。
    • attempted 谨慎用：可用于充分外联仍无回应的 lead follow-up；禁止对 cancellation/complaint/billing/manager-callback 在一次失败尝试后就关为 attempted。

    后端 enum 缺口（backend-gated）：booked 和 cancelled 是业务需要的 closeResult，但后端 TASK_CLOSE_RESULT 尚未支持。过渡期用 other + 明确 reason 兜底，禁止误用 converted（给已订课的 lead）或 cancel_saved（给确认取消的）。原因：lead 可以完成预约但还没成为会员；取消也可以在挽留失败时继续推进。

    3.4 priority

    priority含义
    high当日营收风险/机会——可挽救的取消意向、有流失风险的未解决投诉、未解决的主动催款、需当日预约的高意向 lead
    medium可行机会——感兴趣但未预约、客户要价格/回电、升级意向、freeze/renewal 机会、前会员问回归
    low不急但有明确下一步
    不建 task例行预约确认、确认短信、intake/waiver 提醒、到场指引、无人接听/无意义 voicemail

    3.5 suggestedActions（OTF 场景模板）

    重大设计点：suggestedActions 是自由文本，禁止输出泛化 CRM 标签（call_back / send_sms / book_trial / book_appointment / schedule_tour / send_pricing）。

    每条建议至少包含：① 渠道（call / SMS / manager callback / 无人工动作）；② OTF 具体业务目标。有上下文时再加：③ 支撑证据；④ playbook 话术方向；⑤ 关闭/完成条件。

    反编造：不准凭空造证据、先前上下文、话术、报价、促销、价格或关闭条件。最新通话引用了之前的对话时，用历史互动记录和 pending tasks 补上下文，不强求最新这通包含所有细节。

    prompt 给了 8 个 OTF 场景模板：new lead / pricing question / already-booked / post-class follow-up / cancellation risk / billing recovery / complaint-retention / do-not-contact。

    3.6 "DO NOT create task" 清单（V1 范围控制）

    以下情况不建 task（共 13 类）：

    • lifecycleState = "terminal"（除主动回归的 churned → win_back）
    • 无明确可行下一步（actionNeeded 应为 false）
    • 同 typeCategory 已有 pending task → 改为 UPDATE/CLOSE/留着
    • doNotContact = true 或客户明确说不要联系
    • corporate/vendor/partner/非客户业务询问（V1）
    • 唯一新事件是无客户回应的外呼尝试
    • 唯一新事件是无个人回复的群发消息
    • 仅无人接听、信箱满、无意义 voicemail、无高意向的例行确认
    • 客户已预约且只剩确认短信、intake/waiver 提醒、到场指引
    • 唯一原因是缺 intake form（V1 忽略）
    • 互动中已解决且无投诉/升级/承诺下一步/遗留目标
    • typeCategory 会是 lead_outreach（由 lead-tracking 系统建）

    3.7 关键约束

    • 每个 contact 每个 typeCategory 最多 1 个 pending task（DB 强制），不许建重复。
    • close/update 引用的 taskId 必须来自 PENDING TASKS 输入，伪造会被拒。
    • actionNeeded / suggestedActions / taskDecisions 三者一致：需后续人工跟进 → 建/更新真实 task 且 actionNeeded=true；不需要 → actionNeeded=false 且 suggestedActions=[]（仍可在 taskDecisions 里关闭已完成/失效/被阻断的 pending task）。
    • 空的 taskDecisions[] 表示「已考虑所有场景，无人工 task 动作需要」。

    四、Task 决策的输入依据

    contact-analyzer 读哪些输入区来做 Task 判断：

    输入区对 Task 决策的作用
    PENDING TASKS提供可 close/update 的真实 taskId + typeCategory + priority + dueAt + 首条 suggested action；overdue/due-soon 由 AI 用当前时间对比 dueAt 自行推算
    RECENTLY CLOSED TASKS只读历史——防重复、影响 priority 判断；绝不引用其 taskId（故意不展示），也不能重新关闭/更新
    RECENT CALLS结构化通话事实（含 classification 的 follow_up/outcome/cc 等），优先级高于重新解读 summary
    RECENT MESSAGESSMS/voicemail；用于 DNC 关键词检测（"STOP"/"UNSUBSCRIBE"）、engagement 证据

    五、与现有 spec 的差异（需对齐）

    从 prompt 反推时发现 prompt 与现有设计文档对不上，如实记录，不在本文做产品判断：

    差异点Prompt（2026-05）实际现有 spec 文档
    typeCategory 枚举lead_follow_up / booked_not_converted / cancellation_risk / retention / upgrade / renewal / referral / win_back（8 个）task-lifecycle.md §四 用 LEAD OUTREACH / PAYMENT RECOVERY / FREEZE RECOVERY / EVENT PROMOTION / SPECIAL PROMOTION 等场景标签（12 个），命名与粒度不一致
    booked / cancelled 关闭backend-gated，prompt 暂用 other 兜底字段设计未体现此过渡状态
    renewal 语义同时覆盖「冻结恢复」和「付款催回」spec 把 FREEZE RECOVERY 和 PAYMENT RECOVERY 分成两个独立场景

    这与 CLAUDE.md「Docs vs DB Schema 漂移（#199）」追踪的不一致同源。要不要据此对齐 tasks-field-design.md/task-lifecycle.md，是产品决策，需另行确认。