#Task Pipeline Deliverable (Codex)

Historical design input（2026-07-23 校准）：本文保留 Task Orchestrator、0 / 1 / N decisions、create_closed、Activity/Outcome 分离等 Task V2 依据，但不再单独作为实施规格。当前路线以 Task V2+ 工程审计与实施基线 为准；V3 内容仍是待评估 proposal。

用途: Codex 独立设计产出,避免和并行 AI 的 task-lifecycle-gap-analysis.md / task-lifecycle-gap-analysis-claude-code.md 修改冲突。 日期: 2026-05-30 范围: system design only。不改代码、不写 DB、不做 rollout、不设计完整 SMS pipeline。 设计口径: 这里写 final / long-term-proof target architecture。实现顺序可以另写 implementation plan,但概念模型先按最终态说清楚。 Review basis: 当前 task pipeline redesign 以这份 Codex 文档作为 review basis。旧 V2 task docs 已移动到 archive/,避免和新模型混读。 2026-05-31 补充: 全系统 pipeline 调研后，Task Orchestrator 应视为 unified architecture 的 shared mutation module，而不是 task feature 内部 helper。见 Task Pipeline Architecture Addendum。

#How to Read This Doc

这份文档按"先最终 contract,再解释为什么"组织。读者不用先理解所有历史问题,也能先看到最后系统应该长什么样。

核心阅读路径:

API contract -> schema -> workflow -> prompt contract

原因是 prompt 不应该先被设计出来。prompt 的输入/输出必须由稳定的 task API、schema 和 state machine 反推,否则会变成"AI 想怎么说就怎么说",代码和 UI 很难长期维护。

#Executive Summary

结论: Task 是一个统一的 Work Object / 业务事项对象。它有二元 lifecycle: open / closed;中间执行过程写入 progress log;最终业务结果写入 close outcome。

#一句话模型

Task lifecycle:       open / closed
Task progress log:    no_answer / left_voicemail / text_sent / callback_requested / ...
Business outcome:     booked / converted / cancel_saved / issue_resolved / do_not_contact / ...

#为什么用 open / closed,不是 pending / closed

结论: schema + code + UI 同步改名 open / closed。测试环境无 prod migration 压力,一次性改干净,不保留 pending 映射。

实施:

schema/code/API/UI: tasks.status = open | closed (DEFAULT 'open')
Migration: UPDATE tasks SET status='open' WHERE status='pending'
Sweep: 全 repo grep 'pending' 替换为 'open'
       (4 Lambda + studio-api raw SQL + CHECK constraints
        + partial unique index WHERE status='pending')

#Current System Context

结论: task pipeline 不是单点功能,它处在 per-call AI、contact analyzer、lead pipeline、staff UI/API 和 manager metrics 中间。最终设计必须覆盖所有入口。

#1. Final Object Model

结论: 最终模型分 4 层,每层回答不同问题。不要把它们压进一个字段。

#Task 的边界

#2. Final Workflow

结论: 目标状态下,所有 task 写操作都经过 Task Orchestrator;AI 只给 proposal,代码执行 state transition。

#Desired Workflow: 每一步在做什么

这张图的重点不是"多一个复杂系统",而是把 task 写入拆成清楚的责任链:入口先过滤,AI 只判断语义,代码最后安全写库。

SMS 在这个 workflow 里的位置:SMS 先作为 messages activity 存下来,再进入"触发与过滤层"。thanks/ok/emoji 这类 trivial message 不触发 AI;STOP 这类确定 DNC 由代码直接处理;购买、取消、投诉、预约、回流、DNC 自然语言表达等 meaningful SMS 才触发 Task Orchestrator。也就是说,SMS 不单独发明一套 task 系统,但它有自己的轻量触发规则。

#现有 Workflow 及问题点

这张图描述的是当前系统怎么跑,以及为什么这个 flow 会让 task 语义混乱。它不是 final design。

图里的"业务已完成 + 不需要后续跟进"对应当前代码/prompt 信号里的 followUpNeeded = false 和 primaryOutcomeResult = success。文档正文避免使用 fu=no + out=success 这种内部缩写,因为它对不熟悉 prompt 字段的人不直观。

#Architecture Recommendation

结论: 建一个明确的 Task Orchestrator / task domain service,作为所有 task mutation 的唯一协调层。它不是一个大 prompt,也不是一个新 UI 组件;它是代码里的 state machine + policy + transaction boundary。

