#Task Accuracy Baseline v1 设计稿

Current legacy executable baseline（2026-07-15）：本文用于解释和回归现有 production prompt/Zod/writer vocabulary；lead_outreach / lead_follow_up relay、global closeResult、task_progress_events、task_objectives / task_issues 等不得作为 Target。新 domain/eval contract 见 Task System Design V3。

#0. 先说结论

Task Accuracy Baseline v1 不是“先做 Vapi 自动外呼”，也不是“让 AI 自由发挥生成任务”。它要先证明一个更底层的能力：

用 production prompt + production Zod schema + synthetic scenarios，证明 AI 能稳定把 contact / call / message / lead / task context 转换成正确的 taskDecisions[]，并且所有高风险 mutation 都被 Policy Guard 和 DB constraint 控住。

这一步如果不准，后面接 Vapi、自动短信、AI agent execution、usage metering 都会变成“把错误更快放大”。所以 demo 前最重要的是：让 task decision 先可信、可复现、可解释、可回归测试。

#0.1 今天改什么，不动什么

这次 Task Accuracy Baseline v1 先把“评审对象”和“测试对象”改对。不要把所有未来架构一次性塞进来。

今天改：

• 把 scenario 写成可 review 的业务状态，而不是只写一个简陋表格。
• 每个 scenario 必须写清楚：
  • existingState：已有 contact / task / attempt / lifecycle。
  • newEvidence：这次 call / SMS / voicemail / lead 到底发生了什么。
  • expected：正确的 task decision。
  • notExpected：明确不应该出现的 decision。
  • rationaleZh：为什么这样判。
• 在 contacts-analyzer golden eval 代码里维护同一份 scenario metadata。
• 把 attemptCount 放进 analyzer 的 OPEN TASKS context，因为 unable_to_reach / follow-up threshold 离不开它。
• 先输出 review Markdown，让产品先确认 expected decision，再跑真实模型。

今天不动：

• 不改 production DB schema；tasks.attempt_count / task_progress_events / dueAt 已够支撑 v1。
• 不加 objective / desiredOutcome column；v1 先用 scenario 的 objectiveContext 表达。
• 不接 Vapi。
• 不做 raw audio / speech-to-text 测试。
• 不把 message pipeline 改成主动触发 analyzer；先作为后续 issue。
• 不让 writer 自动在 attempt threshold 时 close；v1 先由 AI decision 在 threshold 上 close，deterministic writer hardening 作为后续 issue。

最重要的 policy decision / implementation gap：

record_progress:
  writer 会写 task_progress_events
  writer 会 attempt_count + 1
  writer 会更新 dueAt
  writer 不会自动 close unable_to_reach

unable_to_reach:
  v1 policy 已确认 threshold = 2
  attemptCount = 0 + failed attempt -> record_progress
  attemptCount = 1 + failed attempt -> close unable_to_reach
  deterministic writer auto-close / progress_then_close 作为 #1142 后续 hardening

#1. 这份设计根据什么来

Scenario 不是只靠 common sense 拍脑袋，也不是只机械覆盖 enum。优先级是：

关键原则：

• taskDecisions[] 是 proposal，不是 command。
• AI 只做判断和建议；真正写库必须走 applyTaskAction()。
• 安全层是刹车：Zod schema、taskRef resolver、Policy Guard、writer guard、DB constraint 各拦一段。DNC、duplicate、store mismatch、hallucinated task ref、missing evidence 都要 fail closed。
• Scenario 不做 enum 全排列。我们按“会影响决策的字段”覆盖。
• Demo 只展示稳定通过的 case；不稳定但产品上正确的 case 标成 knownGap，不现场赌模型。

#2. Source of Truth

这份设计以 live code 为准。主要读过的 source：

#3. 我们到底在测试什么

#In Scope

#Out of Scope for v1

• 不测原始 audio。
• 不把语音重新转 transcript。
• 不做 Vapi 自动外呼。
• 不自动发 SMS / Email / WhatsApp。
• 不实现完整 approval queue。
• 不在 demo 前做 task objective schema migration。

这些不是不重要，而是 demo 前不是最短路径。

#4. 当前生产流程

现在的 contacts-analyzer 不是一个“任意 POST transcript 就生成 task”的公开接口。它是事件触发：上游 pipeline 已经把 call / message / lead 的结构化结果写进 Neon，然后 SQS 触发 analyzer 聚合 context。

Call 入口：现在最接近 Task Accuracy v1 的真实主路径

RingCentral call ended webhook
  -> transcribe-queue
  -> transcribe-processor
  -> S3 transcript / structured call summary
  -> ai-analysis-queue
  -> ai-analysis-processor
  -> Neon: calls / contacts / contact_timeline
  -> contacts-analyzer SQS: { phone, storeId, source }
  -> read recent calls/messages/leads/tasks/contact
  -> production prompt + ContactsAnalysisSchema
  -> taskDecisions[]
  -> resolve taskRef T1/T2
  -> writeAnalysisWithTasks()
  -> applyTaskAction()
  -> Policy Guard + DB constraints
  -> tasks / task_progress_events / task_suggestions / task_playbooks

Message 入口：现在主要先写事实，后续被 analyzer 读取

RingCentral SMS / voicemail webhook
  -> message-processing-queue
  -> message-processor
  -> Neon: messages / contacts / contact_timeline
  -> STOP keyword can update contact.doNotContact
  -> 当前不会主动 trigger contacts-analyzer
  -> 但下一次 contacts-analyzer 运行时会把 messages 读进 context

未来建议：
message-processor 在高价值 inbound reply / STOP / objection 场景下
  -> enqueue contacts-analyzer

Lead 入口：lead_outreach 是 deterministic system task，不是 AI 创建

lead-tracking poller
  -> Neon: leads
  -> EventBridge LeadCreated
  -> lead-processor
  -> contacts upsert
  -> deterministic create lead_outreach task
  -> contact_timeline
  -> 后续 call/SMS/AI 再 progress / update / close

关键约束：
AI 可以 create 8 个业务 category
AI 不能 create lead_outreach
lead_outreach belongs to lead-tracking / lead-processor

这三条入口对应到 Task Accuracy v1 的测试含义：

#4.1 Transcript 怎么插入？

我们 demo 前不需要真的走 audio → transcription。可以直接假设 transcript 已经处理完，把关键内容放到 analyzer 真实会读的字段里：

三层测试深度：

Demo 前建议优先 Level 1 + Level 2。Level 3 很重要，但会把变量变多，不适合两天内证明 task decision 准确性。

#4.2 为什么不先大改 DB schema？

短答案：demo 前不要先改 production DB schema。先把 scenario 和 eval 跑准，再让真实 scenario 反推 schema。

原因有三个：

1. Task Accuracy v1 的核心是验证 prompt -> Zod schema -> Policy Guard -> writer 是否稳定，不依赖新表。
2. typeCategory 现在已经深度绑定 prompt、Zod schema、writer、UI、open-task dedup index。两天内迁 schema 容易把 demo 风险放大。
3. 我们还没用 35-60 个 scenario 证明哪些 objective / issue 真的是高频、稳定、跨行业的抽象。

所以 v1 先在 scenario 里显式写 objectiveContext，但不立刻写入 production DB。这样 review 的内容是长期正确的，同时不打断现有系统。

#4.3 Objective / Context 和 AI Decision 的区别

你问得对：如果完全没有 AI 分析，系统怎么知道 objective？

答案是：Objective / Context 不是“AI 已经做完判断后的结论”，而是 AI 判断前的候选目标目录 + 当前上下文包。AI 再基于这个上下文做 decision。

Objective Catalog + Context Builder
  已知事实：
    contact lifecycle / lead status / doNotContact
    recent calls / messages / voicemail / lead
    existing open tasks / recently closed tasks
    tenant/store policy
    task playbook / suggestion history

  产出给 AI 的不是最终答案，而是候选问题：
    这里是否有 unresolved customer objective？
    如果有，是 existing task 的 objective，还是新的 objective？
    这次 evidence 应该 create / close / update / progress / no-op？

AI Decision Layer
  读取上面的 context
  判断 taskDecisions[]
  输出 proposal
  不能直接写库

三个例子：

#5. Task Decision 思考模型

这张图是 reviewer 判断 scenario 的心智模型：同一个通话可能是店员打出去，也可能是客人打进来；可能只是一次 attempt，也可能是 close outcome；也可能多轮往返后改变 next action。

New evidence: call / SMS / voicemail / lead
  |
  v
Is this DNC / STOP / doNotContact?
  |
  +-- yes
  |     -> set contact.doNotContact = true
  |     -> close or block open outreach tasks
  |     -> no outbound action
  |
  +-- no
        |
        v
Does a matching open task exist?
  |
  +-- yes
  |     |
  |     v
  |   Did the latest event change the objective state?
  |     |
  |     +-- outbound attempt only
  |     |     -> record_progress: no_answer / left_voicemail / text_sent
  |     |
  |     +-- customer still deciding / asks callback
  |     |     -> record_progress or update
  |     |
  |     +-- achieved / rejected / wrong number / exhausted
  |     |     -> close: booked / converted / not_interested / wrong_number / unable_to_reach
  |     |
  |     +-- new evidence changes next action
  |     |     -> update suggestedActions / priority / dueAt
  |     |
  |     +-- noise only
  |           -> no-op
  |
  +-- no
        |
        v
      Is there a new actionable unresolved objective?
        |
        +-- yes, still open
        |     -> create_open
        |
        +-- yes, arose and settled in same call
        |     -> create_closed
        |     -> requires triggering call evidence
        |        analyzer uses triggeringCallId -> sourceCallId
        |
        +-- no
              -> no-op

几个容易混的点：

• 店员打出去没人接：通常是 record_progress，不是 close，也不是新建任务。
• 客人打进来并预约成功：如果有 open lead_follow_up，应该 close booked；如果没有 open task 且从产生到解决都在这通电话里，可能是 create_closed booked。
• “我不感兴趣”通常是 close not_interested；只有明确 “STOP / do not contact / remove me” 才是 DNC。
• Routine confirmation、waiver、arrival logistics 不应该变成 task。
• dueAt 只是 staff effort 的排期，不应该阻止记录真实 outcome。

#6. Scenario Schema

Scenario 的目的不是让机器看懂，而是让产品 / 业务 / 工程能一起 review：“给了这些证据，expected decision 是否正确？”

#6.1 Review 格式

不要只写 “C-01 lead follow-up create”。每个 scenario 都要写成下面这种状态机格式：

Case A: 店员打给 lead，没人接

existingState:
  Contact 是 active lead
  Open task: T1 lead_outreach
  T1 attemptCount = 0

newEvidence:
  Outbound call
  callState = no_answer
  客户没有任何回复

expected:
  record_progress no_answer on T1
  task 保持 open
  后续由 dueAt 安排下一次 follow-up

notExpected:
  close unable_to_reach
  create_open lead_follow_up
  taskDecisions=[]

rationaleZh:
  单次 outbound no-answer 是一次员工尝试，不是目标完成或失败；
  已有 lead_outreach 就推进原 task，不能重复创建 lead_follow_up。

完整 review 清单由代码导出，避免文档和测试漂移：

cd ../callytics-infrastructure
npm run eval:golden -- --review-md ../docs/docs/ai/product/task-accuracy/baseline-v1-scenario-review.md

这个命令不调用模型，不需要 OPENROUTER_API_KEY。它只把 GOLDEN_CASES[].review 导出成 Markdown，给你逐个 review。

#6.2 Executable Schema

代码里的每个 GoldenCase 同时包含两层：

建议 registry 里每个 case 长这样：

interface TaskAccuracyScenario {
  id: string;
  titleZh: string;
  priority: 'P0-demo' | 'P1-baseline' | 'P2-hardening';
  reviewStatus: 'approved' | 'needs_product_decision' | 'known_gap';
  demoCandidate?: {
    id: 'P0-01' | string;
    status: 'needs_model_validation' | 'blocked_known_gap' | 'candidate';
    titleZh: string;
    rationaleZh: string;
  };
  bucket:
    | 'create_open'
    | 'create_closed'
    | 'close'
    | 'update'
    | 'record_progress'
    | 'negative_noop'
    | 'safety';
  sourceOfRule: Array<'production_prompt' | 'zod_schema' | 'policy_guard' | 'business_rule' | 'eval_practice'>;
  contact: {
    lifecycleStage: 'lead' | 'member' | 'churned' | 'unknown';
    lifecycleState: 'active' | 'paused' | 'terminal';
    doNotContact: boolean;
    leadStatus?: string | null;
    purchaseIntent?: 'high' | 'medium' | 'low' | null;
    hasOpenComplaint?: boolean | null;
  };
  existingTasks: Array<{
    taskRef: 'T1' | 'T2';
    status: 'open' | 'closed';
    typeCategory: string;
    attemptCount?: number;
    dueAtRelative?: string;
    suggestedAction?: string;
    closeResult?: string;
  }>;
  evidence: {
    source: 'call' | 'sms' | 'voicemail' | 'lead' | 'mixed';
    direction?: 'Inbound' | 'Outbound';
    hasTriggeringCallId?: boolean;
    fromPhoneRole?: 'store' | 'contact';
    toPhoneRole?: 'store' | 'contact';
    summaryZh: string;
  };
  objectiveContext?: {
    mode: 'existing_task' | 'candidate_objective' | 'no_objective';
    objectiveType?: string;
    objectiveZh?: string;
    desiredOutcomeZh?: string;
    successCriteria?: string[];
    failureModes?: string[];
    evidenceRequirement?: string[];
  };
  expected: {
    taskDecisions: Array<Record<string, unknown>>;
    contactFields?: Record<string, unknown>;
    dbReplay?: boolean;
    artifactChecks?: Array<'task_suggestions' | 'task_playbooks'>;
  };
  reviewQuestionZh: string;
  notes?: string;
}

字段解释：

#6.3 Scenario Registry / Golden Eval / DB Replay / Demo Pack 的区别

这几个名字容易混在一起。它们不是同一个东西，也不是四套重复系统。

Scenario Registry
  = 题库 / 真值表
  = 我们认为业务上应该发生什么

Golden Eval
  = 让真实模型做题
  = 验证 AI 判断准不准

DB Replay
  = 把关键答案拿去真实 writer path 试写
  = 验证 Policy Guard / writer / DB constraints 是否安全

Demo Pack
  = 从题库里挑稳定通过的展示路线
  = 给 investor / team 看，不是新的测试层

更具体地说：

可以把它们理解成：

Scenario Registry 是考试题
Golden Eval 是让 AI 真做题
DB Replay 是把答案拿去真实系统里试写库
Demo Pack 是挑已经稳定做对的题现场展示

#6.4 DB Replay 不是新业务逻辑

DB Replay 需要写一点 test harness，但不应该写新的 task 业务逻辑。正确边界是：

DB Replay Scenario
  |
  | seed synthetic DB rows
  | contacts / calls / messages / leads / existing tasks
  v
真实 Neon test branch
  |
  | inject mock AI output
  | taskDecisions[] = expected decision
  v
现有 production code
  |
  | contacts-analyzer handler
  | -> resolveTaskRefs(T1/T2)
  | -> NeonRepository.writeAnalysisWithTasks()
  | -> common applyTaskAction()
  | -> Policy Guard / DB constraints
  v
真实数据库写入
  |
  | query persisted state
  | tasks / task_progress_events / contact_timeline / contacts / artifacts
  v
assert expected DB state

所以新增的是：

• scenario seed data。
• mock AI output injector。
• persisted assertion runner。

不新增的是：

• task writer。
• duplicate logic。
• DNC logic。
• create_open / create_closed / close / update / record_progress 业务逻辑。
• Policy Guard。

当前可执行入口：

cd ../callytics-infrastructure
npm run eval:db-replay

运行前置条件：

• NEON_API_KEY 已设置。
• NEON_PROJECT_ID_TEST 指向 test Neon project。
• 该命令会创建 ephemeral Neon branch，跑完后删除。

为什么只选 8-12 个 DB replay，而不是把 57 个 scenario 全部 DB replay：

• Golden Eval 已经负责全量判断覆盖。
• DB Replay 更慢、更重，需要 Neon branch、seed、writer、query assertions。
• 很多 scenario 在 writer 层走同一条路径，全部 replay 会变成重复测同一段代码。
• 第一批先覆盖代表性 mutation 和高风险 guard：create_open / create_closed / close / record_progress / update / no-op / DNC / duplicate / forbidden create / missing evidence / hallucinated taskRef。
• 后续如果 matrix 某个 cell 在真实模型、线上或 demo 中不稳，再给那个 cell 加 targeted DB replay。

#6.5 它是不是 plug-in / plug-out？

方向上是，但 Baseline v1 先不把 framework 抽象过度。

长期目标是：

厚底座 AI Foundation
├─ context builder
├─ LLM / structured output
├─ Policy Guard
├─ writer / Orchestrator
├─ eval harness
├─ replay harness
└─ feedback loop

薄 Skill: Fitness Task Skill
├─ objective / category definitions
├─ prompt fragments
├─ allowed actions
├─ scenario registry
└─ demo pack

未来薄 Skill: Fraud Detection Skill
├─ fraud objective definitions
├─ fraud policy rules
├─ fraud scenarios
└─ fraud demo pack

Task Accuracy Baseline v1 暂时还是 contacts-analyzer 专用，但设计上已经按这个方向切分：

