Skip to content

fix(server): stabilize task persistence and refresh workflows#323

Merged
liujuanjuan1984 merged 4 commits intomainfrom
feat/issue-321-task-terminal-consistency
Mar 26, 2026
Merged

fix(server): stabilize task persistence and refresh workflows#323
liujuanjuan1984 merged 4 commits intomainfrom
feat/issue-321-task-terminal-consistency

Conversation

@liujuanjuan1984
Copy link
Copy Markdown
Collaborator

@liujuanjuan1984 liujuanjuan1984 commented Mar 26, 2026

背景

本 PR 在 #321 首版实现基础上继续收敛 durable task persistence boundary,同时完成 #325 关注的本仓内抽象稳定化,并顺带处理 #322 的 GitHub Actions Node 20 弃用问题。

当前收敛目标有三部分:

  • 为 durable task 明确更稳定的 terminal consistency 与 task store failure contract
  • 将 task store 保护层拆分为可替换的 policy / decorator / wrapper,而不是继续停留在单体补丁层
  • 升级 workflow action major 版本,移除 Node24 强制兼容 workaround

模块一:durable task 一致性与错误边界

  • 为已落库 terminal task 保持最小保护:
    • terminal state 不再被 late non-terminal 覆盖
    • terminal task 不再接受 late mutation 覆盖
  • tasks/get / tasks/resubscribe 遇到 task store 读取异常时,统一映射为稳定的 server-side failure。
  • message/send 遇到 task store 持久化异常时,返回稳定 failed task。
  • message/stream 遇到 task store 持久化异常时,返回稳定 failed terminal event。
  • 新增错误类型:TASK_STORE_UNAVAILABLE
  • 当 terminal task 再次收到持久化写入时,统一输出 warning 日志,便于暴露迟到事件或重复写入。

模块二:task store 抽象收敛

  • server.task_store 中引入更清晰的职责拆分:
    • TaskStoreOperationWrappingDecorator 负责统一包装 get/save/delete 操作异常
    • TaskWritePolicy / FirstTerminalStateWinsPolicy 负责 terminal write policy
    • PolicyAwareTaskStore 负责在保存前执行 write policy
  • GuardedTaskStore 改为组合入口,而不是继续承载全部逻辑。
  • 这使当前实现更接近可复用 persistence boundary,也为后续是否上推 a2a-sdk 保留了更清晰的边界。

模块三:GitHub Actions 升级

  • 将以下 workflow 中的旧 major action 统一升级到 Node 24 兼容版本:
    • CI
    • Dependency Health
    • Publish
  • 升级内容:
    • actions/checkout@v6
    • actions/setup-python@v6
    • astral-sh/setup-uv@v7
  • 删除 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 临时环境变量,避免继续依赖 workaround。

模块四:回归测试与验证

  • 保留 terminal consistency 回归测试。
  • 保留 late mutation rejection 回归测试。
  • 保留 backend failure wrapping 回归测试。
  • 新增 write policy decision 回归测试。
  • 新增 late terminal write warning 日志回归测试。
  • 本地验证:
    • ./scripts/doctor.sh
    • 384 passed
    • 覆盖率:91.45%
  • 远端 workflow 已重新触发,GitHub-hosted annotation 消失情况以本次 PR checks 结果为准。

风险与边界

  • terminal protection 仍采用偏保守策略:对于已 terminal task 的 late same-terminal mutation 也直接拒绝。
  • task store 抽象目前仍是本仓稳定封装,未直接上推 a2a-sdk
  • #322 的最终验收依赖 GitHub Actions 新 run 完成后不再出现 Node 20 deprecation annotation;当前配置面已完成升级。

关联

@liujuanjuan1984
Copy link
Copy Markdown
Collaborator Author

本轮复审结论:当前 PR 的实现方向与 #321 收窄后的目标一致,未发现新的阻塞性问题。

审查判断:

  • GuardedTaskStore 把 terminal consistency 和 task store failure contract 收敛到统一边界,整体实现合理;
  • handler 层为 tasks/get / tasks/resubscribe / message/send / message/stream 增加稳定错误出口,和 issue 目标匹配;
  • 回归测试覆盖了 terminal overwrite、late mutation、backend failure wrapping 与 handler failure path,测试面足够支撑首版收敛;
  • 当前残余风险主要是:terminal protection 采用偏保守策略,late same-terminal mutation 也会被拒绝。短期这是可接受的防护,但若未来需要 terminal 后补充合法元数据,可能需要进一步细化规则。

issue 关系复核:

  • Closes #321 准确;
  • Related #307Related #308 准确,不需要改成 closes,因为本 PR 不是在重复实现它们,而是在其基础上补稳定性边界。

@liujuanjuan1984 liujuanjuan1984 changed the title fix(server): harden durable task persistence boundaries fix(server): stabilize durable task persistence boundaries Mar 26, 2026
@liujuanjuan1984
Copy link
Copy Markdown
Collaborator Author

本轮已基于当前分支继续收敛 #325,复审结论如下:

  • 未发现新的阻塞性问题。
  • 当前实现比首版 GuardedTaskStore 更合理:terminal write policy、operation error wrapping、store decorator 的职责边界已经拆开。
  • 这使 server.task_store 从“本仓临时保护层”更接近“稳定 persistence boundary abstraction”,也更符合 #325 的目标。

当前残余风险只有一项:

  • terminal policy 仍偏保守,late same-terminal mutation 会被整体拒绝;如果未来需要在终态后补充受控 metadata,仍需单独细化 policy。

本地验证:

  • ./scripts/doctor.sh
  • 383 passed
  • coverage 91.22%

@liujuanjuan1984
Copy link
Copy Markdown
Collaborator Author

补充一处可观测性收敛:

  • 当 task 已经落入 terminal state 后,又收到新的持久化写入尝试时,现在会统一输出 warning 日志。
  • 这包括两类情况:
    • 重复的 terminal 写入被接受
    • terminal 后的 late mutation 被 policy 拒绝

本次不改变既有 policy,只增加显式暴露,便于排查迟到事件、重复写入或异常上游行为。

验证:

  • uv run pytest --no-cov tests/server/test_task_store_factory.py
  • ./scripts/doctor.sh
  • 384 passed

@liujuanjuan1984 liujuanjuan1984 changed the title fix(server): stabilize durable task persistence boundaries fix(server): stabilize task persistence and refresh workflows Mar 26, 2026
@liujuanjuan1984 liujuanjuan1984 merged commit 39fa676 into main Mar 26, 2026
3 checks passed
@liujuanjuan1984 liujuanjuan1984 deleted the feat/issue-321-task-terminal-consistency branch March 26, 2026 06:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant