> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Task V2 → Task V2+ → Task V3 工程审计与设计建议（Historical） > **状态：Historical point-in-time audit。** 本文保留从 2026-07-23 开始的审计、讨论结论和阶段性实施建议；正文中的“当前”“路线”“候选”等措辞只描述当时快照，不再是今天的实施授权。 > > 当前 selected Target 见 [Task V3 Product / Domain Contract](/product-design/v3/tasks-feature/task-domain-lifecycle.md)，实施和环境状态见 [Task V3 Rollout 状态快照](/product-design/v3/tasks-feature/task-v3-rollout-status.md)。代码、schema、config、migration 与 runtime evidence 仍分别决定实际状态；Target 或 historical audit 都不能证明 TEST acceptance 或 PROD release。 完整证据、逐表审计和讨论 comments 保留在 [Lark 完整审计](https://ljprwpnmsg2d.jp.larksuite.com/docx/VIXidzIwBoTFPuxUKbAjRJycp5c)；两张可视化流程图在 [FigJam](https://www.figma.com/board/RdVd273tkV2vCo0Va5W7yk)。本文把阶段性判断和设计建议整理进 Git，供后续复核、PR review 和回溯使用；只有经过再次验证并实际合并的代码、测试和明确产品决定，才构成对应阶段的已实施事实。 ## 1. 先统一术语 | 名称 | 准确定义 | 当前状态 | | ------------ | ---------------------------------------------------------------------------------------- | ----------------------- | | **Task V1** | 早期产品、字段和 Prompt 设计 | Historical，仅用于理解演进 | | **Task V2** | 当前线上产品与实现基线，包括现有 Task 行为、actions、Guard、Orchestrator、数据库和 API/UI 读取 | Live baseline | | **Task V2+** | 保留 Task V2 产品语义，补齐统一 snapshot、Decision Journal、authority/Guard、Next Action 和稳定读模型后的工程增强版 | 当前实施方向 | | **Task V3** | Reasoner 与 V2+ 在同一 snapshot、同一 contract 上完成 Shadow 比较，证明更好，得到明确批准并成为线上判断器后的阶段 | Conditional；未 finalized | “Legacy”不再是当前系统的产品名称。`legacy` 只在以下情况保留： - 代码或数据库中的真实字面量，例如 `legacy/legacy` authority mode； - compatibility 字段、历史 row、import provenance； - 已明确准备退役的 writer/read lane； - 描述第三方或旧系统数据时的技术含义。 同理，`target` 可以作为已有代码、config 或 migration 的字面量保留。晋级前的产品和工程讨论使用 **Task V2+** 或 **Task V3 candidate**；只有 Reasoner 通过同 snapshot Shadow、得到明确批准并成为线上判断器后，才称为 **Task V3**。 ## 2. 事实、产品决定与设计建议的使用顺序 | 问题 | 应使用的证据或决定 | | ------------------ | ---------------------------------------------------------------------- | | 线上现在怎样运行 | live code、schema、migration state、config、tests 和目标环境证据 | | 用户现在怎样使用、哪里真正有问题 | 测试用户反馈、产品观察、可复现样本和线上数据 | | 当前产品行为必须保留什么 | 已明确批准的产品决定 + live behavior；本文的 parity list 只是审计清单，需逐项验证 | | 某个 PR 应该实现什么 | 开工前最新审计结果、明确批准的最小范围，以及该 PR 合并后的代码和测试 | | 本文能证明什么 | 当时的审计记录、工作假设和 design proposal；不能自行证明设计已 finalized 或仍然合理 | | 讨论、comments、完整审计证据 | Lark 文档 | | 流程图和协作标注 | FigJam | | Task V3 可选设计空间 | V3 target proposal、design evaluation 和 historical implementation audit | Lark 不直接镜像成第二份逐字副本。原因是 comments、内嵌画板和实时讨论会持续变化，机械复制会产生两份都像“最终文档”的内容。建议维护方式是： 1. 在 Lark 讨论和批注； 2. 把阶段性结论、反例和未决问题通过 docs PR 更新到本文； 3. 明确区分“proposal”“已批准范围”和“已合并事实”； 4. 每个实施 PR 前重新读取最新代码和数据，而不是机械执行本文路线； 5. 由 Git review 记录建议的版本和修改原因，实际行为仍以 live code/schema 为最终证据。 ## 3. Principal Engineer 结论 当前正确方向不是继续完成 Full Task V3，也不是回滚所有已经合并的 V3 基础组件，而是： ```text 固定 Task V2 产品契约 ↓ 补齐无争议的工程地基 ↓ 建立可复现的 Task V2+ baseline ↓ 让 Reasoner 在同一 snapshot 上 no-write Shadow ↓ 只保留被证据证明有价值的 V3 component ``` 核心判断： 1. **Task V2 是可用的当前产品，不是待淘汰的错误实现。** - 测试用户实际使用后认为整体可用； - `create_closed`、多 objective、人工关闭和不同 category 并存都有真实数据； - 当前主要问题来自 behind-the-scenes 工程质量，而不是已证明的 domain failure。 2. **先做工程正确性，再评估模型准确率。** - snapshot、scope、authority、幂等、transaction、decision fate、schema drift 属于确定性工程问题； - Prompt/model 是否漏建、误建、误关属于 accuracy 问题； - 两类问题不能再用同一个 rollout gate 混在一起。 3. **Reasoner 是候选判断器，不是新 writer。** - 它只能读取受限 snapshot、生成 proposal； - mutation 仍由同一个 Orchestrator 和 Guard 执行； - Shadow 阶段到比较即停止，不写真实 Task。 4. **复杂度必须由已观察到的问题证明。** - 新表、字段、adapter、authority 或 runtime 必须说明它解决哪个现有机制无法表达的问题； - “已经写了很多代码”不是继续完成设计的理由。 ## 4. Task V2 parity contract Task V2+ 和任何未来 Task V3 判断器都不得静默破坏以下行为： - `create_open` - `create_closed` - `close` - `update` - `reopen` - `keep_open` / `no_new_objective` 等可审计 no-op - 同一次 interaction 产生 0、1 或多个 objective decisions - 同一 Store + contact + category 最多一个 open Task - 不同 category 可以同时拥有 open Task - staff/API 的 manual mutation - DNC、scope、authority、dedupe、idempotency - evidence、assessment、suggestion 和 timeline 其中 `create_closed` 是一等产品语义：同一 interaction 中出现并完成的 material objective，即使没有 matching open Task，也必须留下完整的 closed outcome ledger。未来 command model 只有在证明原子性、幂等、无中间 open side effect、Outcome/evidence parity 和 read projection parity 后，才能用其他内部实现替代它。 ## 5. 先分开两类问题 ### 5.1 工程地基 这些问题不需要先做模型 A/B，但必须有 deterministic contract、integration 和 security tests： - versioned、typed、store-scoped `TaskDecisionSnapshot`； - server-injected `storeId` / contact identity / DNC / authority； - 明确 `asOf`、source coverage、partial/unavailable、stable ordering 和 payload budget； - mutation idempotency、transaction、concurrency 和 row-state fence； - evidence binding 和 exact source reload； - assessment → authority → Guard → writer → final fate 的可查询链路； - migration/schema drift、rollback 和 cutover safety； - read failure 安全退化为 no-mutation； - Prompt/Reasoner 不接 arbitrary SQL，也不能直接写数据库。 ### 5.2 判断准确率 只有工程地基稳定后，才在同一 corpus 上评估： - 是否选错 action； - 是否漏建、误建、重复或误关； - 是否正确理解 fresh evidence； - 是否正确处理 `create_closed`、multi-objective、DNC 和 correction； - V2+ Analyzer 与 Reasoner 的 precision、recall、latency、cost 和可解释性。 ## 6. 当前 Task V2 线上流程 ```mermaid flowchart LR subgraph inputs["同一 Contact 的四类材料"] evidence["Call / SMS / Lead / staff evidence"] hardState["Store / DNC / time / authority hard state"] contactPrior["AI-derived Contact prior"] taskState["Current Task state"] end inputs --> reader["ContactsReader：多组 scoped reads"] reader --> analyzer["Contacts Analyzer：Prompt + model"] analyzer --> decisions["0 / 1 / N Task V2 decisions"] decisions --> assessment["AI assessment"] assessment --> orchestrator["Task Orchestrator"] orchestrator --> guard["Guard：scope / DNC / authority / row state / dedupe / idempotency"] guard --> records[("tasks / contact_timeline / suggestions")] records --> projection["API / UI / reporting"] reader -. "缺少统一 asOf / coverage" .-> readGap["Read gap"] assessment -. "未完整串联最终结果" .-> fateGap["Decision-fate gap"] ``` 这条链路已经有正确的产品骨架。Task V2+ 不重写它的产品含义，只修复读取、审计、authority、时间模型和 projection 的工程缺口。 ## 7. Task V2+ 最终流程 ```mermaid flowchart LR evidence["Evidence"] hardState["Server-owned hard state"] contactPrior["AI-derived Contact prior"] taskState["Current Task state"] evidence --> snapshot["TaskDecisionSnapshot v1
asOf / coverage / evidence refs / stable order"] hardState --> snapshot contactPrior --> snapshot taskState --> snapshot snapshot --> live["Task V2+ live decider"] live --> contract["Task V2 兼容的 0 / 1 / N contract"] contract --> journal["Decision Journal"] journal --> orchestrator["Task Orchestrator + Guard"] orchestrator --> records[("现有 Task 真实数据")] records --> readModel["Stable read model"] readModel --> consumers["API / UI / reporting"] snapshot -. "同一输入" .-> reasoner["Reasoner Shadow"] reasoner --> proposals["Proposal + mismatch reason"] proposals --> compare["Replay / human comparison"] compare --> stop["停止：不进 live mutation、不写 Task"] ``` Task V2+ 的变化： | 维度 | Task V2 | Task V2+ | | ------------- | ----------------------------------------- | ------------------------------------------------------------------------ | | 产品语义 | 现有 actions 与 0 / 1 / N decisions | 保持不变 | | AI 读取 | typed reader，但多组查询不共享完整 snapshot contract | 一个带 `asOf`、coverage、typed evidence refs 和稳定顺序的 snapshot | | Decision fate | assessment 与最终 mutation 结果未完整闭环 | 每个 decision 都有 authority、Guard、writer、Task id/no-op/reject/zero-row fate | | Authority | global 与 per-objective 可能冲突 | 单一 invariant，变更可审计、可 CAS、可回滚 | | 时间模型 | Next Action / Deadline 尚未完整贯通 | Prompt、writer、timeline、API/UI 使用同一语义 | | 数据 | `tasks` 仍是 current snapshot | 继续复用，不新增平行 Task truth table | | Reasoner | source-ready 组件存在，但尚未证明替代价值 | 同 snapshot、no-write Shadow | ## 8. Reasoner、Shadow 与 Task V3 ### Reasoner Reasoner 是专门做 Task 判断的 AI decision loop： 1. 读取 `TaskDecisionSnapshot`； 2. 只在缺少 material evidence 时调用受限 read tool； 3. 输出 evidence-backed 0 / 1 / N proposals； 4. 不直接修改数据库。 Reasoner 好不好，必须通过同一输入、同一 action contract、同一 expected truth 来比较，不能因为它的架构更新就预设它更准。 ### Shadow Shadow 是上线前的验收模式： ```text same snapshot ├─ Task V2+ live decider → normal Guard/write path └─ Reasoner → proposal/eval/compare → stop ``` Shadow 不进入 live mutation Orchestrator，不调用真实 writer，也不改变 Task。只读 schema/Guard compatibility check 可以存在，但不能伪装成一次真实执行。 ### Task V3 只有同时满足以下条件，系统才进入 Task V3： 1. Reasoner 与 V2+ 使用同一个 snapshot 和 parity contract； 2. `create_closed`、0 / 1 / N、no-op、update/close 等行为全部兼容； 3. human-ratified corpus 上持续优于 Task V2+； 4. safety、latency、cost、correction 和 operations gates 通过； 5. Peter 明确批准； 6. 按单个 Store / objective 可回滚地切换线上判断器。 即使进入 Task V3，也只替换 live decider。snapshot、Decision Journal、Orchestrator、Guard、canonical Task records 和 read projection 都继续复用。 ## 9. 数据库审计结论 ### 保留 - `tasks`：current Task snapshot； - `type_category NOT NULL`； - open uniqueness； - `contact_timeline`：append-only Activity/Outcome/audit ledger； - `task_suggestions`：产品可见建议； - `ai_task_decision_assessments`：AI 判断记录； - Task Orchestrator：统一 mutation boundary； - existing Guard、scope、DNC、dedupe 和 idempotency。 ### 优先增强 - snapshot 的 `asOf`、coverage、evidence refs 和稳定顺序； - assessment 与最终 fate 的关联； - Next Action / Deadline / Activity / Outcome 的端到端读写； - global/per-objective authority invariant； - migration/schema drift gate； - behavior-preserving parity tests。 ### 暂不作为默认方案 - 新的 Task base table； - `type_category` nullable； - all-seven authority cutover； - unanimous seven-row epoch； - 在 parity 前用 V3 command union 替代 Task V2 actions； - 为未启用 runtime 提前扩散所有 UI/reporting dual mode； - 仅为了“更完整”而新增 table 或 abstraction。 新增最小 Decision Journal storage 前，先验证现有 assessments、receipts、timeline 和 structured logs 是否足够表达。只有现有结构不能可靠查询完整 fate 时，才设计最小 additive migration。 ## 10. KEEP / IMPROVE / DEFER / DROP | 结论 | 内容 | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **KEEP** | Task V2 产品心智和 actions、`tasks` snapshot、open uniqueness、0 / 1 / N、Orchestrator、Guard、store isolation、evidence、timeline、suggestions、assessments | | **IMPROVE NOW** | unified snapshot、authority invariant、decision fate、Next Action end-to-end、schema drift、parity suite | | **DEFER** | full V3 writer、seven-kind authority、Judge Console/Human Control、large UI/reporting dual mode、production cutover | | **DROP / REDO** | #1634 as-is、`type_category nullable`、all-seven cutover、新 Store 默认 `target/target`、把 Full V3 当作预设终点 | ## 11. 分阶段 PR 建议 ### 11.1 2026-07-24：PR 5 开工前复核 原始 PR 5 把 Next Action、Deadline、Activity、Outcome 的 Prompt、writer、timeline、API 和 UI 全部列为待建设范围。这个假设在开工前复核后不成立： - [#1430](https://github.com/retaintive/callytics-infrastructure/pull/1430) 和 [#1480](https://github.com/retaintive/callytics-infrastructure/pull/1480) 已经交付大部分 Task V2 work model、commands、timeline、read projection 和 workbench； - 2026-07-24 对 production 的只读聚合显示：293 条 Task V2 中，123 条 open Task 全部有 `deadline_at`，170 条 closed Task 全部有 `close_result`；293 条都有 canonical `task.created` 事件，170 条 closed Task 都有 canonical status event； - production 已存在 7 条 `task.next_action_changed` 和 19 条 canonical `task.activity_recorded` 事件，证明 schedule、Activity 和 Outcome 不是从零建设； - production 与 test 的 `next_action_text` / `next_action_source` 都仍为 0。当前 “What to do” 主要来自 `task_suggestions`，但 AI suggestion 只是建议，不等于员工已采纳的 Next Action。 因此，不继续执行原始“大而全 PR 5”。当前最小、可观察的产品缺口是：**Task V2+ 还不能可靠记录员工明确采纳的 Next Action 文本及其来源。** 本轮建议拆分为： | PR | 经复核后的范围 | 明确不做 | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | **PR 5A** | 复用已有 `tasks.next_action_*` 字段，为 Task V2+ `change_next_action` 和 “record activity + plan” 增加显式 adopted Next Action；记录旧值/新值、可信 actor/source，并保持事务、幂等和 Guard 语义 | 不新增表或 migration；不改 AI Prompt；不把 suggestion 自动升级成 adopted plan；不从 `due_at` 或历史 suggestion 回填 | | **PR 5B** | Web 提供明确的 adopt/edit 交互，并收紧现有 API/UI contract；是否实施及具体 UI 仍须在 PR 5A 合并后复核 | 不重建已经存在的 Read API/projection；不重做 Deadline、Activity 或 Outcome | 关键语义： - `next_action_at = NULL` 对 Task V2 表示 ready now，不等于缺失或错误； - AI suggestion 与 adopted Next Action 必须分开，只有显式员工动作才能把建议变成当前计划； - 仅调整时间时必须保留已有 Next Action 文本和 provenance； - 没有历史 adopted plan 的旧 Task 保持 unknown，不能用推断数据制造虚假确定性； - `close_result` 和 `create_closed` 继续保留，不强行替换成尚未验证的 V3 Outcome model； - model-emitted Activity 不重新进入本阶段范围。 以下是 2026-07-23 提出的阶段路线，不是预先批准的固定 backlog。每个阶段开工前都必须像 PR 5 一样重新审计；如果功能已经存在、问题没有证据或更小改动足够，应缩小、替换或取消对应 PR。 | PR | 主题 | 范围 | 完成门槛 | | ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **PR 1** | Snapshot contract and Task V2 parity baseline | 锁定 actions、no-op、0 / 1 / N、open uniqueness；定义 `TaskDecisionSnapshot v1` | 只加 contract/tests；无 migration、model change 或 cutover | | **PR 2** | Make Task V2+ consume one snapshot | Contacts Analyzer 改为读取统一 snapshot；保留现有 Prompt schema、actions、Guard、Orchestrator 和 writer | fixtures/replay 与 PR 1 baseline parity；partial/unavailable 安全 no-mutation | | **PR 3** | Close the decision-fate loop | 串联 assessment → authority → Guard → writer → Task id/no-op/reject/zero-row | 每个 decision 都有可查询终态 fate | | **PR 4** | Harden authority and Guard safety | 安全 provision、统一 authority invariant、Guard 看见现有 V2 open rows、可审计 rollback | PostgreSQL tests 覆盖 provision/conflict/rollback/duplicate blocker；不做 all-seven cutover | | **PR 5A（复核后建议）** | Record adopted Next Action in Task V2+ | 复用现有字段，补齐显式员工采用/编辑的 writer、timeline 和 API contract | domain/API tests 证明 suggestion ≠ adopted plan、原子性、幂等、DNC、deadline conflict 和兼容行为 | | **PR 5B（待再次复核）** | Add explicit adopt/edit UX | 在已有 read projection 上增加明确采用/编辑交互 | 真实浏览器验证；不重建 read model；V2 行为不回归 | | **PR 6** | Run Reasoner as no-write Shadow | 同一 snapshot 上生成兼容 V2 contract 的 proposals 和 mismatch reason | Reasoner 无 Task write authority；对比结果可复现、有人审 | | **PR 7** | Conditional gradual cutover | 只有 PR 6 证明更好且 Peter 批准后，按一个 Store / objective 切换 decider | **当前不批准实施**；accuracy/safety/rollback/fate gates 全部通过 | PR 1–4 的实际状态应以 merged PR 和 main branch 为准；表中的文字只保留设计演进与审计背景，不替代代码事实。 ## 12. 每个实施 PR 的共同 Gate 每个 PR 都必须回答： 1. 它解决哪个已经观察到的问题？ 2. 为什么现有机制不能解决？ 3. 最小改动是什么？ 4. 哪些 Task V2 行为必须保持？ 5. 失败时如何 no-mutation、回滚和留 fate？ 6. 用什么 deterministic test 证明工程边界？ 7. 如果涉及模型，用什么同 corpus/human-ratified evidence 证明质量？ 禁止用以下内容替代证据： - source-ready； - tests 很多； - mergeable； - schema 已经 expand； - “比旧系统高”但没有绝对质量门槛； - 新架构在概念上更完整。 ## 13. 仍未 finalized 的内容 以下都是待评估的 proposal，不是默认实施授权： - Task V3 完整 lifecycle 和 seven-kind rollout； - full Reasoner writer； - all-seven authority； - Human Control / Judge Console； - provider custody/outbox 的进一步扩展； - SMS/Call/VoiceMail 的 V3 semantic execution； - complete dual-mode UI/reporting； - Task V3 production cutover。 任何未来文档如果使用 `Accepted`、`canonical`、`final` 或 `supersedes Task V2`，必须同时给出： - 同 corpus 的 Task V2+ vs V3 evidence； - behavior parity； - rollout/rollback plan； - Peter 的明确批准记录。 在 2026-07 的这份审计里，满足这些条件前，当时的 Task V3 proposal 只作为设计输入和可复用组件清单。今天取代该 proposal 的内容见 [Task V3 Product / Domain Contract](/product-design/v3/tasks-feature/task-domain-lifecycle.md) 与 [Task V3 Rollout 状态快照](/product-design/v3/tasks-feature/task-v3-rollout-status.md)。 ## 14. 相关材料 - [系统世界观](/product-design/system-worldview.md) - [Task V2 compatibility entry](/product-design/v2/tasks-feature/index.md) - [Task V3 当前入口](/product-design/v3/tasks-feature/index.md) - [Task V3 Product / Domain Contract](/product-design/v3/tasks-feature/task-domain-lifecycle.md) - [Task V3 Rollout 状态快照](/product-design/v3/tasks-feature/task-v3-rollout-status.md) - [Task V3 高层设计评估](/product-design/v3/tasks-feature/task-v3-design-evaluation.md) - [Task V3 historical implementation audit](/product-design/v3/tasks-feature/task-v3-implementation-audit-remediation.md) - [docs PR #459：audit-first handoff](https://github.com/retaintive/docs/pull/459) - [Lark 完整审计](https://ljprwpnmsg2d.jp.larksuite.com/docx/VIXidzIwBoTFPuxUKbAjRJycp5c) - [FigJam：Task V2 与 Task V2+ 流程](https://www.figma.com/board/RdVd273tkV2vCo0Va5W7yk)