• scenario 是业务 skill 层的东西。
• prompt / schema / model call 是 AI Decision 层。
• Policy Guard / writer 是底座层。
• demo pack 是展示路线，不是业务逻辑。

以后如果换到 fraud、billing、support，应该替换的是 skill 的 objective/scenario/playbook，不是重写整套 eval / policy / replay 基座。

#6.6 什么时候会触发这些检查？

Task Accuracy Foundation 不是 production request path 里的同步检查。真实用户事件进来时，系统不会临时跑完整 Scenario Registry。

真实 production event
  -> contacts-analyzer
  -> taskDecisions[]
  -> Policy Guard / writer
  -> DB mutation

生产路径每次都会走 runtime guard，但不会每次跑 Golden Eval / DB Replay。

开发 / CI / demo 前
  -> Scenario Registry
  -> Golden Eval
  -> selected DB Replay
  -> Demo Pack / Known Gaps

建议触发方式：

#7. Decision Axes

不要做全排列。我们按“会改变决策”的轴覆盖。

#7.1 Contact Axes

#7.2 Task Axes

#7.3 Evidence Axes

#8. Proposed Scenario Set

第一批目标是 35-60 个，不是把下面所有组合硬乘。P0 demo pack 是从 executable scenario metadata 里挑出来的稳定 case，不额外算一套，也不维护一份脱离代码的 wish list。

#8.1 P0 Demo Pack

#8.2 Create Open Cases

覆盖 8 个 AI-creatable category。

#8.3 Negative / No-op Cases

#8.4 Close Outcome Cases

Close 不和所有 category 做硬乘，而是按业务结果测。

#8.5 Progress Cases

#8.6 Update Cases

#8.7 Safety Cases

#9. TaskPlaybook / Suggestions 要不要测

要加，但 v1 不要过度扩大范围。

当前代码里 writeAnalysisWithTasks() 对 accepted create_open、带 suggestedActions 的 create_closed/update 会写：

• task_suggestions：append-only，每条建议一行，带 promptVersion / runId。
• task_playbooks：append-only/cache，content 包含 primaryAction、recommendedSteps、optionsYouCanOffer、avoid、closeGuidance。

v1 建议测两层：

原因：demo 前我们要证明“AI decision + safe write + artifact created”闭环存在；playbook 质量当然重要，但它是另一个 eval 维度，不应该阻塞 Task Accuracy Baseline v1。

#10. First Batch vs Second Batch

#第一批：Task Accuracy Baseline v1

目标是证明 task decision 本身准。

• 35-60 个 scenario。
• Golden eval 跑 production prompt + production Zod schema + real model。
• 8-12 个 DB replay 验证 writer / policy / constraints / artifact writes。
• Demo pack 只选稳定通过 case。

#第二批：Hardening + Voice-Agent Readiness

目标是让系统准备好接自动执行。

• 多轮 back-and-forth：几天内来回通话 / SMS。
• 同 phone 跨 store。
• recently closed 后又出现新证据。
• concurrent duplicate create。
• stale proposal：AI 开始分析后 staff 已经改了 task。
• playbook semantic quality eval。
• approval queue。
• Vapi agent execution log。
• operating hours / blackout / DNC before dialing。

#11. Definition of Done

Task Accuracy Baseline v1 完成时应该有：

• 35-60 个 synthetic scenarios，每个有结构化 expected decision。
• 覆盖 create_open / create_closed / close / update / record_progress / no-op / safety。
• 使用 production prompt + production Zod schema + real model 的 golden eval。
• 8-12 个 DB replay case，验证 writer / Policy Guard / DB constraints；当前入口是 npm run eval:db-replay。
• task_suggestions / task_playbooks 的基础 artifact write 被验证。
• knownGap 明确记录，不把不稳定 case 放进 demo。
• GitHub parent issue 统筹，child issues 分开执行。
• Scenario registry 能继续复用：以后加 industry、加 Vapi、加 prompt update，都从这里扩展。

#12. 当前缺口

#13. 下一步评审方式

建议接下来这样推进：

1. 先把上面的 scenario registry 写成机器可读文件。
2. 你逐个 review P0 + P1：expected decision 对不对。
3. 不确定的 scenario 标 needs_product_decision，不要直接写进 hard assertion。
4. 通过 review 的 case 才进 golden eval。
5. 高风险 case 再进 DB replay。
6. Demo pack 从“连续稳定通过”的 case 里挑，不从 wish list 里挑。

这会让 task eval 变成团队长期资产，而不是一次性的 demo 脚本。