它不负责:

#3. Final Schema

结论: tasks 存当前事项快照和最终结果;task_progress_events 存执行过程;contact_timeline 存统一时间线投影。

#tasks: work object snapshot

#tasks.closeResult: keep vs move out

结论: closeResult 不删除这个字段,但要把它从"混合结果桶"改成"最终业务 outcome"。

#attempted: final definition

结论: attempted 不再作为 future 默认 closeResult。尝试过程用 task_progress_events 和 attemptCount 表达;真正终止 task 时,必须写一个 terminal business outcome。

历史 attempted 数据暂不作为本设计处理范围。这里定义的是 future semantics 和新写入行为。

#task_progress_events: progress source of truth

#contact_timeline: contact-level timeline projection

contact_timeline 继续做统一 timeline 和审计,但不承载所有 task progress 查询语义。每次 task progress 应同步写入 timeline event:

task_progress_events: 业务事实 SoT
contact_timeline:     contact 维度 timeline projection / audit feed
tasks:                当前快照

#4. Progress Write Path

结论: 一次 progress update 应该在一个 transaction 里写 progress event、timeline event,并更新 task 快照。

例子: staff 点击 Left Voicemail

1. INSERT task_progress_events
   progressType = left_voicemail
   channel = phone
   actorType = staff
   callId = ...
   occurredAt = ...

2. INSERT contact_timeline
   eventType = task.progress_recorded
   entityType = task
   entityId = taskId
   newValue = { progressType, channel, callId }

3. UPDATE tasks
   attemptCount = attemptCount + 1
   dueAt = next retry window
   updatedAt = now

#Timeline event mapping

结论: task_progress_events 新增后,现有 contact_timeline 不废弃。两者并存:progress table 是 task progress 的 SoT,timeline 是 contact-level 展示和审计投影。

Transaction policy:

#Why not only contact_timeline

#查询性能

性能不是反对 task_progress_events 的理由。Postgres 很适合这种 append-only event 表,关键是索引:

tasks.attemptCount 只是列表快照;纠错和历史以 task_progress_events 为准。

#5. API Contract

结论: 未来 API / CLI / OAuth / AI agent 不应该解析 prompt 文本或 timeline JSONB。它们应该读 typed work objects。

#推荐 API shape

GET /v3/tasks/:taskId
  -> task snapshot

GET /v3/tasks/:taskId/progress
  -> ordered task_progress_events

POST /v3/tasks/:taskId/progress
  -> record_progress, idempotencyKey required

POST /v3/tasks/:taskId/close
  -> close with business outcome

GET /v3/contacts/:contactId/timeline
  -> cross-entity contact_timeline

GET /v3/contacts/:contactId/work-objects
  -> open/closed objectives + recent progress + recommended next action

#API response should separate three concepts

{
  "task": {
    "id": "task_123",
    "status": "open",
    "typeCategory": "lead_follow_up",
    "priority": "high",
    "dueAt": "2026-05-30T21:00:00Z",
    "attemptCount": 2
  },
  "latestProgress": {
    "progressType": "left_voicemail",
    "channel": "phone",
    "occurredAt": "2026-05-30T18:10:00Z"
  },
  "close": null
}

Closed example:

{
  "task": {
    "id": "task_456",
    "status": "closed",
    "typeCategory": "lead_follow_up"
  },
  "latestProgress": {
    "progressType": "callback_requested",
    "occurredAt": "2026-05-30T17:20:00Z"
  },
  "close": {
    "closeType": "manual_closed",
    "closeResult": "booked",
    "closedAt": "2026-05-30T18:00:00Z"
  }
}

#6. Prompt Contract Derived From API

结论: prompt 的职责不是"设计 task 状态",而是在 API/schema 允许的动作空间里提出语义 proposal。

#Prompt input should include

#Prompt output should be proposed mutations

{
  "taskDecisions": [
    {
      "action": "record_progress",
      "taskId": "task_123",
      "progressType": "callback_requested",
      "evidence": "Customer asked to be called back Friday afternoon.",
      "nextDueAtHint": "2026-06-05T18:00:00Z",
      "confidence": 0.88
    },
    {
      "action": "create_closed",
      "typeCategory": "lead_follow_up",
      "closeResult": "booked",
      "evidence": "Staff booked an intro class during the call.",
      "confidence": 0.93
    }
  ]
}

#Prompt must not do

#7. Code vs Prompt Responsibilities

结论: AI 负责语义判断,代码负责世界状态。typeCategory 是 hybrid: AI 在代码允许范围内选择。

#typeCategory allowed set

#8. UI Semantics

结论: Tasks 页面应明确分成两种操作:记录进展 vs 关闭事项。左侧操作建议命名为 Progress Update 或 Log Progress,不要叫后端意义上的 status update。

Prompt 输出也应使用 progress proposal,而不是 "status update":

{
  "action": "record_progress",
  "taskId": "uuid-from-input",
  "progressType": "callback_requested",
  "reason": "Customer asked staff to call back Friday afternoon.",
  "nextDueAtHint": "Friday afternoon",
  "confidence": 0.88
}

#Human / AI Race Conditions

结论: 人可能比 AI 快,AI 也可能比人快。UI/API 必须让 staff override 成为一等行为,但所有写入仍走同一个 Orchestrator。

#9. Scenario Coverage

结论: 同一套 objective/progress/outcome 模型覆盖关键场景,不需要为每个场景写特殊状态。

#10. Explicit Conflict Decisions

结论: brief 里的冲突不是二选一,但每个都要有明确边界。推荐方案是统一 work object + progress/outcome 分层。

#11. Metrics Impact

结论: completion 和 attempt workload 必须分开。

#12. Implementation Touchpoints

结论: 这是 final target 的设计清单,不是阶段拆分。

#Implementation Staging, Without Weakening Final Design

结论: final model 一次定清楚;实现可以先做最小闭环,但不能把 schema/prompt 设计成只适合短期。

#13. Rationale / Deep Dives

#1. 为什么不是 Agile-style workflow status

Agile task status 管的是工程流程,例如 Todo -> In Progress -> In Review -> Done。Retaintive task 管的是客户事项是否还需要处理。

不推荐:

open -> attempted -> voicemail_left -> waiting_callback -> text_sent -> closed

推荐:

task.status = open
latestProgress = left_voicemail
attemptCount = 2
dueAt = tomorrow

#2. callback_later 怎么拆

#3. closeResult 只保留 business outcome

下面两组不是映射关系,而是两类不同 enum。

Business outcome examples:

converted
booked
cancel_saved
issue_resolved
not_interested
wrong_number
do_not_contact
unable_to_reach
other

Progress examples:

no_answer
left_voicemail
text_sent
callback_requested
follow_up_scheduled
customer_considering

#4. 并发 / 幂等 / fallback

#5. SMS 为什么不单独做一套 task pipeline

结论: SMS 应该先作为 activity 存储,再通过 channel-specific trigger/filter 进入同一个 Task Orchestrator。不要为 SMS 发明另一套 task lifecycle。

业界老 CRM 常把 call、SMS、email 都挂到同一个 contact activity/timeline 下,但触发 task 的规则常因 channel 不同而不同。这个方向对 Retaintive 有参考价值:统一 objective,但不统一所有触发成本。2026 AI 成本下降后,也不应该简单照搬"SMS 一律等 daily batch";更合理的是 lightweight code/classifier gate + meaningful message 触发 orchestrator。

#6. 竞品 API 校准

竞品只是校准。很多旧 CRM 设计来自人工录入、AI 不成熟、LLM 成本高的时代。Retaintive 应利用 AI-native 条件,提供更清楚的 work-objects API,让外部系统和 AI agent 一次读懂当前事项、进展、结果和下一步。

Official references:

• HubSpot Tasks API: https://developers.hubspot.com/docs/reference/api/crm/engagements/tasks
• Salesforce Task Fields: https://help.salesforce.com/s/articleView?id=sf.task_fields.htm&language=en_US&type=5
• Salesloft Call Dispositions API: https://developers.salesloft.com/docs/api/call-dispositions/
• Outreach Advanced Task Mapping for Call Tasks: https://support.outreach.io/hc/en-us/articles/360042104133-Microsoft-Dynamics-Advanced-Task-Mapping-Call-Task

#14. Brief Compliance Checklist

结论: 当前版本满足 brief 的核心交付和 acceptance criteria。剩余需要 Max review 的不是文档遗漏,而是产品 policy 拍板。

Open product policy items: