详细设计 2/3:TAPD、本地 Story、Session 三套生命周期

三套状态互相关联,但绝不共用一个 status。同步器读取事实,决策器给出动作,处理器才执行副作用。

TAPD Story(外部业务状态)

状态由项目工作流配置决定

例如:规划中 → 实现中 → 已实现

也可能是自定义或并行工作流

权威来源:TAPD

本地 Story(AI 执行状态)

接纳态:candidate | ready

执行态:idle | active | paused | blocked

终态:completed | aborted

权威来源:本地 DB + graph

AI Session(运行事实)

missing | starting | live

exited | unknown

session 存在不代表 Story active

权威来源:PTY/session resolver

主流程

TAPD 同步 本地 candidate→ 用户启动 ready / idle→ 上下文检查 active + session→ 阶段完成 completed→ 生成建议 确认后回写 TAPD

状态 × 用户动作 → 行为

事实状态动作决策与副作用
TAPD 新项,无本地 Storysync创建 candidate;不启动线程,不创建 session
candidatestart校验至少一个可用项目;转 ready 后显式启动
candidate 且项目路径无效start拒绝执行;页面反馈并写诊断事件
idle/paused/blockedopen session生成最新 context snapshot,再启动或恢复 session
active + live sessionopen session只 attach,不重复注入或重复启动
completedsync suggestion读取 TAPD 合法流转,生成建议,不直接回写
回写建议待确认confirm调用 TAPD 更新;成功后记录外部状态与审计事件
任意非终态refresh context单 Story 扫描项目并更新有证据事实,不启动 AI

外部变更如何进入本地

P0 使用显式 story sync / Web 同步;只更新 TAPD 镜像字段,不覆盖本地执行状态和用户确认资料。

P1 可接 TAPD Webhook 做增量同步,但事件只进入同步队列,仍不得自动启动 Story。

冲突规则

TAPD 标题、负责人、截止日期:TAPD 为权威。

本地项目、分支、文档、DDL/Nacos:本地资料模型为权威,TAPD 同步不覆盖。

TAPD 已关闭但本地仍 active:显示 drift 警告,由用户决定终止、完成或继续,不自动杀 session。